Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 59dc22637d release: 0.1.0-beta.35 - its changelog file (accessibility: the statement, a screen reader's names and announcements, headings and charts, contrast themes, focus), HANDOFF's beta.35 section (D88-D92), owner-only item 32, the release lines (beta.35 PR-7)
docs/changelog/0.1.0-beta.35.md takes [Unreleased] as it stood (#366-#371) under a
summary and the update paragraph: the legal texts keep their versions, schema 22
and rules 2026.11.2 unchanged. HANDOFF's beta.34 START HERE (with its alpha.3
lines) moves verbatim to docs/handoff/history/0.1.0-beta.34.md with its row; the
new START HERE carries D88-D92, the choices, what was measured and the traps (a
ContentDialog test needs the dispatcher's context, a static event hears every
test's, WPF UI's throwing brushes fall back to the Fluent fills inside the App, a
resource reference's callback runs on an equal value, a forward StaticResource
fails only when used, Python's "\b", RenderTargetBitmap's offset); owner-only item
32 is beta.35 on real hardware; D88-D92's rows, and D82's and D87's rows now point
at the history files they moved to. README, ACCURACY, the Disclaimer's accuracy
block and LIMITATIONS name 0.1.0-beta.35; ACCESSIBILITY.md's checks paragraph
rewrapped.

No alpha with this release (D92): alpha.4 moves the alpha line to .NET 11's
release as a task of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 13:15:56 +07:00
poli0981andClaude Opus 5.5 731f6d3082 feat: focus and motion - Ctrl+1 to 5 put the keyboard in the page they open and say its title, a message box is owned by the window it opens over, and pages slide in only while Windows animates (beta.35 PR-6) (#371)
* feat: focus and motion - Ctrl+1 to 5 put the keyboard in the page they open and say its title, a message box is owned by the window it opens over, and pages slide in only while Windows animates (beta.35 PR-6)

PageFocus: after a page shortcut the page shown takes the focus once laid out (its first
control) and its first-level heading is announced; the shell tells it each page shown
from NavigationView.Navigated. PageMotion: the NavigationView's Transition is None while
SystemParameters.ClientAreaAnimation is off, followed as it changes (WPF UI 4.3.0 played
FadeInWithSlide whatever it was). MessageBoxes: WPF UI's MessageBox sets no owner
(measured: null before and after it is shown), so every box is owned by the App's
active window - six call sites, and a scan holds it.

Measured, and left alone: a ContentDialog already gives the focus back to its opener
(WPF UI's ContentDialogHostController stores and restores it); a test pins it. A first
measurement said otherwise because it ran with no dispatcher context, where the
dialog's own finally never resumed.

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

* test(native): the tiny ring's case retries until one attempt both overlapped the writer and was lapped by it - CI's single attempt kept up with all 200000 records (beta.35 PR-6)

ci.yml's check on #371 failed in fl_ring, "a tiny ring, so the writer laps the
reader constantly": attempts 1, most overlapped drains 167058, dropped 0. The loop
repeated an attempt only when it had not overlapped the writer (#308); an attempt
that overlapped and was never lapped ended it, and CHECK(dropped > 0) failed. Both
now hold in the same attempt, the last, repeated up to kMaxAttempts (8): a reader
that never counts a drop still fails every attempt. 40 local runs of the case and
the native suite (32/32) pass; nothing outside the test changes.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 06:11:02 +00:00
poli0981andClaude Opus 5.5 cea7d87ff8 feat: Windows contrast themes followed - every colour the theme's own, the accent its highlight, the charts in its colours; and the title bar, the snackbars and a Danger button read (D91) (beta.35 PR-5) (#370)
* feat: Windows contrast themes followed - every colour the theme's own, by role from WPF UI's four contrast files, the accent its highlight and the highlight's text, the charts in its colours, the Remove button its own button, on and off at once (D91) (beta.35 PR-5)

While SystemParameters.HighContrast is on, the light or the dark Fluent theme (as the
contrast theme is) lies under Services/ContrastOverlay: every key of WPF UI 4.3.0's HC1,
HC2, HCBlack and HCWhite in the user's own SystemColors colour for its role
(Services/ContrastRoles: the colour a key has in all four, opaque colours only; ties and
placeholders by name), the transparent keys transparent, the 21 accent keys as the
highlight and the text on the accent as the highlight's text. No Mica, no
SystemThemeWatcher (it would apply WPF UI's files: 84 of 97 colours a red placeholder,
17 brushes that throw). A switch, an edit or turning it off is followed at once.

What the App draws itself reads ContrastTheme.Active: ChartPalette.ForContrast,
ChartTheme.TextOn, the artwork band, the Import list, the update footer. The Remove
button takes the DangerButton style (WPF UI's Danger is a fixed #F44336). Settings >
Theme says a contrast theme is in use.

Red first: the sweep under four default and two edited themes found the chips at
1.26-1.78:1, the Remove button at 3.06-4.42:1, the badges' black, and the pressed
menu item white on white.

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

* fix: what no sweep rendered reads - the agent's pill on the theme's own fills, every snackbar in the theme's colours, a Danger button's dark text on its red and the theme's own button under a contrast theme (beta.35 PR-5)

Measured 2026-11-09 against WPF UI 4.3.0's styles, outside any surface the sweeps render:
the title bar's agent pill was a ui:Badge with a bound palette appearance (light theme
2.78, 2.63, 2.16 and 3.68:1), the Success and Caution snackbars white on fixed green and
orange (2.78 and 2.16:1 in both themes), and a Danger button white on #F44336 in the dark
theme (3.68:1), out of any contrast theme's reach.

AgentPill (a Pill on the theme's success, caution and critical fills), the strip's
messages all Secondary, and an implicit ui:Button style: a Danger button's text is
TextFillColorDarkPrimaryBrush (5.3 and 5.7:1), and the theme's own button while a
contrast theme is on, message boxes included. The DangerButton style of the first
commit is gone; a bound badge appearance and the other five button appearances are
refused.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 05:46:12 +00:00
poli0981andClaude Opus 5.5 54a2c08601 feat: headings and charts a screen reader can use - page and section headings, every chart named with where its numbers are, its keys kept, a double-click that shows all of it, no series told apart by colour alone (D90) (beta.35 PR-4) (#369)
Every Title is AutomationProperties.HeadingLevel Level1 and every section Subtitle Level2; a Subtitle that shows
a value says None. AccessibilityTests holds every Title and Subtitle to a declared level, PagesLoadTests every
page to one first-level heading.

Every plot is Charts/ChartPlot, ScottPlot's WpfPlot with a peer: an Image of the localized type "chart", named
and with help text saying where its numbers are and which keys move it, focus drawn with WPF UI's focus style.
Charts/ChartKeys keeps the arrows and A with the chart after ScottPlot has acted (the page used to scroll or move
the focus on); a double-click shows all of the chart, as the guide said, instead of ScottPlot's benchmark overlay.
Charts/ChartPatterns gives every series a line pattern, marker or hatch by its index - Compare's five sessions,
the GPU temperature and hot spot, the two stutters, the two lows, the two limits - and
NoChartTellsTwoSeriesApartByColourAlone reads every chart's legend for two entries that differ by colour only.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 04:52:30 +00:00
poli0981andClaude Opus 5.5 926580c0f2 feat: a screen reader is told what appears - safety notices, the agent's and the update's banners, every short message, a game page's notice and each maintenance result, through UI Automation's notification (D89) (beta.35 PR-3) (#368)
Services/IAnnouncer over Services/UiaAnnouncer, the one place the App raises UI Automation's notification event:
only on its active window (a game that has the screen is never interrupted) and only when a screen reader listens.
An Alert (every one read): a safety notice as it arrives, a warning in the strip, the agent going offline, a game
page's refusal. A Status (a newer one replacing one not yet read): the strip's info and success, the agent back, an
update's step, a page's success, every Database maintenance result.

Every transient message goes through IMessageStrip now - MainWindowViewModel's six direct ISnackbarService calls
moved to it - and SnackbarStrip says what it shows. Services/ShellAnnouncements says only a change: the first state
is read with the window, a download's percent ticks are one step, a rebuilt window says nothing. The maintenance
line's LiveSetting, which announced nothing, is gone; no XAML may set one.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 04:36:48 +00:00
poli0981andClaude Opus 5.5 0b485d1293 feat: what a screen reader is given - every item, cell and row button named by what it shows, the display-only controls with a voice, the notices' text reachable, no silent Tab stop (D88) (beta.35 PR-2) (#367)
PagesLoadTests.Automation sweeps the UI Automation tree WPF builds for every page, window, dialog and control,
every tab shown: no Tab stop without a peer, no item named by its type, every focusable control named, no shown
text hidden in a template, no two buttons in a list sharing a name. All five went red on main first.

Fixes: every list item type speaks through ToString (Services/SpokenText) - Choice its label, a notice its title
and text, a document page its title, a session row its date, length and tier; FpsReadout, TriStateChip and
ChangeBadge get SpokenTextAutomationPeer (a Text element, no children) and leave the tab order, and the readout
says rule 6 aloud (Native, displayed and the factor together); a template column names its cells through
Controls/CellName over WPF UI's DefaultDataGridCellStyle, an empty cell read as "empty"; a row's button names its
row; the App's InfoBar template draws title and message through ContentPresenters; implicit styles take
ItemsControl, ui:Image and ui:CardControl out of the tab order; a CardExpander's expand button is named after its
header (Controls/ExpanderToggleName); the dialog hosts are no Tab stops. ScreenReaderNamesTests holds each piece.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 04:16:02 +00:00
poli0981andClaude Opus 5.5 fad7b84075 feat: the accessibility statement - ACCESSIBILITY.md under Help > Accessibility and on the wiki, the Accessibility problem form and its label, the documents corrected (D88) (beta.35 PR-1) (#366)
ACCESSIBILITY.md states WCAG 2.2 AA through WCAG2ICT as a goal and never a claim, what works with the keyboard
alone, a screen reader, a contrast theme or Magnifier, how it is checked (the owner's pass of 2026-11-09 on
beta.34 and alpha.3), the known limits with what to do instead, and how a barrier is reported and handled - by
severity, no promised times. Embedded and shown under Help > Accessibility and after Limitations in the guide's
window; a wiki page of its own.

The Accessibility problem issue form, a user-interface section in the PR template, and the labels accessibility,
safety and priority-high - the last two named by the Safety gap form since 2026-08-02 and never existing.

Documents corrected: charts take focus and ScottPlot's keys (ChartKeyboardTests measures it; 08_UI said
neither); the database-maintenance live region announces nothing; the Narrator gap is the owner's pass now;
20_OPEN_QUESTIONS G's accessibility row closed; NFR-9 widened (D88-D91); LIMITATIONS gains an Accessibility
section and loses its one struck sentence, which a screen reader reads as current.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 03:51:44 +00:00
dependabot[bot] 4cc4c3e9c2 Bump the minor-and-patch group with 1 update (#365)
Bumps Meziantou.Analyzer from 3.0.317 to 3.0.319

---
updated-dependencies:
- dependency-name: Meziantou.Analyzer
  dependency-version: 3.0.319
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-11-09 07:03:16 +07:00
poli0981andClaude Opus 5.5 27f537a2d7 docs: 0.1.0-alpha.3's notes - its changelog file opening with the experimental-build warning, its row, HANDOFF's alpha.3 lines, owner-only item 31 (D87) (alpha.3 PR-1) (#363)
The third alpha is the source of 0.1.0-beta.34 on .NET 11 RC3 (D87: right after
beta.34, on RC3 because the train reached it before .NET 11's release on
2026-11-10). Its notes are on main as every release's are; the alpha branch takes
them with the sync that follows this pull request (13_CI_CD §The alpha line).

- docs/changelog/0.1.0-alpha.3.md: the experimental-build warning, the update
  from alpha.2 (the ledger copy, the Disclaimer 2.13 and the Privacy Policy 2.14
  once, the Alpha notice's box again, schema 22 - which an alpha.2 cannot open),
  installing over a beta and going back, and what differs from the beta - the
  same as alpha.1 from beta.32.
- CHANGELOG.md: its row in the Releases table.
- docs/HANDOFF.md: START HERE's "0.1.0-alpha.3" lines (the sync by a merge
  commit, the switch unchanged, the first alpha whose ledger moves) and
  owner-only item 31, the third alpha on real hardware.

No release line moves (README, ACCURACY, the Disclaimer's copy and LIMITATIONS
keep naming the newest beta).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 09:51:02 +00:00
poli0981andClaude Opus 5.5 44c031faca release: 0.1.0-beta.34 - its changelog file (DLSS 5 and DLSS 4.5 from evidence, filters, Games at once), HANDOFF's beta.34 section (D83-D87), owner-only item 30, the release lines (beta.34 PR-7) (#362)
docs/changelog/0.1.0-beta.34.md takes [Unreleased] as it stood (#356-#361)
under a summary and the update paragraph: the Disclaimer 2.13 and the
Privacy Policy 2.14 once, schema 22 (a beta.33 cannot open it), rules
2026.11.2. HANDOFF's beta.33 START HERE (with its alpha.2 lines) moves
verbatim to docs/handoff/history/0.1.0-beta.33.md with its row; the new START
HERE carries D83-D87, the choices, what was measured and the traps
(notice-check reads the index, the native token test's exact mask, WPF UI's
navigation cache and pane template, Microsoft.Data.Sqlite's synchronous
async); owner-only item 30 is beta.34 on real hardware; D87's row. README,
ACCURACY, the Disclaimer's accuracy block and LIMITATIONS name
0.1.0-beta.34.

One wording fix found while writing the notes, before the release: D83's
evidence is DLSS Frame Generation IDENTIFIED in the session (fg_mode =
dlssg), as DlssText reads it - its factor need not have been counted - and
five places written in #357 said "counted" (05_DETECTION twice, spike-notes
§26, the changelog entry, HANDOFF's D83 row), with DlssText's and the test's
comments. DlssTextTests now pins it: Dynamic applied with DLSS Frame
Generation identified and the count refused (non_uniform) reads DLSS 4.5.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 09:34:30 +00:00
poli0981andClaude Opus 5.5 f66d98eb78 docs: the tested-games list from a copy of the ledger of 2026-11-06 (D35) - fifteen more games measured, the first Xbox titles; the docs sweep across the train (beta.34 PR-6) (#361)
Owner request 2026-11-06, item 5: review, update and sync the documents and the
tested-games list, from the database.

- docs/LIST_GAME_TESTED.md: refreshed from a copy of the owner's ledger taken
  2026-11-06 (read-only; 131 sessions of 27 games, the same as the live ledger
  when the commit was made), as drafted in the plan the owner approved: fifteen
  more Tier-1 rows (Phantom Blade Zero under Dynamic, Hogwarts Legacy loading
  DLSS 5's runtime, Valor Mortis and inKONBINI from the Xbox app, ...), seven
  rows updated, the Tier-2 sessions and the guard's refusals since 2026-09-27,
  the driver range and the engine versions read since.
- docs/08_UI.md: the DLSS line's two new rows (D83, D84); Compare over every
  session.
- docs/HANDOFF.md: item 28's tested-list step done.
- docs/open-questions/closed-s.md: S30 notes the fifth Streamline id decoded,
  from the vendor's header rather than by guess (row O4's warning).
- guide/08-settings.md: a language change stays on Settings.
- CHANGELOG.md: the entry.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 09:17:49 +00:00
poli0981andClaude Opus 5.5 efaf585928 feat: filters on Games and Compare; the Compare page's layout; the selected pane item keeps its label (D85, D86) (beta.34 PR-5) (#360)
Owner request 2026-11-06, items 3 and 4, with a screenshot of Compare.

- Games (D85): Store, Engine, State, Installed and Played beside the search
  and sort, with Clear filters; the title counts what is shown of all while a
  filter or the search narrows it. Kept while the App runs, not saved.
- Compare (D85): every session (it was the newest 200, one game lookup each;
  now one read of the names, off the UI thread), filtered by game, tier and
  frame generation, with a count; a ticked session stays listed.
- Compare layout: the selection bar on the left above the list with Clear
  selection; columns sized to what they hold and one filler column; the date
  sorts by when; the settings-changed cell says so or shows a dash; the
  result table's labels sit over their columns (MetricHeader bound).
- The pane (D86): our copy of WPF UI 4.3.0's LeftFluent item template
  without the IsActive collapse, so the selected page keeps its label.
- Strings en/vi/ja (ja review); 08_UI, guide/07-screens, CHANGELOG, HANDOFF.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 09:05:13 +00:00
poli0981andClaude Opus 5.5 a78d7bd359 feat: Games opens at once from any page - the window keeps the library page, cards before the executable checks; a language change keeps the page on screen (beta.34 PR-4) (#359)
The owner, 2026-11-06: switching to Games stalls 0.5-1.5 s; and changing the language in Settings
brings back the last game page instead of Settings.

- Measured first (spike-notes 27, a scratch test, not committed; 65 games, the first executable
  check held 800 ms for a USB drive waking): first cards 822-830 ms -> 10-15 ms; a revisit
  181-215 ms -> 15-16 ms; the first build unchanged (the non-virtualizing grid, by decision).
- WindowPageCache: the window's own page provider keeps the GamesPage it built (set after
  SetNavigationControl, which hands the NavigationView the container's provider; WPF UI's
  NavigationCacheMode is never read when a page provider is set). One per window, so a language
  change's new window builds its own.
- GamesViewModel: the library read on the thread pool; the cards listed before the executable
  checks, each getting its Not installed pill when its check answers; a read keeps every card that
  would look the same (GameCardViewModel.LooksLike, Sync - never Clear); the page reads the library
  again each time it is shown (Attach). The list view is bounded (MaxHeight 640).
- ShellHost notes every page the live window shows (pane clicks included), so a rebuild opens on
  the page on screen - Settings after a change made there.
- Tests: GamesViewModelTests (cards before the checks, a page shown again, Sync), WindowPageCacheTests
  (kept per window; the shell remembers the page on screen).
- Docs: 16_WPFUI_SYNTAX, wiki App-UI-development, 08_UI, 09_I18N, spike-notes 27, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 08:49:55 +00:00
poli0981andClaude Opus 5.5 c9b0aab862 feat: DLSS 5 is named where the game ran its neural rendering (schema 0022, rules 2026.11.2, Privacy 2.14); Streamline headers re-vendored at v2.14.16 (D84) (beta.34 PR-3) (#358)
The owner, 2026-11-06: Hogwarts Legacy with Neural Rendering on loaded DLSS 5's runtime
(nvngx_dlssnr.dll 310.9.16.0, from the game's folder) and the session could say only "DLSS 5
runtime loaded". Then: check what changed in recent Streamline versions, fix it if needed.

- Streamline: the vendored closure was v2.12.0 byte for byte; v2.14.16 changes three of its
  eleven files (kFeatureDLSS_NR = 1004, the uplift buffer types 70-72, kStructVersion7, the
  version). Re-vendored byte for byte; README provenance, THIRD_PARTY_NOTICES row.
- Overlay (hook path): the slEvaluateFeature detour decodes kFeatureDLSS_NR into its own bit;
  RecordPresent sets FL_FEAT_SL_NEURAL_RENDERING (feature byte bit 7, an enumerator - no layout
  change) under the condition every Streamline fact shares; the evaluate row's family also claims
  FL_HOOK_SL_NEURAL_RENDERING (bit 12), published with the detour. Overhead: decode unchanged
  within noise (4.7 ns a call), +0.14..0.19 ns a present.
- Agent: Domain.Metrics.NeuralRendering.SharePct; sessions.dlss_nr_pct (schema 0022) only from a
  writer that published the family - an older Overlay's silence is never a measured 0 %.
  CensusNames records sl.dlss_nr.dll.
- Rules 2026.11.2: capability dlss_nr -> "Supports DLSS 5 Neural Rendering".
- App (D84): DLSS 5 heads the DLSS line where it ran ("DLSS 5 (neural rendering on 97.3% of
  rendered frames)"); its library listed with version and source; measured 0 -> "runtime loaded,
  not seen running"; nothing to tell -> "runtime loaded" as before. CSV basis/pct.
- CaptureHost dev census: a kFeatureDLSS_NR bucket.
- Privacy Policy 2.14 (neural-rendering libraries); the accuracy block's DLSS 5 sentence.
- Tests: native guard_test (the new harness mode through an injected Overlay; 0xF00D lights no NR
  fact; the token case's exact mask gains the family), NeuralRenderingTests, SessionAggregatorTests,
  DlssGenerationTests, DlssTextTests (a row shaped from session 132), LedgerDatabaseTests (0022),
  the repository round trip, the rules fixture, RuntimeModuleSourcesTests, SlCensusTests.
- Docs: 05_DETECTION, 06_DATA_MODEL, 17_HOOK_ENGINE, LIMITATIONS, guide/03, guide/10, the accuracy
  block, spike-notes 26 (+ owner-only item 30(a)'s decision table), HANDOFF (D84), CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 08:39:42 +00:00
poli0981andClaude Opus 5.5 569bacac95 feat: a session under the NVIDIA App's Dynamic frame generation reads DLSS 4.5; Disclaimer 2.13 (D83) (beta.34 PR-2) (#357)
The owner, 2026-11-06: Phantom Blade Zero under the NVIDIA App's Dynamic multi frame generation,
up to x3, read "DLSS 4" - but Dynamic (and x6) exist only in DLSS 4.5. The DLSS line named a
generation from the measured multiplier alone, and "up to x3" never passes x3.0.

- Domain: DlssEvidence.DynamicFrameGeneration, DlssBasis.DynamicFrameGeneration; the rule's new
  row sits below a measured x5 and above every DLSS 4 row.
- App: DlssText reads Dynamic as DLSS Frame Generation counted AND the game's driver profile
  setting NGX_DLSSG_MODE to 4 (NvidiaDriverSettings.DlssgModeDynamic, NVIDIA's own name) AND the
  driver's FG word reporting the mode override applied (FG_MODE). The driver's own mode number
  (3 Dynamic / 1 Fixed on all sixteen stored sessions) is recorded, not keyed on. Label "DLSS 4.5
  (Dynamic multi frame generation, set in the NVIDIA App)", CSV basis=dynamic_frame_generation.
  A Fixed multiplier names nothing by itself (Witcher 3 under Fixed x6 still presented x2.0).
- Dlss_Basis_Dynamic in en/vi/ja (ja review).
- Docs: 05_DETECTION (row + amendment), 03_METRICS (the ceiling decode confirmed), LIMITATIONS,
  guide/03, guide/10, the accuracy block re-dated 2026-11-06 + Disclaimer 2.13, spike-notes 26
  (new), HANDOFF decisions index (D83), CHANGELOG.
- Tests: DlssGenerationTests, DlssTextTests (a row shaped from the owner's session 129 and four
  negatives).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 08:15:42 +00:00
poli0981andClaude Opus 5.5 f7bfe1e8f1 fix: an Xbox game's picture name that names a file's stream is passed over, not thrown on; the guard's note on GuardedInjectImpl sits above it again (beta.34 PR-1) (#356)
Two things a self-review of #351 and #352 found after their gates were green.

- XboxArtCache.Image: a ShellVisuals name in MicrosoftGame.config that points at a
  stream of a file, named like a drive ("Resources\a:b.png"), made the scale
  search's pattern "a:b.scale-*.png", and EnumerateFiles throws ArgumentException
  on a rooted pattern ("Second path fragment must not be a drive or UNC name") -
  which XboxArtCache.Find does not catch. GameArt.ForAsync's task then faulted:
  the game page showed no picture and logged an unobserved task, and a command
  that awaits the page's reload would reach the dispatcher's crash report. A name
  whose leaf holds ':' is now no picture, like a name outside the package. Red
  without the fix (the exact ArgumentException), green with it; no install of
  the owner's eleven titles has such a name (spike-notes §25).
- fl_guard.cpp: #352 put BlockingMitigation and TargetIsolationVerdict between
  GuardedInjectImpl and the comment that describes it ("A refusal returns here
  ... runs only for a target the full evaluation allowed"), so it read as the
  first line of BlockingMitigation's. It moves back above GuardedInjectImpl and
  names the target's isolation among what runs after the evaluation. No code
  change there.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 08:09:29 +00:00
poli0981andClaude Opus 5.5 405449283b docs: 0.1.0-alpha.2's notes - its changelog file opening with the experimental-build warning, its row, HANDOFF's alpha.2 lines, owner-only item 29 (D82) (alpha.2 PR-2) (#354)
The second alpha is the source of 0.1.0-beta.33 on .NET 11 RC3 (D82: right after
beta.33, on RC3 because the train reached it before .NET 11's release on
2026-11-10). Its notes are on main as every release's are; the alpha branch takes
them with the sync that follows this pull request (13_CI_CD §The alpha line).

- docs/changelog/0.1.0-alpha.2.md: the experimental-build warning, the update
  from alpha.1 (the ledger copy, the Privacy Policy 2.13 once, the Alpha notice's
  box again), installing over a beta and going back, and what differs from the
  beta - the same as alpha.1 from beta.32.
- CHANGELOG.md: its row in the Releases table.
- docs/HANDOFF.md: START HERE's "0.1.0-alpha.2" lines (the sync by a merge commit,
  the switch unchanged, the first delta an alpha's release has to find - #350's
  lookup) and owner-only item 29, the second alpha on real hardware.

No release line moves (README, ACCURACY, the Disclaimer's copy and LIMITATIONS
keep naming the newest beta).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 07:37:51 +00:00
poli0981andClaude Opus 5.5 249c02be56 release: 0.1.0-beta.33 - its changelog file (games from the Xbox app and the Microsoft Store), HANDOFF's beta.33 section (D77-D82), owner-only item 28, the release lines (beta.33 PR-3) (#353)
docs/changelog/0.1.0-beta.33.md takes [Unreleased] as it stood (#351, #352)
under a summary and the update paragraph: Privacy Policy 2.13 once, schema
21, rules 2026.11.1. HANDOFF's beta.32 START HERE moves verbatim to
docs/handoff/history/0.1.0-beta.32.md with its row; the new START HERE
carries D77-D82, the choices, what was measured and the traps (the
Malwarebytes quarantine of fl_guard_test.exe, the ARM64 clang-format,
SonarCloud read after a merge); owner-only item 28 is the Xbox titles on
real hardware. README, ACCURACY, the Disclaimer's accuracy block and
LIMITATIONS name 0.1.0-beta.33.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 07:23:45 +00:00
poli0981andClaude Opus 5.5 042fdd631c feat: Xbox games start through Windows and are recorded once they appear; the guard refuses an app container and a game under code protection by their own reasons; one exe-path reader for the capture path (D78, D80) (beta.33 PR-2) (#352)
* feat: Xbox games start through Windows and are recorded once they appear; the guard refuses an app container and a game under code protection by their own reasons; one exe-path reader for the capture path (D78, D80) (beta.33 PR-2)

Play on a game the Xbox app or the Microsoft Store installed runs
`explorer.exe shell:AppsFolder\<AUMID>` in either Play mode and from an
elevated App: the user's shell activates the package as its Start-menu
tile does. Started by its path a GDK game is never the game in its
package (spike-notes §25), so the agent answers LaunchGame for an
executable whose install root is a GDK package root with `PackagedGame`
and starts nothing; the watcher records the game when it appears.

The guard asks one last question before the primitive, from the target's
own token and mitigation policies: kTargetAppContainer (a UWP app, D78)
and kTargetMitigation (signed-only images, no dynamic code, a strict or
non-CET-blocking user shadow stack, strict CFG). Neither is a finding;
both are Tier 2 with the reason. Each ended before as a failed
injection, a hook that installed nothing, or a risk of ending the game.
"Could not tell" refuses as kProcessUnreadable. Catch2 holds each
refusal through the seam, and two against Windows itself (a child
started under ProhibitDynamicCode + MicrosoftSignedOnly).

TargetResolver re-finds a game by the kernel's image name, as the
watcher keys it (ProcessImagePath), instead of the loader's
(MainModule), still opening candidates with the guard's rights so a
process an anti-cheat driver closes stays TargetUnreadable (D21).

Also: SonarCloud's two findings on PR-1 - the wcslen in
IsGdkPackageRoot (cpp:S5813) and new-code coverage under 80 %.

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

* test: a PC with no games folder names none - the hosted runner has no .GamingRoot, and FluentAssertions' OnlyContain fails an empty list (beta.33 PR-2)

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 06:14:56 +00:00
poli0981andClaude Opus 5.5 6ba6a41cea feat: games from the Xbox app and the Microsoft Store - the GDK library, a package root as an install-root boundary, the xbox platform rule, the game's own art; Privacy 2.13 (D77-D81) (beta.33 PR-1) (#351)
* docs(spike-notes): §25 - the Xbox/GDK titles' layout, read-only, and the launch probe's decision table, written before the run (D77) (beta.33 PR-1)

The owner's 11 GDK packages under C:\XboxGames and D:\xbox, read without launching anything: the .GamingRoot files,
MicrosoftGame.config / appxmanifest.xml, the WindowsApps junction chain, and the executables refusing FILE_READ_DATA
and FILE_EXECUTE to every process outside their package. Then the probe's method and the table that decides what each
outcome changes - committed before the probe runs, as the house rule asks.

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

* docs(spike-notes): §25's run - six GDK titles activated through their packages; the image paths, the chains, the tokens, the mitigations, and what a start by path really does (D77, D80) (beta.33 PR-1)

The image path and the loader's main-module path are both the Content spelling on every process of every chain; no
chain member the guard's rights cannot open; no fuzzy-fragment module; full trust, not an AppContainer, medium
integrity; none of the four mitigations. And CreateProcess by path is not error 5, as assumed: the package's launch
executable is replaced by an unpackaged gamelaunchhelper.exe that activates the package (the game is never the
caller's process nor its descendant), and an Unreal shipping executable runs outside its package. D80 stands on those
two measured grounds; the read-only claim is struck and dated in place.

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

* feat: games from the Xbox app and the Microsoft Store - the GDK library, a package root as an install-root boundary for the guard and detection, the xbox platform rule (root_file, rules 2026.11.1), the game's own art; Privacy 2.13 (D77-D81) (beta.33 PR-1)

The import gains a fifth store, `xbox`: each ready drive's .GamingRoot names the games folders, each
<Game>\Content\ holding MicrosoftGame.config beside appxmanifest.xml is a GDK package (read with DTDs prohibited),
and Windows' appmodel calls (PackageFamilyNameFromId, GetPackagesByPackageFamily) say whether it is installed for
this user. The record: the family name as the store id, Content as the install folder (the spelling the game's own
process reports, spike-notes section 25), the AUMID as the launch key; ExecutableLocator picks the process that
draws, never gamelaunchhelper.exe.

Safety: no install-root boundary matched the Xbox layout, so check 4 walked only an Unreal title's
Binaries\WinGDK. A GDK package root is now a boundary for InstallRoot and the native ResolveInstallRoot alike, asked
only where no store boundary matched (it can only widen the walk); GamesInstalled joins the native list; one case
list, tests/fixtures/install-roots/cases.txt, is read by Catch2 and xUnit both.

Detection: an `xbox` platform first in the array (a GDK FINAL FANTASY ships steam_api64.dll), decided by a new
root_file signal from the install root's own listing, so a deep walk that ran short cannot make it Unknown. Art: the
square logo and the splash image the package names, from inside the package root only. games.platform's vocabulary
gains xbox; the importer's fake repository now validates as the real one does. Privacy Policy 2.13 with the wording
approved with the plan; TRADEMARKS, 02_SPEC, 15_ROADMAP, 05/06/08/19/20, README, LIMITATIONS and the guide follow.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 05:10:52 +00:00
poli0981andClaude Opus 5.5 7b3dec2b96 fix(release): find the delta by the name the pack listed - Velopack puts a non-default channel in its package names, which would have failed the second alpha (D73) (alpha.2 PR-1) (#350)
The 0.1.0-alpha.1 rehearsal (run 41220645263) packed FrameLedger.App-0.1.0-alpha.1-alpha-full.nupkg:
on a non-default channel Velopack names the packages with it. release.yml built the delta's name
for the default channel (FrameLedger.App-<v>-delta.nupkg), so the first alpha with a previous
alpha to diff against would have thrown "vpk produced no delta". The check now takes the one
*-delta.nupkg that assets.<channel>.json lists; a beta's names and checks are what they were.

13_CI_CD §release.yml (the alpha line) names the packages; CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 17:09:28 +00:00
poli0981andClaude Opus 5.5 11eaf14517 docs: 0.1.0-alpha.1's notes - its changelog file opening with the experimental-build warning, its row, HANDOFF's alpha.1 lines, owner-only item 27 (D73-D76) (alpha.1 PR-2) (#348)
* docs: 0.1.0-alpha.1's notes - its changelog file opening with the experimental-build warning, its row, HANDOFF's alpha.1 lines, owner-only item 27 (D73-D76) (alpha.1 PR-2)

The first alpha's notes, on main as every release's are; the alpha branch takes them with its
sync, and release.yml reads them for the tag v0.1.0-alpha.1 on alpha.

- docs/changelog/0.1.0-alpha.1.md: the warning first (an alpha of beta.32 on .NET 11 RC3, own
  risk, the Alpha notice with its tick box), installing it over the beta, going back, Windows and
  the processor, what differs from beta.32 (runtime, C# 15, three packages, SQLite 3.53.4, .NET
  11's IHost rethrow, the R2R target).
- CHANGELOG.md: its row in the Releases table. No release line moves (README, ACCURACY,
  LIMITATIONS keep naming the beta).
- HANDOFF: the alpha.1 lines under beta.32's START HERE (the next alpha follows the next beta;
  .NET 11 GA on 2026-11-10 moves the switch even without a beta); owner-only item 27.

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

* docs: where the alpha branch was cut - main at the notes, one docs commit after v0.1.0-beta.32 (alpha.1 PR-2)

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 16:23:35 +00:00
poli0981andClaude Opus 5.5 ac8bfda3d3 release: 0.1.0-beta.32 - its changelog file (the alpha line's groundwork), HANDOFF's beta.32 section (D73-D76), owner-only item 26, the release lines (beta.32 PR-4) (#347)
- docs/changelog/0.1.0-beta.32.md: the [Unreleased] entries of #344, #345 and #346, with what a
  user sees on updating (EULA 1.6 and Disclaimer 2.12 once; schema 21 and rules 2026.10.4 as
  they were; a beta never becomes an alpha).
- HANDOFF: beta.31's START HERE to docs/handoff/history/0.1.0-beta.31.md (and its row); the
  beta.32 START HERE - the owner's request, D73-D76, the evaluation, choices, the probe, traps;
  D73-D76 in the decisions index; owner-only item 26.
- The release lines: README's accuracy block and install line, legal/ACCURACY.md and the
  Disclaimer's copy, LIMITATIONS - "the latest beta is 0.1.0-beta.32", alphas published apart.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 16:07:25 +00:00
poli0981andClaude Opus 5.5 49b9084c1c feat: an alpha says what it is and asks first - Alpha notice + tick box, the alpha Agent's wait, ALPHA badge/banner, ledger copy; EULA 1.6, Disclaimer 2.12 (D73-D75) (beta.32 PR-2) (#346)
* feat: an alpha says what it is and asks first - the Alpha notice with its own tick box, the alpha Agent's wait, ALPHA badge and banner, the ledger copy before an alpha opens it; EULA 1.6, Disclaimer 2.12 (D73-D75) (beta.32 PR-2)

The owner's decisions of 2026-10-31, asked while planning: the alpha replaces the beta and shares
its data folder, copying the ledger before it first opens it (D73); a versioned Alpha notice with
its own tick box in the Legal Gate, the alpha's Agent waiting for it, a badge and a banner (D74);
the EULA and the Disclaimer made true about alphas (D75). Nothing of it shows in a beta.

- legal/ALPHA_NOTICE.md 1.0 (the approved text), embedded; Shared.AlphaNotice holds its key and
  version for both processes. LegalDocuments.Load(BuildLine) adds it after the four on the alpha
  line; About lists it on every line, for information.
- First run: on an alpha's gate a second warning box with the tick box; Accept is disabled until
  it is ticked. While the notice is outstanding the App holds the Agent's start - a hold of its
  own beside the updater's, set before the host starts (the connection's first round runs under
  the first-run window) - and Accept releases it and starts the Agent at once.
- Agent: an alpha's --serve reads legal_acceptance after opening the ledger and exits 8 until the
  notice is accepted at this build's version (the logon task can start it first); maintenance
  verbs are not held. Its log names the release line and the runtime.
- The shell: ALPHA badge beside the Agent pill (tooltip: the runtime), window title "FrameLedger
  Alpha", a Warning InfoBar at every start, closable for the run, opening the notice. About and
  --diag name the runtime; Settings locks the update channel on an alpha and says why.
- The ledger: LedgerDatabase.OpenAsync(backupFirst:) - an alpha copies the ledger with SQLite's
  online backup into backups\ledger-before-<version>.db before anything opens it for writing, once
  per version, under a lock of its own (the migration lock's 30 s would time a slow copy out); the
  newest three are kept and the copy just made is never pruned; a copy that cannot be made refuses
  the open (App: start-failure dialog; Agent: exit 7). Never for a viewer.
- EULA 1.6 (§2B) and Disclaimer 2.12 (§0): "pre-release builds - betas, and alphas". 12 strings in
  en/vi/ja (ja marked review).
- Docs: 08_UI, 06_DATA_MODEL §Migrations, 01_ARCHITECTURE §Lifecycle and §Data directory,
  11_UPDATER, 12_BUILD, LIMITATIONS §Alpha builds, guide/11-alpha-builds.md (+ contents, sidebar,
  the App's page list), guide/01-install, terms-in-plain-words, wiki/Releasing, CHANGELOG.
- Tests: FirstRunViewModel (tick, hold release), LegalDocuments (both lines; the constant equals
  the document's version), AgentConnection (the notice hold survives the updater's release),
  SettingsViewModel (locked picker), LedgerBackup (once per version, rows copied, keep three, the
  copy just made survives a skewed clock, a copy that cannot be made refuses the open, no request
  copies nothing), AlphaNoticeGate.

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

* fix: the ALPHA badge in the accent appearance, the picker's alpha lock on a container, About's legal list in its test (beta.32 PR-2)

The local gate's three reds on the previous commit, each a design test doing its job:
- ContrastTests: a badge's literal Appearance may not be a palette one (Danger paints outside the
  theme dictionaries, 08_UI §Contrast) - the ALPHA badge is Primary, the accent with its own text.
- ViewerModeTests: the update-channel picker keeps the viewer switch on the control itself; the
  alpha line's lock is a Grid around it bound to CanChooseUpdateChannel.
- DocumentWindowsTests: About's legal list now names legal/ALPHA_NOTICE.md (on every line, D74).

App.Tests 725/725.

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

* test: the alpha's start logic out of App.xaml.cs into AlphaStart, tested; the notice window, the exception, the no-op holds (beta.32 PR-2)

SonarCloud's quality gate on #346: new-code coverage 69.3 % against 80 %. The uncovered new lines
were the App's start helpers, DocumentWindows.ShowAlphaNotice, MainWindowViewModel's alpha
properties, LedgerBackupException's constructors and two default interface members.

- Services/AlphaStart: BackupFor (the copy only for an alpha over its own folder) and
  HoldTheAgentForTheNoticeAsync (the hold only while the notice is outstanding), which App.xaml.cs
  now calls; AlphaStartTests covers both and the viewer's and a window set's no-op members.
- DocumentWindowsTests: the alpha banner's button opens the notice in one window and asking again
  reveals it. LedgerBackupTests: the exception's three constructors.

App.Tests 730/730; dotnet format clean.

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

* docs: one Changed heading under [Unreleased] after main came in (beta.32 PR-2)

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 15:50:05 +00:00
poli0981andClaude Opus 5.5 8ac4c00e4b fix: what .NET 11's SDK asks of the source, in forms .NET 10 also compiles - span LastIndexOf/StartsWith/EndsWith, comparers for string sets, JsonElement.Parse; the probe in spike-notes §24 (D73-D76) (beta.32 PR-3) (#345)
The whole gate was run on .NET 11 RC3 (SDK 11.0.100-rc.3.26522.148) in a throwaway worktree
before the alpha line's switch was written. Native 32/32, every test suite green with no change
of answer, coverage and format clean; the managed build was red at 21 sites in 14 files, all
rewritten here so both SDKs compile them and they answer as before:

- CA1307 (13): .NET 11 adds LastIndexOf/StartsWith/EndsWith(char, StringComparison); the span
  forms (MemoryExtensions, also in .NET 10) are ordinal like the char forms. One site in a
  FluentAssertions expression tree, where a span cannot appear, compares the last char.
- MA0002 (7): C# 15 can give a collection expression a comparer, so Meziantou now flags
  HashSet<string>/Dictionary<string,...> built by []; the constructor with StringComparer.Ordinal
  (what [] used) compiles on C# 14 too.
- CA2026 (1, new in the 11 SDK): JsonElement.Parse instead of JsonDocument.Parse(...).RootElement
  in a test.

license-check was red on .NET 11 only because legal/licenses/nuget/ is the beta's package set;
the alpha branch regenerates it. docs/spike-notes/24-dotnet11-probe.md: the decision table
written before the run and what it found.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 15:19:19 +00:00
poli0981andClaude Opus 5.5 648e9c28b1 build: the alpha line - RELEASE_LINE stamped into every assembly, release.yml's line-vs-tag rule and Velopack alpha channel, CI on the alpha branch, no wiki for an alpha (D73) (beta.32 PR-1) (#344)
The owner, 2026-10-31: an alpha build where new .NET versions are tried, .NET 11 RC3 / C# 15 first,
with an experimental-build warning (owner decisions D73-D76, asked while planning). This is the
plumbing on main; it changes nothing in a beta.

- RELEASE_LINE (main | alpha), read like VERSION by Directory.Build.props, stamped as the
  FrameLedger.ReleaseLine assembly metadata; any other value is a build error. Shared.BuildLine
  reads it back for composition (BuildLineTests, AssemblyIdentityTests).
- release.yml: the version gate reads RELEASE_LINE - the alpha line takes vX.Y.Z-alpha.N and
  nothing else, no other line may carry an -alpha. tag; an alpha's vpk download and pack take
  --channel alpha (feed releases.alpha.json, asset names from assets.<channel>.json); the main
  line's pack command is unchanged. An alpha's release is titled "(experimental alpha)".
- ci.yml: also on pushes to alpha; no sonarcloud job and no Changelog step for pull requests into
  alpha. wiki.yml: no publish after an -alpha. tag.
- tools/fps-impact-runbook.ps1: the Agent path no longer names a TFM.
- Docs: 12_BUILD §The alpha line, 13_CI_CD §The alpha line (+ ci/release/wiki sections, branch
  policy), 11_UPDATER §Channels corrected in place (the alpha line uses Velopack channels;
  GithubSource reads the newest ten releases, hence one alpha per beta), 20_OPEN_QUESTIONS §G
  "The main line's .NET" with its decision table written first, CLAUDE.md, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 14:58:38 +00:00
poli0981andClaude Opus 5.5 2752fe9a2d release: 0.1.0-beta.31 - its changelog file (the remaining library updates), HANDOFF's beta.31 section (D72), the release lines (beta.31 PR-2) (#343)
- docs/changelog/0.1.0-beta.31.md: [Unreleased] moved under its heading, with the opening and how to update from
  beta.30 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules 2026.10.4; the first update
  beta.30's Velopack 1.2.161 installs). Its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.30's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.30.md (its row in the split
  table); beta.31's START HERE - D72, the choices made, what was measured, the trap; Decisions index row D72; no new
  owner-only item (item 25(c) is this update).
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 11:09:31 +00:00
poli0981andClaude Opus 5.5 6b9330cb67 deps: the .NET 10.0.14 servicing packages and the updates beta.30 left - Markdig 1.5.0, CsWin32 0.3.367, Meziantou 3.0.317, coverlet.collector 10.1.0, Catch2 3.16.1 (D72) (beta.31 PR-1) (#342)
The owner, after beta.30: "làm thêm bản beta 31 với các deps còn lại (.net 10.0.14) và 1 số thư viện khác" - inside
Dependabot's seven-day cooldown on purpose (owner decision D72).

- Microsoft.Extensions.Hosting, Microsoft.Data.Sqlite, System.Diagnostics.EventLog 10.0.14 (Microsoft.Data.Sqlite
  10.0.14 still declares SQLitePCLRaw 2.1.13).
- Markdig 1.5.0: license.txt at the packaged commit 9900e46e is byte-identical; the override's header names it.
- CsWin32 0.3.367 and Meziantou.Analyzer 3.0.317: the build is warning-free as it was, nothing to change.
- coverlet.collector 10.1.0: NoSecondMatcherTests leaves out the Coverlet.* types the collector injects into each
  instrumented assembly (a constant reflection cannot read; not ours) - the reason it stayed at 10.0.1 in beta.29.
  Passes with coverage collected as CI collects it.
- Catch2 3.16.1 (native tests): clean under /W4 /WX with the /EHsc fix kept; 32 of 32 suites pass.
- legal/licenses/nuget regenerated; 13_CI_CD §Dependabot, CLAUDE.md, 08_UI.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 10:56:29 +00:00
poli0981andClaude Opus 5.5 4eb81c467b release: 0.1.0-beta.30 - its changelog file (and the .NET 10.0.14 runtime it carries), HANDOFF's beta.30 section (D69-D71), owner-only item 25, the release lines; ConsentPrompt.ShowAsync tested (beta.30 PR-4) (#341)
- docs/changelog/0.1.0-beta.30.md: [Unreleased] moved under its heading, with the opening and how to update from
  beta.29 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules 2026.10.4; a delta of about
  5 MB, installed by beta.29's updater), and a Security entry: the runtime is .NET 10.0.14, the out-of-band release of
  2026-10-25 - the rehearsal (run 40303218479) installed SDK 10.0.403, and the package's deps.json names the 10.0.14
  runtime packs. Its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.29's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.29.md (its row in the split
  table); beta.30's START HERE - D69, D70, D71, the choices made, what was measured (WPF's re-transfer, WPF UI's
  template, ScottPlot's label, the SQLite engines, the rehearsal), the traps; Decisions index rows D69-D71; item 24(d)
  updated; owner-only item 25.
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.
- ConsentDialogKeysTests.OnlyThePrimaryButtonWithThePhraseTypedEnables: ConsentPrompt.ShowAsync through a fake
  IContentDialogService (Primary + phrase -> on; Primary alone, or the phrase and a close -> off) - the four lines
  SonarCloud found uncovered in #338.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 10:34:13 +00:00
poli0981andClaude Opus 5.5 517ef136f8 deps: Velopack and vpk 1.2.161 (D71), Markdig 1.4.2, and the SQLitePCLRaw pin dropped - Microsoft.Data.Sqlite's own 2.1.13 again; what was not taken and why (beta.30 PR-3) (#340)
- Velopack 1.2.0 -> 1.2.161 (Directory.Packages.props) with vpk 1.2.161 (release.yml) - the owner's decision D71, item
  24(d)'s Velopack half; never 1.2.158 (NuGet-deprecated). The five private fields VelopackHooksTests reads are there.
- Markdig 1.4.0 -> 1.4.2 (parser fixes); license.txt at the packaged commit 6a410393 is byte-identical to 1.4.0's, the
  reviewed override's header names the new commit.
- SQLitePCLRaw.bundle_e_sqlite3 3.0.5 transitive pin dropped: its own comment said to drop it once
  Microsoft.Data.Sqlite resolved a patched version (10.0.13 declares 2.1.13), and it had put a package built against
  the 2.x line on SQLitePCLRaw 3.x - a cross-major resolution NuGet does not report. The engine is SQLite 3.53.3
  (3.53.4 under the pin; read from the native libraries), above every floor the ledger needs.
- legal/licenses/nuget regenerated by license-gather (78 packages); THIRD_PARTY_NOTICES names the engine's package.
- Not taken, with reasons (13_CI_CD §Dependabot): the 10.0.14 servicing packages (a day old; the Brotli fix is the
  runtime's), Markdig 1.5.0, CsWin32 0.3.366/0.3.367, coverlet.collector 10.1.0, FluentAssertions 8.
- Docs: CLAUDE.md, 08_UI, 11_UPDATER, 13_CI_CD, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 10:18:23 +00:00
poli0981andClaude Opus 5.5 5608c71d59 fix(app): the hardware-change markers on a game's charts - a numbered badge per changed day in a band above the chart, the list under it, a tooltip (D70) (beta.30 PR-2) (#339)
The owner's screenshot (2026-10-26): "Driver GPU: 32.0.16.1742 -> 32.0.16.2101" with its top cut off at the chart's edge.
ScottPlot's VerticalLine label grows up from the data area into the top-axis panel, which an unused axis measures at
15 px; a day's further lines were lost; white on the orange read 1.78:1 / 2.63:1. Owner decision D70: numbers + a list.

- TrendSeriesBuilder.Markers (replaces MergedByDay): one ChangeMarker per changed day, numbered oldest first, each
  change once; the view model hands the same list to both charts and both lists.
- ChangeMarkerPlottable (IPlottable + IRenderLast): the dashed lines clipped to the data area; the badges after the
  axes in a band kept with Axes.Top.MinimumSize, joined to their lines, coloured from ChartTheme.Current at every render
  with ChartTheme.TextOn's black or white (black on both oranges, 11.79:1 / 8.00:1).
- ChangeBadgeLayout: inside the data width, never over another; too close -> aside in order; beyond ~one badge from
  their lines or no room -> one badge for the run ("3-5").
- ChangeMarkerList + Controls/ChangeBadge under both charts; Formats.Day; Trend_Changes_Header and
  Trend_Change_Heading_Format in en/vi/ja (ja drafts marked review).
- TrendChart: tooltip near a line or over a badge; the pointer read through the element's DPI now
  (GetPlotPixelPosition) - DisplayScale is read once, before the control has a window - for the overview's click too.
- ChartPalette.ForBackground shared by FgMixBar and ChangeBadge.
- Tests: ChangeBadgeLayoutTests (cases + a 20-2000 px sweep), PagesLoadTests.Changes (real renders at 640x320, 640x220,
  tight limits, 300x220, thirty days in a row; the tooltip's hit test), ChartMathTests (the badge text in both
  palettes), TrendSeriesBuilderTests, GameDetailViewModelTests; the shared page fixture has a driver change so the
  readable and theme-switch sweeps measure the list and its chip.
- Docs: 08_UI (Trend, the numbered markers, Contrast, DPI, Known gaps), 16_WPFUI_SYNTAX (Theming, Custom controls,
  ScottPlot, two Gotchas), 02_SPEC FR-6.3, guide 03 and 07, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 10:02:40 +00:00
poli0981andClaude Opus 5.5 1485341284 fix(app): Enter enables once the consent phrase is typed exactly (D69); the game page's switches read their row again after every click (beta.30 PR-1) (#338)
- ConsentPrompt: the primary button (Enable hooking) is the dialog's default, built by Build() so a test can render it.
  WPF UI 4.3.0's template sends Enter to the default button, and DefaultButton = Close made Enter in the phrase box
  decline without a word (the owner's report, 2026-10-26).
- ConsentDialogContent: while the phrase does not match, the content keeps Enter (SwallowsEnter) - the template makes
  Close the default while the primary is disabled; an IME's ImeProcessed is never taken for Enter.
- GameDetailViewModel: the Hooking and Recording commands raise the switch's property whatever happened
  (ThenShowStoredAsync). The switches are OneWay with a Command, a click flips IsChecked through SetCurrentValue, and a
  command that changed nothing (declined, refused, no Agent) left the switch on beside "off".
- Tests: ConsentDialogKeysTests (the real template and switch on the STA thread), GameDetailViewModelTests (every
  outcome raises the property; red without the fix).
- Docs: 19_SAFETY §User-facing consent (the D69 amendment), 08_UI (§Keyboard, the two switches, WPF UI's key routing
  corrected), 16_WPFUI_SYNTAX §Gotchas, the wiki's App-UI-development, guide 07-screens, DialogKeyboard's comment,
  CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 09:39:31 +00:00
poli0981andClaude Opus 5.5 dc4727f846 release: 0.1.0-beta.29 - its changelog file, HANDOFF's beta.29 section (SonarCloud from CI, the libraries Dependabot never updated), owner-only item 24, the release lines; the patch check's NOSONAR on the line SonarCloud names (beta.29 PR-4) (#337)
- docs/changelog/0.1.0-beta.29.md: [Unreleased] moved under its heading, with the opening and how to update from
  beta.28 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules 2026.10.4; what is shown and
  recorded is beta.28's, the libraries under it newer); its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.28's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.28.md (its row in the split
  table); beta.29's START HERE - D68, the choices made, what the analyses measured, the traps; owner-only item 24
  (optional settings: SonarCloud for Dependabot's pull requests, the branch a refused dispatch left, required checks,
  the two updates not taken).
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.
- A correction from main's analyses after #336: the 34 issues were dated by blame, two of them new code (the gate's
  C); the first analysis with a version kept the old new-code start and the next went green with nothing fixed; the
  merge of #336 closed 33, and cpp:S3519's NOSONAR moves from `p -= 5` to the read SonarCloud reports on the next line
  (a comment; the Overlay's code unchanged). 13_CI_CD, the beta.29 changelog and HANDOFF (two traps) say so.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 13:48:14 +07:00
poli0981andClaude Opus 5.5 3c89a76f71 fix(native): the 34 C++ issues of main's first SonarCloud analysis from CI - hook-harness asks for its D3D11 objects first, NvU32 as %lu, LARGE_INTEGER initialised through QuadPart, read bounds tested, five NOSONAR with reasons; the triage in 13_CI_CD (beta.29 PR-3) (#336)
main's first SonarCloud analysis from CI (run 40160302893) failed its gate on a C reliability rating: 34 C++ issues,
all on lines older than the release and all counted as new code, which the compilation database's real MSVC flags let
CFamily see for the first time.

- hook-harness: --vulkan and --opengl create no D3D11 objects, and --opengl alone (the default probes) or either flag
  beside a D3D11 mode called through a null swapchain - exit 0xC0000005 on main, measured. Every mode that drives the
  D3D11 swapchain asks HaveD3D11 first (exit 1 with a message); the dispatch's duplicate mode flags are the pre-pass's.
- fl-probe-nvapi: %lu for NvU32 (an unsigned long); the machine line CaptureHost parses prints the same digits.
- guard_test: 64-bit arithmetic on FILETIME's halves instead of a ULARGE_INTEGER; strnlen with the value's bound.
- A LARGE_INTEGER read through QuadPart after `{}` had made its first member, the LowPart/HighPart struct, the active
  one: the Overlay's log clock epoch and the Vulkan layer's enable-list read (where the PR's first two pushes drew the
  same S6232 on their own lines) are initialised through QuadPart now.
- VkLayer (that once-per-process read) and fl-baseline-probe: the read's bound tested before the terminator is
  written.
- NOSONAR with the reason above it, five: the ring's Publish (the path runs past a failed REQUIRE in ring_test), the
  patch check's hot-patch read, three console printf of a test and a probe.

The Overlay built from main and from this change, in one folder with one FL_BUILD_ID, has a byte-identical .text
(722,153 bytes); the layer's .text differs in one 613-byte range inside ThisProcessIsEnabled. docs/13_CI_CD.md carries
the triage, corrects its claim that issues on older lines are dated by blame, says why a local SonarAnalyzer's C#
findings are not the gate's, and quotes Dependabot's 2026-10-25 run on the shipped libraries.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 12:59:21 +07:00
poli0981andClaude Opus 5.5 a55cc478e8 deps: the NuGet updates Dependabot never proposed - .NET 10.0.13 servicing (Hosting, Sqlite, EventLog), Dapper 2.1.89, CsWin32 0.3.363, the test SDK and xunit; coverlet stays at 10.0.1 (beta.29 PR-2) (#335)
- Shipped: Microsoft.Extensions.Hosting, Microsoft.Data.Sqlite, System.Diagnostics.EventLog 10.0.12 -> 10.0.13 (the
  October servicing release); Dapper 2.1.86 -> 2.1.89; the CsWin32 source generator 0.3.333 -> 0.3.363.
- Tests: Microsoft.NET.Test.Sdk 18.11.0, xunit.v3.mtp-off 4.0.2, xunit.runner.visualstudio 4.0.1.
- legal/licenses/nuget: tools/license-gather.ps1 re-run - 32 files name the new versions; no licence text changed.
- Not taken: coverlet.collector 10.1.0 - the tracker it adds to every assembly it instruments declares a constant
  (ModuleTrackerRegistryKey) whose value reflection cannot read, and NoSecondMatcherTests reads every string constant
  in Application, Domain and Infrastructure; measured locally with coverage on (10.1.0 fails, 10.0.1 passes), after
  the first CI run had blamed CsWin32. Directory.Packages.props says so beside it. Also not taken: Markdig 1.5.0,
  Velopack 1.2.161, FluentAssertions 8; Meziantou is Dependabot's to propose.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 12:02:07 +07:00
poli0981andClaude Opus 5.5 a644dd873e ci(sonar): SonarCloud from CI - the sonarcloud job, SonarQube.Analysis.xml, the scanner as a local tool, the C++ through the compilation database; Dependabot cooldown, the NuGet audit, CodeQL reads the workflows (beta.29 PR-1) (#334)
The owner turned SonarCloud's Automatic Analysis off and set SONAR_TOKEN (2026-10-24) and asked for
the CI-based analysis with the newest scanner, run until its gate passed, and for Dependabot, the
audit and code scanning to be brought up to date (owner decision D68, replacing D67).

- ci.yml: a second job, sonarcloud, after check - SonarScanner for .NET 12.0.0 from
  .config/dotnet-tools.json; begin -> its own `dotnet build` -> end. Its own build because the
  scanner's targets turn TreatWarningsAsErrors off in the build they instrument. Advisory, not a
  required check; sonar.qualitygate.wait makes a failed gate a red job. Runs for this repository's
  pull requests (not a fork's, not Dependabot's - no secret) and for main: the organisation's plan
  refuses any other branch ("not allowed to access data from non main branches"). Permissions per
  job, none at workflow level (githubactions:S8264 on the first analysis).
- Coverage: build.ps1 collects "XPlat Code Coverage;Format=cobertura,opencover"; the job downloads
  check's artifact. C# only: sonar.coverage.exclusions leaves the PowerShell tools and src/native,
  which have no coverage report, out of the figures (SonarCloud counted build.ps1's 232 executable
  lines as uncovered).
- C++: FrameLedger.Infrastructure.csproj names src/native's .cpp/.h as FlNativeSource items that
  exist only while the scanner instruments the build; analysed with CMake's compilation database
  (configure with CMAKE_CXX_SCAN_FOR_MODULES=OFF - the .modmap response files only a build writes
  stopped CFamily - and fl_ac_floor_gen): 32 compilation units, all in full.
- SonarQube.Analysis.xml replaces .sonarcloud.properties; the version is the newest v* tag, so the
  project's "Previous version" new code is everything since the last release; S8417 (src/native)
  and csharpsquid:S6640 (Infrastructure, Shared) ignored where they apply by design;
  sonar.cs.roslyn.ignoreIssues.
- Dependabot: a seven-day cooldown on version updates; the actions' minor and patch releases
  grouped. It has never proposed a NuGet library update here (#66-#314: analyzers only) - beta.29
  PR-2 makes the missed ones. Directory.Build.props: the NuGet audit written down (all, low).
  codeql.yml: the actions language; superseded pull-request runs cancelled.
- Docs: 13_CI_CD (ci.yml, codeql.yml, SonarCloud rewritten with D67 kept as history and the first
  analyses measured, Dependabot and the NuGet audit, the checklist), 12_BUILD, CLAUDE.md, HANDOFF's
  D68 row, the wiki's Releasing page, CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 11:00:35 +07:00
poli0981andClaude Opus 5.5 410c66d146 release: 0.1.0-beta.28 - its changelog file, HANDOFF's beta.28 section (every game being recorded on the Dashboard), owner-only item 23, the release lines (beta.28 PR-2) (#333)
- docs/changelog/0.1.0-beta.28.md: [Unreleased] moved under its heading, with the opening and how to
  update from beta.27 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules
  2026.10.4; only the App changes); its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.27's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.27.md (its
  row in the split table); beta.28's START HERE - no new owner decision, the choices made for the
  cards, the traps; owner-only item 23 (two and three games at once).
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 05:10:29 +00:00
poli0981andClaude Opus 5.5 2188373239 feat: the Dashboard shows every game being recorded - one live card per running session, hooked first, two to a row, the games counted; two native injection cases wait up to 12 s (beta.28 PR-1) (#332)
The owner, 2026-10-20: "Thêm cơ chế hiển thị UI/UX Dashboard khi chạy >=2 game trong cùng 1 thời
điểm". The Agent records one session per executable, so two games are two sessions; the Dashboard had
one live card, which a hooked session took and kept, and the second game showed only as "Running
sessions: 2".

- DashboardViewModel.LiveCards: a LiveCaptureViewModel per running session, made by its session's
  first event or seed (LiveSessions) and fed only its own session's events; hooked first, each kind in
  the order it started, moved never rebuilt; LiveIdle, LiveCountText ("2 games recording" from two
  on, Dashboard_Live_Count_Format en/vi/ja) and LiveColumns (two to a row from two on).
- LiveCaptureViewModel: a card is one session's (a constructor with its guid; another session's start
  or seed no longer takes it).
- DashboardPage: the header with the count, one idle card, an ItemsControl of cards in a UniformGrid.
- Docs: 08_UI §Dashboard, guide/07-screens, CHANGELOG.
- Tests: DashboardViewModelTests (two games, a third, each ending; the existing cases per card),
  LiveCaptureViewModelTests, PagesLoadTests' surfaces draw a hooked and a held card in both themes.

Then, from this PR's first CI run (the native OpenGL and window-hold injection cases wait up to 12 s for their frames - 4 s was not enough on a loaded CI runner (beta.28 PR-1)):

#332's first CI run: fl_guard_test "OpenGL: the injected Overlay hooks opengl32!wglSwapBuffers ..."
failed with writeIndex 0 and apiMask 0x10 - the hook installed (the OpenGL bit is set at install),
no frame recorded in the 4 s the case waited; the suite took 115 s on that runner. Nothing native
changed in beta.28.

- Both cases with that wait (OpenGL, and the D3D11 chain on a real window) hold the harness 16 s and
  wait up to 12 s, ending at the 20th record as before; the child is terminated when the case ends,
  so the longer hold costs nothing.
- The OpenGL case's failure says the hooks mask, the writer's status and whether the harness still
  runs; the window case's says the status.
- CHANGELOG [Unreleased] (developers only).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 04:42:29 +00:00
poli0981andClaude Opus 5.5 94120d3308 release: 0.1.0-beta.27 - its changelog file, HANDOFF's beta.27 section (six faults from the owner's eight sessions; the crash-safety question left to the owner), owner-only item 22, the release lines (beta.27 PR-2) (#331)
- docs/changelog/0.1.0-beta.27.md: [Unreleased] moved under its heading, with the opening and how to
  update from beta.26 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules
  2026.10.4; the frame-generation fix reads stored sessions at once, the rest applies to new ones);
  its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.26's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.26.md (its
  row in the split table); beta.27's START HERE - no new owner decision, the owner's two ways for
  Steam games and why the note was taken, one question left to the owner (the crash safety counting
  a direct start's hand-off), what the ledger copy measured, the traps; owner-only item 22 (the driver's report and 20(b), Start directly on Lies of P, one window
  per session, display sizes).
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 10:53:28 +07:00
poli0981andClaude Opus 5.5 24a87159f4 fix: the owner's eight sessions of 2026-10-20 - a x2.52 state, the driver's DLSS word lost at exit, Start directly losing the game Steam starts, two summary windows, display sizes, a bare DLSS line; the Steam note; the two load-flaky tests (beta.27 PR-1) (#330)
The owner ran the installed 0.1.0-beta.26 (sessions 64-71) and asked for the results to be checked,
the two flaky tests fixed, bugs fixed, and a release if there were bugs. Read from a backup copy of
the ledger and the logs (docs/spike-notes/23-owner-runs-2026-10-20.md).

- FgWindow.IsNearWholeMultiplier: a window is a state's only within 10 % of a whole multiplier of two
  or more (FgSlices.Slice.IsActive); FgMixRecord.Parse reads stored rows by the same rule. Silent Hill
  2 under Dynamic MFG listed x2.52 for 12.8 s - windows where the multiplier stepped; it now reads
  x2.0, x3.0, none and 7.36 % not classified.
- NgxDriverState / CaptureSession: the driver is not asked after the game has gone, and CREATED |
  EVALUATE stand once a reading carried them. The last NGX reading, taken after the target exited,
  replaced every in-game one: none of the 14 answered sessions kept the two bits, so DLSS
  (driver-reported) and the NVIDIA App's mode (D63) never showed on an NGX-direct title.
- CaptureOrchestrator: a launch says it ended on its own (Recorded) with the pids it recorded
  (Targets), so a process turned away while it ran - the game Steam starts after Lies of P hands
  itself over - is recorded when it ends; the launch's own process never is.
- SessionSummaryOpener: one window per session; opening it again brings it forward.
- DisplayTally: the sizes are the mode's last sample that saw the window (a game leaving exclusive
  fullscreen closes it first; five sessions stored none).
- DlssText.Line: no line that says only "DLSS".
- Tests: the guard's scan set includes the test host above the harness, which under a full gate
  releases modules while it starts its other classes - ModuleScanFailed (reproduced 1 run in 12 of
  the assembly with coverage; 15 of 15 green after), ProcessUnreadable on 2026-10-19.
  ShmDrainIntegrationTests.InjectAsync asks again on those two reasons only (4 times at most, 250 ms
  apart); the pause case waits for READY; every injection suite waits for the harness's flushed
  "presenting" line instead of 800 ms (tests/Shared/HarnessReady.cs).
- Docs: 03_METRICS (the mix, the driver-reported rung, display sizes), 04_CAPTURE, 06_DATA_MODEL,
  08_UI, 14_TESTING, 18_GPU_VENDOR_APIS, 19_SAFETY (direct starts counted by the crash safety -
  measured, the policy unchanged), LIMITATIONS, guide (troubleshooting, results), spike-notes section
  23, HANDOFF items 20 and 21, CHANGELOG.

Then, on the owner's word about Steam games (Play > Start directly says a Steam game may hand itself to Steam - the notice, the tooltip and Settings (en/vi/ja); why a note rather than a fixed Steam rule (beta.27 PR-1)):

The owner, 2026-10-20: Steam games hand themselves to Steam; a note in the UI, or a fixed setting
that Steam's games always go through the Steam client - the choice left open. The note:

- GamePlayer: PlayResult.SteamGame - the game the agent starts (Start directly, or an App running as
  administrator, or a Steam record with no link) is one Steam's own records name; the notice then
  reads Play_Started_Steam_Format / Play_Elevated_Steam_Format. Store records are read once a press.
- Strings: Play_ToolTip_Direct and Settings_PlayMode_Body say a Steam game may hand itself to Steam
  and the game Steam then starts is recorded; Settings adds that a few will not start outside Steam
  at all. en/vi/ja, ja marked review; Strings.Designer regenerated.
- Why not the fixed rule: three of the five Steam games started directly on 2026-10-20 ran and were
  measured from their first frame, and a Vulkan game is measured only when FrameLedger starts it
  (Everhex Demo) - recorded in 08_UI.
- Docs: 08_UI, guide/08-settings, LIMITATIONS, CHANGELOG.
- Tests: GamePlayerTests (Steam started directly and elevated say it; a loose or GOG game does not).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 10:31:47 +07:00
poli0981andClaude Opus 5.5 ea3a8d3ee0 release: 0.1.0-beta.26 - its changelog file, HANDOFF's beta.26 section (the x1336 state fixed, measured on the owner's ledger), the release lines (beta.26 PR-3) (#329)
- docs/changelog/0.1.0-beta.26.md: [Unreleased] moved under its heading, with the opening and how to
  update from beta.25 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules
  2026.10.4; recorded sessions read by the new rule); its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.25's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.25.md (its row
  in the split table; D65 pointed there); beta.26's START HERE - why a release was needed, no new owner
  decision, what the ledger copy measured (Silent Hill 2's first fifteen seconds compiling shaders),
  the traps.
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.
- docs/13_CI_CD.md and HANDOFF item 20(e): the owner marked the last six SonarCloud issues the same day
  (S1244 x4 and S7631 false positives, S3869 accepted); main's analysis at 6b07eb2 has none open.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 23:41:34 +07:00
poli0981andClaude Opus 5.5 c14340e4f9 ci(sonar): SonarCloud's six open findings on main triaged; wiki.yml publishes only for a Release run of this repository (beta.26 PR-2) (#328)
- docs/13_CI_CD.md SonarCloud: the six left open after the owner's marking of the analysis of
  e35b971 (0.1.0-beta.25) - S3869 to accept as the table said, four S1244 false positives (exact
  comparisons on purpose: HSV's max, the scroll snap, a default scale), and S7631 fixed here - each
  with the comment to paste in the UI.
- .github/workflows/wiki.yml: the job also requires workflow_run.head_repository to be this
  repository; a fork could not start the Release run before either, and the condition now says so.
  13_CI_CD wiki.yml says so.
- HANDOFF item 20(e) annotated; CHANGELOG (developers only).
- PR-1's wording, now measured: the x1336 stretch is the session's first fifteen seconds - 1,369, 4,877
  and 1,303 presents with 1, 0 and 1 application frames, then a 13,348 ms frame - Silent Hill 2
  compiling its shaders at start (the owner), decoded from the ledger copy's frames.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 23:19:36 +07:00
poli0981andClaude Opus 5.5 6b07eb2dc8 fix: a frame-generation window is read only with eight application frames and a ratio up to x8 - the x1336.0 Silent Hill 2 state; the owner's runs of 2026-10-19 recorded (beta.26 PR-1) (#327)
The owner's Silent Hill 2 session (0.1.0-beta.25, NVIDIA App Dynamic multi frame generation) listed a
x1336.0 state (0.20 -> 267.20 FPS, 10 s) and the DLSS line cited it. Its two windows held one
application-frame token each against 1,336 presents: a window needed eight presents and one token.

- FgSlices.Slice.IsReadable: eight presents AND eight application frames; IsActive also caps the ratio
  at FgWindow.GenerationCeiling (x8 - no shipping technology generates more than x6). The mix and the
  steady state read the same windows.
- FgWindow refuses a ratio that held above x8 as BeyondGeneration ("beyond_generation"), after
  uniformity; its words in the capture host and the App (en/vi/ja).
- FgMixRecord.Parse reads a stored mix by today's rule: a stored state above x8 or under eight
  application frames a window joins the not-classified time. That session now reads x2.0, x3.0, x6.1,
  none and 30 s not classified; its DLSS line cites x6.1.
- Docs: 03_METRICS (the mix's amendment), 06_DATA_MODEL, LIMITATIONS, 05_DETECTION (the override's
  library names), spike-notes section 22 (the owner's runs: the Dynamic line confirmed, Lies of P read
  no FSR mode with the query hooked), HANDOFF items 20 and 21 annotated.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 22:36:57 +07:00
poli0981andClaude Opus 5.5 e35b971f27 release: 0.1.0-beta.25 - its changelog file, HANDOFF's beta.25 section with D65 built and owner-only item 21, the release lines (beta.25 PR-2) (#326)
- docs/changelog/0.1.0-beta.25.md: [Unreleased] moved under its heading, with the opening and how to
  update from beta.24 (nothing shown again - Disclaimer 2.11, Privacy Policy 2.12; schema 21; rules
  2026.10.4); its row in CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.24's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.24.md (its row
  in the split table; D62-D64, D66, D67 pointed there); beta.25's START HERE - D65 built, the rule the
  plan did not have (no FSR mode at a dynamic resolution), what was measured, the traps; owner-only
  item 21 (Lies of P), its decision table written before the run; D65's row in the decisions index.
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.
- docs/17_HOOK_ENGINE.md: the ffxDispatch row and the record layout no longer read FSR's quality byte as
  always 0xFF - #325 left both lines as they were.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 20:54:05 +07:00
poli0981andClaude Opus 5.5 d7f056947a feat: FSR's quality mode, from the size the game asked AMD's library for and then rendered at - ffxQuery hooked beside ffxDispatch, none at a dynamic resolution (D65, beta.25 PR-1) (#325)
The FidelityFX dispatch carries no quality mode: FfxApiUpscaleQualityMode is an input to
ffxQuery, which a title asks before it sizes its targets. The Overlay now hooks ffxQuery on
the four modules it hooks ffxDispatch on, keeps each answer the vendor returned (one slot
per mode), and an UPSCALE dispatch whose sizes fit exactly one kept answer publishes
0x10 + mode in upscalerQuality; anything else stays 0xFF. Its own hook family
(FL_HOOK_UPSCALER_QUALITY, bit 11, mirrored), rule 4 justified in 17_HOOK_ENGINE.

A session, its segments and the live card read one rule (Domain.Metrics.QualityByte): FSR's
mode is withheld when any FSR frame was rendered at a size no named frame has - a dynamic
resolution - as legal/ACCURACY.md's approved clause promises. The App names the mode
(FSR 3 Quality, FSR Native AA); en/vi/ja.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 20:05:00 +07:00
poli0981andClaude Opus 5.5 5807220c51 release: 0.1.0-beta.24 - its changelog file, HANDOFF's beta.24 section with D62-D67 and owner-only item 20, the release lines, the analyzers Dependabot proposed in #314 (beta.24 PR-10) (#324)
- docs/changelog/0.1.0-beta.24.md: [Unreleased] moved under its heading, with the opening and how to
  update from beta.23 (Disclaimer 2.11 and Privacy Policy 2.12 shown once, schema 21); its row in
  CHANGELOG.md's Releases table.
- docs/HANDOFF.md: beta.23's START HERE moved verbatim to docs/handoff/history/0.1.0-beta.23.md (its row
  in the split table, D60/D61 pointed there); beta.24's START HERE - D62-D67 (D65, FSR's quality mode,
  deferred to the next beta), what the owner's ledger measured, the traps; owner-only item 20; the
  decisions index rows D62-D67.
- The release lines: README, the accuracy block (legal/ACCURACY.md and its copies), LIMITATIONS.
- Directory.Packages.props: Meziantou.Analyzer 3.0.307 and Microsoft.VisualStudio.Threading.Analyzers
  18.12.1 - Dependabot's #314, which it closed itself after a rebase request; applied by hand.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 19:47:54 +07:00
poli0981andClaude Opus 5.5 3751348d5a feat: which DLSS a session ran - each library's version and where it was loaded from, the preset the driver reports, DLSS 4 / 4.5 only where the session shows it (D64, beta.24 PR-8) (#323)
- Domain: Detection/DlssGeneration, evidence-bound and strongest first: preset L/M reported applied ->
  DLSS 4.5, a DLSS-G state at x5 or more -> 4.5, preset J/K -> 4, x3/x4 -> 4, library 2.x -> 2, library
  3.x or frame generation 1.x-3.x -> 3; a 310 library alone, a CNN preset or x2 names nothing. Never a
  default preset inferred from a version.
- Application: RuntimeModuleSource / RuntimeModuleSources - a module's folder class (game, graphics
  driver: the driver store or %ProgramData%\NVIDIA, Windows); RuntimeModuleInfo.Source; CensusNames gains
  five snapshot-only names (sl.dlss_d, sl.common, sl.reflex, amd_fidelityfx_loader_dx12, nvngx_dlssnr);
  the aggregator stores sessions.runtime_module_sources (schema 0021) - the class, never the path.
- Infrastructure: the module snapshot records every module under %ProgramData%\NVIDIA\NGX whatever its
  name (the owner's Silent Hill 2 ran x6 through the NVIDIA App override with no census-named DLSS
  library loaded) and classifies each module's folder.
- App: DlssText - the summary's DLSS line, the game page's label, the CSV "# dlss:" line.
- Strings: 16 new keys en/vi/ja (ja marked review).
- Tests: DlssGenerationTests, RuntimeModuleSourcesTests, RuntimeModuleSnapshotSourceTests (this test
  process's own modules, a copied native DLL under a temporary NVIDIA\NGX folder), SessionAggregatorTests,
  LedgerDatabaseTests (script 0021), the repository round trip, DlssTextTests (rows shaped like the owner's
  Witcher 3 and Silent Hill 2 sessions).
- Docs: 05_DETECTION DLSS generation (the table with its sources; "the override loads nvngx_dlss.dll under
  the same name" struck as unmeasured), 06_DATA_MODEL 0021, 08_UI, LIMITATIONS, guide 03/10, CHANGELOG;
  legal/ACCURACY.md's DLSS version bullet and Privacy Policy 2.12 in the words approved with the plan.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 19:34:45 +07:00
poli0981andClaude Opus 5.5 a6717fe3ca feat: the quality mode the NVIDIA App set, where the driver reports its override applied - on every page that names the upscaler; the driver line reads NGX's numbering (D63, beta.24 PR-7) (#322)
- Application: Recording/QualityResolver (D63). When DLSS super resolution ran (a hook named it, or the
  driver saw it created and evaluated) and the driver's per-process word says an NVIDIA App override
  applied (ENABLED with PERF_MODE, SR_DLAA_MODE or SCALING_RATIO), the mode is the profile's
  NGX_DLSS_SR_MODE checked against the word's performanceMode; DLAA from its bit; a custom ratio with
  its percent. Disagreement, or a report that does not settle, reads as overridden with no mode - never
  the game's value. Otherwise the hooked Streamline byte; otherwise none. Read at display time from
  ngx_driver_words and driver_profile, so sessions recorded before resolve alike. NgxDriverWords.Parse;
  the live progress event gains upscalerQualityOverride (07_IPC: optional, from the report alone).
- Domain: UpscalerQualityMode, and UpscalerNames decodes the three numberings - the hooked byte
  (sl::DLSSMode), the driver's report (NGX's own: measured on the owner's ledger, Silent Hill 2 under the
  App's Ultra Performance, profile 5, was reported as 3) and the profile (NGX_DLSS_SR_MODE).
- App: Formats.UpscalerOf(SessionRow / SessionProgressEvent) on the summary, the Sessions tab, the game
  page and the live card ("DLSS (driver-reported) Quality · NVIDIA App", "· NVIDIA App override"); mode
  names from resx; the driver line decodes the report in NGX's numbering (it printed nothing for 3 and
  would have printed a DLAA override's 5 as Ultra Performance); CSV "# quality_mode:".
- Native: five comments that called a quality byte of 0 "NGX MaxPerf" corrected - comments only.
- Strings: 4 new keys en/vi/ja (ja marked review).
- Tests: QualityResolverTests (the owner's Silent Hill 2 and Expedition 33 words as fixtures),
  UpscalerNamesTests, FormatsTests, NvidiaOverridesTests, SessionProgressCalculatorTests,
  SessionExporterTests, MetricEnumMirrorTests.
- Docs: 03_METRICS Upscaling (D63 amendment; the beta.8 sentence struck for the mode only), 05_DETECTION,
  07_IPC, 08_UI, 18_GPU_VENDOR_APIS, LIMITATIONS, guide 03/10, CHANGELOG; legal/ACCURACY.md's Quality mode
  bullet in the words approved with the plan, without its FSR clause; Disclaimer 2.11.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 19:18:55 +07:00
poli0981andClaude Opus 5.5 3a25d01bf8 feat: every frame-generation state a session held - a bar and a table with each state's share, its own Native -> Displayed and how it was set (D62, beta.24 PR-6) (#321)
- Domain: Metrics/FgMix over the steady state's own five-second windows (FgSlices: the cut and the
  dominant state, moved out of FgSteadyState unchanged). Windows are active, no frame generation (only
  where a counted none is allowed) or not classified; active ones are grouped by repeating the steady
  state's extraction until none is left, a group under 10 s going back to not classified. Each row has
  its own factor, rates, seconds and share; the shares sum to 1. Never an average across states.
- Application: SessionAggregator stores it as sessions.fg_mix (schema 0020, JSON through FgMixRecord)
  when the frame generation was named and the count stood or was refused only as non_uniform /
  ambiguous_band. Older sessions keep NULL and are never rebuilt from their blobs.
- App: the summary's "Frame generation in this session" - FgMixBar (chart palette, a state by its
  multiplier, two new keys; follows a theme switch through ApplicationBackgroundColor) and a table
  (swatch, x4.0 frame generation, 35.33%, 70 -> 282 FPS, time); above it how frame generation was set
  (NvidiaOverrides.FrameGenerationContext: the NVIDIA App's Dynamic / Fixed, the driver's own profile, or
  the game); a line for a session that counted frame generation and has no mix. CSV "# fg_mix:"; the
  FG column's formats moved to resx; the profile line's automatic dynamic target reads "max refresh rate".
- Strings: 26 new keys en/vi/ja (ja marked review), one reworded.
- Tests: FgMixTests, FgMixPresentationTests, NvidiaOverridesTests, SessionSummaryViewModelTests,
  SessionExporterTests, SessionAggregatorTests, LedgerDatabaseTests (script 0020), the repository round
  trip, MetricEnumMirrorTests (FgMixKind is Domain's own); the summary surface in PagesLoadTests carries
  a mix, so the block is read in both themes and through a switch.
- Docs: CLAUDE.md rule 6 (dated amendment), 03_METRICS The mix, 06_DATA_MODEL 0020, 08_UI, LIMITATIONS,
  guide 03/07/10, CHANGELOG; legal/ACCURACY.md's frame-generation bullet gains the sentence approved
  with the plan (README and the Disclaimer carry it verbatim).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 19:04:55 +07:00
poli0981andClaude Opus 5.5 985decfdc6 docs: 20_OPEN_QUESTIONS keeps its open entries and spike-notes becomes the index of its sections - the resolved and measured moved verbatim (beta.24 PR-5) (#320)
Owner request 2026-10-19 (decision D66), second half of the split.

- docs/20_OPEN_QUESTIONS.md (4,467 -> 2,008 lines) keeps its rules (the "A ✅
  entry is closed" rule gains a dated amendment naming where), the scope
  decisions, §S24 and every entry §S24 does not mark resolved. The 26 S and 4 H
  entries it marks resolved moved, in order, to docs/open-questions/closed-s.md
  and closed-h.md; a table at the end of each series lists them. S12's heading
  says ✅ but §S24 says 🅓 (deferred): it stays.
- docs/spike-notes.md (2,816 -> 47 lines) is the title, the intro and the index
  of its 24 sections (§Environment, §0-§21, §Exit criteria), each moved to its
  own file under docs/spike-notes/, with the convention for a new measurement.
- tools/docs-split-check.ps1 holds both indexes to their folders (11 self-test
  cases). PR template, fps-impact-runbook's message, CLAUDE.md, docs/README and
  12_BUILD name the parts.

Proof: a script rebuilt both originals byte for byte from the parts against the
base commit (the original supplies the heading order only); docs-split-check,
wiki-check, notice-check and the App's document tests pass.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:47:55 +07:00
poli0981andClaude Opus 5.5 237971ef59 docs: CHANGELOG and HANDOFF split into parts, moved verbatim - each original stays as the index, release-notes reads the version's own file, a gate keeps them in step (beta.24 PR-4) (#319)
Owner request 2026-10-19 (decision D66): the long documents split.

- CHANGELOG.md keeps its header (with a dated note), [Unreleased] and a
  Releases table; each released section moved to docs/changelog/<version>.md
  (23 files) and the ledger kept before the first tag to five parts under
  docs/changelog/ledger-before-0.1.0-beta.1/, cut at ### boundaries. 6,130 ->
  107 lines.
- docs/HANDOFF.md keeps the rule, a "How this file is split" table that
  resolves every cited section (§P2, §P3, §P4, §Traps, §2b, §beta.N, items),
  START HERE, the open owner-only items, a Decisions index (D1-D61) and
  "Keeping this file honest" with the convention for each release. The P0
  queue, P2-P4 and every train beta.3-beta.22 moved to docs/handoff/history/,
  the passed owner-only items (3, 12, 14-19) to docs/handoff/owner-only-passed.md,
  the corrections and traps to docs/handoff/traps.md. 2,844 -> 299 lines.
- tools/release-notes.ps1 reads docs/changelog/<version>.md when it exists,
  CHANGELOG.md otherwise; three new self-test cases.
- tools/docs-split-check.ps1 (new gate, nine self-test cases both ways): no
  released section left in CHANGELOG.md, one own heading and no relative link
  per release file, and both indexes name their files and vice versa.
- 12_BUILD, 13_CI_CD, CLAUDE.md, README, docs/README, wiki/Releasing,
  wiki/Developers and wiki/Developer-glossary name the split.

Proof: a script rebuilt both originals from the parts byte for byte (CHANGELOG
6,130 lines, HANDOFF 2,844); release-notes output for all 23 versions matches
the SHA-256 baseline taken before the split; wiki-check, notice-check and the
App's document tests pass.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:34:22 +07:00
poli0981andClaude Opus 5.5 16134d246f fix(overlay): the game-side log keeps every line a stop writes - the last flush waits for the stop (beta.24 PR-3) (#318)
* fix(overlay): the game-side log keeps every line a stop writes - the last flush waits for the stop, and a slot is printed only once written (beta.24 PR-3)

StopObserving sets g_observing to 0 first and writes STOP / UNHOOK_* after; the
watchdog's loop returns the moment it reads 0 and made its one final flush at
once. When the stop ran on a presenting thread (MayObserve's one-frame safety
stop), that thread could still be writing: the last patch's line (the kernelbase
loader detour) reached the ring after the last flush ever made. fl_guard's
native-log case went red under load since beta.9 for exactly this.

- StopObserving stores g_stopLogged (release) after its lines and the status,
  then wakes the watchdog. WatchdogThread waits for it, bounded at 2 s, then
  writes STOP_FLUSHED (a=1 when the stop finished) and makes the final flush.
- Each log slot has a commit word written after its fields (g_logCommit):
  an ordinary flush stops at the first uncommitted slot for the next one to
  pick up; the final flush names it in a # line. The header is written once.
- guard_test [log]: polls for STOP_FLUSHED and requires a=1, then checks every
  UNHOOK line as before.

Per-present path: unchanged (no instruction added there); the one-time stop
gains a store and a SetEvent. 32/32 native tests; the [log] case 20/20 with all
28 logical processors kept busy.

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

* fix(overlay): FlushLog's parameter is lastFlush, not final - a context-sensitive keyword, SonarCloud cpp:S1669 on #318 (beta.24 PR-3)

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:16:32 +07:00
poli0981andClaude Opus 5.5 6d10b3092e fix: what SonarCloud found that was real - Explorer by full path and quoted, the action pinned, two string reads bounded, module renamed, three C# smells (beta.24 PR-2) (#317)
- App: one Services/Explorer helper starts %WINDIR%\explorer.exe by full path and
  always quotes the path (S4036; three of five call sites passed it bare). Tests.
- Workflows: ilammy/msvc-dev-cmd pinned to its v1.13.0 commit (S7637).
- Native: FlGuardRulesFilePath returns wcsnlen(out, cap); the NVAPI bridge
  measures the driver's branch name with strnlen over its buffer (S5813);
  `module` renamed in the hook inventory and dllmain (S1669, rename only, no
  code change); fl-probe-hookprofile drops compound assignment on a volatile
  (S6191, deprecated in C++20).
- PipeServer.RunAsync loops while not cancelled and ends cancelled (S2190);
  ProcessLauncher's unused static Start overload is removed (S3427); a launch's
  own session passes CancellationToken.None with its reason (S8949).
- 13_CI_CD §SonarCloud: the 17 accepted S5813 sites with why each string is
  terminated; S3869 accepted (no SafeHandle overload from CsWin32 here).
- Dependabot #314 (VS Threading Analyzers 18.12.1, Meziantou 3.0.307): the
  first-start view model's answer task (VSTHRD003) and one test fake's
  synchronous wait (VSTHRD002) are suppressed with their reasons; the whole
  solution builds with both the current and the bumped analyzers.

Gate: ./build.ps1 check ALL GATES PASSED (312 s); 32/32 native tests.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 10:26:32 +00:00
poli0981andClaude Opus 5.5 5b5dc11857 build(sonar): SonarCloud analyses only FrameLedger's own code - .sonarcloud.properties and the triage of the 341 issues (beta.24 PR-1) (#316)
Automatic Analysis reads .sonarcloud.properties from the default branch: the vendored SDK headers, generated files, the vendor stubs, tests/fixtures, licence texts, docs/vendor-exports.json and the SQLite migrations are excluded, and C++ is reported against C++20. docs/13_CI_CD.md §SonarCloud records the triage of the 341 issues of the 2026-09-28 analysis and the owner's steps. Owner decision D67.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 17:10:44 +07:00
poli0981andClaude Opus 5.5 0de7dc6b27 docs(handoff): owner-only item 19 passed; the fl_guard chip goes with the next pre-release; the library grid stays as it is (after 0.1.0-beta.23) (#313)
The 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ũ."

- HANDOFF, owner-only item 19 struck as items 16-18 were: Passed 2026-10-15, the item as
  written kept below the answer.
- HANDOFF, beta.23's section: "After the release" records the answer - the chip the
  release tree's local gate left (fl_guard's native-log test, red under load, known
  since beta.9; no native code changed in beta.23) goes with the next pre-release, and
  the library grid stays as it is (the beta.11 non-virtualizing UniformWrapPanel, 275 ms
  at 48 games); the decision bullet that left it to the owner points there.
- spike-notes section 21: the offer to virtualize the grid carries the owner's answer.

Documents only; no release - nothing a user runs changed.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 18:25:54 +00:00
poli0981andClaude Opus 5.5 4c07baadeb release: 0.1.0-beta.23 - the CHANGELOG section, release lines, HANDOFF's beta.23 section with D60-D61 and owner-only item 19 (beta.23 PR-5) (#312)
The [Unreleased] entries of #308-#311 move under [0.1.0-beta.23] with the release's
summary and how to update from beta.22: the Privacy Policy (2.11) is shown once, no game
is read again (detection rules 2026.10.4 unchanged), the artwork shows by itself for games
Steam or GOG GALAXY installed.

Release lines: legal/ACCURACY.md, README.md and legal/DISCLAIMER.md (the identical
accuracy line), README's list of pre-releases and its count (twenty-three), LIMITATIONS'
version line.

HANDOFF: beta.22's START HERE struck; beta.23's section with the owner's request, D60 (the
artwork is what is already on the PC; a chosen image's path is followed only when it is
ours, never through a link), D61 (the band's colour as far as every text reads), the bar
the pages' speed was judged by and what it left for the owner (the library grid's
virtualization), and the traps met; owner-only item 19 (the artwork on real Steam and GOG
games, the theme switch, choosing and dropping an image, the speed on WALTO's longest
session, Privacy 2.11 shown once, the ja strings).
Local gate: ALL GATES PASSED in 384 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 00:39:18 +07:00
poli0981andClaude Opus 5.5 c39d970be3 docs: the first real Vulkan game in the tested list, and four places that described what was never built or a count gone stale (beta.23 PR-4) (#311)
The owner asked for the documents to be brought up to date (2026-10-14) and approved,
under D35, a row from the ledger for the Vulkan game the agent's log showed on 2026-10-13.

- LIST_GAME_TESTED: Everhex Demo (Steam 5128880) - Presented 239.7 FPS, 1 % low 213.5,
  14,955 frames in 69 s through FrameLedger's Vulkan layer, started by Play set to
  Start directly; the figures re-read from a copy of the database made with SQLite's
  online backup (12_BUILD section Debugging). Its "no real Vulkan or OpenGL game has
  been measured" is struck and corrected, and LIMITATIONS says the same in a user's words.
- 15_ROADMAP P5: "eleven pre-releases through 0.1.0-beta.11" went stale at the next
  release; it points at the CHANGELOG now instead of holding a count.
- 08_UI, Settings as specified: "Privacy: online-metadata opt-in" is struck - the card
  has not been shown since 2026-09-16 and the built section below says so.
- 05_DETECTION: the "(opt-in) Steam appdetails lookup, cached 7 days" was never built;
  FrameLedger makes no store request, and beta.23's artwork (D60) is read from disk.
- CLAUDE.md, the solution layout: FrameLedger.Injector/ also builds
  FrameLedger.Guard.dll, the guard's C ABI the Agent loads.
- #310's own notes, which the code outgrew before it merged: 08_UI's note on the header's
  cover and 06_DATA_MODEL's cover_path comment now say a chosen image's path is never
  followed through a junction or a symbolic link; the band's colour is the cover's or
  else the banner's; PagesLoadTests.TheGamePagesArtworkIsDrawn and
  AccessibilityTests.NoStyleOfAWpfUiControlLeavesOutItsTemplate are named.

CHANGELOG [Unreleased] has one Changed entry. Local gate: ALL GATES PASSED in 312 s on
the first commit, and in 384 s on the release tree that holds both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 00:22:14 +07:00
poli0981andClaude Opus 5.5 fb0ee60fa0 feat(app): a game's page shows its artwork - your own image, else what the Steam or GOG GALAXY app keeps on this PC - in a band coloured from it (beta.23 PR-3) (#310)
The owner asked for a game's cover and hero art on its page, its colour optionally
carried into the page (2026-10-14), and chose: images already on the PC only, a banner
with a portrait cover, the colour on by default.

D60 - where the artwork comes from:
- The image the user chooses in Edit... > Choose image..., copied only once the dialog
  closed with Save (Cancel leaves nothing) as a PNG no larger than 1200 px a side, to
  the data folder's covers\game-<id>-<unix ms>.png - a new name for each choice, so a
  shown file is never written over - and named in games.cover_path relative to the data
  folder. A cover_path is followed only when it is one of those names, in that folder
  and never through a junction or a symbolic link: a viewer's copy of a ledger may come
  from anywhere, and a rooted, share (\\host\...) or .. path is never opened. "Use the
  store's image" deletes the copy, as removing a game with its sessions does; at start
  the App deletes the copies no row names (its own folder only, never a viewer's).
- Else what the store's app keeps: Steam's appcache\librarycache\<appid>\ (flat, or in
  hash-named folders - library_600x900[_2x], library_capsule, library_hero, header,
  library_header; the newest copy wins) and GOG GALAXY's webcache\<user>\gog\<id>\
  (WebP). Which store installed the game is asked of the stores' own records as Play
  asks (StoreRecords.Owning over Steam's and GOG's, kept two minutes), never of the
  row's platform alone; store ids are digits only. Epic's and itch's apps keep no image
  files.
- Found, decoded (no larger than the page needs, frozen, the twelve latest kept) and
  coloured on the thread pool: the page's text is there first. Nothing is downloaded; privacy.online_metadata
  stays reserved.

D61 - the band's colour: the artwork's dominant colour (a hue histogram of a 48 px copy,
greys and near-black or near-white skipped) over the card's fill, at the strongest
opacity - at most 30 % on the dark theme, 22 % on the light - at which every text the
header shows still reads: primary and secondary 4.5:1, tertiary 3:1, the pills' and the
warning's text 4.5:1 on their fills. Controls/ArtTint follows a theme switch through a
resource reference on the band (ApplicationThemeManager.Changed is raised by Apply
alone); no tint in high contrast; no text is ever drawn on a picture.

Settings > Games: "Show game artwork" (ui.game_art) and "Colour the game page from its
artwork" (ui.game_art_tint), both on. Strings in en, vi and ja (ja marked for review).

Caught in a render of the page before this commit: the cover's own Style was not based
on WPF UI's DefaultImageStyle, so the ui:Image had no template and drew nothing beside a
banner that drew. PagesLoadTests.TheGamePagesArtworkIsDrawn and
AccessibilityTests.NoStyleOfAWpfUiControlLeavesOutItsTemplate both ran red first;
16_WPFUI_SYNTAX's Gotchas list has it.

Docs: Privacy Policy 2.11 (section 1: the images you choose; section 4: the store apps'
images, and their records read when a game's page opens) with legal-drift-history,
TRADEMARKS, THIRD_PARTY_NOTICES, LIMITATIONS (Game artwork), 08_UI, 16_WPFUI_SYNTAX,
06_DATA_MODEL, 01_ARCHITECTURE, 02_SPEC FR-1.3, 05_DETECTION, 12_BUILD,
20_OPEN_QUESTIONS (Cover art closed), guide 05/07/08, wiki App-UI-development, CHANGELOG.

Tests: StoreArtCachesTests (both Steam layouts, the better cover and the newest copy,
ids of another shape, nothing there, several GOG users), ColorMathTests (agrees with the
tests' own WCAG; the hardest colours keep every pair readable in both themes),
GameArtTests (source order, a missing own image, the D59 owning rule, off in Settings
reads nothing, a cover_path not ours, a damaged file, records read once),
CoverStoreTests (a new name each choice, a non-image leaves nothing, tidying keeps a
removed row's image, deleting follows our names only, a covers junction is never
followed), EditGameViewModelTests, GameDetailViewModelTests, PagesLoadTests (the band
readable in both themes and through a switch; the edit dialog's image row; the artwork
drawn).
Local gate: ALL GATES PASSED in 282 s; the artwork classes 20 times green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 00:08:58 +07:00
poli0981andClaude Opus 5.5 fb313ebca6 perf(app): a game's page opens and changes session without freezing the window; a Dashboard or Logs visit no longer stays in memory (beta.23 PR-2) (#309)
The owner asked whether switching pages and tabs is slow (2026-10-14). Measured before
changing anything, with a pre-committed bar - fix what keeps the UI thread busy 50 ms or
more, can block on I/O, or grows with each visit - over the App's own pages in a real
window, Release, a ledger shaped like the owner's (docs/spike-notes.md section 21):

- Open a game with 100 sessions: 1,175-1,507 ms -> 369 ms. The Sessions grid sat in the
  page's own scroller with no height limit and built every row (17 columns each); it is
  bounded now (MaxHeight 520, as Compare's list is), builds the rows on screen, scrolls
  itself and hands the wheel to the page at its ends.
- Choose a 2,000,000-frame session: 843-1,016 ms freeze -> 17 ms. Microsoft.Data.Sqlite
  completes its async calls synchronously, so the blob read, the decode and the stutter
  detection ran on the UI thread whatever ConfigureAwait said; then the Distribution tab
  sorted every frame three times. SessionSeriesLoader reads and decodes on the thread
  pool, and Charts.SeriesDigest works out once, there, what the charts need from the
  whole session (one sort shared by the histogram, the percentile curve and its lows;
  the gap count; the presents line). The charts' public entry points are unchanged and
  compute for themselves on a series without a digest.
- A session ends after 20 Dashboard visits: 20 notices and 20 reloads -> one of each.
  DashboardViewModel and LogsViewModel were IDisposable transients the root container
  kept until exit; every Dashboard stayed subscribed. The Dashboard attaches on Loaded
  and detaches on Unloaded; neither is IDisposable; FR-3.8's in-App notice moves to
  Services.SessionNotices, one subscription for the App's life (it reached other pages
  only through the leak), kept by AgentConnectionHostedService like LiveSessions.

Also: the game page asks whether the .exe is on disk off the UI thread and no longer
reads a drive from a property getter; GameLibrary.LoadAsync stops summarising every
game's sessions for a field nothing read (GameDetail.Summary removed); the Logs tick
reads nothing when the newest file is unchanged and filters off the UI thread; Play
reads the stores' records on the thread pool (Services.StoreRecordsReader, which PR-3's
artwork reuses); at Debug the App logs how long each page took to appear.

Recorded, not fixed (spike-notes section 21): page builds of 600-2,500 visuals still cost
85-370 ms, and the library grid (275 ms at 48 games) is non-virtualizing by the beta.11
decision - a virtualizing one changes the page's look, the owner's call.

Docs: 08_UI (the game page's costs; FR-3.8's snackbar corrected in place), 16_WPFUI_SYNTAX
Gotchas (synchronous SQLite; no IDisposable transient view models), wiki
App-UI-development, spike-notes section 21, CHANGELOG.

Tests: SeriesDigestTests (sorted forms equal the charts' own; the digest of a decoded
series; the read happens off the caller's thread), DashboardViewModelTests (an
off-screen Dashboard hears nothing, one notice per session, a hidden window leaves the
notice to the tray), GameDetailViewModelTests (the executable is looked for off the
opener's thread), LogsViewModelTests (a tick re-reads only a changed file),
PagesLoadTests (the Sessions grid builds the rows on screen and hands the wheel on).
Local gate: ALL GATES PASSED in 355 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 23:24:36 +07:00
poli0981andClaude Opus 5.5 2982679fc1 test(native): the ring's concurrency cases guard on drains that overlapped the writer, repeated until one attempt did - not on a share of the stream (beta.23 PR-1) (#308)
The owner (2026-10-13, after beta.22): "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é" -
every owner-only item passed; take the chip beta.22's local gate left.

The chip: ring_test.cpp's "SPSC under a hammering writer" made a full local
gate red on a tree that touched no native code. Its anti-vacuity guard,
CHECK(accepted > kTotal / 2), failed 5 of 40 runs and then 5 of 200 of
fl_ring_test.exe on the owner's hybrid i7-14700KF - accepted 1024, 6747,
21370, 45028, 61596 - with CHECK_FALSE(mixed) clean every time. A share of
the stream measures 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. docs/HANDOFF.md's trap already said to read which assertion fired.

Measured on the way, which is why it is not one line:
- a start barrier alone (the writer starts once the reader is about to loop)
  left 1 of 200: a reader the OS did not run while the writer wrote - one
  overlapping drain, accepted 2048. No single run can rule that out.
- the tiny ring's guard, CHECK(dropped > 0), passed a reader made to wait for
  the writer to finish (1.6 million drops over eight attempts): it could not
  tell a run without overlap from one with it.

Both cases now: the start barrier; a count of the drains that copied records
while the writer was still writing; and the run repeated - every attempt
checked for its properties (mixed, poisonAccepted) - until one attempt made
100 such drains, at most 8 times; the guard is that count. The tiny ring also
keeps dropped > 0, for the attempt that overlapped (the last), no longer a sum
a vacuous attempt could fill. The property checks are unchanged.

Measured: 1,000 runs, no failure, at most 3 attempts, the best attempt at
least 122 overlapping drains (median 146,981); a reader made to wait for the
writer fails both guards in every run (most overlapped drains 0 after 8
attempts). clang-format clean.

Docs: HANDOFF's native-test trap amended (both guards, the rates, the fix);
owner-only items 16, 17 and 18 struck as passed; beta.22's section says what
followed the release. CHANGELOG [Unreleased], developers only. No release:
nothing a user runs changed.

Gate: ./build.ps1 ALL GATES PASSED (309 s). The owner's live rules files were
pre-seeded and restored byte for byte.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 23:36:42 +07:00
poli0981andClaude Opus 5.5 76e89b65de release: 0.1.0-beta.22 - the CHANGELOG section, release lines, HANDOFF's beta.22 section and owner-only item 18 (beta.22 PR-2) (#307)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-13, 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 from beta.21's review of Play as its own PR
(#306) and its own pre-release.

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.22] - 2026-10-13, with its
  summary and "Updating from 0.1.0-beta.21" (nothing to accept and no game
  read again: the legal documents and rules 2026.10.4 are beta.21's);
  tools/release-notes.ps1 -Version 0.1.0-beta.22 extracts it (1,161
  characters).
- The accuracy block's release line (legal/ACCURACY.md, embedded in README
  and the Disclaimer; its date stays 2026-10-13, nothing in it changed),
  README's release lines and count ("Twenty-two"), LIMITATIONS' version.
- HANDOFF: beta.21's START HERE struck; the beta.22 section - the owner's
  words, no new decision, the traps (VSTHRD003 and a Func<Task<T>>;
  ObjectDisposedException is an InvalidOperationException); owner-only item
  18 (the ja string; nothing else a person can run on purpose).

Gates run locally on this tree: accuracy-check, wiki-check (27 pages),
notice-check, release-notes. The code is #306's, whose tree passed
./build.ps1 (291 s) and CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 21:58:43 +07:00
poli0981andClaude Opus 5.5 712146685f fix(app): a request the capture agent never answered is said in words and the page reads what is stored - never a crash dialog or an exception's name (beta.22 PR-1) (#306)
The owner (2026-10-13, during beta.21): "make the chip a new PR after the
release, and a new version". The chip came from beta.21's review of Play
(#304): when the pipe closes, PipeClient fails a request in flight with what
ended its reader - an IOException, an IpcFramingException or an
ObjectDisposedException - and a client AgentConnection disposed between its
check and the write throws the last.

What each caller did, read in the code:
- SessionDeletion caught no IOException: deleting sessions while the agent
  stopped or restarted for an update ended in the App's crash dialog (an
  exception out of a command); a timeout showed its own message.
- HookingConsent and AntiCheatExceptions caught IOException and
  TimeoutException as Failed with the exception's type name as the detail:
  the game page's notice read "IOException".
- Every caller missed IpcFramingException and ObjectDisposedException.
- GamePlayer (beta.21) caught them all and said "the agent is not running",
  which is untrue when the launch may have run.

Changes:
- AgentConnection.RequestAsync answers through AnsweredAsync: an
  IpcFramingException or ObjectDisposedException becomes ONE IOException
  ("the connection to the Agent closed before it answered", the original as
  its inner exception). IAgentRequests names the four ways a request fails.
  RefreshStatusAsync also catches IpcFramingException.
- AgentAnswers.IsUnanswered (IOException or TimeoutException): whether the
  request was carried out is not known.
- SessionDeletion, HookingConsent, AntiCheatExceptions and GamePlayer tell
  the three apart: InvalidOperationException = not connected, nothing was
  sent (AgentUnavailable, in their existing words); unanswered = a new
  Unanswered outcome, said with one new string, Agent_Unanswered (en/vi/ja,
  ja marked review); IpcRequestException as before. An unanswered delete
  also lets go of what named a deleted session (it may have run), and an
  ack without its counts is unanswered too. The game page reads what is
  stored after an unanswered delete, and Settings re-reads its hooked games
  after an unanswered revoke; the consent and exception paths already
  re-read the page.
- 07_IPC section Client behavior; CHANGELOG.

Tests: AgentConnectionTests.EveryWayThePipeClosesUnderARequestIsOneIOException;
SessionDeletionAndOverviewTests.ADeleteTheAgentNeverAnsweredIsSaidAsNotKnownAndThePageReadsWhatIsStored
(a delete that ran and lost its answer: the page empties and the selection
lets go); HookingConsentTests.AnAskTheAgentNeverAnsweredIsNotKnownAndOneNeverSentIsNoAgent;
AntiCheatExceptionsTests.AnAskTheAgentNeverAnsweredIsNotKnownAndSaidInWords;
GamePlayerTests.AnAnswerThatNeverCameIsNotKnownAndARequestNeverSentIsNotRunning
(replaces beta.21's "not running").

Gate: ./build.ps1 ALL GATES PASSED (291 s); App 619. The owner's live rules
files were pre-seeded and restored byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 21:43:02 +07:00
poli0981andClaude Opus 5.5 86dffa660f release: 0.1.0-beta.21 - the CHANGELOG section, release lines, HANDOFF's beta.21 section with D57-D59 and owner-only item 17, the Wuthering Waves row of LIST_GAME_TESTED (beta.21 PR-5) (#305)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-13), with the
plan: "Làm trọn mạch ngay" - commit, push, CI, auto-fix, merge, bump the
version and release in one go. The release carries #301 (check 4 also walks
the executable's folder; Wuthering Waves on the title list; rules 2026.10.4),
#302 (the four itch "launchers" are malware - the docs corrected, D57; the
Supports card), #303 (the documents' wheel; one render per page) and #304
(Play, D59; Privacy Policy 2.10).

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.21] - 2026-10-13, with its
  summary and "Updating from 0.1.0-beta.20" (Privacy 2.10 shown once; every
  game read and checked for anti-cheat once more under rules 2026.10.4, and
  Wuthering Waves and any game with an anti-cheat beside its executable turned
  off; the four itch downloads pointed at Security); the subsections in Keep a
  Changelog's order (Added, Changed, Fixed, Security); #302's Supports card
  fix, which had no entry, added under Fixed. tools/release-notes.ps1 -Version
  0.1.0-beta.21 extracts it (5,147 characters).
- The accuracy block (legal/ACCURACY.md, embedded in README and the
  Disclaimer): its date moves to 2026-10-13 - #304 changed its Vulkan
  sentence, and the block asks to be dated when it changes - and its release
  line; README's release lines and count ("Twenty-one"); LIMITATIONS' version.
- HANDOFF: beta.20's START HERE struck; the beta.21 section - the owner's
  list, D57-D59, the train, the traps (the pre-scan's depth limit is a reach
  and not a refusal; a long rules note fails rules-validate with a message
  about something else; the owner's older live rules make parallel test hosts
  race; WPF's fixed 48 DIP wheel step; the review of Play after green gates
  that found four defects, fixed in #304, and SessionDeletion's same gap,
  which the owner asked for as its own PR and beta.22; the analyzers met); owner-only item 17
  (Wuthering Waves blocked before any session, NTE and GF2's exception
  unchanged; Play in both modes with a Steam, an Epic, a GOG and an itch game,
  never elevated; the wheel and a touchpad; Privacy 2.10 once; the ja strings).
- docs/LIST_GAME_TESTED.md: the Wuthering Waves row in the anti-cheat table -
  hooked 37 s on 2026-10-12 before the 30 s re-check met ACE's driver, refused
  before any injection since beta.21 - marked as added 2026-10-13 from the
  agent's log (approved with the plan, D35).

Gates run locally on this tree: accuracy-check (self-test and live),
notice-check, wiki-check (self-test and 27 pages), changelog-check and
release-notes (self-tests), release-notes -Version 0.1.0-beta.21. The code is
#304's, whose tree passed ./build.ps1 (292 s) and CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 21:24:12 +07:00
poli0981andClaude Opus 5.5 81e95c5a72 feat(app): Play - through the store that installed the game, or started directly by the agent, switched in Settings > Games (D59); Privacy Policy 2.10 (beta.21 PR-4) (#304)
The owner's request of 2026-10-13: "a play button on a game's page (or in the
list) that points to the platform to play". Asked with the plan, the owner
answered (D59): "1: press Play -> the platform opens -> it runs; 3: it runs at
once; let me switch between the two".

Play heads a game's page (Primary, before Edit...) 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,
App-owned, the Agent never reads it):

- Through the store (default): the store that installed the game is the one
  whose own records name the folder its executable is in - the records the
  import reads (IStoreLibrarySource), deepest folder first, then the entry's
  own store id (StoreRecords). The row's platform is not trusted: detection
  rewrites it (an itch build shipping steam_api reads as Steam) while
  store_id stays the importer's, and a Steam link built from an itch id would
  start another game. The hand-off is each store's own form (StoreLaunches),
  measured read-only on the owner's PC:
  - Steam: steam://rungameid/<appid> (the link of Steam's 20 game shortcuts);
  - Epic: com.epicgames.launcher://apps/<ns>%3A<item>%3A<app>?action=launch&silent=true
    (the launcher's shortcut form; UNMEASURED - no Epic shortcut on the PC),
    or the AppName alone where the manifest names no catalog
    (EpicLibrarySource now reads CatalogNamespace/CatalogItemId into
    StoreGame.LaunchKey);
  - GOG: GalaxyClient.exe /command=runGame /gameId=<id> /path="<folder>"
    (GALAXY's own game shortcut), GALAXY's path from GOG's registry
    (GogGalaxyLocator);
  - itch: itch://install?game_id=<id>&launch (the itch app 26.22.0, read
    from its bundle, asks which copy to launch).
  Every id is checked against its store's shape before the shell gets it.
  No store, GOG without GALAXY, or the App itself running as administrator
  (a store app it started would be elevated, and so would the game): the
  agent starts it instead, and the notice says why.
- Start directly: the App sends LaunchGame (the pipe command existed since P3
  PR-1b with no caller): launch mode, recorded from the first frame, never
  elevated (UnelevatedProcess), hooked only where the gate allows, refused
  for a recording-off entry; agent unavailable / recording off / already
  running / failed each have their own notice, and a launch Windows refuses
  (740: the game requires administrator) ends as the existing notice.

GamePlayer (App) does both; IShellStarter is ShellStarter in the profile and
ViewerShellStarter in a viewer (D52), where every Play button is also off
(ActsOnThisPc). Strings en/vi/ja (ja marked review).

Privacy Policy 2.10 (the wording approved with the plan): section 4 names the
lists of installed games the Steam, GOG GALAXY, Epic Games and itch apps keep,
and where GOG GALAXY is installed, read at import and at Play - the import read
Epic's and itch's lists before without a word; section 2 says Play hands a
game to its store's app, which may connect to its store, while FrameLedger
connects to nothing. legal-drift-history says what 2.10 changed.

Docs: 02_SPEC FR-1.9 (and FR-3.2's caller), 04_CAPTURE and 07_IPC (LaunchGame
has a caller), 06_DATA_MODEL (ui.play_mode; capture.background stays
reserved), 08_UI section Games, the guide's screens and settings pages (and
its Vulkan layer row), LIMITATIONS (a Play section; Vulkan games through Play),
the accuracy block's Vulkan sentence in its three copies, the SettingsRegistry
note on capture.background, CHANGELOG.

Tests: StoreLaunchesTests (each store's form, ids of the wrong shape build
nothing, a GOG folder that cannot stand in quotes), StoreRecordsTests
(deepest folder, prefix trap, the entry's store id among equals, an itch
build that ships Steam's API), GamePlayerTests (every branch, the notices),
StoreLibrarySourcesTests (Epic's launch key, GOG GALAXY's locator against an
HKCU key), ViewerModeTests (the page's and the library's Play off in a
viewer; ShellStarter only in the profile).

Review before the merge, after the first CI run was green (the beta.19
lesson): a pipe that closes while LaunchGame is in flight fails it with an
IOException, ObjectDisposedException or IpcFramingException (PipeClient), and
none was caught - 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; each is now "the capture agent is not running". A store record whose
id builds no link read "GOG GALAXY is not installed" (PlayFallback.NoLink,
logged); the agent's UnknownGame reached a notice as the token
(PlayOutcome.NotInLibrary); two notices advised what their path could not do
(Play_RecordingOff_Fallback_Format; Play_AgentUnavailable_Format reworded,
en/vi/ja). SessionDeletion's same gap is left as a task of its own. Tests:
AConnectionThatGoesMidRequestIsTheAgentNotRunningNeverAnException,
EachNoticeIsTrueOnThePathItIsSaidOn.

Gate: ./build.ps1 ALL GATES PASSED on both commits (281 s, then 292 s);
Application 522, App 615. The owner's live rules files were pre-seeded
and restored byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 21:10:11 +07:00
poli0981andClaude Opus 5.5 babd500ec3 perf(app): the documents scroll by Windows' lines and glide, and a page is rendered once - MarkdownView handles the wheel and renders ahead of layout (beta.21 PR-3) (#303)
The owner's request of 2026-10-13: scrolling the documents in the app is slow.
Measured first (rendering every embedded document in memory): layout costs
about 1 ms per wheel step, so drawing was not it. Two things were:

- WPF's ScrollViewer moves a FIXED 48 DIP per wheel message, whatever its
  delta (ScrollViewer._mouseWheelDelta; deltas of -1, -15, -120 and -360 each
  moved 48 on a FlowDocumentScrollViewer): about 2.4 lines of body text,
  Windows' "lines to scroll" ignored, a touchpad's small deltas each jumping
  the whole step - LICENSE took about 200 notches to the end.
- Each of MarkdownView's three properties rendered the whole document on its
  own: DocumentBrowser.ShowPage rendered the old text under the new path first,
  the Legal Gate's three bindings rendered three times, and nothing was kept.

Changed:

- MarkdownView handles PreviewMouseWheel itself: the delta in proportion, at
  Windows' lines per notch at a browser's line (100/3 DIP; three lines = 100,
  scaled by the zoom; -1 = a screen), eased there over about 120 ms through
  CompositionTarget.Rendering unless Windows' animations are off; a notch
  turned while easing adds to the target; something else moving the view, a
  new page or Unloaded ends the easing. At either end the wheel is left
  unhandled, so the update notes' dialog scrolls instead; Ctrl+wheel stays the
  zoom. The keyboard modifiers and the lines setting are injectable, as
  ChartWheel's are.
- One render per page: MarkdownView.Show sets the three properties and renders
  once, now (DocumentBrowser uses it); property changes post one render at
  DataBind priority, ahead of layout; Anchors and ScrollTo render what is
  pending first. A view keeps the last 16 documents it rendered (path, plain,
  text), so going back to a page costs its layout only.
- The table renderer's TableColumn Width = GridLength.Auto is gone: it is
  WPF's default.
- The ui log and --diag name WPF's render tier (0 = software rendering, where
  every scroll is drawn on the CPU).

Tests: MarkdownViewTests - the step's arithmetic; on a real view, one notch
moves 100 DIP and a delta of 15 an eighth of that, the end leaves the wheel to
the host, Ctrl leaves it to the zoom; easing adds notches to the target and a
new page stops it; Show renders once, a page shown before is not rendered
again, past 16 the oldest is; properties set one by one render once, after the
dispatcher runs. DiagReportTests: render_tier. Docs: 08_UI (rendered
documents), 16_WPFUI_SYNTAX (the 48 DIP trap), CHANGELOG.

Gate: ./build.ps1 ALL GATES PASSED (272 s); App tests 605; MarkdownViewTests
looped 5x green. The owner's live rules files were pre-seeded with the
repository's for the run and restored byte for byte after (a test run with
their older file in place raced two seeders on one replace -
AgentReadOnlyVerbsTests: "could not write the rules file").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 20:22:59 +07:00
poli0981andClaude Opus 5.5 df113c0888 fix: the four itch "launchers" are malware - the docs say so and stop advising to run one (D57); the Supports card says what a scan found (beta.21 PR-2) (#302)
The owner's report of 2026-10-13 ("the RPG Maker path is wrong" for HELLO,
HELLO WORLD!) led to the files behind it. Read without running anything
(spike-notes section 20): the 213 MB .NET program HELLO, HELLO WORLD!, A
Doll's Locket - Remake, City of Bones and Traumerei Chapter 2 put in front of
their RPG Maker game is not a launcher. Beside each sits a byte-identical
3,060-byte registry file that sets AmsiEnable=0 (HKCU and HKLM) and adds
Microsoft Defender exclusions for .exe, .msi, powershell.exe, rundll32.exe,
msiexec.exe and regasm.exe, plus SpyNet off, and a 3,216-byte encrypted
".xml"; the program's metadata names VM and debugger checks, AES decryption,
an in-process PowerShell runspace and RunPayload/PayloadStep steps, and it
starts the RPG Maker runtime beside it - the decoy. SHA-256 of all four in
spike-notes section 20.

Owner decision D57 (asked, 2026-10-13): correct the documentation; the import
keeps taking a store's own pick when it is not a helper.

- docs/spike-notes.md: section 17's "front their runtime with a 213 MB .NET
  launcher" struck and corrected; new section 20 with what the files are.
- docs/05_DETECTION.md: the beta.19 note's rationale annotated, its "measured
  with the admin mode on (D34)" sentence struck; the RPG Maker paragraph's
  examples annotated.
- docs/HANDOFF.md: D28, D56 ("the locator now picks the same file" - not for
  HHW's import: itch's verdict names the program in front, which is not a
  helper) and owner-only item 15(a) (do not run Doll's Locket's launcher).
- CHANGELOG: a Security entry under [Unreleased]; the beta.19 entry's admin
  advice marked withdrawn.
- docs/LIST_GAME_TESTED.md: the HELLO, HELLO WORLD! row says its download is
  malware (approved with the plan, D35).
- LIMITATIONS.md: FrameLedger does not tell whether a game is safe to run.

The repository states only what the files are; nothing here was run,
decrypted or uploaded.

Also fixed, from the same screenshot: the game page's Supports card read "Not
scanned yet" for every game that ships none of the capability files, even
beside a Details card the sweep had read. It now says that until the sweep has
read the executable (ExeMachine set), then "None found" (new string
GameDetail_Supports_None, en/vi/ja - ja marked review). Test:
TheSupportsCardSaysNotScannedOnlyUntilTheSweepHasReadTheExecutable. 08_UI
says the same.

Gate: ./build.ps1 ALL GATES PASSED (301 s); App tests 600. The owner's live
rules files were copied aside and restored byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 20:07:05 +07:00
poli0981andClaude Opus 5.5 1070cd303f fix(guard): an anti-cheat beside the executable is found before anything is injected - check 4 walks the executable's own folder too; rules 2026.10.4 (beta.21 PR-1) (#301)
The owner's report of 2026-10-13: no anti-cheat found in Wuthering Waves
(Steam 3513350). Measured read-only on the owner's disk and in the Agent's log
(spike-notes section 19):

- The install root holds a launcher, Client\ and Engine\; the entry is
  Client\Binaries\Win64\Client-Win64-Shipping.exe, and Tencent's ACE sits
  beside it in Client\Binaries\Win64\AntiCheatExpert\ (ACE-BASE.sys,
  ACE-CORE.sys, ACE-Base64.dll, ACE-Service64.exe, ACE-Setup64.exe) - four
  levels under the root.
- Check 4 walked the install root only (ResolveInstallRoot, since
  2026-09-25), and WalkDir opens folders only while depth + 1 <
  kMaxPreScanDepth (3): a folder at the last level is named and never opened,
  SILENTLY - the walk reports kOk. The rules already named the folder; the
  walk never handed it to the matcher. The library pre-scan read the game
  clean three times, and the session of 2026-10-12 was hooked for 37 s until
  the 30 s re-scan met ACE-BASE.sys - a machine-wide finding, which turned
  nothing off.

Fixed:

- Check 4 walks the install root, then - when the executable lives below it -
  the executable's own folder (ScanGameFolders): same walk, same reach, its
  own 4096-entry budget, same matcher, same D33 tolerance and finding record.
  Sources::ImageDirectory names the executable's folder and the checks
  resolve the root from it (CheckStaticPreScan, CheckBlockedStoreId). Raising
  the reach was measured and rejected (spike-notes section 19): depth 4 still
  misses NTE's AntiCheatExpert\ (six levels down), depth 5 overruns 4096
  entries on three installed titles, which would refuse them. Across the
  owner's 83 Steam installs the second walk costs at most 103 entries and
  newly finds exactly those two folders.
- Rules 2026.10.4 (the bump is also what makes every game's pre-scan run
  again - the sweep re-scans only on a rules version or executable change):
  the five ACE-* files, ACE-CORE.sys (drivers), the ACE-BASE service, a
  modules row of its own for ACE-Base64.dll appended at the end (the
  Overlay's early-stop index), and Wuthering Waves' Steam id on the title
  list (owner decision D58). Notes within the schema's 300 characters.
- Comments that said the depth cap refuses (fl_prescan.h, guard_test.cpp)
  and docs that said so (19_SAFETY item 4, 05_DETECTION) are corrected in
  place; CLAUDE.md's D33 ".sys anywhere in the install tree" now says what
  check 4 reaches.

Tests: the fake lists a folder per directory and records every directory
check 4 walks; Wuthering Waves' layout refuses from the path and from the
pid; an executable at its root is walked once; an unfinished walk of the
executable's folder refuses; D33's tolerance and the .sys rule hold in the
second walk; and two REAL-filesystem cases - the real walk names Win64 from
the root and never opens it, the pre-scan over the real walk and store seam
finds AntiCheatExpert\ beside a nested executable and passes the same tree
without it; the real ImageDirectory names the executable's own folder.

Before/after on the owner's disk, read-only (FlStaticPreScanGame): the
installed beta.20 guard answers Allow for Wuthering Waves; this build answers
BlockedStoreId Anti-Cheat Expert. NTE, GF2 (NEP2.dll) and nine other Unreal
installs read as before.

Gate: ./build.ps1 ALL GATES PASSED (296 s); native 32/32. The owner's live
rules files were copied aside before the run and restored byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 19:51:38 +07:00
dependabot[bot]andpoli0981 f8ecc19371 Bump the minor-and-patch group with 1 update (#291)
Bumps Meziantou.Analyzer from 3.0.294 to 3.0.299

---
updated-dependencies:
- dependency-name: Meziantou.Analyzer
  dependency-version: 3.0.299
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: poli0981 <127664709+poli0981@users.noreply.github.com>
2026-10-12 13:17:25 +00:00
poli0981andClaude Opus 5.5 57a428846e release: 0.1.0-beta.20 - the CHANGELOG section, release lines, HANDOFF's beta.20 section and owner-only item 16 (beta.20 PR-2) (#300)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-12, the
same evening as beta.19): "tung bản beta20 rồi đóng phiên hẳn". The release
carries #299: a Ren'Py game's engine version from the engine's own
renpy/vc_version.py (rules 2026.10.3, Privacy Policy 2.9).

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.20] - 2026-10-12, with its
  summary and "Updating from 0.1.0-beta.19" (Privacy 2.9 shown once; every
  game read again for its engine); tools/release-notes.ps1 -Version
  0.1.0-beta.20 extracts it (957 characters).
- The accuracy block's release line (legal/ACCURACY.md, embedded in README
  and the Disclaimer; accuracy-check green), README's release lines and
  count, LIMITATIONS' version.
- HANDOFF: beta.19's START HERE struck; the beta.20 section - the owner's
  two words, no new decision (the 2.9 wording was shown with #299), the
  traps (keyboxd's I/O error, the owner's live rules copied aside and back,
  looping a touched test class); owner-only item 16 (Bound Between Desks
  reads Ren'Py 8.5.0; Privacy 2.9 once; the ja string).

Gates run locally on this tree: accuracy-check, wiki-check (self-test and
27 pages), notice-check, test-artifacts, release-notes. The code is #299's,
whose tree passed ./build.ps1 (325 s) and CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 19:12:26 +07:00
poli0981andClaude Opus 5.5 4ae563c97e feat(detection): the engine version of Ren'Py games, read from the engine's own version file (beta.20 PR-1) (#299)
The owner asked (2026-10-12, after beta.19's Unity, Godot and RPG Maker
versions) for the version of Ren'Py games. The renpy rule had no version
extractor.

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 read-only on the
owner's one Ren'Py install, Bound Between Desks (Steam): 109 bytes, the
same number the game's log.txt printed at its last start; the launcher has
no version resource (spike-notes §18).

- Rules 2026.10.3: renpy -> {"type": "renpy_build"}; the schema's enum of
  code-decided extractors gains it. Every entry is read again once.
- Domain: RenPyBuildFacts + RenPyVersion.Decide keep MAJOR.MINOR.PATCH,
  as Ren'Py names its releases (the fourth number is the build), source
  renpy_vc_version; VersionExtractorType.RenPyBuild; the evaluator leaves
  it to the detector, as the other code-decided types.
- Application: IGameFileProbe.ReadRenPyBuildAsync; StaticGameDetector
  makes the one second read for a Ren'Py match.
- Infrastructure: RenPyBuildReader reads the first 4 KiB of
  renpy/vc_version.py beside the executable, its version line only.
- App: the game page says "Ren'Py 8.5.0" and that it was read from the
  engine's version file (en/vi/ja, ja marked review); a Ren'Py row whose
  file names no version says "Not found in the game's files".
- Privacy Policy 2.9: §4's list of the version marks an engine keeps in
  its own files names Ren'Py's (legal-drift-history). The Legal Gate shows
  it once at the next update.
- The accuracy block (ACCURACY, README, DISCLAIMER), LIMITATIONS,
  05_DETECTION §Engine version - Ren'Py, 06_DATA_MODEL, 08_UI, CHANGELOG.
- HANDOFF: owner-only item 15 struck, passed 2026-10-12 (the owner's
  report, and the Agent's log for the removal: one check at 18:04:00 took
  three session-less entries); the rules-reseed trap gains the backup the
  session made of the owner's two rules files.

Through the shipped pipeline (StaticGameDetector over GameFileProbe, read
only): Bound Between Desks renpy 8.5.0 renpy_vc_version in 79 ms; Dialoop,
Plethora of Bullets 2, A Doll's Locket and City of Bones read as before.

Tests: RenPyVersionTests (the measured value; the build dropped; shapes
that are not a version), EngineBuildReadersTests (the measured file beside
the launcher; no file, a version_name only, past the bounded head),
StaticGameDetectorTests (one read for the matched engine),
GameDetailViewModelTests and FormatsTests (the page's words).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 18:41:13 +07:00
poli0981andClaude Opus 5.5 3e9028c139 release: 0.1.0-beta.19 - the CHANGELOG section, release lines, HANDOFF's beta.19 section and owner-only item 15 (beta.19 PR-5) (#296)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-12) asked for
four items; the train is #292 (the import never takes a helper; D56), #293
(Change executable... opens in the game's folder), #294 (Unity, Godot and RPG
Maker versions; rules 2026.10.2; Privacy Policy 2.8) and #295 (an uninstalled
game with no session leaves the library; D55), then the two follow-ups of
#295's review the owner asked for as separate PRs: #297 (one notice per check;
the Games page shows its newest read) and #298 (the presence probe's
unreadable-folder tests).

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.19] - 2026-10-12, with its summary
  and "Updating from 0.1.0-beta.18" (Privacy 2.8 shown once; every game read
  again for its engine; the removal switch to turn off first if wanted; an
  entry made for a helper is re-pointed by hand); tools/release-notes.ps1
  -Version 0.1.0-beta.19 extracts it.
- The accuracy block's release line (legal/ACCURACY.md, embedded in README and
  the Disclaimer; accuracy-check green), README's release lines and count,
  LIMITATIONS' version.
- HANDOFF: beta.18's START HERE struck; the beta.19 section - D55, D56, the
  existing entry not rewritten, the owner's two train instructions; the traps
  (a store's own pick can be a helper, substring helpers never overrule a
  store, Godot's string past the scan and Unity's FileVersion string, Exists
  answering false for what it may not see, the locked signing key, the
  mechanical ones, what the pre-merge review of #295 found, looping a touched
  test class, the rules reseed); owner-only item 15.

Release rehearsal: release.yml dispatched on the branch (run 38226132220)
green - FL_BUILD_ID from the clean checkout, buildid-check ok over 4 native
binaries, a 2.35 MB delta from 0.1.0-beta.18 (28 of 460 files patched).
The final tree passed ./build.ps1 (ALL GATES PASSED in 284 s).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 17:13:55 +07:00
poli0981andClaude Opus 5.5 59e8ea4967 test(infrastructure): a game folder Windows will not list is never gone (beta.19 PR-7) (#298)
The presence probe (#295, D55) decides whether an entry's executable is
gone — FileGone, the one answer that lets the Agent remove the entry — or
merely unreadable. File.Exists and Directory.Exists say false for what
they may not look at, so the probe asks listings: the file in its folder's,
a folder that reads as missing in its parent's, and a listing it is refused
is Unknown. The review of #295 found those two branches untested.

ExecutablePresenceProbeTests now denies the current user rights on real
folders and gives them back in a finally (the owner can always change the
access list):

- ListDirectory denied on the game folder: the executable there and a
  Gone.exe there are both Unknown, and Present again once it lists;
- ListDirectory + ReadAttributes denied on the game folder and
  ListDirectory on the library folder it is in: Directory.Exists says false
  for the game folder, and the probe still says Unknown.

Each skips (Assert.SkipUnless) when the process can list what it is denied
— a backup privilege enabled — rather than asserting something else.

Measured red on this machine: with the folder listing replaced by
File.Exists the first test fails (Present for a folder that will not list);
with the parent-listing check dropped the second fails with FileGone, the
answer that would have removed an installed game. Both restored.

FR-1.8 (02_SPEC) names the case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 17:03:21 +07:00
poli0981andClaude Opus 5.5 89aae82432 fix(app): one check's removals are said once, after one read of the library (beta.19 PR-6) (#297)
The Agent removes an uninstalled, session-less entry by itself since this
train (D55), and says each removal in its own GameRemoved event. One check
that removes several sends them milliseconds apart, and the Games page on
screen showed a snackbar and started a full library read for each. WPF UI
4.3.0's SnackbarService keeps one snackbar and shows every message at once
in it (Show(true) -> SnackbarPresenter.ImmediatelyDisplay, read from the
4.3.0 assembly), so only the last name stayed on screen.

The page now waits GamesViewModel.RemovalSettle (one second, over an
injected TimeProvider) after the first removal for the rest of the check,
reads the library once and says them in one notice: the game's name as
before, or the count, five names and how many more
(Games_Removed_Many_Format, Games_Removed_More_Format; en/vi/ja, ja marked
review). A removal heard during the read starts the next notice. The game
page's own handling of its entry is unchanged.

Tests: GamesViewModelTests — the single removal waits, then says the one
name; three removals in one check make one wait, one notice naming all
three and the remaining card; six name five and "1 more". Both over a
clock whose timers fire when the test says so.

Docs: 08_UI §Games; CHANGELOG's D55 entry.

fix(app): the Games page shows its newest read of the library (beta.19 PR-6)

Reads of the library overlap - a session that ends, an import, a removal -
and each awaits its executable checks off the UI thread. The read that
started first could finish last, its checks waiting on a slow drive, and
its older list was shown over the newer one: after the Agent removed a
game, an overlapping older read put the removed game's card back until the
next read.

Found by running GamesViewModelTests in a loop while the release train was
gated: one local run in about 165 failed. The pre-existing
ACardSaysWhetherItsExecutableIsThereAndWhy starts its own two reads (the
constructor's and an explicit one), and the first could be applied last.

GamesViewModel.LoadAsync now numbers each read (Interlocked) and shows it
only if no newer read began meanwhile. The executable check is injectable
(Func<string, bool>, default GameLibrary.ExecutableExists) so a test can
hold one read's check.

Tests:
- GamesViewModelTests.AnOlderReadThatFinishesLastIsNotShownOverANewerOne
  holds the first read in its check (bounded waits, so a broken test
  fails rather than hangs), lets a newer read list two games, then lets
  the first finish. It goes red without the guard ("found 1").
- ACardSaysWhetherItsExecutableIsThereAndWhy awaits the page's first read
  before adding the games it lists.

Measured: 10 runs of the class green and the whole App suite 599/599.

Docs: 08_UI §Games; CHANGELOG Fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 16:49:59 +07:00
poli0981andClaude Opus 5.5 c1a9e16cc4 feat(agent): a game that is no longer installed and has no session leaves the library by itself (beta.19 PR-4, D55) (#295)
The owner asked (2026-10-12) whether the Agent removes games whose executable
is gone, and if not, to remove them when no session was recorded. It did not:
D41 (2026-10-03) marked them Not installed and removed nothing. Owner decision
D55 amends it: removed after ten minutes, behind a Settings switch on by
default.

- UninstalledEntryPrune (Application/Watch), asked by DetectionSweep about an
  entry whose executable stayed unreadable after the relocator: the file gone
  at sweeps >= 10 minutes apart at the same path (counted in memory - a restart
  only delays it), the switch on (retention.remove_uninstalled_games, read at
  every sweep), not recording and no .partial waiting (the merge's busy test),
  and no anti-cheat block, exception grant or failed-trial mark (rule 2 and
  D38: an uninstall must not be how a block or "never again" disappears).
- ExecutablePresenceProbe tells what ExecutableIdentity.Read's null runs
  together: a drive not connected, nothing left of the path but the drive's
  root (a different disk under the same letter), a folder Windows will not list
  (asked of the parent's listing, since Exists answers false for both) - and
  FileGone, the only answer that removes: the file gone from a folder that is
  still there, or the game's folder gone from one that is.
- SqliteGamePrune: one DELETE that holds every stored condition in the same
  statement - same row, same path, in the library, NOT EXISTS a session, no
  block, no grant, no trial mark - so a session finalized meanwhile wins.
- IPC GameRemoved (additive): the Games page on screen reloads and says why in
  the snackbar; a game page showing that entry reloads into its not-found state.
- Settings > Data > Remove uninstalled games (off in a viewer like every
  Agent-read setting; its strip says the Agent reads it within 15 seconds).
  Strings en/vi/ja (ja marked review).
- Docs: 02_SPEC FR-1.8, 06_DATA_MODEL (writer ownership, settings registry),
  07_IPC, 08_UI, 19_SAFETY, the guide's data, screens and settings pages.

A self-review after the gate (before the merge): the presence probe asks the entry's own
drive (VolumeRoots.IsReady: the type first, so a dead share is never asked whether it is
ready) instead of listing every drive per entry; an entry the delete refused is asked again
after an hour (its sessions may since have been deleted) rather than never; 06_DATA_MODEL's
cross-reference names the 19_SAFETY section that exists. The vi and ja switch texts name the
pill as those languages show it (“Chưa cài”, “未インストール”).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:50:26 +07:00
poli0981andClaude Opus 5.5 a53ebee683 feat(detection): the engine version of Unity, Godot and RPG Maker games, read from their own files (beta.19 PR-3) (#294)
The owner's request of 2026-10-12. Rules 2026.10.1 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 while the
"Godot Engine v..." string sits 57-78 MB into both exports on the owner's
disk, so it never read one; both RPG Maker rules had version: null.

Measured read-only on 23 installs first (spike-notes section 17), then decided
in code as Unreal's is since beta.10:

- Rules 2026.10.2: unity_build, godot_build, rpgmaker_build - extractor types
  that take no parameter (the schema's enum beside unreal_build).
  StaticGameDetector makes one second read for the engine that matched;
  RuleEvaluator answers null for them as for unreal_build.
- Domain: UnityVersion (player ProductVersion, else the data file's header,
  else the player's numeric version), GodotVersion (a data pack's header,
  beside the executable or appended to it, else the executable's version
  while it is still Godot's; a zero patch dropped, as Godot names it),
  RpgMakerVersion (MZ/MV core-script header; the RGSS library Game.ini names
  -> XP/VX/VX Ace, its version or the one its name carries). New
  EngineVersionSource ids name the witness - and the maker.
- Infrastructure: UnityBuildReader, GodotBuildReader, RpgMakerBuildReader -
  version resources and at most a few kilobytes of any file; RPG Maker's files
  beside the executable or up to two folders above, as RpgMakerTitle looks.
- App: Formats.Engine(id, source) and EngineWithVersion - "RPG Maker MZ
  1.10.0", "RPG Maker VX Ace (RGSS 3.0.1)", "Unity 2022.3.39f1", "Godot 4.4.1"
  on the page, the subtitle and the card; the Engine version row says what
  each was read from, and "Not found in the game's files" once read. Strings
  en/vi/ja (ja marked review).
- Privacy Policy 2.8: section 4 names the version marks an engine keeps in its
  own files (the owner-approved wording), which also covers two reads that were
  never stated (UnityPlayer.dll's version, an RPG Maker title). The accuracy
  block, LIMITATIONS, 05_DETECTION, 06_DATA_MODEL, 08_UI and
  legal-drift-history say the same.

The shipped pipeline over the owner's installs (read-only): Unity 15 of 15,
Godot 2 of 2, RPG Maker 6 of 6, every one as measured; 24 ms to 4.1 s per
entry on the USB drive, nearly all of it the install's walk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:40:00 +07:00
poli0981andClaude Opus 5.5 3f798ad364 feat(app): Change executable... opens in the game's own folder (beta.19 PR-2) (#293)
The owner's request of 2026-10-12: the file dialog of Change executable...
opened wherever the last file dialog was, and the pick is almost always
another file of the same install.

GameFolder.StartFolder derives the folder from the row's path - the only
place one is stored: the install folder a store boundary names (InstallRoot:
steamapps\common\X, GOG Galaxy\Games\X, Epic Games\X, GamesInstalled\X), above
an Unreal package's <Project>\Binaries\Win64 where no boundary is recognised,
else the executable's folder; the nearest folder still there when that one is
gone (a Not installed entry); null for a drive that is not connected, where
Windows opens its last folder. It asks the file system, so the page runs it off
the UI thread. IGamePicker.PickExecutable takes the folder; Add game passes
none and keeps Windows' own choice.

Tests: GameFolderTests (each layout, a gone folder, an absent drive),
GameDetailViewModelTests.ChangingTheExecutableOpensThePickInTheGamesOwnFolder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:25:07 +07:00
poli0981andClaude Opus 5.5 38fdb6bd32 fix(import): a helper a store names is never the game, and an NW.js runtime outranks its launcher (beta.19 PR-1) (#292)
The owner's A Doll's Locket - Remake (itch 5085165, RPG Maker MZ) was imported as
Dolls Locket\notification_helper.exe. 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, so with the 213 MB
DollsLocket.exe launcher asking for administrator and the NW.js runtime a level
deeper in css\, the helper was the whole verdict (read from the owner's butler.db,
read-only).

- ItchLibrarySource skips a verdict candidate whose whole name is a runtime helper
  (ExecutableLocator.RuntimeHelperNames) or that sits in a Unity plugin folder; with
  nothing left the locator guesses and the review marks the row guessed. Whole
  names, not the locator's fragments: "node" is inside Nodebuster.
- ExecutableLocator ranks an executable beside nw.dll + package.json as an NW.js
  runtime (owner decision D56): below the Unity and Unreal layouts, above a name
  match. On the owner's disk it now picks css\Game.exe for Doll's Locket and
  swiftshader\Game.exe for HELLO, HELLO WORLD! (what D28 chose by hand); every other
  install it was run over picks what it picked before. notification_helper, nwjc
  and chromedriver join the helper fragments.
- LibraryImporter matches a store title to an entry by platform + store id as well
  as by path, so a corrected guess does not offer the same game a second time; the
  existing entry is re-pointed with Change executable... (nothing rewrites it).

HANDOFF owner-only item 14 (beta.18 on real hardware) is struck: passed 2026-10-08.

* fix(import): a store title is its entry by store id also when the entry's executable is inside the title's folder (beta.19 PR-1)

Found in a self-review after the stack's gate: the platform an import writes
is badged "detected", and the detection sweep refreshes it with what its own
rules find - an itch build that ships steam_api64.dll reads as Steam. Matching
the store id under the same platform only would then offer the same itch
title again beside its entry. The id now matches under the same platform, or
with the entry's executable inside the title's install folder; the same number
under another platform elsewhere is another store's numbering and stays a new
candidate (LibraryImporterTests.TheSameStoreIdInsideTheTitlesFolderIsTheSameTitleWhateverThePlatformReadsAs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:10:47 +07:00
poli0981andClaude Opus 5.5 6ed7851d90 test(capturehost): the Vulkan launch case asks the harness before the host runs; the target-exit case holds 15 s (beta.18 PR-5) (#290)
The two CaptureHost end-to-end races that failed beta.18's CI (both re-run green), taken at the owner's request
(2026-10-07) before the tag.

LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing failed #288 (run 37627351438) with
"session: RefusedByGuard / verdict: ModuleScanFailed  a module list came back incomplete". A hosted runner has the
Vulkan loader and no device, so the harness exits 77 with a "[SKIP]" line; the test read that line, or the session's
LaunchTargetExited, off the HOST's output. The runner is elevated, so the host starts the harness through
CreateProcessWithTokenW (UnelevatedProcess), which hands the child no stdout: the line never reached the host's output,
and when the guard's scan hit the dying harness the test failed instead of skipping. It now runs the plain harness
itself first (`--vulkan --hold-presenting 1`, bounded at 60 s), skips on 77 with the harness's own line, and otherwise
runs in full with no skip after the host - once the harness has presented here, every failure is real.
Measured: on this machine (a device) both cases pass, the Vulkan one in full; with the probe's ICDs hidden
(VK_DRIVER_FILES / VK_ICD_FILENAMES at a missing file, a throwaway edit) it skips in 0.66 s:
"[SKIP] vkCreateInstance failed (no ICD, or no surface extensions)".

WhenTheTargetExitsTheHostStopsAndSaysWhy failed #286 (run 37619719203) with TargetNotRunning: the host resolves its
target once, as it starts, and a host slower than the harness's 6 s hold found it gone (recorded since 2026-09-21).
The host prints nothing until its session ends, so there is no "attached" to wait for; the hold is 15 s, a margin.

The class's remark said CI does not run it; CI has, since 2026-09-06 - corrected in place. Docs: 13_CI_CD (the flake
tally), HANDOFF (beta.18's trap, struck to fixed), CHANGELOG [0.1.0-beta.18] (this ships in that tag).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 23:39:14 +07:00
poli0981andClaude Opus 5.5 dadcacf1a0 release: 0.1.0-beta.18 - the CHANGELOG section with how to update from beta.17, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's beta.18 section and owner-only item 14 (beta.18 PR-4) (#289)
* fix(release): the natives carry the clean checkout's build id - read before the date substitution, handed to CMake, read back out of the binaries (beta.18 PR-3)

The chip from beta.17, open since beta.4 (HANDOFF §0.1.0-beta.4, "Found and NOT fixed"): the owner's Dashboard read
"Overlay build v0.1.0-beta.17-dirty", and beta.16's the same. The release run's own log says why:
"RELEASE_DATE = 2026-10-07 in 3 file(s)" and, 22 s later, "FL_BUILD_ID = v0.1.0-beta.17-dirty". release.yml writes the
release date into the tracked legal/*.md before the gate, and CMake's configure reads `git describe --dirty` after it.
CI's own checkout is clean (main's last run: "FL_BUILD_ID = 15b4c6b0ecc1").

- release.yml: a step before the substitution reads describe from the clean checkout (12 digits, as CMake does),
  refuses one that is already dirty or longer than 31 characters, and exports FL_BUILD_ID. After the publish,
  tools/buildid-check.ps1 reads it back out of the four natives that compile it.
- src/native/FrameLedger.Shm/CMakeLists.txt: the environment's FL_BUILD_ID is taken as given, after a check for the
  characters a C string literal carries without escaping; otherwise describe as before. Its comment said a released
  build was exact - "CI configures and builds once from a clean checkout" - corrected in place.
- tools/buildid-check.ps1 (new): looks for the id as the C string it is compiled as (characters + NUL) in each
  binary's bytes; nothing is loaded - loading the Overlay would run its DllMain. -SelfTest, eight cases, both
  directions, runs in the gate (build.ps1 'buildid-check').

Measured here: ./build.ps1 native with FL_BUILD_ID=b18-envtest.1+x_y printed "FL_BUILD_ID = b18-envtest.1+x_y", and
buildid-check over the four built DLLs: "ok - 4 native binaries carry 'b18-envtest.1+x_y'"; with FL_BUILD_ID='bad "id"'
the configure stopped ("holds a character no build id has"). On this branch's own describe (dirty, "+"), the tool
refused the id itself and found it in all four binaries.

Docs: 12_BUILD (§Release-time token substitution; gate 14c), 13_CI_CD (§release.yml), HANDOFF (§0.1.0-beta.4's bullet
struck, dated), CLAUDE.md (tools), wiki Releasing, CHANGELOG [Unreleased].

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

* release: 0.1.0-beta.18 - the CHANGELOG section with how to update from beta.17, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's beta.18 section and owner-only item 14 (beta.18 PR-4)

VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-07) asked for beta.18 - the two chips beta.17 left and
the page text that blends into the dark window; the train follows beta.17's: merge on green CI, then the signed tag
v0.1.0-beta.18 on the merge commit. wiki.yml publishes the wiki after the Release run succeeds.

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.18] - 2026-10-07, with its summary and "Updating from 0.1.0-beta.17";
  tools/release-notes.ps1 -Version 0.1.0-beta.18 extracts it (3948 characters).
- The accuracy block's release line (legal/ACCURACY.md, embedded in README and the Disclaimer; accuracy-check green),
  README's release lines and count, LIMITATIONS' version.
- HANDOFF: beta.17's START HERE struck; the beta.18 section - no new decisions; the traps (a page in the NavigationView
  inherits nothing; the accent is not in the theme dictionary; the gate's own refusals look like findings on the wire;
  Safety_Consent_* strings are versioned with the disclosure; a release's natives were -dirty by its own hand; the
  CaptureHost e2e flake met again); owner-only item 14.

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

* docs(handoff): the beta.18 traps name the Vulkan launch e2e race that failed #288's CI

On an elevated runner the harness starts through CreateProcessWithTokenW, its "[SKIP]" line never reaches the host's
output, and a guard scan that hits the exiting harness (ModuleScanFailed) fails the test instead of skipping it.
Re-run; the deterministic fix is a task.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 21:06:45 +07:00
poli0981andClaude Opus 5.5 1d0e8407bd fix(release): the natives carry the clean checkout's build id - read before the date substitution, handed to CMake, read back out of the binaries (beta.18 PR-3) (#288)
The chip from beta.17, open since beta.4 (HANDOFF §0.1.0-beta.4, "Found and NOT fixed"): the owner's Dashboard read
"Overlay build v0.1.0-beta.17-dirty", and beta.16's the same. The release run's own log says why:
"RELEASE_DATE = 2026-10-07 in 3 file(s)" and, 22 s later, "FL_BUILD_ID = v0.1.0-beta.17-dirty". release.yml writes the
release date into the tracked legal/*.md before the gate, and CMake's configure reads `git describe --dirty` after it.
CI's own checkout is clean (main's last run: "FL_BUILD_ID = 15b4c6b0ecc1").

- release.yml: a step before the substitution reads describe from the clean checkout (12 digits, as CMake does),
  refuses one that is already dirty or longer than 31 characters, and exports FL_BUILD_ID. After the publish,
  tools/buildid-check.ps1 reads it back out of the four natives that compile it.
- src/native/FrameLedger.Shm/CMakeLists.txt: the environment's FL_BUILD_ID is taken as given, after a check for the
  characters a C string literal carries without escaping; otherwise describe as before. Its comment said a released
  build was exact - "CI configures and builds once from a clean checkout" - corrected in place.
- tools/buildid-check.ps1 (new): looks for the id as the C string it is compiled as (characters + NUL) in each
  binary's bytes; nothing is loaded - loading the Overlay would run its DllMain. -SelfTest, eight cases, both
  directions, runs in the gate (build.ps1 'buildid-check').

Measured here: ./build.ps1 native with FL_BUILD_ID=b18-envtest.1+x_y printed "FL_BUILD_ID = b18-envtest.1+x_y", and
buildid-check over the four built DLLs: "ok - 4 native binaries carry 'b18-envtest.1+x_y'"; with FL_BUILD_ID='bad "id"'
the configure stopped ("holds a character no build id has"). On this branch's own describe (dirty, "+"), the tool
refused the id itself and found it in all four binaries.

Docs: 12_BUILD (§Release-time token substitution; gate 14c), 13_CI_CD (§release.yml), HANDOFF (§0.1.0-beta.4's bullet
struck, dated), CLAUDE.md (tools), wiki Releasing, CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:53:00 +07:00
poli0981andClaude Opus 5.5 a48e99b6c1 fix(app): every notice says what happened in words - the gate's own refusals, a familyless refusal, a re-scan that could not look, a stop mid-session (beta.18 PR-2) (#287)
The chip from beta.17 (found while writing the guide), measured on the Agent's own events. Three notices printed what
only the code knows:

- Disable all hooking: the gate labels its own refusals where a finding carries its family, so the 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." A game blocked before read "previously blocked was detected
  in this game (AntiCheatFile|NetEase Yidun|NEP2.dll)". The gate's refusals are said as the 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 Agent sends
  the guard's reason for every refusal (RecordedSessionEvents.GuardReasonOf; beside a family only, until now), and the
  sentence is the guard's 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 ran read "Capture stopped: Access is denied. was detected while
  the game was running"; it reads Safety_Unhooked_Unnamed_Format ("... the game's process could not be opened ...").
- CaptureDegraded printed its reason raw and said the session went on: "The hook stopped (WriterSelfDisabled); the
  session continues without measuring." A stop ends the session (07_IPC). The notice is the end's sentence;
  Notice_Degraded_Unknown_Format names only a reason this build has no words for.

And the rest of the chip:
- Turning the kill switch on said "Applied. The capture agent reads it at the next session start."; a measured session
  stops at its next safety scan, within 30 s (CaptureOptions.ScanInterval), and Settings_KillSwitch_Applied_On says so.
- Turn off / the game page's switch / withdrawing an exception with no agent said "Nothing was enabled." - the enable
  path's words (Safety_Consent_AgentUnavailable, left as is: changing a Safety_Consent_* string's meaning would bump
  the consent disclosure). Agent_NotConnected_NothingChanged.
- The viewer (--data-dir, D52) left the user-mode exception option, the three Recording numbers and the update channel
  live; every setting the Agent reads is off there now, held by the registry (ViewerModeTests).
- 08_UI listed a "PawnIO missing" banner that was never built.

Tests, red on the unfixed code first (12 App, 1 Application):
- NoticesFromTheAgentTests builds each event as the Agent does - the gate's verdict (HookedCaptureGate, kill switch),
  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. The
  notices' tests had only raised events written by hand ("GuardBlocked", "HookFaulted"), which no Agent sends.
- RecordedSessionEventsTests.BothSafetyEventsCarryTheGuardsReasonWheneverItRefused; SettingsViewModelTests (the kill
  switch's two strips, Turn off); ViewerModeTests.EverySettingTheAgentReadsIsOffInAViewer and the channel's row;
  ReasonTextTests' familyless refusal now as the Agent sends it.

Strings: three new App keys and one Shared (Safety_Unhooked_Unnamed_Format, ja = the English until reviewed), one App
key renamed; en/vi/ja. Docs: 07_IPC (guardReason, CaptureDegraded), 08_UI (§Notifications policy, the viewer, the
kill switch's strip, PawnIO), HANDOFF (beta.17's list corrected in place), CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:12:26 +07:00
poli0981andClaude Opus 5.5 b42d94bf1d fix(app): page titles read in the dark theme - every page sets the text colour the navigation Frame does not pass (beta.18 PR-1) (#286)
The owner's screenshots of 0.1.0-beta.17 (2026-10-07, dark theme): every page's title and section headings - Dashboard,
Recent sessions, Games, Compare, Pick 2 to 5 sessions, Settings and its groups, Logs - near-black on the dark window.
beta.16's screenshot shows the same.

Cause: a page is shown in WPF UI's NavigationViewContentPresenter, which is a Frame, and Frame.Init sets
InheritanceBehavior.SkipToAppNow - the window's Foreground stops there. A TextBlock that sets no colour falls to the
default, which WPF UI 4.3.0's TextBlockMetadata overrides to Brushes.Black. Cards, grids and controls set their own in
their templates; the bare titles and headings did not (19 texts on six pages, 1.29:1). It came and went: a page on
screen during a theme switch did take the window's new colour, and each navigation makes a new page that does not.

- Pages/*.xaml: every Page root sets Foreground="{DynamicResource TextFillColorPrimaryBrush}".
- AccessibilityTests.EveryPageSetsItsOwnTextColour: every Page root in the App's XAML sets it. Red before: all six.
- PagesLoadTests.EveryTextIsReadableInBothThemes (Dark, Light): every surface hosted as the App hosts it - a page in
  the presenter, a window as itself, anything else in an unshown FluentWindow - and every text that shows >= 3:1 over
  the colour painted under it. Red before in Dark: the 19 titles and headings at 1.29:1; Light green.
- PagesLoadTests.Hosted puts a page in the presenter, so EveryTextFollowsAThemeSwitch checks the App's real host too.
  Until now it laid pages out straight in a window, whose colour they inherited - green over the black titles. Red
  before, both ways: a page made after the switch stayed black. It now pairs texts by their place in the tree and
  compares what shows (a switch re-applies the template of a DataGrid's collapsed scroll bar and select-all corner).
  An Appearance="Secondary" put back on one Settings text still turns it red, both ways.
- Visuals.UnderTheme switches as the App does: the accent resources derived for the theme from Windows' default accent,
  then the dictionary, and the application's own resources put back after. The accent is not in a theme dictionary, so
  a Light check measured the dark theme's link blue on the light window (1.9:1) - a colour the App never shows.
  ContrastTests uses it too; it passed systemAccentColor: true, which reads the machine's own accent palette.
- Docs: 16_WPFUI_SYNTAX (a theming bullet, a Gotchas entry), 08_UI §Contrast (the fifth hole), 14_TESTING (a page is
  measured in the Frame; a theme brings its accent), wiki App UI development, CHANGELOG [Unreleased].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 19:50:14 +07:00
poli0981andClaude Opus 5.5 15b4c6b0ec release: 0.1.0-beta.17 - the CHANGELOG section with how to update from beta.16, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's beta.17 section with D53-D54 and owner-only item 13 (beta.17 PR-5) (#285)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-07) approved the train end to end: merge on green CI,
then the signed tag v0.1.0-beta.17 on the merge commit. wiki.yml publishes the wiki after the Release run succeeds.

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.17] - 2026-10-07, with its summary and "Updating from 0.1.0-beta.16";
  tools/release-notes.ps1 -Version 0.1.0-beta.17 extracts it.
- The accuracy block's release line (legal/ACCURACY.md, embedded in README and the Disclaimer; accuracy-check green),
  README's release lines and count, LIMITATIONS' version.
- HANDOFF: beta.16's START HERE struck; the beta.17 section - D53 (the wiki's source is the repository, published by
  wiki.yml), D54 (the guide is the wiki's End-user half, twelve pages), the traps (ui:TextBlock Appearance pins a brush;
  a Loaded class handler is not a load hook; the wiki's branch and the read-only default token; gating a stack from the
  main checkout), the findings left as tasks; owner-only item 13.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:55:24 +07:00
poli0981andClaude Opus 5.5 2c967b3d63 docs(wiki): the developer half of the wiki, built from the repository and published at each release (beta.17 PR-4, D53) (#284)
* docs(guide): the user guide looks things up too - the screens, every setting, troubleshooting, a glossary (beta.17 PR-3, D54)

The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D54):
the End-user part IS the user guide, one source - shown in the App under Help > User guide and, from PR-4, on the
wiki. Four pages join it after the FAQ, each written from the code it describes (labels, defaults, ranges and messages
read in SettingsPage.xaml, SettingsRegistry, Strings.resx and the view models):

- guide/07-screens.md - the badge and banners, every menu item, Dashboard, Games, a game's page, the session summary,
  Compare, Logs, the tray icon, keyboard and mouse.
- guide/08-settings.md - every setting the Settings page shows, in its order: what it does, its default, and which
  ones the agent reads.
- guide/09-troubleshooting.md - what you see, what it means, what to do: the agent, a game recorded but not measured
  (each "Why:"), N/A figures, "How it ended", updates, the database, the viewer, reporting a problem.
- guide/10-glossary.md - the words the App shows, A to Z.

guide/README.md lists them in the App's order (EmbeddedDocuments.GuidePages). The first run's "Your library" step named
"File > Import library... on the Games page"; File is the main window's menu and the Games page has no import button -
fixed in en/vi/ja (vi names the menu as shown, "Tep").

Tests (GuideDocumentsTests), each shown to bite on a deliberately broken page:
- EveryLinkToASectionNamesAHeadingOfItsPage - every section link, within a page, to another guide page, Limitations or
  a document, against the anchors the App's renderer gives the target (it replaces the one-anchor check);
- TheContentsListThePagesInTheAppsOrder;
- TheSettingsPageOfTheGuideNamesEverySetting - every Settings_*_Label the Settings page binds, in English;
- TheScreensPageOfTheGuideNamesEveryPageAndMenuItem - every Nav_* and Menu_* of the main window.
MarkdownRendererTests counts the guide's twelve pages.

Docs: CLAUDE.md and 08_UI ("eight short English pages" struck, the tests named; the consent dialog's button is "Keep
hooking off", not "Keep it off"), CHANGELOG [Unreleased].

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

* docs(wiki): the developer half of the wiki, built from the repository and published at each release (beta.17 PR-4, D53)

The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D53):
the wiki's source lives in the repository and the Wiki tab is a copy, published when a release is made; the End-user
half is the user guide (PR-3, D54). The Wiki tab existed with one placeholder page.

- wiki/: Home (two doors), _Sidebar, and eleven short developer pages - Developers (where to start, where status lives),
  Architecture (a mermaid diagram, the processes, the two tiers, a frame's way to the screen), Repository map, Build and
  test (the gates in one table), Contributor rules (the nine rules in plain words, what will never be built, every
  pull request), Capture pipeline, Metrics (and the display rules), Data and IPC, App UI development (the WPF UI traps,
  this train's two included), Releasing, Developer glossary. Each links to its full document and states no status.
- tools/wiki-build.ps1: names each page (a guide page after its first heading; guide/README.md is User-guide,
  LIMITATIONS.md Limitations), rewrites links between pages to page names and every other repository link to GitHub at
  -Ref, drops each page's first heading, writes _Footer.md naming the ref. Refuses a link to a missing file, folder or
  section, two sources for one page, a page nothing leads to, a sidebar out of the guide's order, a backticked path in a
  wiki/ page that names nothing, and a version written into a wiki/ page. -SelfTest: nine cases, both directions.
- build.ps1: the wiki-check gate after notice-check (self-test, then -Check).
- .github/workflows/wiki.yml: on workflow_run of Release (success, started by a pushed v* tag - a rehearsal never
  publishes) and by hand (ref, publish). Checks out head_sha, links at the tag, uploads the pages, and publishes with
  gh auth setup-git + a clone of <repo>.wiki.git + push HEAD:master, only when something changed. contents: write, since
  the repository's default token is read-only. Separate from release.yml so a wiki failure is never a red release and
  can be re-run.
- Docs: README (the wiki, both halves), docs/README.md (the wiki; "D1...D46" corrected), CONTRIBUTING (where
  documentation lives), CLAUDE.md (wiki/ and wiki-build), 12_BUILD (gate 13d), 13_CI_CD (wiki.yml, five repo-local
  workflows, the owner's wiki-editing setting), CHANGELOG [Unreleased].

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 10:18:43 +00:00
poli0981andClaude Opus 5.5 1722a4ef56 docs(guide): the user guide looks things up too - the screens, every setting, troubleshooting, a glossary (beta.17 PR-3, D54) (#283)
The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D54):
the End-user part IS the user guide, one source - shown in the App under Help > User guide and, from PR-4, on the
wiki. Four pages join it after the FAQ, each written from the code it describes (labels, defaults, ranges and messages
read in SettingsPage.xaml, SettingsRegistry, Strings.resx and the view models):

- guide/07-screens.md - the badge and banners, every menu item, Dashboard, Games, a game's page, the session summary,
  Compare, Logs, the tray icon, keyboard and mouse.
- guide/08-settings.md - every setting the Settings page shows, in its order: what it does, its default, and which
  ones the agent reads.
- guide/09-troubleshooting.md - what you see, what it means, what to do: the agent, a game recorded but not measured
  (each "Why:"), N/A figures, "How it ended", updates, the database, the viewer, reporting a problem.
- guide/10-glossary.md - the words the App shows, A to Z.

guide/README.md lists them in the App's order (EmbeddedDocuments.GuidePages). The first run's "Your library" step named
"File > Import library... on the Games page"; File is the main window's menu and the Games page has no import button -
fixed in en/vi/ja (vi names the menu as shown, "Tep").

Tests (GuideDocumentsTests), each shown to bite on a deliberately broken page:
- EveryLinkToASectionNamesAHeadingOfItsPage - every section link, within a page, to another guide page, Limitations or
  a document, against the anchors the App's renderer gives the target (it replaces the one-anchor check);
- TheContentsListThePagesInTheAppsOrder;
- TheSettingsPageOfTheGuideNamesEverySetting - every Settings_*_Label the Settings page binds, in English;
- TheScreensPageOfTheGuideNamesEveryPageAndMenuItem - every Nav_* and Menu_* of the main window.
MarkdownRendererTests counts the guide's twelve pages.

Docs: CLAUDE.md and 08_UI ("eight short English pages" struck, the tests named; the consent dialog's button is "Keep
hooking off", not "Keep it off"), CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:02:13 +07:00
poli0981andClaude Opus 5.5 b18d7dc80e fix(app): hide scroll bars reaches every scroller - a ScrollChanged class handler beside Loaded (beta.17 PR-2) (#282)
The owner's screenshot of 0.1.0-beta.16 (2026-10-07): with Settings > Window > Hide scroll bars on, the Dashboard still
drew its scroll bar while Settings did not.

Cause, read in dotnet/wpf: BroadcastEventHelper.OnBroadcastCallback raises Loaded only on elements whose
SubtreeHasLoadedChangeHandler is set, and FrameworkElement.ThisHasLoadedChangeEventHandler counts instance handlers,
style EventSetters, template triggers and FEF handlers - not EventManager class handlers. ScrollBarHiding (beta.14)
had one class handler on ScrollViewer.Loaded, plus a walk of the open windows when the toggle changes; the flag is
applied before the first window, so the walk never helped at start-up. WPF UI 4.3.0's ToggleSwitch, CheckBox and
ProgressRing templates carry a Loaded EventTrigger, so Settings' scroller loaded and was hidden; the Dashboard (cards,
text, borders) never loaded as far as the option knew.

- Services/ScrollBarHiding: a class handler on ScrollViewer.ScrollChangedEvent (handledEventsToo), calling the same
  idempotent Set. Every scroller raises it from its first layout, inside ContextLayoutManager.UpdateLayout, so the
  bar is gone before the first frame; the Loaded handler stays. Doc comment and App.xaml.cs comment corrected.
- ScrollBarHidingTests.AScrollerLaidOutWithNoLoadedEventIsHidden: red before (Auto).
- ScrollBarHidingTests.EverySurfaceShownWithTheOptionOnDrawsNoBar: every page navigated in WPF UI's presenter, the
  first run, About, the user guide, a session's summary and every dialog's content, each shown in a real window off
  the screen with the option on first. Red before: the Dashboard's ScrollViewer, Game detail's sessions DataGrid
  (horizontal), the first run's ListBox and MarkdownView, About's ScrollViewer, the user guide's ListBox and
  MarkdownView. Settings and Logs were already hidden (the control); the check requires Dashboard, Settings, Logs and
  the user guide to have something to scroll.
- ScrollBarHidingTests.WpfRaisesLoadedOnlyWhereASubtreeListensForIt: the harness against WPF - a scroller with its own
  Loaded class handler is not called holding a Border, and is holding a CheckBox.
- Docs: 08_UI §Settings (the false "reaches every scroller" struck and dated), 16_WPFUI_SYNTAX §Gotchas (a class
  handler on Loaded is not a load hook), 14_TESTING, CHANGELOG [Unreleased].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 16:40:17 +07:00
poli0981andClaude Opus 5.5 23fa7a0fb4 fix(app): text follows a theme switch - SecondaryText/TertiaryText replace ui:TextBlock Appearance (beta.17 PR-1) (#281)
The owner's screenshots of 0.1.0-beta.16 (2026-10-07): after Dark -> Light, Settings' descriptions were light grey on
white; after the way back, dark grey on dark.

Cause, read in WPF UI at tag 4.3.0 (main is the same): TextBlock.OnAppearanceChanged stores
TryFindResource(TextFillColorSecondaryBrush|TertiaryBrush) in the internal AppearanceForeground, and TextBlockMetadata
coerces every TextBlock's Foreground to it. The brush is the one found when the element was made and is never looked
up again, so a text kept the theme it was created under. Pages are transient, so the page in view during a switch -
Settings, where the theme is chosen - showed it.

- Styles/FrameLedger.xaml: SecondaryText and TertiaryText (Foreground by DynamicResource), and the 129
  `ui:TextBlock Appearance=` in 20 files take them (107 Secondary, 22 Tertiary; only TextBlock start tags were
  edited, every ui:Button/ui:Badge Appearance kept).
- ContrastTests.NoTextBlockTakesItsColourFromAppearance: no Appearance on a TextBlock, the attached form, a style
  setter or the code form, in the App. Red before: 129 hits.
- PagesLoadTests.EveryTextFollowsAThemeSwitch (Dark and Light): every page, the first run, About, the user guide, a
  session's summary, every dialog's content, the safety InfoBar and the two custom controls, made under one theme in an
  unshown FluentWindow (only Application.Windows hear a dictionary change), switched, and compared text by text with
  the same surface made fresh. Red before: 146 stale texts each way, all TextFillColorSecondary/Tertiary.
- PagesLoadTests.WpfUisAppearanceStillKeepsTheThemeATextWasMadeUnder: the library's behaviour, kept visible; red the
  day upstream follows a switch.
- PagesLoadTests.Surfaces: one catalogue of every surface over loaded view models, for any check that wants them all.
- Docs: 16_WPFUI_SYNTAX (Text row, theming bullet, a Gotchas entry), 08_UI §Contrast (the fourth hole),
  14_TESTING (a theme switch needs a window), CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 09:20:59 +00:00
dependabot[bot]andpoli0981 6f74574e8f Bump Meziantou.Analyzer and Roslynator.Analyzers (#262)
Bumps Meziantou.Analyzer from 3.0.266 to 3.0.294
Bumps Roslynator.Analyzers from 5.0.0 to 5.0.1

---
updated-dependencies:
- dependency-name: Meziantou.Analyzer
  dependency-version: 3.0.294
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: Roslynator.Analyzers
  dependency-version: 5.0.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: poli0981 <127664709+poli0981@users.noreply.github.com>
2026-10-06 11:40:23 +00:00
poli0981andClaude Opus 5.5 cf4a1acc8e release: 0.1.0-beta.16 - the end-to-end suites consent to a run-unique harness copy (the beta.15 chip); beta.15 verified (#280)
* test(e2e): the suites whose host resolves its target by name consent to a run-unique copy of the harness (beta.16, the beta.15 chip)

#269's first CI run lost AgentEndToEndTests.AConsentedBoundedCaptureLandsAsOneHookedRowInTheScratchLedger: exit 6,
TargetAmbiguous - "hook-harness.exe: 1 process(es) with that name could not be read (pid 3684: Only part of a
ReadProcessMemory or WriteProcessMemory request was completed.)". build.ps1 runs the test projects as parallel processes;
another project's hook-harness.exe was still starting (its module list a partial copy), and TargetResolver must count an
unreadable process of the consented executable's NAME. The refusal is right; the suites sharing one name was not. The
[Collection("agent-harness")] only serialises classes inside Agent.Tests.

- AgentEndToEndTests, PartialRecoveryEndToEndTests and CaptureHostEndToEndTests consent to
  hook-harness-<their scratch directory>.exe, a copy of the staged harness beside their data, as PipeEndToEndTests
  already did: StageTarget copies it once per test and registers the directory with HarnessOverlayLogSweep, so its
  overlay logs leave with the run. TargetResolver, the guard and every product rule are unchanged.
- The self-constraint tests pin the copy to the staged hook-harness.exe byte for byte (and the staged one to the test
  binary's directory), so the suites still inject into nothing but our own harness.
- AnotherHookHarnessRunningBesideTheSuiteDoesNotMakeTheTargetAmbiguous runs a second harness beside the capture. Measured
  against the old shared name: "session: TargetAmbiguous", red; green now.
- Suites that attach by pid (ShmDrainIntegrationTests, the native fl_guard_test) were never exposed and keep the name.

Docs: 14_TESTING (test isolation), HANDOFF (the beta.15 trap marked fixed), CHANGELOG (development note).

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

* release: 0.1.0-beta.16 - the CHANGELOG section, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's section, and owner-only item 12 marked passed

VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-06), after beta.15's release: item 12 passed on real
hardware ("đã chạy và ok"), do the chip beta.15 left, release, and close the session.

Nothing in the app changed since beta.15, and the section says so; "Updating from 0.1.0-beta.15" is the ordinary path.
HANDOFF: beta.15's START HERE is struck; the beta.16 section records the chip, the beta.15 train's merges (#277 and #278
were opened from the pushed branches, so their squash titles are GitHub's defaults; the content is the gated stack's)
and three traps - a session restart that empties gpg-agent's cache before a tag, a strict linear main that makes every
stacked PR rebase and re-run CI, and a desktop app that wakes the session on a red PR but never on a green one. Item 12
is marked passed in the owner-only list; no item is added.

tools/release-notes.ps1 -Version 0.1.0-beta.16 extracts the section (860 characters); accuracy-check is green.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 07:13:29 +00:00
poli0981andClaude Opus 5.5 bfd5238360 release: 0.1.0-beta.15 - the CHANGELOG section with how to update from beta.14, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's train section with D51-D52 and owner-only item 12 (beta.15 PR-6) (#279)
VERSION stays 0.1.0: the tag's numeric core. The tag waits for the owner's confirmation (asked 2026-10-06).

The [Unreleased] entries of PR-1..PR-5 move under [0.1.0-beta.15] with a summary for the release body; "Updating from
0.1.0-beta.14" says what is different this time: nothing migrates and nothing is shown again, and beta.14's own update
step stops the Agent before Velopack applies - this is the first update where it runs.

HANDOFF: beta.14's START HERE is struck; the beta.15 section carries the request, D51 and D52 (asked before the plan) and
the traps of the train - launch mode's election that never ran because the tests hand-built the session's outcome, the
watcher that reports a process once, a snapshot pid that names whoever holds it now, static choice lists, and the Agent
end-to-end test that lost to another test project's harness (left as a task). Owner-only item 12: the update from
beta.14, a quick restart, a change of language, a launcher, the viewer over a copy, the ja strings.

tools/release-notes.ps1 -Version 0.1.0-beta.15 extracts the section (3583 characters); accuracy-check and notice-check
are green.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 04:37:17 +00:00
poli0981andClaude Opus 5.5 690ce3acf8 Beta15/pr5 viewer (#278)
* fix(watch): a game started again while its last session finalizes is recorded when that session ends (beta.15 PR-3)

From the beta.14 audit (chip, folded into beta.15 by the owner). CaptureOrchestrator.Start turned a process away while a
session for its executable was still running ("one at a time"), and ProcessWatcher reports a pid once - so a game
started again during the previous session's finalize (driver profile up to 5 s, a crash reporter waited for up to
2.5 s, the transaction) never got a session. Verified on the code first: path (b), dropped, never picked up.

- The newest turned-away process per executable is remembered (Deferred: the event and the process's start time) and
  started from Reap when that session ends - if the session ended on its own (RunAndReportAsync records the result; a
  cancelled or faulted one starts nothing), the process is the same one (pid and start time) and it is then the
  executable's ONLY process. A helper of a multi-process game (NW.js, Electron) still has the game beside it, so it stays
  turned away, as before.
- The start happens outside the table's lock; the log says "recording it now".

Tests (CaptureOrchestratorTests, FakeRecorder.Pending holding finalize open): the restart is recorded when the session
ends (red before: one request), a helper of a game still running is not, a process that left meanwhile is not. The
existing one-at-a-time test keeps its behaviour.

Docs: 04_CAPTURE §Process watcher, HANDOFF trap, CHANGELOG.

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

* fix(guard): the scan set follows a parent link only while creation times allow it (beta.15 PR-4, D51)

The guard's scan set (19_SAFETY item 1, 20_OPEN_QUESTIONS S16) is the injection target, its ancestors below the first
platform launcher and its descendants, walked over one Toolhelp snapshot that links a process to its parent by pid
alone. Windows reuses pids: once a game's launcher exited, the game named a pid that could belong to anything, and 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.

Owner decision D51: a parent/child link is cut ONLY when it is proven wrong - both creation times read 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; a cut child is not walked, nor anything below it. An unread time keeps the link (fail closed, rule 2),
equal times keep it, and each pid is walked and sent once. The launcher boundary, the depth (16), the frontier (512, one
more refuses) and "a member that cannot be read refuses" are unchanged; no C ABI change.

- fl_guard_scanset.h/.cpp: WalkScanSet, a pure allocation-free walk over snapshot rows with the creation-time callback
  and the sink; ProvenNotItsChild; ProcessCreatedAt (PROCESS_QUERY_LIMITED_INFORMATION + GetProcessTimes, the module
  scan's own read-only right; reads nothing inside the process).
- fl_guard_sources.cpp: EnumerateScanSetImpl builds rows from the snapshot and calls the walk; the static rows lose the
  image names (the launcher flag is computed as they are read). The guard stays non-re-entrant (NativeAntiCheatGuard
  serialises every call).
- The new source is in all three CMake lists (FL_INJECTOR_SOURCES, FrameLedger.Injector, FrameLedger.Guard).
- guard_test.cpp [D51]: the plain tree; a reused parent pid; an "older child"; unread times on either end keep the
  link; equal times; cycles; the limits (missing target, frontier 511/512, depth, a full sink); and the real source
  keeps a child this process just started and reads real creation times.
- 19_SAFETY item 1 amended (with the one residual: a clock set backwards), 20_OPEN_QUESTIONS S16 note, CHANGELOG.

Gate: ./build.ps1 check - ALL GATES PASSED in 289s (32/32 native suites).

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

* feat(app): FrameLedger.exe --data-dir opens a copy of a data folder as a viewer - no Agent started or contacted, nothing on the PC changed (beta.15 PR-5, D52)

From the beta.14 audit (chip, folded into beta.15 by the owner): the App had no --data-dir, so a build of one's own could
only be looked at over the profile's ledger - and a newer build migrates it past what the released one can read. D6
deliberately keeps the Agent's --data-dir under --console, the pipe is one per user and the Agent behind it records into
the profile's ledger, so an App over another ledger that still talked to that Agent would send it the other ledger's game
ids: SetHookEnabled consenting for the wrong game (rule 1), DeleteSessions deleting the wrong game's sessions.

Owner decision D52: the App's --data-dir is a VIEWER over a copy. D6 is unchanged.

- Program.Main reads --data-dir (DataFolderArgument) after Velopack and before the single-instance key, the log or the
  ledger: a folder that exists makes a viewer (UiPaths.UseViewerFolder; the folder is its own single-instance key, so it
  runs beside the profile's App); the profile's own folder (case, separators, a relative path, a junction - resolved as
  the Agent's identity resolves links), a missing folder, a flag with no folder or two flags refuse with a message box,
  exit 2. UiPaths refuses the profile folder a second time.
- MachineFacingServices: everything that reaches past the ledger - the pipe client, the launcher, the connection's hosted
  service, the Run entry, the Agent's maintenance flags, Velopack and the startup update check - is registered in one
  place; a viewer gets ViewerAgentLink (never connected, nothing behind it), ViewerRunAtLogon, ViewerAgentTool and
  ViewerUpdateClient (not installed) and no hosted service at all.
- AgentConnectionState.Viewer: the pill reads "Viewer - no Agent"; a persistent InfoBar names the folder.
- ActsOnThisPc disables, in a viewer: hooking, the exception's grant/withdraw, re-enable, Delete all sessions (game page
  and Settings), the kill switch, the exceptions list and refresh, the admin mode, the logon task and the Vulkan layer
  buttons, Start with Windows, the automatic update check, Help > Check for updates, Tools > Update detection rules and
  the tray's Pause. MainWindowViewModel takes IAgentLink rather than the concrete connection.
- Strings (en/vi/ja; ja marked review): Agent_State_Viewer, Viewer_Banner_*, Viewer_ChangesThisPc_Off, DataDir_*.

Tests: DataFolderArgumentTests (the profile refused in six spellings and through a junction, missing, no value, twice, a
copy inside the profile allowed, UiPaths' second lock), ViewerModeTests (the viewer link sends nothing; the consent dialog
never opens; the viewer composition holds no pipe/launcher/hosted service/registry/Velopack while the profile's still
does; every machine-facing control in the XAML binds ActsOnThisPc), SettingsViewModelTests and GameDetailViewModelTests
(viewer vs profile on the same answers).

Docs: 08_UI §Shell, 12_BUILD §Debugging (how to copy a ledger safely with SQLite's backup), 01_ARCHITECTURE §Data
directory, 10_LOGGING, CONTRIBUTING, CLAUDE.md, HANDOFF (D6 pointer, the owner's-data trap), CHANGELOG.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 01:58:56 +00:00
poli0981andClaude Opus 5.5 f94c76bcb6 Beta15/pr4 guard (#277)
* fix(watch): a game started again while its last session finalizes is recorded when that session ends (beta.15 PR-3)

From the beta.14 audit (chip, folded into beta.15 by the owner). CaptureOrchestrator.Start turned a process away while a
session for its executable was still running ("one at a time"), and ProcessWatcher reports a pid once - so a game
started again during the previous session's finalize (driver profile up to 5 s, a crash reporter waited for up to
2.5 s, the transaction) never got a session. Verified on the code first: path (b), dropped, never picked up.

- The newest turned-away process per executable is remembered (Deferred: the event and the process's start time) and
  started from Reap when that session ends - if the session ended on its own (RunAndReportAsync records the result; a
  cancelled or faulted one starts nothing), the process is the same one (pid and start time) and it is then the
  executable's ONLY process. A helper of a multi-process game (NW.js, Electron) still has the game beside it, so it stays
  turned away, as before.
- The start happens outside the table's lock; the log says "recording it now".

Tests (CaptureOrchestratorTests, FakeRecorder.Pending holding finalize open): the restart is recorded when the session
ends (red before: one request), a helper of a game still running is not, a process that left meanwhile is not. The
existing one-at-a-time test keeps its behaviour.

Docs: 04_CAPTURE §Process watcher, HANDOFF trap, CHANGELOG.

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

* fix(guard): the scan set follows a parent link only while creation times allow it (beta.15 PR-4, D51)

The guard's scan set (19_SAFETY item 1, 20_OPEN_QUESTIONS S16) is the injection target, its ancestors below the first
platform launcher and its descendants, walked over one Toolhelp snapshot that links a process to its parent by pid
alone. Windows reuses pids: once a game's launcher exited, the game named a pid that could belong to anything, and 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.

Owner decision D51: a parent/child link is cut ONLY when it is proven wrong - both creation times read 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; a cut child is not walked, nor anything below it. An unread time keeps the link (fail closed, rule 2),
equal times keep it, and each pid is walked and sent once. The launcher boundary, the depth (16), the frontier (512, one
more refuses) and "a member that cannot be read refuses" are unchanged; no C ABI change.

- fl_guard_scanset.h/.cpp: WalkScanSet, a pure allocation-free walk over snapshot rows with the creation-time callback
  and the sink; ProvenNotItsChild; ProcessCreatedAt (PROCESS_QUERY_LIMITED_INFORMATION + GetProcessTimes, the module
  scan's own read-only right; reads nothing inside the process).
- fl_guard_sources.cpp: EnumerateScanSetImpl builds rows from the snapshot and calls the walk; the static rows lose the
  image names (the launcher flag is computed as they are read). The guard stays non-re-entrant (NativeAntiCheatGuard
  serialises every call).
- The new source is in all three CMake lists (FL_INJECTOR_SOURCES, FrameLedger.Injector, FrameLedger.Guard).
- guard_test.cpp [D51]: the plain tree; a reused parent pid; an "older child"; unread times on either end keep the
  link; equal times; cycles; the limits (missing target, frontier 511/512, depth, a full sink); and the real source
  keeps a child this process just started and reads real creation times.
- 19_SAFETY item 1 amended (with the one residual: a clock set backwards), 20_OPEN_QUESTIONS S16 note, CHANGELOG.

Gate: ./build.ps1 check - ALL GATES PASSED in 289s (32/32 native suites).

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 01:31:21 +00:00
poli0981andClaude Opus 5.5 9c82288192 fix(watch): a game started again while its last session finalizes is recorded when that session ends (beta.15 PR-3) (#276)
From the beta.14 audit (chip, folded into beta.15 by the owner). CaptureOrchestrator.Start turned a process away while a
session for its executable was still running ("one at a time"), and ProcessWatcher reports a pid once - so a game
started again during the previous session's finalize (driver profile up to 5 s, a crash reporter waited for up to
2.5 s, the transaction) never got a session. Verified on the code first: path (b), dropped, never picked up.

- The newest turned-away process per executable is remembered (Deferred: the event and the process's start time) and
  started from Reap when that session ends - if the session ended on its own (RunAndReportAsync records the result; a
  cancelled or faulted one starts nothing), the process is the same one (pid and start time) and it is then the
  executable's ONLY process. A helper of a multi-process game (NW.js, Electron) still has the game beside it, so it stays
  turned away, as before.
- The start happens outside the table's lock; the log says "recording it now".

Tests (CaptureOrchestratorTests, FakeRecorder.Pending holding finalize open): the restart is recorded when the session
ends (red before: one request), a helper of a game still running is not, a process that left meanwhile is not. The
existing one-at-a-time test keeps its behaviour.

Docs: 04_CAPTURE §Process watcher, HANDOFF trap, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 08:07:35 +07:00
poli0981andClaude Opus 5.5 1712dc503d fix(capture): launch mode's refused outcome carries the launcher's pid, so the descendant election finally runs (beta.15 PR-2) (#275)
From the beta.14 audit (chip, folded into beta.15 by the owner). CaptureSession built the outcome of launch mode's two
guard refusals (LaunchTargetExited, LaunchNoPresentationRuntime) without TargetPid, and
CaptureOrchestrator.ElectAfterLaunchAsync returned at `TargetPid == 0` - before its own "election:" log line - so the
election (#150, 2026-09-10) never ran. The orchestrator's tests built the outcome by hand with the pid, which is why
nothing saw it.

- The refused cue is `refused with { TargetPid = pid, ExitCode = alive.ExitCode }`; the refusal handling moved to
  CaptureSession.RefusedAsync (MA0051 - SessionAsync was at 60 lines).
- ElectAfterLaunchAsync logs an outcome without a launcher pid instead of returning silently.
- CaptureSessionLaunchTests.TheGuardsTwoLaunchRefusalsAreTheirOwnSessionEndReasons asserts the pid (red before: 0).

Reachable from `Agent --console launch` (the App sends no LaunchGame). A real launcher run is still owed (owner-only).
Docs: 04_CAPTURE (corrected in place), spike-notes §14.2, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 07:42:32 +07:00
poli0981andClaude Opus 5.5 fd4b2f0d5d fix(app): every list of choices, the tray's menu and the Agent pill follow a change of language at once (beta.15 PR-1) (#274)
From the beta.14 audit (chip, owner: fold the five into beta.15). A change of language rebuilds the window and its
pages, so their own text followed; two kinds did not, until a restart:

- Lists of choices built once in a static and bound with x:Static: Settings' Themes and UpdateChannels (D47's
  "Automatic (Beta)" label too), Logs' Sources and Levels, Games' Sorts. They are instance properties now, bound through
  the view model - built per page, in the language the page opens in (GameDetail's TrendMetrics has worked that way
  since beta.8). Languages stays static: each language in its own words, the same in every language.
- Singletons that outlive the rebuilt window: the tray's menu and tooltip (TrayHost) and the Agent pill and update
  banner (MainWindowViewModel). Both implement ILanguageFollower; ShellHost.Rebuild calls every registered follower once
  the new window is up. The shell's registrations moved to App.AddShell (MA0051).

Tests: LanguageFollowingTests (no view model may keep a static list of labelled choices but the languages - red on the
five lists before), SettingsViewModelTests / GamesViewModelTests / GameDetailViewModelTests (a page opened in Vietnamese
lists Vietnamese choices; the trend selector pinned for the first time), TrayHostTests (the menu relabelled, now in the
strings-culture collection).

Docs: 09_I18N (runtime switching), CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 07:26:19 +07:00
poli0981andClaude Opus 5.5 68f115d57d release: 0.1.0-beta.14 - CHANGELOG section with how to update from beta.13, release lines, HANDOFF train section and owner-only item 11 (beta.14 PR-9) (#272)
VERSION stays 0.1.0: the tag's numeric core. The tag waits for the owner's confirmation, and PR-5 / PR-7 for the owner's
approval of the Privacy Policy 2.7 wording.

"Updating from 0.1.0-beta.13" says the three things a beta.13 user must do differently: choose Beta first (beta.13's
default stable channel finds no pre-release), update with no game running (beta.13 still auto-applies at start), and that
schema 0019 cannot be opened by an earlier version.



docs(handoff): two more traps of the beta.14 train - the 31-character build id ten commits after a tag, and the hosted runner that was never acquired (beta.14 PR-9)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 05:12:48 +07:00
poli0981andClaude Opus 5.5 4130b7cbe4 feat(app): the new measurements as summary cards, a render scale chart, a clocks and fan chart, trend metrics and compare rows labelled (presented) (beta.14 PR-8, D49) (#271)
The App's half of D49 (PR-7 recorded the values). Every value is read from the stored row, never recomputed, and reads
N/A on a session recorded before beta.14.

Summary (SessionSummaryViewModel, the cards in AddFrameCards / AddPacingCards / AddMachineCards):
- Time below 60 FPS, with below 30 and "display under {refresh} Hz" beneath - the refresh share named for the display, as
  it is over the presents the display received - and Frame to frame; both carry (presented) where the lows do.
- VSync (share of frames, tearing allowed beneath), Ray tracing (share of frames, rays per pixel; only where measured),
  Game in focus (foreground over drain ticks), Capture quality (gaps, lost records, faults).
- The 1% Low card carries "displayed: N" where frames were generated - rule 6, beside the game's own, never instead.
- GPU clocks (core, memory; fan and memory temperature beneath), GPU held back (power, heat; NVIDIA only), Frames per watt.

Charts:
- RenderScaleChart over RenderScaleSeries: 100 x sqrt(render / 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, a sentence where never measured.
- SensorsChart: the memory temperature on the temperatures plot, in a new palette colour (Chart_SensorTertiary: no
  existing colour was 60 apart from all six beside it - ChartMathTests caught Chart_Histogram == Chart_Native), and a
  Clocks and fan plot - core and memory MHz, fan RPM on the right, the ticks a limit held the card back shaded
  (LimitRuns); collapsed when the session stored none of them.

Trend: nine metrics (time below 60 / refresh, frame to frame, render scale = 100 / upscale_ratio, VSync share, frames per
watt from hooked sessions; core clock, memory temperature, power-limit share from every session), with ms, MHz and FPS/W
axes. Compare: nine rows; the median, lows, stutter, time below 60 and frame to frame carry (presented) in the cell of a
present-only session, the best decided on the number, never the label. The Latency tab is shown only for a game with a
session that measured latency (nothing measures Reflex today). Formats.Share, Milliseconds, FramesPerJoule.

Tests: SessionSummaryViewModelTests (every new card with values, a pre-beta.14 row at N/A, the displayed low),
RenderScaleAndClocksTests (scale arithmetic, steps, flat line, limit runs, both charts drawn on the STA thread),
TrendSeriesBuilderTests, CompareViewModelTests (labels and bests), FormatsTests, GameDetailViewModelTests (Latency tab),
ChartMathTests (the clocks plot's colours too).

Docs: 08_UI (summary, trend, compare, latency), 03_METRICS (render scale over time), legal/ACCURACY.md (one bullet, mirrored
into README and DISCLAIMER by accuracy-check; Disclaimer version unchanged as in beta.13), guide/03-read-your-results,
LIMITATIONS, CHANGELOG. Strings en/vi, ja marked for review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 04:58:54 +07:00
poli0981andClaude Opus 5.5 5db18c9da9 feat(metrics): time below 30/60/refresh, frame to frame, VSync/tearing, the card's clocks and limits, frames per watt - recorded, schema 0019 (beta.14 PR-7, D49) (#270)
Owner request 2026-10-05 ("propose metrics and charts"); D49: all four groups. This is the Agent's half; the App's
charts, cards, trend and compare come in PR-8. Every value is null where nothing measured it.

Pacing (Domain.Metrics.FramePacing): the share of the measured time below 30 FPS, below 60 FPS and below the monitor's
refresh rate, and the mean |ft[k] - ft[k-1]| over neighbouring intervals (FrameTimeSeries.FollowsBreak: a pair across a
gap or pause is not a pair). A frame counts as below X when it is itself 10 % longer than 1000/X, or when the median of
the nine around it (RollingMedian, the stutter rule's window and edges) is 2 % longer. Measured on a copy of the owner's
ledger: GIRLS' FRONTLINE 2 capped at 60 (296,380 frames, median 16.63 ms) read 50.0 % "below 60" by the plain rule and
9.6 % by this one (4.7 % of it below 30); a rolling mean does not help. Synthetic: steady 58 -> 93 %, 60.2 -> 0.7 %, a
100 ms hitch counts its own time and no neighbour's; a steady 59 reads 40 % (the stated cost). 30/60/frame-to-frame are
over the statistics' series (application frames when generated frames were counted - rule 6); the refresh share is over
the presents, at display_monitor_hz.

Sync (PresentArgsShares): the share of presents with a sync interval >= 1 and with DXGI_PRESENT_ALLOW_TEARING - both in
every Direct3D record since P1 and read by nothing; sync_interval_mode (0001) gets its first writer (on/off/mixed). OpenGL
and Vulkan carry no arguments: null.

The card (both tiers): core/memory clock, fan, memory temperature - in the samples before, stored nowhere - as series and
averages; power and thermal limit from NVAPI's perf-decrease reasons (GpuLimitReasons: 0x2, 0x1; 100 or 0 per tick, so
the mean is the share), NVIDIA only, null elsewhere.

Efficiency (EnergyEfficiency, SessionAggregator.ApplyEfficiency): application FPS / average GPU board power. Never the
displayed rate; the native rate when frame generation was counted over the session, the presented rate only under
no_fg_runtime; null for census_not_run, fg_runtime_loaded, none_withheld, a steady-state session, no power, Tier 2.

Schema 0019: thirteen REAL columns, ADD COLUMN only; SessionRow, SessionRowColumns (Parameters6/Read6). The sensor
statistics table shows the six new series in their own units (Formats.Frequency, Formats.Rpm; strings en/vi/ja review),
because it lists every catalogued series and printed anything unknown as memory.

Tests: FramePacingTests, PresentArgsSharesTests (+ efficiency), FrameTimeSeries FollowsBreak, PacingSyncAndEfficiency-
AggregationTests (series, sync, efficiency per qualifier, both tiers, the catalogue's names, the limit bits), the
migration (LedgerDatabaseTests.ScriptNineteen...), the column-for-column round trip, the table's units.

Docs: 03_METRICS (Pacing, Sync, the card, Efficiency, accuracy rows), 06_DATA_MODEL (schema, sensor_blobs, 0019),
LIMITATIONS, Privacy Policy 2.7 section 1 (the card's sensor series), legal-drift-history (what 2.7 changed), CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 04:44:00 +07:00
poli0981andClaude Opus 5.5 d565760830 feat(build): every managed binary names FrameLedger and carries the native copyright line; versioninfo-check reads both kinds (beta.14 PR-6, D50) (#269)
Owner request 2026-10-05 ("Thêm Assembly metadata"); D50: company and product "FrameLedger", the copyright the
native FL_COPYRIGHT word for word.

Measured before the change, from the built binaries: FrameLedger.Agent.exe/.dll read Company and Product
"FrameLedger.Agent" and FileDescription "FrameLedger.Agent" (what Task Manager lists); each library its own assembly
name; every managed LegalCopyright was one space; the apphost's OriginalFilename is its assembly's (FrameLedger.dll).
tools/versioninfo-check.ps1 read the five native binaries and nothing else.

- Directory.Build.props: Company, Product, Authors, Copyright, Description (the native blocks' sentence, the Comments
  field), RepositoryUrl (stamped as AssemblyMetadata by the SDK); the FrameLedgerSourceRef metadata moved here from the
  App csproj, and release.yml passes the same ref to the Agent's publish.
- App: AssemblyTitle "FrameLedger" and a Description. Agent: AssemblyTitle "FrameLedger Agent" and a Description.
- versioninfo-check.ps1: the rules in one function over a block, a managed half (-ManagedDir, -ExpectedProductVersion -
  required, -ManagedOnly), one LegalCopyright across every binary read, the apphost carrying its assembly's block,
  Company as well as Product = FrameLedger, and -SelfTest: ten cases, nine RED, each for the reason it names (four
  mutations of the rules each turn the self-test red). build.ps1 runs the self-test and both halves (the managed half
  alone under -SkipNative); release.yml reads out/app with the tag's version.
- AssemblyIdentityTests (App, Agent): company, product, copyright = FL_COPYRIGHT parsed from CMakeLists.txt,
  description, RepositoryUrl = IssueLink.Repository, and the Win32 block Explorer shows. Red on the source before.

Docs: 12_BUILD (Identity table, the gate, the publish lines), 13_CI_CD, 19_SAFETY, FORKING (what a fork changes),
CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 04:33:07 +07:00
poli0981andClaude Opus 5.5 1f7aebd0a4 fix(capture): a crash is a crash report of this game or the engine crash reporter it started (beta.14 PR-5) (#267)
Owner request 2026-10-05 (prevention; example SILENT HILL 2, UE 5.1), and a false crash found on the
owner's ledger: The Witcher 3, 2026-10-04, exit code 0, stored crashed by a WER 1001
RADAR_PRE_LEAK_64 (Windows' memory-leak detector) whose P1 named witcher3.exe.

E1 - CrashEventMatcher (pure): a 1000 from "Application Error" counts only when its AppName [0] equals
the executable's, its AppPath [10] (when given) is the executable's, and its ProcessId [8] (typed)
is the session's pid; a 1001 from "Windows Error Reporting" only when EventName [2] is a crash report
(APPCRASH, BEX, BEX64, CLR20r3, MoAppCrash, MoBEX) and P1 [5] equals the name. EventLogCrashSource
filters by provider in the XPath and asks the matcher; ICrashEventSource.FoundCrash(CrashQuery).
Checked once against the owner's real Application log: the Witcher 3 window no longer matches.

E2 - CrashReporterWitness, fed by the watcher's 1 s snapshots (CaptureOrchestrator.PollOnceAsync):
every on-crash reporter (CrashReporterCatalog: CrashReportClient, CrashReporter, CrashReport,
BsSndRpt/BsSndRpt64) with its parent by pid, image and start (a pid reused by a later process is not
the parent); always-on handlers (UnityCrashHandler64/32, crashpad_handler) never. SessionRecorder asks
at the end (two more polls when the game just left, at most 2.5 s); CrashReporterRule counts it when it
started >= 10 s after the game and the game left within 60 s: crashed, notes crash_reporter=<image>;
otherwise a note crash_reporter_seen=. Unreal's crash (exit code 3, no event) is crashed now. No
process is opened. Formats.ExitText names the reporter (string en/vi/ja).

E4 - ExecutableLocator: "bssndrpt" and "bugsplat" are helper fragments (KCD2 picked its game by rank).

Privacy Policy 2.7 (section 4): the Application log's crash reports about a tracked game, and the names
of programs a tracked game starts (the first was read since P2 and not stated).

Tests: CrashEventMatcherTests (the real RADAR record shape, a hang, a name inside another, pid and path
ties, typed and hex values), CrashReporterWitnessTests, CrashReporterRuleTests, SessionRecorderTests
(exit code 3 + reporter = crashed and named; a game that kept running = note only), ExitStatusMapper,
CaptureNotes, ReasonText (ExitText), ExecutableLocator, EventLogCrashSource.

Docs: 04_CAPTURE (crash classification corrected in place), 19_SAFETY (crash safety), 06_DATA_MODEL
(note slots), LIMITATIONS (When a game crashed), CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 03:54:05 +07:00
poli0981andClaude Opus 5.5 101b6cf4d3 test(infra): the build-id mismatch check uses another id of the same length, not one longer than the field (beta.14) (#273)
ShmHandshakeValidatorTests.TheGuardReportsThisInstallsBuildId appended "x" to this install's build id and expected a
mismatch. The handshake's buildId holds 31 characters plus NUL, and the helper cuts at 31: once `git describe` is 31
characters long - ten commits after a tag, v0.1.0-beta.13-10-g15ec7c1c5fd4 in a local gate on 2026-10-06 - the cut id
equals the real one and the check read Ok. It passed for the first nine commits after every tag and failed from the
tenth, locally and on CI alike.

The mismatch is now another id of the same length (the last character changed), which can never be cut.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 02:59:31 +07:00
poli0981andClaude Opus 5.5 e8bb477415 test(app): the chart-wheel test says which keys are held instead of reading the machine's keyboard (beta.14) (#268)
A local ./build.ps1 check (PR-6) went red on ChartWheelTests.APlainWheelOverAChartScrollsThePageAndNotTheChart:
offset 0. Nothing in that gate touched the App. ChartWheel read Keyboard.Modifiers, which is the machine's real
keyboard from any thread - measured: a fresh background STA thread's GetKeyState reported the machine's NumLock - so a
Ctrl held anywhere while the test ran sent the plain wheel down the zoom path (page not scrolled). CI, with no person at
the keyboard, never saw it.

ChartWheel.CurrentModifiers (default Keyboard.Modifiers; the App never sets it) is what both handlers read; the test sets
it inside its own work item on the one STA thread and puts it back. The keys are a parameter now, so the Ctrl+wheel half
is driven end to end too (page stays, the surface ScottPlot zooms from is reached). A mutation that stops Ctrl+wheel at
the plot turns that case red.

Docs: 14_TESTING (a test that sends input says which keys are held), CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 02:20:27 +07:00
poli0981andClaude Opus 5.5 5ac1555a8b fix(guard): a scan-set member still loading or already gone is read again once before the guard refuses, and a refused re-scan of a game that has exited ends as its exit (beta.14 PR-4, D48) (#266)
Owner decision D48 (2026-10-05), from the crash-reporter question: the 30 s re-scan reads every process
in the game's tree; a member still being created (an engine's crash reporter as its game dies, any
helper started a moment before - EnumProcessModulesEx ERROR_PARTIAL_COPY) or gone between the snapshot
and the open (OpenProcess ERROR_INVALID_PARAMETER) refused the session as unreadable, ending it as a
safety unhook - which also ends a user-mode exception's trial for good.

Native (FrameLedger.Guard): Collected::kRetry, produced by EnumerateModules only for those two errors;
ACCESS_DENIED (a protected process) stays kFailed and is never retried. CheckModules runs one pass,
notes a kRetry and goes on (a finding anywhere still refuses at once), then Pause(kScanRetryPauseMs =
250) and a second pass over a FRESH scan set, where kRetry refuses as kProcessUnreadable and a gone
target leaves no set (kProcessTreeUnavailable). Sources::Pause seam (Sleep in SystemSources).
FindPresentationRuntime treats kRetry as "not yet". fl_prescan's chain ended in an implicit pass for
any new Collected value - it refuses anything but kOk now. fl-baseline-probe names the new value.

Managed: ExitScanRelabel - when the re-scan refused for ProcessUnreadable / ModuleScanFailed /
ProcessTreeUnavailable (never a finding) and the game itself has exited at conclusion, the session is
TargetExited (exit code decides normal/crashed), CaptureOutcome.ExitScanReason, notes
`scan_at_exit=<reason>` (CaptureNotes.ScanAtExit). Findings, live games and other checks unchanged.

Tests: ctest fl_guard [D48] (re-read clean; still unreadable refuses; exited member drops out; gone
target refuses; ACCESS_DENIED never retried; a finding refuses at once; a finding the re-read sees
refuses; [live]: a suspended process and a pid with no process answer kRetry against the real source),
CaptureSessionTests (relabel for the three reasons; live game, finding, driver failure unchanged),
SessionRecorderTests (the note and the exit status), CaptureNotesTests.

Docs: 19_SAFETY (check 1 amended; During a session), 04_CAPTURE, 14_TESTING, CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 02:02:46 +07:00
poli0981andClaude Opus 5.5 544a6c6202 fix(update): the channel follows the running copy, no update is applied at start behind FR-12, and the apply waits for a game still holding the Overlay (beta.14 PR-3, D47) (#265)
Owner request 2026-10-05: audit the update logic (no failure reported). Read against Velopack 1.2.0
and the owner's own updater log.

- update.channel defaulted to stable while every release is a GitHub pre-release: a copy left on its
  defaults never found one (the log: "No releases found" since the ledger reset). Owner decision D47:
  default `auto` (choices auto/stable/beta) - UpdateChannelPolicy: a pre-release copy asks for
  pre-releases, a release for releases; a stored stable/beta wins. Settings lists "Automatic (Beta)".
- VelopackApp applied a downloaded package at the next start (SetAutoApplyOnStartup is ON by default)
  inside Run(), before FR-12 and the Agent's stop - the log shows the Agent killed. Off now; the
  package is adopted at start (UpdateService.AdoptPending over UpdateManager.UpdatePendingRestart, no
  feed request) and goes Ready/Deferred like any other.
- OnBeforeUpdateFastCallback asks the Agent to stop before Velopack replaces the version (installer
  over an installed copy); Velopack's diagnostics go to the App's log (VelopackSerilogLogger).
- The apply waits while a game still has FrameLedger.Overlay.dll (or the Vulkan layer) loaded from the
  install folder (PayloadInUse: a mapped image refuses an exclusive write; no process opened), and
  while an Agent waits on the administrator prompt (ElevationMarker, beside the instance lock).
- Stop budget = IpcProtocol.AgentShutdownGrace (15 s, the Agent's host reads it too) + 5 s; was 10 s.
- The offer states the delta's size (UpdateInfo.DeltasToTarget) with the full package as fallback.
- IOException is Offline only from the network (HttpIOException, a socket error); the uninstaller
  removes the "Start FrameLedger with Windows" Run value.

Tests: UpdateChannelPolicyTests, UpdateServiceTests (pre-release copy asks for pre-releases; a stable
choice wins; a pending package is Ready without a feed request and applies; deferred under a session;
a held Overlay keeps it Ready, leaves the Agent alone and says why; the elevation marker holds the
folder; the stop budget outlasts the grace), VelopackHooksTests (private fields of the pinned 1.2.0
builder: _autoApply false, the logger, the before-update hook), UpdatePromptsTests, PayloadInUseTests,
UpdateFailureMapperTests, UninstallHookTests, SettingsViewModelTests, SettingsRegistryTests.
Strings en/vi/ja (ja marked review).

Docs: 11_UPDATER (the update audit, beta.14), 06_DATA_MODEL, 08_UI, 12_BUILD, LIMITATIONS,
guide/01-install, CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 01:46:24 +07:00
poli0981andClaude Opus 5.5 c1984cab74 feat(app): Settings > Window > Hide scroll bars - no bar drawn anywhere, every scroller still scrolls (beta.14 PR-2) (#264)
Owner request 2026-10-05: an option to hide the scroll bars but still scroll.

ui.hide_scrollbars (bool, default 0, App only - AgentReads false). A bar's visibility is bound inside
its scroller's template, so no style reaches it: Services/ScrollBarHiding registers one class handler
on ScrollViewer's Loaded at start (beside DialogKeyboard) and, while on, sets an Auto or Visible axis to
Hidden - WPF's "no bar, still scrolls" for wheel, keyboard and touch - keeping the scroller's own value
on it; a Disabled axis is never touched (it lays its content out at the viewport's width). The Settings
toggle applies to the open windows at once (posted to the dispatcher from another thread), and off puts
every kept value back. Read at start beside ui.fps_decimals.

Strings en/vi/ja (ja marked review). Tests: ScrollBarHidingTests (a plain scroller, a disabled one, a
DataGrid's, a multi-line TextBox's and a FlowDocumentScrollViewer's: on hides every bar and the wheel
still scrolls; off restores each scroller's own setting; one that loads while on is hidden and one that
loads after off is left alone), SettingsViewModelTests.HidingScrollBars..., SettingsRegistryTests.
The class joins the strings-culture collection (process-wide state, runs alone).

Docs: 06_DATA_MODEL (settings row), 08_UI (Settings), 16_WPFUI_SYNTAX (gotcha), CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 01:31:02 +07:00
poli0981andClaude Opus 5.5 32e3c5aa8e fix(app): the import list readable in the dark theme with whole tick boxes, and the mouse wheel scrolls every page, dialog and chart (beta.14 PR-1) (#263)
Owner report 2026-10-05 (screenshot of File > Import library in the dark theme; "the wheel does not
scroll, I have to drag the scroll bar").

Import list: the row style added in beta.11 was based on {x:Type DataGridRow}, which WPF UI 4.3.0 does
not define - it keys its row style DefaultDataGridRowStyle - so the lookup fell through to Aero2's row and
SystemColors.WindowBrush (white in every theme) under the dark theme's white text. Based on
DefaultDataGridRowStyle now. WPF UI's CheckBox (MinWidth 120, padding 11) drew a sliver of the box in the
40 px column: MinWidth 0, no padding. The dialog's own scrolling is off (ImportReviewPrompt.Create), so the
list takes the height the window leaves and is the one thing that scrolls; the intro and the count stay.
Compare's DataGridCheckBoxColumn (an Aero2 box) is a template column with the theme's CheckBox.

Wheel: NavigationViewContentPresenter makes ScrollViewer.CanContentScroll default to true for Page and wraps
such a page in a DynamicScrollViewer; the five pages' own root ScrollViewer then had infinite height,
nothing to scroll, and took every wheel. Every Page sets CanContentScroll="False"; page roots and the
session summary show their bar on Auto. The Logs tail is bounded again, so autoscroll follows the end.
Scrollers nested in dialogs are ui:PassiveScrollViewer. Charts/ChartWheel (through ChartTheme.Attach, all
nine plots): a plain wheel is re-raised on the plot's parent so ScottPlot never zooms; Ctrl+wheel zooms
and stops there.

Tests (each run red against the unfixed XAML first): ImportReviewRenderTests (every text cell >= 4.5:1
against the composited colour painted under it, Dark and Light; ticked boxes drawn whole, counted in a
RenderTargetBitmap; a 60-row list scrolls inside the list with the footer in view), AccessibilityTests
(no BasedOn a type the App's dictionaries hold no style for; no DataGridCheckBoxColumn; every Page opts out
of the DynamicScrollViewer; no plain ScrollViewer in a dialog), PagesLoadTests (pages navigated in the real
presenter are not wrapped and the wheel scrolls them; the Logs tail is bounded and follows the end; every
page reads CanContentScroll false after WPF UI's override), ChartWheelTests. Visuals/Wcag test helpers;
ContrastTests uses Wcag.

Docs: 08_UI (UX rules, Contrast's third hole), 16_WPFUI_SYNTAX (two corrections in place, five gotchas),
14_TESTING (what the App draws), guide/03 (Ctrl+wheel), CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 01:03:04 +07:00
poli0981andClaude Opus 5.5 0ffecb5851 release: 0.1.0-beta.13 - Velopack deltas in release.yml, the CHANGELOG section, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's train section and owner-only item 10 (#261)
* ci(release): publish a Velopack delta - download the previous release before vpk pack, keep only what this pack built, filter the feed to this build (beta.13)

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

* release: 0.1.0-beta.13 - the CHANGELOG section, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's train section with the one START HERE and owner-only item 10

VERSION stays 0.1.0: the tag's numeric core.

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

* test(capture): the four sessions that must end on a scan, a throw, the kill switch or an exit get a 30 s safety net instead of a 120 ms ceiling they raced on a loaded runner (beta.13)

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 09:39:53 +07:00
poli0981andClaude Opus 5.5 e77a130fc9 fix: a refusal for a driver or service says "on this PC", the unhook notice promises nothing untrue, the GPU sensors follow the game's adapter, and the language-changing tests run alone (beta.13 PR-1) (#260)
The four follow-ups the beta.12 documentation audit left as chips; three of
them here, the fourth (Velopack deltas) rides the release PR.

S23-3. The guard's checks 2 and 2b are machine-wide: while Easy Anti-Cheat's
service runs for another title, every game refuses with BlockedService, and
the notice read "Easy Anti-Cheat was detected in this game". CaptureRefused
and SafetyUnhook gain an optional guardReason (additive; reason stays the
session's end reason), and BlockedService / BlockedDriver read
Safety_Refused_MachineWide_Format, Safety_Unhooked_MachineWide_Format and
Summary_Tier2_Why_MachineWide_Format (en/vi; ja as an English copy awaiting
the human safety review, like its siblings). Safety_Unhooked_Format loses
"will not inject into this game again until you enable it again", untrue both
ways since 2026-09-22. Formats.NamedRefusal is the one place a named refusal
is worded; SafetyNotices and HookingConsentResult both use it.

L1's adapter. SelectAdapter had no caller, and fixing that alone would have
changed little: the composite merges L3 > L2 > L1 per field, and L2 and L3
read their own first GPU. CaptureProgress carries the handshake's AdapterLuid;
the recorder hands it to the poller once (noted in the .partial);
CompositeTelemetrySource.SelectAdapter points L1 at it (IGpuAdapterSelector)
and tells the other layers its vendor (IGpuVendorFollower): L2 maps that
vendor's LHM node, L3 contributes nothing for a non-NVIDIA adapter. What stays
first-found is written in 18_GPU_VENDOR_APIS and LIMITATIONS.

Culture races. The strings-culture collection serialized its own members but
ran beside every other class; it now has a definition with
DisableParallelization, and StringsTests asserts xUnit bound it.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 09:11:38 +07:00
poli0981andClaude Opus 5.5 ff43d8cdb3 release: 0.1.0-beta.12 - the CHANGELOG section, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's train section with the one START HERE and owner-only item 9 (#259)
The [Unreleased] entries move under ## [0.1.0-beta.12] - 2026-10-04 with a
summary for a user and the update notes from beta.11 (schema 0018; the
Legal Gate shows EULA 1.5 / Disclaimer 2.10 / Privacy 2.6 once; the GPL is
no longer accepted). The date is the local one, as beta.9 and beta.10 did
when their runs fell on the previous UTC day.

The accuracy block's release line moves in its three copies (ACCURACY,
README, Disclaimer - the precedent of beta.6-8: no version bump for the
release line). README's release list and count, LIMITATIONS' version line.

HANDOFF: the beta.12 train section (D43-D46, the traps, the code gaps the
documentation audit found and left for their own PRs) carries the file's
one START HERE, and owner-only item 9 lists what only real hardware and the
owner can check: the game's memory beside Task Manager, the Legal Gate, the
guide and About, the ja strings, and LIST_GAME_TESTED's refresh (D35).

VERSION stays 0.1.0: the tag's numeric core.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 01:52:22 +07:00
poli0981andClaude Opus 5.5 63808a3821 docs: about a hundred statements the code contradicted, corrected in place with dated notes; a developer index; the Logs page reads the Agent's lines; a Settings switch that did nothing removed (D46, beta.12 PR-6) (#258)
Four audits read docs 01-20, HANDOFF, CLAUDE.md and FORKING against the
code. Every stale statement is struck and followed by a dated correction,
the repository's own convention (D46); history stays as it stood.

The largest classes: a rules feed that does not exist (05, 11, 13, 19, 02
FR-7.3, the rules file's own $comment, the rules workflow's header -
rules reach a user with a release); hooks that were never built (01's
diagram, 17's XeSS row and detour count, 03's fgEvaluations sources); the
in-game watchdog described as reading two numbers and sleeping (17; the
Disclaimer was fixed in PR-5); the unhook path and the vtable-swap advice
(17); L1 never pointed at the game's adapter (18); pre-release steps that
would bump VERSION (13, CHANGELOG header); the Legal Gate's row count (08);
the logging configuration of the two processes (10); a delta package never
published (11, 14); missing 0009/0013 migration entries and a duplicated
0002 paragraph (06); closed items still marked open, and S23-3 marked
deferred while the refusal UI shipped without it (20); the stale START HERE
(HANDOFF); the layout, tools and static-analysis lines (CLAUDE.md); three
names a fork must also change (FORKING). docs/README.md is a new index.

Code found by the same audits:
- LogTail.LevelOf read only the App's "[HH:mm:ss.fff LVL]" prefix, so the
  Logs page's Warning and Error filters showed no Agent line; the Agent
  writes Serilog's default template, a date first. Both are read, with a
  strict timestamp shape; the test that fed App-form lines into the fake
  Agent log now uses the real form.
- Settings' "Record games launched outside FrameLedger" wrote
  capture.background, which no Agent code read, and the App cannot start a
  game, so "off" could only mean recording nothing. The switch and its two
  strings (en/vi/ja) are removed; the key stays reserved, AgentReads false.
- Comments that said what is not so: the sparkline, the flyout,
  VulkanLayerRegistered "false by construction", two self-test counts, the
  sensor blobs' nominal Hz, SessionRowColumns' missing generator.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 01:29:49 +07:00
poli0981andClaude Opus 5.5 f1e518f962 feat: a user guide in the app, the GPL shown for information rather than accepted, EULA 1.5 / Disclaimer 2.10 / Privacy 2.6, and a README for players and for developers (D44, D45, beta.12 PR-5) (#257)
- guide/: eight short English pages for players (install and first start, record a game, read your results, anti-cheat
  and safety, your data, questions and answers, the terms in plain words), embedded in the App and shown under
  Help > User guide - the first Help item - with Limitations last; links between pages open in the window.
  Help > Documentation becomes Online documentation: the README at this build's source.
- The Legal Gate: LegalDocument.RequiresAcceptance; the GPL is listed as "your licence", with a line saying GPLv3
  section 9 needs no acceptance, and Accept writes three rows (an old gpl row stays, unread). The summary names the
  user-mode exception (it said there was no way to override the refusal) and the one network request (it said nothing
  is sent anywhere).
- EULA 1.5: an unmeasured session also records the game's memory use; the GPL needs no acceptance; where the
  third-party notices are in an installed copy; consumer rights no agreement can limit, and severability.
  Disclaimer 2.10: what it reads about a game from outside it; the maintainers' preface moves to
  docs/legal-drift-history.md. Privacy 2.6: the game's memory use (replacing a video-memory figure never read), a new
  section 3A on what an export or a bug report carries about you; the history notes move to the same file.
- README: a pointer to the guide up front, the safety table's D38 rule and the feature list's memory line corrected,
  Tier 2 names the game's memory, NOTICE beside the licence, and a section for developers and forks.
- Strings: 3 new keys, 6 changed, en/vi/ja (ja marked review).
- Tests: GuideDocumentsTests (every page listed and titled, every link leads somewhere, the section anchor exists), the
  guide in the renderer's nothing-dropped test (17 documents), the guide window, three acceptance rows and the old gpl
  row left alone, the documentation link.
- Docs: 02_SPEC FR-11, 06_DATA_MODEL, 08_UI, 09_I18N, CLAUDE.md layout, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 00:51:27 +07:00
poli0981andClaude Opus 5.5 ca2275ce85 feat(app): documents rendered, not raw Markdown - the Legal Gate, Help > Limitations, the update notes and a tabbed About with the program's legal notices; links open this version's documents (owner request 4, D45, beta.12 PR-4) (#256)
- Markdown/MarkdownRenderer: Markdig 1.4.0 (BSD-2-Clause) into a themed WPF FlowDocument - headings with GitHub
  anchors, emphasis, strikethrough, code, quotes, nested and numbered lists, pipe tables, rules, links. HTML is off
  (shown as text), no image is fetched (its description stands in), an unknown node is shown as its source text. The
  GPL is shown as written, monospace.
- Controls/MarkdownView (FlowDocumentScrollViewer: selectable, Ctrl+C, zoom) and Markdown/MarkdownLinks: http, https and
  mailto through IUrlOpener, #section scrolls, a relative path resolves against the document's place in the repository
  and opens in the App when the window holds that page; file:, javascript:, drive and UNC paths are never followed.
- Services/RepositoryLinks: release.yml stamps -p:FrameLedgerSourceRef (the tag; a rehearsal's commit) as assembly
  metadata, so every link into the repository opens this version's documents instead of main's.
- The Legal Gate renders its documents (a link to another document opens it in the gate; View on GitHub goes through
  IUrlOpener); Help > Limitations is Windows/DocumentWindow; Help > About is Windows/AboutWindow - This app (the
  Appropriate Legal Notices: copyright, no warranty, the licence with the NOTICE terms, this version's source),
  Third-party licences (THIRD_PARTY_NOTICES and the package index, the licences folder), Legal documents (EULA, GPL,
  Disclaimer, Privacy, NOTICE, Trademarks). The update notes are rendered.
- Licences: tools/license-gather.ps1 takes a reviewed override for an expression it has no text for (sixteen self-test
  cases); tools/license-overrides/Markdig.txt; legal/licenses/nuget (78 packages); a THIRD_PARTY_NOTICES row, and its
  "About -> Third-party tab" item ticked. The table there had a note line between its rows, which ended it for Markdig;
  the note is below the table now.
- Strings: 22 new keys, 2 removed, en/vi/ja (ja marked review).
- Tests: MarkdownRendererTests (each construct; nothing dropped and no table left as source, for all nine embedded
  documents), MarkdownLinksTests, DocumentWindowsTests, the first-run opener, the legal documents' paths.
- Docs: 08_UI, 11_UPDATER, 16_WPFUI_SYNTAX (FlowDocument), 12_BUILD, 20_OPEN_QUESTIONS, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 00:22:50 +07:00
poli0981andClaude Opus 5.5 cc847c588e feat(app): the game's own memory wherever a session is shown - two summary cards, a stored statistics table, Sessions columns, Trend and Compare metrics, two memory charts, the live card, the CSV line (D43, beta.12 PR-3) (#255)
- Formats.Memory: Task Manager's units (MB below 1 GB, GB to two decimals, 1 GB = 1024 MB, null is N/A, never 0).
- Services.GameMemoryText: the summary's VRAM (this game) and RAM (this game) cards - the median with the peak and the
  shared / commit peak beneath - the Sessions grid's median · peak cells and tooltips, the live line, the CSV
  `# game_memory:` header line; all from the stored columns and sensor_stats_json. Where Windows reported no private
  working set the working set is shown and says so; an unpinned hold that summed several processes says how many.
- Services.SensorStatsTable + the summary's "Statistics per series": every stored series' mean / median / minimum /
  peak / readings in its own unit; a session recorded before beta.12 gets one sentence instead.
- SensorsChart: two memory plots in GB - Video memory (this game's dedicated and shared, the whole graphics card's)
  and Memory (this game's private working set or labelled working set, the whole PC's). The line that read the
  never-produced per-present vram_proc blob is gone.
- Trend: MaxVramProcess (vram_proc_max_mb, never written, so never a point) becomes Median / Peak VRAM (game) and
  Median / Peak RAM (game) in GB, machine metrics over both tiers; Avg RAM in use is labelled as the whole PC's, in GB.
  Compare gains the four rows, ranking nothing.
- Live card: MemoryText from SessionProgress / SessionHeld (the old VramText read a field nothing produced).
- Strings: 41 new keys, 4 relabelled, 5 dead ones removed, en/vi/ja (ja marked review); 09_I18N glossary rows.
- Tests: GameMemoryTextTests (new), summary, trend, compare, chart, live card, dashboard, export; GamesViewModelTests
  joins the culture collection (it compared resource text across a parallel culture flip and failed once).
- Docs: 08_UI (corrected in place, new beta.12 paragraph), 03_METRICS export schema, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 23:53:21 +07:00
poli0981andClaude Opus 5.5 2ce8251d31 feat: the game's own memory, measured from outside the game in every session - a C++ reader of the GPU Process Memory counters and GetProcessMemoryInfo, median and mean, schema 0018 (D43, beta.12 PR-2) (#254)
- FrameLedger.ProcessStats.dll (C++20, loaded by the Agent, never into a game): the game process's dedicated and shared
  GPU memory from the documented `GPU Process Memory` performance counters (no handle to the game, every instance of the
  pid summed) and its private working set / working set / commit from GetProcessMemoryInfo (EX2, falling back to EX)
  through PROCESS_QUERY_LIMITED_INFORMATION only (a sentinel refuses an EX2 answer whose private working set was not
  filled). Not D3DKMTQueryStatistics ("Reserved for system use").
  ctest fl_process_stats (GPU_INSTANCE on a hardware adapter, NO_GPU_INSTANCE on CI) and fl-probe-processstats.
- Measured first, decision table in spike-notes §16 written before the runs: +512.0 MiB for a 512 MiB buffer,
  private working set equal to Windows' own counter, 0.1 ms per read, nothing leaked over 600 reads; dedicated reads a
  constant 4.5 MiB above DXGI's local usage, so it is never compared with a budget.
- NativeProcessStats (third facade), GameMemoryReader: a pinned session reads through its held handle; an unpinned
  Tier-2 hold opens each process of the executable for the read, refuses a reused pid, sums. CaptureSession tells the
  observer which process (ICaptureObserver.Measuring), the recorder forwards it to the poller (ITelemetryPoller.Follow).
- TelemetrySample.Game; five sensor series; schema 0018 (game_vram_dedicated_*, game_ram_private_*, ..., sensor_stats_json);
  SeriesAggregates gains Median and Min; a wide .partial sensors chunk (type 8) with type 4 still read; SessionProgress
  and SessionHeld carry the game's memory live.
- notice-check accepts a contributor's own copyright line in the same form.
- Tests: the two classes that open a LibreHardwareMonitor Computer run one at a time - GenericCpu.Update threw a
  NullReferenceException in the local gate when they ran in parallel (the Agent's own read is already contained).
- Docs corrected in place: 03_METRICS, 18_GPU_VENDOR_APIS, 17_HOOK_ENGINE, 20_OPEN_QUESTIONS (§M7, §H10, new §M11),
  04_CAPTURE, 19_SAFETY, 06_DATA_MODEL, 07_IPC, 02_SPEC, 01_ARCHITECTURE, 12_BUILD, CLAUDE.md; the accuracy block and
  LIMITATIONS.md.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 23:21:45 +07:00
poli0981andClaude Opus 5.5 ff949afc6f feat(legal): NOTICE with the GPLv3 section 7 additional terms, the licence header in every source file, and the documents for people who build, contribute or redistribute (D45, beta.12 PR-1) (#253)
- NOTICE: copyright, GPL-3.0-only, and three additional terms of the kinds section 7 permits - (b) preserve the
  notices and the attribution in the program's legal notices, (c) mark a modified version as different and do not
  call it "FrameLedger" alone, (e) no trademark rights in the name. Shipped as licenses\NOTICE.txt; release.yml
  refuses a published tree without it.
- Section 7 wants additional terms named in the source files: every first-party .cs .cpp .h .inl .ps1 .xaml file
  (1,053; src/native/third_party excluded) opens with the SPDX line and a pointer to NOTICE. tools/notice-check.ps1
  is the gate (six self-test cases, both directions; -Fix writes a missing header) and tools/resx-gen.ps1 generates
  the string accessors with the header.
- The native VERSIONINFO LegalCopyright said GPL-3.0-or-later; it now names the real licence.
- CONTRIBUTING.md, FORKING.md, CODE_OF_CONDUCT.md (Contributor Covenant 2.1 by reference), legal/TRADEMARKS.md.
- 12_BUILD gate list, CLAUDE.md layout and conventions.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 22:16:00 +07:00
poli0981andClaude Opus 5.5 3fb27c8df4 test: the recorder's session harness no longer depends on how many drains a loaded runner fits into 150 ms (beta.12 PR-0) (#252)
main went red at a1b06d2 on SessionRecorderTests.ASessionThatRecordedNothingEndsTheExceptionOnlyDuringItsTrial(1,true):
expected Saved, got Discarded. The loop is bounded by MaxDuration on the wall clock, the session's length comes from the
SteppingClock (+5 s per drain), and a busy hosted runner fitted fewer than six drains into 150 ms - under the 30 s
minimum. The harness's minimum is now one clock step: SuperviseAsync drains at least twice (once in the loop, once
after it), so every hooked session is over it on any machine, and a held session whose clock never moves stays under
it, which is what ARefusedSessionIsATierTwoRow... asserts.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 22:01:48 +07:00
poli0981andClaude Opus 5.5 a1b06d28be release: 0.1.0-beta.11 - the CHANGELOG section, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's train section (#251)
* release: 0.1.0-beta.11 - the CHANGELOG section, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's train section

The eleventh pre-release (owner, 2026-10-03: "bump beta11"). The [Unreleased] entries of
#247-#250 move under ## [0.1.0-beta.11] - 2026-10-03 as written, after a summary for a user
and "Updating from 0.1.0-beta.10" (quit the App and the Agent first; schema 0017 adds one
column and an older version cannot open the database again; every game is re-checked once
under rules 2026.10.1; an exception made under beta.9 or beta.10 stays in force and finishes
its trial). The sub-sections' bullets are separated as beta.10's are.

The accuracy block's date and release line (legal/ACCURACY.md and its two verbatim copies,
README.md and legal/DISCLAIMER.md; accuracy-check), README's release list and count
("Eleven tagged pre-releases"), LIMITATIONS.md's version line, and HANDOFF's section for the
train: decisions D38-D42 and the CrackProof choice, the traps met on the way, and owner-only
item 8 (what only real hardware can check in beta.11). VERSION stays 0.1.0; the tag carries
the pre-release suffix.

release-notes.ps1 -Version 0.1.0-beta.11 extracts the section (7,728 characters).

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

* docs(safety): the trial paragraph says what a short or unhooked session is not judged by - its frames and its exit - and that a crash while hooked or a finding still ends the exception for good

19_SAFETY's D38 paragraph said a session too short to be stored, or never hooked, "proves nothing
either way and is not judged". UserModeExceptionLapsePolicy judges it by the D33 ends all the same:
a crash while hooked, however short, or a finding about the game at the start, ends the exception
for good during the trial; what such a session is not judged by is its frames and its exit (it
neither counts toward the two nor fails the trial that way). Found in a last read before the tag.

UserModeExceptionLapsePolicyTests pins the short crash: EndOf answers SessionCrashed for a hooked
session that crashed and was not stored, in the trial. ./build.ps1 check: ALL GATES PASSED.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 12:07:15 +07:00
poli0981andClaude Opus 5.5 c4e47868dd feat: delete all sessions of a game or of every game, charts across a game's sessions, and no Settings row without a control (D39, D40, beta.11) (#250)
* feat: delete all sessions of a game or of every game, charts across a game's sessions, and no Settings row without a control (D39, D40, beta.11)

Owner requests 2026-10-03; when asked, the owner chose both charts (an overview on the Sessions
tab and several metrics on the Trend) and both places for Delete all sessions (the game's page
and Settings > Data).

Delete all sessions (D40, FR-1.7):
- A pipe request, DeleteSessions { gameId? } -> DeleteSessionsAck { gameId?, games, sessions }.
  The rows are the Agent's (06_DATA_MODEL Writer ownership), so the Agent deletes them through
  ISessionRepository.DeleteSessionsAsync in one transaction - segments, frame and sensor series and
  annotations cascade - and answers Error SessionRunning while a session of that game (of any
  game, for all; CaptureOrchestrator.IsRecording / IsRecordingAny) is being recorded.
- App: SessionDeletion asks; the game page's Sessions tab and Settings > Data (a new section, one
  row) ask first through IConfirmations.DeleteSessionsAsync with the count; the strip says what
  was deleted or why nothing was (a recording, no agent, an older agent). The game page reloads
  and clears File > Export's selection when it pointed at a deleted session (ids are reused).

Charts across sessions (D39, FR-6.6):
- The Sessions tab opens with "Sessions at a glance": every hooked session's Presented FPS, or
  Native and Displayed where frame generation was measured (rule 6), and the 1% / 0.1% lows,
  oldest first, partial sessions hollow (TrendSeriesBuilder.Overview); a click near a session's
  points selects it in the grid (TrendChart.SessionClicked).
- The Trend keeps its selector and adds "Also draw": ticked metrics are drawn on the same chart,
  their unit (TrendSeriesBuilder.UnitOf: FPS, degC, %, W, MB, x) on the left when it is the
  selected metric's and on the right when it is a second one; a third unit cannot be ticked.
  TrendChart.Show takes TrendLines; one line keeps its name on the axis as before.

Settings, no row without a control (owner request): the hooked-games card shows only while a game
has hooking on; the Elevation row became the admin mode row's status line; the language note is
gone; the retention message names Settings > Recording.

Strings en/vi/ja (ja marked review); docs 02_SPEC (FR-1.7, FR-6.6, FR-10), 06_DATA_MODEL, 07_IPC,
08_UI; CHANGELOG. Tests: repository delete + cascade; the handler's delete and its malformed
payload; IsRecordingAny; SessionDeletion's outcomes; the game page asks, deletes through the
Agent and reloads; Settings asks with the total; the overview and the two-unit Trend; units.

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

* fix(app): the overview draws Native and Displayed only for sessions that generated frames - on the others Native is the Presented rate, and a second line on the same points read as a second measurement

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

* fix(app): after Delete all sessions, a summary window open on a deleted session closes and File > Export lets go of it - from Settings too

The plan for D40 said the summary windows of deleted sessions close; they did not. A summary is
a window of its own, so after a delete it stayed open on a session that is gone, and a note
written from it would have gone to whichever session takes the id next (the table has no
AUTOINCREMENT). And File > Export's selection was let go of only by the game page: a delete from
Settings > Data left it naming a deleted session.

Both now happen in SessionDeletion, the App's one path to DeleteSessions, after the Agent
answers Deleted: the selection is cleared when its session is no longer in the ledger
(ISessionRepository.FindByIdAsync - a session of another game stays selected), and the summary
windows close the ones whose session is gone (ISessionWindows, which SessionSummaryOpener now
implements over the windows it opened; DI registers the one opener under both interfaces). A
failure there is logged and not the delete's. The game page's own clearing moved there.

Tests: AfterADeleteWhatNamedADeletedSessionLetsGoOfIt (the selection cleared, a kept session
still selected, the windows asked after each delete and not after a refused one); the game page
test builds its SessionDeletion with the selection. 08_UI and the CHANGELOG entry say it.
./build.ps1 check: ALL GATES PASSED (App 399).

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

* fix(app): Delete all sessions closes only the summary windows still open after the ledger read - one the user closed meanwhile is not closed twice

SessionSummaryOpener.CloseDeletedAsync awaits a read per window; a window the user closed during it
has left the list (its Closed handler removes it), and WPF's Window.Close on a closed window can
throw. Each window is closed only while it is still in the list. ./build.ps1 check: ALL GATES PASSED.

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

* fix(app): the Trend unticks a metric left in a third unit when the selected metric changes - every ticked box has its line

With two units ticked beside the selected metric (degC and a frame rate, say), changing the selected
metric to a third unit (watts) left three units ticked; TrendChart draws two, so one box stayed ticked
naming a line that was not there. BuildTrendLines now keeps the selected metric's unit and the first
ticked unit in the list and unticks the rest, before it sets which options can be ticked.

Test: TheOverviewAndTheTrendDrawSeveralMetricsTwoUnitsAtMost goes on to tick degC and the 1% low,
select watts, and finds two units drawn and one line per ticked box. 08_UI says it.
./build.ps1 check: ALL GATES PASSED.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 11:44:00 +07:00
poli0981andClaude Opus 5.5 c48b1348a7 feat(app): the Games library fills the window, switches to a list, counts and refreshes its games; import hides what is already in it (beta.11) (#249)
* feat(app): the Games library fills the window, switches to a list, counts and refreshes its games; import hides what is already in it (beta.11)

Owner requests 2026-10-03 (screenshots): the empty band right of the library; a manual refresh
for when games are installed or uninstalled; import's games already in the library, dimmed or
hidden. The owner chose, when asked: the refresh does all three (reload, new games from the
stores, mark uninstalled games), and the view switches between a filling grid and a list.

Library (Games page):
- Controls.UniformWrapPanel: as many columns as fit at 300 px or wider, every card an equal share
  of the width, each row as tall as its tallest card - the cards were 300 px in a WrapPanel, so a
  card's width went unused at the right. The pill row wraps instead of cutting its last pill.
- A list view (name, store, engine, status, sessions, played, last played; double-click or Enter
  opens a game); the button beside the sort shows the other view; ui.library_view remembers it.
- The title counts the games ("Games - 42").
- Refresh reads the library again, then ImportLibraryFlow.RunAsync(onlyNew: true) asks the stores
  for games installed since ("No new games" and no checklist when there are none), and every
  entry whose executable is not on disk carries a "Not installed" pill whose tooltip names the path
  and says when the drive itself is not connected (ExecutablePresenceProbe, off the UI thread on
  each listing, never stored; nothing is removed).
- The page reloads itself while 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 showed only after leaving the page.

Import (FR-1.2): the games already in the library - at this path or under another drive letter -
are hidden by default; "Show the N games already in the library" brings them back dimmed; a row
that cannot be imported has its box disabled (the XAML said "cannot be ticked" while a tick was
taken and ignored).

Strings en/vi/ja; 08_UI, 06_DATA_MODEL (ui.library_view), CHANGELOG. Tests: GamesViewModelTests
(reload on import and session end, not after Detach; presence; column math), ImportLibraryFlowTests
(refresh offers only new games; hidden until asked), PagesLoadTests (the grid fills its width; the
list replaces it and is remembered; the checklist renders with existing rows shown). Rendered to
PNG in a hosted window to look at it (1270 px: three columns; 900 px: two; the list).

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

* refactor(app): the library's Not installed pill reads the file the game page's way - GameLibrary.ExecutableExists and its sentence - instead of a second probe and two more strings

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 10:48:22 +07:00
poli0981andClaude Opus 5.5 0e03d07dac feat: the user-mode anti-cheat exception needs no earlier sessions - its first two are a trial that ends it for good if one goes badly (D38, schema 0017, Disclaimer 2.9, EULA 1.4) (#248)
The owner deleted their ledger and found GIRLS' FRONTLINE 2 "Not eligible: 0 successful hooked
session(s), two are needed" - for good. D33's rule was a catch-22 for every game it could meet
again: since beta.8 the library sweep blocks a game the moment it is added, a blocked game is
never hooked without a grant (CaptureSession sends it to Tier 2 before the resolver), so it could
never earn the two sessions, and a reset ledger lost the ones it had. Asked with that (2026-10-03),
the owner chose D38: a grant needs no session; the first two hooked sessions under it are a trial;
any end during the trial ends the exception for good.

Agent / Application:
- UserModeExceptionRules: TrialSessions = 2 replaces RequiredSessions; IsEligible(block, verdict,
  trialFailed) - the guard's answer and the trial mark, no count; InTrial(successfulBefore).
- UserModeExceptionLapse.TrialFailed; UserModeExceptionLapsePolicy judges a session against the
  grant in force: during its trial every D33 end, or a stored hooked session with no frames or an
  abnormal exit, revokes it with trialFailed; a session too short to store, or never hooked, is
  not judged. The recorder passes the row it stored (SessionForTrial).
- ISessionRepository.CountSuccessfulUnderGrantAsync (family + started >= grant) replaces
  CountSuccessfulHookedAsync; ac_exception_sessions is now the trial's progress.
- AgentCommandHandler: TooFewSessions is gone; a game whose trial failed is refused before
  anything is scanned (Refused TrialFailed, signal = unix ms). AntiCheatExceptionCommands drops
  the session repository.
- The sweep answers a blocked entry whose executable cannot be read ("PreScanFailed", no bytes in
  the key) instead of leaving it "Checking..." for ever.

Infrastructure: schema 0017 games.ac_exception_trial_failed_at; the revoke sets it once
(COALESCE), eligibility is never written eligible over it and a grant is refused over it, both in
SQL; Change executable does not name it; a twin merge keeps the earlier mark.

App: the disclosure is ac-exception-dialog/2 (Why names no count, a Trial paragraph); the card
says "trial: N of 2", a failed trial "none can be made again", a scan that found nothing "was not
found" (not "could not finish"); an eligible game's Anti-cheat card no longer says "cannot be
turned on" beside Make exception...; the Settings list shows only games it can act on, without
the duplicated count, and Refresh only while a row is checking. Strings en/vi/ja (ja safety text
English until reviewed).

Docs and legal: CLAUDE.md rule 2 amendment, 19_SAFETY, FR-2.8, 06_DATA_MODEL (0017), 07_IPC,
08_UI, 20_OPEN_QUESTIONS, LIMITATIONS, SECURITY, the accuracy block (README, Disclaimer),
Disclaimer 2.9 (2A), EULA 1.4, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 10:25:42 +07:00
poli0981andClaude Opus 5.5 5ab297b7b7 feat(rules): three CrackProof titles on the anti-cheat title list - Umamusume, Heaven Burns Red, Madoka Magica Magia Exedra by Steam id (rules 2026.10.1, beta.11) (#247)
The owner asked for "a few" games protected by HyperTech's CrackProof, by Steam id where needed.
Three are listed, each on the evidence of its own Steam store page, which states "Uses Kernel
Level Anti-Cheat" and names CrackProof (read 2026-10-03):

- 3224770 Umamusume: Pretty Derby (Cygames)
- 1973710 Heaven Burns Red (WRIGHT FLYER STUDIOS / Key; the Steam app is the Japanese release)
- 2987800 Madoka Magica Magia Exedra (Aniplex)

ANOTHER EDEN (1252600) is named by a community list (AreWeAntiCheatYet) but its store page says
nothing of the kind, so it is left out.

Why a title list and not a family: a Proton log of Umamusume shows the driver loaded from
C:\Windows\System32 under a numbered name (usrdrv017864.sys, ValveSoftware/Proton#8853) - outside
the game's folder, so the .sys rule cannot see it before the first run, and no driver token
could name it. Steam ids only: no executable name was verified, and a guessed one is a false
refusal waiting for an unrelated game. A title-list finding is never excepted by the user-mode
exception.

- rules/detection-rules.json: blockedStoreIds +3 (family "CrackProof"), rulesVersion 2026.10.1 -
  every library entry is pre-scanned again once; the floor regenerates from the file.
- guard_test: the three ids refuse as BlockedStoreId naming CrackProof, from the floor.
- 19_SAFETY check 3 (counts, the evidence, why no executables) and a seed-table row like VAC's;
  20_OPEN_QUESTIONS S14's row; CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 10:06:50 +07:00
poli0981andClaude Opus 5.5 ebea4a7eda release: 0.1.0-beta.10 - the CHANGELOG section, the accuracy block's release line, README's release lines (#246)
The tenth pre-release, the owner's four beta.10 items: the exact Unreal Engine version on a game's page (#241, schema
0015); the display mode - exclusive full-screen, borderless, windowed or minimised, as a share of each session, with the
window's and the monitor's size - on the summary, the game page, the Trend and Compare, both tiers (#242 shared-memory
layout 4, #243 schema 0016); running the capture agent as administrator, off by default, with a UAC prompt at every
agent start and games kept standard-user (#244, D34); and the documents - LIMITATIONS.md (Help > Limitations), the
owner-approved list of games tested, Privacy 2.5 and Disclaimer 2.8 (#245, D35, D36). Same unsigned installer; the
Legal Gate opens once for Privacy 2.5 and Disclaimer 2.8; the EULA is unchanged (1.3). A game running while the update
is installed must be restarted before it can be measured (layout 4).

HANDOFF's beta.10 section already names `[0.1.0-beta.10]` as its status.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 17:32:19 +00:00
poli0981andClaude Opus 5.5 372389c521 docs: what FrameLedger cannot do, the games it has been run with, and the legal text for beta.10 - LIMITATIONS.md in the App, the tested-games list, Privacy 2.5, Disclaimer 2.8 (D35, D36) (#245)
Item 4 of the owner's beta.10 request (update the docs at the end, add a list of real games tested) and owner decisions
D35 (the list from a COPY of the owner's ledger plus the repository's evidence, reviewed by the owner before commit)
and D36 (legal text where it would become false, and a user-facing LIMITATIONS.md for the whole software).

- LIMITATIONS.md (repository root): the limits of the whole software in the user's words - the games it will not
  measure, an unmeasured session, frame generation, upscaling and ray tracing, the display mode, the engine version,
  sensors, the admin mode, platform and tested hardware, data, installation - each linked to its details. Embedded in
  the App (LimitationsDocument) and shown under Help > Limitations with Open on GitHub; NOT one of FR-11's accepted
  documents. LimitationsDocumentTests: embedded as written, not in LegalDocuments.Keys, every repository link exists.
- docs/LIST_GAME_TESTED.md: 22 games measured hooked, the unmeasured sessions and why, six refused by the guard, and
  the Unreal versions read without running - from a copy of the ledger (read in the scratchpad with Python sqlite3,
  never a FrameLedger binary on the data folder) and spike-notes, CHANGELOG, HANDOFF and the run reports. Approved by
  the owner 2026-09-27, with Alan Wake 2's two 2026-09-04 captures added and UMIGARI kept on its run reports.
- Legal: Privacy Policy 2.5 (a game window's display facts, the Unreal build name, and - first said here - the
  executable's content and the processor/memory counters); Disclaimer 2.8 (section 5A, the admin mode and its risk; the
  limitations page and the list in section 0); the accuracy block dated 2026-09-27 with the display mode, the engine
  version and the admin mode (README and DISCLAIMER copies, accuracy-check green); SECURITY.md's admin-mode reports.
  EULA unchanged (1.3).
- Stale text corrected in place: 19_SAFETY's ETW Tier-2 offer, README's Agent row and elevation paragraph, 04_CAPTURE's
  port list, HANDOFF D11's pipe owner check, 17_HOOK_ENGINE's fault policy (compare-and-restore, not MH_ALL_HOOKS),
  HANDOFF's "Alan Wake 2 did not run on 2026-09-04", and the 18-vs-9 session count recorded rather than guessed.
- HANDOFF: the beta.10 train (D34-D37, what was measured, the traps), owner-only item 7 (beta.10 on real hardware) and
  item 6 done by the ledger's evidence (three GF2 sessions under the exception); CLAUDE.md's reading order names both
  new documents; 08_UI's Help menu; CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 17:02:56 +00:00
poli0981andClaude Opus 5.5 7ad1519a4c feat: run the capture agent as administrator - an option off by default, a disclosure, and a UAC prompt at every agent start; games stay standard-user (D34, beta.10) (#244)
* feat: run the capture agent as administrator - an option off by default, a disclosure, and a UAC prompt at every agent start; games stay standard-user (D34, beta.10)

The owner asked for a Settings option, off by default, to let the Agent run with administrator rights. Owner decision D34
(2026-09-27): Windows is asked at EVERY Agent start - by the App, or by the logon task's Agent - with no silent path, and
games started from an elevated Agent must not run elevated.

- Setting capture.run_elevated (registry, Agent-read), read BEFORE the Agent exists by Infrastructure.Startup's
  RunElevatedSetting: one row, PRAGMA query_only, no version gate (the first start after an update meets an older
  schema), anything but "1" is off.
- App: AgentLauncher asks through a UAC prompt owned by the main window (ShellHost.Handle) and starts the Agent with
  --serve --for-user <SID>; declined or failed, it starts the standard user's Agent with --elevation <outcome>; an
  elevated Agent that exits 11 (another account answered) makes it start standard-user Agents until the App restarts.
  With the option off and the App elevated, the Agent gets the desktop shell's token. The connection shows
  AgentConnectionState.Elevating while the prompt waits.
- Agent: --serve takes at most one of --for-user <SID> (refuses to run as another account: exit 11, before anything is
  claimed or written) or --elevation declined|other-account|failed. A plain --serve with the option on and no elevation
  (the logon task's) holds the folder's ElevationMarker, asks Windows once (taskbar prompt), and hands over to the
  elevated Agent once it has claimed the folder - or serves as before and says why. HelloAck.ElevationOutcome carries
  the answer; an elevated Agent logs its enabled privileges.
- Games: ProcessLauncher in an elevated Agent starts the game with the shell's token (UnelevatedProcess: GetShellWindow,
  the token duplicated, CreateProcessWithTokenW, the kill switch's explicit environment) and refuses with error 1400
  rather than start it elevated. LaunchGame is reachable by any process of the user; an elevated launch would be a
  silent elevation.
- Locks: the ledger's migration lock is a SharedMutex with a stated DACL (owner the user; user, Administrators, SYSTEM),
  so an elevated creator no longer locks the unelevated App out; the elevation marker keeps two prompts from racing.
- Privileges: nothing enables one. TokenPrivileges reads them; chokepoint-check forbids AdjustTokenPrivileges,
  RtlAdjustPrivilege, EnterDebugMode and SeDebugPrivilege under src/ (canary checked); PrivilegeFootprintTests asserts on
  the elevated CI runner that the resolver and LibreHardwareMonitor's CPU group enable none.
- Settings: "Run the agent as administrator" with the versioned disclosure (Shared Safety_AdminMode_*, agent-admin-dialog/1;
  ja = the English pending review, vi translated), then a restart over the pipe - never under a running session - and the
  elevation line says why a standard user's Agent is one. Safety_Refused_TargetUnreadable names the mode.
- Updater: the apply also waits for the data folder's instance lock to be let go; an Agent holding it without answering
  is never updated under.
- Tests: setting reader (no ledger, no table, "1"/"0"), marker, account check, SharedMutex SDDL + wait/release,
  environment block, shell-token start (elevated runs only), privilege footprint, CLI surface, Settings toggle
  (declined writes nothing; accepted writes, stops, retries; a running session defers), elevation words, Elevating pill,
  launcher marker, updater held-folder cases.
- Docs: 01_ARCHITECTURE ADR-9, 19_SAFETY elevated targets, 20_OPEN_QUESTIONS G (closed: chosen, not inherited),
  06_DATA_MODEL settings, 02_SPEC FR-10, 12_BUILD flags, 07_IPC (HelloAck, prompts, stated DACLs), 08_UI Settings,
  11_UPDATER, 18_GPU_VENDOR_APIS, 04_CAPTURE launch; CHANGELOG.

No hook-path change: the Overlay is untouched.

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

* test: the admin mode's two tests as the hosted runner measured them - a variable keeps the process's own name casing, and the runner's token arrives with SeDebugPrivilege on

CI on #244 (run 36332900944) failed two of the new tests, both on facts of the hosted runner rather than of the code:

- The environment block keeps an existing variable's own casing ("Path" there, "PATH" on the dev box) when the caller
  overrides it - Windows compares names without case, so the value replaces it rather than standing beside it. The
  test now finds the one PATH entry case-insensitively and checks its value.
- The runner's token ARRIVES with SeDebugPrivilege enabled (an administrator's service), so "nothing enabled before
  anything ran" was false there. The footprint test now asserts that nothing it runs NEWLY enables a powerful
  privilege, and names what was already on in its message.

The third failure of that run, TargetResolverTests.OneInstanceResolves (TargetNotRunning), is the hosted-runner flake
the test's own comment records from 2026-09-04; this PR does not touch the resolver.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 23:49:16 +07:00
poli0981andClaude Opus 5.5 5a890553b2 feat: the display mode - how each game was shown and for how much of the session, both tiers, on the summary, the game page, the trend and compare (schema 0016, beta.10) (#243)
The owner asked for the game's window size and display mode (exclusive fullscreen / borderless / windowed) and the share of
the session each took, with trend and compare. PR-2 (#242) published the swap chain's own answer in shared-memory region 4;
this change reads the window from outside, classifies, tallies, stores and shows it.

- Domain/Display: DisplayModeClassifier (no window -> minimised -> exclusive, only from a region-4 sample under 2 s old ->
  covers its monitor: borderless when the chain said not exclusive, "fullscreen or borderless" when nothing could say ->
  windowed), DisplayTally (milliseconds, not ticks: a sample stands for the time until the next), DisplaySummary.
- Application: IDisplayProbe; DisplaySampler on the capture loop's tick beside focus (100 ms hooked) and on the Tier-2
  hold's tick (1 s) - an interval ending on a paused tick is dropped; ITargetResolver.PidsOf finds a hold's processes by
  image path in the watcher's snapshot (never by name, never an unreadable path), still opening nothing;
  CaptureOutcome.Display; the recorder writes it on the row's skeleton (SessionDisplayColumns), so a Tier-2 row has it.
- Infrastructure: WindowGeometryProbe - user32 out of process, per-monitor DPI aware (V2) while it asks and put back; the
  window region 4 names when it still belongs to the game (to its root), else the largest visible, uncloaked, non-tool
  top-level window of the game's processes; MONITORINFOEX + EnumDisplaySettings for the monitor and its refresh rate.
  Nothing belonging to the game is read (CLAUDE.md rule 4). Schema 0016: fifteen sessions.display_* columns, ADD COLUMN
  only; sessions.swap_effect gets its first writer.
- Composition: the Agent's CaptureSession and the operator host's take the probe.
- App: a Display stat card and line on the session summary, the last measured session and a Display column (tooltip with
  every share) on the game page, three Trend metrics (exclusive / borderless / windowed share, every tier, never left out
  as a mid-session change, no exclusive or borderless point where the two could not be told apart), three Compare rows
  (never ranked), the CSV's "# display:" line (invariant). Strings en/vi/ja; Strings.Designer.cs regenerated.
- Tests: classifier and tally (Domain); sampler on a moved clock, pause, staleness, swap-effect names; CaptureSession Tier 1
  from region 4 + window and Tier-2 hold by the snapshot's pids; recorder Tier-2 row and hooked row; LatestProcessSnapshot
  pids; migration 0016 and the repository round trip; WindowGeometryProbe against hook-harness's real window; App card,
  line, game page, trend, compare, export, DisplayText.
- Docs: 03_METRICS (new section Display mode, accuracy row, export header), 04_CAPTURE, 05_DETECTION (runtime facts row;
  present mode still has no writer), 06_DATA_MODEL (DDL + 0016), 08_UI, 02_SPEC (FR-7.4, FR-7.2 note), CHANGELOG.

No hook-path change: the Overlay is untouched by this PR (its cost was measured in #242).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 23:15:28 +07:00
poli0981andClaude Opus 5.5 a4b18e698c feat(overlay): shared-memory region 4 - the presenting swap chain's exclusive state, window and back buffer, polled twice a second (layout 4, beta.10) (#242)
The owner asked for the game's window size and display mode (exclusive fullscreen / borderless / windowed) and the share of
a session each took. Two of the facts that decide it only the process knows: whether the swap chain is in exclusive
fullscreen, and which window it presents to. This change publishes them; the Agent's window geometry, the classification,
the storage and the App follow in the next PR of the train.

- fl_shm.h layout 4: FlDisplayState, a 64-byte region at 0xC0 (the ring moved to 0x100; FlWriterState had no slack left).
  A seqlock the writer never waits on: a presenting thread that finds it taken skips the sample. DXGI_SWAP_EFFECT is
  stored plus one (DISCARD is 0, the vendor-zero trap).
- Overlay: the present hook asks GetFullscreenState(&fs, nullptr) and GetDesc at most every 500 ms per chain - getters
  on the chain the title passed, the same object FindOrAdd already described (CLAUDE.md rule 4); the chain with the
  largest back buffer is described, and one silent for 2 s gives way. SetFullscreenState stays unhooked on purpose: DXGI
  leaves exclusive fullscreen by itself (focus loss, Alt+Enter) without the title calling it. The periodic GetDesc also
  refreshes every record's output size, closing the unhooked ResizeBuffers1 hole on D3D12. OpenGL publishes the window
  and client size it already read, with no exclusive bits.
- Managed: ShmLayout mirror + FlDisplayFlags; ShmRingReader.DisplayState takes a consistent copy (eight attempts, a full
  fence between copy and re-check); ICaptureSink/ShmCaptureSink expose it. Nothing consumes it yet.
- Tests: hook-harness --hold-presenting-hwnd (the first DXGI fixture with a window); fl_guard "[display]" checks the region
  names the harness's own window, its back buffer, windowed and a second sample; the OpenGL case checks its region; the
  mirror test covers the region and now fails a struct the dump emits but nothing mirrors.
- Overhead (hook-harness --probe-frames, 3 runs, WARP): GetFullscreenState 12.6-13.1 ns/call, GetDesc 13.6-14.5 ns/call,
  paid at most twice a second per chain - under 1 ns per present at 60 fps, plus one QPC comparison per present.
- Docs: 07_IPC (layout 4 + region 4; the FlWriterState block showed reserved[5] where the header had none), 17_HOOK_ENGINE
  (SetFullscreenState row: polled, not hooked), 15_ROADMAP, 11_UPDATER (pre-1.0 practice for the MAJOR rule).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 22:46:01 +07:00
poli0981andClaude Opus 5.5 32fdcf82f3 feat(detection): the exact Unreal Engine version from the shipping executable, and the witness it rests on (beta.10) (#241)
The owner asked for the exact Unreal Engine version on a game's page. The rule could not give one: it read only the
executable's ProductVersion string, which most shipping executables leave empty, and its pattern
`\+\+UE(4|5)\+Release-(\d+\.\d+)` had two capture groups of which the evaluator returns the first - so every Unreal
version ever stored was a bare "4" or "5".

Measured first, read-only, on the owner's ten installed Unreal titles: the numeric file version is the engine's in seven,
a studio's own in three; the engine's branch name (UTF-16 `++UE5+Release-5.1`) is in the bytes of five - in .rdata in
four, 290 MB into .code in Black Myth: Wukong's protected executable (whose .rdata is 8 KB).

- Domain: UnrealVersion.Decide weighs the two witnesses (branch + agreeing file version -> M.m.p; branch alone -> M.m;
  a file version that reads as an engine's where nothing says the studio replaced it -> M.m.p; else nothing), and
  EngineVersionSource names the rung. The ten measured titles are its test cases.
- Rules 2026.09.6: the unreal extractor is `unreal_build` (a fourth oneOf branch in the schema, no parameter);
  StaticGameDetector makes the second read for the one engine that matched, never the probe for every game.
- UnrealBuildReader: the version resource, then the branch name in .rdata (or the whole file, bounded at 1 GiB, when
  .rdata is under 1 MiB), 4 MB chunks with overlap so a cut name is never read short, cancellation between chunks.
  Through the shipped reader on the same ten files: every version as measured, 16 ms to 1.1 s each, 7.5 s for Black
  Myth on the owner's USB drive.
- Schema 0015: games.engine_version_source, written only with a version the row took; the old rule's bare "4"/"5"
  removed only where field_provenance says detected.
- rules-validate: a version pattern must compile and capture exactly one group (canary: the old pattern is red).
- App: the game page's Details say which witness an Unreal version rests on, or that none was found.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 22:14:49 +07:00
poli0981andClaude Opus 5.5 a7329fc45c release: 0.1.0-beta.9 - the CHANGELOG section, the accuracy block's release line, README's release lines, HANDOFF's status pointer (#239)
The ninth pre-release: one narrow exception a user can make, per game, for a game whose only
anti-cheat runs in user mode and that FrameLedger has measured hooked at least twice (owner
decision D33): the guard's tolerance and the Overlay's channel (#236), the Agent's eligibility,
grant, marks and ends with schema 0014 (#237), and the option, the list, the disclosure and the
legal text in the App (#238). Same unsigned installer; the Legal Gate opens once for the
Disclaimer 2.7 and the EULA 1.3 (owner's leave 2026-09-26). The Privacy Policy is unchanged.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:29:22 +00:00
poli0981andClaude Opus 5.5 f32c10d758 feat(app): the user-mode anti-cheat exception in Settings and on the game page - its option, its list, its versioned disclosure, and the legal text that says it (D33) (#238)
Owner decision D33 (2026-09-26), beta.9 PR-3 of 4, on the guard (#236) and the Agent (#237).
This is the part a user sees; every state it shows is the Agent's, read from its columns,
and every grant is the Agent's to make.

- Settings > Capture: "Allow hooking in games with user-mode anti-cheat that were measured
  before" (hooking.usermode_ac_exceptions, off by default) and under it the User-mode
  exceptions list - eligible games (Make exception...), games held back only by the session
  count, games carrying an exception (Withdraw), each with its finding, its successful hooked
  sessions and its state. Off, only kept exceptions are listed, suspended. "Checking..." until
  the Agent has answered about every blocked game; Refresh re-reads.
- The disclosure: AntiCheatExceptionPrompt / AntiCheatExceptionDialogContent over the new
  Safety_Exception_* family (Shared, versioned by AntiCheatExceptionDisclosure.Version; ja
  English verbatim marked for review). Why it is offered, the risk at the same grain as FR-2.1's
  dialog (a ban possibly days later, invisible to FrameLedger), what is still refused, how it
  ends, that it turns nothing on, offline/single-player; the primary button bound to the ticked
  "I accept the risk of a ban for this game", Enter = Keep it blocked.
- AntiCheatExceptions: the handshake on HelloAck.ExceptionDisclosureVersion (no dialog against
  other text), then SetAntiCheatException; Granted / Withdrawn / Refused (TooFewSessions, the
  guard's finding, BlockNotExceptionable, could not verify) / OptionOff / VersionMismatch /
  AgentUnavailable, each said in the user's language.
- The game page: a User-mode exception card (ExceptionView over GameRow.AcException) - eligible,
  checking, not eligible and why (too few sessions; "the guard also found Kernel driver in the
  game folder (NEPKernel.sys)"; "... is not user-mode throughout"), in force, suspended, ended
  and why. An exception in force brings the Hooking card back even while anti-cheat cards are
  hidden, its switch usable through FR-2.1's dialog, the finding still under it.
- Marks: the library card says Exception; a session hooked under one is "Hooked · exception"
  in the Sessions tab (tooltip names the family) and has a line in its summary.
- Legal (owner-approved): Disclaimer 2.6 -> 2.7 (sec. 2A describes the exception and its risk;
  sec. 2's "no setting" sentence points to it), EULA 1.2 -> 1.3 (the code-injection clause
  names it), the accuracy block (all three copies, re-dated 2026-09-26), SECURITY.md (what in
  the exception is a security report), README's Hard refusal row. Privacy stays 2.4. The Legal
  Gate re-shows the two changed documents.

Tests: AntiCheatExceptionsTests (handshake, declined sends nothing, our version sent, the
Agent's answers, withdrawal needs no dialog, the button waits for the tick),
GameDetailViewModelTests (eligible offers it; in force makes the switch usable; off =
suspended; the card says Exception; why not eligible - one session, Aniimo's driver, a
kernel-level family), SettingsViewModelTests (off by default; the list follows the Agent's
columns; off lists only a kept exception).

Docs: 08_UI (the game page card, the Settings list), 09_I18N (Safety_Exception_*),
20_OPEN_QUESTIONS (the decision recorded, what stays the owner's), 19_SAFETY (status),
CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:16:06 +00:00
poli0981andClaude Opus 5.5 9b5d1cd486 feat: the Agent grants, keeps and ends a user-mode anti-cheat exception - eligibility from its own facts, the Overlay told first, every re-scan naming the family, schema 0014 (D33) (#237)
Owner decision D33 (2026-09-26), beta.9 PR-2 of 4, on PR-1's native half. Nothing in the
App asks for an exception yet (PR-3 adds the option, the list and the disclosure); this is
everything the Agent does once something does.

- The option: hooking.usermode_ac_exceptions (SettingsRegistry, off by default, Agent-read)
  behind IUserModeExceptionSwitch. Off suspends every exception and deletes none.
- Eligibility: AntiCheatPreScanSweep asks each BLOCKED entry, while the option is on, one
  question - a tolerant pre-scan naming the block's family (PreScanGameAsync(exe, family)),
  keyed on the rules, the executable and the block text so it re-runs only on a change -
  and counts ISessionRepository.CountSuccessfulHookedAsync every pass (hooked, frames,
  exit_status normal). UserModeExceptionRules.IsEligible: a module/file/folder block, the
  guard let exactly that family through, >= 2 sessions. A block is still never scanned for
  a new one and never cleared.
- The grant: SetAntiCheatException {gameId, enabled, disclosureVersion} (07_IPC). The
  Agent's disclosure version (AntiCheatExceptionDisclosure.Version, also in HelloAck), the
  option on, an exceptionable block, then the Agent's OWN facts - a tolerant pre-scan of the
  file on disk and the session count - and the store writes the grant only over facts that
  make the game eligible (ConsentWriteOutcome.NotEligible otherwise), bound in SQL to the
  block they were reached about. A grant turns nothing on: hooking is FR-2.1's SetHookEnabled,
  which under an exception in force names the family and answers prescan "exception".
- The session: HookRequest.FromConsent derives ToleratedFamily from the stored grant only
  (UserModeExceptionRules.CoveredFamily: option on, grant on these bytes, block naming that
  family) and only when the Overlay's channel was published first
  (IOverlayToleranceChannel -> Infrastructure.Capture.OverlayToleranceChannel, the
  Local\FrameLedger.Tolerate.<pid> mapping with a stated O:<user>D:P(A;;GR;;;<user>) DACL, a
  name already taken refused). The gate hands the guard the NAME; GuardSupervisor names it
  to every 30 s re-scan. A blocked row whose exception does not apply is hooking-off before
  the process is opened. The hooked session is marked (sessions.ac_exception_family,
  "; ac-exception=<family>" in the notes, CaptureNotes reads it, CSV header line).
- The end: UserModeExceptionLapsePolicy after the row is stored - NewFinding (a finding
  about the game at the start or the re-scan), SafetyUnhook, OverlayStopped, SessionCrashed
  while hooked; the sweep ends a grant on other bytes (ExecutableChanged, with the option off
  too) or one the facts no longer support (NoLongerEligible - never on a scan that could not
  look); Change executable ends it; the user withdraws it (Withdrawn). An end turns hooking
  off while the block stands and keeps the consent stamp and the grant's history.
- Schema 0014: fourteen games.ac_exception_* columns (eligibility + key, grant, end) and
  sessions.ac_exception_family, ADD COLUMN only. GameRow.AcException, GameConsentRecord
  .Exception, StoredBlock (Reason|Family|Signal read back).
- IAntiCheatGuard: every method takes string? toleratedFamily - required, so every caller
  states which it means; still four methods of int/string/CancellationToken
  (NoSecondMatcherTests unchanged but for the note).

Tests: UserModeExceptionRulesTests, UserModeExceptionLapsePolicyTests, D33 cases in
AntiCheatPreScanSweepTests (option off asks nothing, keyed question, live count, title list
never asked, the Aniimo shape, ends), HookRequestFromConsentTests, HookedCaptureGateTests
(both entries), GuardSupervisorTests, CaptureSessionTests (the channel before the injection,
option off / other bytes -> hooking-off without opening the process, a failed channel is no
exception, a start-time finding), SessionRecorderTests (the mark; a crash ends it),
AgentCommandHandlerTests (disclosure/option, facts, refusals, SetHookEnabled under it,
withdrawal), SqliteGameConsentStoreTests, SqliteSessionRepositoryTests, LedgerDatabaseTests
(0014), OverlayToleranceChannelTests (read by the user, write refused, squatted name, NUL/
newline), IpcCodecTests, SettingsRegistryTests.

Docs: 02_SPEC (FR-2.3 note, FR-2.8), 04_CAPTURE (the gate's one branch), 06_DATA_MODEL (schema
0014, the setting, writer ownership), 07_IPC (SetAntiCheatException, HelloAck, SetHookEnabled,
section D built), 19_SAFETY (status), HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 21:22:22 +00:00
poli0981andClaude Opus 5.5 01d3afd504 feat(guard): the native half of the user-mode exception - the guard tolerates one named user-mode family and keeps scanning, and the Overlay learns it before its loader detour exists (D33) (#236)
Owner decision D33 (2026-09-26, beta.9 PR-1 of 4): a per-game exception for anti-cheat
that is user-mode throughout, bound to evidence (>= 2 successful Tier-1 sessions), chosen
with CLAUDE.md rule 2 and D22 quoted back. This PR is the part the guard and the Overlay
own; nothing asks for it yet (NativeAntiCheatGuard passes no family), so every game is
judged exactly as in beta.8. The Agent's half is PR-2, the App's and the legal text PR-3.

- ABI: FlGuardEvaluate, FlGuardedInject, FlGuardedInjectWhenReady and FlStaticPreScanGame
  take `const char* toleratedFamilies` - family NAMES, never evidence; nullptr/"" is
  today's behaviour. No new entry point, and nothing of the withdrawn bypass comes back.
- fl::guard::FamilyIsUserModeOnly / ResolveTolerance / MatchNameTolerating: the guard
  itself decides which names it honours - a family with no drivers or services entry and
  no .sys among its files, in the floor AND the rules file (the floor cannot shrink, so
  data can make a family kernel-level and never the reverse). At most 8 names.
- Tolerant scans keep scanning past a tolerated hit (module sink, CheckModules, the tree
  walk), so a second family, a suspicious module or a .sys further in still refuses - the
  load-order fail-open S22(b) closed for the exemption. A .sys is refused whichever family
  matched it. Title lists, drivers, services, the fuzzy tier, scan failures,
  TargetUnreadable, WOW64 and the kill switch are untouched; the Vulkan branch evaluates
  strictly (the layer's self-scan goes inert on any anti-cheat module).
- kAllowedUserModeException = 28 (the slot the withdrawn bypass left): an allow that names
  the family and signal it let through. Managed: AntiCheatRefusalReason
  .AllowedUnderUserModeException, AntiCheatVerdict.RanUnderException / AllowedUnderException;
  IsFindingAboutTheGame stays false for it; Refused() cannot carry either allow.
- fl_tolerance.h: Local\FrameLedger.Tolerate.<pid>, FlTolerance (16 + 8 x 64 = 528 B), the
  Agent's channel to the Overlay BEFORE injection (the ring is the Overlay's, created after
  its detour would need the answer). Mirrored as Shared.FlTolerance / ToleranceLayout and
  held by ShmLayoutMirrorTests through fl-layout-dump.
- Overlay: InitThread reads the mapping once, before InstallLoaderHook, resolves each name
  against its own compiled floor and honours only a user-mode family (a 64-bit mask over the
  floor's module families, logged as TOLERANCE). Hook_LoadLibraryExW tests one bit before
  the early stop.
- NativeAntiCheatGuard: the parameter crosses as NUL-terminated UTF-8 byte[] (CA2101 rejects
  [MarshalAs(LPUTF8Str)] string), the shape FlGuardCheckRules already used.

Overhead: the present path is unchanged - no per-frame hook body was edited. The loader
detour gains one acquire load of a uint64, a shift and a compare on the floor-match branch
only (a branch taken approximately never); the mapping is read once on the init thread.

Tests: guard_test [D33] (6 cases, 73 assertions): the user-mode matrix, ResolveTolerance,
the allow and its family/signal, everything outside the family still refusing (EAC named,
BattlEye after NEP2, a suspicious module, vgk.sys, vgc, a title list, the Aniimo shape with
NEPKernel.sys, an incomplete walk, an unreadable process), the pre-scan answering as the
chokepoint does, and an integration case: a decoy NEP2.dll loaded 2.5 s after injection
does not stop the Overlay when the mapping names NetEase Yidun, and does when it names
Easy Anti-Cheat. AntiCheatVerdictTests, ShmLayoutMirrorTests, ReasonTextTests follow the
new reason.

Docs: CLAUDE.md rule 2 (amendment D33), 19_SAFETY (new section The user-mode exception,
cross-references), 17_HOOK_ENGINE (the detour note, overhead), 07_IPC (section D, the
tolerance mapping), HANDOFF (the beta.9 train: decision, evidence, traps), CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 20:33:40 +00:00
poli0981andClaude Opus 5.5 1a655237f5 release: 0.1.0-beta.8 - the CHANGELOG section, the accuracy block re-dated and extended, README's release lines, the Privacy Policy 2.4, HANDOFF's status pointer (#235)
The eighth pre-release: anti-cheat found before anyone asks (#227-#229), what a
game's files and the NVIDIA driver say about it (#230, #231), reasons that read
as what they are (#232), a Trend that works and FPS with two decimals (#233),
and a frame-generation session's numbers and charts over application frames
(#234). Same unsigned installer; the Legal Gate opens once for the Privacy
Policy 2.4 (owner's leave 2026-09-25: it names the library-wide anti-cheat check,
the files' version information and the NVIDIA driver's per-game settings).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 17:06:15 +00:00
poli0981andClaude Opus 5.5 9e7eed6351 fix: a frame-generation session's lows are over application frames, a pause is a gap and not time, and the charts draw what they say (#234)
Owner request 2026-09-25 (beta.8, item 8: fix the charts that are not reasonable). Measured first on the
owner's Onimusha demo capture (DLSS FG x3, read from a copy of the ledger): generated frames are submitted
half a millisecond after their application frame, so the stored median over presents read 2,073 FPS on a
60 FPS game, and the chart's "native" line was each frame's interval to the generated one before it.

- Domain: FrameTimeSeries.ApplicationFrames (application frame to application frame; a gap or an uncounted
  present breaks the chain); MeasuredSeconds - D leaves out every interval a gap sat in, so AverageFps is the
  kept intervals over the seconds they span; RecordWindow.SecondsOf and FgWindow.From take the gap set.
- Application: SessionAggregator takes median / lows / min / max / sigma / stutter over application frames
  where generated frames were counted (segments too), the Displayed 1% low over presents, and no frame
  statistic when a technology was named and no application frame counted. CaptureSession marks a gap before
  the first record stamped at or after the resume's QPC (test red before the fix). SessionFinalizer writes
  frame_blobs.first_present_ms (schema 0013).
- App: SessionSeriesLoader charts the dominant swapchain, application-frame intervals, every present when
  all were generated (noted), sensors on the frames' axis when the blob says where the first present is,
  Tier-2 sensors alone. FrametimeChart: labels (Application frames / Presents), no 0 ms frames after gaps,
  a note on present timing and closed-up gaps, segment labels, the overlay only when aligned.
  DistributionChart: histogram over p0.5-p99.5 with centred bars and an outside count; PercentileCurve
  drawn where ten frames lie beyond each side (FR-4.8 generalised) with the 1% / 0.1% lows marked.
  SensorsChart: watt axis, "Memory", VRAM 0 left out, distinct colours in both themes (light Percentile
  was SensorSecondary's gold), both tiers; the summary window gets a Sensors section. The game page
  reloads when one of its sessions completes.
- The live 5 s window reads the survivors' rate over a drop, not the survivors spread over the lost time.
- Docs: 03_METRICS, 04_CAPTURE, 06_DATA_MODEL, 08_UI, HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 16:52:59 +00:00
poli0981andClaude Opus 5.5 aba58dfd7d fix: the Trend tab draws on first open with Native and Presented as two metrics, FPS can show two decimals, and every steady-state factor carries its share (#233)
Owner request 2026-09-25 (beta.8, items 6 and 7: does Trend really work; FPS with up to two
decimals behind a setting).

- Trend: the page draws what the view model holds when it is made (the load finished before
  the page subscribed, so every first open was blank); the date axis is made before the theme
  and the label (DateTimeTicksBottom replaced the axis and dropped both); "Average" is two
  metrics - Presented FPS on sessions that counted no generated frame, Native FPS where frame
  generation was measured - and the tab opens on Native when the newest measured session counted
  generated frames; machine metrics count Tier-2 sessions; partial points (settings changed, or a
  steady state for Native/Displayed/factor) are hollow with a note; one hardware marker per day;
  the metric list in the page's language; the empty text names the metric.
- FPS decimals: ui.fps_decimals (off by default; Settings > Window), FpsDecimals holder read at
  start and moved at once, Formats.FpsNumber "62.40" / "62", rounded half away from zero.
- Rule 6: the readout line (Average card, Compare) and the Sessions grid's FG column carry the
  steady share; "Lifetime average" is labelled as the last measured session it is.
- Compare: the best cell's accent colour (a local Foreground outranked the trigger), best as
  shown (ties by displayed text), loads unranked, the 0-100 percentile axis (AutoScale ran after
  SetLimitsX), and PNG exports with an opaque background (ChartTheme.SavePng).
- Docs: 08_UI, 06_DATA_MODEL (ui.fps_decimals), HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 16:39:06 +00:00
poli0981andClaude Opus 5.5 2c02978b5b fix: reasons read as what they are - End task is not a crash, a refusal no anti-cheat names is not "detected", every end reason has its words (#232)
Owner request 2026-09-25 (beta.8, item 5: clearer reasons - 32-bit game, exe missing,
process killed...).

- Exit classification: a crash is an exception's exit code (NTSTATUS 0xC0000000-0xC0FFFFFF
  but 0xC000013A, 0xE06D7363 C++, 0xE0434352 .NET, 0x80000003) or the event log's witness;
  End task's 1, a program's -1, Ctrl+C are ordinary ends with the code in the notes.
  CrashAutoDisablePolicy takes the exit code too and still counts every non-zero exit in
  its window (the safety did not loosen); its row reason says "ended abnormally".
- capture_notes: the guard slot has three positions, guard=Reason|Family|Signal, none
  dropped and no ';' inside one (an empty family used to be dropped and the signal read as
  the family; a ';' in a signal cut it). Old rows are read by the rule that separates them:
  findings and the gate's own refusals carry a family, every other reason's second part
  was its signal. exit_code, crash_event and the new launch_error are read back.
- A launch that cannot start keeps Windows' reason (IProcessLauncher.Start(..., out
  win32Error), a default interface overload; CaptureOutcome.LaunchError).
- App: every SessionEndReason has its sentence (Formats.EndReasonText, enum-walk test);
  every familyless guard refusal says what happened (Formats.GuardSentence) in the
  summary, the safety notice and the enable-time refusal instead of "<signal> was
  detected in this game"; the summary says how it ended ("crashed (0xC0000005 access
  violation)", "ended with exit code 1 - what End task and taskkill leave"); the missing
  executable bar and notice say whether the drive or the file is missing.
- Docs: 04_CAPTURE (classification corrected, notes format, launch error), 19_SAFETY (crash
  safety counts abnormal ends), 08_UI, HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 16:02:50 +00:00
poli0981andClaude Opus 5.5 7d6b670173 feat: a session records the NVIDIA driver profile it ran under, and says what the NVIDIA App overrides - DLSS preset and mode, frame generation, Smooth Motion (#231)
Owner request 2026-09-25 (beta.8, item 4: detect whether the NVIDIA App overrides DLSS
settings - FG, RR, the model preset - through NVAPI).

- NVAPI bridge ABI 2: FlNvDriverProfile(exePath, ids, count, out) reads, through DRS, the
  profile the driver applies to an executable (FindApplicationByName on the full path;
  none named -> the current global profile) and the value, location and "someone set it"
  of each id asked. Read-only: a session is created, loaded, read and destroyed; the
  bridge has no DRS setter. A path too long for NVAPI's string is refused, never
  truncated. FlNvDriverProfileSize for the mirror.
- The ids and their values' meanings are NVIDIA's NvApiDriverSettings.h (MIT), written as
  Application.Capture.NvidiaDriverSettings (18 constants, no header vendored); Smooth
  Motion is community-documented only and labelled so.
- NvapiDriverProfileSource (IDriverProfileSource) over the bridge; SessionRecorder reads
  the profile beside every session (both tiers), bounded at 5 s, and a failed read costs
  the column, never the session. Schema 0012: sessions.driver_profile (DriverProfileRecord
  JSON). ngx_driver_words keeps ratio/mode/preset/fg fields beside its masks.
- App: the session summary says the profile and what it overrides ("DLSS override (preset K,
  Quality) - Frame Generation override (x4, latest preset)") and what the driver reported
  applying in the game's process from its override bits; the game page's Details card has
  an "NVIDIA App override" row from the newest session that read one. Configuration, never
  a measurement (03_METRICS).
- Fixed: ctest fl_nvapi_bridge passed on its branch line alone (PASS_REGULAR_EXPRESSION
  ignores the exit code) while its reference-counting check failed on every GPU machine;
  the check is corrected and a FAIL_REGULAR_EXPRESSION added.
- Docs: 18_GPU_VENDOR_APIS (ABI 2, read-only DRS, the ctest trap), 03_METRICS, 06_DATA_MODEL
  (0012), 08_UI, HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 15:49:57 +00:00
poli0981andClaude Opus 5.5 efcee1d08d feat: the game page says what the game's files say - x64 or x86, file and store versions, the DLSS/FSR/XeSS files it ships - and a 32-bit game's hooking cannot be turned on (#230)
Owner request 2026-09-25 (beta.8, item 3: game version, DLSS/FSR versions, 32/64-bit).

- Schema 0011: games.exe_machine / exe_file_version / exe_product_version /
  library_versions, written whole by the detection sweep (DetectionWrite). A NULL
  exe_machine is stale once, so every library entry is read under this build.
- PeImports.ReadArchitecture: the COFF machine and, for .NET, the CLR header's flags
  (Domain.Detection.ExecutableArchitecture: x64 | x86 | arm64 | arm | anycpu |
  anycpu32 | other | unknown) - an AnyCPU assembly carries an I386 machine and runs as
  64-bit unless it prefers or requires 32-bit.
- GameFileProbe: the files a capability rule names, with the numeric version of their
  VS_FIXEDFILEINFO (bounded at 48); RuleEvaluator.NamesFile shares the matcher.
- Known not hookable (x86, anycpu32, arm64, arm): SetHookEnabled answers
  Refused ExecutableNotX64 before anything is scanned or stamped; the sweep turns off
  hooking on a row enabled before this build (hook_autodisabled_reason); the page
  disables the switch with the reason and offers no re-enable. A switch that is on can
  still be turned off.
- App: a Details card (runs as, file/product version, store build labelled with its
  store, engine, shipped libraries), the subtitle says "Steam build 20374416", and the
  session summary lists the runtime libraries (runtime_modules, recorded since P2 and
  shown nowhere) against the copy the game ships.
- Rules 2026.09.5: fsr gains ffx_fsr3*.dll, xess gains libxess_dx11.dll (+ fixture).
- Docs: 05_DETECTION (what the files say about themselves), 06_DATA_MODEL (0011),
  07_IPC (ExecutableNotX64), 08_UI (Details, loaded libraries), HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 15:34:41 +00:00
poli0981andClaude Opus 5.5 653e2991db feat: the Agent pre-scans the library for anti-cheat, and an anti-cheat game's page shows the finding instead of its hooking switch (#229)
Owner decision 2026-09-25 (beta.8, item 2, HANDOFF D32): hide the hooking part of
anti-cheat games, and find which games those are without waiting for anyone to ask.

- AntiCheatPreScanSweep (Application) + AntiCheatPreScanHostedService (Agent --serve):
  every library entry through the guard's advisory checks 3 and 4 (PreScanGameAsync),
  at start, every 15 s and at once after UpdateRules; once per rules version and
  executable. Skips a blocked row, an unreadable executable and an entry whose session
  is running. Gates nothing: every session start still runs checks 1-4.
- Schema 0010: games.hook_prescan_rules_version / _exe_size_bytes / _exe_mtime_ms, the
  sweep's own key. Change executable clears it with hook_prescan_state.
- IGameConsentStore.RecordPreScanAsync: a finding is the block every other moment
  writes (consent stamp kept), a pass is 'clean', a scan that could not answer is
  'unverified'; the UPDATE itself never writes over a block and never adds a row.
- hook_blocked_reason is stored as Reason|Family|Signal; the App says it in the
  user's language (BlockedReasonText); older rows are shown as stored.
- HookingTurnedOff IPC event, only when the sweep turned off hooking the user had
  turned on: a persistent notice of its own kind (Dismiss, no "record without
  measuring" - no session is running).
- App: ui.hide_anticheat_hooking (default on). The game page shows an Anti-cheat card
  in place of the Hooking card; off, the card is back with the switch disabled and the
  finding under it. The library card says "Anti-cheat" (the caution pair ContrastTests
  already measures). A blocked row no longer offers the crash auto-disable's re-enable.
- Docs: 19_SAFETY (the fourth moment; the enable-time row corrected to checks 3+4 over
  the install root), 02_SPEC FR-2.2/2.7, 06_DATA_MODEL, 07_IPC, 08_UI, HANDOFF D32 +
  traps (and owner-only item 3 marked taken by D30), CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 14:36:04 +00:00
poli0981andClaude Opus 5.5 79f21422a3 feat(guard): check 3 is live in both halves and seeded; any kernel driver in a game's folder is a finding; the pre-scan sees the install root (#228)
beta.8 PR-2, the owner's strictness decisions of 2026-09-25 (HANDOFF D30, D31).

- Check 3's store half: Sources::StoreIdentity reads the store's own metadata from the install root the guard
  derives itself - the Steam library's appmanifest_*.acf whose installdir is the game's folder, or a GOG
  goggame-<id>.info - so no caller hands in evidence (S3) and nothing is read from the game (rule 4). Matrix: listed
  refuses (BlockedStoreId); no store identity is not refused; unreadable store metadata refuses (PreScanFailed).
- rules 2026.09.4 seeds both per-title lists - 30 Steam app ids, 33 executables across nine families (VAC titles,
  Riot, Roblox, Blizzard, Call of Duty, NetEase, ACE, HoYoverse, EA) - and floors them like the families, so data
  can add a title and never remove one. kMaxTitleRules 64 -> 128 (the floor doubles the worst case). rules-validate
  refuses generic executable names, exact rules without .exe, and duplicates, and checks the 2x capacity.
- The kernel-driver rule: a *.sys file in the install tree that no files entry names is AntiCheatFile under
  "Kernel driver in the game folder". Code, not data; a named entry (randgrid.sys) keeps its own family.
- FlStaticPreScan(gameDirectory) -> FlStaticPreScanGame(exePath), and IAntiCheatGuard.PreScanGameDirectoryAsync ->
  PreScanGameAsync(executablePath): SetHookEnabled passed the exe's own folder and the guard scanned exactly that, so
  an Unreal title's root-level EasyAntiCheat folder was never seen by the enable-time scan. The guard now resolves
  the install root itself and runs check 3 there too. The port keeps four methods.

Tests: native fakes gain the store seam; new cases for the store matrix, the driver rule, the root resolution and
check 3 in the advisory scan; the real seam against a Steam library and a GOG folder built in %TEMP%; the floor
reproduction and the minimal-file test cover the title lists.
Docs: 19_SAFETY checks 3 and 4, the VAC row; 20_OPEN_QUESTIONS S14 closed and the S24 count; 05_DETECTION; HANDOFF
D30/D31 and traps; CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 13:59:28 +00:00
poli0981andClaude Opus 5.5 80df94a934 feat(rules): the anti-cheat blocklist names twenty-two families through more signals; the guard holds 256 entries (#227)
The owner asked for the anti-cheat set to be as large and as strict as possible (beta.8, PR-1).

- rules 2026.09.3: 11 families / 19 entries / 30 values become 22 / 74 / 142. New: EA AntiCheat, Activision
  Ricochet (19_SAFETY's "no data yet" row), NetEase Anti-Cheat, NetEase Yidun, Nexon Game Security, TenProtect,
  AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat, Roblox Hyperion; existing families gain drivers, services,
  folders and files (BEDaisy.sys, FACEIT.sys, ESEADriver, HoYoKProtect.sys, xhunter1, denuvo-anti-cheat.sys...).
  Every new token is documented, not measured, and its note says so. Services that run outside play are left out
  (EAAntiCheatService, PnkBstrA, Denuvo's updater). New modules rows are appended (early_stop_family is an index).
- kMaxFamilies 64 -> 256 (2 x 74 worst case); schema maxItems follows. Rules is 541,736 bytes, so it is reset in
  place (ResetRules) rather than assigned from a stack temporary: the Vulkan layer parses on a game's own thread.
  Native tests hold Rules on the heap.
- A generated fixture requires every seed value to match its own family in its own group; Ricochet's "no data"
  test asserts its data now; VAC's asserts no family entry fakes it.
- Measured: the Overlay's MatchesFloorModule goes from ~20 ns to ~60 ns per miss over the larger floor.

Docs: 19_SAFETY Blocklist seed (regenerated table, expansion note), 14_TESTING, 20_OPEN_QUESTIONS S5, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 13:38:11 +00:00
poli0981andClaude Opus 5.5 53048ab2e0 release: 0.1.0-beta.7 - the CHANGELOG section, the accuracy block's release line, README's release lines, HANDOFF's status pointer (#226)
The seventh pre-release: a program in the library can be left unrecorded,
and Steam's own tools already in a library start that way (#225, D29,
schema 0009). Same unsigned installer; the Legal Gate opens once for the
Privacy Policy 2.3 and the Disclaimer 2.6.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 09:19:12 +07:00
poli0981andClaude Opus 5.5 944f827a2b feat: a library entry can be left unrecorded - Steam tools start off, the Privacy Policy and the Disclaimer say so (#225)
Owner, 2026-09-23: the Agent records Borderless Gaming although hooking is
off, and it starts with Windows. Since Tier 2 exists every library entry
that runs gets a session, so each boot added one, for as long as the
utility ran, to the playtime totals (today 07:36-07:45 in agent-*.log).

D29: a per-entry Recording switch (FR-1.6) plus the import's known-tools
list applied to the entries an earlier import made.
- Schema 0009: games.record_sessions INTEGER NOT NULL DEFAULT 1; the one
  data change switches it off for rows with platform 'steam' and a
  SteamLibrarySource.KnownTools app id (a test holds the script's ids to
  that list). The UI writes it; the Agent only reads it.
- CaptureOrchestrator: the watchlist (and the launch election's tracked
  set) is the entries whose recording is on - an ignored program is no
  event, no session, no log line; switched off while a session of it
  runs, that session's stop token is cancelled once at the next poll (a
  user stop, saved as such); LaunchGame answers RecordingOff.
- The twin merge keeps the switch off when either twin had it off.
- App: a Recording card on the game page (no dialog: it deletes nothing,
  and nothing goes over the pipe), "Not recorded" on the library card in
  place of the hooking badge; en/vi/ja.
- Legal: the Privacy Policy 2.3 (a program whose recording is off is not
  watched; history note) and the Disclaimer 2.6 (the accuracy block's
  "unless you switched its recording off", which also carries #224's
  correction) - the Legal Gate shows both once. The EULA's statement stays
  true and is unchanged.

Tests: orchestrator (not watched, stop on switch-off once, launch
refused), schema 0009 applied from 8 to a tool/game/hand-added ledger, the
script's ids within KnownTools, repository switch, merge carry, the game
page and the card. Docs: 02_SPEC FR-1.6, 04_CAPTURE, 06_DATA_MODEL,
07_IPC, 08_UI, HANDOFF D29 + traps, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 08:22:55 +07:00
poli0981andClaude Opus 5.5 6fbf1f4cbc release: 0.1.0-beta.6 - the CHANGELOG section, the accuracy block re-dated and corrected, README's release lines, HANDOFF's status pointer (#224)
* fix: one entry per executable across drive letters - twins merge, an updated game follows with hooking off

Item 5 of the owner's beta.6 list: after the USB drive's letter changed
and changed back (H: on 2026-09-22 morning, D: after the reboot), the
library showed two entries side by side for the games played from it, and
the relocator's NOT EXISTS refused every move onto the other entry's path
- 5,675 "could not be moved" lines that day.

D26 (owner): two entries for one executable merge, in the Agent.
- ExecutableRelocator: a same-bytes move refused because another library
  entry holds the path becomes a merge (IGameMerge / SqliteGameMerge, one
  transaction; GameMergePlan picks the entry made first, a tie keeping the
  lower id). Sessions are re-parented before the dropped row is deleted
  (sessions.game_id cascades), the survivor takes the path after (UNIQUE).
  A block either carried is kept (hooking off), a crash auto-disable still
  in force is kept, crash counts add; no consent moves between the rows -
  hook_enabled only ever goes to 0. The merge re-reads both rows in the
  transaction and writes nothing unless they are as planned.
- It waits while a session of either entry runs (CaptureOrchestrator.
  IsRecording) or waits in a .partial to be recovered (IPartialSessionStore.
  PendingGameIds, read beside a running writer with FileShare.ReadWrite).
- Never with an entry removed from the library; other bytes under a twin
  are not merged - the log says once which entry to remove.

D27 (owner): when the only file at the entry's path on another letter has
other bytes (updated meanwhile), the entry follows it through the Change
executable write: hooking off, consent cleared, block kept. The watcher's
adopt follows the same rule.

Also:
- LibraryImporter no longer adds a twin: a store 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" (Import_Note_Moved,
  en/vi/ja) and skipped at import.
- DetectionSweep does not call a merged-away entry unreadable.
- DetectionHostedService catches DbException: a service that throws stops
  the Agent's host, and a busy ledger is a retry.

Tests: relocator (merge, survivor choice, busy, refused merge, removed
owner, other bytes not merged, D27 sweep and watcher, ambiguity), plan,
SqliteGameMerge on a real ledger (sessions re-parented, block and
auto-disable carried or not, no consent moved, nothing written when a row
changed), sweep, importer, import review, .partial headers beside a
writer. Docs: 19_SAFETY, 06_DATA_MODEL, HANDOFF D24 done + D26/D27 + traps,
CHANGELOG.

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

* release: 0.1.0-beta.6 - the CHANGELOG section, the accuracy block re-dated and corrected, README's release lines, HANDOFF's status pointer

The sixth pre-release: another game's Game.exe is no longer recorded under
an entry (#220), a session whose entry was removed keeps its data and a
bad .partial no longer stops the Agent (#219), a game that is not measured
is shown while it runs (#221), RE Engine and FromSoftware are detected and
engines are shown by name (#222), and two entries for one executable under
two drive letters merge (#223). Same unsigned installer; schema 0008
unchanged; rules 2026.09.2.

The accuracy block (README, legal/ACCURACY.md, legal/DISCLAIMER.md) is
re-dated, and one sentence corrected while doing so: it said the driver's
DLSS record "is not displayed yet", and the App has shown it as
"DLSS (driver-reported)" on the library, the summary, the game page and the
live card since 0.1.0-beta.3. A block re-dated with a sentence known to be
false would assert it again. No Disclaimer version bump, as with #218.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 03:57:18 +07:00
poli0981andClaude Opus 5.5 101bbbe5e4 fix: one entry per executable across drive letters - twins merge, an updated game follows with hooking off (#223)
Item 5 of the owner's beta.6 list: after the USB drive's letter changed
and changed back (H: on 2026-09-22 morning, D: after the reboot), the
library showed two entries side by side for the games played from it, and
the relocator's NOT EXISTS refused every move onto the other entry's path
- 5,675 "could not be moved" lines that day.

D26 (owner): two entries for one executable merge, in the Agent.
- ExecutableRelocator: a same-bytes move refused because another library
  entry holds the path becomes a merge (IGameMerge / SqliteGameMerge, one
  transaction; GameMergePlan picks the entry made first, a tie keeping the
  lower id). Sessions are re-parented before the dropped row is deleted
  (sessions.game_id cascades), the survivor takes the path after (UNIQUE).
  A block either carried is kept (hooking off), a crash auto-disable still
  in force is kept, crash counts add; no consent moves between the rows -
  hook_enabled only ever goes to 0. The merge re-reads both rows in the
  transaction and writes nothing unless they are as planned.
- It waits while a session of either entry runs (CaptureOrchestrator.
  IsRecording) or waits in a .partial to be recovered (IPartialSessionStore.
  PendingGameIds, read beside a running writer with FileShare.ReadWrite).
- Never with an entry removed from the library; other bytes under a twin
  are not merged - the log says once which entry to remove.

D27 (owner): when the only file at the entry's path on another letter has
other bytes (updated meanwhile), the entry follows it through the Change
executable write: hooking off, consent cleared, block kept. The watcher's
adopt follows the same rule.

Also:
- LibraryImporter no longer adds a twin: a store 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" (Import_Note_Moved,
  en/vi/ja) and skipped at import.
- DetectionSweep does not call a merged-away entry unreadable.
- DetectionHostedService catches DbException: a service that throws stops
  the Agent's host, and a busy ledger is a retry.

Tests: relocator (merge, survivor choice, busy, refused merge, removed
owner, other bytes not merged, D27 sweep and watcher, ambiguity), plan,
SqliteGameMerge on a real ledger (sessions re-parented, block and
auto-disable carried or not, no consent moved, nothing written when a row
changed), sweep, importer, import review, .partial headers beside a
writer. Docs: 19_SAFETY, 06_DATA_MODEL, HANDOFF D24 done + D26/D27 + traps,
CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 03:42:31 +07:00
poli0981andClaude Opus 5.5 7756072af0 feat(rules): RE Engine and FromSoftware are detected; engines are shown by name (#222)
Items 2 and 3 of the owner's beta.6 list, checked on the owner's disk first.

- re_engine: `re_chunk_000.pak` beside the executable, the exact name (a
  glob without a star is the whole leaf, so a patch archive alone is not
  it). RESIDENT EVIL 2 and the Onimusha demo carry it.
- fromsoftware: a `*.bhd` AND a `*.bdt` sibling - DARK SOULS II
  (GameDataEbl), III (Data0-5), ELDEN RING (Data0-3) and Sekiro (Data1-5).
  The request said `.bht`; on disk it is `.bdt`. No `Game\` requirement:
  Sekiro has none, and "the parent folder is named X" is not a signal type.
- Both after the RPG Maker rules and before godot (whose *.pck also matches
  a loose Wwise bank). rulesVersion 2026.09.2, so every row re-detects.
  None of the other 80 Steam titles on the owner's disk has either marker.
- Fixtures engines/re_engine and engines/fromsoftware; the
  every_engine_marker canary carries both and still expects unity; its
  README said "four engines" while it held six.

The App shows engines by name (Formats.Engine: proper nouns, an unknown or
user-typed id passes through) on the card and the game page, where it
showed `rpgmaker_mv`; a test holds every shipped rule's id to its own name.
A hand-added executable whose name says nothing (Game.exe) is named from
RPG Maker's System.json gameTitle, else the nearest non-runtime folder
(GameTitleGuess + RpgMakerTitle), so HHW's swiftshader\Game.exe is "HELLO,
HELLO WORLD!" and not "Game". GameLibrary's misplaced doc comment fixed.

Engine detection never feeds the guard: ELDEN RING stays refused.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 03:17:34 +07:00
poli0981andClaude Opus 5.5 b7a03f0fce fix: a session that is not hooked is shown while it runs (#221)
A game with hooking off, one the guard refused, or one whose process could
not be read has been recorded since beta.5 (duration, sensors, the reason),
but SessionEventPublisher sent SessionStarted only at the ring attach and
progress only while attached. For as long as such a game ran the Dashboard
said "Nothing is being captured." and the tray stayed idle.

Agent:
- The hold's ticks carry the refusal (CaptureProgress.Held, with the pid the
  loop holds). The first held tick publishes SessionStarted ONCE, at tier 2,
  with an optional `hold` (the loop's reason and the guard's reason, family
  and signal - the words capture_notes will carry), and the refusal's own
  event at once instead of at the exit; it is not repeated at the end.
- Every held tick after feeds a new SessionHeld event (elapsed + sensors) at
  1 Hz while a client listens - never SessionProgress, whose required fields
  would put measured-looking zeros on the wire.
- ActiveSession carries the hold; SessionCompleted carries the entry's id and
  name; a faulted session also completes (finalize "faulted").
- All fields additive and optional: IpcProtocol.Version stays 2.

App:
- LiveSessions (App-lifetime) is seeded from the status on every (re)connect
  and moved by start/completion; the Dashboard seeds its card from it (it is
  rebuilt per visit). The tray and the updater seed their own lists from the
  same status; the updater no longer holds a download at Deferred on a
  status read hours earlier.
- The live card shows a held session with the T2 badge, elapsed, temperatures,
  "Recording duration and sensors only - nothing is measured." and why (the
  summary's own sentence), with no FPS readout. A tier-2 session without a
  hold is starting, not held. A hooked session takes the card, never the
  reverse. Stop clears the name; the notice names the completed session; a
  faulted completion is no notice.
- Formats: RefusedConsentMissing reads "the game's executable changed since
  hooking was turned on" instead of the enum name (en/vi/ja).

Tests: publisher (held announce once, reason once, no progress, status hold,
faulted completion), event table, codec (additive fields, beta.5 payloads),
capture session (ticks carry the hold and pid), live card, LiveSessions,
Dashboard, tray, updater, Tier2Reason, and a pipe end-to-end case with a
hooking-off harness. Docs: 07_IPC, 08_UI, 04_CAPTURE, 11_UPDATER (gap
closed), HANDOFF, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 02:58:33 +07:00
poli0981andClaude Opus 5.5 7ddb367c63 fix: a file name is not an identity - another game's Game.exe no longer runs under a library entry (#220)
2026-09-23 00:16 on the owner's machine: HELLO, HELLO WORLD!'s RPG Maker runtime (swiftshader\Game.exe)
matched Flower in Us, the only entry named Game.exe, by file name; the session was recorded under that
name, which created a new "Flower in Us" entry at HHW's path, and an NW.js child exact-matched the new
entry and started a second session. Both Tier-2 holds were timed by the name Game (HANDOFF D25).

- A StalePath match starts nothing unless the relocator moves the entry to it; otherwise one log line
  per executable, no session, no entry, a silent exit.
- ExecutableRelocator.TryAdoptAsync accepts only a drive-letter twin with the one-candidate rule
  (identical RPG Maker Game.exe stubs could have carried a consent to another game).
- The running table is keyed by executable path; IsRecording(gameId); the election registers and defers.
- Tier-2 liveness reads the watcher's snapshot by image path (LatestProcessSnapshot), opening nothing.
- Resolver notes reach agent-*.log with why a candidate was unreadable; unreadable/could-not-move and the
  sweep summary are logged once per change.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 02:39:53 +07:00
poli0981andClaude Opus 5.5 d586de1ccc fix: a session whose entry was removed lands where its executable lives, or is dropped; one bad .partial never stops the watcher (#219)
Two GIRLS' FRONTLINE 2 sessions on the owner's machine (2026-09-22 23:26, 2026-09-23 00:25) died on the
sessions.game_id foreign key because their entry was removed and re-imported while the game ran, and each
left a .partial that the next start's recovery would have failed on the same way - stopping the host, since
recovery runs before the watcher and the Generic Host stops on a background service's exception.

- ISessionRepository.ResolveOwnerAsync: the row the session started under when it predates the session or
  holds its executable, else the row that holds the executable now, else FinalizeStatus.GameRemoved.
- The write re-checks the row inside its transaction (SessionOwnerMissingException), never the FK error.
- PartialRecovery never throws: an unfinalizable file is quarantined as <guid>.partial.failed.
- Log lines name the session, the game and the executable; the host logs into agent-*.log (AddSerilog).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 02:24:58 +07:00
poli0981andClaude Fable 5.1 97c3feb648 release: 0.1.0-beta.5 - the CHANGELOG section, the accuracy block re-dated, README's release lines, HANDOFF's status pointer (#218)
The fifth pre-release: the guard override is gone and a finding turns hooking off (#215), Tier 2 exists
(#216), a drive that changes its letter is followed (#217). Same unsigned installer; schema 0008; the
Legal Gate opens once (Disclaimer 2.5, EULA 1.2).

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-22 14:54:16 +07:00
poli0981andClaude Fable 5.1 480b30ae0d feat: a drive that changed its letter is the same executable - the row follows it with consent, block and detection kept (#217)
Owner ask 2026-09-22 (D24). The owner's external drive came back as H: instead of D: and every game on it
read "executable unreadable"; a game launched from H: matched its row by file name only and ran as a
stranger. ExecutableRelocator finds the same file - same size, same mtime, exactly one other drive-letter
root - and moves the row to it through IGameRepository.RelocateExecutableAsync, whose write requires the
same size and mtime again. Asked by the 15 s sweep (relocate, then scan in the same pass), by the watcher
on a file-name match (adopt, so the session is the row's), and by the enable-hooking command before it
says unreadable. The game's page says when its executable is not where the entry points.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-22 11:46:31 +07:00
poli0981andClaude Fable 5.1 3f95c4b9fb feat: Tier 2 exists - a refused session is held, unhooked, until the game exits; hooking-off is decided before the process is opened; Steam tools are not games (#216)
Owner ask 2026-09-22 (D23): "Tier 2 does not work - what does it record, and show it." Every refusal
returned within a second and the 30 s minimum discarded it. CaptureSession.HoldUnhookedAsync now keeps a
refused session open, ticking the telemetry poller through the observer, until the target exits (a pinned
liveness, or the executable's name through ITargetResolver.IsRunning when the loop never opened the
process). The row lands as T2 with its sensor aggregates and the reason; the summary says why
(Formats.Tier2Reason over capture_notes). The operator host sets HoldUnhooked = false.

RunAsync reads the consent record before resolving the target: a hooking-off row - merely added, blocked,
auto-disabled - is never opened, so an elevated utility in the library (Borderless Gaming) is a quiet
Tier-2 row rather than the anti-cheat-driver notice. SteamLibrarySource.KnownTools keeps the next import
from adding one. PartialRecovery no longer reads a tick as proof of a hooked session.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-22 11:35:42 +07:00
poli0981andClaude Fable 5.1 7c67f4610d fix: the guard override is withdrawn; a finding turns the game's hooking off at session start and at the re-scan (#215)
Owner decision 2026-09-22 (D22). The per-game override of 2026-09-21 is removed entirely: the native
acknowledged entries and reason 28, FlGuardIsJudgement, the SetGuardBypass message, the App's card and
dialog, the session mark and export line, the Safety_Bypass_* strings, and schema 0007's five columns
(0008 drops them). CLAUDE.md rule 2 reads "there is no override" again; Disclaimer 2.5, EULA 1.2.

In its place: an anti-cheat named in the game itself (its process, its title lists, its folder) is written
to the row as the pre-scan always wrote it, now also when the guard finds it at a session's start or at
the 30 s re-scan (AntiCheatVerdict.IsFindingAboutTheGame, CaptureSession.TurnHookingOffAsync). A
machine-wide driver or service refuses that session only. CaptureRefused / SafetyUnhook carry
hookingTurnedOff and the notice says so; capture_notes carry hooking-turned-off=.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-22 11:14:24 +07:00
poli0981andClaude Fable 5.1 b9c11e4a34 docs: beta.4's notes named a cause they had no evidence for - corrected against Windows' own event logs (#214)
The owner reported that the external USB drive holding the Steam library had a loose cable on 2026-09-21. The System
and Application logs agree: disk resets and paging errors on that drive from 20:42, two restarts of the PC (20:57,
21:02), start_protected_game.exe and GF2_Exilium.exe both ending 0xc0000006 (in-page I/O error).

Withdrawn: the [0.1.0-beta.4] Updating note said an install over a running Agent had half-replaced the folder and
caused three failed starts. Nothing was installed between those failures and the start that worked; they are
unexplained. Corrected in place, and HANDOFF says it was a guess that got published.

Explained: the GF2 SafetyUnhook at 21:45 coincides with that game crashing on the failing drive.

Unchanged, with the evidence stated: TargetUnreadable (Easy Anti-Cheat's log says "successfully loaded in-game" the
second the resolver found a process it could not open), the two App instances at 21:07, the English safety texts.
FrameLedger injected nothing into ELDEN RING in any run.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 23:27:06 +07:00
poli0981andClaude Fable 5.1 dd3bf3634f release: 0.1.0-beta.4 - the CHANGELOG section, the accuracy block re-dated, README's release lines, HANDOFF; a wrong date corrected (#213)
CHANGELOG: [Unreleased] becomes [0.1.0-beta.4] - 2026-09-21 with a user-facing summary and the update notes (quit the
App and end the Agent before installing; the Disclaimer moved to 2.4; no schema change). The accuracy block and its two
embedded copies name 0.1.0-beta.4. HANDOFF gains decision D21 (a process an anti-cheat driver protects is
TargetUnreadable and the bypass stops there - rule 3, not rule 2), four things found and NOT fixed, and three traps.

#212 dated its comments and docs 2026-09-22; it was written and merged on 2026-09-21. Fourteen files corrected, dates
only. VERSION stays 0.1.0.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 22:46:20 +07:00
poli0981andClaude Fable 5.1 a670c26b0e fix: one App per data folder; safety texts follow the UI language; the bypass page says what is true; a protected process is TargetUnreadable (#212)
All four from the owner's installed beta.3 (a screenshot of ELDEN RING's page under the guard bypass, and the day's logs).

Single instance. Nothing stopped a second App: the log shows two started 360 ms apart - two shells, two tray icons, a
second log file, both writing one ledger. Services.SingleInstance claims the data folder in Program.Main (named mutex +
named event keyed on a hash of the folder, after Velopack's hooks, before any window); a later start sets the event and
exits 0, and the first brings its window forward through ShellHost.Reveal. --diag never claims.

Language. FrameLedger.Shared's Strings was never given the UI culture and fell back to the thread's, which the App's
async start does not pass on to later dispatcher work: a Vietnamese UI showed the consent dialog, the refusal notices
and the whole guard-bypass card in English. App.ApplyCulture sets both families.

The page. Under a bypass it printed "Hooking is disabled for this game: ..." beside a hooking switch that was on. The
finding stays and reads "The guard found: ... You chose to bypass it for this game".

The result. With the bypass on, ELDEN RING under Easy Anti-Cheat produced no session and a toast reading
"InjectFailed: TargetAmbiguous". The anti-cheat's driver closes the game's process to other programs; the resolver
could read no candidate and called that ambiguous. It is SessionEndReason.TargetUnreadable now, classified as a
refusal, and reaches the user as a persistent notice saying nothing was injected or measured, that the bypass does not
change this, and that FrameLedger will not work around another product's protection (rule 3; nothing here attempts
to). The bypass disclosure says so before it is accepted (guard-bypass-dialog/2) and so does DISCLAIMER 2A (2.3 -> 2.4).
The refusal notices no longer say "there is no way to override this".

Also: the Agent's session log line names what the guard said when it was not a plain allow - a SafetyUnhook on the
owner's machine left no trace of which finding fired.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 22:19:39 +07:00
poli0981andClaude Fable 5.1 a10b281074 release: 0.1.0-beta.3 - the CHANGELOG section, the accuracy block re-dated, README's release lines, HANDOFF's decisions and traps (#211)
CHANGELOG: [Unreleased] becomes [0.1.0-beta.3] - 2026-09-21 with a user-facing summary and the update notes (schema 7;
the Legal Gate re-opens; a Steam row created for the wrong executable is not rewritten). The accuracy block
(legal/ACCURACY.md and its two embedded copies) is dated 2026-09-21, names 0.1.0-beta.3 and says "beta" where it said
"pre-alpha". README's install line names the three pre-releases. HANDOFF gains what no other file carries: decisions
D18-D20 (the one guard override and its fixed shape; the derived DLSS preset still not shown; the bug bundle does not
get the machine's hardware), what the owner still owes, and the traps this train paid for. VERSION stays 0.1.0.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 19:44:59 +07:00
poli0981andClaude Fable 5.1 a3516efe97 docs(legal): the terms an end user needs - beta, minimum requirements, the guard bypass; stale docs; two flaky tests (#210)
Terms. legal/DISCLAIMER.md 2.2 -> 2.3 and legal/EULA.md 1.0 -> 1.1, so the Legal Gate opens once after the update:
- section 0: this is pre-release (beta) software; it certainly still has bugs, and the developer is not responsible for
  incidents that result;
- section 2A: the per-game guard bypass, entirely at the user's own risk, no responsibility and no liability;
- section 4A: the PC must meet at least the minimum requirements the game's developer or publisher states - read them
  first; problems below them, or on unstable, overclocked or overheating hardware, are the user's, not the developer's;
- section 7A: back up your own data; builds are unsigned - download from the project's Releases page only and verify the
  hash; no affiliation with any game, platform or vendor; numbers are for your own information.
The first-run Legal step shows a short plain-language summary of those points (en/vi/ja) above the documents, which
remain the terms. legal/ACCURACY.md and its two embedded copies no longer say "There is no override anywhere", and say
that injection happens past the guard or past the user's own acceptance of a game's bypass.

Stale docs. THIRD_PARTY_NOTICES 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, both seen on PR #209's CI and neither touching what that PR changed: the native-log test slept a
fixed 1500 ms and read the log between two UNHOOK_RESTORED lines (it polls for the last one, bounded at 10 s), and
ParentDumpTests dumped a child it had started microseconds earlier and got ERROR_PARTIAL_COPY (it retries while the
child finishes loading, bounded at 5 s).

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 19:27:54 +07:00
poli0981andClaude Fable 5.1 234962f0e7 feat(safety): a per-game "bypass the anti-cheat guard" switch, at the user's own risk (owner decision 2026-09-21) (#209)
The owner asked for a mode that skips the guard behind a warning the user MUST accept first, and chose the per-game
form. CLAUDE.md rule 2 said "There is no override switch. Do not add one"; it is amended with this, and the amendment
is the constraint list below. Rule 3 is untouched: the bypass changes WHETHER FrameLedger injects, never HOW.

What it is. A switch on the game's page, off by default, never global: no setting, no CLI switch, no environment
variable, no field in rules/detection-rules.json (the schema still rejects one). It is a recorded human act - its own
disclosure, accepted by a ticked acknowledgement AND the typed phrase BYPASS, stamped by the Agent with the
disclosure's version (schema 0007: games.guard_bypass_at / _disclosure_version) through IGuardBypassStore, a port of its
own. It is keyed on the executable like consent, and ends when hooking is turned off or the executable changes.

What it overrules: the guard's JUDGEMENT (blocklist matches, the suspicious-module rule, scans that could not look,
unusable rules, the PreviouslyBlocked latch). What it never overrules: the kill switch, a game merely added, a missing
consent, a foreign payload, a 32-bit target, a failed injection, and a Vulkan title the guard refuses.

Native. FlGuardedInjectAcknowledged / FlGuardedInjectWhenReadyAcknowledged live in fl_guard.cpp, the one chokepoint
file. They run EVERY check, verify the payload, use the same LoadLibraryW primitive, and answer
AllowedUnderUserBypass (28) with the family and signal of what was found - never kAllow, so Allowed() stays false for
every caller written before it. IsGuardJudgement is the list; FlGuardIsJudgement exports it for the mirror test.

Managed. AntiCheatVerdict.IsAllowedUnderBypass, asked by name in CaptureSession only. HookRequest gains the fifth
input, built in FromConsent from a stored record that names its disclosure, dropped on a fingerprint mismatch.
HookedCaptureGate checks it after the kill switch, enablement and consent. The port's acknowledged methods DEFAULT to
the hard gate. GuardSupervisor still scans and still ticks under a bypass; a judgement is kept, counted and does not
unhook, a fact still does. SetGuardBypass re-checks everything the App checked; SetHookEnabled under a recorded bypass
still writes the finding and stamps consent beside it.

Afterwards. sessions.guard_bypassed / guard_bypass_family / guard_bypass_signal; the sessions list, the summary, the
CSV header and the JSON export say so. A session recovered from a .partial does not carry the mark (recorded limit).

Docs with it: CLAUDE.md rule 2, 19_SAFETY (the spec), 02_SPEC FR-2.7, 06, 07, 08, 14, 20_OPEN_QUESTIONS, SECURITY.md,
and tools/chokepoint-check.ps1's own description. Safety strings in en/vi; ja ships the English until a reviewer signs.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 18:58:29 +07:00
poli0981andClaude Fable 5.1 9a14304a41 feat: CPU load, memory and (elevated) CPU temperature; per-game trend metrics; Settings shows this PC (#208)
* feat: CPU load, memory and (elevated) CPU temperature are measured; trend metrics per game; Settings shows this PC

Telemetry. sessions.avg_cpu_load / avg_cpu_temp / max_cpu_temp / avg_ram_mb and the cpu_load / cpu_temp / ram_mb
series were in schema 0001 with no producer. TelemetryPoller now reads the machine beside the GPU on the same 1 Hz
tick through ISystemTelemetrySource, and the reading rides each TelemetrySample as a SystemReading - outside GpuSample,
whose capability bits and layer attribution mean nothing here. Two unprivileged Win32 calls, no process opened:
GetSystemTimes (time busy across every logical processor; the first tick has no interval and is null, never 0) and
GlobalMemoryStatusEx. CPU temperature is the one privileged reading: a separate CPU-only LibreHardwareMonitor Computer,
opened only when the Agent is elevated AND PawnIO is installed. It is UNMEASURED on real hardware (20_OPEN_QUESTIONS
M10 carries the one session that settles it). HelloAck.cpuTempAvailable reports those two conditions instead of a
constant false. The .partial sensor chunk carries the three values in bits 12-14 of its existing presence mask, so an
older file reads back with an empty reading. No migration; older sessions keep their nulls.

App. 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 xFG factor - a factor that is its session's steady state (rule 6) is a
partial point: left out by default, drawn marked when mid-session changes are included. The Sensors chart draws CPU
temperature, CPU load and system memory; Compare gains three rows; the session summary gains GPU and CPU cards and the
session's hardware snapshot under its header; the live card carries cpuLoadPct. Settings > System states this PC as a
session's snapshot would record it (the same IHardwareSnapshotSource), with Copy; nothing is sent anywhere. --diag
prints it; the bug bundle's sysinfo.json is deliberately unchanged (its keys are the issue link's prefill).

legal/ACCURACY.md and its two embedded copies say what is and is not measured about the processor.

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

* style: one property per line in the trend test's object initialiser

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 18:17:36 +07:00
poli0981andClaude Fable 5.1 366b0467bc build(native): FL_BUILD_ID falls back to a shorter form when the long one does not fit, so a dirty tree configures (#207)
After the first tag `git describe --always --dirty --abbrev=12` yields `v0.1.0-beta.2-2-g<12 hex>-dirty` on any tree
with an uncommitted change: 35 characters against FlShmHandshake::buildId's 31. Every local CMake configure of a dirty
tree was fatal, and the recorded workaround was "commit before you build" (2026-09-17, hit again 2026-09-21).

The id is a version-skew signal, not a provenance guarantee, so when the long form does not fit the configure retries
with `--dirty=+ --abbrev=8` (`v0.1.0-beta.2-2-gd3e74988+`, 26 chars). A release is a clean checkout at a tag and never
takes the fallback. Still too long after that is still fatal, for the reason the check exists.

Verified: a deliberately dirtied worktree two commits past the tag configured with
`FL_BUILD_ID = v0.1.0-beta.2-2-gd3e74988+` and built; before this it stopped at the FATAL_ERROR.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 17:56:45 +07:00
poli0981andClaude Fable 5.1 985ecba12e fix(app): DLSS is named where the driver reports it, instead of "Unknown upscaler"; a measured preset is its name (#206)
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: `unknown`. FSR was named because its dispatch is hooked. 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. Nothing under FrameLedger.App read it.

Formats.Upscaler(token, quality, driverReported) is 03_METRICS' ladder in one place: a hook's name outranks
everything and takes its measured preset; where no hook named one and the driver reports NGX super resolution created
and evaluated, the text is "DLSS (driver-reported)" - attributed, identity only, never a quality; otherwise the
token's own text, and `unknown` now reads "Upscaler not identified". The library, the session summary, the game page
and the live card (SessionProgress.upscalerDriverReported, optional) all use it. Sessions already recorded show it
too, because the column was always written.

Domain.Metrics.UpscalerNames, promised by 03_METRICS from the start: the one produced quality byte (sl::DLSSMode via
Streamline) is its preset's name - "DLSS Balanced", not "DLSS 2". A value with no name is shown as stored. A preset
derived from the render scale is still not shown (HANDOFF 7a, an owner decision not taken).

Nothing native changed; no hook was added.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 17:41:26 +07:00
poli0981andClaude Fable 5.1 d3e74988a7 fix(app): the Games card's tags are readable in the light theme, and a Steam import picks the game, not its browser helper (#205)
Badges. The platform and engine tags on the Games card (and the edit dialog's "Detected" marker) were
ui:Badge Appearance="Secondary". WPF UI 4.3.0's Secondary trigger repaints the background only and keeps the default
badge's on-accent foreground, so in the light theme they were near-white text on a near-white fill: two empty boxes
beside a readable hooking pill (owner's screenshot, 2026-09-21). They are the App's own TagPill + TagPillText now, the
pair ContrastTests already measures in both themes, and ContrastTests refuses a Secondary badge in App XAML.

Steam import. Steam names no executable, so the import guessed "the largest non-helper". On GIRLS' FRONTLINE 2:
EXILIUM that was GF2_Exilium_Data\Plugins\ZFGameBrowser.exe (1,082,944 bytes), not the 675,392-byte Unity player, and
because the watcher, consent and the gate are keyed on the executable path, hooking enabled on that row could never
match the game - while the same game added by its exe worked. ExecutableLocator now ranks: the engines' own layouts
(Unity X.exe beside X_Data; Unreal *-Win64-Shipping.exe), then a name matching the install folder, then size. It skips
X_Data\Plugins and redistributables folders, knows browser/webview/subprocess/analyzer/vconsole as helpers, and walks
four levels. 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).

Change executable. The game page shows the row's executable and re-points it: IGameRepository.ChangeExecutableAsync
leaves the row as a new game would be (hooking off, no consent, pre-scan not run), never clears a block, refuses a path
another row owns; the App revokes consent over the pipe first, as removal does. Rows an earlier import created are
not rewritten.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 17:19:03 +07:00
poli0981andClaude Fable 5.1 34e405fe08 deps: xUnit.net v3 4.0.1 (as xunit.v3.mtp-off) and the other outdated packages; one test race the new scheduler found (#204)
xunit.v3 3.2.2 -> 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 package; 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.

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.
WPF-UI [4.3.0] and FluentAssertions [7.2.2] stay pinned, with their reasons. legal/licenses/nuget regenerated.

The first gate run on 4.0.1 failed StringsTests.TheCulturePropertyOverridesTheThread: eight App.Tests classes write
the process-wide Strings.Culture and ran in parallel. They share one collection now; five runs green, then the gate.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 16:58:22 +07:00
poli0981andClaude Opus 5 e2568eb312 release: 0.1.0-beta.2 — the CHANGELOG section, the accuracy block re-dated with the steady state, README's release lines (#202)
The commit the second tag points at (13_CI_CD §Branch & release policy; VERSION
still reads 0.1.0).

- CHANGELOG: the [Unreleased] entries move as written under
  `## [0.1.0-beta.2] - 2026-09-17` — the header's rule from the second tag on —
  after a short account of what changed for a user and three update notes: end
  every Agent before installing (an elevated one needs an elevated Task
  Manager), the ledger migrates to schema 6 without re-aggregating stored
  sessions, and sessions recorded while several Agents ran appear once per
  Agent. release-notes.ps1 extracts 10.6 KB.
- legal/ACCURACY.md: dated 2026-09-17, "latest pre-release is 0.1.0-beta.2",
  and the frame-generation bullet says what a finished session's factor is
  when the state changed: the steady state's, always with its share
  (03_METRICS §The steady state, #198). Re-embedded verbatim in README.md and
  legal/DISCLAIMER.md (accuracy-check green). The Disclaimer's version stays
  2.2, as it did for 0.1.0-beta.1: the block is re-dated, the terms are not
  changed.
- README: the install and status lines name the latest pre-release.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-17 15:33:01 +07:00
poli0981andClaude Opus 5 402e98ab56 fix(agent): one Agent per data folder — an App started as administrator no longer starts an Agent per connect round (#201)
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 three Agents it started run
at High integrity; the first, at Medium); the pipe of the Agent already serving
refused it, AgentConnection swallowed the refusal, took it for an absent Agent
and started another on each round, 17 s apart. Nothing in the Agent noticed the
first — 01_ARCHITECTURE §Lifecycle specified a single instance through named
mutexes and it was never built — so every game launched in the next hour was
injected, read and recorded by all four (four sessions with equal frame counts
per launch), and the three extras logged "accept failed" every 260 ms for four
hours, 2 MB each.

Why the pipe refused: PipeOptions.CurrentUserOnly compares the pipe's owner
with the client token's default OWNER (dotnet/runtime ValidateRemotePipeUser),
and an elevated token's default owner is BUILTIN\Administrators — the log files
the elevated Agents created are owned by it, the unelevated ones' by the user.

- Infrastructure.Startup.AgentInstanceLock: a named mutex per data folder
  (Local\FrameLedger.Agent.<hash>), held and never waited on; access denied
  counts as held. --serve and the console's capture / launch / recover claim it
  before logging, rules and the ledger; a second process exits 10 with one line.
- App: AgentLauncher.RunningAgent probes the claim and the last Agent it started
  (watched until exit, exit code logged); AgentConnection starts nothing while
  one is up, and logs why a connect failed once per distinct reason.
- Pipe: the SDDL states the owner (O:<user>), and PipeClient checks the owner
  against its token USER before writing a byte
  (PipeAccessControl.RequireOwnedByCurrentUser).
- PipeServer: an instance that cannot be created backs off 250 ms -> 10 s and is
  logged once per streak with its Win32 error — read with GetLastSystemError,
  since CsWin32 0.3.298 declares CreateNamedPipeW without SetLastError and
  GetLastPInvokeError read 0.
- Tests: AgentInstanceLockTests; OneAgentPerDataFolderTests (the shipped binary
  against a claimed scratch folder: exit 10, nothing created);
  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, error 231).
- Docs: 01_ARCHITECTURE §Lifecycle, 07_IPC §C and §Client behavior, 08_UI,
  12_BUILD, 20_OPEN_QUESTIONS §G (a second reader on one ring from another data
  folder is still possible), CHANGELOG.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-17 15:03:12 +07:00
poli0981andClaude Opus 5 fcf91acc40 fix(app): closing the App no longer ends in a Fatal error — the tray is removed on its own thread (#199)
The installed 0.1.0-beta.1 logged "the calling thread cannot access this object
because a different thread owns it" from TrayHost.Dispose and exited with code 1
on close. 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.

- App.RunAsync waits for the stop request on the dispatcher; TearDownAsync
  stops the host once, from the UI thread.
- TrayHost.Dispose marshals to the icon's dispatcher from any thread (bounded
  at 5 s; skipped once the dispatcher has shut down).
- 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.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-17 14:51:20 +07:00
poli0981andClaude Opus 5 63cec83e69 fix(diagnostics): a crash dump is written by a child process, so it can no longer hang the process it describes (#200)
* fix(diagnostics): a crash dump is written by a child process, so it can no longer hang the process it describes

FrameLedger.Infrastructure.Tests hung about one run in eight (it cancelled the
first tag's release run after 58 minutes). The verbose reporter of a hung run
showed thirteen tests started and none finished, one of them
CrashDumpWriterTests.WritesAMinidumpOfThisProcess — which, like the product's
crash path in the App and the Agent, called MiniDumpWriteDump on the calling
process. That suspends every other thread of it; one holding the heap or
loader lock deadlocks the dumper and the whole process freezes. Forty runs
without that test: no hang.

- CrashDumpWriter.TryWrite starts FrameLedger.Agent.exe --write-crash-dump
  <file> and waits up to 30 s; a missing, failed or slow helper is a null path
  and one line, as before.
- ParentDump (the helper) dumps its PARENT with the same flags. It takes no pid
  and refuses unless the parent is still running, started before it, and has
  its image in the helper's own directory — the App or the Agent, never a game
  (CLAUDE.md rule 4). The self-contained install ships no createdump.exe.
- The Agent answers --write-crash-dump before logging, rules and the ledger.
- build.ps1: --blame-hang did not stop the hung xUnit v3 executable, so dotnet
  test runs under a 25-minute wall-clock limit, kills the tree on expiry, and
  names the test projects that wrote no results.trx (exercised locally: success,
  timeout-kill with nothing left alive, failure exit).
- Tests: ParentDumpTests (a real minidump of another process; which parent is
  ours), CrashDumpWriterTests (failing and missing dumper), CrashDumpHelperTests
  (the shipped Agent dumps the test process from outside; refuses a System32
  parent; the flag's surface). 40 runs of the suite with them: no hang, no
  failure.
- Docs: 10_LOGGING §Crash handling, 12_BUILD Agent flags, 13_CI_CD tally,
  CHANGELOG.

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

* fix(diagnostics): a failed dump names dbghelp's error instead of 0

CsWin32 0.3.298 declares MiniDumpWriteDump without SetLastError, so
Marshal.GetLastPInvokeError() read whatever an earlier call left - 0 when
measured on CreateNamedPipeW the same day (#201). The code is read with
GetLastSystemError at once, as CsWin32's own wrappers do, and printed as the
HRESULT dbghelp reports. ParentDumpTests: dumping a process that has exited
fails, leaves no file, and the line carries a non-zero code.

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

* fix(persistence): the migration mutex is the ledger file's, so a hung process no longer fails every other ledger

MigrationRunner took Local\FrameLedger.Ledger.Migrate for every ledger. On #199's CI
run Infrastructure.Tests froze (the in-process minidump this PR removes) while
one of its tests held it, and seven App and Agent tests - each on its own
scratch ledger - failed after 30 s with "another process has been migrating
the ledger". The name is the file's now: Migrate.<SHA-256 of the full path>,
MigrationRunner.LockNameFor.

MigrationLockTests: names differ per file and ignore case; a thread holding
another ledger's lock does not delay opening this one (on main it waited 30 s
and threw). 06_DATA_MODEL §Migrations, CHANGELOG.

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-17 14:39:00 +07:00
poli0981andClaude Opus 5 3ecf36f71f feat(fg): a session whose frame-generation state changed publishes its steady state, with its share (schema 0006) (#198)
* feat(fg): a session whose frame-generation state changed publishes its steady state, with its share (schema 0006)

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. The refusal is right (Wukong
averages to 2.22; its gameplay ran x4.1) and stays; 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, with Native and Displayed counted
  over the state's own windows. Only behind a NonUniform refusal; never beside
  a published session factor; never for an unattributed or saturated set.
- FgWindow: BucketTolerance 25 % -> 10 % (a x3-then-x4 session published 3.69;
  the one published session read x2.04 for a gameplay of 2.00);
  MultipleStreams refuses only when the chains' samples INTERLEAVE — Onimusha
  recreates its swapchain on entering gameplay and was refused on every session.
- Row: fg_factor_scope ('session' | 'steady') and fg_steady_share, schema 0006;
  fg_refusal and its detail stay beside a steady factor. FgLadder: a steady
  state without an identity is ActiveUnidentified.
- UI: the generated shape with the chip "x2.0 FG · 75%" — the share is never
  omitted — and a tooltip saying why there is no session-wide factor.
- Replayed over the owner's nine sessions through the real FgWindow: eight
  publish (Onimusha x4.00 60 -> 240, Lies of P x2.00, Hell Is Us x3.03, Cronos
  x2.00 225 -> 451, Wukong x4.11); the ninth had nine seconds of gameplay.
- CLAUDE.md rule 6 amended (owner decision 2026-09-17). Docs: 03_METRICS §The
  steady state, 08_UI, 06_DATA_MODEL, CHANGELOG. Two strings en/vi/ja.

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

* fix(fg): FgSteadyState drops its unreachable branches and checks its arguments (coverage 94.7 % -> 100 %)

CI's coverage gate refused the steady-state PR: FgSteadyState at 94.7 %
against the 95 % per-calculator floor. The misses were branches that cannot
run: an empty state after re-drawing around the pooled factor (a weighted mean
of members within 10 % of the centre always has a member within 10 % of
itself), a zero presenting time (a valid start always yields a slice), a
before-origin QPC and an infinite slice factor that the active check
short-circuits before reading. They are gone; an out-of-range start throws
instead of returning null, and a direct-call test covers the arguments and the
no-active-window case. Behaviour for every reachable input is unchanged:
Domain 165 and Application 246 green, 100 % line coverage on the class.

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-17 11:51:42 +07:00
poli0981andClaude Fable 5.1 d8815b5b73 docs: the first tag ran — 13_CI_CD §release.yml, 12_BUILD sizes, 15_ROADMAP §P5, CHANGELOG (#197)
v0.1.0-beta.1 on becc208, run 35111939019: cancelled once by a test hang
(Infrastructure.Tests, 58 min, no test named), green on the re-run in 11 min;
the pre-release exists with the section's notes and SHA256SUMS. The sentences
that said the workflow had never run under a tag are struck where they sit.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 23:25:25 +07:00
poli0981andClaude Fable 5.1 f631c43c51 chore(build): dotnet test names a hung test and fails after 15 minutes (--blame-hang) (#196)
The first tag run sat in Infrastructure.Tests for 58 minutes — every other
suite green, the same suite 42 s an hour earlier — until the 60-minute job
limit cancelled it, and the log named nothing. --blame-hang with a 15-minute
timeout and a mini dump makes the next hang a named failure. 13_CI_CD's tally
records the run.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 23:12:33 +07:00
poli0981andClaude Fable 5.1 becc208d8f release: 0.1.0-beta.1 — the CHANGELOG section, the accuracy block's first sentence, README's release lines (#195)
The commit the first tag points at (13_CI_CD §Branch & release policy;
VERSION already reads 0.1.0).

- CHANGELOG: `## [0.1.0-beta.1] - 2026-09-16` is a written summary of what the
  pre-release is and is not — the moved entries would be 370 KB against a
  125,000-character release body — and the entries stay below it verbatim
  under `## Ledger before 0.1.0-beta.1`, where release-notes.ps1 stops
  (4.5 KB extracted). The header's "this file still has no heading" note is
  struck and the reason recorded. `[Unreleased]` is empty.
- legal/ACCURACY.md: "unreleased: no tagged build" becomes "first pre-release
  is 0.1.0-beta.1", re-embedded verbatim in README.md and legal/DISCLAIMER.md
  (accuracy-check green).
- README: the install section's "no release yet" line and the status line
  name the pre-release.

Rehearsed on main by release.yml's dry run (run 35107110773): the gate,
publish (252 MB tree), licences, tree assertion, vpk (Setup.exe 110 MB,
portable zip and full nupkg 105 MB) and checksums all passed; only the
Release step was skipped, as designed.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 21:55:31 +07:00
poli0981andClaude Fable 5.1 e0758e6dae fix(tests): the capture-host suite waits for a killed host to exit before reading or deleting its files (#194)
Two CaptureHost flakes CI kept producing had one cause: Kill() returned before
the killed host had released its files, so the kill-and-recover case opened a
.partial the dead process still held ('being used by another process'), and
Dispose's ledger delete silently failed and left a consent record for the
refusal case to find. Kill waits for exit (15 s, asserted); DeleteHostLedger
retries. 13_CI_CD's flake tally records it.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 21:42:35 +07:00
poli0981andClaude Fable 5.1 e69fdf30ac docs(legal): the legal documents say what the software does, in release form (EULA 1.0, Disclaimer 2.2, Privacy 2.2) (#192)
- 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; 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 rules update, an opt-in Steam lookup)
  under an audit note since 2026-08-04; 2.2 keeps the two real rows (Velopack
  update check and download), says there is no other request, and records the
  removal as history. §1: no cover art (no such feature); log retention as the
  code has it (7 days App, 14 Agent).
- Disclaimer: the 25-line audit block inside the accepted text moved unchanged
  to docs/legal-drift-history.md; a five-line pointer explains how §4 is kept
  true (ACCURACY.md + accuracy-check); the contact footer is added.
- Third-party notices: the IGCL/ADLX box ticked with its check named
  (license-check §1); the About-tab box says 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 (no code
  makes the request); the setting stays reserved (06_DATA_MODEL, 08_UI).
- 20_OPEN_QUESTIONS §S20: a feed lands as a new policy version, not as rows
  kept in advance. CHANGELOG.
- ACCURACY.md's "unreleased" sentence deliberately untouched: it is rewritten
  in the tag commit, where it becomes false.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 21:29:23 +07:00
poli0981andClaude Fable 5.1 96b564ce77 chore(release): a release rehearsal (workflow_dispatch dry run), SECURITY.md, and an honest hygiene checklist (#191)
* chore(release): a release rehearsal (workflow_dispatch dry run), SECURITY.md, and an honest hygiene checklist

P5 prep. release.yml has never been exercised by a tag; everything after the
version gate had only run by hand on one machine.

- release.yml: `workflow_dispatch` with a `version` input runs the identical
  job — gate, publish, runtime licences, the published-tree assertion,
  `vpk pack`, checksums, the artifact (`release-<version>-dry-run`) — and skips
  only `gh release create`; no tag is made. A missing `## [x.y.z]` section is
  a warning with placeholder notes in a rehearsal and stays a stop on a tag,
  because that section is written in the tag commit and a rehearsal precedes
  it.
- 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, the response intent stated as an
  intent. ISSUE_TEMPLATE/config.yml points a vulnerability at the private
  route; README 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 first paragraph
  rejects, the rest are GitHub settings only the owner can set. §release.yml
  documents the dry run. 14_TESTING: the Velopack-delta row is reachable from
  the second release. 15_ROADMAP §P5, CHANGELOG.

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

* fix(release): a handled dry-run failure clears LASTEXITCODE (the runner's pwsh wrapper exits with it)

The first rehearsal printed the warning for the missing CHANGELOG section and
then failed anyway: GitHub's pwsh step ends with 'exit $LASTEXITCODE', which
release-notes.ps1 had left at 1.

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 21:13:38 +07:00
poli0981andClaude Fable 5.1 1ff501a2d5 feat(fg): the "factor not counted" tooltip says which bucket and by how much (sessions.fg_refusal_detail, schema 0005) (#190)
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 > 25 % from the whole, or held no tokens —
a menu, a loading screen, an alt-tab inside a whole play session), one
multiple_streams (a second swapchain); the tooltip could only repeat the kind.
FgWindow had computed the bucket, its ratio and the window's; the aggregator
kept only the kind.

- Application.Recording.FgRefusalDetail: kind, subject, count, bucket
  index/count, the bucket's ratio (null when it held no tokens — infinity is
  not JSON) and the window's; ToJson/Parse over RecordingJsonContext.
- 0005_fg_refusal_detail.sql; SessionRow.FgRefusalDetail; SessionRowColumns;
  SessionAggregator.ApplyFg stores it beside fg_refusal.
- FpsPresentation.IdentifiedTooltip(technology, refusal, detail) appends
  RefusalDetailText: "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.
- No number is decided by it; the producer is unchanged (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; Strings.Designer.cs regenerated.
- Tests: SessionAggregatorTests, LedgerDatabaseTests (script five),
  FpsPresentationTests. Docs: 06_DATA_MODEL §Migrations, 03_METRICS §FG
  factor, 08_UI §FPS display rule, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 20:59:38 +07:00
poli0981andClaude Fable 5.1 d7a38fbd89 docs(spike): §14.1's row half — the shipped Agent's Lies of P session (fsr3, 1506×848→2560×1440, FG ×2.04, rt no) (#193)
The owner's afternoon of watcher-driven sessions produced the milestone's row:
sessions.id 10, Lies of P, attach mode from a Steam launch. The 'against its
menus' column stays blank for the owner; the DLSS-G rows of the same afternoon
are recorded as the refused shape. 15_ROADMAP §P2 says the row half exists.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 20:46:05 +07:00
poli0981andClaude Fable 5.1 93154495d9 fix(import): itch.io import reads butler's database, so an install location outside %APPDATA% is found (#188)
* fix(import): itch.io import reads butler's database, so an install location outside %APPDATA% is found

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. The app records its installs in %APPDATA%\itch\db\butler.db:
install_locations, caves, and butler's own verdict JSON naming the executable
it launches.

- Copy butler.db (+ -wal) to a temporary directory, open the copy read-only
  (the running app holds it in WAL mode), join the three tables, take the first
  Windows candidate of the verdict as the executable (an HTML/Love2D game leaves
  the locator's guess), still scan apps\ receipts for what the database does
  not list; an install found both ways is one row, the database's.
- One log line per run through the importer's sink says what was consulted
  and what each source yielded.
- The constructor now takes the itch directory, not apps\.
- Measured on this machine: 1 location, 2 caves, both titles with butler's
  executables.
- Tests: StoreLibrarySourcesTests (butler.db built in the test: a location
  elsewhere, a custom folder, a forward-slash verdict path, an HTML-only
  verdict, an unparsable verdict, a receipt beside a cave, a receipt-only
  install; no database and a garbage database fall back to receipts and say so).
- Docs: 05_DETECTION §Platform signatures, CHANGELOG.

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

* style(tests): using order in StoreLibrarySourcesTests (dotnet format)

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

* fix(tests): the layer registration test deletes only its own registry subtree

It deleted SOFTWARE\FrameLedger.Test whole, which is shared with the GOG
reader's test; when the two overlapped on the runner the GOG keys vanished
mid-test (#188 round 2, 'expected a single item, collection empty').

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 20:11:44 +07:00
poli0981andClaude Fable 5.1 8e3a67a8a1 feat(rules): RPG Maker MV/MZ and XP/VX/VX Ace engine rules, rulesVersion 2026.09.1 (#189)
05_DETECTION marked both RPG Maker rows ⛔ "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 — www/ is only where MV keeps its data — so
all: [nw.dll, package.json] is the whole signal. Measured on the owner's
Flower in Us (Steam) and a hand-extracted MV title: both engine=none before,
both rpgmaker_mv now; Godot, Ren'Py and the rest unchanged.

- rpgmaker_mv: all of nw.dll + package.json siblings, version null (the .js
  header needs a `from` that strings_regex lacks).
- rpgmaker_rgss "RPG Maker XP/VX/VX Ace": any of RGSS1*/RGSS2*/RGSS3*.dll or a
  *.rgssad/*.rgss2a/*.rgss3a archive, version null (which DLL matched is not a
  value any extractor produces) — one rule, the variant unnamed.
- Both after unity/unreal and before godot (an MV game has no .pck; a Godot
  game has no nw.dll).
- Fixtures engines/rpgmaker_mv, engines/rpgmaker_rgss; every_engine_marker
  gains nw.dll, package.json, RGSS301.dll and still expects unity.
- rulesVersion 2026.09.1: the sweep's cache key changes, so every game is
  re-detected on the Agent's next pass.
- Docs: 05_DETECTION §Engine signatures (the ⛔ note kept, struck), CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 19:36:50 +07:00
poli0981andClaude Fable 5.1 c419482169 fix(app): the hooking chip meets AA in both themes, and the FG qualifier no longer clips (#187)
The Games card's "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, 2.6:1 — and
no `#` in our XAML for NoXamlHardCodesAColour to catch. It is a Border in the
new HookStatePill style (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.

ContrastTests holds it two ways: no App XAML uses the four palette appearances,
and every pill (text, fill) pair composited over the card and window is ≥ 4.5:1
in both theme dictionaries — with the old pair asserted below it so the check is
known to bite. The accent brushes are derived the way MainWindow derives them
(ApplicationAccentColorManager.Apply on a fixed default accent).

The Dashboard's FG qualifier chip had the other defect — a sentence-length
qualifier in a star column with no trimming — so the text trims with an
ellipsis at 260 px (the tooltip carries the sentence) and the recent-sessions
row sizes the readout to content with the game's name trimming first.

Docs: 08_UI §Contrast, 16_WPFUI_SYNTAX §Theming, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 18:59:30 +07:00
poli0981andClaude Fable 5.1 c6491a3b89 fix(ledger): a print verb no longer migrates the ledger it prints, and a close checkpoints the WAL it wrote (#186)
`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 WAL a fresh connection
discarded (salt one generation behind the header, no checkpoint into the main
file); the mechanism is unrecorded and 06_DATA_MODEL §Migrations carries what
was observed.

- `LedgerDatabase.OpenReadOnlyAsync`: existing file, `query_only`, no
  MigrationRunner; older AND newer schemas refused with the reason;
  WriteAsync/MaintainAsync throw.
- Agent: `sessions`, `consent list`, `killswitch status` open read-only
  (`Program.PrintsOnly`); `db path` opens nothing; a refusal is a console line
  with exit 7, not a crash dump. App `--diag` opens read-only.
- `OpenAsync` runs a passive checkpoint after migrating and reports it;
  `DisposeAsync` runs `wal_checkpoint(TRUNCATE)` and reports it, through the new
  `diagnostics` sink (one log line each in agent-*.log / ui-*.log).
- Tests: LedgerDatabaseTests (older schema refused byte-for-byte unchanged,
  read-only reads and refuses writes, missing file creates nothing, a close
  leaves the row readable through immutable=1); AgentReadOnlyVerbsTests.
- Docs: 06_DATA_MODEL, 12_BUILD, 10_LOGGING, HANDOFF §Traps, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 18:43:10 +07:00
1670 changed files with 108199 additions and 14658 deletions

No files matched your search

+13
View File
@@ -0,0 +1,13 @@
{
"version": 1,
"isRoot": true,
"tools": {
"dotnet-sonarscanner": {
"version": "12.0.0",
"commands": [
"dotnet-sonarscanner"
],
"rollForward": false
}
}
}
+100
View File
@@ -0,0 +1,100 @@
# ACCESSIBILITY.md (beta.35, D88) sends every accessibility barrier here. It is its own form rather than part of the bug
# report because a barrier needs different facts: what the reporter uses to read or operate the screen, and how far it
# stops them. Nothing here asks about the reporter themself.
name: Accessibility problem
description: Something in FrameLedger cannot be reached, read or seen — with the keyboard, a screen reader, a contrast theme, Magnifier or another aid
labels: [accessibility]
body:
- type: markdown
attributes:
value: |
Thank you for telling us. **You never need to tell us anything about yourself or a disability** — what you use
and what happened is enough. Screenshots and recordings help but are optional.
If FrameLedger refused to hook a game, stopped measuring or turned hooking off **without your knowing** — a
safety notice you could not perceive — say so below: it is a safety problem too, and it is handled first.
What FrameLedger aims for and what it cannot do yet: [ACCESSIBILITY.md](https://github.com/poli0981/frameledger/blob/main/ACCESSIBILITY.md).
- type: textarea
id: task
attributes:
label: What were you trying to do?
placeholder: 'e.g. switch hooking on for a game, read a session''s frame rate, answer the terms window'
validations:
required: true
- type: textarea
id: what-happened
attributes:
label: What happened instead?
description: What you heard, saw or could not do — and what you expected.
validations:
required: true
- type: textarea
id: steps
attributes:
label: How to get there
placeholder: |
1. Open Games (Ctrl+2)
2. Tab to …
3. …
- type: input
id: app-version
attributes:
label: FrameLedger version
description: Help ▸ About
validations:
required: true
- type: input
id: os
attributes:
label: Windows version
placeholder: 'Windows 11 26100.2314'
validations:
required: true
- type: dropdown
id: aid
attributes:
label: What do you use?
multiple: true
options:
- Keyboard only
- Narrator
- NVDA
- JAWS
- Windows Magnifier
- A Windows contrast theme
- Voice Access or other speech input
- Display scaling or a large text size
- Something else (say below)
validations:
required: true
- type: input
id: aid-version
attributes:
label: Its version, if you know it
placeholder: 'e.g. NVDA 2026.1'
- type: dropdown
id: severity
attributes:
label: How much does it stop you?
description: Optional — the maintainer sets it when reading the report (ACCESSIBILITY.md, How serious it is).
options:
- Not sure
- Critical — I cannot do the task at all
- Serious — only with great difficulty or a workaround
- Moderate — it is tiring or inconsistent
- Minor — it barely gets in the way
- type: textarea
id: more
attributes:
label: Anything else
description: A screenshot, a recording, or a diagnostic file from Help ▸ Report a bug (built on your PC; you choose what to attach).
+6
View File
@@ -0,0 +1,6 @@
# Where a report goes when it is not a bug, a feature or a safety gap (SECURITY.md).
blank_issues_enabled: true
contact_links:
- name: Security vulnerability (private)
url: https://github.com/poli0981/frameledger/security/advisories/new
about: A way past the guard, an injection the user did not enable, a privacy leak — report it privately, per SECURITY.md.
+20
View File
@@ -1,5 +1,16 @@
# Central package management makes NuGet PRs single-file diffs
# (docs/12_BUILD.md, docs/13_CI_CD.md).
#
# The nuget entry also covers .config/dotnet-tools.json (the SonarScanner for
# .NET, since 2026-10-25). No dotnet-sdk entry, on purpose: global.json is a
# floor (10.0.100) with rollForward latestFeature, so every machine and the CI
# runner already build with the newest 10.0 SDK they have; raising the floor is
# a decision, not an update (docs/12_BUILD.md).
#
# COOLDOWN (2026-10-25): a version update waits seven days after a release is
# published, so a release that is pulled or found compromised in its first
# week never reaches a pull request here. Security updates do not wait — the
# option does not apply to them.
version: 2
updates:
- package-ecosystem: nuget
@@ -7,6 +18,8 @@ updates:
schedule:
interval: weekly
open-pull-requests-limit: 5
cooldown:
default-days: 7
groups:
minor-and-patch:
update-types: [minor, patch]
@@ -21,7 +34,14 @@ updates:
- dependency-name: FluentAssertions
update-types: [version-update:semver-major]
# One pull request a week for the actions' minor and patch releases; a new
# major still comes alone, because it is the one that changes inputs.
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
cooldown:
default-days: 7
groups:
actions-minor-and-patch:
update-types: [minor, patch]
+15 -1
View File
@@ -30,6 +30,18 @@ review questions from `docs/19_SAFETY_AND_ANTICHEAT.md` §Review checklist.
**Measured overhead:** <!-- e.g. "0.31 µs/present, game Avg FPS delta -0.2%" -->
## User-interface changes only
Skip this section if the PR does not change what the App shows. Otherwise — `ACCESSIBILITY.md` §For contributors,
`docs/08_UI.md` §Accessibility:
- [ ] Every control that shows no text of its own has a name, from `.resx` in `en`, `vi` and `ja`
- [ ] Colours come from the theme only, and nothing is shown by colour alone
- [ ] Everything new can be reached and used with the keyboard, in reading order, and Esc leaves a new dialog
- [ ] `ACCESSIBILITY.md` (and `LIMITATIONS.md`) changed in this PR if what works or what does not moved
**Checked by hand:** <!-- e.g. "Tab through the new card with the mouse unplugged; Narrator reads its name and value" -->
## Safety-string changes only
- [ ] `Safety_*` resx keys have human-reviewed `ja` (never machine-drafted — `docs/09_I18N.md`)
@@ -38,4 +50,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). -->
+156 -11
View File
@@ -9,23 +9,29 @@
#
# So this workflow does exactly one thing of substance: ./build.ps1 check.
# Anything CI checks that local does not is a way for the two to disagree.
#
# Since 2026-10-25 (owner decision D68) a second job, `sonarcloud`, hands that
# run's coverage to SonarCloud and analyses the tree there. It is not the gate
# and not a required check: it builds again in a build of its own, and a
# SonarCloud outage or a failed quality gate is a red job beside a green
# `check`, never a blocked merge (docs/13_CI_CD.md §SonarCloud).
name: CI
on:
push:
branches: [main]
# `alpha` since 2026-10-31 (D73, docs/13_CI_CD.md §The alpha line): the same source on a prerelease .NET, whose
# merges and syncs from main need the same gate under its own global.json.
branches: [main, alpha]
pull_request:
workflow_dispatch:
# Permissions do not inherit into reusable workflows, and defaults are broader
# than this job needs either way (docs/13_CI_CD.md).
permissions:
contents: read
# For the Changelog step below only: listing a pull request's changed files is
# the Pull Requests API, and an explicit `permissions:` block grants nothing it
# does not name. Read-only, and the job writes nothing back.
pull-requests: read
# than this job needs either way (docs/13_CI_CD.md). Since the second job
# (2026-10-25) they are granted per job and the workflow grants none: a grant at
# this level reaches every job, so `sonarcloud` would have held `check`'s
# pull-requests read for nothing (SonarCloud githubactions:S8264).
permissions: {}
concurrency:
group: ci-${{ github.ref }}
@@ -35,6 +41,12 @@ jobs:
check:
runs-on: windows-latest
timeout-minutes: 40
permissions:
contents: read
# For the Changelog step below only: listing a pull request's changed files is
# the Pull Requests API, and an explicit `permissions:` block grants nothing it
# does not name. Read-only, and the job writes nothing back.
pull-requests: read
steps:
- uses: actions/checkout@v7
@@ -47,7 +59,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
@@ -166,8 +178,11 @@ jobs:
Write-Host ("vulkaninfo.exe on PATH: {0}" -f ($(if ($cmd) { $cmd.Source } else { 'no' })))
Write-Host ("HKLM:\SOFTWARE\Khronos\Vulkan\Drivers present: {0}" -f (Test-Path 'HKLM:\SOFTWARE\Khronos\Vulkan\Drivers'))
# Not for a pull request into `alpha` (D73): what the alpha line changes is written in its release's own file on
# main (docs/changelog/x.y.z-alpha.N.md), and an [Unreleased] entry on the alpha branch would collide with main's
# at every sync.
- name: Changelog
if: github.event_name == 'pull_request'
if: github.event_name == 'pull_request' && github.base_ref != 'alpha'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
@@ -178,11 +193,141 @@ jobs:
if ($LASTEXITCODE -ne 0) { throw "could not list the pull request's changed files" }
./tools/changelog-check.ps1 -ChangedFiles @($files)
# Cobertura for a person reading it, OpenCover for the sonarcloud job below
# (build.ps1 writes both from the one test run since 2026-10-25).
- name: Upload coverage
if: always()
uses: actions/upload-artifact@v7
with:
name: coverage
path: '**/TestResults/**/coverage.cobertura.xml'
path: |
**/TestResults/**/coverage.cobertura.xml
**/TestResults/**/coverage.opencover.xml
if-no-files-found: warn
retention-days: 14
# SonarCloud, analysed from CI (owner decision D68, 2026-10-25; docs/13_CI_CD.md
# §SonarCloud). A job of its own, after `check`, for two reasons:
#
# - The scanner instruments the build it wraps and turns TreatWarningsAsErrors
# off in it (SonarQube.Integration.targets), so it cannot wrap the gate's
# build without weakening the gate. It gets a build of its own here.
# - It is advisory. `main`'s required contexts stay `check` and the two
# `analyze` jobs; a failed quality gate or a SonarCloud outage turns this job
# red and blocks nothing.
#
# It takes the gate's coverage (the `coverage` artifact) rather than running
# the tests a second time, and CMake's compilation database for the C++.
# Settings: SonarQube.Analysis.xml. The scanner: .config/dotnet-tools.json.
sonarcloud:
needs: check
# A pull request from this repository, or main. SONAR_TOKEN reaches neither a
# fork's pull request nor Dependabot's, and the scanner cannot start without
# it. Any other branch is refused by the organisation's plan - "Organization
# is not allowed to access data from non main branches", measured on a
# workflow_dispatch run of a feature branch, 2026-10-25 - so a dispatch on
# one runs `check` alone. The same plan is why a pull request INTO `alpha`
# (D73) and a push to it run `check` alone: SonarCloud analyses main's line.
if: >-
(github.event_name == 'pull_request' &&
github.base_ref != 'alpha' &&
github.event.pull_request.head.repo.full_name == github.repository &&
github.event.pull_request.user.login != 'dependabot[bot]') ||
(github.event_name != 'pull_request' && github.ref == 'refs/heads/main')
runs-on: windows-latest
timeout-minutes: 40
permissions:
contents: read
steps:
- uses: actions/checkout@v7
with:
# Blame for the new-code period, and the tags for the version.
fetch-depth: 0
- name: Set up .NET
uses: actions/setup-dotnet@v6
with:
global-json-file: global.json
# The analysis of the C++ runs the compiler of the compilation database.
- name: Set up MSVC (x64)
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
with:
arch: x64
- name: Cache NuGet
uses: actions/cache@v6
with:
path: ~/.nuget/packages
key: nuget-${{ runner.os }}-${{ hashFiles('**/Directory.Packages.props', 'global.json') }}
restore-keys: nuget-${{ runner.os }}-
# The JRE the scanner provisions, and SonarCloud's analysers.
- name: Cache SonarCloud
uses: actions/cache@v6
with:
path: ~/.sonar/cache
key: sonar-${{ runner.os }}-${{ hashFiles('.config/dotnet-tools.json') }}
restore-keys: sonar-${{ runner.os }}-
# tests/<project>/TestResults/<guid>/coverage.opencover.xml, as `check` wrote
# them. Same workspace path on every hosted Windows runner, so the reports'
# absolute paths name these sources.
- name: Download the gate's coverage
uses: actions/download-artifact@v8
with:
name: coverage
# Configure only, plus the one header the build generates: the analysis
# reads the sources with the flags and defines CMake gives each one, and
# needs nothing built. FetchContent's sources land in build/, excluded.
#
# CMAKE_CXX_SCAN_FOR_MODULES=OFF: with C++20 and Ninja, CMake (3.28 on)
# scans every source for modules and gives each compile command an
# `@<object>.modmap` response file that only the BUILD writes, and the
# C/C++ analyser stops on a response file it cannot open ("unexpanded
# response file", the first run, 2026-10-25). Nothing here uses a module.
- name: Native compilation database
shell: pwsh
working-directory: src/native
run: |
cmake --preset x64-release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_SCAN_FOR_MODULES=OFF
if ($LASTEXITCODE -ne 0) { throw 'cmake configure failed' }
cmake --build --preset x64-release --target fl_ac_floor_gen
if ($LASTEXITCODE -ne 0) { throw 'generating the blocklist floor failed' }
# The version is the newest release tag the commit descends from, so the
# project's new-code period ("previous version") is everything since the
# last release.
- name: Begin the analysis
shell: pwsh
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: |
$ErrorActionPreference = 'Stop'
dotnet tool restore
if ($LASTEXITCODE -ne 0) { throw 'dotnet tool restore failed' }
$tag = git describe --tags --abbrev=0 --match 'v*' 2>$null
$version = if ($LASTEXITCODE -eq 0 -and $tag) { $tag.Substring(1) } else { (Get-Content VERSION -Raw).Trim() }
Write-Host "sonar.projectVersion: $version"
dotnet tool run dotnet-sonarscanner begin /k:poli0981_frameledger /o:poli0981 /v:$version `
/s:"$PWD\SonarQube.Analysis.xml" /d:sonar.token=$env:SONAR_TOKEN
if ($LASTEXITCODE -ne 0) { throw 'the scanner did not begin' }
# Platform: see build.ps1's Clear-VcxprojPlatform (the MSVC step exports
# Platform=x64, which MSBuild reads as a solution platform).
- name: Build for the analysis
shell: pwsh
run: |
Remove-Item Env:Platform -ErrorAction SilentlyContinue
dotnet build FrameLedger.slnx -c Release
if ($LASTEXITCODE -ne 0) { throw 'the analysis build failed' }
- name: End the analysis
shell: pwsh
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: |
dotnet tool run dotnet-sonarscanner end /d:sonar.token=$env:SONAR_TOKEN
if ($LASTEXITCODE -ne 0) { throw 'the analysis failed, or its quality gate did' }
+17 -1
View File
@@ -7,6 +7,12 @@
# Repo-local for now. The ops repo has codeql-mixed.yml, but C++ needs manual
# build mode driven by the CMake preset, and that input surface has not been
# verified. Switch to a caller stub once it has.
#
# AND the workflows themselves, since 2026-10-25: CodeQL's `actions` language
# reads .github/workflows for injection from event data, untrusted checkouts
# and over-broad tokens — the same class of finding SonarCloud raised once
# (githubactions:S7631, wiki.yml, beta.26). Its context, `analyze (actions,
# none)`, is not one of main's required checks.
name: CodeQL
@@ -22,6 +28,14 @@ permissions:
contents: read
security-events: write
# A new push to a pull request replaces its run. A push to main and the weekly
# scan each get a group of their own (the run id), so none of them is ever
# cancelled or left pending behind another, and the default branch's alerts
# always come from a finished analysis.
concurrency:
group: codeql-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
cancel-in-progress: true
jobs:
analyze:
runs-on: windows-latest
@@ -35,6 +49,8 @@ jobs:
build-mode: none
- language: cpp
build-mode: manual
- language: actions
build-mode: none
steps:
- uses: actions/checkout@v7
@@ -47,7 +63,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
+136 -15
View File
@@ -21,12 +21,35 @@
# channel sees it. The managed assemblies take the tag's full version through
# -p:Version; the native blocks keep the numeric core (CMake's project() accepts
# nothing else).
#
# THE ALPHA LINE (2026-10-31, owner decisions D73-D76; 12_BUILD §The alpha line): the
# RELEASE_LINE file says `alpha` on the long-lived `alpha` branch, where the same source
# builds on a prerelease .NET. Its tags are `vX.Y.Z-alpha.N` and nothing else, no other
# line may carry one, and its packages go to Velopack's `alpha` channel
# (releases.alpha.json) - which no beta reads, as no alpha reads releases.win.json
# (11_UPDATER §Channels). The version gate below enforces all three.
#
# A DRY RUN (2026-09-16, P5 prep): `workflow_dispatch` with a version runs every
# step below — the gate, the publish, the tree assertion, vpk, the checksums — and
# uploads the result as a workflow artifact, but creates no tag and no Release.
# It is the first-tag measurement without the tag: 13_CI_CD §release.yml said the
# workflow "has not been exercised by a tag yet", and everything after the version
# gate had only ever run by hand on one machine. In a dry run a missing
# `## [x.y.z]` CHANGELOG section is a printed warning with placeholder notes rather
# than a stop, because the section is written in the tag commit and a dry run
# precedes it; on a real tag it stays a hard stop.
name: Release
on:
push:
tags: ['v*']
workflow_dispatch:
inputs:
version:
description: 'Version to rehearse (e.g. 0.1.0-beta.1): numeric core must equal VERSION; no tag, no Release'
required: true
type: string
# The Release API is contents: write; nothing else is needed and nothing else is granted.
permissions:
@@ -50,7 +73,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
@@ -71,9 +94,13 @@ jobs:
- name: Version gate (tag vs VERSION, CHANGELOG section)
id: version
shell: pwsh
env:
DRY_RUN: ${{ github.event_name == 'workflow_dispatch' }}
DISPATCHED_VERSION: ${{ inputs.version }}
run: |
$ErrorActionPreference = 'Stop'
$tag = $env:GITHUB_REF_NAME
$dry = $env:DRY_RUN -eq 'true'
$tag = if ($dry) { 'v' + $env:DISPATCHED_VERSION.TrimStart('v') } else { $env:GITHUB_REF_NAME }
$m = [regex]::Match($tag, '^v(\d+\.\d+\.\d+)(-[0-9A-Za-z.]+)?$')
if (-not $m.Success) { throw "tag '$tag' is not vMAJOR.MINOR.PATCH[-prerelease]" }
$full = $tag.Substring(1)
@@ -81,12 +108,45 @@ jobs:
$pre = if ($m.Groups[2].Success) { 'true' } else { 'false' }
$file = (Get-Content VERSION -Raw).Trim()
if ($core -ne $file) { throw "tag $tag has numeric core $core but VERSION says $file — bump VERSION in the same commit as the changelog section, then tag" }
# D73: the release line this commit builds (Directory.Build.props refuses any other value too) and the tags it may
# carry - an alpha's on the alpha line only, and nothing else there.
$line = (Get-Content RELEASE_LINE -Raw).Trim()
if ($line -cnotin @('main', 'alpha')) { throw "RELEASE_LINE says '$line'; it must be main or alpha" }
$suffix = $m.Groups[2].Value
if ($line -eq 'alpha' -and $suffix -cnotmatch '^-alpha\.\d+$') { throw "this commit is on the alpha line (RELEASE_LINE); its tag must be vX.Y.Z-alpha.N, not $tag" }
if ($line -ne 'alpha' -and $suffix -match 'alpha') { throw "tag $tag names an alpha, but RELEASE_LINE says '$line': an alpha is tagged on the alpha branch, nowhere else" }
$channel = if ($line -eq 'alpha') { 'alpha' } else { 'win' }
New-Item -ItemType Directory -Force out | Out-Null
./tools/release-notes.ps1 -Version $full -OutFile out/notes.md
if ($LASTEXITCODE -ne 0) { throw 'release notes' }
if ($LASTEXITCODE -ne 0) {
if (-not $dry) { throw 'release notes' }
Write-Host "::warning::CHANGELOG.md has no '## [$full]' section yet - a dry run continues with placeholder notes; a real tag stops here"
[System.IO.File]::WriteAllText('out/notes.md', "DRY RUN of $full - CHANGELOG.md has no ``## [$full]`` section yet.`n", [System.Text.UTF8Encoding]::new($false))
# The runner's pwsh wrapper ends the step with `exit $LASTEXITCODE`, so a handled failure must clear it
# (measured 2026-09-16: the first rehearsal printed the warning and then failed with the script's exit 1).
$global:LASTEXITCODE = 0
}
"version=$full" >> $env:GITHUB_OUTPUT
"prerelease=$pre" >> $env:GITHUB_OUTPUT
Write-Host "releasing $full (pre-release: $pre)"
"channel=$channel" >> $env:GITHUB_OUTPUT
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre; line: $line; Velopack channel: $channel)"
# 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
@@ -121,9 +181,14 @@ jobs:
run: |
$ErrorActionPreference = 'Stop'
$v = '${{ steps.version.outputs.version }}'
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
# beta.12: the App's links into the repository open the documents of THIS release (Services/RepositoryLinks.cs):
# the tag, or for a rehearsal - which has no tag - the commit it was built from.
$ref = if ('${{ steps.version.outputs.dry_run }}' -eq 'true') { '${{ github.sha }}' } else { "v$v" }
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -p:FrameLedgerSourceRef=$ref -o out/app
if ($LASTEXITCODE -ne 0) { throw 'App publish failed' }
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
# beta.14 (D50): the same ref for the Agent - Directory.Build.props stamps it on every assembly, and both
# publishes build the same libraries into this one folder.
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -p:FrameLedgerSourceRef=$ref -o out/app
if ($LASTEXITCODE -ne 0) { throw 'Agent publish failed' }
# A self-contained package redistributes the .NET runtime, and its licence and
@@ -150,7 +215,7 @@ jobs:
}
Get-ChildItem $dest | ForEach-Object { Write-Host (" {0,-64} {1,8:N0}" -f $_.Name, $_.Length) }
# What ships is what matters: the two entry points and the four shipped native
# What ships is what matters: the two entry points and the five shipped native
# binaries (versioninfo-check's list) must be in the tree, and the unshipped
# capture host must not be (package-closure-check proves it statically; this
# reads the directory).
@@ -158,14 +223,18 @@ jobs:
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'rules/detection-rules.json',
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'FrameLedger.ProcessStats.dll', 'rules/detection-rules.json',
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/NOTICE.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
$missing = @($required | Where-Object { -not (Test-Path (Join-Path out/app $_)) })
if ($missing.Count -gt 0) { throw "out/app is missing: $($missing -join ', ')" }
if (Test-Path out/app/FrameLedger.CaptureHost.exe) { throw 'out/app contains the unshipped capture host (12_BUILD: exactly two roots)' }
if (@(Get-ChildItem out/app/licenses/dotnet -File -ErrorAction SilentlyContinue).Count -lt 2) { throw 'out/app/licenses/dotnet holds fewer than two files -- the runtime licence step did not run' }
./tools/versioninfo-check.ps1 -BuildDir out/app
# beta.14 (D50): the managed half too - the eight managed binaries, carrying the tag's full version.
./tools/versioninfo-check.ps1 -BuildDir out/app -ManagedDir out/app -ExpectedProductVersion '${{ steps.version.outputs.version }}'
if ($LASTEXITCODE -ne 0) { throw 'versioninfo-check over the published tree' }
# beta.18: the native binaries carry the build id read from the clean checkout, exactly - never "<tag>-dirty".
./tools/buildid-check.ps1 -BuildDir out/app -Expected $env:FL_BUILD_ID
if ($LASTEXITCODE -ne 0) { throw 'buildid-check over the published tree' }
$size = (Get-ChildItem out/app -Recurse -File | Measure-Object Length -Sum).Sum / 1MB
Write-Host ("published tree: {0:N0} MB" -f $size)
@@ -179,17 +248,66 @@ 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
dotnet tool install -g vpk --version 1.2.161
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
$v = '${{ steps.version.outputs.version }}'
vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
# D73: `win` (Velopack's default on Windows) for the main line, `alpha` for the alpha line - each release's feed
# and the previous release its delta is made from are its own line's. The main line's pack keeps its exact
# command (no --channel), so a beta is packed as every beta before the alpha line existed.
$channel = '${{ steps.version.outputs.channel }}'
New-Item -ItemType Directory out/release -Force | Out-Null
vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel $channel --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) }
$pack = @('pack', '--packId', 'FrameLedger.App', '--packVersion', $v, '--packDir', 'out/app', '--mainExe', 'FrameLedger.exe', '--packTitle', 'FrameLedger', '--packAuthors', 'FrameLedger', '--releaseNotes', 'out/notes.md', '--outputDir', 'out/release')
if ($channel -ne 'win') { $pack += @('--channel', $channel) }
vpk @pack
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
$assets = "assets.$channel.json"
$index = "releases.$channel.json"
$legacyName = if ($channel -eq 'win') { 'RELEASES' } else { "RELEASES-$channel" }
$built = @((Get-Content "out/release/$assets" -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
if ($built.Count -eq 0) { throw "vpk pack wrote no $assets entries" }
$keep = $built + @($index, $assets, $legacyName)
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/$index" -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/$index"), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
if (Test-Path "out/release/$legacyName") {
$legacy = @(Get-Content "out/release/$legacyName" | Where-Object { $built -contains ($_ -split ' ')[1] })
[System.IO.File]::WriteAllLines((Join-Path $PWD "out/release/$legacyName"), [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) }
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)' }
Write-Host ('feed: ' + (($feed.Assets | ForEach-Object { '{0} {1} {2}' -f $_.Type, $_.Version, $_.FileName }) -join '; '))
$setup = "FrameLedger.App-$channel-Setup.exe"
if (-not (Test-Path "out/release/$setup")) { throw "vpk did not produce $setup (README §Install names the beta's, guide/11-alpha-builds.md the alpha's)" }
# The delta is the one this pack listed, not a name built here: Velopack puts a non-default channel in its packages'
# names (FrameLedger.App-<v>-alpha-full.nupkg - measured on the 0.1.0-alpha.1 rehearsal, 2026-10-31), so the name
# this step built for the default channel would have failed the second alpha.
$delta = @($built | Where-Object { $_ -like '*-delta.nupkg' })
if (Get-ChildItem out/previous -Filter '*-full.nupkg' -ErrorAction SilentlyContinue) {
if ($delta.Count -ne 1) { throw "the previous full package was downloaded, but vpk produced no delta ($assets lists: $($built -join ', '))" }
} else {
Write-Host '::warning::no previous full package - this release carries no delta'
}
- name: Checksums
shell: pwsh
@@ -205,13 +323,16 @@ jobs:
Get-Content out/release/SHA256SUMS.txt
- name: Create the GitHub Release
if: steps.version.outputs.dry_run != 'true'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
run: |
$ErrorActionPreference = 'Stop'
$v = '${{ steps.version.outputs.version }}'
$ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', "FrameLedger $v", '--notes-file', 'out/notes.md', '--verify-tag')
# An alpha says what it is in the list of releases too, not only in its notes (D74).
$title = if ('${{ steps.version.outputs.channel }}' -eq 'alpha') { "FrameLedger $v (experimental alpha)" } else { "FrameLedger $v" }
$ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', $title, '--notes-file', 'out/notes.md', '--verify-tag')
if ('${{ steps.version.outputs.prerelease }}' -eq 'true') { $ghArgs += '--prerelease' }
$ghArgs += Get-ChildItem out/release -File | ForEach-Object { $_.FullName }
gh @ghArgs
@@ -221,7 +342,7 @@ jobs:
if: always()
uses: actions/upload-artifact@v7
with:
name: release-${{ github.ref_name }}
name: release-${{ steps.version.outputs.version || github.ref_name }}${{ steps.version.outputs.dry_run == 'true' && '-dry-run' || '' }}
path: |
out/release/**
out/notes.md
+6 -4
View File
@@ -1,9 +1,11 @@
# Gate changes to the detection + anti-cheat rules (docs/13_CI_CD.md).
#
# The raw file on `main` IS the distribution endpoint (docs/05_DETECTION.md),
# so there is nothing to publish — this workflow only gates correctness. That
# also means a bad merge ships to every user on their next rules check, which
# is why the anticheat block gets extra scrutiny here.
# There is nothing to publish: no rules feed exists (docs/20_OPEN_QUESTIONS.md
# §S20 feed half), so a rules change reaches users inside a release, seeded by
# the Agent from the packaged copy. This header said the raw file on `main` was
# the distribution endpoint until 2026-10-04. This workflow only gates
# correctness, and the anticheat block still gets the extra scrutiny, because
# whatever merges here ships in the next release.
name: Rules
+106
View File
@@ -0,0 +1,106 @@
# 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 and ACCESSIBILITY.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 - in THIS repository. A fork cannot start this repository's Release run (it runs on a tag push or by
# hand), so the head checked out below is always the owner's; the repository check says so in the condition rather
# than leaving it to release.yml's triggers (SonarCloud githubactions:S7631, beta.26).
# Nor does an alpha's release (D73, 2026-10-31): the wiki shows the newest beta, and an alpha's tag is on the `alpha`
# branch, whose guide is the beta's it was cut from - publishing it would only move the wiki's links off main's line.
if: >-
github.event_name == 'workflow_dispatch' ||
(github.event.workflow_run.conclusion == 'success' &&
github.event.workflow_run.event == 'push' &&
github.event.workflow_run.head_repository.full_name == github.repository &&
startsWith(github.event.workflow_run.head_branch, 'v') &&
!contains(github.event.workflow_run.head_branch, '-alpha.'))
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"
+168
View File
@@ -0,0 +1,168 @@
# Accessibility
FrameLedger should be usable by everyone who plays games on a Windows PC — with a keyboard alone, with a screen reader,
with a Windows contrast theme or Magnifier, and without telling colours apart. This page says what FrameLedger aims
for, what works today, how that was checked, what does not work yet and what to do instead, and how to tell us about a
barrier. It is written for the person who has just met one; the details for developers are in
[`docs/08_UI.md`](docs/08_UI.md#accessibility).
FrameLedger is a desktop program: its own window, its dialogs, its document windows, the icon by the clock and the
notices Windows shows for it. It draws nothing inside a game, so it cannot make a game itself any easier to use.
*Beta software: this page describes version 0.1.0-beta.35. In the app: Help ▸ Accessibility.*
## What FrameLedger aims for
- **WCAG 2.2 at level AA**, applied to desktop software as W3C's
[WCAG2ICT](https://www.w3.org/TR/wcag2ict-22/) guidance explains. This is a goal that guides the work, not a claim:
no formal evaluation has been made, and FrameLedger does not say it conforms to any standard.
- **Every task can be done with the keyboard alone.**
- **A screen reader can read every control and every value**, in the language FrameLedger is shown in, and hears what
changes — a notice, a result.
- **Text and controls keep their contrast** in the light and the dark theme and under Windows contrast themes, and
**colour is never the only way something is shown.**
- **Everything stays sharp at any display scale**, and when the window moves between screens.
## What works today
### The keyboard
| Keys | What they do |
|---|---|
| **Ctrl+1** … **Ctrl+5** (also with the numeric keypad) | Open Dashboard, Games, Compare, Logs and Settings, and move the keyboard into that page; a screen reader hears its title. |
| **Alt** or **F10**, then the arrow keys and **Enter** | Move to the menus. **Alt** with a menu's underlined letter opens it (*File*, *Tools*, *Help* in English). |
| **Tab** and **Shift+Tab** | Move through a page or a dialog in reading order. |
| The **arrow keys**, **Home**, **End**, **Page Up**, **Page Down** | Move inside a list or a table — a game's sessions, the games list, the Compare list, the import checklist. |
| **Enter** or **Space** | Press the button, switch or box that has the focus. **Enter** on a game in the list opens its page. |
| **Esc** | Closes a dialog the way its **Close** or **Cancel** button does: nothing is changed. A dialog that has no Close button waits for an answer, and the terms window has its own **Decline** and **Accept**. |
| **Enter** in the hooking warning | Switches hooking on once the phrase is typed exactly; before that it does nothing. |
| On a chart: the **arrow keys**, **Ctrl** with an arrow, **A** | Tab reaches every chart. The arrows move its view, Ctrl with an arrow zooms, A shows all of it again (so does a double-click); the page around it stays put. |
The same keys are in the user guide, [The screens](guide/07-screens.md#keyboard-and-mouse).
### Screen readers
- **Every page, menu, dialog and setting can be reached and used with Narrator.** The owner checked this on
2026-11-09, keyboard only with the mouse disconnected, on 0.1.0-beta.34 and 0.1.0-alpha.3, and found no fault.
- **Every page has headings**: its title is a heading of the first level, each section one of the second, so a screen
reader's heading keys move from section to section.
- **Every chart says what it is and where its numbers are written as text**, and which keys move it.
- **Every button, switch and box that shows no text of its own has a name**, from the same translations as the screen.
- **Lists, drop-down options and table cells are read by the words they show**, and a button repeated on each row names
its row — *Open: 11/9/2026 14:03*, *Play: Cyberpunk 2077*, *Turn off: Cyberpunk 2077*.
- **The frame-rate readout says the game's own frames, the displayed frames and the frame-generation factor together**
(*Native 62 FPS, displayed 118 FPS, frame generation ×1.9*) — never the larger number alone; a ray-tracing chip says its
value and where it came from (*Ray Tracing: Yes, measured*).
- **What appears is said as it appears**: a safety notice (hooking refused, measuring stopped, hooking turned off), the
capture agent going away and coming back, an update's steps, a short message at the bottom of the window, a notice on a
game's page and a result of **Tools ▸ Database maintenance** — in the words shown, while FrameLedger's window is the
active one. While a game has the screen nothing interrupts it; the notice stays in the window, and Windows' own
notifications from the icon by the clock are read by the screen reader itself.
- **The notices above the page can be read where they are shown**, and the button that answers one says which notice it
answers.
- **Tab goes from control to control**: pictures, lists and the rows of Settings are not stops of their own.
- **Dialogs say they are dialogs**, keep the focus inside them until they close, and then give it back to the control
that opened them. A message box opens over FrameLedger's window, never behind it.
### Seeing the screen
- **Light, dark, or the same as Windows** (Settings ▸ Theme). FrameLedger takes every colour from the theme, and every
text is measured against what is painted under it, in both themes.
- **Windows contrast themes** (Settings ▸ Accessibility ▸ Contrast themes) — Aquatic, Desert, Dusk, Night sky, or one
whose colours you changed: every colour in the window becomes one of the theme's, whatever Settings ▸ Theme says, as
soon as you turn one on, edit it or turn it off. The charts draw in its colours too, their lines and marks still told
apart by pattern, and Settings ▸ Theme says a contrast theme is in use.
- **The colour a game's picture lends its page** is used only as far as every text on it still reads, and never under a
contrast theme.
- **Windows display scaling** at any size, on every screen; **Magnifier** (Windows logo key + Plus) works as with any
program.
- Labels such as *Hooking on* and *Not installed*, and the ray-tracing chips, always carry their words; a chip that reads
*N/A* is also drawn with a dashed edge.
- **No chart tells two series apart by colour alone**: its lines are solid, dashed or dotted, its points circles,
triangles or squares, its shaded stretches striped or dotted.
### Languages
FrameLedger is shown in English, Vietnamese or Japanese (Settings ▸ Language), and the names a screen reader reads come
from the same translations. The documents — the user guide, this page, the legal texts — are in English.
## How it is checked
- **On every build**, by the project's own tests: what a screen reader is given for every page, window and dialog —
every place Tab stops has a name, no list or table item is read by its program name, no text is hidden from a screen
reader inside a control, no two buttons in a list share a name; each thing that appears is said once, in its words;
every page has one first-level heading and every section title a level; no chart tells two series apart by colour
alone; a chart's keys move it and stay its own; every control that shows no text has a name; no colour is written
into a screen; every text reads against its background in both themes and after a theme switch, and under Windows'
four contrast themes and two edited ones is drawn in the theme's own colours at 4.5:1 or better; **Esc** closes the
open dialog without an answer, and a dialog gives the focus back; **Ctrl+1** … **Ctrl+5** open the pages in their
order and move the keyboard into them; a page slides in only while Windows' animation effects are on; the program
declares it follows each screen's scaling.
- **By hand**: the owner's pass of 2026-11-09 above, repeated for each release that changes a screen.
- **Not tested yet**: NVDA, JAWS, Voice Access, touch, Windows 10, and other people's PCs. They should work through the
same Windows interface Narrator uses, but nobody has checked. Contrast themes are checked by the tests above and have
not yet been looked at on a screen.
## Known limitations
Each one with what to do instead. A barrier that is not on this list is worth reporting.
- **A chart's points cannot be read one by one.** A screen reader hears the chart's name and where its numbers are:
a session's figures and *Statistics per series* in its summary, the table under the Compare chart, the Sessions table
and the list of changes under a trend chart, and **File ▸ Export ▸ Session CSV** or **Session JSON**.
- **In the user guide and the other documents the app shows, headings are read as ordinary text**: Windows' document
view gives them no heading role. Their links and their order work as on any page.
- **The short messages at the bottom of the window close after four seconds**, and cannot be read again once closed. A
screen reader is told each one as it appears.
- **Windows' text size setting** (Settings ▸ Accessibility ▸ Text size) **is not followed.** Use display scaling
(Settings ▸ System ▸ Display ▸ Scale) or Magnifier.
- **Pausing capture is only in the menu of the icon by the clock.**
- **The windows Windows itself shows** — choosing a file, the administrator prompt — are Windows', not FrameLedger's.
## Report an accessibility problem
1. Open an issue with the
[Accessibility problem form](https://github.com/poli0981/frameledger/issues/new?template=accessibility.yml).
2. Say what you were trying to do and what happened instead; your FrameLedger version (Help ▸ About) and your Windows
version; and what you use — the keyboard alone, Narrator, NVDA, JAWS, Magnifier, a contrast theme — with its version.
The steps to get there help, and so does a screenshot or a recording, but neither is required. **You never need to
tell us anything about yourself or a disability.**
3. If you want to attach details from your PC, **Help ▸ Report a bug** builds them into a file on your PC and shows you
what is inside first; nothing is uploaded by itself.
**A safety notice you could not perceive** — hooking refused, measuring stopped or hooking turned off, without your
knowing — is a safety problem as well: say so in the report, and it is handled first.
### How serious it is
You do not have to choose; the maintainer sets it when reading the report.
| Severity | What it means | For example |
|---|---|---|
| **Critical** | A task cannot be done at all. | Hooking cannot be switched off with the keyboard; the terms window or the hooking warning cannot be answered; a safety notice cannot be read. |
| **Serious** | It can be done only with great difficulty or a workaround. | A value can be read only by exporting the session. |
| **Moderate** | It is tiring or inconsistent. | A name that differs from what the screen shows; an extra stop for Tab. |
| **Minor** | It barely gets in the way. | A tooltip the keyboard cannot reach, when its words are shown elsewhere too. |
### What happens next
FrameLedger has one maintainer, so there are no promised times. Every report is read and answered, without doubting what
you describe. Critical problems come before other work; a workaround, when there is one, is written on the issue; the
fix ships in a release, and the issue is closed once you say it works for you — or when a fix has been out for a while
and nobody has answered.
## Who looks after this
The project's owner, poli0981, keeps this page and the checks behind it, and reviews both for each release that changes
a screen. A change to FrameLedger that moves anything on this page changes the page in the same pull request.
## For contributors
A change to the App keeps what the tests above hold: a name, from the translations in all three languages, for every
control that shows no text; colours only from the theme. Say in the pull request what you checked with the keyboard
and with Narrator. The rules and the checks are in [`docs/08_UI.md`](docs/08_UI.md#accessibility) and
[`CONTRIBUTING.md`](CONTRIBUTING.md).
## Feedback
To improve this page, open an issue or a pull request. A barrier goes through the form above, so that it is not lost.
+71 -4321
View File
File diff suppressed because it is too large. Load diff
+76 -17
View File
@@ -12,16 +12,26 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
1. **Injection is opt-in, per game, never automatic.** The user must add the game *and* enable hooking for it. There is no "hook everything" mode, no global auto-inject.
2. **The anti-cheat guard is a hard gate, not a warning.** Before injecting, scan the target for known anti-cheat/anti-tamper modules (`19_SAFETY`). If any is found → **refuse**, log, tell the user why. There is no override switch, no "I understand, continue anyway" button. Do not add one.
> **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 *(within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder)*, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
> **Amended 2026-10-03 (owner decision D38): the evidence moved from before the grant to its trial.** "≥ 2 successful Tier-1 sessions" above could never be met by a game blocked at add time — since beta.8 that is every blocked game — nor after a ledger reset. Asked with that, the owner chose: a grant needs no session; the first two hooked sessions under it are a trial, and any end during the trial (a crash, a safety unhook, a floor stop, a new finding, or a stored hooked session with no frames or an abnormal exit) ends the exception **for good** (`games.ac_exception_trial_failed_at`, schema 0017, never cleared). Every other condition above is unchanged, and so is the last sentence.
3. **Never implement evasion.** No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented `LoadLibraryW`. The DLL keeps its real name, real exports, and version info. A performance tool must be *visible* to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle.
4. **Never read or write game memory outside our own hooks.** We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
5. **The hook must never crash the game.** Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (`17_HOOK_ENGINE` §Fault policy).
6. **FPS display rule (product requirement):** wherever FPS is shown and Frame Generation is active, show *Native FPS*, *Displayed FPS*, and the FG factor together (`62 → 118 FPS (×1.9 FG)`). Never a single inflated number. See `docs/03_METRICS.md`.
> **Amended 2026-09-03 (owner decision).** When frame generation is *not measured* — `FL_MEASURED_FG` clear, which is every title on today's writer — the one number that may stand alone is **Presented FPS** (`presents / D`), with a mandatory qualifier from the **runtime census** (`FlWriterState.runtimeCensus`): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. **The census never produces `none`**: a statically linked FSR has no module to see, and a census-`none` there would be exactly the inflated number this rule forbids.
> **Amended 2026-09-03 (owner decision).** When frame generation is *not measured* — `FL_MEASURED_FG` clear, ~~which is every title on today's writer~~ which is every title with no Streamline or FidelityFX hook live *(corrected 2026-10-04: the writer sets it since #103, 2026-09-03)* — the one number that may stand alone is **Presented FPS** (`presents / D`), with a mandatory qualifier from the **runtime census** (`FlWriterState.runtimeCensus`): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. **The census never produces `none`**: a statically linked FSR has no module to see, and a census-`none` there would be exactly the inflated number this rule forbids.
>
> **Amended 2026-09-05.** A counted `none` (`presents = application frames`) is **withheld** — Presented FPS with a third qualifier, "this number counts application frames; the Displayed rate is unknown" — on the one shape measured to produce a false `none`: Streamline ≥ 2.8.0 with `sl.dlss_g.dll` loaded (Dying Light: The Beast, five captures, DLSS FG ×4 per the owner). `docs/03_METRICS.md` §Frame Generation carries the key and why it is the Streamline plugin rather than `nvngx_dlssg.dll`; `20_OPEN_QUESTIONS` §H5 carries the session that keeps or withdraws it.
>
> **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*).
@@ -32,14 +42,15 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
| Concern | Choice |
|---|---|
| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md` |
| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md`. **The `alpha` branch** (D73–D76, 2026-10-31) builds the same source on a prerelease .NET — .NET 11 RC3, C# 15 — and differs from main only where `docs/12_BUILD.md` §The alpha line lists; code on main must keep compiling as C# 14 on .NET 10, so no C# 15 syntax |
| Native | **C++20, MSVC v143+, `/MT` static CRT, `/GS`, `/guard:cf`, no RTTI, no C++ exceptions in hook paths** |
| Hooking | **MinHook** (BSD-2-Clause) for inline hooks; direct vtable-entry swap for COM interfaces |
| Vulkan | **Implicit Vulkan layer** (`VK_LAYER_FRAMELEDGER_overlay`), not hooking — `17_HOOK_ENGINE` §Vulkan |
| UI | WPF + WPF UI (`WPF-UI` pinned = 4.3.0) + CommunityToolkit.Mvvm — `docs/16_WPFUI_SYNTAX.md` |
| App composition | .NET Generic Host + DI in `FrameLedger.App` |
| Charts | ScottPlot 5 |
| GPU telemetry | Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
| Markdown in the App | **Markdig** (BSD-2-Clause, pinned ~~1.4.0~~ 1.5.0 since beta.31 — 1.4.2 in beta.30) → WPF `FlowDocument`, HTML off, no image fetched — the Legal Gate, the user guide, Help ▸ Limitations, Help ▸ Accessibility (beta.35, D88), the update notes, About (beta.12; row added 2026-10-04) |
| GPU telemetry | **The game process's own memory since beta.12 (D43):** `FrameLedger.ProcessStats.dll` (C++, loaded by the Agent, never into a game) reads its dedicated/shared GPU memory from the `GPU Process Memory` counters and its working sets from `GetProcessMemoryInfo` — `18_GPU_VENDOR_APIS` §The game process's memory. Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
| CPU/board sensors | LibreHardwareMonitorLib ≥ 0.9.6 (PawnIO) — **optional**, elevated only |
| Tier-2 fallback | **There is none, and Tier 2 is not a measurement.** Owner decision 2026-08-28: the ladder is two rungs — hooked, or duration + sensors + the reason. ~~ETW-based, no injection~~; ~~Intel PresentMon console binary~~ dropped 2026-08-27 after §S31 retired it. Whether a shipped build ever regains a no-injection measurement is `docs/20_OPEN_QUESTIONS.md` §G |
| Storage | SQLite via Microsoft.Data.Sqlite + Dapper (no EF) |
@@ -54,14 +65,25 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
```
FrameLedger.slnx # XML solution format (SDK default since .NET 10)
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
LIMITATIONS.md ACCESSIBILITY.md # what the software cannot do; the accessibility statement (D36, D88)
global.json # pins the SDK band — see 12_BUILD
RELEASE_LINE # `main`, or `alpha` on the alpha branch (D73, 2026-10-31) — 12_BUILD §The alpha line
build.ps1 # the quality gate; CI runs this identical script
SonarQube.Analysis.xml # SonarCloud's settings for ci.yml's sonarcloud job (D68, 2026-10-25; it replaced
.config/dotnet-tools.json # .sonarcloud.properties) and the scanner it runs — 13_CI_CD §SonarCloud
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)
FrameLedger.ProcessStats/ # C++ DLL loaded by the Agent (never a game): the game process's memory (beta.12, D43)
tests/ tools/ third_party/ # ctest suites; probes, hook-harness, vendor stubs; vendored headers
# (these three lines added 2026-10-04 — the list stopped at Shm)
FrameLedger.Domain/ # entities, metric calculators — zero dependencies
# (Metrics/ WRITTEN 2026-09-09, P2 PR-A: frame times,
# percentiles, lows, stutter, the FG window and its
@@ -80,7 +102,8 @@ src/
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
# reader, HeldProcessLivenessSource, TargetResolver (path only,
# never a pid), ProcessLauncher, the module snapshot, the marker scan
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + ShmRecord struct mirror
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + the struct mirror (ShmLayout.cs;
# it said "ShmRecord", a type that never existed, until 2026-10-04)
FrameLedger.Agent/ # capture orchestrator: watcher, injector control, shm drain, recorder
# BUILT 2026-09-10 (P2 PR-F): a Generic Host. `--serve` = watcher
# (Application.Watch: ProcessWatcher, ProcessTree, DescendantElection,
@@ -97,7 +120,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
@@ -110,12 +135,21 @@ src/
# is not what holds rule 1.
tests/
FrameLedger.Domain.Tests/ FrameLedger.Application.Tests/ FrameLedger.Infrastructure.Tests/
FrameLedger.Agent.Tests/ FrameLedger.App.Tests/
FrameLedger.CaptureHost.Tests/ # incl. the Category=Integration end-to-end case
native/FrameLedger.Overlay.Tests/ # Catch2: ring buffer, record encode, fault policy
tools/ # changelog-check, chokepoint-check, coverage-gate, gen-ac-floor,
# hookinventory-check, license-check, package-closure-check,
# rules-validate, vendor-exports, versioninfo-check,
# vklayer-blastradius
Shared/ fixtures/ # test helpers; the detection corpus and other fixtures
~~native/FrameLedger.Overlay.Tests/~~ # never existed (corrected 2026-10-04): the native tests are
# src/native/tests/ (ctest, mostly Catch2 — ring, guard, layout,
# vklayer, unhook, rules budget, NVAPI bridge, process stats)
tools/ # accuracy-check, changelog-check, chokepoint-check, coverage-gate,
# gen-ac-floor, hookinventory-check, license-check, license-gather
# (+ license-overrides/), notice-check, package-closure-check,
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
# versioninfo-check, vklayer-blastradius, fps-impact-runbook,
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate),
# buildid-check (beta.18: the release's build id in the shipped natives),
# 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
# resx-gen (the committed Strings.Designer.cs generator).
@@ -123,19 +157,31 @@ tools/ # changelog-check, chokepoint-check, coverage-gat
# fl-layout-dump -> struct offsets for the C# mirror test
# hook-harness -> dummy D3D11 + D3D12 + Vulkan + OpenGL app
# (--vulkan since #140, --opengl since #141)
# fl-probe-* -> guard, hook profile, interposer, NVAPI, process
# stats, signer, Vulkan layer; fl-baseline-probe;
# vendor-stubs/ -> fixture DLLs with the vendors' export names
rules/detection-rules.json # engine/platform/capability + anticheat blocklist
guide/ # the user guide (beta.12, D44): ~~eight~~ short English pages for players, embedded in the
# App (Help > User guide); README.md is its contents. docs/ is for developers.
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
# and the guide is the wiki's End-user part)
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
# publishes them with guide/, LIMITATIONS.md and ACCESSIBILITY.md to the Wiki tab at a release;
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
docs/ legal/ legal/licenses/
```
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **Two facades since 2026-09-10:** `NativeAntiCheatGuard` (required — absent throws) and `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself), both by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why a third facade claims a name there rather than setting its own.
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **~~Two~~ Three facades since ~~2026-09-10~~ 2026-10-03:** `NativeAntiCheatGuard` (required — absent throws), `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself) and, since beta.12 (D43), `NativeProcessStats` (optional — the game process's own memory, read from outside the game; absent reads N/A), all by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why the third facade claims a name there rather than setting its own.
## Coding conventions
**C# —** `Nullable enable`, `TreatWarningsAsErrors`, `AnalysisLevel latest-all`, file-scoped namespaces, Roslynator + Meziantou + VS Threading analyzers, `dotnet format` clean. Async suffixed `Async`, `ConfigureAwait(false)` off the UI. All user-visible strings from `.resx`. Timestamps UTC (unix-ms in SQLite); QPC ticks only inside the capture pipeline.
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: `/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`).
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: ~~`/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`)~~ CodeQL (`codeql.yml`, a required check); `/analyze` and clang-tidy are not configured *(corrected 2026-10-04)*. SonarCloud analyses the C++ too, from CMake's compilation database, in `ci.yml`'s advisory `sonarcloud` job *(since 2026-10-25, D68 — `13_CI_CD` §SonarCloud)*.
**Struct mirroring —** `FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock` each exist twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by `tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
**Licence header —** every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`) opens with two comment lines, `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` (beta.12, owner decision D45). GPLv3 §7 requires additional terms to be named in the source files, and `NOTICE` holds them — (b) preserve the notices, (c) mark modified versions, (e) no trademark rights in the name. `tools/notice-check.ps1` is a `build.ps1` gate; `-Fix` writes a missing header. `src/native/third_party/` is excluded.
**Struct mirroring —** ~~`FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock`~~ `FlShmHandshake`, `FlWriterState`, `FlControlBlock`, `FlDisplayState` (layout 4, beta.10), `FlFrameRecord` and `FlTolerance` (D33, beta.9) each exist twice *(corrected 2026-10-04)*: `src/native/FrameLedger.Shm/include/fl_shm.h` / `fl_tolerance.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by ~~`tools/fl-layout-dump`~~ `src/native/tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReferences`), because offsets cannot see it: measured 2026-08-05, swapping the `fixed byte BuildId[32]` for this repo's own `[MarshalAs(ByValTStr)] string` idiom keeps `Marshal.SizeOf` at 64 and every offset correct while `Unsafe.SizeOf` collapses to **40** — a mirror that passes the obvious checks and cannot be read out of a memory-mapped view.
@@ -143,7 +189,7 @@ It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReference
The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` gives the Agent a build id of its own and `ShmHandshakeValidator` performs the refuse-to-attach comparison `07_IPC` specifies (§S23-1). **Its default is `NotEvaluated`, not `Ok`** — a result nobody produced has validated nothing, the same rule `AntiCheatVerdict` follows.
**Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. `tools/hook-harness` is a dummy **D3D11 + D3D12 + Vulkan + OpenGL** app used to exercise hooks without a real game — `--vulkan` since #140 and `--opengl` since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (`docs/12_BUILD.md` §Targets is the accurate list).
**Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. ~~`tools/hook-harness`~~ `src/native/tools/hook-harness` (path corrected 2026-10-04) is a dummy **D3D11 + D3D12 + Vulkan + OpenGL** app used to exercise hooks without a real game — `--vulkan` since #140 and `--opengl` since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (`docs/12_BUILD.md` §Targets is the accurate list).
## Definition of done (per PR)
@@ -151,6 +197,8 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
- Hook-path changes state measured overhead in the PR body (`14_TESTING` §Hook overhead).
- Any new hook is listed in `17_HOOK_ENGINE` §Hook inventory and justified against rule 4.
- New user-visible strings exist in `en`, `vi`, `ja`.
- A change to what the App shows keeps `ACCESSIBILITY.md` §For contributors (names, theme colours, nothing by colour alone,
keyboard reach) and updates that page when it moves what works or what does not (D88).
- Any deviation from a doc updates that doc in the same PR.
## Reading order
@@ -158,7 +206,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
@@ -169,8 +220,16 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
8. `docs/18_GPU_VENDOR_APIS.md` — layered GPU telemetry (DXGI/PDH · LHM · NVAPI) + vendor-SDK licence rules
9. `docs/06_DATA_MODEL.md` · `docs/07_IPC.md` · `docs/08_UI.md` · `docs/16_WPFUI_SYNTAX.md`
10. Remaining (`09`–`15`).
11. **`LIMITATIONS.md`** (repository root; shown in the App under Help ▸ Limitations) — what the WHOLE software cannot
do, in the user's words, each item linked to its details. When a change moves a limit, the page changes in the same
PR (D36, 2026-09-27). **`ACCESSIBILITY.md`** (repository root; Help ▸ Accessibility) — the accessibility statement:
WCAG 2.2 AA through WCAG2ICT as a goal, never a claim; what works with the keyboard, a screen reader and contrast
themes, what does not, how a barrier is reported (D88, 2026-11-09); `docs/08_UI.md` §Accessibility holds its checks.
**`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
+14
View File
@@ -0,0 +1,14 @@
# Code of conduct
FrameLedger adopts the **[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)**
(© Contributor Covenant contributors, licensed CC BY 4.0) as its code of conduct, for everyone who takes part in the
project — in issues, pull requests, discussions and any other project space.
In short: be respectful and welcoming, criticise ideas rather than people, and do not harass, insult or demean anyone.
The full text linked above is the code; this summary does not replace it.
## Reporting
Report behaviour that breaks the code to the maintainer at **contact@poli0981.dev**. Reports are read in confidence,
and the maintainer decides on the response in line with the Covenant's enforcement guidelines — from a private note to
a ban from the project's spaces.
+87
View File
@@ -0,0 +1,87 @@
# Contributing to FrameLedger
Thank you for looking. FrameLedger is a small project with strict rules, because it loads code into games and a mistake
can cost a user their account. This page says how to build it, what a change has to bring with it, what will not be
merged, and under what licence your contribution is accepted.
## Before you start
- **Read `CLAUDE.md`'s *Non-negotiable rules* and `docs/19_SAFETY_AND_ANTICHEAT.md` first.** They constrain everything
that touches a game.
- **Open an issue before anything larger than a fix**, so the approach can be agreed before the work is done.
- **A game with anti-cheat that FrameLedger fails to detect** is a safety bug: use the *Safety gap* issue form.
- **A vulnerability in FrameLedger itself** goes the private route in `SECURITY.md`, never a public issue.
- **Something that cannot be reached, read or seen** — with the keyboard, a screen reader, a contrast theme — uses the
*Accessibility problem* form; `ACCESSIBILITY.md` says what the App aims for.
- Everyone who takes part follows the `CODE_OF_CONDUCT.md`.
## Building
You need Windows 10 22H2 or later (x64), Visual Studio 2022 with the C++ workload (MSVC v143), CMake 3.28 or later,
PowerShell 7, and the .NET SDK that `global.json` pins. Then:
```powershell
./build.ps1 check
```
That is the whole quality gate, and continuous integration runs the identical script: the native build and its tests,
`clang-format`, the managed build with warnings as errors, `dotnet format`, every test project, and the repository's own
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
Documentation lives in three places: `guide/` for players (shown in the app and on the wiki), `wiki/` for the wiki's own
pages, and `docs/` for developers. A change a player would notice updates `guide/`; a change to how the code is put
together updates `docs/` — and the `wiki/` page that summarises it, if that page now says something else.
`./build.ps1 check` builds the wiki and fails on a link that leads nowhere.
Never point a build of your own at the data FrameLedger records into (`%LOCALAPPDATA%\FrameLedger`): a newer build
migrates the database, and the released one cannot read it back. To look at real data, copy the folder and start
`FrameLedger.exe --data-dir <copy>` — a viewer that starts no Agent and changes nothing on the PC (`docs/12_BUILD.md`
§Debugging says how to copy it safely).
## What a pull request brings with it
The definition of done is the one in `CLAUDE.md`:
- it builds without warnings (C# and C++), the tests are green, and `dotnet format` and `clang-format` are clean;
- a change to the hook path states its measured overhead in the PR (`docs/14_TESTING.md` §Hook overhead);
- a new hook is listed in `docs/17_HOOK_ENGINE.md` §Hook inventory and justified against rule 4;
- every new user-visible string exists in `en`, `vi` and `ja` (`docs/09_I18N.md`);
- a change to what the App shows keeps `ACCESSIBILITY.md` §For contributors — a name for every control that shows no
text, theme colours only, nothing shown by colour alone, everything reachable by keyboard — and says in the PR what was
checked with the keyboard and Narrator; if it moves what works or what does not, `ACCESSIBILITY.md` changes with it;
- a change that makes a document wrong updates that document in the same PR;
- a change under `src/` adds an entry under `## [Unreleased]` in `CHANGELOG.md`;
- every new source file carries the licence header — `./tools/notice-check.ps1 -Fix` writes it. A file you wrote
yourself may name you in its second line instead, in the same form:
`Copyright (C) <year> <your name> - additional terms under GPLv3 section 7: see NOTICE`.
The pull-request template lists the safety checks for changes to the capture layer, and the accessibility checks for
changes to the user interface.
## What will not be merged
Whatever its other merits, a change that
- adds any way to override, weaken or skip the anti-cheat guard (rule 2);
- makes FrameLedger harder to detect — manual mapping, header erasure, thread hiding, unlinking modules, obfuscation,
renamed binaries (rules 3 and 9);
- reads or writes game memory outside the hooked calls (rule 4), or makes a hook able to crash a game (rule 5);
- adds telemetry, analytics or any network request beyond the ones `legal/PRIVACY_POLICY.md` lists (rule 8);
- turns injection on for a game the user did not individually enable (rule 1).
## Licensing of contributions
FrameLedger is licensed under the GNU GPL, version 3 only, with the additional terms in `NOTICE`. **By opening a pull
request you confirm that you have the right to submit the change, and you license it under GPL-3.0-only, with the
additional terms in `NOTICE` (GPLv3 §7 (b), (c) and (e)) applying to it as they apply to the rest of FrameLedger's own
material.** There is no contributor licence agreement and no copyright assignment: you keep the copyright in your
contribution. Code from elsewhere must come with a licence compatible with GPL-3.0-only and be listed in
`legal/THIRD_PARTY_NOTICES.md`.
Changes written with AI assistance are welcome on the same terms — you are responsible for what you submit, as for any
other change.
## Questions
Open an issue, or write to contact@poli0981.dev.
+54
View File
@@ -67,8 +67,62 @@
<FrameLedgerVersionFile>$(MSBuildThisFileDirectory)VERSION</FrameLedgerVersionFile>
<Version Condition="'$(Version)' == '' And Exists('$(FrameLedgerVersionFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerVersionFile)').Trim())</Version>
<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
<!-- D73 (2026-10-31): the RELEASE LINE, from the RELEASE_LINE file beside VERSION - `main`, the betas and releases on
the .NET that global.json pins, or `alpha`, a beta's source built on a prerelease .NET from the long-lived `alpha`
branch, where this file and global.json are two of the few lines that differ (docs/12_BUILD.md §The alpha line).
Not a property a command line sets: the file is the one source, release.yml refuses a tag that disagrees with it,
and the target below refuses a value that is neither line. Every assembly carries it (the ItemGroup below), and
Shared.BuildLine reads it at run time. -->
<FrameLedgerReleaseLineFile>$(MSBuildThisFileDirectory)RELEASE_LINE</FrameLedgerReleaseLineFile>
<FlReleaseLine Condition="Exists('$(FrameLedgerReleaseLineFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerReleaseLineFile)').Trim())</FlReleaseLine>
</PropertyGroup>
<ItemGroup>
<AssemblyMetadata Include="FrameLedger.ReleaseLine" Value="$(FlReleaseLine)" />
</ItemGroup>
<Target Name="FrameLedgerReleaseLineCheck" BeforeTargets="BeforeBuild" Condition="'$(FlReleaseLine)' != 'main' And '$(FlReleaseLine)' != 'alpha'">
<Error Text="RELEASE_LINE at the repository root must say 'main' or 'alpha', and it says '$(FlReleaseLine)' (docs/12_BUILD.md §The alpha line)" />
</Target>
<!-- The NuGet audit (2026-10-25, docs/13_CI_CD.md §Dependabot and the NuGet audit): every restore checks the WHOLE
package graph, transitive packages included, against the advisory database, at every severity. These are the
SDK's defaults for net10.0, written down so that a later SDK's defaults cannot move them. With
TreatWarningsAsErrors, a vulnerable package is NU1901-NU1904 and the restore - and so the gate - is red, which
is what happened with SQLitePCLRaw 2.1.11 (Directory.Packages.props). -->
<PropertyGroup>
<NuGetAudit>true</NuGetAudit>
<NuGetAuditMode>all</NuGetAuditMode>
<NuGetAuditLevel>low</NuGetAuditLevel>
</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'))">
+45 -27
View File
@@ -3,7 +3,10 @@
<!--
Central package management (docs/12_BUILD.md). Every version is pinned here
and nowhere else, which also makes Dependabot PRs single-file diffs.
All versions verified against nuget.org on 2026-08-02.
All versions verified against nuget.org on 2026-08-02; re-verified and bumped 2026-09-21; bumped again
2026-10-25 (beta.29 PR-2) with the updates Dependabot had never proposed (docs/13_CI_CD.md §Dependabot and
the NuGet audit), and 2026-10-26 (beta.30 PR-3): Velopack and Markdig, the SQLitePCLRaw pin dropped; and again
2026-10-26 (beta.31, the owner's request): the .NET 10.0.14 servicing packages and the updates beta.30 had left.
-->
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
@@ -25,10 +28,17 @@
<PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.2" />
<PackageVersion Include="ScottPlot.WPF" Version="5.1.59" />
<PackageVersion Include="H.NotifyIcon.Wpf" Version="2.4.1" />
<!--
Markdig (Alexandre Mutel): Markdown rendered in the App (beta.12, owner request 4) - the Legal Gate, Help,
About and the user guide show their documents rendered, not as raw text. BSD-2-Clause, no dependency on
net10.0. The package ships no licence file, so its text is a reviewed override
(tools/license-overrides/Markdig.txt). HTML is disabled in the pipeline (App/Markdown/MarkdownRenderer.cs).
-->
<PackageVersion Include="Markdig" Version="1.5.0" />
</ItemGroup>
<ItemGroup Label="Hosting and logging">
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.10" />
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.14" />
<PackageVersion Include="Serilog" Version="4.4.0" />
<PackageVersion Include="Serilog.Extensions.Hosting" Version="10.0.0" />
<PackageVersion Include="Serilog.Sinks.Console" Version="6.1.1" />
@@ -37,46 +47,48 @@
<ItemGroup Label="Storage">
<!-- No EF: Dapper over Microsoft.Data.Sqlite (CLAUDE.md pinned stack). -->
<PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.10" />
<PackageVersion Include="Dapper" Version="2.1.79" />
<PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.14" />
<PackageVersion Include="Dapper" Version="2.1.89" />
<!--
Transitive pin, not a direct dependency.
Microsoft.Data.Sqlite 10.0.10 resolves SQLitePCLRaw.lib.e_sqlite3 2.1.11,
which carries GHSA-2m69-gcr7-jv3q (high severity, vulnerable range
<= 2.1.11) via its bundled SQLite. With TreatWarningsAsErrors that is
NU1903 and the build fails — correctly. Pinning the bundle forward to the
3.x line pulls a patched native library.
CentralPackageTransitivePinningEnabled is what makes this work from here.
Revisit when Microsoft.Data.Sqlite ships a build that resolves a patched
version on its own, and drop this pin rather than carrying it forever.
No transitive pin on SQLitePCLRaw since beta.30 (2026-10-26). From the scaffold (2026-08-02) to beta.29 this held
SQLitePCLRaw.bundle_e_sqlite3 at 3.0.5: Microsoft.Data.Sqlite 10.0.10 resolved SQLitePCLRaw.lib.e_sqlite3 2.1.11,
which carries GHSA-2m69-gcr7-jv3q (vulnerable range <= 2.1.11) through its bundled SQLite, NU1903 under
TreatWarningsAsErrors. Its own comment said to drop it once Microsoft.Data.Sqlite resolved a patched version on
its own; 10.0.13 declares SQLitePCLRaw 2.1.13, and the pin had become a conflict NuGet does not report - it put a
package built against the 2.x line on SQLitePCLRaw's 3.x line. The NuGet audit (Directory.Build.props) still
turns a vulnerable SQLite red (docs/13_CI_CD.md §Dependabot and the NuGet audit).
-->
<PackageVersion Include="SQLitePCLRaw.bundle_e_sqlite3" Version="3.0.5" />
</ItemGroup>
<ItemGroup Label="Interop, telemetry and packaging">
<PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.298" />
<PackageVersion Include="Velopack" Version="1.2.0" />
<PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.367" />
<PackageVersion Include="Velopack" Version="1.2.161" />
<!-- MPL-2.0. docs/18_GPU_VENDOR_APIS.md §L2 requires >= 0.9.6, and
legal/THIRD_PARTY_NOTICES.md has a release-gate check that no
depended-upon file carries MPL-2.0 Exhibit B. Consume UNMODIFIED. -->
<PackageVersion Include="LibreHardwareMonitorLib" Version="0.9.6" />
<!-- The crash witness (04_CAPTURE §Crash & exit classification): Application log events 1000/1001. In-box
for WPF apps, a package for a class library on the Windows TFM. Microsoft, MIT. -->
<PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.10" />
<PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.14" />
</ItemGroup>
<ItemGroup Label="Analyzers (build-time only)">
<PackageVersion Include="Roslynator.Analyzers" Version="4.16.1" />
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.257" />
<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.319" />
<PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="18.12.1" />
</ItemGroup>
<ItemGroup Label="Testing">
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
<PackageVersion Include="xunit.v3" Version="3.2.2" />
<PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.11.0" />
<!--
xUnit.net v3, 4.x line (2026-09-21). 4.0 made Microsoft Testing Platform v2 the default of the plain
`xunit.v3` package and dropped MTP v1. build.ps1's gates are VSTest-shaped on purpose - the
`XPlat Code Coverage` collector, `results.trx` read by the struct-mirror gate and by Invoke-TestsWithin -
so the projects reference the SAME 4.x framework through its `mtp-off` variant, the one xunit publishes
for exactly this. Moving to MTP v2 is a build.ps1 change, not a version bump; do them together or not at all.
-->
<PackageVersion Include="xunit.v3.mtp-off" Version="4.0.2" />
<PackageVersion Include="xunit.runner.visualstudio" Version="4.0.1" />
<!--
FluentAssertions is pinned to the 7.x line ON PURPOSE, and must not be
bumped to 8.x without redoing the licence analysis.
@@ -94,8 +106,14 @@
Reviewed 2026-08-02. See docs/20_OPEN_QUESTIONS.md §G.
-->
<PackageVersion Include="FluentAssertions" Version="[7.2.2]" />
<PackageVersion Include="NSubstitute" Version="6.0.0" />
<PackageVersion Include="coverlet.collector" Version="10.0.1" />
<PackageVersion Include="NSubstitute" Version="6.2.0" />
<!--
10.1.0 not taken on 2026-10-25: the tracker it injects into each instrumented assembly declares a constant,
ModuleTrackerRegistryKey, whose value reflection cannot read ("Literal value was not found"), and
NoSecondMatcherTests reads every string constant in Application, Domain and Infrastructure. Taken in beta.31
(2026-10-26): that test now leaves out the types coverlet adds (namespace Coverlet.*), which are not ours.
-->
<PackageVersion Include="coverlet.collector" Version="10.1.0" />
</ItemGroup>
</Project>
+94
View File
@@ -0,0 +1,94 @@
# Forking and redistributing FrameLedger
This page is for anyone who clones or forks FrameLedger — and above all for anyone who **gives builds of a modified
FrameLedger to other people**. It says what the licence lets you do, what it asks of you when you distribute, and the
practical things a fork has to change so that its users and FrameLedger's users do not get each other's updates, data
or blame. It is written to be useful, not as legal advice; the texts that decide are `LICENSE` (the GNU GPL, version 3)
and `NOTICE`.
## What the licence lets you do
FrameLedger is free software under the **GNU General Public License, version 3 only** (`GPL-3.0-only`). You may run it
for any purpose, study and change its source, and share copies — changed or not — free of charge or for a fee. You do
not need anyone's permission, and you do not have to accept the licence just to run the program (GPLv3 §9).
## What it asks when you distribute a build
"Distribute" here is the GPL's *convey*: giving a copy to someone else, including publishing an installer. Running
FrameLedger yourself, or changing it for yourself, asks nothing of you.
- **The source goes with the build.** Whoever receives your binaries must be able to get the complete source code
that builds them, under the same licence (GPLv3 §6) — the C++ and C# sources, the build scripts (`build.ps1`,
`src/native/CMakeLists.txt`, the workflows) and everything else needed to rebuild them. Publishing the exact source
tree at the tag you built from, next to the release, is the simplest way. An installer such as the Velopack
`Setup.exe` counts as a binary.
- **Keep the notices.** Ship `LICENSE`, `NOTICE` and the third-party licences with every copy. The release workflow
already does this: the App's publish step copies them into `licenses\` beside the executables (`licenses\NOTICE.txt`,
`licenses\FrameLedger-GPL-3.0.txt`, `licenses\THIRD_PARTY_NOTICES.md`, `licenses\nuget\`), and
`.github/workflows/release.yml` refuses a published tree without them. Do not remove the copyright and licence
headers from the source files.
- **Say that it is changed.** A modified version must carry prominent notices that you modified it, and when
(GPLv3 §5(a)).
- **Add no restrictions.** You may not impose terms that take away the rights the GPL gives your users (GPLv3 §10) —
an end-user agreement that forbids what the GPL permits is not allowed. FrameLedger's own EULA says that nothing in
it limits those rights.
### The additional terms in `NOTICE`
FrameLedger's own material is licensed with three additional terms of the kinds GPLv3 §7 permits. In short:
- **(b)** keep the copyright line and the attribution *"Based on FrameLedger by poli0981 —
https://github.com/poli0981/frameledger"* in your build's Appropriate Legal Notices (FrameLedger shows them under
Help ▸ About);
- **(c)** do not name a modified version "FrameLedger" alone, say in its notices and documentation that it is modified
and by whom, and do not present its builds, installers or update feed as the original project's;
- **(e)** no rights are granted in the name "FrameLedger" or the project's logo and icon, beyond saying truthfully
where your work comes from ("based on FrameLedger", "a fork of FrameLedger").
`NOTICE` has the exact wording. These terms cover material written by FrameLedger's developer; how far they reach
depends on the copyright in that material — parts of FrameLedger were written with AI assistance under the developer's
direction. If the difference matters to you, ask a lawyer, not this page.
## What a fork that ships builds has to change
FrameLedger installs into the user's profile, keeps one database there, runs a background agent and registers a few
system-wide names. A fork that keeps them **collides with an installed FrameLedger**: the two would update each other,
share — and migrate — one database, and fight over the same pipe and shared memory. Change all of these together:
| What | Where | Why |
|---|---|---|
| Product name, icon, title | the App's resources, `--packTitle` in `release.yml`, `Strings.resx` | NOTICE (c) and (e) |
| Update feed | `VelopackUpdateClient.RepositoryUrl` (`src/FrameLedger.App/Update/VelopackUpdateClient.cs`) | otherwise your users are offered FrameLedger's releases, and FrameLedger's users yours |
| Install folder | `--packId` in `release.yml` (today `FrameLedger.App`) | Velopack installs into `%LOCALAPPDATA%\<packId>` and **deletes that folder on uninstall** — never choose a packId that equals any data folder |
| Data folder | `LedgerPaths` (`src/FrameLedger.Infrastructure/Persistence/LedgerPaths.cs`) and the other `%LOCALAPPDATA%\FrameLedger` paths (`DetectionRulesFile`, `VkLayerLaunchEnvironment`, the Overlay's log folder, and the guard's own `fl::guard::RulesFilePath` in `src/native/FrameLedger.Injector/src/fl_ac_rules.cpp`) | a newer schema migrates the database in place and an older build cannot open it again |
| Agent pipe | `IpcProtocol.PipeName` (`src/FrameLedger.Shared/Ipc/IpcProtocol.cs`) | the App talks to whichever agent owns the pipe |
| Shared memory and mutex names | `Local\FrameLedger.*` (the ring, the tolerance channel, `SingleInstance`, the agent's instance lock) — in C# and in `src/native` | two programs must not open each other's ring |
| Vulkan layer | `VK_LAYER_FRAMELEDGER_overlay`, its `HKCU\SOFTWARE\Khronos\Vulkan\ImplicitLayers` registration, and its `FRAMELEDGER_ENABLE_VK_LAYER` / `DISABLE_FRAMELEDGER_VK_LAYER` variables (the manifest template in `src/native/FrameLedger.VkLayer/` and `VkLayerLaunchEnvironment`) | one implicit layer per name — and a fork that keeps the variables is switched on by every FrameLedger launch |
| Start with Windows | `RunAtLogon.DefaultValueName` (`src/FrameLedger.Infrastructure/Startup/RunAtLogon.cs`) | one `HKCU\…\Run` value per name |
| Logon task | `LogonTask` (the Agent's maintenance verbs) | one task per name |
| Issue and help links | `IssueLink.Repository` (`src/FrameLedger.App/Services/IssueLink.cs`) — `RepositoryLinks` builds every document link in the App from it and the source ref `release.yml` passes — plus the Releases link in `guide/01-install.md` and `.github/ISSUE_TEMPLATE/` | your users' reports belong in your tracker |
| Who the documents name | `legal/EULA.md`, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md` name poli0981 as the Developer, with a contact | the person who distributes a build is the one its users deal with; review every claim they make, too — they describe FrameLedger's builds, not yours |
| Version information | `FL_COMPANY_NAME` / `FL_PRODUCT_NAME` / `FL_COPYRIGHT` in `src/native/CMakeLists.txt`; `Company` / `Product` / `Authors` / `Copyright` / `Description` / `RepositoryUrl` in `Directory.Build.props` and the `AssemblyTitle` / `Description` of the App's and the Agent's csproj (since beta.14); and the names `tools/versioninfo-check.ps1` and the two `AssemblyIdentityTests` require | anti-cheat vendors and users identify the DLLs loaded into games and the processes beside them by it (`docs/19_SAFETY_AND_ANTICHEAT.md`); it must name your project, and the copyright line must be one line on every binary — the check compares them |
| Checksums | your own `SHA256SUMS.txt` | users verify what *you* built |
The detection rules and the anti-cheat blocklist (`rules/detection-rules.json`) ship with each build; keeping them
current for your users becomes your job.
## What we ask, and cannot require
The GPL does not allow adding restrictions, so the following is a request, not a condition. FrameLedger is built
around a few rules (`CLAUDE.md`, *Non-negotiable rules*), and the reason is the people who use it:
- the anti-cheat guard is a hard gate with no override switch;
- injection is opt-in, per game, and never automatic;
- nothing is hidden from security software — no manual mapping, no header erasure, no renamed or obfuscated binaries;
- the game's memory is never read or written outside the hooked calls;
- no telemetry and no silent network requests.
A build that drops any of these can get its users' accounts banned. It is not FrameLedger, must not say it is
(NOTICE (c)), and the original developer is not responsible for it.
## See also
`NOTICE` · `LICENSE` · `CONTRIBUTING.md` (if you would rather send your change upstream) ·
`legal/TRADEMARKS.md` · `legal/THIRD_PARTY_NOTICES.md` · `docs/12_BUILD.md` (building from source)
+2
View File
@@ -49,6 +49,8 @@
-->
<ItemGroup Condition="'$(IsTestProject)' == 'true'">
<Compile Include="$(MSBuildThisFileDirectory)tests\Shared\HarnessOverlayLogSweep.cs" Link="Shared\HarnessOverlayLogSweep.cs" />
<!-- When a started harness is really up (beta.27): the injection tests wait for its own "presenting" line. -->
<Compile Include="$(MSBuildThisFileDirectory)tests\Shared\HarnessReady.cs" Link="Shared\HarnessReady.cs" />
</ItemGroup>
<!--
+34
View File
@@ -0,0 +1,34 @@
<Project>
<!--
Ships FrameLedger.ProcessStats.dll beside the importing project's output (beta.12, owner decision D43).
The third P/Invoke facade after the guard's and the NVAPI bridge's (docs/18_GPU_VENDOR_APIS.md §L1, the game
process's memory): NativeProcessStats loads it BY ABSOLUTE PATH from AppContext.BaseDirectory and never falls back
to a search, so it has to actually be there. Read-only, and NEVER loaded into a game — the Agent (and the unshipped
capture host) load it into their own process for the 1 Hz read of a game's dedicated/shared GPU memory (the
GPU Process Memory counters) and its working sets (GetProcessMemoryInfo).
Imported by the same three projects as the bridge: FrameLedger.Agent, FrameLedger.CaptureHost and
FrameLedger.Infrastructure.Tests (the mirror test and the real read P/Invoke into the real DLL).
Warn rather than fail when absent, as the bridge does: an absent reader is a missing measurement (every game-memory
field reads N/A), not a safety hole.
-->
<PropertyGroup>
<FlProcessStatsOutDir>$(MSBuildThisFileDirectory)build\native\x64-release\FrameLedger.ProcessStats\</FlProcessStatsOutDir>
</PropertyGroup>
<ItemGroup>
<None Include="$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll" Condition="Exists('$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll')">
<Link>FrameLedger.ProcessStats.dll</Link>
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
</ItemGroup>
<Target Name="FlWarnOnMissingProcessStats" AfterTargets="Build"
Condition="!Exists('$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll')">
<Warning Text="FrameLedger.ProcessStats.dll was not found at $(FlProcessStatsOutDir). Run build.ps1 native first; the game's memory will read N/A." />
</Target>
</Project>
+296
View File
@@ -0,0 +1,296 @@
# What FrameLedger cannot do
FrameLedger measures a game by loading a small component into it — only for a game you added and switched
hooking on for — and reading the graphics calls the game makes. That is why it can tell the real render
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.35.*
## Games it will not measure
- **Games with anti-cheat.** FrameLedger looks for anti-cheat before it touches a game and refuses when it
finds one — there is no switch that overrides this. The one exception is an anti-cheat that runs entirely
inside the game (no driver, no service), which you can allow per game after a warning; its first two
sessions are a trial, and one that does not go well ends the exception for good. A ban is still possible and
may come days later. Kernel anti-cheat is never allowed.
([Safety](docs/19_SAFETY_AND_ANTICHEAT.md))
- **Anti-cheat FrameLedger does not know about.** The list of anti-cheat products is FrameLedger's own and
can be incomplete. A game protected by something unknown may be hooked; that is a risk to your account
that you take by switching hooking on.
- **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 — **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.
- **Vulkan games that run as administrator.** Windows' Vulkan loader does not load FrameLedger's Vulkan
layer into an elevated game, so admin mode does not help there.
- **A game that was already running when FrameLedger was updated** — restart the game once.
- **Games you did not switch hooking on for.** Adding a game only records its sessions; measuring it is a
separate, per-game choice with its own warning.
## What an unmeasured session contains
When a game is not measured — any of the reasons above — its session still records **how long it ran, the
machine's sensors (GPU temperature, load, power; CPU load; memory), how much memory the game itself used (read from
Windows, outside the game) and why nothing was measured.** Every
frame-rate, upscaler, frame-generation and ray-tracing value reads **N/A**, never 0. How the game's window was
shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
## When a game crashed
- A session reads **crashed** when the game ended with an exception's code, when Windows logged a crash report of it,
or — since 0.1.0-beta.14 — when it started its engine's crash reporter (Unreal's, CD PROJEKT RED's, Capcom's,
BugSplat's) and exited within a minute. A game that handles its own crash quietly, starts no reporter and leaves no
crash report reads **ended normally**, with its exit code.
- A crash reporter is seen from a once-a-second look at running programs: one that opens and closes faster can be
missed, and one started in the game's first 10 seconds is not counted (it could be a monitor that starts with the
game). Unity's crash handler and Chromium's `crashpad_handler` start with every game that has them, so their presence
says nothing. Sessions recorded before 0.1.0-beta.14 keep how they were stored — a few of them may read *crashed*
because Windows logged a memory report about the game. ([details](docs/04_CAPTURE.md))
## Frame rate and frame generation
- **One inflated number is never shown.** When frame generation is measured, the page shows the game's own
frames and the displayed frames together (`62 → 118 FPS (×1.9 FG)`). When it cannot be measured, the page
shows **Presented FPS** with a sentence saying whether generated frames could be included.
- **Frame generation done by the driver outside the game** (AMD Fluid Motion Frames, NVIDIA Smooth Motion)
is not visible to FrameLedger; the rates shown are what the game presented.
- Frame generation is counted on **Direct3D games** only. DLSS Frame Generation and FSR frame generation are
named from the calls the game makes; any other generator is shown only as *active*, never named, and where
the generated frames cannot be counted the page shows Presented FPS with a note instead of a factor.
- **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*: a window in which the multiplier stepped reads between two whole multipliers and, since
0.1.0-beta.27, is never a state of its own. A state shorter than 10 seconds is not listed. A stretch the game
presents with almost no frame
count of its own — shaders compiling at start, a loading screen, a menu drawn outside frame generation — reads as
*Not classified* too. 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 has been checked against the App on one 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 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. For FSR through AMD's FidelityFX libraries (since 0.1.0-beta.25) that is the
mode whose render size the game asked AMD's library for and then rendered at — checked on a test program, not yet
on a real game; a game at a dynamic resolution, one that sizes its frames without asking, and a game FrameLedger
joined after it asked show none. For DLSS it is the options a Streamline game passes, 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). Sessions recorded before 0.1.0-beta.27 kept
the NVIDIA driver's answer from after the game had closed, which never says DLSS ran: on a game no hook names, they
show neither the driver's report nor the NVIDIA App's mode. ([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), the NVIDIA App's *Dynamic* frame generation that the driver reports applied (DLSS 4.5, whatever multiplier
it chose — since 0.1.0-beta.34), or a library whose major version names one (2.x, 3.x). A *Fixed* ×5 or ×6 set in
the App names DLSS 4.5 only when the frames show it. A 310 library with no such evidence shows its
version only. **DLSS 5**
(since 0.1.0-beta.34) is named where the game was seen running its neural rendering through Streamline, with the share
of rendered frames; its library loaded and nothing seen reads *runtime loaded* — *not seen running* only where the
Overlay looked. A game that runs neural rendering outside Streamline is not seen. 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.
- HDR output, NVIDIA Reflex latency, the video-memory budget Windows gives a game, and shader-compilation
stutter are **not measured yet** — they read N/A. ([Accuracy](legal/ACCURACY.md))
## The game's memory
- **What is shown is what Task Manager's Details tab shows** for the game's process — *Dedicated GPU memory*,
*Shared GPU memory* and *Memory* (the private working set) — read from Windows once a second, from outside
the game. FrameLedger never looks inside the game's memory to get it.
- **One process.** A measured game is its own process; for a game that is not measured, every process running
the game's executable is added together. Launchers, crash reporters and other helper programs are not counted.
- **The private working set needs a recent Windows**: Windows 10 22H2 or Windows 11 with the September 2023
update or later. Without it the working set is shown instead, labelled as such.
- A game that has not created anything on the graphics card yet (its first second, a launcher screen) reads
N/A for video memory. AMD and Intel graphics cards have not been tested.
([Metrics](docs/03_METRICS.md))
## Display mode (full-screen, borderless, windowed)
- **Exclusive full-screen is known only for a measured Direct3D (DXGI) game** — the game's own swap chain
says so. For OpenGL, Vulkan and unmeasured games, a window covering the screen reads *Fullscreen or
borderless*, never either one.
- **What Windows does behind the game is not visible:** a game in exclusive full-screen may still be shown
through Windows' compositor ("fullscreen optimizations"), and a game's menu may call a borderless window
"Fullscreen". FrameLedger reports what the game asked for.
- The mode is sampled ten times a second in a measured session and once a second in an unmeasured one; very
short switches can be missed. A session recovered after a crash, and every session recorded before
beta.10, read N/A. Some sessions recorded before 0.1.0-beta.27 of a game in exclusive full-screen show no window or
monitor size: the game's last moments, after its window had closed, replaced them.
([Display mode](docs/03_METRICS.md#display-mode--both-tiers-beta10))
## Engine version
- 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.**
- Since beta.19 also **Unity**, **Godot** and **RPG Maker** (MV, MZ, XP, VX, VX Ace): from the engine's own files —
Unity's player library or data file, Godot's data pack, RPG Maker's core script or the runtime library its `Game.ini`
names. A Unity game whose data file is encrypted shows the version without its release letter (`2019.4.40`, not
`2019.4.40f1`); an XP, VX or VX Ace game shows its runtime library's number, which is not the editor's.
**RPG Maker 2000 and 2003 are not recognised.**
- Since beta.20 also **Ren'Py**: from the engine's own version file (`renpy/vc_version.py`); a Ren'Py game whose engine
names no version there shows none. Other engines show a version only where their files state one.
([Detection](docs/05_DETECTION.md))
## Sensors
- GPU temperature, load, power and memory are best supported on **NVIDIA** GPUs. **AMD and Intel GPUs have
not been tested** on real hardware yet.
- **On a PC with more than one graphics card**, the GPU figures follow the card the game draws on once a Direct3D game
has shown its first frame; before that, in an unmeasured session, and for OpenGL or Vulkan games they describe the
first card Windows lists, and with two cards of one brand the temperature and load come from that brand's first card.
The session's hardware details always name the first card. None of this has been tested on a machine with two cards.
([Telemetry](docs/18_GPU_VENDOR_APIS.md))
- **CPU temperature** needs *Run the agent as administrator* and the separately installed PawnIO driver, and
has not been verified on real hardware yet. CPU load is the time the processor was busy — not Task
Manager's "utility" figure, which can exceed 100%. ([Telemetry](docs/18_GPU_VENDOR_APIS.md))
- **Whether the graphics card was held back by its power limit or by heat** (since 0.1.0-beta.14) is known only on
NVIDIA cards, and only as it was at each once-a-second reading. On other cards it reads N/A.
- **Frames per watt** (since 0.1.0-beta.14) counts the game's own frames — never generated ones — against the graphics
card's power alone, not the processor's or the whole PC's. It reads N/A where the game's own frame rate is not known.
([Metrics](docs/03_METRICS.md))
## Running the agent as administrator
Off by default. When on, **Windows asks every time the agent starts** and names an unknown publisher, because
FrameLedger is not signed. It lets FrameLedger open games that run as administrator and read the CPU
temperature; it does not bypass anti-cheat, does not open protected processes, and does not make games you
start from FrameLedger run as administrator. **The risk:** FrameLedger is installed in your user folder, so a
program running under your account could replace its files and would then run as administrator the next time
you accept the prompt. Turn it on only if you trust everything that runs under your account.
([Architecture, ADR-9](docs/01_ARCHITECTURE.md))
## Platform and what has been tested
- **Windows 10 22H2 or Windows 11, 64-bit only.**
- 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.
- **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)).
## Accessibility
What works with the keyboard alone, a screen reader, a contrast theme or Magnifier, what does not yet, and how to report
a barrier is on its own page: [Accessibility](ACCESSIBILITY.md) (in the app: Help ▸ Accessibility). The largest limits:
- **A chart's points cannot be read one by one.** A screen reader hears its name and where its numbers are written —
the session's figures, the tables, **File ▸ Export**; its keys move it.
- **Windows' text size setting is not followed** — use display scaling or Magnifier.
## 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.
- **Some games will not start directly** (seen on two Steam games, 2026-10-19 and 20). Lies of P, started by *Start
directly*, hands itself to Steam within seconds — since 0.1.0-beta.27 the game Steam then starts is recorded —, and
Clair Obscur: Expedition 33 closes within seconds, with or without FrameLedger's hook. Each such start ends a
measured session early, which the crash safety counts: two turn hooking off for the game. Start such a game through
its store (Settings ▸ Games ▸ *Play button*); the notice after Play says when a Steam game may hand itself to Steam.
([details](docs/spike-notes/23-owner-runs-2026-10-20.md))
## Xbox app and Microsoft Store games
- **Only games built on Microsoft's GDK** (since 0.1.0-beta.33) — what the Xbox app and the Microsoft Store install into
a games folder you chose, PC Game Pass games included — are found by **Import library**. An older Store app (UWP) is
not listed, and a game Windows has not installed for you, such as one left behind on a drive, is not offered.
([details](docs/spike-notes/25-xbox-gdk.md))
- **Their executables cannot be read by other programs** — Windows refuses it to anything outside the game's own
package — so FrameLedger shows no Unreal Engine version and no *Runs as* for them, and says what it could not read
rather than guessing. A Unity game's version still reads, from its player library.
- **The anti-cheat list's per-game entries know Steam ids only.** An Xbox copy of a game listed there by its Steam id is
checked like any other game — its files, its executables, the anti-cheat drivers and services on your PC — but not
by that entry. ([Safety](docs/19_SAFETY_AND_ANTICHEAT.md), [open question](docs/20_OPEN_QUESTIONS.md))
- **Play starts them through Windows, in either Play mode** — as their Start-menu tile does — because Windows starts
such a game only through its package: *Start directly* cannot start one, so it is recorded once it appears, a few
seconds after its start, and the first frames before then are not measured. ([Play](docs/08_UI.md),
[capture](docs/04_CAPTURE.md))
- **An older Store app (UWP), and a game Windows runs under code protection the hook cannot live under** — only
Microsoft-signed code, no generated code, strict stack or control-flow protection — **is never hooked**: its session
keeps its duration, your PC's sensors and the reason. Measuring a game from the Xbox app with the Vulkan graphics API
has not been tried. ([Safety](docs/19_SAFETY_AND_ANTICHEAT.md), [open question](docs/20_OPEN_QUESTIONS.md))
## Game artwork
- **Only the Steam and GOG GALAXY apps keep pictures FrameLedger can show** (since 0.1.0-beta.23) — **and, since
0.1.0-beta.33, an Xbox game ships its own**: its square logo and its splash image, shown from its own folder. 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
- Everything stays on your computer (`%LOCALAPPDATA%\FrameLedger`). FrameLedger sends no telemetry; its only
network requests are the update check and the update download, both to GitHub, and the check can be switched
off. The anti-cheat list and the detection rules ship with each version — **a newer list reaches you only with
the next update.** ([Privacy policy](legal/PRIVACY_POLICY.md))
- Per-frame data is kept for the **last 20 sessions of each game** (configurable); older sessions keep their
summaries.
- A newer version upgrades the database in place, and an **older version cannot open it again** — there is
no downgrade.
## Installation
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.
## Alpha builds
*Only for an alpha — a version ending in `-alpha.N`, an experimental build on a new .NET
([Alpha builds](guide/11-alpha-builds.md)).*
- **It runs on a .NET that Microsoft has not finished** — .NET 11's release candidate first — and has not been tested
the way a beta is: everything on this page applies to it, and so can problems no beta has shown
([Alpha notice](legal/ALPHA_NOTICE.md)).
- **Windows 10 22H2 Home and Pro are not supported** by Microsoft for .NET 11; an alpha may run there, but nobody
supports it. It does not start at all on a processor without SSE4.2 and POPCNT.
- **A failure in the capture agent's own background work ends the agent with a crash report** on an alpha, where a
beta's agent stops and exits quietly: .NET 11 reports it that way.
- **It shares the beta's data folder.** It copies the database into `backups` before it first opens it, and does not
open it if the copy cannot be made; the newest three copies are kept and older ones it made are deleted.
- **It updates only to newer alphas**, and its update channel is locked; going back to the beta means installing the
beta over it.
+45
View File
@@ -0,0 +1,45 @@
FrameLedger
Copyright (C) 2026 poli0981 <contact@poli0981.dev>
FrameLedger is free software: you can redistribute it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation, version 3 of the
License only (GPL-3.0-only).
FrameLedger is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details. Its full text is in the file LICENSE
and at <https://www.gnu.org/licenses/gpl-3.0.html>.
ADDITIONAL TERMS UNDER SECTION 7 OF THE GNU GENERAL PUBLIC LICENSE, VERSION 3
These terms apply to the material in this repository authored by poli0981. They do not
apply to third-party components, which keep their own licences (legal/THIRD_PARTY_NOTICES.md).
Every first-party source file points here with the line
"Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE".
(b) Preservation of notices. You must preserve this notice, the copyright line above, and
the attribution "Based on FrameLedger by poli0981 - https://github.com/poli0981/frameledger"
in the Appropriate Legal Notices displayed by any work that contains this material
(in FrameLedger itself: Help > About).
(c) Marking of modified versions. A modified version you convey must be marked in
reasonable ways as different from the original version: it must not be named
"FrameLedger" alone, it must say in its Appropriate Legal Notices and in its
documentation that it is modified and by whom, and it must not present its builds,
installers or update feed as those of the original project.
(e) Trademarks. These terms grant no rights under trademark law to use the name
"FrameLedger", or the project's logo and icon, beyond describing the origin of a work
truthfully (for example "based on FrameLedger").
Section 7 of the GPL permits additional terms of the kinds its paragraphs (a) to (f) list;
the three above are of the kinds named in paragraphs (b), (c) and (e).
SEE ALSO
FORKING.md what a redistributor of a modified version is asked to change
legal/TRADEMARKS.md third-party names and marks
legal/THIRD_PARTY_NOTICES.md the third-party components and their licences
LICENSE the GNU General Public License, version 3
+122 -48
View File
@@ -4,30 +4,50 @@
> No telemetry. No accounts. All data stays on your machine.
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
anti-cheat, and look after your data, a page each, then every screen, every setting and what to do when something goes
wrong. What FrameLedger cannot do is on one page: [Limitations](LIMITATIONS.md). How it works with the keyboard alone, a
screen reader or a contrast theme, and how to report a barrier: [Accessibility](ACCESSIBILITY.md). All three are in the
app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and on the project's
[wiki](https://github.com/poli0981/frameledger/wiki) with the developer pages.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-15.** The software is pre-alpha and
> **unreleased**: no tagged build or installer has been published. The source holds the desktop app
> ⚠ **What FrameLedger actually measures today — 2026-11-06.** The software is a beta; its latest
> **beta is `0.1.0-beta.35`** (2026-11-09), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds on a prerelease .NET — are published apart). 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, injects only into games you enabled and only past the safety guard, and
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> and only past the safety guard, and
> stores sessions in a local database. What that path measures:
>
> - **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
> NVIDIA Streamline (with Ray Reconstruction Yes/No), and FSR through AMD's shipped FidelityFX DLLs:
> named FSR 3 from the older DLLs, and FSR without a version from the newer ones, which host both
> FSR 3.1 and FSR 4. FSR 2, and FSR shipped any other way, is not identified. For DLSS titles that
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session, labelled
> *driver-reported*; the app does not display it yet. Intel XeSS is **not** read (its SDK licence
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session and shown
> as *DLSS (driver-reported)*. The NVIDIA driver's profile for the game — the DLSS and frame-generation
> overrides the NVIDIA App sets — is read, never changed, and shown as the driver's settings beside what
> 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), or, for FSR through
> AMD's FidelityFX libraries, the mode whose render size the game asked for and then rendered at. In
> every other case — FSR at a dynamic resolution among them — 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,
> a measured multi-frame factor, or the NVIDIA App's Dynamic frame generation that the driver reports applied);
> "DLSS 5" only when the game was seen running its neural rendering, otherwise "runtime loaded" when its library was
> 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
@@ -35,22 +55,65 @@
> - **Frame generation (Direct3D titles only):** the Displayed rate is counted from presents, plus the
> presents DXGI's own counter saw on the same swap chain that the hook did not; the Native rate from
> the vendor's own per-frame calls (NVIDIA Streamline, AMD FidelityFX) where the title makes them, and
> `N/A` where it does not. 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.
> `N/A` where it does not. When frame generation did not stay in one state for the whole session
> (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. 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
> minimised — as a share of the session, with the window's size and the monitor's, in every session.
> Exclusive full-screen is known only for Direct3D titles FrameLedger injects into, from the game's own
> 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. Since beta.19 also Unity's (from its
> player library or its data file — without the release letter where only the library's number is readable),
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
> once a second from Windows' own counters, from outside the game, in every session: a game
> FrameLedger injects into through the handle it already holds, any other by opening it briefly with
> the least access Windows offers (and adding up every process running its executable). Shown with
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), HDR, and CPU temperature. Stutter count and
> stutter time are measured from frame times.
> 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
> administrator — an option, off by default, for which Windows asks at every start of the Agent — with
> PawnIO installed, and that reading has not yet been checked on real hardware; everywhere else it is `N/A`.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
> goes passthrough. A global switch in Settings turns all hooking off, and a running capture stops at
> its next check; it can only refuse, never permit. There is no override anywhere.
> its next check; it can only refuse, never permit. **There is no override.** A finding about a game — anti-cheat
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder. Its first two sessions are a trial, and one that does not go well ends it
> for good. The guard still runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
@@ -69,11 +132,11 @@ Most tools tell you your frame rate. FrameLedger tells you **what produced that
- **Which upscaler is running** — DLSS / FSR, read from the API the game calls, not guessed from files on disk. Intel XeSS is not read: its SDK licence forbids it.
- **Frame Generation, measured** — native and generated frames counted separately. Shown as `62 → 118 FPS (×1.9 FG)` when both are counted, and as a qualified Presented FPS when they are not — never as one inflated number.
- **Ray tracing, actually detected** — including inline ray tracing (DXR 1.1 `RayQuery`), which frame-counting tools miss entirely.
- **Per-process VRAM** and whether the driver was exceeding its budget (a real stutter explanation).
- **The game's own VRAM and RAM** — Task Manager's figures for the game's process, read from outside the game in every session, with mean, median and peak (since beta.12). ~~and whether the driver was exceeding its budget~~ — the video-memory budget is not measured yet.
- **Shader-compilation stutter attribution** — which frame spikes were pipeline compiles.
- **PC latency** when the game uses Reflex.
Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distributions, stutter metrics, CPU/GPU temperatures, session history, cross-session comparison, and Steam/GOG/Epic/itch.io library import. UI in **English / Tiếng Việt / 日本語**.
Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distributions, stutter metrics, CPU/GPU temperatures, session history, cross-session comparison, and Steam/GOG/Epic/itch.io/Xbox library import. UI in **English / Tiếng Việt / 日本語**.
## How it works — and the trade-off, stated plainly
@@ -86,7 +149,7 @@ FrameLedger is built to keep that risk small and to be honest about it:
| Safeguard | |
|---|---|
| **Off by default** | Injection is disabled for every game until you enable it individually, after a consent prompt |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>**One narrow exception since beta.9 (owner decisions D33, D38):** per game, after its own disclosure and only while a Settings option (off by default) is on, a game whose only finding is one anti-cheat that runs entirely in user mode — no driver file in its folder, on no title list — may be hooked under a user-mode exception. ~~and that FrameLedger has measured successfully at least twice~~ *(corrected 2026-10-03: since beta.11, D38, a grant needs no earlier session; its first two hooked sessions are a trial, and one that does not go well ends it for good.)* The guard still runs every check under it, refuses anything else it finds, and ends it on anything new; a ban remains possible (`legal/DISCLAIMER.md` §2A).<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **No evasion, ever** | FrameLedger does not hide, rename, obfuscate, or disguise itself. It keeps its real name, real exports, and version info. It is meant to be plainly visible to any security software that looks. This is an architectural rule, not a setting |
| **Read-only** | It never reads or writes game memory, never modifies game behavior, never touches saves or input, and never changes GPU clocks, fans, or power limits |
| **Always a way out** | FrameLedger refuses rather than pushes through. When the guard finds anti-cheat, or the hook fails, or you have not enabled a game, it **stops** — and records the session anyway: start, end, duration, whatever hardware sensors your machine provides, and the reason there is nothing else. Every measured value reads `N/A`; it never estimates one.<br><br>**The way out is that it does not inject, not that it measures another way.** An earlier version of this row promised a no-injection measurement mode. It was designed around Intel PresentMon, that was dropped on 2026-08-27 after measurement, and no replacement was chosen — so **frame times require hooking**. Said in this row rather than a footnote because the row is in the SAFETY table, and a reader deciding whether to enable a game needs the real alternative, not a comfortable one |
@@ -98,32 +161,23 @@ FrameLedger is built to keep that risk small and to be honest about it:
| Tier | How | What you get |
|---|---|---|
| **1** | Injected hooks (opt-in, per game) | Everything above |
| **2** | None — nothing is injected | **Session duration, whatever hardware telemetry your machine can provide, and why there is nothing else** (which check refused, or that the hook failed, was not enabled, or the game is 32-bit). On NVIDIA that telemetry is measured to be GPU temperature, load, power, clocks, VRAM in use and fan speed, with no elevation; AMD and Intel are untested. Everything else reads `N/A` |
| **2** | None — nothing is injected | **Session duration, whatever hardware telemetry your machine can provide, the game's own memory use (read from Windows, outside the game; since beta.12), and why there is nothing else** (which check refused, or that the hook failed, was not enabled, or the game is 32-bit). On NVIDIA that telemetry is measured to be GPU temperature, load, power, clocks, VRAM in use and fan speed, with no elevation; AMD and Intel are untested. Everything else reads `N/A` |
The tier is recorded on every session and shown in the UI. Metrics unavailable at a session's tier read `N/A` — FrameLedger never substitutes an estimate for a measurement.
> **This ladder used to have three rungs and a middle one that measured frame times without injecting.** It was to be built on Intel PresentMon; that was dropped on 2026-08-27 after measurement, and no replacement was chosen. **So frame times, FPS and the lows are now Tier-1-only.** Said plainly because the previous README promised them without injection, and a reader who remembers that would otherwise assume it still holds.
## Architecture
| Component | Runs as | Role |
|---|---|---|
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
| `FrameLedger.Agent.exe` | Standard user (elevation optional) | Injection control, safety guard, data collection, GPU telemetry, storage |
| `FrameLedger.Overlay.dll` | Inside the game | C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks |
| `FrameLedger.VkLayer.dll` | Inside the game | Vulkan implicit layer (Vulkan titles use this instead of injection) |
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (not read yet — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on.
## Requirements
- Windows 10 (22H2) or Windows 11, 64-bit
- A 64-bit DirectX 11/12 or OpenGL game, or a Vulkan game FrameLedger starts, for hooked (Tier-1) capture. **32-bit games — including most DirectX 9 titles — cannot be measured at all**: the component FrameLedger loads is x64 and an x64 DLL cannot enter a 32-bit process. Such a title records duration and hardware telemetry and nothing else. *(This line previously said "supported at Tier 2 only", which meant frame times without injection. That tier no longer exists.)*
- Optional: [PawnIO](https://pawnio.eu/) for CPU temperature, which is not read yet (GPU telemetry works without it, through your graphics driver's own libraries)
- Optional: [PawnIO](https://pawnio.eu/) for CPU temperature, read only when the Agent runs as administrator (since 0.1.0-beta.3; not yet checked on real hardware). CPU load, memory in use and all GPU telemetry work without it
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (~~not read yet~~ read with PawnIO, not yet checked on real hardware — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on. **Since beta.10 it is a choice in Settings** — *Run the agent as administrator*, off by default: Windows asks every time the agent starts, games you start from FrameLedger still run as you, and `LIMITATIONS.md` says what it does not change.
## Install
> **No release has been published yet.** The steps below are for the first tagged release; until then FrameLedger runs only from a source build (`docs/12_BUILD.md`).
> **The latest beta is `v0.1.0-beta.35` (2026-11-09); before it `v0.1.0-beta.34` (2026-11-06), `v0.1.0-beta.33` (2026-11-03), `v0.1.0-beta.32` (2026-10-31), `v0.1.0-beta.31` (2026-10-26), `v0.1.0-beta.30` (2026-10-26), `v0.1.0-beta.29` (2026-10-25), `v0.1.0-beta.28` (2026-10-20), `v0.1.0-beta.27` (2026-10-20), `v0.1.0-beta.26` (2026-10-19), `v0.1.0-beta.25` (2026-10-19), `v0.1.0-beta.24` (2026-10-19), `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**.
@@ -131,26 +185,46 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
## Privacy
Everything lives locally in `%LOCALAPPDATA%\FrameLedger`. The only network calls FrameLedger will ever make: update checks against GitHub Releases, detection-rules updates from this repository, and *optional, opt-in* store metadata lookups. Bug reports are always built locally, shown to you, and submitted by you. Full policy: [`legal/PRIVACY_POLICY.md`](legal/PRIVACY_POLICY.md).
**Today it makes one of them: the update check** — at startup, a few seconds after launch, unless you turn it off in Settings ▸ Updates, and when you choose Help ▸ Check for updates — plus the download of an update you accepted; both go to GitHub Releases, from an installed copy only, and nothing is applied until you restart (never while a game is hooked). The rules feed does not exist — the blocklist ships with the build and updates only when you install a new one (`docs/20_OPEN_QUESTIONS.md` §S20). Listing a fetch that has no code is over-disclosure, and this document was already corrected once for describing a weekly outbound request the software never made.
Everything lives locally in `%LOCALAPPDATA%\FrameLedger`. The only network calls FrameLedger makes are **the update check** — a few seconds after launch unless you turn it off in Settings ▸ Updates, and when you choose Help ▸ Check for updates — and **the download of an update you accepted**; both go to GitHub Releases, from an installed copy only, and nothing is applied until you restart (never while a game is hooked). There is no other request: the anti-cheat blocklist and the detection rules ship with the build and update only when you install a new one (`docs/20_OPEN_QUESTIONS.md` §S20), and nothing is looked up on any store. Bug reports are always built locally, shown to you, and submitted by you. Full policy: [`legal/PRIVACY_POLICY.md`](legal/PRIVACY_POLICY.md) — version 2.2 removed the three rows (a rules feed twice over, a Steam lookup) that earlier versions listed for requests the software never made.
## License
GPL-3.0-only. See `LICENSE`. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
## Documentation
Developer/AI-facing docs in [`docs/`](docs/). Start with `CLAUDE.md`, then `docs/19_SAFETY_AND_ANTICHEAT.md` (which constrains everything else), then `docs/01_ARCHITECTURE.md`.
GPL-3.0-only (see `LICENSE`), with the additional terms in [`NOTICE`](NOTICE) that GPLv3 section 7 permits: keep the copyright line and the attribution, mark a changed version as changed and do not call it "FrameLedger" alone, and no trademark rights in the name ([`legal/TRADEMARKS.md`](legal/TRADEMARKS.md)). In the app: Help ▸ About. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
## Reporting a safety gap
If you find a game with anti-cheat that FrameLedger fails to detect, please open an issue — **that is a safety bug and is treated with the same priority as a security report.**
If you find a game with anti-cheat that FrameLedger fails to detect, please open an issue with the *Safety gap* form — **that is a safety bug and is treated with the same priority as a security report.** A vulnerability in FrameLedger itself takes the private route in [`SECURITY.md`](SECURITY.md).
**How fast a fix can reach you, stated accurately.** Blocklist entries are data rather than code, so a fix is a one-line change here. But the software has **no rules-update path yet**: it installs the blocklist that shipped with your build and never fetches another (`docs/20_OPEN_QUESTIONS.md` §S20, feed half). Until that exists, a blocklist fix reaches you **only when you install a new release**. This paragraph previously said the opposite, and the sentence it said it in was a response-time promise attached to a security-priority commitment.
## For developers and forks
FrameLedger is GPL-3.0-only free software, and you are welcome to build it, change it and redistribute it.
- **Build it:** [`docs/12_BUILD.md`](docs/12_BUILD.md) — `./build.ps1 check` is the whole quality gate, the same one CI runs.
- **Contribute:** [`CONTRIBUTING.md`](CONTRIBUTING.md) — the definition of done, what will not be merged, and that a
contribution is licensed GPL-3.0-only with the [`NOTICE`](NOTICE) terms (no CLA). Conduct:
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reports: [`SECURITY.md`](SECURITY.md). Accessibility — the goal,
the checks and how a barrier is reported: [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
- **Fork or redistribute:** [`FORKING.md`](FORKING.md) — what the GPL asks of anyone who distributes builds, and the names
a fork must change so it does not share FrameLedger's update feed, install folder, data, pipe or Vulkan layer.
- **Find your way around:** the [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages are short, and each
links to the document it summarises ([`wiki/`](wiki/) is their source).
- **Read the design:** the developer documentation is in [`docs/`](docs/). Start with [`CLAUDE.md`](CLAUDE.md), then
[`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) — which constrains everything else — then
[`docs/01_ARCHITECTURE.md`](docs/01_ARCHITECTURE.md).
### Architecture
| Component | Runs as | Role |
|---|---|---|
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
| `FrameLedger.Agent.exe` | Standard user — as administrator only when you turn that on in Settings, and Windows asks at every start (beta.10) | Injection control, safety guard, data collection, GPU telemetry, storage |
| `FrameLedger.Overlay.dll` | Inside the game | C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks |
| `FrameLedger.VkLayer.dll` | Inside the game | Vulkan implicit layer (Vulkan titles use this instead of injection) |
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
---
**Status:** pre-alpha, under active development. Roadmap: [`docs/15_ROADMAP.md`](docs/15_ROADMAP.md).
**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.
+1
View File
@@ -0,0 +1 @@
main
+72
View File
@@ -0,0 +1,72 @@
# Security policy
FrameLedger loads a component into game processes that the user has individually enabled, and it
refuses to do so when it detects anti-cheat or anti-tamper software. Two kinds of report matter here,
and they take different routes.
## A vulnerability in FrameLedger
Anything that could let FrameLedger be used against the person running it or against a third party:
a way to make the Agent inject into a process the user did not enable, a way past the anti-cheat
guard, a way to make the hook read or write game memory it does not own, a way to make the App or
Agent execute something from an untrusted source, a privacy leak (data leaving the machine, or the
bug bundle carrying what the privacy policy says it does not).
**Report it privately.** Use GitHub's private vulnerability reporting on this repository when it is
enabled (Security ▸ Report a vulnerability); otherwise e-mail <contact@poli0981.dev>. Please do not
open a public issue for a vulnerability until a fix has shipped.
What helps: the version (Help ▸ About, or `FrameLedger.exe --diag`), the steps, and what you observed.
What to leave out: instructions for defeating any anti-cheat system — FrameLedger needs to know what
to refuse, never how to evade (`docs/19_SAFETY_AND_ANTICHEAT.md`).
This is a one-person project. The intent is to acknowledge a private report within a week and to say
plainly what will happen next; that is an intent, not a contractual response time.
## The guard has no override
For two pre-releases (0.1.0-beta.3 and beta.4) a user could overrule the anti-cheat guard for one game through a
disclosure. That switch was withdrawn on 2026-09-22 (`docs/19_SAFETY_AND_ANTICHEAT.md` §What a finding does to the game): a finding
now turns the game's hooking off. What IS a security report: any way to reach an injection past a refusal — a flag, a
setting, a crafted rules file, a pipe message, a database edit the Agent honours — or a finding about a game that
does not turn its hooking off.
Since 0.1.0-beta.9 one narrow exception exists (owner decision D33, `docs/19_SAFETY_AND_ANTICHEAT.md` §The user-mode
exception): per game, only for one anti-cheat family that is user-mode throughout, with the guard still running every
check. The grant is a record in your own database, like the consent stamp; what keeps it narrow is the guard, which
decides itself which family it may let through. So these are security reports too: the guard letting through a family
that has a driver, a service or a `.sys` in the floor or the rules; an exception applying to a game with a kernel
driver in its folder, on a title list, or with a second anti-cheat; the Agent writing a grant on a pipe message
without its own tolerant pre-scan; an exception that survives a new finding, a crash or safety stop under it, or a
changed executable; since 0.1.0-beta.11 (D38), an exception that survives a session during its two-session trial that
did not go well, and any grant written for a game whose earlier exception failed its trial; and the Overlay tolerating
a family the guard did not.
## Running the agent as administrator
Since 0.1.0-beta.10 the capture agent can run as administrator — an option, off by default (owner decision D34,
`docs/01_ARCHITECTURE.md` ADR-9) — and Windows asks at every start of the agent. The residual risk is stated to the user
rather than solved: FrameLedger installs per user and unsigned, so a program running under the same account could replace
its files and be run as administrator when the user next accepts the prompt. What IS a security report: any way the
agent becomes administrator WITHOUT that prompt (a task, a service, an inherited token the option did not choose); a game
or any other program that an elevated agent starts with its own token instead of the desktop shell's; any privilege the
agent enables (none is — `tools/chokepoint-check.ps1` forbids the enablers under `src/`); an elevated agent that runs for
another account than the one that asked; and a named object an elevated agent creates that the same user's unelevated
processes can no longer open, or that another user can.
## A safety gap — a game with anti-cheat that FrameLedger fails to detect
This is treated with the same priority as a security report, and it takes the **public** route: open
an issue with the *Safety gap* form (`.github/ISSUE_TEMPLATE/safety_gap.yml`). Blocklist entries are
data (`rules/detection-rules.json`), so the fix is small — but the software has no rules-update path
yet, so a fix reaches installed copies only with the next release (`README` §Reporting a safety gap
says the same, and `docs/20_OPEN_QUESTIONS.md` §S20 carries the feed that would change it).
## Scope notes
- Releases are not code-signed; `SHA256SUMS.txt` is published beside every asset (`docs/11_UPDATER.md`
§Unsigned releases). A report that an installer's hash does not match what the release lists is a
security report.
- The evasion techniques FrameLedger will never implement are listed in `docs/19_SAFETY_AND_ANTICHEAT.md`.
A pull request that makes FrameLedger harder for anti-cheat to see is declined on principle, not
reviewed for quality.
+84
View File
@@ -0,0 +1,84 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
SonarCloud, analysed from CI since 2026-10-25 (docs/13_CI_CD.md §SonarCloud, owner decision D68): ci.yml's
`sonarcloud` job passes this file to the SonarScanner for .NET's begin step (/s:). It replaces
.sonarcloud.properties, which only Automatic Analysis read (D67). The project key, the organisation, the version
and the token are given on the command line; everything that does not change from one run to the next is here.
-->
<SonarQubeAnalysisProperties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonarsource.com/msbuild/integration/2015/1">
<Property Name="sonar.host.url">https://sonarcloud.io</Property>
<!--
What is not FrameLedger's code, or not code at all:
- src/native/third_party: the vendored SDK headers (NVAPI, Streamline, FidelityFX, Vulkan-Headers), 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.
And, since the scanner reads the whole checkout for the languages it finds outside the projects (PowerShell,
YAML, JSON), what a build writes into it: the native build tree with the sources CMake fetched into it, out/,
every project's bin/ and obj/, and the test results the coverage comes from.
-->
<Property Name="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/**,build/**,out/**,**/bin/**,**/obj/**,**/TestResults/**</Property>
<!-- Tests repeat their arrange steps on purpose; duplication there is not a defect. -->
<Property Name="sonar.cpd.exclusions">tests/**,src/native/tests/**</Property>
<Property Name="sonar.sourceEncoding">UTF-8</Property>
<!--
The native code: CMake's compilation database for the x64-release preset, which the job configures before the
begin step. The sources reach the analysis through FrameLedger.Infrastructure.csproj's FlNativeSource items,
because the scanner analyses only files an MSBuild project names. Reported against C++20, the standard
src/native/CMakeLists.txt sets.
-->
<Property Name="sonar.cfamily.compile-commands">build/native/x64-release/compile_commands.json</Property>
<Property Name="sonar.cfamily.reportingCppStandardOverride">c++20</Property>
<!--
The gate's coverage: build.ps1 writes OpenCover beside the Cobertura that tools/coverage-gate.ps1 reads, one
report per test project in TestResults/<guid>/. The second copy the trx logger keeps under In/ is not matched.
-->
<Property Name="sonar.cs.opencover.reportsPaths">tests/*/TestResults/*/coverage.opencover.xml</Property>
<!--
Coverage is measured for the C# only. SonarCloud counts the executable lines of a file no report covers as
uncovered - the first analysis read build.ps1's 232 lines to cover, every one uncovered, and failed the gate on the
two a pull request changed - so the PowerShell tools (tested by their own -SelfTest cases, which no coverage tool
reads) and the native code (Catch2 suites and the injection tests, with no coverage collector) are left out of the
coverage figures. They are analysed for issues as everything else is.
-->
<Property Name="sonar.coverage.exclusions">**/*.ps1,**/*.psm1,src/native/**</Property>
<!--
Roslynator, Meziantou, the VS threading analyzers and the .NET analyzers already gate the build (warnings as
errors); what they report at a lower severity is the project's choice. Only SonarCloud's own rules are imported.
-->
<Property Name="sonar.cs.roslyn.ignoreIssues">true</Property>
<!--
Two rules this project breaks by design everywhere they apply (the triage of 2026-10-19 in docs/13_CI_CD.md
accepted every instance):
- S8417, sequentially consistent atomics: 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. The rule
key's repository is a wildcard because a header is indexed as C and a source file as C++.
- csharpsquid:S6640, unsafe code: 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).
-->
<Property Name="sonar.issue.ignore.multicriteria">atomics,unsafeInfrastructure,unsafeShared</Property>
<Property Name="sonar.issue.ignore.multicriteria.atomics.ruleKey">*:S8417</Property>
<Property Name="sonar.issue.ignore.multicriteria.atomics.resourceKey">src/native/**/*</Property>
<Property Name="sonar.issue.ignore.multicriteria.unsafeInfrastructure.ruleKey">csharpsquid:S6640</Property>
<Property Name="sonar.issue.ignore.multicriteria.unsafeInfrastructure.resourceKey">src/FrameLedger.Infrastructure/**/*</Property>
<Property Name="sonar.issue.ignore.multicriteria.unsafeShared.ruleKey">csharpsquid:S6640</Property>
<Property Name="sonar.issue.ignore.multicriteria.unsafeShared.resourceKey">src/FrameLedger.Shared/**/*</Property>
<!-- The end step waits for the quality gate, so a failed gate is a red job, not a check nobody opens. -->
<Property Name="sonar.qualitygate.wait">true</Property>
<Property Name="sonar.qualitygate.timeout">600</Property>
</SonarQubeAnalysisProperties>
+96 -26
View File
@@ -1,3 +1,6 @@
# SPDX-License-Identifier: GPL-3.0-only
# Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
#Requires -Version 7.0
<#
.SYNOPSIS
@@ -68,6 +71,25 @@ function Invoke-Checked([string]$What, [scriptblock]$Body) {
if ($LASTEXITCODE -ne 0) { throw "$What failed (exit $LASTEXITCODE)" }
}
<#
`dotnet test` under a wall-clock limit (2026-09-17). `--blame-hang` does not stop a deadlocked xUnit v3 test
executable — measured: the hung process was still alive four minutes after a 60 s hang timeout — so a hang spent the
CI job's whole 60-minute budget and named nothing (the first tag's release run, 2026-09-16). This kills the process
tree after $Minutes and names the test projects that wrote no results.trx: the ones that did not finish.
#>
function Invoke-TestsWithin([int]$Minutes, [string[]]$Arguments) {
$p = Start-Process -FilePath 'dotnet' -ArgumentList $Arguments -NoNewWindow -PassThru
$null = $p.Handle # Start-Process quirk: without a cached handle ExitCode reads empty after exit
if (-not $p.WaitForExit($Minutes * 60 * 1000)) {
& taskkill /T /F /PID $p.Id 2>&1 | Out-Null
$unfinished = @(Get-ChildItem (Join-Path $repo 'tests') -Directory -Filter '*.Tests' |
Where-Object { -not (Test-Path (Join-Path $_.FullName 'TestResults/results.trx')) } |
ForEach-Object { $_.Name })
throw "dotnet test did not finish within $Minutes minutes — a test hung, and the process tree was killed. No results.trx from: $($unfinished -join ', ')"
}
if ($p.ExitCode -ne 0) { throw "dotnet test failed (exit $($p.ExitCode))" }
}
<#
Clear an ambient Platform variable before any MSBuild invocation.
@@ -253,18 +275,27 @@ function Invoke-Managed([bool]$FixFormat) {
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
# --logger trx so downstream gates can assert that a NAMED test executed,
# not merely that the run was green. The struct-mirror gate below reads it.
#
# --blame-hang: a test that never returns names itself and fails the run after
# 15 minutes, instead of eating the job's timeout. The first tag run
# (v0.1.0-beta.1, 2026-09-16, run 35111939019) sat in Infrastructure.Tests for
# 58 minutes — every other suite green, the whole suite 42 s the run before —
# until the 60-minute job limit cancelled it, and the log named nothing. The
# timeout is per test host, well above the slowest suite (Agent, ~1.5 min on
# the hosted runner); the mini dump goes to TestResults beside the trx.
# --blame-hang did NOT stop the deadlocked xUnit v3 executable it was added for (measured 2026-09-17); the
# wall-clock limit of Invoke-TestsWithin is what bounds a hang now. The suite takes 4-5 minutes on the runner.
#
# Two coverage formats from the one run (2026-10-25, D68): Cobertura for the coverage gate below, OpenCover for
# SonarCloud, whose C# importer reads no Cobertura. ci.yml's sonarcloud job takes them from this run's artifact.
$testArgs = @('test', "`"$solution`"", '-c', $Configuration, '--no-build',
'--collect:"XPlat Code Coverage;Format=cobertura,opencover"', '--logger', 'trx;LogFileName=results.trx')
if ($SkipIntegration) {
Skip-Gate 'integration tests' 'the guard refuses a .NET test host that loads a `protect`-matching module (20_OPEN_QUESTIONS §S19(b)) — run ./build.ps1 check with no switches to include them'
Invoke-Checked 'dotnet test' {
dotnet test $solution -c $Configuration --no-build --collect:"XPlat Code Coverage" `
--logger 'trx;LogFileName=results.trx' --filter 'Category!=Integration'
}
Invoke-TestsWithin 25 ($testArgs + @('--filter', 'Category!=Integration'))
}
else {
Invoke-Checked 'dotnet test' {
dotnet test $solution -c $Configuration --no-build --collect:"XPlat Code Coverage" `
--logger 'trx;LogFileName=results.trx'
}
Invoke-TestsWithin 25 $testArgs
}
# The cobertura reports above were produced and ignored from the day the
@@ -274,12 +305,10 @@ function Invoke-Managed([bool]$FixFormat) {
# so the number is never negotiated against code that already exists.
Write-Step 'coverage-gate'
$coverageTool = Join-Path $repo 'tools/coverage-gate.ps1'
if (Test-Path $coverageTool) {
Invoke-Checked 'coverage-gate' { & $coverageTool }
}
else {
Skip-Gate 'coverage-gate' 'tools/coverage-gate.ps1 not implemented yet'
}
# The tool has existed since P2. A missing file is a broken checkout, and this script's own header says why a gate
# must not read as "skipped" then: it would say "checked" in CI output when nothing was (corrected 2026-09-21).
if (-not (Test-Path $coverageTool)) { throw 'tools/coverage-gate.ps1 is missing; the coverage gate cannot be skipped' }
Invoke-Checked 'coverage-gate' { & $coverageTool }
}
# --- 7-9. Project-specific gates -------------------------------------------
@@ -288,23 +317,33 @@ function Invoke-ProjectGates {
# failure (docs/13_CI_CD.md).
Write-Step 'rules-validate'
$rulesTool = Join-Path $repo 'tools/rules-validate.ps1'
if (Test-Path $rulesTool) {
Invoke-Checked 'rules-validate' { & $rulesTool }
}
else {
Skip-Gate 'rules-validate' 'tools/rules-validate.ps1 not implemented yet'
}
if (-not (Test-Path $rulesTool)) { throw 'tools/rules-validate.ps1 is missing; the rules gate cannot be skipped' }
Invoke-Checked 'rules-validate' { & $rulesTool }
# 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'
@@ -387,7 +426,7 @@ function Invoke-ProjectGates {
Write-Step 'license-check'
$licenseTool = Join-Path $repo 'tools/license-check.ps1'
if (Test-Path $licenseTool) {
# P4 PR-6: the NuGet half's generator proves itself first (fourteen cases, five that must be RED), then
# P4 PR-6: the NuGet half's generator proves itself first (sixteen cases since beta.12, six that must be RED), then
# license-check runs its live -Check over this build's restore output as its section 3.
Invoke-Checked 'license-gather (self-test)' { & (Join-Path $repo 'tools/license-gather.ps1') -SelfTest }
Invoke-Checked 'license-check' { & $licenseTool }
@@ -420,6 +459,31 @@ function Invoke-ProjectGates {
Skip-Gate 'accuracy-check' 'tools/accuracy-check.ps1 not implemented yet'
}
# beta.12 (D45): GPLv3 section 7 wants additional terms named "in the relevant source files", so every
# first-party source file opens with the SPDX line and the NOTICE pointer. Self-test first (seven cases, both
# directions), then the live pass over the tracked tree; ./tools/notice-check.ps1 -Fix writes a missing header.
Write-Step 'notice-check'
$noticeTool = Join-Path $repo 'tools/notice-check.ps1'
Invoke-Checked 'notice-check (self-test)' { & $noticeTool -SelfTest }
Invoke-Checked 'notice-check' { & $noticeTool -RepoRoot $repo }
# beta.17 (D53/D54): the GitHub Wiki is built from wiki/, guide/, LIMITATIONS.md and (beta.35) ACCESSIBILITY.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) {
@@ -435,6 +499,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.
+52 -9
View File
@@ -23,11 +23,18 @@
│ ├ upscaler hooks: NGX · Streamline · FFX · XeSS │
│ ├ RT hooks: CreateStateObject · DispatchRays · BuildRaytracingAS │
│ ├ PSO hooks: pipeline creation (stutter attribution) │
│ ├ per-process VRAM: IDXGIAdapter3::QueryVideoMemoryInfo │
│ ├ (per-process VRAM via QueryVideoMemoryInfo: never built — D43 reads │
│ │ the game's memory from outside, in the Agent's ProcessStats.dll) │
│ └ ring writer (allocation-free, lock-free, SEH-guarded) │
└───────────────────────────────────────────────────────────────────────────┘
```
> **Corrected 2026-10-04 — the game-process box names hooks that were never built.** ~~NGX · XeSS ·
> CreateStateObject · PSO hooks~~: NGX is licence-blocked, XeSS stops at the runtime census by licence, and
> `CreateStateObject` and pipeline creation are unwritten rows of `17_HOOK_ENGINE` §Hook inventory. What the Overlay
> does install: the DXGI present path, `wglSwapBuffers`, the Streamline and FidelityFX entry points, the two
> `ID3D12GraphicsCommandList4` ray-tracing methods, and the `LoadLibraryExW` wake.
> `*` **`AntiCheatGuard` is a facade, not an implementation.** The guard is
> native (`20_OPEN_QUESTIONS` §S13(a)); the box above is the P/Invoke wrapper
> in `Infrastructure` that the Agent calls. Nothing managed parses rules or
@@ -57,8 +64,8 @@
| Tier | Mechanism | Gets you | When used |
|---|---|---|---|
| **1** | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT/PT evidence, per-process VRAM, PSO stutter attribution, Reflex latency, present flags | Offline/single-player titles the user opted in |
| **2** | None | **Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else** — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every measured field reads `N/A` (FR-4.9) | Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
| **1** | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT ~~/PT~~ evidence, ~~per-process VRAM, PSO stutter attribution, Reflex latency,~~ present flags *(corrected 2026-10-04: path tracing, the in-game VRAM, PSO attribution and Reflex latency have no producer — `05_DETECTION` §Runtime facts)* | Offline/single-player titles the user opted in |
| **2** | None | **Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else** — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every ~~measured~~ frame field reads `N/A` (FR-4.9) *(corrected 2026-10-04: two facts are measured from outside the game in both tiers — the display mode (beta.10) and the game process's memory (beta.12, D43))* | Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
Tier is recorded per session (`sessions.capture_tier`) and shown in the UI, because metric availability differs and comparing across tiers must be explicit.
@@ -90,8 +97,23 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
- Agent idles at ~0% CPU: 1 Hz process poll. No capture machinery exists until a tracked game launches.
- Session ends when the process tree exits, or on safety unhook, or on user stop.
- The DLL is **not unloaded** from a live process after unhooking (threads may still be inside trampolines). It disables its hooks, stops writing, and goes dormant until the process exits. Documented, deliberate.
- UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.
- ~~UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.~~ *(Corrected 2026-10-04: closing the UI never stops the Agent. `Shutdown` is sent only for an update, by the uninstall hook and for the admin mode's restart; the background-capture setting was read by nothing, and its switch is gone since beta.12 — `06_DATA_MODEL` §Settings registry.)*
- Single instance via named mutexes; the ring name is per-PID so multiple games can be captured simultaneously (rare but supported).
- **An alpha build's `--serve` waits for the Alpha notice (D74, 2026-10-31):** it reads `legal_acceptance` after opening the
ledger and, until the App's Legal Gate has recorded the notice at the version the build carries (`Shared.AlphaNotice`),
logs why and exits **8** — the logon task or the admin mode's prompt can start it before the App ever showed the notice.
The App holds its own start of the Agent while the gate is open and starts it at the Accept; the maintenance verbs
(`--register-vklayer`, `--install-task` and their reverses) are not held. The main line serves as before.
> **The single instance was specified here and not built until 2026-09-17**, and 0.1.0-beta.1 ran four Agents: an
> App started as administrator was refused by the pipe of the Agent already serving (`07_IPC` §C, amended the same
> day), took the refusal for an absent Agent, and started another on each connect round — and every game launched in
> the next hour was injected, read and recorded by all four. **Built:** `Infrastructure.Startup.AgentInstanceLock`,
> one named mutex per data folder (`Local\FrameLedger.Agent.<hash of the folder>`), claimed by `--serve` and the
> console's capturing verbs (`capture`, `launch`, `recover`) before logging, rules or the ledger; a second process
> exits **10** with one line on stderr. The App probes the same claim before it starts an Agent (`07_IPC` §Client
> behavior). What it does not cover: two Agents on two data folders (a developer's `--console --data-dir` beside the
> installed Agent) can still both attach to one game's ring — `20_OPEN_QUESTIONS` §G, Agent lifecycle.
## Failure domains
@@ -100,12 +122,12 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
| Anti-cheat detected pre-injection | Refuse, explain which signal fired, offer Tier 2 |
| Anti-cheat detected mid-session | Immediate clean unhook, `exit_status = unhooked_safety`, prominent notice |
| Injection API fails (access denied, protected process) | Log, no retry loop, offer Tier 2 + "run Agent elevated" hint — elevation here is about *attaching to an elevated target*, not about reaching a tier; Tier 2 needs none |
| Hook faults 3× | DLL self-disables, sets fault flag in handshake block, Agent finalizes session as `degraded` |
| Hook faults 3× | DLL self-disables, sets ~~fault flag in handshake block~~ `FlWriterState.status` to `SELF_DISABLED` *(corrected 2026-10-04)*, Agent finalizes session as `degraded` |
| Game crashes ≤ 60 s after injection, twice | Hooking auto-disabled for that game, Tier 2 takes over |
| Ring overflow (Agent stalled) | Overwrite-oldest; dropped count published in the ring header → session flagged with a data-quality warning |
| Ring overflow (Agent stalled) | Overwrite-oldest; ~~dropped count published in the ring header~~ the Agent counts drops from its own read index *(corrected 2026-10-04: the writer keeps no reader index and publishes no count — `04_CAPTURE` §Ring draining)* → session flagged with a data-quality warning |
| Layout/version mismatch DLL ↔ Agent | Agent refuses to attach, tells user to restart the game after update |
| Vendor API unavailable (no NVAPI etc.) | GPU telemetry degrades to `N/A`; frame metrics unaffected |
| DB locked/corrupt | Integrity check + backup-and-recreate in Tools |
| DB locked/corrupt | Integrity check + backup~~-and-recreate~~ in Tools ▸ Database maintenance *(corrected 2026-10-04: there is no recreate action)* |
## Data directory
@@ -116,11 +138,18 @@ ledger.db SQLite (WAL)
rules\detection-rules.json engine/platform/feature + anticheat blocklist
logs\ui-*.log, agent-*.log, overlay-<pid>-*.log (native log flushed at session end, never mid-frame)
crashdumps\*.dmp
breadcrumbs\<pid>.json pre-injection breadcrumb (19_SAFETY §Crash safety)
breadcrumbs\<pid>.json (corrected 2026-10-04: never created — the breadcrumb is the .partial file's header and notes)
tmp\<sessionGuid>.partial crash-safety flush of raw buffers, every 60 s (04_CAPTURE §Ring draining)
covers\*.jpg
covers\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
backups\ledger-before-<v>.db an alpha build's copy of ledger.db before it first opened it, newest three (D73,
2026-10-31; 06_DATA_MODEL §Migrations) — the alpha shares this folder with the beta
```
*(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.
@@ -132,3 +161,17 @@ covers\*.jpg
- **ADR-7 (2026-07, core change):** **Capture moves to in-process graphics-API hooking**, C++20 DLL + MinHook, with a Vulkan implicit layer for Vulkan. Rationale: passive detection of DLSS/upscaling/frame-generation/RT state showed large errors against real games; those states are only knowable at the API boundary. Trade-offs accepted: anti-cheat exposure (mitigated by the hard guard in `19_SAFETY`, offline titles only), crash risk in the host process (mitigated by SEH guards + fault policy + auto-disable), a second toolchain in the build, and per-API maintenance as vendors change SDKs. Scope limited to titles the user explicitly opts in.
- **ADR-8:** **No evasion, ever** (`19_SAFETY` §What we will never build). This is an architectural constraint, not a preference — it defines what "correct" means for this codebase.
- **ADR-9:** Elevation demoted from required to optional; the Agent runs as a standard user by default.
**Chosen, not inherited, since beta.10 (owner decision D34, 2026-09-27):** Settings ▸ Capture agent ▸ *Run the agent as
administrator* (`capture.run_elevated`, off by default, a versioned disclosure — `agent-admin-dialog/1` — before it turns
on). With it on, **Windows is asked every time the Agent starts** — a UAC prompt owned by the App's window when the App
starts it, flashing on the taskbar when the logon task does — and there is no silent path: no "highest privileges" task,
no service. The elevated Agent is started for one user (`--serve --for-user <SID>`) and refuses to run as another
account (exit 11: a standard user answered with an administrator's password, and that account's `%LOCALAPPDATA%` is not
this user's ledger); a declined prompt leaves a standard user's Agent that says so (`--elevation declined`,
`HelloAck.ElevationOutcome`). With it off, an App started as administrator starts the Agent with the desktop shell's
token. **A game an elevated Agent starts gets the shell's token too** (`Infrastructure.Startup.UnelevatedProcess`) —
`LaunchGame` reaches the Agent over a pipe any process of the user may open, so an elevated launch would be a silent
elevation — and nothing enables a privilege (`TokenPrivileges` reads them; `tools/chokepoint-check.ps1` forbids the
enablers under `src/`). It buys what it always did: attaching to a game that runs as administrator, and the CPU
temperature with PawnIO. It does not open a process an anti-cheat driver protects (D21), and a Vulkan game that runs as
administrator stays unmeasured — the Khronos loader ignores the HKCU implicit layers for an elevated process.
+29 -16
View File
@@ -6,27 +6,33 @@ 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.2 Auto-import from Steam, GOG Galaxy, Epic, itch.io with a review checklist — and, since beta.33 (D79), the Xbox app and the Microsoft Store (GDK titles: each drive's `.GamingRoot` folders and each game's package files, `05_DETECTION` §Platform signatures & metadata). **Import never enables hooking for anything.**
- 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; since beta.33 also the square logo and splash image an Xbox game ships in its own package folder.)*
- 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). *(beta.33, D80: a game the Xbox app or the Microsoft Store installed starts through Windows in either mode — its package activated as its Start-menu tile does — and never by the agent's launch mode, which cannot start it in its package.)*
- 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`)
- FR-2.1 Hooking is **off by default for every game**. Enabling requires a per-game consent dialog stating what is injected, why, and the anti-cheat/ban risk.
- FR-2.2 The static anti-cheat pre-scan disables the toggle outright for titles shipping anti-cheat; the reason is shown and the control is not clickable.
- FR-2.3 The runtime guard refuses injection and refuses to continue a session when anti-cheat is detected. **No override exists anywhere in the UI, config, or CLI.**
- FR-2.2 The static anti-cheat pre-scan disables the toggle outright for titles shipping anti-cheat; the reason is shown and the control is not clickable. Since 2026-09-25 (beta.8, owner decision) the Agent runs that pre-scan over every library entry itself — once per rules version and executable, whether or not hooking was ever asked for — and by default the game's page shows only the finding in place of the Hooking card (Settings: *Hide hooking on anti-cheat games*, `ui.hide_anticheat_hooking`); the library card says "Anti-cheat". The reason is always on the page (`19_SAFETY` §What a finding does to the game).
- FR-2.3 The runtime guard refuses injection and refuses to continue a session when anti-cheat is detected. **No override exists anywhere in the UI, config, or CLI.** *(Since 2026-09-26 one narrow, evidence-bound exception exists — FR-2.8. It is not an override: the guard still runs every check and decides itself which anti-cheat family it may let through.)*
- FR-2.4 Global "disable all hooking" kill switch in Settings; also honored by the Vulkan layer.
- FR-2.7 (owner decision 2026-09-22; it was a per-game override for one day, withdrawn) A finding about a game — anti-cheat named in its process, on its title lists or in its folder — turns hooking off for that game wherever the guard makes it: at the pre-scan, at a session's start, at the 30 s re-scan, or (since 2026-09-25) at the Agent's pre-scan of the library. The row carries the reason, the game's page and the notice say so, and nothing overrides it (`19_SAFETY` §What a finding does to the game).
- FR-2.8 (owner decision D33, 2026-09-26) **The user-mode anti-cheat exception.** A Settings option, off by default, lets the user grant a per-game exception to a game whose only anti-cheat findings are ONE family that is user-mode throughout (no driver, service or `.sys` in the floor or the rules), whose install tree holds no `.sys`, which is on no title list, ~~and which FrameLedger has measured hooked at least twice (successful Tier-1 sessions)~~ and no exception of which ever ended during its trial (D38, 2026-10-03: a grant needs no session; its first two hooked sessions are a trial, and an end during the trial — any end below, or a stored hooked session with no frames or an abnormal exit — ends it for good, `games.ac_exception_trial_failed_at`). The Agent computes that eligibility itself; the user grants each game through a versioned disclosure that states the ban risk; hooking is then turned on through FR-2.1's dialog as ever. Machine-wide drivers and services, title lists, kernel drivers in the game folder, the fuzzy tier, a scan that could not finish, an unreadable process, a 32-bit game, the kill switch and Vulkan are never excepted. A new finding, a crash / safety unhook / Overlay stop under it, or a changed executable ends it; the option off suspends it; the block itself is never cleared and stays shown (FR-2.2). Sessions under it are marked with the family (`19_SAFETY` §The user-mode exception).
- FR-2.5 Repeated crashes shortly after injection auto-disable hooking for that game, with an explanation and a manual re-enable path.
- FR-2.6 Users can always see, per session, which tier produced the data.
### FR-3 Session capture
- FR-3.1 Watcher detects tracked exe launches (1 Hz) and captures automatically at the highest permitted tier.
- FR-3.2 Launch mode: start the game from FrameLedger for suspended-launch injection (catches startup-time upscaler init).
- FR-3.2 Launch mode: start the game from FrameLedger for suspended-launch injection (catches startup-time upscaler init). *(The App reaches it since beta.21: Play set to Start directly sends `LaunchGame` — FR-1.9.)*
- FR-3.3 Attach mode for games launched externally; sessions flagged `late_attach`.
- FR-3.4 Track the process tree; capture the descendant that actually presents.
- FR-3.5 Per-frame records for the whole session; telemetry at 1 Hz (configurable 0.5–2 s).
- FR-3.6 Session ends on process-tree exit, safety unhook, or user stop. Sessions under the minimum length (default 30 s) are discarded.
- FR-3.7 Crash detection: nonzero exit code or matching Application Error 1000 / WER 1001 events → `exit_status = crashed`.
- FR-3.7 Crash detection: ~~nonzero exit code~~ an exception's exit code *(corrected 2026-10-04: since beta.8, `ExitStatusMapper.IsExceptionCode` — End task's exit code 1 is `normal`, the code kept in `capture_notes`; `04_CAPTURE` §Crash & exit classification)* or matching Application Error 1000 / WER 1001 events → `exit_status = crashed`.
- FR-3.8 Post-session toast with summary + "View".
- FR-3.9 Pause/resume capture globally from tray.
@@ -35,9 +41,9 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-4.2 **Native vs Displayed FPS + FG factor**, always shown together (`62 → 118 FPS (×1.9 FG)`).
- FR-4.3 *(Tier 1)* Measured upscaler identity, quality preset, render resolution, output resolution, upscale ratio; mid-session changes captured as segments.
- FR-4.4 *(Tier 1)* Measured RT activity (`rt_frame_pct`, `rays_per_pixel`, RT PSO count); RR from the NGX feature; PT as a confidence-scored suggestion only.
- FR-4.5 *(Tier 1)* Per-process VRAM usage/budget and budget-exceeded percentage.
- FR-4.5 *(Tier 1)* Per-process VRAM usage/budget and budget-exceeded percentage. *(beta.12, owner decision D43: the **usage** half is met for **both tiers** from outside the game — the game process's dedicated and shared GPU memory, Task Manager's columns — with its private working set, working set and commit beside it, mean / median / peak (`03_METRICS` §Game process memory). The budget and its exceeded percentage stay unmeasured, `20_OPEN_QUESTIONS` §M11.)*
- FR-4.6 *(Tier 1)* PSO-compilation stutter attribution; *(Tier 1 + Reflex)* PC latency avg/p95.
- FR-4.7 Telemetry aggregates: CPU/GPU temp, hotspot, loads, power, throttle %, RAM.
- FR-4.7 Telemetry aggregates: CPU/GPU temp, hotspot, loads, power, throttle %, RAM. *(beta.12: every stored series also has its median and minimum, in `sensor_stats_json`.)*
- FR-4.8 Sufficiency guards: 0.1% Low needs ≥ 10,000 app frames, 1% Low ≥ 1,000; else `N/A`.
- FR-4.9 Any metric unavailable at the session's tier renders `N/A` — never an estimate presented as measurement.
@@ -51,14 +57,17 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
### FR-6 History & comparison
- FR-6.1 Sessions table per game: date, duration, tier badge, Native, Displayed, FG×, lows, resolution + upscaler, RT/PT/RR chips, crash badge, tags.
- FR-6.2 Compare 2–5 sessions; **mixed-tier comparisons require explicit acknowledgement** and are marked on the chart.
- FR-6.3 Hardware snapshot per session; trend charts mark changes ("GPU driver 572.16 → 576.02").
- FR-6.3 Hardware snapshot per session; trend charts mark changes ("GPU driver 572.16 → 576.02") — since beta.30 a
numbered badge per day that changed, its changes listed under the chart (owner decision D70).
- FR-6.6 Charts across a game's sessions (beta.11, owner decision D39): the Sessions tab opens with an overview of every hooked session's rate and lows (Presented FPS, or Native and Displayed where frame generation was measured; 1% and 0.1% lows), a click selecting the session; and the Trend draws more metrics beside the selected one, two units at most (the second against the right axis).
- FR-6.4 Sessions with mid-session settings changes are excluded from trends by default, with a toggle.
- FR-6.5 Session tags and notes.
### FR-7 Detection
- FR-7.1 Static: engine, engine version, store platform, store id, publisher, game version (`05_DETECTION`).
- FR-7.2 Runtime: API, present mode, swap effect, HDR, upscaler, FG, RT — all Tier 1, all measured.
- FR-7.3 Rules ship as `detection-rules.json`, updatable independently of releases; **anticheat-block updates apply regardless of the user's rules auto-update preference.**
- FR-7.1 Static: engine, engine version, store platform, store id, publisher, game version (`05_DETECTION`; the Unreal Engine version since 2026-09-27, §Engine version).
- FR-7.2 Runtime: API, present mode, swap effect, HDR, upscaler, FG, RT — all Tier 1, all measured. (Present mode and HDR have no writer yet, `05_DETECTION` §Runtime facts; swap effect is written since beta.10 from the display-mode sample.)
- FR-7.4 Display mode (beta.10, owner request 2026-09-27): how each session's game was shown — exclusive fullscreen, borderless, windowed, minimised, or *fullscreen or borderless* where nothing could tell the two apart — as a share of the session's time, with the window, back buffer and monitor sizes; both tiers (Tier 2 from the window alone); shown on the session summary, the game page, the Trend (three share metrics) and Compare, and exported (`03_METRICS` §Display mode).
- FR-7.3 Rules ship as `detection-rules.json`, updatable independently of releases; **anticheat-block updates apply regardless of the user's rules auto-update preference.** *(Unmet — corrected 2026-10-04: there is no rules feed and no auto-update preference. Rules change only with a release: `RulesSeeder` installs them, Tools ▸ Update detection rules re-seeds them — `20_OPEN_QUESTIONS` §S20 feed half.)*
### FR-8 Tri-state flags
- FR-8.1 `Yes / No / N/A` for Ray Tracing, Path Tracing, Ray Reconstruction, per session, with source (`measured | manual | inherited`).
@@ -71,10 +80,14 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-9.3 Chart PNG.
### FR-10 Settings
Language (en/vi/ja), theme, start with Windows, minimize to tray, background capture, **global hooking kill switch**, min session length, telemetry interval, retention, Agent elevation (optional — explains what it unlocks), Vulkan layer registration state, update channel, online metadata opt-in, reopen legal documents.
> **beta.10 (D34):** "Agent elevation (optional — explains what it unlocks)" is the admin mode — *Run the agent as
> administrator*, off by default, a disclosure before it turns on, Windows' prompt at every Agent start (`01_ARCHITECTURE`
> ADR-9, `08_UI` §Settings).
Language (en/vi/ja), theme, start with Windows, minimize to tray, background capture, **global hooking kill switch**, min session length, telemetry interval, retention, Agent elevation (optional — explains what it unlocks), Vulkan layer registration state, update channel, ~~online metadata opt-in,~~ reopen legal documents *(corrected 2026-10-04: the opt-in has had no row since 2026-09-16 because no store request exists, and the background-capture switch — read by nothing — is gone since beta.12; `06_DATA_MODEL` §Settings registry)*. **beta.11 (owner request 2026-10-03: no row without a control):** Delete all sessions (FR-1.7, a *Data* section); the elevation state is a line of the admin mode's own row, not a row of its own; the hook-enabled list shows only while a game has hooking on; the language row carries no separate note.
### FR-11 Legal Gate
First run blocks until the user accepts EULA, GPLv3 notice, Disclaimer, Privacy Policy. Re-shown when a document version increments. The injection risk is stated in the Disclaimer *and* repeated at per-game consent (FR-2.1) — once is not enough for something that can cost an account.
First run blocks until the user accepts ~~EULA, GPLv3 notice, Disclaimer, Privacy Policy~~ the EULA, the Disclaimer and the Privacy Policy; **the GPLv3 is shown beside them for information and needs no acceptance** (GPLv3 §9 — "You are not required to accept this License in order to receive or run a copy of the Program"; changed beta.12, owner decision D45, `08_UI` §First-run flow). Re-shown when a document version increments. The injection risk is stated in the Disclaimer *and* repeated at per-game consent (FR-2.1) — once is not enough for something that can cost an account.
### FR-12 Updates
Velopack against GitHub Releases; silent startup check, manual check in Help; error dialogs mapped per `11_UPDATER`. **Updates never apply while a game is hooked** — deferred to session end (the DLL on disk must not change under a running game).
@@ -100,7 +113,7 @@ Draw live FPS/frametime/upscaler info inside the game. Only for games already ho
- **NFR-6 Accuracy:** per `03_METRICS` §Accuracy budget, stated per tier.
- **NFR-7 Resilience:** power loss loses at most the last 60 s of raw data; DB never corrupts (WAL + transactions); Agent restart recovers `.partial` sessions as `interrupted`.
- **NFR-8 OS support:** Windows 10 22H2+ and Windows 11, x64. No ARM64 in v1.
- **NFR-9 Accessibility:** full keyboard navigation, adequate contrast in both Fluent themes, Per-Monitor V2 DPI awareness. *(What each clause means for this app, and the check that holds it: `08_UI` §Accessibility, P4 PR-8.)*
- **NFR-9 Accessibility:** full keyboard navigation, adequate contrast in both Fluent themes, Per-Monitor V2 DPI awareness. *(What each clause means for this app, and the check that holds it: `08_UI` §Accessibility, P4 PR-8.)* *(Widened 2026-11-09, beta.35, owner decisions D88–D91: and a screen reader reads every control and value and is told what changes; Windows contrast themes are followed; nothing is shown by colour alone. The goal behind all of it is WCAG 2.2 AA as W3C's WCAG2ICT applies it to desktop software — a goal, not a conformance claim — stated to users in `ACCESSIBILITY.md`.)*
- **NFR-10 Offline-first:** everything except updates and opt-in metadata works with zero connectivity.
- **NFR-11 Auditability:** the entire set of hooks is enumerable in `17_HOOK_ENGINE` §Hook inventory and matches the code; a reviewer must be able to verify in minutes that nothing reads game memory.
@@ -108,4 +121,4 @@ Draw live FPS/frametime/upscaler info inside the game. Only for games already ho
**Permanently:** any evasion technique (`19_SAFETY`); reading/writing game memory; kernel drivers; hardware control (overclocking, fan curves, power limits — `18_GPU_VENDOR_APIS` is read-only); online/competitive titles.
**v1:** Microsoft Store/UWP/Game Pass titles (packaged-app injection constraints); macOS/Linux; cloud sync; benchmark automation; ARM64. **Tier-1 capture of 32-bit games, including most Direct3D 9 titles** — the Overlay is x64-only and an x64 DLL cannot be loaded into a 32-bit process; those titles are Tier 2, which since 2026-08-28 means **not measured at all** — duration, sensors and the reason (`17_HOOK_ENGINE` §Build profile, `20_OPEN_QUESTIONS` §Scope).
**v1:** ~~Microsoft Store/UWP/Game Pass titles (packaged-app injection constraints)~~ *(narrowed 2026-11-03, beta.33, owner decisions D78–D80: Microsoft Store, Xbox app and PC Game Pass titles built on the GDK — full-trust packages — are in scope; what "the constraints" are was measured in `spike-notes` §25. UWP apps, which run in an app container, stay out: refused with a reason of their own)*; macOS/Linux; cloud sync; benchmark automation; ARM64. **Tier-1 capture of 32-bit games, including most Direct3D 9 titles** — the Overlay is x64-only and an x64 DLL cannot be loaded into a 32-bit process; those titles are Tier 2, which since 2026-08-28 means **not measured at all** — duration, sensors and the reason (`17_HOOK_ENGINE` §Build profile, `20_OPEN_QUESTIONS` §Scope).
+410 -14
View File
@@ -1,6 +1,6 @@
# 03 — Metrics
**Single source of truth** for every number FrameLedger displays. ~~Implement in `FrameLedger.Domain.Metrics` with golden tests (`14_TESTING`).~~ **Implemented in `FrameLedger.Domain.Metrics` since 2026-09-09 (P2 PR-A), with the goldens `14_TESTING` names:** `FrameTimeSeries` (frame times from QPC, gaps excluded), `Percentile` (linear), `FrameStatistics` (median / lows / min / max / σ with the sufficiency guards), `RollingMedian` + `StutterDetector`, `FgWindow` + `FgRefusal` (the factor and every refusal, as facts — the English lives with the report), `UpscaleExtent`, `SegmentBuilder`, `RtVerdict` / `HdrVerdict` (the tri-states), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates`. They consume `FrameSample` and `WriterFacts` — Domain's own types, since Domain references nothing — and `Application.Metrics.FrameSampleMapper` is the one place a shared-memory record becomes one; the Domain enums are pinned to `FrameLedger.Shared`'s in both directions by `MetricEnumMirrorTests`. The frame-generation LADDER (rung 0 / 1 / 3 / 4 as a verdict, and the withheld `none`) is not yet a Domain type: it is still the capture host's prose in `MeasuredFacts`, and lands with the recorder that stores `fg_mode` (PR-D).
**Single source of truth** for every number FrameLedger displays. ~~Implement in `FrameLedger.Domain.Metrics` with golden tests (`14_TESTING`).~~ **Implemented in `FrameLedger.Domain.Metrics` since 2026-09-09 (P2 PR-A), with the goldens `14_TESTING` names:** `FrameTimeSeries` (frame times from QPC, gaps excluded), `Percentile` (linear), `FrameStatistics` (median / lows / min / max / σ with the sufficiency guards), `RollingMedian` + `StutterDetector`, `FgWindow` + `FgRefusal` (the factor and every refusal, as facts — the English lives with the report), `UpscaleExtent`, `SegmentBuilder`, `RtVerdict` / `HdrVerdict` (the tri-states), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates`. They consume `FrameSample` and `WriterFacts` — Domain's own types, since Domain references nothing — and `Application.Metrics.FrameSampleMapper` is the one place a shared-memory record becomes one; the Domain enums are pinned to `FrameLedger.Shared`'s in both directions by `MetricEnumMirrorTests`. The frame-generation LADDER (rung 0 / 1 / 3 / 4 as a verdict, and the withheld `none`) ~~is not yet a Domain type: it is still the capture host's prose in `MeasuredFacts`, and lands with the recorder that stores `fg_mode` (PR-D).~~ *(Corrected 2026-10-04: it landed with PR-D on 2026-09-10 as `Application.Recording.FgLadder` — in Application, not Domain. The session row (`SessionAggregator`), the live card (`SessionProgressCalculator`) and the capture host's report all read it; `MeasuredFacts` keeps only the host's strings.)*
Every metric declares which **capture tier** it requires (`01_ARCHITECTURE` §Capture tiers). A Tier-2 session simply has `N/A` where Tier-1 data is missing — never a silently degraded estimate presented as fact.
@@ -27,7 +27,7 @@ Let `D` = session duration (first → last present), `F_app` = frames the *game*
| **Native FPS (avg)** | `count(F_app) / D` | 1 |
| **Displayed FPS (avg)** | `count(F_disp) / D` | 1 |
| **Presented FPS (avg)** | `presents / D` — **numerically Displayed FPS; the name for the one number that stands alone.** "Native" and "Displayed" are printed only *together* (rule 6); when frame generation is not measured, this is the headline, with a mandatory qualifier (§Frame Generation, rung 0's qualifier) | 1 |
| **FG factor** | `DisplayedFPS / NativeFPS`, shown `×N.N`; `—` when FG inactive; **`N/A` when FG is not measured** — and **`N/A` when FG was *identified* but the count refused** (`fg_mode` a technology, `fg_factor` NULL, `fg_refusal` the reason — schema 0003, 2026-09-14): the one number is then Presented FPS with a warning chip naming the technology, exactly rung 0's third row, because the identity says generated frames may be in the presents and the count cannot say how many. Never `×0.0`, never "Native" | 1 |
| **FG factor** | `DisplayedFPS / NativeFPS`, shown `×N.N`; `—` when FG inactive; **`N/A` when FG is not measured** — and **`N/A` when FG was *identified* but the count refused** (`fg_mode` a technology, `fg_factor` NULL, `fg_refusal` the reason — schema 0003, 2026-09-14 — and `fg_refusal_detail` its numbers: the bucket that departed, its ratio and the window's — schema 0005, 2026-09-16): the one number is then Presented FPS with a warning chip naming the technology, exactly rung 0's third row, because the identity says generated frames may be in the presents and the count cannot say how many. Never `×0.0`, never "Native". **Since 2026-09-17 a session refused as `non_uniform` publishes its STEADY STATE instead** — `fg_factor_scope = steady`, the share beside it (§The steady state, below) | 1 |
| **Avg FPS** (headline) | = Native FPS when `fg_mode` is measured (`api` rung) or `none`; **= Presented FPS, labelled, when `fg_mode` is `N/A`**. Time-based, **not** the mean of instantaneous FPS values | 1 |
| **Median FPS** | `1000 / p50(ft_app)` | 1 |
| **1% Low** | `1000 / p99(ft_app)` | 1 |
@@ -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.
@@ -55,8 +58,32 @@ entirely rather than counted as one long frame. Including it would fabricate a
stutter — the exact artifact these metrics exist to detect honestly. Gaps count
toward the session's data-quality warnings.
> **Since beta.8 a pause is a gap, and a gap is not time either.** The Overlay records nothing while FR-3.9's pause
> holds, so the first record after the resume is QPC-apart from the last one before it by the whole pause: counted, a
> fabricated minutes-long frame in every statistic — the Overlay's own comment on its pause check (`MayObserve`) names that
> artefact — and paused minutes in every average. `CaptureSession` reads the QPC as it tells the ring to resume and marks
> a gap before the first record stamped at or after it (`CaptureSessionTests.TheFirstRecordPresentedAfterAResumeFollowsAGap`,
> red before the fix). And **`D`, the time base of every average, is the time the kept intervals span** — first to last
> present less every interval a gap sat in (`FrameTimeSeries.MeasuredSeconds`, `FgWindow.Seconds`): Presented FPS is
> the kept intervals over the seconds they span, and Native / Displayed leave the gaps out of their seconds too. For
> lost records this reads the survivors' rate (a drop is the Agent falling behind, not the game) where it read the
> survivors spread over the lost time — a rate nobody measured; with no gap nothing changes.
**Lows use application frames only.** Generated frames smooth display cadence but do not represent simulation stalls; mixing them hides real stutter. A secondary "Displayed 1% Low" is stored for the Displayed chart series but never replaces the headline.
> **And since beta.8 (2026-09-25) they are computed that way — until then they were not.** Where generated frames were
> counted (`fg_mode` a technology, or `active`), `SessionAggregator` took the median, the lows, min / max, σ and the stutter
> rule over every present of the dominant stream: the 1% low of a ×2 session sat above its native average, and on the
> owner's Onimusha demo capture (DLSS FG ×3, which submits each generated frame half a millisecond after its application
> frame) the stored median read **2,073 FPS on a 60 FPS game**. `ft_app` is now `Domain.Metrics.FrameTimeSeries.ApplicationFrames`:
> the interval between two consecutive presents that carried an application frame's token, the generated presents between
> them adding no interval of their own; a gap or a present that does not claim the count breaks the chain. The segments'
> lows follow; the Displayed 1% low stays over every present. **A technology named and no application frame counted**
> (`no_evaluations`, `not_counted`) has no frame statistic at all — N/A rather than a low over presents that include
> generated frames. Per-present attribution is accurate to one present (§Frame Generation); it was measured regular —
> application, generated, generated, repeating — on that capture. **Rows written before beta.8 keep their stored
> numbers**, as with the steady state (#198); their charts are drawn from the blob with the new rule.
> **When frame generation is NOT measured, the lows are taken over presents and labelled
> `(presented)`** — added 2026-09-03 with Presented FPS. On a title with no in-process frame
> generation that is exactly the application-frame low; on one that generates frames through a
@@ -66,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`:
@@ -369,13 +431,118 @@ F_app = Σ fgEvaluations (APPLICATION frames, counted at the
> its verdict on the line under the ratio so the number cannot be read without it. A guard keyed
> on a quantity that is zero on the route that runs is not a guard.
>
> ### The steady state — owner decision 2026-09-17
>
> **The refusal was right and its consequence was wrong.** A session that ran its menus at ×1 and its gameplay at
> ×4 averages to a number no configuration had (Black Myth: Wukong, 2026-09-16: 2.22 over a session whose gameplay
> read ×4.1 for two thirds of it), so the session-level factor is refused — and until this date the gameplay's own
> number was thrown away with the average. Every real play session opens with a splash, a menu or a loading screen,
> so on the owner's machine the shipped Agent published a factor on **one hooked session in nine** while the live
> card, which looks at five seconds at a time, showed it throughout; the owner read that as a broken data path. It
> was not: the nine sessions' stored per-frame counts read **2.00 / 3.00 / 4.00 to two decimals** inside gameplay.
>
> **The rule.** When — and only when — the session-level factor is refused as `NonUniform`, `FgSteadyState` cuts the
> claimed span into **five-second windows (the live card's own)**, classifies each by its own `presents ÷ tokens`,
> and takes the set of ACTIVE windows (≥ 1.5) agreeing within **10 %** that holds the most time. It is published when
> it covers **≥ 10 s and ≥ 10 % of the presenting time**: `fg_factor`, `native_fps` and `displayed_fps` are that
> state's own (counted over its windows, independently), `fg_factor_scope = 'steady'`, `fg_steady_share` the fraction,
> and `fg_refusal` / `fg_refusal_detail` stay set as the reason the number is not session-wide. ×3 and ×4 are 25 %
> apart and never pool; a factor that wanders forms no state and the refusal stands alone; any other refusal
> (unattributed, saturated, interleaved streams) gets no steady state — slicing does not make a record set
> trustworthy. **Never a session average, and never shown without its share.** Replayed over the nine sessions:
> 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` is **10 %**, the steady state's own, down from 25 %: at 25 % a
> session that ran ×3 then ×4 published 3.69, and the owner's one published session read ×2.04 because its opening
> bucket (2.35) sat inside the tolerance while its gameplay read 2.00 — tightening was unaffordable while a refusal
> meant no number, and is free now. And **`MultipleStreams` refuses only when the chains' samples INTERLEAVE**:
> the hazard is a process-wide drain word with two chains presenting at once, and Onimusha recreates its swapchain
> on entering gameplay — chain 1 for the menus, chain 2 after, not one sample interleaved in three sessions — which
> is one stream at a time and was refused as two.
>
> **This also leaves §RT/PT/RR without a settled denominator.** `rt_frame_pct`,
> `rays_per_pixel` and the `≥ 5% of frames` gate are per-APPLICATION-frame quantities, and
> dividing them by presents dilutes each by the frame-generation factor — at ×4 a title that
> path-traces every application frame reports 25%. Whoever writes the RT hooks must choose a
> denominator and state it here.
>
> *(Settled 2026-08-20 with the RT hooks — §RT/PT/RR, "The denominator": `rt_frame_pct` is a share of presents
> and says so, and the tri-state is unaffected. Marked here 2026-10-04.)*
`fgEvaluations` is recorded per present by the NGX/Streamline/FFX/XeSS FG hooks
> ### 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.
>
> **Amended 2026-10-19 (beta.26): a window needs application frames, and a ratio frame generation can produce.**
> "≥ 8 samples and tokens" was built as eight presents and ONE token, and the owner's Silent Hill 2 session listed a
> ×1336.0 state — the session's first ten seconds, the game compiling its shaders, presented with one token per window
> (`spike-notes` §22); the DLSS line cited it. A window is now read only with ≥ 8 presents AND ≥ 8 application frames (`FgSlices.Slice.IsReadable`, both
> active and *no frame generation*), and is active only up to **×8** (`FgWindow.GenerationCeiling`: no shipping
> technology generates more than five frames per application frame, DLSS 4.5's ×6); every other window is *not
> classified*. The steady state reads the same windows, so it can no longer pick such a stretch either. A session-wide
> or live ratio that held above ×8 is refused as **`beyond_generation`** (after uniformity: a session that changed
> state stays `non_uniform` and keeps its steady state and its mix). **A stored mix is read by today's rule**
> (`FgMixRecord.Parse`): a row above ×8, or whose windows averaged fewer than eight application frames, joins the
> not-classified time — so the session stored with the ×1336.0 row reads ×2.0, ×3.0, ×6.1, no frame generation and
> 30 s not classified, and its shares still add up.
>
> **Amended 2026-10-20 (beta.27): a state is near a whole multiplier.** Every frame generation that ships multiplies by
> a whole number — ×2 for FSR, XeSS and DLSS 3, up to ×4 for DLSS 4, up to ×6 for DLSS 4.5 — and its windows read near
> one: 1.98, 3.01, 6.06. The owner's Silent Hill 2 session of 2026-10-20 under the NVIDIA App's *Dynamic* mode listed
> a **×2.52** state for 12.8 s: windows in which the multiplier stepped between ×2 and ×3 read ×2.21–×2.70 — at 135 s,
> 251 application frames followed by one generated frame and 270 by two — and three of them pooled into a state nobody
> held (`spike-notes` §23). A window is now active only within **10 %** of a whole multiplier of two or more
> (`FgWindow.IsNearWholeMultiplier`: ×1.8–×2.2, ×2.7–×3.3, … ×5.4–×6.6); a window between two is *not classified*, and
> the steady state reads the same windows. A stored mix is read by the same rule (`FgMixRecord.Parse`): that session
> reads ×2.0 27.30 %, ×3.0 62.41 %, no frame generation 2.93 % and 7.36 % not classified. Of the 70 sessions in the
> owner's ledger copy it was the only stored row between two multipliers.
>
> **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, and since beta.26 a ratio beyond any frame generation) 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. *(2026-11-06, beta.34:
> the ceiling's decode held on the owner's Phantom Blade Zero — a ceiling of 5 held states up to ×6.0, a ceiling of 2
> nothing above ×3.0 — `spike-notes` §26. And the context line is no longer the only place the Dynamic mode shows: the
> DLSS line names DLSS 4.5 where the driver reports Dynamic applied, D83, `05_DETECTION` §DLSS generation.)*
`fgEvaluations` is recorded per present by ~~the NGX/Streamline/FFX/XeSS FG hooks~~ the `slGetNewFrameToken`
detour; where Streamline never issued a token, by the FidelityFX dispatches — new PREPARE `frameID`s, else UPSCALE
dispatches, the FSR 3.0 host's included *(corrected 2026-10-04: NGX and XeSS have no hook)*
(`17_HOOK_ENGINE` §Upscaling / frame generation). `fg_factor = F_disp / F_app`.
> **`fgEvaluations` counts EVALUATIONS, not generated frames — owner ruling, 2026-08-14 —
@@ -447,9 +614,40 @@ carries the three shapes.
## Upscaling — measured, not guessed (Tier 1)
> **The NVIDIA driver's overrides are a configuration, not a measurement (beta.8, 2026-09-25).** A session now also
> stores the driver profile its executable ran under (`sessions.driver_profile`: the NVIDIA App's DLSS, Ray
> Reconstruction and frame-generation overrides, read from the driver's settings store — never from the game's process
> 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.~~ *(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.
> *(Corrected 2026-10-20: it lacked them because the word stored had been read after the game closed — §The
> driver-reported rung. A session recorded from beta.27 keeps them; one recorded before, on a title no hook names, never
> reads the override's mode.)*
From the upscaler hooks we get, per frame:
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`) — from the API that was called, not from a DLL sitting on disk.
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`; **`fsr`** since 2026-09-04 — FSR through the SDK 2.x upscaler DLL, version not named) — from the API that was called, not from a DLL sitting on disk. *(Corrected 2026-10-04: `fsr` was missing here; `fsr4` is reserved and no writer produces it.)*
> **`dlss_rr` is NOT a value of this field, and this line listed it until 2026-08-06.** Layout
> v3 retired it and **reserved** the slot rather than reusing it, because it made Ray
@@ -460,6 +658,35 @@ From the upscaler hooks we get, per frame:
> the conflation the record had already removed.
- `renderW × renderH` vs `outputW × outputH` → **exact upscale ratio**: `sqrt((outW×outH)/(renW×renH))`, reported both as a ratio (`1.50×`) and a percentage (`67% render scale`).
- `upscalerQuality`: the vendor's own quality enum (DLSS Performance/Balanced/Quality/DLAA, XeSS quality setting, FSR preset), mapped to a display name per vendor in `Domain.UpscalerNames`.
> **`Domain.Metrics.UpscalerNames` exists since 2026-09-21; this line promised it from the start and the UI printed the
> raw integer until then.** It holds ONE table because one producer exists: `sl::DLSSMode` as the title chained it
> into `slEvaluateFeature` (1 Performance · 2 Balanced · 3 Quality · 4 Ultra Performance · 5 Ultra Quality · 6 DLAA;
> `eOff` and anything past `eCount` never reach a row). The ffx-api dispatch carries no quality and XeSS has no hook,
> so there is nothing of theirs to name. A value the table does not know is shown as stored. It names the MEASURED
> byte only — a label derived from the render/output ratio is `HANDOFF` §7a's owner decision, still not taken.
> *(Corrected 2026-10-19, beta.25: the ffx-api dispatch still carries no quality, and FSR's mode now comes from the
> vendor's own query — the next note. XeSS still has no hook.)*
> **A second producer since beta.25 (2026-10-19, owner decision D65): FSR's mode, from the vendor's own query.**
> `FfxApiUpscaleQualityMode` is an input to `ffxQuery`, which a title calls before it sizes its targets — "what
> render size (`…GETRENDERRESOLUTIONFROMQUALITYMODE`) or ratio (`…GETUPSCALERATIOFROMQUALITYMODE`) does this mode
> give at this display size?" — never to the per-frame dispatch, which carries the size alone. The Overlay hooks
> `ffxQuery` on the four modules it hooks `ffxDispatch` on (`17_HOOK_ENGINE` §Hook inventory), keeps each answer the
> vendor returned (one slot per mode), and an UPSCALE dispatch whose `renderSize` (and `upscaleSize`, where the title
> states it) fits exactly ONE kept answer — a size answer exactly, a ratio answer within one pixel of
> `display / ratio`, the vendor truncating and an engine perhaps rounding — publishes `0x10 + mode`: 16 Native AA ·
> 17 Quality · 18 Balanced · 19 Performance · 20 Ultra Performance (offset so FSR's Native AA, 0, can never be read
> as Streamline's `eOff`). No fit, two fits, or no query seen → `0xFF`. **A session, its segments and the live card
> read one rule (`Domain.Metrics.QualityByte`)**: the most common told byte, and for FSR none when any FSR record
> was rendered at a size no FSR-named record has. A dynamic resolution still matches an answer at the top of its
> range, so the plain modal would name a mode the session mostly did not render at; `legal/ACCURACY.md` promises
> none ("FSR at a dynamic resolution among them — no mode is shown"). A "not told" record at a named size — a
> present that drained a frame-generation PREPARE alone, a frame before the title asked — is not that evidence. A
> title that sizes its targets without asking, or asked before the Overlay was loaded, reads none: the honest
> answer, not a gap. `Domain.Metrics.UpscalerNames` decodes the byte for the `fsr`, `fsr3` and `fsr4` tokens.
> Measured on the hook harness with the vendor stub answering as the SDK documents (`fl_guard` "FSR's quality
> mode", by size through the SDK 2.x loader and by ratio through the 1.1.x monolith); a real title is owner-only
> item 21 (Lies of P at Quality, then Performance).
- Resolution changes mid-session (user changed settings, or dynamic resolution scaling) produce **segments**: the session stores a segment list `(startFrame, renderW/H, outputW/H, upscaler, quality)`. Aggregates report the dominant segment plus a "settings changed during session" flag — averaging across a settings change is the classic way benchmark numbers become meaningless.
> **Two segmentation axes exist, they compose in ONE order, and neither document said so until
@@ -502,7 +729,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`
@@ -515,6 +744,34 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`.
> than resolved*. Beside an `N/A` with the bit clear it prints the driver's negative, attributed, which
> says nothing about FSR or XeSS. **The negative is owed** (§H5): a title with DLSS switched off should
> read the bit clear; if it does not, the rung is withdrawn.
>
> **The App states the rung since 2026-09-21; until then only the capture host's console did.** The Agent has written
> `sessions.upscaler_driver_reported` since P2, and nothing under `FrameLedger.App` read it, so every NGX-direct DLSS
> title read "Unknown upscaler" in the library while FSR — whose dispatch the hook does see — was named (the owner's
> report). `Formats.Upscaler(token, quality, driverReported)` is the ladder in one place: a hook's name outranks
> everything and takes its measured preset; where no hook named one (`unknown`, or no claim) and the driver reports the
> feature, the text is **`DLSS (driver-reported)`** — attributed, identity only, never a quality even when a byte is
> on the row; otherwise the token's own text, and `unknown` now reads "Upscaler not identified" (a hook ran and saw
> nothing — which is what it means — rather than "Unknown upscaler", which read as a product). The live card gets the
> same word through `SessionProgress.upscalerDriverReported` (`07_IPC`). Segments carry no driver word: the driver's
> 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.
>
> **Corrected 2026-10-20 (beta.27): every stored word had lost the rung.** The loop asked the driver once more after its
> last drain — on a session that ended because the game closed, after the game had gone — and that answer, the last,
> was the state (`NgxDriverState`: "the last ANSWERED reading is the state"). The driver still answers for the pid,
> with `CREATED | EVALUATE` cleared: Expedition 33 read `0x8067F` while it ran (2026-09-06) and its stored sessions
> `0x8007F`, the same word without the two bits. Of the 14 sessions in the owner's ledger copy in which the driver
> answered, none kept them — so no stored session reads *DLSS (driver-reported)*, and none on an NGX-direct title under
> an NVIDIA App override reads its mode (D63). Since beta.27 the driver is not asked once the game has gone, and the
> two bits stand once a reading carried them: a game releasing its features on its way out no longer unsays them, and
> every other bit is still the last reading's. Sessions recorded before keep what they stored (`spike-notes` §23).
**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
@@ -600,15 +857,147 @@ Derived extras (Tier 1): `rays_per_pixel` (mean dispatch volume ÷ output pixels
> 2026-08-20 `maxTraceRecursionDepth` has no producer: `CreateStateObject` is a separate PR,
> and `pt_confidence` reads it, which is one of the reasons Path Tracing is still `N/A`.
## Per-process VRAM (Tier 1)
## Display mode — both tiers (beta.10)
`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).
**Owner request, 2026-09-27:** "detect the game's window size and whether it runs full-screen, borderless or windowed,
and how much of the time". Schema 0016 (`06_DATA_MODEL`), shared-memory region 4 (`07_IPC`, layout 4), the Agent's
`Application.Capture.DisplaySampler`, Domain's `Display.DisplayModeClassifier` and `Display.DisplayTally`.
**Two witnesses, and neither reads the game.**
1. *The swap chain's own answer* — Tier 1, DXGI only. The Overlay asks `IDXGISwapChain::GetFullscreenState` and `GetDesc`
on the chain the game passed to `Present`, at most twice a second per chain, and publishes the chain with the largest
back buffer in region 4: its window, back buffer, swap effect, and whether it is exclusive (`17_HOOK_ENGINE` §Hook
inventory — polled, not a `SetFullscreenState` hook). OpenGL publishes its window and client area with no exclusive
answer; the Vulkan layer publishes nothing yet.
2. *The window from outside* — both tiers. The Agent asks user32 about the game's top-level window: minimised or not, the
client area in screen coordinates, the monitor it is on and that monitor's refresh rate — per-monitor DPI aware while it
asks, because the Agent runs DPI-unaware and Windows would otherwise scale another process's coordinates
(`Infrastructure.Display.WindowGeometryProbe`). The window is the one region 4 names when it still belongs to the game
(a handle is reused once its window is gone), else the largest visible, uncloaked, non-tool top-level window of any
process running the game's executable — found by image path in the watcher's snapshot for a Tier-2 session that never
opened the process. This is the focus sample's class of question: CLAUDE.md rule 4 is about game memory, and no handle
to the game's process is opened for it.
**The ladder, per sample** (`DisplayModeClassifier`):
| Mode | When | Column (ms) |
|---|---|---|
| No window | no window could be read and the chain did not say exclusive | `display_nowindow_ms` — outside every share |
| Minimized | the window is minimised | `display_minimized_ms` |
| Exclusive fullscreen | a region-4 sample under 2 s old in which the swap chain SAID exclusive | `display_exclusive_ms` |
| Borderless | the client area covers its monitor (±1 px each edge) and the chain said not exclusive | `display_borderless_ms` |
| Fullscreen or borderless | the client area covers its monitor and nothing could say which — OpenGL, Vulkan, every Tier-2 session | `display_covers_ms` |
| Windowed | anything else | `display_windowed_ms` |
**Time, not ticks.** A sample stands for the wall time until the next: every drain tick (100 ms) hooked, every hold tick
(1 s) at Tier 2 — so the two add up in one unit, milliseconds. An interval that ends on a paused tick is dropped, which
excludes a pause to within one tick at each edge, as the frame series' gap does. A mode's **share** is its milliseconds
over the observed time (every mode but *No window*). `display_changes` counts samples whose mode differs from the one
before, no-window samples skipped. The sizes — `display_window_*` (client area), `display_buffer_*` (back buffer),
`display_monitor_*` and `display_monitor_hz` — are the ones seen in the mode that lasted longest *(corrected 2026-10-20,
beta.27: the last ones a sample of that mode SAW — a game leaving exclusive fullscreen closes its window while its swap
chain's last word is under 2 s old, and those last samples, exclusive with no window, had replaced every size: two Lies
of P and three Dark Souls III sessions stored none. A mode no sample of which saw its window keeps the back buffer
alone)*; `display_source` is the
strongest witness any sample had (`swapchain` > `opengl` > `window`). `sessions.swap_effect`, a column since 0001 with no
writer, is written from region 4.
**What it cannot say** (the user-facing list is `LIMITATIONS.md`):
- *Exclusive* is what the game asked DXGI for. Windows may still present such a game through the compositor ("fullscreen
optimizations"), and a flip-model borderless window may be promoted to independent flip; neither is visible without a
trace session, which FrameLedger does not have (`20_OPEN_QUESTIONS` §G).
- A game's menu may call a borderless window "Fullscreen"; the swap chain's answer is what is reported.
- A minimised game issues only occlusion probes, which the hook drops before sampling: a region-4 sample older than 2 s
keeps its window and loses its exclusive bits.
- Tier 2, OpenGL and Vulkan can never tell exclusive from borderless. Their covering time is *Fullscreen or borderless*,
and the trend draws no exclusive or borderless point for a session with any of it.
- A session recovered from its `.partial` file has no display facts — the tally is not in the crash file — and reads
N/A. The focus pair, which the partial carries, is the precedent this does not follow.
**A side effect of region 4's poll (layout 4).** `GetDesc` every 500 ms also refreshes the chain's output size, which
catches a `ResizeBuffers1` the hook inventory does not have: a title that resizes through it now splits its segments at the
change and reads "settings changed mid-session" (FR-6.4), which is what it was.
**Where it is shown** (`08_UI`): the session summary's Display card and line, the game page's last measured session and
its Sessions column, three Trend metrics — *Exclusive fullscreen share %*, *Borderless share %*, *Windowed share %*, every
tier, and a mode switch is not a mid-session change for them (switching resizes the swap chain; the share is what that
switch was) — three Compare rows, never ranked, and the CSV's `# display:` line (§Export schema) and the JSON's aggregates.
## Game process memory — both tiers (beta.12, owner decision D43)
**What is measured since 2026-10-03:** the game process's own memory, read from OUTSIDE the game once a second by the
Agent through `FrameLedger.ProcessStats.dll` (`18_GPU_VENDOR_APIS` §The game process's memory) — never from the game's
memory (CLAUDE.md rule 4):
| Figure | Source | What it is |
|---|---|---|
| **Dedicated GPU memory** (`game_vram_dedicated`) | PDH `\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated Usage`, every instance naming the pid summed | the number Task Manager's Details tab shows under that name |
| Shared GPU memory (`game_vram_shared`) | the same counter set's `Shared Usage` | system memory the GPU uses on the game's behalf |
| **Memory — private working set** (`game_ram_private`) | `GetProcessMemoryInfo`, `PROCESS_MEMORY_COUNTERS_EX2.PrivateWorkingSetSize` | Task Manager's "Memory" column; N/A on a Windows that predates EX2 (Windows 10 22H2 / 11 22H2 without the September 2023 update) |
| Working set (`game_ram_ws`) | `WorkingSetSize` | the whole working set, shared pages included; what the card falls back to where the private working set is N/A |
| Commit (`game_commit`) | `PrivateUsage` | private memory committed, resident or not |
**Which process.** A hooked session — and any session refused after the loop pinned the process — reads the pinned pid
through the handle the session already holds (`SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION`). An unpinned Tier-2 hold
(hooking off, blocked, unresolved, cannot pin) reads **every process running the game's executable** in the watcher's
snapshot, each opened for the read with `PROCESS_QUERY_LIMITED_INFORMATION` and closed after it, and SUMS them; a process
whose creation time is not the snapshot's (a reused pid), or that refuses even that right, is left out of both halves.
`game_memory_processes` says how many were summed. Child processes of another executable (a launcher, a crash handler, a
web view) are not counted.
**Dedicated is not the DXGI budget model's "local usage".** dwm.exe read 858 MB dedicated against 310 MB local at an idle
desktop, and a test process holding a buffer read 4.5 MiB more dedicated than its own `QueryVideoMemoryInfo(LOCAL)` at
both 8 MiB and 512 MiB (`spike-notes` §16, M3) — a constant per-device amount, not one that grows with the game's
allocations. So dedicated is defined as Task Manager's column and is **never compared with a budget**: the budget and
`budget_exceeded_pct` stay unmeasured (`20_OPEN_QUESTIONS` §M11), and `vram_proc_*` / `vram_budget_exceeded_pct` /
`FlFrameRecord.vramUsedMb` stay reserved for that in-process figure.
**Aggregates** (schema 0018): dedicated avg / median / max, shared max, private working set avg / median / max, working
set max, commit max, the process count, the sources (`counters,ex2,ex,held,opened`), and every series' n / mean / median /
min / max in `sensor_stats_json` (§Sensor aggregates). MiB stored; shown in GB as Task Manager does (1 GB = 1024 MiB).
> **The paragraph below is the design that was never built, kept as it stood** (struck 2026-10-03: the Overlay never
> called `QueryVideoMemoryInfo` — `dllmain.cpp` lists `FL_MEASURED_VRAM` as unproduced, §H10 never settled where in the
> game to call it — and D43 chose the outside read instead).
~~`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).~~
## Sensor aggregates
Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline aligned to the frame timeline via the shared QPC epoch captured at session start. Fields with no data are `N/A`, never 0.
Per session over 1 Hz samples: `avg` (mean of non-null), `max` — and since beta.12 the `median` (the linear-interpolation
50th percentile: the middle sample of an odd count, the mean of the two middle ones of an even count) and the `min`
(`Domain.Metrics.SeriesAggregates`). Every stored series' n / mean / median / min / max is written once at finalize to
`sessions.sensor_stats_json`, so the summary's statistics read stored values and outlive a retention sweep of the raw
series. Sensor timeline aligned to the frame timeline via the shared QPC epoch captured at session start. Fields with no
data are `N/A`, never 0.
## Accuracy budget (shown in Help → About metrics)
**The card's clocks and limits (beta.14, D49), both tiers.** The core and memory clock (MHz), the fan (RPM) and the
memory temperature were in the samples before (L2 reads them, L3 too) and stored nowhere; they are series now
(`gpu_core_clock`, `gpu_mem_clock`, `gpu_fan`, `gpu_mem_temp`) with `avg_gpu_core_clock_mhz`, `avg_gpu_mem_clock_mhz`,
`avg_gpu_fan_rpm` and `max_gpu_mem_temp`. **What held the card back** is NVAPI's perf-decrease reasons
(`GpuSample.ThrottleReasons`, L3 only): `gpu_power_limit` / `gpu_thermal_limit` read 100 on a tick whose reasons include
the power limit (`0x2`) / thermal slowdown (`0x1`) and 0 on one whose reasons do not, so their mean — `power_limit_pct`,
`thermal_limit_pct` — is the share of ticks held back. A card no layer reports reasons for (every card but NVIDIA's) has
no answer: N/A, never "not limited". `throttle_pct` (any reason) is unchanged.
## Efficiency (beta.14, D49)
`app_frames_per_joule` = the application frame rate ÷ the card's average board power — FPS per watt, frames per joule.
**Never the displayed rate** (rule 6): a generated frame costs the card a fraction of a rendered one, and counting it would
sell frame generation as efficiency. The application rate is known when frame generation was counted over the session
(Native FPS; a counted `none` makes it the presented rate), or when no frame-generation runtime was loaded
(`presented_qualifier = no_fg_runtime`). **Null** for `census_not_run`, `fg_runtime_loaded` and `none_withheld`, for a
session whose generation changed state (its steady state covers a share of the session, and the power is the whole
session's), without a power reading, and at Tier 2 (no frames). The power is the **graphics card's** — not the
processor's, not the whole PC's — averaged over the session's sensor ticks. `Domain.Metrics.EnergyEfficiency`,
`SessionAggregator.ApplyEfficiency`.
## Accuracy budget ~~(shown in Help → About metrics)~~
*(Corrected 2026-10-04: no such page exists. Users read these limits in `LIMITATIONS.md` (Help ▸ Limitations) and in
`legal/ACCURACY.md`, which it links.)*
| Quantity | Tier 1 | Tier 2 |
|---|---|---|
@@ -617,10 +1006,17 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline
| Upscaler + render resolution | **exact** (vendor API arguments) | not available |
| RT active | measured per frame | not available |
| Path tracing | heuristic, confidence-scored, never asserted | not available |
| Per-process VRAM | exact | not available |
| ~~Per-process VRAM~~ Game process memory (beta.12) | ~~exact~~ dedicated / shared GPU memory as Task Manager counts it — a known 512 MiB allocation read +512.0 MiB (`spike-notes` §16); private working set equal to Windows' own counter; read from outside the game | ~~not available~~ the same, from outside; an unpinned hold sums the executable's processes |
| PC latency | as reported by Reflex | not available |
| Display mode (beta.10) | per 100 ms sample: exclusive fullscreen as the swap chain answers it (DXGI; OpenGL and Vulkan cannot say), borderless, windowed, minimised; the window's size from user32 | per 1 s sample, from the window alone: windowed, minimised, or *fullscreen or borderless* — never split |
| GPU temp / load / power | vendor API accuracy, ±1 s sampling | same |
| CPU temperature | sensor-inherent ±1–2 °C, needs LHM + PawnIO + elevation | 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 |
> **The Tier-2 column is now "not available" for everything except sensors, and that is the whole change.** It previously claimed frame times within 0.1% without injection. Nothing produces them.
@@ -640,13 +1036,13 @@ Per-column sources, and what a *Tier-2* export does instead:
| Column | Tier-1 source | Tier 2 |
|---|---|---|
| `frame_index`, `qpc_ms`, `frametime_ms` | `frametimes` blob + session `qpcEpoch` | ~~from CSV~~ — no Tier-2 CSV exists; a Tier-2 session exports no per-frame rows at all |
| `native_or_generated` | `frame_flags` generated bit — set where `fgEvaluations == 0`, i.e. the presents that carried **no** application-frame evaluation. Inverted from the pre-2026-08-14 reading, and accurate to one frame per the note in §Frame Generation | `FrameType` (2.x) |
| `native_or_generated` | `frame_flags` generated bit — set where `fgEvaluations == 0`, i.e. the presents that carried **no** application-frame evaluation. Inverted from the pre-2026-08-14 reading, and accurate to one frame per the note in §Frame Generation | ~~`FrameType` (2.x)~~ — no Tier-2 CSV *(corrected 2026-10-04)* |
| `render_w/h`, `output_w/h` | `render_res` blob — **two `uint16` pairs per frame**, not one; `ResizeBuffers` is hooked precisely because output resolution changes mid-session | `N/A` |
| `upscaler`, `upscaler_quality`, `fg_mode` | segment table, joined by frame index | `N/A` |
| `rt_flags` | `rt_flags` blob, **one byte per frame** preserving all three bits (`asBuildObserved`, `dispatchObserved`, `psoCreatedEver`) — collapsing them to a single "rt-active" bit loses the inline-RayQuery distinction this project exists to measure. The third was `rtPsoAlive` until layout v3 renamed it: creation is observed at `CreateStateObject` and destruction is COM `Release`, which is not in the hook inventory and must not be added, so the bit latches and could only ever mean "created ever" | `N/A` |
| `dispatch_rays` | `dispatch_rays` blob (`uint32[]`, the volume) | `N/A` |
| `pso_created` | `pso_created` blob (`uint16[]`, the **count**, not a flag) | `N/A` |
| `vram_mb` | `vram_proc` per-frame blob. Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so | `N/A` |
| `vram_mb` | `vram_proc` per-frame blob. ~~Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so~~ **Corrected 2026-10-03: the Overlay never produced it, so the column has always been empty.** It stays in the list — the schema is fixed — and the header's note says so; the game's memory is the `# game_memory:` header line (beta.12, §Game process memory) | `N/A` |
| `reflex_latency_us` | `latency_us` blob; **finalize must write it** | `N/A` |
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, hardware snapshot, segment list, the tri-state flags with their sources, and the note that `vram_mb` is 1 Hz-sampled. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, swap effect, **the display line** (beta.10: `# display:` with each mode's milliseconds, the changes, the source and the window / back buffer / monitor sizes, or `N/A` for a session recorded before — §Display mode; a mode is the session's, not a frame's, so it is not a column), hardware snapshot, segment list, the tri-state flags with their sources, ~~and the note that `vram_mb` is 1 Hz-sampled~~ **the game's memory** (beta.12: `# game_memory:` with the dedicated GPU memory's mean / median / max, the shared max, the private working set's mean / median / max, the working set's and the commit's max — MiB, invariant — the process count and the sources, or `N/A` for a session recorded before or one where nothing answered; the session's figure, read once a second, so a header line like the display's), and the note that `vram_mb` is the in-game figure this build does not produce. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
+169 -13
View File
@@ -22,6 +22,7 @@ public interface IFrameSource : IAsyncDisposable
> {
> FlWriterState WriterState { get; } FlShmHandshake Handshake { get; }
> long TotalDropped { get; } long TotalGaps { get; }
> FlDisplayState? DisplayState { get; } // region 4, beta.10 (added to this sketch 2026-10-04)
> DrainResult Drain(Span<FlFrameRecord> into, IList<ulong> gapIndices);
> void PublishGuardResult(uint completedEvaluations, bool unhookRequested);
> void SetPaused(bool paused); void RequestLogFlush();
@@ -38,7 +39,9 @@ public interface IFrameSource : IAsyncDisposable
> with `FlGuardBuildId`), `ITargetLivenessSource` (`HeldProcessLivenessSource`, §S29(e)),
> `ITargetResolver` (`TargetResolver`, path only — never a pid), `IProcessLauncher`
> (`ProcessLauncher`, launch mode), `IRuntimeModuleSnapshot`, `INgxDriverProbe`,
> `IExecutableMarkerScan`. `ShmRingReader` itself gains no interface and no second consumer
> ~~`IExecutableMarkerScan`~~ — **corrected 2026-09-27:** the marker scan is the recorder's, not the loop's; the loop's
> later ports are `IKillSwitch` (FR-2.4), `ICapturePauseSource`, `IUserModeExceptionSwitch` and
> `IOverlayToleranceChannel` (D33) and `IDisplayProbe` (beta.10). `ShmRingReader` itself gains no interface and no second consumer
> (`NoSecondRingReaderTests`). A **pure move**: the loop's ordering rules, its tests and the
> capture host's report are byte-for-byte what they were; the host is now a thin shell that
> composes the same objects. What the table below used to call `HookedFrameSource` is this.
@@ -74,6 +77,32 @@ promises.** It is stated here, in `README` §Capture tiers and in `03_METRICS`
frame times without injection and a reader who remembers that will otherwise assume
it still holds.
> **Built 2026-09-22 — until then Tier 2 did not exist in practice.** Every refusal returned from
> `CaptureSession` within about a second and `SessionFinalizer`'s 30 s minimum discarded the row, so the
> table above described a tier no session had ever reached (the owner's log: `Discarded (tier 2, exit=Normal,
> frames=0)` for every refusal). Now the loop **holds** a refused session open — `HoldUnhookedAsync`, one tick
> per `CaptureOptions.HoldInterval` (1 s), each tick draining the telemetry poller through the observer as a
> hooked session's ticks do — until the target exits, the user stops it or `MaxDuration` runs out. The clock is
> the pinned liveness when the loop holds a pin, and ~~the executable's NAME~~ **the executable's image path in the
> watcher's own 1 Hz snapshot** (`ITargetResolver.IsRunning` over `LatestProcessSnapshot`, 2026-09-23; a process
> whose path could not be read still counts by its name; the console verbs, where nothing polls, keep the name
> list) when it never opened the process — by name, another game's `Game.exe` held an RPG Maker game's session
> open. Nothing about the hold touches the target, and no process is opened for it. *(Corrected 2026-10-03, beta.12, D43:
the hold now reads the game's own memory, once a second, by opening each process running the executable with
`PROCESS_QUERY_LIMITED_INFORMATION` for the read and closing it after — the right the watcher's own snapshot already uses
on every process each second; nothing is held, nothing is injected, and the memory's contents are never read. Its video
memory comes from performance counters that need no handle at all; `03_METRICS` §Game process memory.)* **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
> first, and a row whose hooking is off — merely added, blocked by a finding, auto-disabled — goes straight to
> the hold with `RefusedHookNotEnabled` (its verdict is the row's block when it has one, `PreviouslyBlocked`).
> The resolver used to run first, and a hooking-off utility that runs elevated (Borderless Gaming, imported from
> Steam) was reported as a process an anti-cheat driver protects, with the notice that sentence deserves.
> `TargetNotRunning` alone returns at once — there is nothing to hold. Launch mode's two guard refusals
> (`LaunchTargetExited`, `LaunchNoPresentationRuntime`) return at once too, because the descendant election
> is waiting on them. The unshipped operator host sets `HoldUnhooked = false`: to an operator a refusal is the
> answer and the exit code. The discard rule is unchanged: a Tier-2 row under 30 s is still dropped, which is
> now a game that ran under 30 s rather than every refusal. `PartialRecovery` no longer reads a tick as proof of
> a hooked session — a held session flushes ticks with no records and no `attached` note.
**The reason is the payload of Tier 2**, not a consolation attached to it. A session
that records duration and sensors while saying nothing about *why* it measured
nothing is indistinguishable from a broken capture. `sessions.capture_notes` and the
@@ -103,7 +132,8 @@ which makes the notification more important than it was, not less.
## Process watcher
- 1 Hz snapshot via `CreateToolhelp32Snapshot` (CsWin32): pid, ppid, exe path (`QueryFullProcessImageName`).
- Watchlist match on normalized full path (`GetFinalPathNameByHandle` — junctions/symlinks), filename fallback with a stale-path warning badge.
- **One spelling of the exe path for the whole capture path (beta.33).** The watcher keys a game on the kernel's image name (`QueryFullProcessImageName`), and `TargetResolver`, which re-finds the game just before the guard, read the loader's (`Process.MainModule`) until beta.33: for a game started through a junction — a package Windows activates from `C:\Program Files\WindowsApps\<package>`, a junction to the game's own folder — the two could differ, and the session would end `TargetNotRunning` about a game the watcher had just matched. Both read `Infrastructure.Io.ProcessImagePath` now; the resolver still opens a candidate with the guard's own rights (`PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_VM_READ`), so a process an anti-cheat driver closes stays `TargetUnreadable` (D21). `spike-notes` §25 measured the two spellings equal on the owner's eleven Xbox titles; one reader keeps them equal by construction (`TargetResolverTests`).
- Watchlist match on normalized full path (~~`GetFinalPathNameByHandle`~~ `File.ResolveLinkTarget` *(corrected 2026-10-04 — `ExecutableIdentity` says why)* — junctions/symlinks), ~~filename fallback with a stale-path warning badge~~ **and a file name alone never starts a session (2026-09-23, HANDOFF D25): it can only be the entry's own executable on a drive that changed its letter (the relocator's rule), or it is not in the library.**
- Process tree assembled from ppid chains; the **capture target** is the descendant that actually presents. In launch mode we know it; in attach mode we wait for the first ring handshake. ~~or (Tier 2) elect the PID with the most presents in the first 10 s~~ — there is no Tier-2 present stream to elect from. Re-elect if the presenting PID dies while the tree lives (level-transition relaunches).
> **Built 2026-09-10 (P2 PR-F), in `Application.Watch` with one adapter.** `ToolhelpProcessSnapshotSource`
@@ -113,7 +143,31 @@ which makes the notification more important than it was, not less.
> both null so it can match nothing. `ProcessWatcher` diffs it against the watchlist — the `games` rows — on the
> normalised full path first and on the file name only when exactly ONE row carries it (`StalePath`, the
> "stale-path warning badge"; the session is keyed on the path the process actually runs from, so consent for the
> old path does not follow the binary). `ProcessTree` reads ppid chains with the one rule that defeats pid
> old path does not follow the binary — **unless it IS the same binary on a drive that changed its letter**, 2026-09-22:
> `CaptureOrchestrator.AdoptIfMovedAsync` asks `ExecutableRelocator` first, and when the row's file is gone and the
> running one has the row's size and mtime, the row is moved and the session is the row's, consent and all;
> `19_SAFETY` §A moved drive is the same executable). **Narrowed 2026-09-23 (D25): a `StalePath` match that is not
> adopted records NOTHING.** The stranger session was keyed on the real path and named after the matched row, and
> `SessionRecorder`'s `EnsureAsync` turned that into a new library entry with the other game's name: *HELLO, HELLO
> WORLD!*'s `swiftshader\Game.exe` became a second "Flower in Us" (the only entry named `Game.exe`), and its NW.js
> children, matching the new entry exactly, started a second session beside the first. Now the process is said once
> in the log ("not in the library, so nothing is recorded") and its exit is silent; the adopt itself accepts only the
> 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. *(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). *(beta.27,
> 2026-10-20:)* a launch never said it had ended on its own, so after **Play** ▸ *Start directly* nothing turned away
> while it ran was ever recorded — Lies of P hands itself to Steam within seconds, and twice on 2026-10-19 the game
> Steam started went unrecorded (`spike-notes` §23). A launch now says so, with the processes it and its election
> recorded: the one it started appears to the watcher after the launch began and is turned away like any other, and a
> launch the user stopped does not start again on it. **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
> needs its own record. `CaptureOrchestrator` is the `--serve` loop: one snapshot per second, ONE session per game
@@ -125,10 +179,27 @@ which makes the notification more important than it was, not less.
> (`05_DETECTION` §Caching) on its own task, because `GameFileProbe` blocks on file I/O and the 1 Hz poll must
> not wait on it. It reads game files and writes the detected columns of `games`; it never touches a process,
> a hook, or a consent column.**
>
> **The watchlist is the entries whose recording is on (2026-09-23, FR-1.6, D29).** Borderless Gaming starts with
> Windows on the owner's machine, and since Tier 2 exists every library entry that runs gets a session — one per boot,
> for as long as the utility ran, in the playtime totals. `games.record_sessions = 0` (schema 0009, the user's switch on
> the game page) takes an entry out of the watchlist `PollOnceAsync` hands the watcher, and out of the launch election's
> tracked set: its process appearing is no event, no session and no log line. Switched off while a session of it runs,
> the orchestrator cancels that session's stop token at its next poll — the loop ends as a user stop and saves what it
> had — and `LaunchGame` answers `RecordingOff`. Switched back on, a process that is still running is picked up by
> the next poll (a pid the watcher never matched is new to it). Detection and the drive-letter relocator still follow
> the entry; they read files, not processes.
## Launch mode vs attach mode
**Launch mode (preferred).** User starts the game from FrameLedger (or FrameLedger is set as the launch wrapper): `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
**Launch mode (preferred).** User starts the game from FrameLedger ~~(or FrameLedger is set as the launch wrapper)~~ *(corrected 2026-10-04: no wrapper exists, and no App button sends `LaunchGame` yet — the pipe command has no caller; launch mode runs from the Agent's developer verb `--console launch --exe`. Since beta.21 one does: **Play** set to *Start directly* — D59, `08_UI` §Games)*: `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
> **An elevated Agent starts the game as a standard user (beta.10, the admin mode, D34).** `ProcessLauncher` checks its
> own token: elevated, it starts the game with the desktop shell's token (`Infrastructure.Startup.UnelevatedProcess` —
> `GetShellWindow`'s process, its token duplicated, `CreateProcessWithTokenW`, the same explicit environment the kill
> switch decides), pins it from the start's own handle, and never falls back to its own token: with no shell the launch
> fails with `Launch_Error_1400`. `LaunchGame` is a pipe command any process of the user can send; an elevated launch would
> be an elevation without a prompt.
> **Built 2026-09-06 (P1 item 2) as "inject late", which is the only shape §S1 left possible, and the
> sentence above is kept as the intent it does not quite describe.** A `CREATE_SUSPENDED` target has
@@ -149,6 +220,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.
>
@@ -167,13 +243,15 @@ which makes the notification more important than it was, not less.
**Attach mode.** Game launched from Steam/GOG/Epic normally; watcher sees it, guard runs, inject. Feature hooks install late, so early-init facts may be missed; the Overlay compensates by re-reading state on the first `EvaluateFeature` call it does observe, and the session is flagged `late_attach = true` so the UI can note that startup-time settings may be incomplete.
Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).
> **A game the Xbox app or the Microsoft Store installed is always attach mode (beta.33, D80).** Windows starts it through its package — **Play** runs `explorer.exe shell:AppsFolder\<AUMID>` in either mode — and started by its path it is never the game in its package (`spike-notes` §25: `CreateProcess` of the launch executable makes Windows activate the package itself, so the game is not the launcher's descendant; of an Unreal shipping executable, the game runs outside its package). So `LaunchGame` for an executable whose install root is a GDK package root answers `PackagedGame` and starts nothing (`OrchestratorOptions.IsPackaged` = `GdkPackageFiles.IsInPackage`), the watcher records the game when it appears, and the session is `late_attach`: §25 measured an Unreal title's D3D device 2.4–3.7 s after its process, a Unity title's 0.1–1.2 s, so what ran before the hook is in `dxgiPresentsBeforeHook`. The Vulkan layer's switch (`FRAMELEDGER_ENABLE_VK_LAYER=1`) is set only by `ProcessLauncher`, so a Vulkan GDK title cannot get it (`20_OPEN_QUESTIONS` §G).
~~Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).~~ *(Corrected 2026-10-04: not built — there is no wrapper entry point and no UI text; a game started from Steam is recorded in attach mode. The parenthesis still holds: never modify a user's Steam config for them.)*
## The guard
The guard is **native** (`20_OPEN_QUESTIONS` §S13(a)) and the Agent reaches it through `IAntiCheatGuard`, a **thin P/Invoke facade over the single implementation** — never a second one. Two blocklist matchers that can disagree is a fail-open by construction: the day they diverge, one is wrong and nothing says which. Nothing managed parses rules or matches a blocklist, and a test asserts it (§S15 item 1).
The facade exposes exactly two operations, and neither hands out a clearance:
The facade exposes ~~exactly two operations~~ four *(corrected 2026-10-04: `GuardedInjectWhenReadyAsync`, launch mode's waiting entry, and `PreScanGameAsync`, the advisory checks 3–4 behind FR-2.2 and the library pre-scan, joined the two below; since D33 each takes `toleratedFamily`, a family name the guard resolves itself)*, and none hands out a clearance:
- `GuardedInjectAsync(pid, payload)` — runs every pre-injection check and, only on a pass, injects. There is no overload that skips the checks and no way to supply evidence; the guard collects its own, so a caller can ask but only the guard answers (§S13(b)).
- `EvaluateAsync(pid)` — the same checks with no injection, for the 30 s in-session re-scan. It cannot be used to pre-authorise anything: it takes no payload and returns no token, so acting on a pass means calling `GuardedInjectAsync`, which re-collects.
@@ -182,6 +260,18 @@ Its result is authoritative: no code path may inject without a passing check, an
What the Agent checks **before** asking the guard is the thing the native side structurally cannot see: **per-game consent** (CLAUDE.md rule 1). Consent is a record of something a human did, so `HookedCaptureGate` refuses an unconsented or un-enabled game without the guard ever being called.
> **The user-mode exception (D33, 2026-09-26) — one branch, and it only narrows.** A blocked game is refused
> `PreviouslyBlocked` before the guard is asked, as ever, UNLESS `HookRequest.FromConsent` found its exception in
> force: `hooking.usermode_ac_exceptions` on, a grant on the row made on the executable on disk, the block naming that
> family (`UserModeExceptionRules.CoveredFamily`) — and the session could publish the Overlay's channel
> (`IOverlayToleranceChannel`, `07_IPC` §D) BEFORE building the request. Then the gate hands the guard the family's
> NAME through the same entry (`GuardedInjectAsync` / `…WhenReadyAsync`), the guard decides whether to honour it and
> runs every check, and every 30 s re-scan names it again (`GuardSupervisor(guard, toleratedFamily)`). A blocked row
> whose exception does not apply is hooking-off before the process is opened, like any other. A hooked session under
> it is marked (`sessions.ac_exception_family`, `; ac-exception=<family>` in the notes), and a finding about the game,
> a safety unhook, the Overlay's own stop or a crash while hooked ends the exception (`UserModeExceptionLapsePolicy`,
> after the row is stored). `19_SAFETY` §The user-mode exception is the rule; this is where the loop applies it.
> **Where it lives, corrected 2026-08-06.** This sentence said "lives in SQLite", and was the
> only line in the tree that said where consent lives — while no database, no `games` table
> and no consent writer existed in any `.cs` file (§S27). The port is
@@ -234,6 +324,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
> **The PAIR, because zero is not a finding.** A process owning no top-level window at all — `hook-harness` presents to a composition swapchain and has none — is unfocused on every tick of every run. Reporting that as focus loss would fire on every integration run and teach the reader to ignore the line, which is the could-not-look/looked-and-found-nothing collision `FlRtTier` and `upscalerQuality` already exist to avoid.
>
> **It is attribution, never the guard.** What refuses a mixed window is `FgWindow.BatchRefusal`, computed from the records alone, so a caller that never wires focus still cannot publish an averaged ratio. Focus is what lets the report name the cause.
- **Each drain tick also samples the display mode (beta.10)** — `Application.Capture.DisplaySampler` on the same tick as focus: shared-memory region 4 (the presenting chain's window, back buffer, swap effect and exclusive state, as the Overlay last asked them) and the window's geometry from outside (`IDisplayProbe`, `Infrastructure.Display.WindowGeometryProbe`), classified and added up by the time each sample stood for; a paused tick drops the interval it ends. The last sample is closed before the last drain, and the tally rides out on `CaptureOutcome.Display`. **The Tier-2 hold samples too**, once per hold tick (1 s): the window only — by the pinned pid when the loop holds one, else by every process running the executable in the watcher's snapshot (`ITargetResolver.PidsOf`, image path only — never a name), still opening nothing. The recorder writes the tally on the row's skeleton, so both tiers store it (`03_METRICS` §Display mode, `06_DATA_MODEL` 0016).
- **Dropped records are computed here, not read from the header.** The Overlay has no reader index and cannot know whether a slot it overwrites was consumed. The Agent owns the read index, so it owns the accounting: when `writeIndex - readIndex > capacity`, add the excess to the session's data-quality counter and resume at `writeIndex - capacity`. A non-zero value means the Agent stalled for over ~16 s — log it, surface it as a session warning, never silently accept it.
> **That sentence is true only because the read index is seeded from the writer at
@@ -245,7 +336,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
> published at attach are counted separately as `RecordsBeforeAttach`; that is not
> a stall and must not raise this warning.
- **A torn record is a gap, not a skipped frame.** Silently dropping it merges two frame times into one double-length interval, i.e. fabricates a stutter. Record an explicit gap at that index; `03_METRICS` excludes gap-adjacent intervals from frame-time statistics.
- Records go into an in-memory buffer (`ArrayPool<FlFrameRecord>` segments). Every 60 s, a crash-safety flush writes raw buffers to `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`.
- Records go into an in-memory buffer (~~`ArrayPool<FlFrameRecord>` segments~~ a `List<FlFrameRecord>` — corrected 2026-10-04). Every 60 s, a crash-safety flush writes raw buffers to `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`.
## Threading model
@@ -254,7 +345,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
| Thread | Cadence | Owns | Touches |
|---|---|---|---|
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground per tick, drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground and the display mode per tick (beta.10), drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
| **Telemetry** (`fl-telemetry`, `TelemetryPoller`, one per session) | 1 Hz, never faster than 500 ms | Its own `ConcurrentQueue` of `TelemetrySample` | Reads the composite source only; L2 has a thread of its own inside the library, and the composite is read from this thread and no other |
| **Watcher** (built 2026-09-10, PR-F: `CaptureOrchestrator.RunAsync` on a `PeriodicTimer(1 s)`) | 1 Hz process snapshot | The watcher's events and the running-session table — ~~`PollOnceAsync` is their only writer; there is no `Channel`, because there is no second consumer~~ **since 2026-09-13 (P3 PR-1b) the table has one lock**: `PollOnceAsync` on the timer, `LaunchAsync` and `StopSession` from the pipe's tasks (HANDOFF §P3 D12 as built — two commands do not justify a channel); the sessions themselves never take it | The `games` rows (one read per poll) and never the ring; each session it starts runs on its own task |
| **Finalize** (PR-D) | Once, on the session loop's task | The one SQLite connection, behind a `SemaphoreSlim(1)` | `ApplicationStopping` cancels the loop; finalize gets a grace window, then the `.partial` stays for recovery |
@@ -270,9 +361,15 @@ than a tuning knob. ~~There is no UI thread in P2; the pipe reader (P3) joins as
the pipe's tasks touches the ring or the recorder, and the session loop never waits on a client. The command half (PR-1b) is the
`Channel` producer this sentence anticipated.
> **The pause is a gap (beta.8).** FR-3.9's pause stops the Overlay recording; the loop reads the QPC as it tells the ring
> to resume (`ApplyPause`, before `SetPaused(false)`, on the Overlay's own clock — `Stopwatch` is `QueryPerformanceCounter`)
> and marks a gap before the first drained record stamped at or after it (`MarkResume`). A record drained after the
> resume but stamped before it is a straggler the pause had not reached. `03_METRICS` §Data gaps says what a gap then
> does to the statistics and to `D`.
## Telemetry poller
1 Hz on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) + optional CPU sample when the Agent is elevated and PawnIO is present. Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
1 Hz (the session's `telemetry.interval_ms`, 500–2000 ms) on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) ~~+ optional CPU sample when the Agent is elevated and PawnIO is present~~ + *(corrected 2026-10-04)* the machine's reading on the same tick — CPU load and memory in use without elevation, CPU temperature only when elevated with PawnIO — and the game process's memory (beta.12, D43). Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
## Session recorder — state machine
@@ -317,6 +414,22 @@ because a layer cannot leave a running game's loader chain.
**Discard rule:** duration < min session length (default 30 s) → discard silently (log only).
> **A session whose entry was removed while it ran (2026-09-23).** Step 5 wrote under the id the session *started*
> with, and the owner's GIRLS' FRONTLINE 2 entry was removed — and re-imported — twice while the game ran: both
> sessions died on the foreign key (`session: FAULTED SqliteException: … FOREIGN KEY constraint failed`, 2026-09-22
> 23:26 and 2026-09-23 00:25), and each left a `.partial` whose recovery would have died the same way at the next
> start — stopping the host, because recovery ran before the watcher with no guard. As built:
> - **The owner is looked up, not assumed** (`ISessionRepository.ResolveOwnerAsync`, `FinalizeInput.ExePath`): the id
> the session started under when that row predates the session or holds its executable (an id SQLite reused for a
> later game is neither — `games.id` has no AUTOINCREMENT), else the row that holds the executable's path now (the
> re-imported entry), else **`GameRemoved`**: the user removed the game with its sessions and this was one of them.
> Nothing is written, the `.partial` is deleted, and the log says which. The write transaction re-checks the row, so a
> removal between the lookup and the insert is the same answer rather than the foreign key's exception.
> - **Recovery never throws.** A file it cannot finalize is set aside as `<guid>.partial.failed` (never retried, kept for
> a bug report) and reported `Failed`; the next file is recovered, and the watcher starts either way.
> - The Agent's host logs through Serilog since the same day: a background service that stops the host is now in
> `agent-*.log`, where before it was in no file at all.
> **Built 2026-09-10 (P2 PR-D): `Application.Recording`.** The state machine above is the intent; what
> runs is one class per box. `SessionRecorder` owns a session end to end — the row's identity and time
> base (`session_guid`, `qpc_epoch`/`qpc_frequency` from `TimeProvider.GetTimestamp`, which is QPC), the
@@ -342,9 +455,30 @@ because a layer cannot leave a running game's loader chain.
## Crash & exit classification
- Normal: presenting PID exit code 0.
- `crashed`: nonzero exit code, **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.
- 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~~ **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`.
@@ -361,10 +495,25 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
> exit code and the witness (`end=TargetExited; exit_code=-1073741819; crash_event=application_log`).
> `CrashAutoDisablePolicy` counts only crashes inside the 60 s window after the attach — `hook_crash_count`
> is that count and nothing else — and disables on the second; it never re-enables.
>
> **Corrected 2026-09-25 (beta.8, owner item 5): End task is not a crash.** The owner's sessions ended by Task Manager
> read *Crashed* — every non-zero code was one, and `TerminateProcess` leaves 1. A crash is now an exception's code or
> the event log's witness; any other code is `normal` with the code in the notes, and the session summary says it
> ("ended with exit code 1 — what End task and taskkill leave…", "crashed (0xC0000005 access violation)", "0xC0000006
> in-page I/O error: a disk or drive failed…"). **The safety policy did not get looser:** it takes the exit code beside
> the status and still counts every non-zero exit inside its window — a game the hook hung that the user then ended is
> the shape it exists for — and its row reason says "ended abnormally", not "crashed" (`19_SAFETY` §Crash & stability).
>
> **The notes' guard slot has three positions since the same day:** `guard=Reason|Family|Signal`, every slot present
> and `;` never inside one (`CaptureNotes.GuardSlot`). It was `Reason/Family/Signal` with an empty family dropped, so
> a refusal no family names put its signal where the family goes — and the notice read "Access is denied was detected
> in this game" — and a signal with a `;` was cut there. Old rows are read by the one rule that separates them: findings
> and the gate's own refusals carry a family, every other reason's second part was its signal. A launch that cannot
> start keeps Windows' reason (`launch_error=740`; `IProcessLauncher.Start(…, out win32Error)`).
## Live progress
`SessionProgress` at 1 Hz to the UI (`07_IPC`): rolling 5 s Native FPS, Displayed FPS, FG factor, current render→output resolution, upscaler + quality, RT active flag, GPU/CPU temp, per-process VRAM, elapsed. Suppressed when no UI client is connected. This is what makes the Dashboard live card genuinely useful — it is showing *measured* settings, not guesses.
`SessionProgress` at 1 Hz to the UI (`07_IPC`): rolling 5 s Native FPS, Displayed FPS, FG factor, current render→output resolution, upscaler + quality, RT active flag, GPU/CPU temp, ~~per-process VRAM~~ the game process's dedicated GPU memory and private working set (beta.12, from the newest telemetry tick — `SessionHeld` carries the same two for a held session), elapsed. Suppressed when no UI client is connected. This is what makes the Dashboard live card genuinely useful — it is showing *measured* settings, not guesses.
> **Built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D13): `Application.Ipc.SessionProgressCalculator`**, over the last 5 s of the
> ring's records through the same calculators the row uses — `FrameTimeSeries` for the presented rate, `FgWindow` + the FG ladder for
@@ -373,6 +522,13 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
> stands alone with the census qualifier (`FgLadder.PresentedQualifier`, the row's). CPU temperature is null until the Agent composes a
> CPU sensor, and every other unmeasured field is null, never 0. Rate-limited to 1 Hz inside the observer's `Tick`, computed only while
> a client is connected, and a fault in the computation is counted rather than allowed to end the session.
>
> **A held session is live too (2026-09-23).** The hold's ticks carry the refusal (`CaptureProgress.Held`, with the pid the loop
> holds, 0 for a hooking-off hold that never opened the process). The publisher's first held tick announces the session —
> `SessionStarted` at tier 2 with its `hold`, and the refusal's own event at once rather than when the game exits — and every tick
> after feeds `SessionHeld` (elapsed and sensors, nothing measured) at the same 1 Hz while a client listens. It is never run through
> `SessionProgressCalculator`, whose window over no records would still emit a qualifier. A session whose task faults now also
> completes on the pipe (`finalize: faulted`, `07_IPC`), so nothing is left shown as running.
## Overhead rules (NFR-1)
+353 -29
View File
@@ -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`) — and since beta.25 (D65) FSR's mode where the title asked FidelityFX's `ffxQuery` for the size it then dispatched, none at a dynamic resolution (`03_METRICS` §Upscaling) |
| 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) |
@@ -26,11 +26,20 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
| Reflex on + PC latency | NVAPI Reflex hooks |
| Per-process VRAM | `QueryVideoMemoryInfo` |
| PSO compilation events | pipeline-creation hooks |
| Display mode — exclusive fullscreen / borderless / windowed / minimised, with the window, back buffer and monitor (beta.10) | `GetFullscreenState` + `GetDesc` polled on the presenting chain (≤ 2 Hz, shared-memory region 4), and the window's geometry read by the Agent **out of process** — so this row is **both tiers**: a Tier-2 session has the window alone, and never splits exclusive from borderless (`03_METRICS` §Display mode) |
> **Not built, 2026-09-15:** four rows above have no writer yet — HDR output, Reflex and PC latency, per-process
> VRAM, and PSO compilation events. The Overlay never sets their measured bits, so every calculator over them
> returns nothing and the columns stay null; `legal/ACCURACY.md` lists them as not measured. This table is the
> design; the block is the state.
>
> **2026-09-27 (beta.10):** the first row's *swap effect* has a writer since schema 0016 — region 4's `GetDesc`, stored
> in `sessions.swap_effect` as a name (`flip_discard`, …) — and the display-mode row is new. **Present mode has none**,
> and the block above did not list it: `sessions.present_mode` is null on every row, and the pages say N/A.
>
> **2026-10-04 (beta.12, D43):** the per-process VRAM row's *usage* is measured — not by `QueryVideoMemoryInfo` but
> from outside the game, in both tiers, with the game's RAM beside it (`game_vram_*`, `game_ram_*`; `03_METRICS`
> §Game process memory). The in-game figure, its budget and `vram_proc_*` stay unbuilt.
> **"present-count delta" is removed from the FG row, and it was not merely unreliable —
> it was structurally zero.** `03_METRICS` §Frame Generation retired that rung on
@@ -42,11 +51,11 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
> stale-by-not-being-touched failure this project keeps recording; `06_DATA_MODEL`'s
> `fg_source` enum carried the same value and is corrected in the same pass.
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement.
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement. **The ~~one exception~~ exceptions** *(corrected 2026-10-04)* are how its window was shown (the display-mode row, beta.10) and the game process's memory (beta.12), which the Agent reads from outside the game in either tier.
## Static hints — rules engine
Rules are **data, not code**: `rules/detection-rules.json`, bundled and updatable from the repo (raw GitHub URL, ETag-cached; manual "Update detection rules" in Tools + weekly auto-check). Schema:
Rules are **data, not code**: `rules/detection-rules.json`, bundled ~~and updatable from the repo (raw GitHub URL, ETag-cached; manual "Update detection rules" in Tools + weekly auto-check)~~ *(corrected 2026-10-04: nothing fetches. The rules ship with the build and `RulesSeeder` installs them in `%LOCALAPPDATA%\FrameLedger\rules\`; Tools ▸ Update detection rules re-seeds from the copy beside the binary and wakes the detection and anti-cheat sweeps. A rules change reaches users with a release — `20_OPEN_QUESTIONS` §S20 feed half)*. Schema:
```json
{
@@ -59,9 +68,9 @@ Rules are **data, not code**: `rules/detection-rules.json`, bundled and updatabl
}
```
The `anticheat` block is the same file that feeds the hard guard in `19_SAFETY` — shipping it as updatable data is what lets a newly-protected game be blocked without waiting for an app release. **Rules updates that touch the `anticheat` block are treated as security updates:** applied on next check regardless of the user's auto-update preference for other rules.
The `anticheat` block is the same file that feeds the hard guard in `19_SAFETY` — shipping it as updatable data is what lets a newly-protected game be blocked without waiting for an app release. ~~**Rules updates that touch the `anticheat` block are treated as security updates:** applied on next check regardless of the user's auto-update preference for other rules.~~ *(Corrected 2026-10-04: there is no feed and no auto-update preference, so today a newly-protected game waits for a release; the sentence is what a feed must do once built, §S20.)*
Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`, `sibling_glob`, **`path_contains`**, `pe_company_contains`, `pe_product_contains`, `strings_contains` (bounded 8 MB scan), `manifest_field`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`.
Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`, `sibling_glob`, **`path_contains`**, `pe_company_contains`, `pe_product_contains`, `strings_contains` (bounded 8 MB scan), `manifest_field`, and since beta.33 **`root_file`** — an exact file name directly in the install root, answered from that one folder's own listing (`GameFileSnapshot.RootFiles`), so a deep walk that ran short makes its miss no less certain; a root that could not be listed makes it `Unknown`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`, and since 2026-09-27 **`unreal_build`** (no parameter; decided in code, §Engine version). A regex extractor must capture exactly **one** group — the evaluator returns the first — and `rules-validate.ps1` refuses any other count and any pattern that does not compile (both promised by the rules file's `$comment` and enforced by nothing until beta.10).
> `path_contains` and `strings_regex` were in the shipped data and the schema
> and missing from this list; the schema's own `$comment` said so and nobody had
@@ -83,7 +92,10 @@ Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`,
### Trust and staleness of the rules feed
`20_OPEN_QUESTIONS` §S4. The file is fetched over HTTPS from a raw GitHub URL.
> **Specified, not built (corrected 2026-10-04):** there is no feed (§S20 feed half, §S4); these rules apply once one
> exists. Today the seeder validates the packaged copy with the guard's parser and keeps `detection-rules.json.bak`.
`20_OPEN_QUESTIONS` §S4. The file ~~is~~ would be fetched over HTTPS from a raw GitHub URL.
Three rules, because a gate whose data can silently go stale is a gate with an
expiry date nobody sees:
@@ -131,13 +143,15 @@ Recorded as a residual risk, not as a solved problem.
| Engine | Signals | Version |
|---|---|---|
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | FileVersion of `UnityPlayer.dll` |
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)` |
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
| 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")` | `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` + `www/` or `package.json` | `rpg_core.js` / `rmmz_core.js` header |
| RPG Maker XP/VX/VXAce ⛔ | `RGSS10*`/`RGSS20*`/`RGSS30*.dll` | dll name → XP/VX/VXAce |
| Ren'Py | `renpy/` dir **or** `*.rpa` | `renpy/__init__` strings / `log.txt` first line |
| 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)* |
| CryEngine | `CrySystem.dll` | FileVersion |
| Source | `gameinfo.txt` + `bin/engine.dll` | `N/A` |
| Unknown | fallback | — |
@@ -146,33 +160,203 @@ Order matters (first match wins). Engine is user-overridable.
**The array order in `detection-rules.json` *is* that precedence**, and the only thing in the repository that notices a reorder is `tests/fixtures/rules/ordering/unity_markers_with_ue_structure` — a directory carrying Unity markers *and* Unreal structure, which is the case `14_TESTING` names.
⛔ **Two rows cannot be expressed in schemaVersion 2**, and are documented rather than half-implemented — a rule that exists but never fires is worse than one that is absent, because it reads as coverage:
> **Both RPG Maker rows were ⛔ "cannot be expressed in schemaVersion 2" until 2026-09-16, and the reasoning was
> half right.** It said MV/MZ needs `nw.dll` **and** (`www/` **or** `package.json`), a nested group v2 refuses. But
> MV and MZ both ship `package.json` beside `nw.dll` unconditionally — `www/` is only where MV keeps its data — so
> `all: [nw.dll, package.json]` is the whole signal and needs no nesting. Measured on the owner's *Flower in Us*
> (Steam) and a hand-extracted MV title, both `Game.exe` + `nw.dll` + `package.json` (+ `www/`), both `engine=none`
> until this rule. The RGSS family is one rule, `rpgmaker_rgss` "RPG Maker XP/VX/VX Ace", `any` over the three DLL
> prefixes and the three archive extensions, `version: null` — the variant is not named, which is the product
> decision the old note deferred, taken as "one engine, no version" rather than three rules. **What still cannot be
> expressed** is a version for either: MV/MZ's lives in a sibling `.js` header and `strings_regex` has no `from`;
> RGSS's is which DLL matched. Both rules sit after `unity` and `unreal` and before `godot` (an MV game has no
> `.pck`; a Godot game has no `nw.dll`), with fixtures `engines/rpgmaker_mv` and `engines/rpgmaker_rgss`, and the
> `every_engine_marker` canary carries both engines' markers and still expects `unity`. `rulesVersion` is
> `2026.09.1`, so the sweep's cache key changes and every game is re-detected on the next pass.
- **RPG Maker MV/MZ.** The signal is `nw.dll` **and** (`www/` **or** `package.json`) — a nested group, and `signalGroup` sets `maxProperties: 1` with its own `$comment` saying nesting is unsupported in v2. Its version is a header inside a sibling `.js`, and `strings_regex` carries no `from`, so it cannot be aimed at a file other than the executable.
- **RPG Maker XP/VX/VXAce.** The signals *are* expressible (`any` over the three `RGSS*` prefixes), but the version is "which of them matched" — an answer no extractor produces. Splitting it into three engine rules with `version: null` and the variant in the display name would work and is a product decision about how the engine reads in the UI, not a mechanical fill-in.
> **RE Engine and FromSoftware, 2026-09-23 (owner request, "mang tính tương đối" — a relative signal, not a proof).**
> Both are file-layout signals, checked on the owner's disk before they were written. **RE Engine:** every Capcom RE
> Engine title ships its content as `re_chunk_000.pak` beside the executable, with patches as
> `re_chunk_000.pak.patch_00N.pak` (RESIDENT EVIL 2 and the Onimusha demo). The rule names the base archive exactly — a
> glob without a star is the whole leaf name — so a patch archive alone is not it. **FromSoftware:** the studio's
> titles keep their data as `.bhd` header + `.bdt` data pairs beside the executable — DARK SOULS II
> (`GameDataEbl.bhd/.bdt`), DARK SOULS III (`Data0`–`Data5`), ELDEN RING (`Data0`–`Data3`, plus `DLC`) and Sekiro
> (`Data1`–`Data5`). The request described the second extension as `.bht`; on disk it is **`.bdt`**. An `all` group
> over the two globs — half a pair is not a pair. The request also described a `<Game>\Game\` layout; it is not a
> signal here, because Sekiro has no `Game\` folder and "the parent folder is named X" is not a signal type anyway.
> None of the owner's other 80 Steam titles carries either marker. Both rules sit after the RPG Maker rules and
> before `godot`, whose `*.pck` would also match a loose Wwise sound bank (an `Unknown` there would stop the walk
> before these rules). Fixtures `engines/re_engine` and `engines/fromsoftware`; the `every_engine_marker` canary
> carries both engines' markers and still expects `unity`. `rulesVersion` is `2026.09.2`, so every stored game is
> re-detected on the next sweep. Engine detection never feeds the guard: ELDEN RING stays refused by its anti-cheat
> whatever engine it is shown as. **Engines are shown by name since the same date** (`Formats.Engine` in the App —
> proper nouns, not resources; an unknown id, or one the user typed, passes through): the game card and page used
> to show the raw id (`rpgmaker_mv`).
⛔ *(kept for the record — the two rows above were the ones this note described)* **Two rows cannot be expressed in schemaVersion 2**, and are documented rather than half-implemented — a rule that exists but never fires is worse than one that is absent, because it reads as coverage:
- ~~**RPG Maker MV/MZ.** The signal is `nw.dll` **and** (`www/` **or** `package.json`) — a nested group, and `signalGroup` sets `maxProperties: 1` with its own `$comment` saying nesting is unsupported in v2.~~ Its version is a header inside a sibling `.js`, and `strings_regex` carries no `from`, so it cannot be aimed at a file other than the executable.
- ~~**RPG Maker XP/VX/VXAce.** The signals *are* expressible (`any` over the three `RGSS*` prefixes), but the version is "which of them matched" — an answer no extractor produces. Splitting it into three engine rules with `version: null` and the variant in the display name would work and is a product decision about how the engine reads in the UI, not a mechanical fill-in.~~
Everything else in the table is in the data and has a fixture; `rules-validate.ps1` fails if a rule id has no fixture directory, or a fixture no rule.
### Engine version — Unreal Engine (beta.10, 2026-09-27, schema 0015)
The owner asked for "the exact Unreal Engine version (3.0, 4.5, 5.1 …) on the game's page". What was shipped could not
give one: the rule read only the executable's `ProductVersion` string, which most shipping executables leave empty, and
its regex had two capture groups, so the one answer it could give was `4` or `5`. **Measured before anything was written,
read-only, on the owner's ten Unreal titles** (`spike-notes` §Unreal Engine versions):
| Title | Numeric file version | Version strings / company | Branch name in the bytes | Read as |
|---|---|---|---|---|
| Black Myth: Wukong | 5.0.0.0 | none | `++UE5+Release-5.0` (290 MB into `.code`; `.rdata` 8 KB) | 5.0.0 |
| Cronos: The New Dawn (demo) | 1.2.0.0 | the studio's | none | — |
| Clair Obscur: Expedition 33 | 5.4.4.0 | none | none | 5.4.4 (file version) |
| Hell Is Us | 5.5.4.0 | `UE5-CL-0` / Nacon | none (the studio's own branch) | 5.5.4 (file version) |
| Lies of P | 4.27.2.0 | none | none | 4.27.2 (file version) |
| Martha Is Dead | 4.27.0.0 | none | `++UE4+Release-4.27` (`.rdata`) | 4.27.0 |
| Rune Factory: Guardians of Azuma | 1.0.3.0 | none | none | — |
| SILENT HILL 2 | 1.0.0.5 | the studio's | `++UE5+Release-5.1` (`.rdata`) | 5.1 |
| UMIGARI | 5.5.4.0 | `++UE5+Release-5.5-CL-40574608` / Epic Games, Inc. | (in the strings) | 5.5.4 |
| AbyssMemory | 4.26.1.0 | none | `++UE4+Release-4.26` (`.rdata`) | 4.26.1 |
**Two witnesses, each wrong in its own way.** The numeric file version (`VS_FIXEDFILEINFO`) is the engine's
MAJOR.MINOR.PATCH unless the studio replaced it (Cronos, SILENT HILL 2, Rune Factory); the branch name the engine compiles
in (a UTF-16 string) names the release line and no patch, and is missing wherever a studio renamed its branch or the
executable is packed. `Domain.Detection.UnrealVersion.Decide` takes them in order: **(1)** both, agreeing on MAJOR.MINOR →
the file's MAJOR.MINOR.PATCH (`unreal_branch_file`); **(2)** a branch name alone → MAJOR.MINOR (`unreal_branch`); **(3)**
no branch name, and a file version that reads as an engine's (4.0–4.27, 5.0–5.9, patch ≤ 20) where nothing says the studio
replaced it — no version strings, a string naming the same `UE4`/`UE5`, or Epic's company name → MAJOR.MINOR.PATCH
(`unreal_file_version`); **(4)** anything else → no version. The third rung is the weakest (a studio could number its own
game 4.2 and ship no strings), which is why `games.engine_version_source` keeps the rung and the game page says it.
**Where it is read.** `StaticGameDetector` makes a second read for the one engine that matched — never the probe for every
game in the library: `GameFileProbe.ReadUnrealBuildAsync` picks the row's own executable when it is the shipping build
(`*-Win64-Shipping.exe`, `*-WinGDK-Shipping.exe`), else the largest shipping executable the walk listed (a row pointing at
the launcher stub at the install root), and `UnrealBuildReader` reads its version resource and — unless the version strings
already name the branch — scans its `.rdata` section for the branch name: 15–39 MB in nine of the ten titles. An `.rdata`
under 1 MiB (Black Myth's protector merged its constants elsewhere) sends the scan over the whole file, bounded at 1 GiB and
stopping at the first chunk that names a release line. Chunks are 4 MB with an overlap, so a name cut by a chunk's edge is
read whole and never as the digits that fitted; cancellation is observed between chunks. Measured through the shipped
reader on the same ten files: every row above as tabled, 16 ms to 1.1 s each and 7.5 s for Black Myth, on the owner's USB
drive — once per executable, because the detection key (rules version + size + mtime) changes only when the file does.
**What it is not.** UE3 titles are not detected as Unreal at all (the rule's signals are UE4/5's layout) and have no
numbered release lines to report. A version the user typed is never overwritten and carries no witness. Rules
`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 |
|---|---|---|
| Xbox *(beta.33, D79; first in the array)* | **both** `MicrosoftGame.config` and `appxmanifest.xml` directly in the install root (`root_file`, `all`): a GDK package root. First because a GDK build can ship Steam's DLL — every FINAL FANTASY Pixel Remaster from the Xbox app carries `Plugins\x86_64\steam_api64.dll` (`spike-notes` §25) — and a `root_file` miss is never `Unknown` for want of a deep walk, so a large Steam install behind it still reads *steam* | each drive's `.GamingRoot` → `<games folder>\<Game>\Content\`: `MicrosoftGame.config` (Identity, ShellVisuals, ExecutableList, StoreId) and `appxmanifest.xml` (the Application id); the package family name and its registration from Windows (`PackageFamilyNameFromId`, `GetPackagesByPackageFamily`) |
| Steam | `steam_api64.dll`/`steam_api.dll` sibling, or path contains `steamapps\common` | nearest `steamapps/appmanifest_<id>.acf` (walk up): `appid`, `name`, `buildid` → version |
| GOG | `goggame-<id>.info` sibling, or `Galaxy64.dll` | `.info` JSON: `gameId`, `name`, `version` |
| Epic | `EOSSDK-Win64-Shipping.dll`, or path under an Epic install | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
| itch.io | `.itch\receipt.json.gz` | receipt JSON: title, id |
| Epic | `EOSSDK-Win64-Shipping.dll`~~, or path under an Epic install~~ *(corrected 2026-10-04: the rule has no path signal)* | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
| itch.io | `.itch\receipt.json.gz` | **`%APPDATA%\itch\db\butler.db`** (`install_locations` + `caves`, butler's `verdict` names the executable) since 2026-09-16, then the receipt JSON: title, id |
| None/Manual | fallback | PE VersionInfo |
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf`; 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.
> **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*. *(beta.33: an Xbox game ships its own — `Infrastructure.Art.XboxArtCache` reads the
> `Square480x480Logo` (else `Square150x150Logo`) and the `SplashScreenImage` its `MicrosoftGame.config` names, inside
> the package root only, as a square cover and the banner; `IStoreArtCache.Find` takes the owning record rather than the
> id, because those pictures live in the install folder.)*
**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; *(beta.33)* Xbox by each drive's `.GamingRoot` and each game's package files. 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
> `Infrastructure.Import` — `SteamLibrarySource` (`libraryfolders.vdf` + `appmanifest_*.acf` through
> `ValveKeyValues`, the Steam root from `HKCU\Software\Valve\Steam\SteamPath`), `GogLibrarySource` (the HKLM
> keys, read-only, the first HKLM read in the tree), `EpicLibrarySource` (`*.item` JSON: `DisplayName`,
> `InstallLocation`, `LaunchExecutable`, `AppName`, `AppVersionString`), `ItchLibrarySource`
> (`%APPDATA%\itch\apps\*\.itch\receipt.json.gz`). **Two stores do not name the game's executable** (Steam,
> itch): `ExecutableLocator` walks the install three levels deep, drops the helpers by name fragment and takes
> the largest — a *guess the review list marks as such*; GOG's `exe` and Epic's `LaunchExecutable` are the store's
> (~~`%APPDATA%\itch\apps\*\.itch\receipt.json.gz`~~ — **since 2026-09-16 butler's database first**: the itch app
> records the install locations the user chose in `%APPDATA%\itch\db\butler.db`, and they need not be under
> `%APPDATA%` at all — on the owner's machine the one location was `D:\another\it` and `apps\` was empty, so the
> receipt scan returned nothing, silently; `install_locations` + `caves` give every install, butler's own `verdict`
> names the executable it launches, and `apps\` receipts are still scanned for what the database does not list. The
> database is copied to a temporary directory and the copy opened read-only, because the running app holds it in
> WAL mode. One log line says what was consulted: `import: itch — butler.db read: 1 location(s), 2 cave(s), …`).
> **Two stores do not name the game's executable** (Steam,
> itch-by-receipt): `ExecutableLocator` walks the install ~~three~~ **four** levels deep, drops the helpers by name
> fragment, everything under a Unity `X_Data\Plugins` folder and every redistributables/prerequisites folder, and then
> **ranks** what is left — ~~takes the largest~~ an executable the engine's own layout names as the game (Unity: `X.exe`
> beside `X_Data`; Unreal: `*-Win64-Shipping.exe`) beats one named after the install folder, which beats a stranger, and
> size decides only between equals. "The largest wins" was measured wrong 2026-09-21 on GIRLS' FRONTLINE 2: EXILIUM:
> the import chose `GF2_Exilium_Data\Plugins\ZFGameBrowser.exe` (1,082,944 bytes) over the 675,392-byte Unity player, and
> because the watcher, consent and the gate are keyed on the executable path, hooking enabled on that row could never
> match the game. The same pass fixed Red Dead Redemption 2 (the 140 MB launcher installer under `Redistributables`),
> Counter-Strike 2 (`vconsole2.exe`), Rune Factory (root bootstrapper vs the shipping binary) and Dying Light: The
> Beast (the game sits four levels down). Still a *guess the review list marks as such*, and since the same date the
> game page shows the row's executable and **Change executable…** re-points it (hooking off and unconsented afterwards,
> exactly as a new game; a block is never cleared by it). GOG's `exe` and Epic's `LaunchExecutable` are the store's
> own. The review (`ImportReviewPrompt`) ticks only what can be imported: a row already in the library or with no
> executable on disk cannot be. Every added row lands exactly as File ▸ Add game… lands it — hooking off — and
> the store's platform, id and version go through `IGameRepository.ApplyStoreMetadataAsync` under the same
@@ -183,7 +367,52 @@ Everything else in the table is in the data and has a fixture; `rules-validate.p
> 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.
> **beta.33 (owner decisions D78/D79, `spike-notes` §25): the Xbox app's and the Microsoft Store's games.**
> `XboxLibrarySource` reads each ready fixed or removable drive's `.GamingRoot` (`GamingRoots`: `RGBX`, a count, UTF-16
> folder names relative to the drive), lists the `<games folder>\<Game>\Content\` folders that are GDK package roots
> (`GdkPackageFiles`: `MicrosoftGame.config` beside `appxmanifest.xml`, read with DTDs prohibited and a 1 MB cap), and
> keeps those whose package Windows says is installed for this user (`PackageFamilyNameFromId`, then
> `GetPackagesByPackageFamily`). The record: the store id is the package family name, the install directory is `Content`
> (the spelling the game's own process reports — never the `C:\Program Files\WindowsApps` junction, whose name carries
> the version), the launch key is the AUMID `<family name>!<Application Id>` that Play activates, the version is the
> package's. It names no executable, so `ExecutableLocator` ranks: the WinGDK or Win64 shipping binary over the stub the
> package launches, the Unity player over its crash handler, never `gamelaunchhelper.exe` (a runtime helper since
> beta.33), with the folder above `Content` as the install's name. **What cannot be read:** every game `.exe` under
> `Content` refuses `FILE_READ_DATA` to a process outside its package, so its PE header, version resource, imports and
> strings are not read — the architecture reads `unknown` (never "not x64", so nothing is turned off for it), no Unreal
> version is shown, and the Unity version still reads, from `UnityPlayer.dll`. A UWP app has no `MicrosoftGame.config`
> and is not listed (D78).
> **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)
@@ -191,8 +420,8 @@ Files shipped with a game tell us what it *supports*. These populate a **"Suppor
- DLSS SR `nvngx_dlss.dll` · DLSS-G `nvngx_dlssg.dll` · **Ray Reconstruction `nvngx_dlssd.dll`**
- Streamline `sl.interposer.dll`, `sl.dlss_g.dll`, `sl.reflex.dll`
- FSR `ffx_fsr2_*.dll`, `ffx_frameinterpolation_*.dll`, `amd_fidelityfx_*.dll`, `ffx_api*.dll` — a hint still, even though `amd_fidelityfx_dx12.dll` / `_upscaler_dx12.dll` / `_framegeneration_dx12.dll` are *hooked* since 2026-09-04: the measured chip comes from the dispatch, never from the file
- XeSS `libxess.dll`, XeFG `libxess_fg.dll`
- FSR `ffx_fsr2_*.dll`, `ffx_fsr3*.dll` (since rules 2026.09.5 — FSR 3's `ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` matched nothing before), `ffx_frameinterpolation_*.dll`, `amd_fidelityfx_*.dll`, `ffx_api*.dll` — a hint still, even though `amd_fidelityfx_dx12.dll` / `_upscaler_dx12.dll` / `_framegeneration_dx12.dll` are *hooked* since 2026-09-04: the measured chip comes from the dispatch, never from the file
- XeSS `libxess.dll`, `libxess_dx11.dll` (since rules 2026.09.5), XeFG `libxess_fg.dll`
- DXR-capable: `d3d12.dll` usage + RT-capable GPU (capability only — says nothing about the game)
- **Vulkan (since P4 PR-2, 2026-09-14) — a code-level fact, not a rule.** The rules can only ask about files
beside the executable, and the Vulkan loader is not one of them (`vulkan-1.dll` lives in System32). So
@@ -205,17 +434,109 @@ Files shipped with a game tell us what it *supports*. These populate a **"Suppor
The UI wording is deliberate: **"Supports DLSS-G"** (capability, from files) versus **"Frame Generation: DLSS-G ×1.9"** (measured, from this session). Users conflating these is exactly the confusion the old design created.
### What the files say about themselves (beta.8, 2026-09-25, schema 0011)
The owner asked for the game's version, the DLSS / FSR versions and whether a game is 32- or 64-bit. The sweep read
most of it already and kept none of it; since beta.8 it keeps four more facts per game, written whole with each
detection (`DetectionWrite`, `games.exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`):
- **What the executable runs as** — `PeImports.ReadArchitecture`, from the same bounded header read as the imports:
the COFF machine and, for a .NET executable, the CLR header's flags (`Domain.Detection.ExecutableArchitecture`:
`x64 | x86 | arm64 | arm | anycpu | anycpu32 | other | unknown`). An "AnyCPU" assembly carries an I386 machine and
runs as a 64-bit process unless it prefers or requires 32-bit, which is why the machine alone is not the answer.
`x86`, `anycpu32`, `arm64` and `arm` are **known not hookable** — the hook is an x64 DLL loaded with `LoadLibraryW`
(CLAUDE.md rule 3) — so enabling hooking on one is refused before anything is scanned or stamped
(`Refused { reason: "ExecutableNotX64", signal: <id> }`, `07_IPC`), and a row enabled before this build read the file
has its hooking turned off by the sweep (`hook_autodisabled_reason` = `executable is x86: the hook runs in x64
processes only`). `unknown` and `other` are not: the guard's `TargetIsWow64` at a session's start stays the check.
A row whose `exe_machine` is NULL is stale once, so every library entry is read under this build.
- **The executable's own versions** — the PE `FileVersion` and `ProductVersion` strings. The file's word, kept apart
from `game_version`, which is the store's (a Steam build id, a GOG or Epic version string) or the user's. For an
Unreal title the file version is often the *engine's*; the page labels both and does not pick one.
- **What it ships, with versions** — every file a capability rule names among those the walk listed, with the
numeric version of its `VS_FIXEDFILEINFO` (the version *string* may carry text, and Streamline stamps `2,8,0,0`):
`nvngx_dlss.dll 3.7.10.0`, `sl.interposer.dll 2.8.0.0`, `ffx_fsr2_api_x64.dll …`. Bounded at 48 files. A file with
no version resource is listed with none — it is shipped either way. FSR is named by its file, never mapped to an
"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.~~ *(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.)* *(Measured 2026-10-19, `spike-notes` §22: under the
override, Silent Hill 2 loaded `160_E658700.bin` 310.9.16.0 and `1B0_E658703.dll` 2.14.16.0 from the NGX folder —
names no census lists; which feature each serves is not established.)* 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` |
| The NVIDIA App's **Dynamic** frame generation — set in the game's profile and reported applied by the driver — in a session where DLSS Frame Generation was identified *(beta.34, owner decision D83)* | DLSS 4.5 (Dynamic multi frame generation, set in the NVIDIA App) | `driver_profile`'s `NGX_DLSSG_MODE` = 4 (dynamic), `ngx_driver_words`' FG word with `FG_MODE` (bit 13), `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~~ *(replaced 2026-11-06 by the two rows below, D84)* |
| DLSS 5's neural rendering **evaluated** — `kFeatureDLSS_NR` (Streamline 2.14) on some of the frames the game rendered through Streamline, seen by an Overlay that decodes it *(beta.34, owner decision D84)* | DLSS 5 (neural rendering on N % of rendered frames) — **heads the table** | `dlss_nr_pct` (schema 0022), from `FL_FEAT_SL_NEURAL_RENDERING` under `FL_HOOK_SL_NEURAL_RENDERING` |
| `nvngx_dlssnr.dll` loaded, neural rendering not seen evaluated | "DLSS 5 runtime loaded" — and "…, not seen running" where an Overlay that decodes it drained Streamline batches and none carried it (0 %); never a generation | `runtime_modules` (the name seen on Hogwarts Legacy, 2026-11-06) and `dlss_nr_pct` |
**Amended 2026-11-06 (beta.34, owner decision D83): Dynamic is DLSS 4.5's.** The NVIDIA App's *Dynamic* frame
generation and its ×6 mode exist only in DLSS 4.5, so a session the driver reports running Dynamic is DLSS 4.5 whatever
multiplier the mode chose: the owner's Phantom Blade Zero under *Dynamic, up to ×3* held ×2.0 and ×3.0 — nine hooked sessions
from 2026-11-03 to 11-05 — and read *DLSS 4 (a ×3.0 frame-generation state)* until then. The row needs all three: the
profile's Dynamic (`NGX_DLSSG_MODE` = 4, NVIDIA's own name for the value), the driver's report that its frame-generation
override applied in the game's process (the FG word's `FG_MODE` bit), and DLSS Frame Generation identified in the session
(`fg_mode = dlssg`; its factor need not have been counted) —
a profile set to Dynamic that the driver never applied is a setting, not evidence. The driver's own mode number is not
read: it answers 3 under Dynamic and 1 under *Fixed* on every stored session (`spike-notes` §26), and NVIDIA's header
names neither. A *Fixed* ×5 or ×6 is not this row — Witcher 3 under the App's Fixed ×6 still presented ×2.0 — and
names DLSS 4.5 only where a state is measured at ×5 or more, which ranks above it.
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~~ `nvngx_dlssnr.dll` —
loaded by the owner's Hogwarts Legacy with Neural Rendering on, 310.9.16.0 from the game's folder (2026-11-06,
`spike-notes` §26), beside its Streamline plugin `sl.dlss_nr.dll`; `kFeatureDLSS_NR = 1004` — Streamline `v2.14.16`'s
public `sl_core_types.h` (re-vendored for it, `src/native/third_party/streamline/README.md`).
**Amended 2026-11-06 (beta.34, owner decision D84): DLSS 5 is named where it ran.** Until then a session could say only
that DLSS 5's runtime was LOADED — and Hogwarts Legacy, Neural Rendering on, loaded it. The Overlay's
`slEvaluateFeature` detour now decodes `kFeatureDLSS_NR` into its own per-frame fact (`FL_FEAT_SL_NEURAL_RENDERING`,
the feature byte's last bit, under the condition every Streamline fact shares) and publishes
`FL_HOOK_SL_NEURAL_RENDERING` with the detour; the Agent stores the share of Streamline batches that carried it
(`dlss_nr_pct`) **only from a writer that published that family** — an older Overlay drains the same batches and never
sets the bit, and its silence must not read as 0 %. Above every other row because DLSS 5 is named for that feature as
DLSS 4.5 is for its own: the session's super resolution, ray reconstruction and frame generation are the libraries the
line lists after it. Whether the game routes neural rendering through `slEvaluateFeature` at all is owner-only item
30(a)'s run; a title that does not reads *runtime loaded*, never *not running*.
## 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`). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1).
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` since 2026-09-25, which takes the executable, resolves the install root itself and runs check 3 as well). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1). **It walks two folders since 2026-10-13:** the install root and, when the executable lives below it, the executable's own folder — each three levels deep. The root alone missed Wuthering Waves' `Client\Binaries\Win64\AntiCheatExpert\`, which sits beside the executable and four levels under the root (`19_SAFETY` §Pre-injection checks, item 4; `spike-notes.md` §19).
Three things this section previously implied that are not true, and are worth stating:
- **The UI answer is advisory.** It decides whether the toggle is *offered*; it does not gate injection. The same scan runs a second time inside the guard's chokepoint against a directory derived from the target's own pid, so "prevention beats interception" is a convenience, not the enforcement.
- **A hit disables the toggle; "could not scan" must not.** The scan is tri-state. `Reason::kPreScanFailed` — directory absent, unlistable, past a bound, or behind a reparse point — is *neither* a hit nor a pass. It must surface as "could not verify", distinct from "anti-cheat found": disabling the toggle on it would be a false refusal with no appeal, and clearing it would be a fail-open.
- **The token list is thin.** `directories` and `files` carry three tokens today. Widening needs verified names; a guessed token fails closed by never firing, which is a silent hole (`19_SAFETY` §Blocklist seed).
- **A hit disables the toggle; "could not scan" must not.** The scan is tri-state. `Reason::kPreScanFailed` — directory absent, unlistable, past the entry bound, or behind a reparse point — is *neither* a hit nor a pass. *("Past a bound" until 2026-10-13: the depth bound is a reach, not a refusal — a folder at the last level is named and never opened, and the walk still reads as complete.)* It must surface as "could not verify", distinct from "anti-cheat found": disabling the toggle on it would be a false refusal with no appeal, and clearing it would be a fail-open.
- **The token list is thin.** `directories` and `files` ~~carry three tokens today~~ *(corrected 2026-10-04: rules 2026.10.1 carry 9 directory families (12 names) and 18 file families (55 names), and since 2026-09-25 any `*.sys` in the install tree is a finding by code, not data)*. Widening needs verified names; a guessed token fails closed by never firing, which is a silent hole (`19_SAFETY` §Blocklist seed).
## Caching & privacy constraints
@@ -225,7 +546,10 @@ Three things this section previously implied that are not true, and are worth st
> `DetectionHostedService` (`--serve` only) sweeps the library on its own task — every 15 s, and at once
> when `UpdateRules` re-seeds the rules file — through `Application.Detection.DetectionSweep`, which runs
> `StaticGameDetector` over the real `GameFileProbe` for every game whose key is stale and persists through
> `IGameRepository.ApplyDetectionAsync`. A game the App adds is scanned on the next tick (the App writes the
> `IGameRepository.ApplyDetectionAsync`. *A missing executable is asked one more question before it is skipped
> (2026-09-22): is the same file — same size, same mtime — under exactly one other drive letter? When it is, the row
> follows it (`ExecutableRelocator`, `19_SAFETY` §A moved drive is the same executable) and this very pass scans
> it there; `DetectionSweepReport.Relocated` counts them.* A game the App adds is scanned on the next tick (the App writes the
> row, the Agent reads the table); no Agent running means no scan, and the game page says "not scanned yet".
> *The key's exe half is NOT `exe_size_bytes` / `exe_mtime_ms`:* those are the consent fingerprint the gate
> reads (`SqliteGameConsentStore` refuses a mismatch while a block stands), so schema 0004 gave the key its own
@@ -234,7 +558,7 @@ Three things this section previously implied that are not true, and are worth st
> the user's and stays; a `detected` entry is refreshed; **an empty field with no entry has nothing to protect
> and is filled and badged `detected`** — without that clause a freshly added game could never receive an
> engine at all, since `EnsureAsync` writes no provenance. A null detected value erases nothing.
> `capability_flags` is written whole every run (a JSON array of the rule ids — `dlss`, `dlss_g`, `dlss_rr`,
> `capability_flags` is written whole every run (a JSON array of the rule ids — `dlss`, `dlss_g`, `dlss_rr`, `dlss_nr` (beta.34),
> `streamline`, `fsr`, `xess`, `xefg`) because the Supports row has no user-edit surface and a stale "Supports
> DLSS-G" after the DLL left is the confusion §Capability hints exists to prevent.
- Strings scans bounded to 8 MB, local only.
+373 -37
View File
@@ -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` — 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. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; never a `hook_*` column), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It was the one Agent write that deletes a `games` row until beta.19; it never touches a consent column. **And since beta.19 (2026-10-12, D55) the Agent removes an entry whose game is no longer installed** (`IGamePrune`, `SqliteGamePrune`, asked by the detection sweep through `UninstalledEntryPrune`): one `DELETE` that holds every stored condition in the same statement — the same row at the same path, `removed_at` NULL, no session stored (`NOT EXISTS` on `sessions` — nothing cascades), no `hook_blocked_reason`, `hook_prescan_state` not `blocked`, no `ac_exception_at` and no `ac_exception_trial_failed_at` — behind `retention.remove_uninstalled_games`; a block, a grant and D38's mark are never removed with their entry (`19_SAFETY` §What a finding does to the game, *What clears it*). **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself *(for Delete all sessions; FR-1.4's removal is the App's own cascade, above — corrected 2026-10-04)*. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; ~~never a `hook_*` column~~ **and two downgrades** *(corrected 2026-10-04)*: *Change executable* (2026-09-21, `GameLibrary.ChangeExecutableAsync`) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and *Remove game ▸ DeLine truncated
## Schema (v2 — hook architecture)
@@ -40,12 +40,24 @@ CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER
CREATE TABLE games (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
exe_path TEXT NOT NULL UNIQUE,
platform TEXT NOT NULL DEFAULT 'none', -- steam|gog|epic|itch|none
exe_path TEXT NOT NULL UNIQUE, -- where the executable lives; rewritten by ExecutableRelocator when the
-- SAME bytes (exe_size_bytes, exe_mtime_ms) turn up under another drive
-- letter (2026-09-22), and by Change executable for a DIFFERENT binary
platform TEXT NOT NULL DEFAULT 'none', -- steam|gog|epic|itch|xbox|none (xbox since beta.33, D79; no CHECK constraint, so no migration)
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; 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)
@@ -53,7 +65,32 @@ CREATE TABLE games (
-- hooking state (19_SAFETY)
hook_enabled INTEGER NOT NULL DEFAULT 0, -- 0 = Tier 2, i.e. nothing measured; default for every new game
hook_consent_at INTEGER, -- per-game informed consent timestamp
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI.
-- 'Reason|Family|Signal' since 2026-09-25 (SqliteGameConsentStore.
-- BlockText), so the App can say it in the user's language; older
-- rows keep "Reason: Family Signal" and are shown as stored
hook_prescan_rules_version TEXT, -- schema 0010 (2026-09-25): the key the Agent's pre-scan of the
hook_prescan_exe_size_bytes INTEGER, -- library last scanned the row under — the rules version and the
hook_prescan_exe_mtime_ms INTEGER, -- executable's size and mtime; NULL = never scanned by the sweep.
-- Change executable clears them with hook_prescan_state
-- schema 0014 (2026-09-26, D33): the user-mode anti-cheat exception, a layer OVER hook_blocked_reason, never its clearing
ac_exception_eligible INTEGER NOT NULL DEFAULT 0, -- the Agent's sweep: the exception may be granted now
ac_exception_verdict TEXT, -- its tolerant pre-scan, Reason|Family|Signal; NULL = nothing asked
ac_exception_sessions INTEGER NOT NULL DEFAULT 0, -- D38: successful sessions under the grant in force (its trial)
ac_exception_checked_rules_version TEXT, -- the key the verdict was reached under: rules, executable size and
ac_exception_checked_exe_size_bytes INTEGER, -- mtime, and the block text itself
ac_exception_checked_exe_mtime_ms INTEGER,
ac_exception_checked_block TEXT,
ac_exception_at INTEGER, -- the user's grant; NULL = no exception in force
ac_exception_family TEXT, -- the family it covers (kept as history once it ends)
ac_exception_disclosure_version TEXT, -- AntiCheatExceptionDisclosure.Version the user accepted
ac_exception_exe_size_bytes INTEGER, -- the executable the grant was made on; other bytes end it
ac_exception_exe_mtime_ms INTEGER,
ac_exception_lapsed_at INTEGER, -- when and why the last grant ended (UserModeExceptionLapse:
ac_exception_lapsed_reason TEXT, -- Withdrawn|ExecutableChanged|NoLongerEligible|NewFinding|
-- SafetyUnhook|OverlayStopped|SessionCrashed|TrialFailed)
-- schema 0017 (2026-10-03, D38): an exception of this game ended during its trial — for good; never cleared
ac_exception_trial_failed_at INTEGER,
hook_autodisabled_reason TEXT, -- set after repeated crashes
hook_crash_count INTEGER NOT NULL DEFAULT 0,
capability_flags TEXT, -- JSON: what the game SHIPS — never a measurement. Since P4 PR-1 (2026-09-14) a JSON
@@ -67,6 +104,14 @@ CREATE TABLE games (
rr_default TEXT NOT NULL DEFAULT 'na',
detection_rules_version TEXT,
exe_machine TEXT, -- schema 0011 (2026-09-25): what the executable runs as, from its PE
-- headers (x64|x86|arm64|arm|anycpu|anycpu32|other|unknown); NULL =
-- not read by this build yet, which the detection sweep reads as stale
exe_file_version TEXT, -- schema 0011: the executable's PE FileVersion (the file's word; game_version
exe_product_version TEXT, -- is the store's or the user's) and its ProductVersion
library_versions TEXT, -- schema 0011: JSON array, the capability files the game SHIPS —
-- {"capability","path","fileVersion","productVersion"}; what a session
-- LOADED is sessions.runtime_modules
field_provenance TEXT, -- JSON: {"engine":"detected","publisher":"user",...}
-- absent or unrecognised reads as "user"
added_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
@@ -85,15 +130,18 @@ CREATE TABLE games (
> human's typed value as auto-detected is a lie they cannot see through; failing to
> badge a detected value merely costs a badge on something they can still edit. The
> rule it exists to support — *detection never overwrites a `user` field* — is in
> `05_DETECTION` §Caching and is enforced by `StaticDetectionResult.ShouldWrite`,
> which is tested even though nothing persists yet.
> `05_DETECTION` §Caching and is enforced by ~~`StaticDetectionResult.ShouldWrite`,
> which is tested even though nothing persists yet~~ `SqliteGameRepository.FieldProvenance.Resolve`
> *(corrected 2026-10-04: applied per field since P4 PR-1, and it also fills an empty field that has no entry;
> `ShouldWrite` keeps its tests but has no production caller)*.
>
> ~~No migration is written here. There is no SQLite layer at all, and §Migrations
> forbids editing an applied script — so guessing the shape into `0001_init.sql`
> before its consumers exist maximises the chance of baking in a wrong guess that
> can only be appended to.~~ **Written 2026-09-09 (P2 PR-B), with its first consumer:** the
> column exists in `0001_init.sql`; the writer (the detection cache, P4) and the reader (the
> library card, P3) are still unbuilt, so it is decided, created, and empty.
> column exists in `0001_init.sql`; ~~the writer (the detection cache, P4) and the reader (the
> library card, P3) are still unbuilt, so it is decided, created, and empty~~ *(corrected 2026-10-04: written since
> 2026-09-14 by the detection sweep, the store import and Edit…; read for the Edit dialog's badges and the game page)*.
> **The three hook-state columns have a consumer before they have a table, and two
> fields it needs are not here.** Added 2026-08-06 with `IGameConsentStore`, whose
@@ -104,7 +152,8 @@ CREATE TABLE games (
> anything else — so a record could carry a consent time that nothing had ever
> disclosed anything for. `ConsentProvenance`'s zero value means *no disclosure was
> shown*, and it deliberately has **no FR-2.1 member**: that dialog needs reviewed
> `Safety_*` wording in en/vi/ja and no `.resx` exists anywhere in this tree.
> `Safety_*` wording in en/vi/ja and ~~no `.resx` exists anywhere in this tree~~ *(superseded: the dialog shipped in
> P3 PR-4 as `ConsentDialog`, below — corrected 2026-10-04)*.
> - **A disclosure/wording version.** `legal_acceptance` carries `(doc, version,
> accepted_at)` while this column carries a timestamp alone, so nothing could mark
> existing per-game consent stale when the reviewed wording changes. It is carried
@@ -126,7 +175,10 @@ CREATE TABLE games (
> shipped producer, still not FR-2.1, stamped by the Agent's clock; the store writes the NAME the
> acknowledgement carries and refuses `NotRecorded`.
>
> **Still unanswered, and it is an owner decision rather than a coding one:** who
> ~~**Still unanswered, and it is an owner decision rather than a coding one:**~~ **Answered by the owner on
> 2026-09-22: nothing clears it** *(corrected 2026-10-04)*. A clean re-scan, *Change executable*, a re-import and a twin
> merge all leave it, and the toggle stays disabled (`19_SAFETY` §What a finding does to the game); D33's exception
> sits on top of the block and never clears it. The question as it stood: who
> clears `hook_blocked_reason` when a re-scan comes back clean. `19_SAFETY` §A game
> already enabled can become blocked later makes a non-null value mean "toggle
> disabled" and makes re-enabling "a user action" — but if nothing clears the column
@@ -152,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
@@ -176,11 +230,13 @@ CREATE TABLE sessions (
-- presentation
api TEXT, present_mode TEXT, swap_effect TEXT,
hdr_flag TEXT NOT NULL DEFAULT 'na', hdr_source TEXT, -- tri-state, like rt/rr beside it
sync_interval_mode TEXT, -- observed vsync behavior
sync_interval_mode TEXT, -- observed vsync behavior: on|off|mixed — first written in beta.14 (0019's
-- §Sync), NULL where no present carried its arguments (OpenGL, Vulkan, Tier 2)
-- upscaling / FG (measured at tier 1)
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown
upscaler_quality TEXT,
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown, and fsr since 2026-09-04 (FL_UPSCALER_FSR_UNVERSIONED; added 2026-10-04)
upscaler_quality TEXT, -- the hooked byte, invariant: dlss 1-6 (sl::DLSSMode); fsr/fsr3 16-20 =
-- 0x10 + FfxApiUpscaleQualityMode since beta.25 (D65); NULL when none told
upscaler_sharpness INTEGER, -- percent; NULL when the API reports none
render_w INTEGER, render_h INTEGER, -- dominant segment
output_w INTEGER, output_h INTEGER,
@@ -196,7 +252,8 @@ CREATE TABLE sessions (
fg_source TEXT, -- api|cadence|manual (`etw` removed 2026-08-28: no producer, no tier)
fg_factor REAL,
-- schema 0003 (2026-09-14): why fg_factor is NULL while fg_mode names a technology — FgRefusalKind as
-- Vocabulary.FgRefusal spells it (not_counted, no_evaluations, non_uniform, dxgi_saturated, …). NULL when a
-- Vocabulary.FgRefusal spells it (not_counted, no_evaluations, non_uniform, dxgi_saturated, …; beyond_generation
-- since beta.26: a ratio above FgWindow.GenerationCeiling that held throughout). NULL when a
-- factor stands or the writer predates the column. A REASON for the UI, never an input to fg_mode or a number.
fg_refusal TEXT,
-- FlWriterState.runtimeCensus, raw (FlRuntimeCensus bits). Which vendor runtime modules
@@ -238,7 +295,54 @@ CREATE TABLE sessions (
avg_cpu_temp REAL, max_cpu_temp REAL,
avg_gpu_temp REAL, max_gpu_temp REAL, max_gpu_hotspot REAL,
avg_gpu_load REAL, avg_cpu_load REAL, avg_ram_mb REAL,
avg_gpu_power_w REAL, throttle_pct REAL
avg_gpu_power_w REAL, throttle_pct REAL,
-- schema 0018 (2026-10-03, beta.12, D43): the game process's own memory, read from outside it, both tiers
-- (03_METRICS §Game process memory), MiB; and every sensor series' n/mean/median/min/max as JSON
game_vram_dedicated_avg_mb REAL, game_vram_dedicated_median_mb REAL, game_vram_dedicated_max_mb REAL,
game_vram_shared_max_mb REAL,
game_ram_private_avg_mb REAL, game_ram_private_median_mb REAL, game_ram_private_max_mb REAL,
game_ram_ws_max_mb REAL, game_commit_max_mb REAL,
game_memory_processes INTEGER, -- processes summed: 1 pinned, every process of the executable for a held one
game_memory_source TEXT, -- counters,ex2,ex,held,opened — the reads that answered
sensor_stats_json TEXT, -- {"gpu_temp":{"N":…,"Mean":…,"Median":…,"Min":…,"Max":…}, …}
-- schema 0019 (2026-10-06, beta.14, D49): pacing (hooked), the present arguments (Direct3D), the card's clocks and limits
-- (both tiers) and efficiency (hooked) — 03_METRICS §Pacing, §Sync, §Sensor aggregates, §Efficiency
time_below_30_pct REAL, time_below_60_pct REAL,
time_below_refresh_pct REAL, -- over presents, at display_monitor_hz; NULL without a rate
frametime_delta_mean_ms REAL, -- mean |ft[k] - ft[k-1]| over neighbouring intervals
vsync_present_pct REAL, tearing_allowed_pct REAL, -- shares of the presents that carried their arguments
avg_gpu_core_clock_mhz REAL, avg_gpu_mem_clock_mhz REAL, avg_gpu_fan_rpm REAL, max_gpu_mem_temp REAL,
power_limit_pct REAL, thermal_limit_pct REAL, -- shares of the ticks that carried reasons: NVIDIA (L3) only
app_frames_per_joule REAL, -- application FPS / average GPU board power; never displayed frames (rule 6)
-- schema 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 0022 (2026-11-06, beta.34, D84): DLSS 5's neural rendering — 05_DETECTION §DLSS generation
dlss_nr_pct REAL, -- 0–100 of the Streamline batches that evaluated kFeatureDLSS_NR; NULL = nothing could tell
-- 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 —
-- N/A, never 0. Written on the recorder's SKELETON: a Tier-2 session never reaches the aggregator.
display_exclusive_ms INTEGER, -- the swap chain SAID exclusive (DXGI only)
display_borderless_ms INTEGER, -- covers its monitor, the chain said not exclusive
display_windowed_ms INTEGER,
display_covers_ms INTEGER, -- covers its monitor and nothing could say which ("fullscreen or borderless")
display_minimized_ms INTEGER,
display_nowindow_ms INTEGER, -- no window could be read
display_changes INTEGER, -- mode changes between samples
display_source TEXT, -- swapchain | opengl | window: the strongest witness any sample had
display_window_w INTEGER, display_window_h INTEGER, -- client area, in the mode that lasted longest (the last seen, beta.27)
display_buffer_w INTEGER, display_buffer_h INTEGER, -- the swap chain's back buffer, same mode
display_monitor_w INTEGER, display_monitor_h INTEGER, display_monitor_hz INTEGER
);
CREATE INDEX ix_sessions_game_started ON sessions(game_id, started_at DESC);
@@ -275,13 +379,29 @@ CREATE TABLE frame_blobs (
-- stored only when either varies
dispatch_rays BLOB, -- uint32[] : ray volume per frame, tier 1 only
pso_created BLOB, -- uint16[] : compile COUNT per frame, not a flag
vram_proc BLOB, -- uint32[] MB per frame; held 1 Hz sample, see 03_METRICS
latency_us BLOB -- uint32[], tier 1 + Reflex only
vram_proc BLOB, -- uint32[] MB per frame; never written (corrected 2026-10-04: the Overlay never produced vramUsedMb)
latency_us BLOB, -- uint32[], tier 1 + Reflex only
first_present_ms REAL -- schema 0013 (beta.8): the dominant stream's first present, ms from qpc_epoch —
-- the sensors' zero (t_ms) against the frames'. NULL before; the charts then
-- keep the sensor overlay off rather than draw it out of step
);
CREATE TABLE sensor_blobs (
session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-- schema 0007 (2026-09-21) added five guard-override columns (games.guard_bypass_at,
-- games.guard_bypass_disclosure_version; sessions.guard_bypassed, guard_bypass_family, guard_bypass_signal) and
-- schema 0008 (2026-09-22) DROPPED them with the feature (19_SAFETY §What a finding does to the game). Sessions that
-- ran under it keep "guard-bypass=" in capture_notes.
series TEXT NOT NULL, -- cpu_temp|gpu_temp|gpu_hotspot|gpu_load|gpu_power|vram_proc|vram_adapter|cpu_load|ram_mb
-- (vram_proc was listed here from 0001 and never written); since schema 0018 (beta.12,
-- D43) also game_vram_dedicated|game_vram_shared|game_ram_private|game_ram_ws|game_commit,
-- MiB — the game process's own memory (Application.Recording.SensorSeriesCatalog); since
-- beta.14 (D49) also gpu_core_clock|gpu_mem_clock (MHz), gpu_fan (RPM), gpu_mem_temp (°C)
-- and gpu_power_limit|gpu_thermal_limit (100 or 0 per tick, NVIDIA only) — a series name
-- needs no migration
-- cpu_load / ram_mb / cpu_temp and sessions.avg_cpu_load, avg_cpu_temp, max_cpu_temp,
-- avg_ram_mb were in schema 0001 with NO producer until 2026-09-21 (Telemetry.SystemTelemetrySource
-- on the poller's tick). Rows before that date hold NULL, which is what they measured; no migration.
hz REAL NOT NULL, codec TEXT NOT NULL, data BLOB NOT NULL,
PRIMARY KEY (session_id, series)
);
@@ -303,11 +423,17 @@ CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
CREATE TABLE legal_acceptance (doc TEXT PRIMARY KEY, version TEXT NOT NULL, accepted_at INTEGER NOT NULL);
```
> **Written since 2026-09-14 (P3 PR-9).** `doc` is one of `eula` / `gpl` / `disclaimer` / `privacy`
> **Written since 2026-09-14 (P3 PR-9).** `doc` is one of `eula` / `gpl` / `disclaimer` / `privacy` *(and `alpha` since
> 2026-10-31, D74: the Alpha notice, written by an alpha build's gate only and read by an alpha's Agent before it serves;
> a beta never reads that row)*
> (`App.Services.LegalDocuments.Keys`); `version` is the document's own `**Version:**` line as embedded in the
> App at build (`GPL-3.0-only` for the licence text) — the App is the only writer, one row per document per
> Accept, re-recorded when the embedded version differs from the row's. `20_OPEN_QUESTIONS` §G "Legal doc
> versioning" closes on that.
>
> **Three rows since beta.12 (D45).** The GPL is shown for information and needs no acceptance (GPLv3 §9), so Accept
> writes `eula`, `disclaimer` and `privacy` only, and the gate is not held open for `gpl`. A `gpl` row an earlier
> version wrote stays, unread (`LegalGate`).
## Settings registry
@@ -325,14 +451,24 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `ui.theme` | choice | `system` | `system` · `light` · `dark` | UI |
| `ui.start_with_windows` | bool | `0` | | UI (P4) |
| `ui.minimize_to_tray` | bool | `0` | | UI (PR-8) |
| `capture.background` | bool | `1` | | Agent |
| `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) |
| `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` | | UI (P4; CLAUDE.md rule 8) |
| `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 |
An operator's bounded capture (`--console … --seconds N`, which lowers the discard threshold to N) keeps
@@ -344,14 +480,17 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
## Blob encoding
`float32`/`uint16`/`uint32` little-endian arrays through `DeflateStream` (Optimal). One hour at 100 fps ≈ 360k frames ≈ 1.4 MB raw frametimes ≈ **≤ 0.7 MB stored**; flags compress far better; render-res only stored when it varies. Decode helpers in `Infrastructure.Blobs` with round-trip test
`float32`/`uint16`/`uint32` little-endian arrays through `DeflateStream` (Optimal). One hour at 100 fps ≈ 360k frames ≈ 1.4 MB raw frametimes ≈ **≤ 0.7 MB stored**; flags compress far better; render-res only stored when it varies. Decode helpers in `Infrastructure.Blobs` with round-trip tests (NaN forbidden — assert).
> **Two rules the finalizer applies (2026-09-10, P2 PR-D).** `frametimes[i]` is the interval from the previous
> record ON THE SAME SWAPCHAIN; the first record of a stream, and any record after a torn slot or an
> overwrite skip, carries 0 with the `frame_flags` gap bit set, so the statistics exclude it and the export
> still reconstructs `qpc_ms`. `swapchain_ids` is present only when the session held more than one stream.
> **Schema 0013 (beta.8)** adds `frame_blobs.first_present_ms`: the charts draw the dominant stream from its first present
> and the sensors from `qpc_epoch`, and nothing said how far apart the two zeros were. Gaps stay closed up on the frame
> axis (a gap's interval is stored as 0), so a series still drifts ahead of its sensors past each gap.
> Sensor series are aligned to `t_ms` (milliseconds from `qpc_epoch`) and a tick with no reading is stored as
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.s (NaN forbidden — assert).
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.
## The `.partial` file
@@ -369,10 +508,11 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> | 1 `Header` | UTF-8 JSON: format version, `session_guid`, `started_at`, `qpc_epoch`/`qpc_frequency`, `game_id`, `snapshot_id`, exe path, pid, tier, mode, Overlay build id, telemetry descriptor, launch wait | on create — the breadcrumb `19_SAFETY` §Crash safety asks for before injection |
> | 2 `Records` | `i64` first ordinal, then N raw `FlFrameRecord` (64 B each); a chunk that does not continue the sequence is refused | each flush |
> | 3 `Gaps` | N × `i32` gap-before record indices | each flush |
> | 4 `Sensors` | N × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null | each flush |
> | 4 `Sensors` | N × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null | ~~each flush~~ read only since beta.12, so a beta.11 file still recovers *(corrected 2026-10-04)* |
> | 5 `Tick` | drain/foreground ticks, dropped, gaps, guard ticks, wall clock, the raw `FlWriterState`; the last one wins | each flush |
> | 6 `Note` | wall clock + UTF-8 text: a state transition | each transition |
> | 7 `Touches` | N × `i64` QPC at which the host touched the target | each flush |
> | 8 `SensorsWide` | the same samples under a 32-bit presence mask that carries the game process's memory (D43) | each flush, since beta.12 *(row added 2026-10-04)* |
>
> Recovery (`PartialRecovery`): a file whose guid is already a row is deleted (the finalize had landed);
> one under the minimum session length is discarded; one with no readable header is dropped; the rest
@@ -380,6 +520,16 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> column computed from the prefix exactly as a live finalize would. **Rejected:** a `sessions_in_progress`
> table — a blob churn every minute, a lock fight with the UI in P3, and `04_CAPTURE` had already named a
> file under `tmp\`.
>
> **The header's `game_id` is where the session started, not necessarily where it lands (2026-09-23).** A live
> finalize and a recovery both ask `ISessionRepository.ResolveOwnerAsync`: that id when the row predates the session
> or holds the header's exe path; else the row that holds the exe path now (an entry removed and re-imported while
> the game ran); else nothing — `FinalizeStatus.GameRemoved` / `RecoveryStatus.GameRemoved`, file deleted, nothing
> written. `games.id` is `INTEGER PRIMARY KEY` without AUTOINCREMENT, so a deleted id can be handed to the next row
> added; `added_at` after the session's start and another path is how that row is told apart. A file recovery cannot
> finalize for any other reason is renamed `<guid>.partial.failed` (`IPartialSessionStore.Quarantine`) — not listed
> again, not retried, kept for a bug report — and recovery goes on to the next file: it runs before the watcher on
> every start, and one file used to be able to stop them all.
## Retention
@@ -399,12 +549,17 @@ Default: raw blobs for the **last 20 sessions per game** (configurable N or unli
## Migrations
Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied at startup by whichever process opens the DB first, guarded by `schema_migrations` + a named mutex. Never edit an applied script; only append.
> **The alpha's copy before it opens the ledger (D73, 2026-10-31).** An alpha build shares this file with the beta, so
> before it first opens it — the App or the Agent, whichever comes first — `LedgerDatabase.OpenAsync(backupFirst:)`
> copies it whole with SQLite's online backup into `backups\ledger-before-<version>.db` beside it
> (`Infrastructure.Persistence.LedgerBackup`), once per alpha version, under a lock of its own
> (`Local\FrameLedger.Ledger.Backup.<hash of the path>`, waited on for five minutes — the migration lock gives a waiter
> 30 s). The newest three copies are kept and only files so named are deleted. A copy that cannot be made — no room, the
> folder unwritable — throws `LedgerBackupException` and the ledger is not opened: the App says so in its start-failure
> dialog, the Agent exits 7 (*ledger refused*) with the reason in its log. The main line passes no request and copies
> nothing; a viewer (D52) reads a copy and makes none. Every case is `LedgerBackupTests`', in scratch folders.
> **`0002_annotation_overrides_and_removal.sql` (P3 PR-3, 2026-09-13) — the first append**, and the first
> time the runner ran two scripts on a real file: `ALTER TABLE ADD COLUMN` only — the three override
> columns on `session_annotations` and `games.removed_at`. `LedgerDatabaseTests` asserts one
> `schema_migrations` row per script, so `LatestVersion` is 2.
Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied at startup by whichever process opens the DB first, guarded by `schema_migrations` + a named mutex. Never edit an applied script; only append.
> **`0002_annotation_overrides_and_removal.sql` (P3 PR-3, 2026-09-13) — the first append**, and the first
> time the runner ran two scripts on a real file: `ALTER TABLE ADD COLUMN` only — the three override
@@ -422,25 +577,206 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
> which are the consent fingerprint the gate reads and which a background scan must never refresh.
> `LatestVersion` is 4; `LedgerDatabaseTests` asserts the columns.
> **`0005_fg_refusal_detail.sql` (2026-09-16) — `sessions.fg_refusal_detail`.** 0003 recorded WHICH refusal took the
> factor; the owner's Dashboard then showed "DLSS-G active — factor not counted" on four titles with a tooltip that
> could only say "the frame-generation state changed mid-session", while `FgWindow` had computed which of the eight
> buckets departed, its ratio and the window's, and `SessionAggregator` kept only the kind. The column is
> `Application.Recording.FgRefusalDetail` as JSON (`RecordingJsonContext`): kind, subject, count, bucket index/count,
> the bucket's ratio (null when it held no tokens — infinity is not JSON) and the window's. Written by the Agent
> beside `fg_refusal`, read by the UI's tooltip (`FpsPresentation.RefusalDetailText`), never an input to a number.
> Existing rows keep NULL. `LatestVersion` is 5; `LedgerDatabaseTests` asserts the column.
> **`0006_fg_steady_state.sql` (2026-09-17) — `sessions.fg_factor_scope` / `fg_steady_share`.** `fg_factor` was
> session-wide or NULL, and on real play it was almost always NULL (`03_METRICS` §The steady state). `session` = one
> state for the whole claimed span; `steady` = `fg_factor` / `native_fps` / `displayed_fps` describe the state the
> session spent most of its generating time in, `fg_steady_share` of the presenting time, with `fg_refusal` and its
> detail still set beside it. A reader that ignores the scope reads a steady factor as a session one, which is why
> every surface prints the share. Existing rows keep NULL. `LatestVersion` is 6.
> **`0007_guard_bypass.sql` (2026-09-21) and `0008_withdraw_guard_bypass.sql` (2026-09-22) — the first DROP.** 0007
> added five columns for the per-game guard override; the owner withdrew the feature a day later and 0008 drops them
> (`ALTER TABLE … DROP COLUMN`, SQLite ≥ 3.35 — `LedgerDatabaseTests` asserts the engine's version beside the columns'
> absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The
> data dropped is the override acknowledgements themselves, which is the decision. `LatestVersion` is 8.
> **`0009_record_sessions.sql` (2026-09-23, D29) — `games.record_sessions`** *(entry added 2026-10-04; it was
> missing)*. FR-1.6's recording switch, `NOT NULL DEFAULT 1`; the App writes it, the Agent only reads it. Its one data
> change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools` as of the
> script). `LatestVersion` is 9; `LedgerDatabaseTests.ScriptNineAddsTheRecordingSwitchOffForSteamToolsOnly`.
> **`0010_prescan_key.sql` (2026-09-25) — `games.hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` /
> `hook_prescan_exe_mtime_ms`.** The Agent pre-scans every library entry for anti-cheat since beta.8, and again
> whenever the rules or the executable change, so it needs what each row was last scanned against — its own key, as
> 0004's columns are the detection sweep's, and apart from `exe_size_bytes` / `exe_mtime_ms` for the same reason
> (the consent fingerprint must never be refreshed by a background scan). `ALTER TABLE ADD COLUMN` only; existing
> rows read NULL, which the sweep reads as "never scanned" and scans on its first pass. `LatestVersion` is 10;
> `LedgerDatabaseTests.ScriptTenAddsThePreScanKeyEmptyForExistingRows` applies it from 9 to a ledger holding a row.
> **`0011_executable_facts.sql` (2026-09-25) — `games.exe_machine` / `exe_file_version` / `exe_product_version` /
> `library_versions`.** The owner asked for the game's version, its DLSS / FSR versions and 32- or 64-bit; the detection
> sweep read the PE version resource and walked the tree for the capability files, and kept neither. Four columns,
> written whole by that sweep (`05_DETECTION` §What the files say about themselves) — facts about files, so no
> provenance and no user override. Existing rows read NULL, and a NULL `exe_machine` makes the sweep read the row once
> more on its first pass. `LatestVersion` is 11; `LedgerDatabaseTests.ScriptElevenAddsTheExecutableFactsEmptyForExistingRows`.
> **`0012_driver_profile.sql` (2026-09-25) — `sessions.driver_profile`.** The NVIDIA driver profile the session's
> executable ran under, read by the Agent's recorder beside every session (both tiers) through the NVAPI bridge's
> read-only DRS entry point (`18_GPU_VENDOR_APIS` §L3, ABI 2): JSON (`Application.Recording.DriverProfileRecord`) —
> `Outcome` (`Application` | `Global` | `Degraded`), `Profile`, and one entry per setting of
> `Application.Capture.NvidiaDriverSettings` with its `Value` (null = set in no profile), `Location` and `Predefined`.
> A driver configuration, never a measurement (`03_METRICS` §Upscaling). NULL for every row before, and where no
> NVIDIA bridge was there to ask. The same day `ngx_driver_words` gained `Ratio`, `Mode`, `Preset`, `FgCount`,
> `FgPreset`, `FgMode` beside its masks (additive JSON fields; older rows lack them). `LatestVersion` is 12;
> `LedgerDatabaseTests.ScriptTwelveAddsTheDriverProfileColumn`.
> **`0013_first_present.sql` (beta.8, 2026-09-25) — `frame_blobs.first_present_ms`** *(entry added 2026-10-04; it was
> missing)*. The charted stream's first present, in milliseconds from `qpc_epoch`, written by the finalizer
> (§Blob encoding); NULL before, and such a row's sensor overlay stays off rather than drawn out of step. `LatestVersion`
> is 13; `LedgerDatabaseTests.ScriptThirteenAddsTheFirstPresentColumn`.
> **`0014_usermode_ac_exception.sql` (beta.9, 2026-09-26, owner decision D33) — the user-mode anti-cheat exception.**
> Fourteen `games.ac_exception_*` columns in three groups — the Agent's eligibility answer about a blocked row and its
> key, the user's grant, and how the last grant ended — and `sessions.ac_exception_family`, the family a HOOKED session
> ran under the exception with. `ADD COLUMN` only; no row changes, so a blocked row stays blocked, not eligible, with
> no grant, until the Agent and the user say otherwise (`19_SAFETY` §The user-mode exception). Written through
> `IGameConsentStore` only — `RecordExceptionEligibilityAsync` (the sweep), `GrantAntiCheatExceptionAsync` (the
> `SetAntiCheatException` command; the store applies `UserModeExceptionRules.IsEligible` itself), `RevokeAntiCheatExceptionAsync`
> (every end) — plus one downgrade in `ChangeExecutableAsync`, which ends a grant (`ExecutableChanged`) and forgets
> the eligibility. The grant and the eligibility are each bound in SQL to the block they were reached about. `LatestVersion`
> is 14; `LedgerDatabaseTests.ScriptFourteenAddsTheExceptionColumnsAndChangesNoRow`.
> **`0015_engine_version_source.sql` (beta.10, 2026-09-27) — where an engine version came from.** `games.engine_version_source`
> (`05_DETECTION` §Engine version): the witness an Unreal version rests on, or the rule's extractor type for every other
> engine; written by `ApplyDetectionAsync` only where the run's version was taken (a `user` field keeps none), cleared by a
> user's edit of the version (`UpdateMetadataAsync`). The script's one data change removes the bare `4` / `5` the old
> Unreal rule wrote (a two-group regex returning its first group) — **only where `field_provenance` says `detected`**: a
> value the user typed, one with no badge (which reads as the user's) and one whose provenance does not parse stay as they
> were, and the last does not fail the migration (`CASE WHEN json_valid(…)`, since SQLite promises no order for `AND`).
> `LatestVersion` is 15; `LedgerDatabaseTests.ScriptFifteenAddsTheWitnessAndRemovesOnlyTheOldRulesDetectedDigit`.
> **`0016_display_mode.sql` (beta.10, 2026-09-27) — how the game was shown.** Fifteen `sessions.display_*` columns
> (`03_METRICS` §Display mode): milliseconds in each mode, the changes, the witness, and the window / back buffer / monitor
> sizes in the mode that lasted longest. ADD COLUMN only, no data change: a session recorded before reads N/A. Written by
> the recorder on the row's skeleton (`Recording.SessionDisplayColumns.WithDisplay`), so a Tier-2 session — which never
> reaches the aggregator — has them too; `sessions.swap_effect`, a column since 0001, gets its first writer from the same
> facts. `SessionRowColumns` is hand-edited (its generator is not in the repository) and reads by name. `LatestVersion` is
> 16; `LedgerDatabaseTests.ScriptSixteenAddsTheDisplayColumnsAndAnEarlierSessionHasNone`,
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`.
> **`0017_exception_trial.sql` (beta.11, 2026-10-03, owner decision D38) — the exception's trial.** One column,
> `games.ac_exception_trial_failed_at`: when an exception of the game ended during its trial (`19_SAFETY` §The user-mode
> exception), NULL when none did. ADD COLUMN only, no data change: a grant made under D33 stays in force and carries no
> mark. Written by the Agent's revoke only (`IGameConsentStore.RevokeAntiCheatExceptionAsync(…, trialFailed)`), set once
> (`COALESCE`), cleared by nothing — not by `ChangeExecutableAsync`, which does not name it — and carried by a twin merge
> (the earlier of two). The store applies it in SQL: no eligibility is written as eligible and no grant is written over
> it. `ac_exception_sessions` (0014) changes meaning without a script: since D38 it is the trial's progress under the grant
> in force, which the sweep rewrites on its first pass. `LatestVersion` is 17;
> `LedgerDatabaseTests.ScriptSeventeenAddsTheTrialMarkAndChangesNoRow`,
> `SqliteGameConsentStoreTests.AnEndDuringTheTrialMarksTheGameAndNothingClearsIt`,
> `SqliteGameMergeTests.AFailedExceptionTrialOnEitherTwinMarksTheSurvivor`.
> **`0018_game_memory.sql` (beta.12, 2026-10-03, owner decision D43) — the game process's own memory.** Twelve
> columns, ADD COLUMN only: `game_vram_dedicated_{avg,median,max}_mb`, `game_vram_shared_max_mb`,
> `game_ram_private_{avg,median,max}_mb`, `game_ram_ws_max_mb`, `game_commit_max_mb`, `game_memory_processes`,
> `game_memory_source` and `sensor_stats_json`. Written by the recorder's aggregation for both tiers
> (`SessionAggregator.WithSensorAggregates`); a session before it reads N/A. **Not `vram_proc_*`**: those name the
> in-process DXGI figure compared with a budget (a different quantity, `03_METRICS` §Game process memory) and stay
> reserved. The `.partial` gains chunk type 8 (`SensorsWide`, a 32-bit mask with the game fields); type 4 is still read,
> so a beta.11 crash file recovers. `LatestVersion` is 18; `LedgerDatabaseTests.ScriptEighteenAddsTheGameMemoryColumnsAndAnEarlierSessionHasNone`,
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`,
> `PartialSessionFileTests.TheGameMemoryRoundTripsAndANarrowSensorsChunkFromBeta11StillReads`.
> **`0019_pacing_sync_gpu_limits.sql` (beta.14, 2026-10-06, owner decision D49) — pacing, sync, the card, efficiency.**
> Thirteen REAL columns, ADD COLUMN only: `time_below_{30,60,refresh}_pct`, `frametime_delta_mean_ms`,
> `vsync_present_pct`, `tearing_allowed_pct`, `avg_gpu_{core,mem}_clock_mhz`, `avg_gpu_fan_rpm`, `max_gpu_mem_temp`,
> `power_limit_pct`, `thermal_limit_pct`, `app_frames_per_joule`. Written by the recorder's aggregation
> (`SessionAggregator.ApplyPacing` / `ApplySync` / `ApplyEfficiency` for a hooked session, `WithSensorAggregates` for the
> card on both tiers); `sync_interval_mode` (0001) gets its first writer beside them. A session before it reads N/A — no
> value is computed after the fact. The `.partial` needs no change: the six new sensor series are fields every sample
> already carried. `LatestVersion` is 19; `LedgerDatabaseTests.ScriptNineteenAddsThePacingAndCardColumnsAndAnEarlierSessionHasNone`,
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`. **A beta.13 cannot open a ledger beta.14 migrated.**
> **`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. **Read by today's rule since beta.26:** `FgMixRecord.Parse` folds a stored state no window of the build
> would form (above ×8, or under eight application frames a window) into the not-classified time — beta.24 and beta.25
> stored one (`spike-notes` §22). `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.
> **`0022_dlss_nr.sql` (beta.34, 2026-11-06, owner decision D84) — DLSS 5's neural rendering, measured.** One REAL column,
> ADD COLUMN only: `dlss_nr_pct`, the share (0–100) of the presents that drained a Streamline evaluation on which the game
> evaluated `kFeatureDLSS_NR` (`Domain.Metrics.NeuralRendering`). Written by the recorder's aggregation
> (`SessionAggregator.ApplyRt`) **only when the writer published `FL_HOOK_SL_NEURAL_RENDERING`** — an Overlay older than
> the script drains the same batches and never sets the bit, so its NULL is "could not tell", never 0. NULL before, and
> never rebuilt (`frame_blobs` keep no feature byte); a session recovered from its crash file is re-aggregated from its
> raw records and keeps it. `LatestVersion` is 22;
> `LedgerDatabaseTests.ScriptTwentyTwoAddsTheNeuralRenderingColumnAndAnEarlierSessionHasNone`, the repository round trip.
> **A beta.33 or alpha.2 cannot open a ledger beta.34 migrated** (the alpha keeps its copy first, D73).
> **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
> `MigrationRunner`, and a refusal (`LedgerSchemaException`) for a schema **older** than the build as well as newer —
> the older file needs the App or `--serve` to bring it forward, not a verb whose name says it reads. The Agent's
> `sessions`, `consent list` and `killswitch status` open that way (`Program.PrintsOnly` is the list, pinned by
> `AgentReadOnlyVerbsTests`), `db path` opens nothing, and the App's `--diag` does the same.
>
> **What that run found, recorded because the mechanism is not known.** The on-disk `ledger.db` was 94 KB, 23 pages,
> dated 14 September, at schema 2 with three test games and no sessions; the day's 41 imported games and 18 sessions
> were in `ledger.db-wal` — 4 MB, 1006 frames — and every one of those frames carried salt-1 one **lower** than the
> WAL header's, with a checkpoint sequence of 1 and a single frame under the new salt. That is the shape SQLite leaves
> after a checkpoint has moved every frame into the main file and the next writer restarts the log; but no checkpoint
> had reached this main file (645 pages of data, 23 on disk, and the file's own time stamp two days old). A fresh
> connection therefore recovered one frame and saw the 14 September state, while the App and Agent that were running
> saw the whole day through the wal-index they shared. Neither process closed cleanly enough to fix it: the Agent's
> stop at 17:57 and the console's exit at 17:58 both left the WAL in place, and `-wal`/`-shm` then vanished between
> 18:00 and 18:04 with no FrameLedger process alive. The data was rebuilt by applying the old-salt chain to the main
> file (176 commits, `integrity_check` ok) and the broken set kept beside it. **Nothing in this repository writes the
> main file behind SQLite's back, replaces it, or restarts the WAL by hand**; what the code can do about an unknown
> mechanism is make the next occurrence visible, and it does: `OpenAsync` runs `wal_checkpoint(PASSIVE)` after
> migrating and logs the frame count it found and moved (`LedgerDatabase.OpenDiagnostics`), and `DisposeAsync` runs
> `wal_checkpoint(TRUNCATE)` and logs that, so a clean close leaves the main file complete and a WAL that will not
> checkpoint is a logged number rather than a silent one. A WAL at open holding frames a passive checkpoint cannot
> move, with no other FrameLedger process running, is the signature to look for.
> **Built 2026-09-09 (P2 PR-B):** `Infrastructure.Persistence.MigrationRunner` over scripts embedded in
> the assembly (so the schema a build applies is the one it was tested against), one transaction per
> script, under `Local\FrameLedger.Ledger.Migrate` — session-local rather than `Global\`, because the
> Agent and the UI share a session and the global namespace asks for a privilege a standard user need
> not hold. **A ledger at a version newer than the build's scripts is refused, not read**
> not hold. *(One name per ledger FILE since 2026-09-17 — `Migrate.<hash of the path>`,
> `MigrationRunner.LockNameFor`: with one name for every ledger, a test process frozen mid-migration held
> every other process's scratch ledger, and seven App and Agent tests failed after 30 s on #199's run.)* **A ledger at a version newer than the build's scripts is refused, not read**
> (`LedgerSchemaException`): guessing at a schema we do not understand is the one option that could
> turn a newer file into wrong answers. `LedgerDatabase` opens with the four pragmas above, one
> connection per process behind a gate, and every write in an explicit transaction — a failing blob
> insert leaves no session row behind (`SqliteSessionRepositoryTests`).
**`0001_init.sql` creates the schema above directly.** There is no v1 → v2
upgrade path, because there is no released v1: nothing has shipped, so no
FrameLedger database exists anywhere in the world. Writing and testing a
upgrade path, because there is no released v1: ~~nothing has shipped, so no
FrameLedger database exists anywhere in the world~~ *(corrected 2026-10-04: eleven pre-releases shipped from
0.1.0-beta.1 on 2026-09-16, and the appended scripts carry their ledgers forward; no schema older than 0001 ever
shipped, so there is still no v1 → v2 path)*. Writing and testing a
migration from a schema that never existed is work with no user on the other end
of it. The `schema_migrations` machinery still ships from day one — it is what
makes the *next* migration safe, and `11_UPDATER` §Versioning already requires
migrations to cover every released `MAJOR-1`. That obligation begins at the first
release, not before it.
migrations to cover every released `MAJOR-1`. ~~That obligation begins at the first
release, not before it.~~ It began with 0.1.0-beta.1.
## Hardware change markers (FR-6.3)
Snapshot captured per session, hashed, deduped. Trend queries join consecutive sessions' snapshots; differing fields emit a marker `{after_session_id, field, old, new}`. GPU driver version now comes from the vendor API (`18_GPU_VENDOR_APIS`) rather than WMI, which makes it accurate enough to be worth charting.
Snapshot captured per session, hashed, deduped. Trend queries join consecutive sessions' snapshots; differing fields emit a marker `{after_session_id, field, old, new}`. GPU driver version now comes from ~~the vendor API (`18_GPU_VENDOR_APIS`)~~ DXGI's four-part user-mode driver version (`HardwareSnapshotSource`; corrected 2026-10-04) rather than WMI, which makes it accurate enough to be worth charting.
+146 -20
View File
@@ -1,24 +1,28 @@
# 07 — IPC
Three channels, each chosen for its constraints:
~~Three~~ Four channels, each chosen for its constraints *(corrected 2026-10-04: §D, the tolerance mapping, arrived
in beta.9 without a row here)*:
| Channel | Between | Transport | Why |
|---|---|---|---|
| **A. Frame ring** | Overlay DLL → Agent | Shared memory, lock-free SPSC | Hot path: no syscall allowed |
| **B. Control block** | Agent ↔ Overlay DLL | Same shared memory, atomics | Tiny, infrequent, must work even if the game is unresponsive |
| **C. Command pipe** | UI ↔ Agent | Named pipe, JSON | Rich, versioned, human-debuggable |
| **D. Tolerance mapping** | Agent → Overlay DLL, once, before injection | Its own shared memory, read-only to the Overlay | Must exist before the Overlay's loader detour does (§D, D33) |
## A + B — shared memory (`Local\FrameLedger.Ring.<pid>`)
Created by the Overlay on init, opened by the Agent. Name is deliberately plain and identifiable (`19_SAFETY` — no obfuscated object names).
Layout — **four regions, each exactly one 64-byte cache line before the ring**:
Layout — **~~four~~ five regions, each exactly one 64-byte cache line before the ring** (layout 4 since
2026-09-27, beta.10: region 4 is new and the ring moved from `0xC0` to `0x100`):
```
[0x0000] FlShmHandshake 64 B write-once by the Overlay at init
[0x0040] FlWriterState 64 B Overlay-written (writeIndex touched every present)
[0x0080] FlControlBlock 64 B Agent-written
[0x00C0] FlFrameRecord[capacity] (64 B each, power-of-two capacity)
[0x00C0] FlDisplayState 64 B Overlay-written, at most every 500 ms per chain (layout 4)
[0x0100] FlFrameRecord[capacity] (64 B each, power-of-two capacity)
```
The header is split in two on purpose. The immutable handshake and the
@@ -49,9 +53,19 @@ struct alignas(64) FlWriterState { // Overlay-written
uint32_t rtStateObjectsCreated; // @32 session count, published at 1 Hz
uint32_t rasterPsoCreated; // @36 session count, published at 1 Hz
uint32_t runtimeCensus; // @40 FlRuntimeCensus bits; watchdog-published, OR-only (2026-09-03, took reserved[0])
uint32_t reserved[5]; // @44..63 must be zero; reserved for additive fields
uint32_t slTagCensus; // @44 FlSlTagType bits per route (2026-09-05)
uint32_t dxgiPresentsUnseen; // @48 presents DXGI counted beyond the hooked ones (2026-09-05, saturating)
uint32_t dxgiPresentSamples; // @52 hooked presents on which that counter was read
uint16_t loaderSignals; // @56 the LoadLibrary detour's installed bit + wake count (2026-09-06)
uint16_t earlyStopFamily; // @58 1-based floor family index of an early stop; 0 = none (2026-09-06)
uint32_t dxgiPresentsBeforeHook; // @60 presents before the first hooked one (2026-09-06) -- the LAST word:
// no slack left, so layout 4 added a region rather than a field
};
> **This block showed `reserved[5]` at @44 until 2026-09-27** — five words the header had spent by 2026-09-06
> (`slTagCensus`, the two DXGI counters, the loader words, `dxgiPresentsBeforeHook`). `fl_shm.h` is normative and the
> mirror test reads the header, so nothing broke; a reader of this page was told there was room where there was none.
struct alignas(64) FlControlBlock { // Agent-written
uint32_t pauseRequested; // @0
uint32_t unhookRequested; // @4 19_SAFETY: set when the guard fires mid-session
@@ -61,12 +75,41 @@ struct alignas(64) FlControlBlock { // Agent-written
uint32_t reserved[11]; // @20..63 must be zero
};
struct alignas(64) FlDisplayState { // Overlay-written (layout 4, 2026-09-27, beta.10)
uint32_t seq; // @0 seqlock: odd while a writer is inside; the writer CASes and SKIPS if taken
uint32_t flags; // @4 FlDisplayFlags: SAMPLED | EXCLUSIVE_KNOWN | EXCLUSIVE | OPENGL
uint64_t hwnd; // @8 OutputWindow (DXGI) or WindowFromDC (OpenGL); 0 = a composition chain
uint32_t bufferWidth; // @16 the back buffer (DXGI) / client area (OpenGL)
uint32_t bufferHeight; // @20
uint32_t swapEffect; // @24 DXGI_SWAP_EFFECT + 1 (DISCARD is 0); 0 = not read
uint32_t swapFlags; // @28 DXGI_SWAP_CHAIN_DESC.Flags
uint32_t chainId; // @32 the FlFrameRecord.swapchainId described
uint32_t samples; // @36 samples published (wraps)
uint64_t sampleQpc; // @40 QPC of the last sample
uint32_t reserved[4]; // @48..63 must be zero
};
static_assert(sizeof(FlShmHandshake) == 64);
static_assert(sizeof(FlWriterState) == 64);
static_assert(sizeof(FlControlBlock) == 64);
static_assert(FL_SHM_RING_OFFSET == 0xC0 && FL_SHM_RING_OFFSET % 64 == 0);
static_assert(sizeof(FlDisplayState) == 64);
static_assert(FL_SHM_DISPLAY_OFFSET == 0xC0 && FL_SHM_RING_OFFSET == 0x100 && FL_SHM_RING_OFFSET % 64 == 0);
```
**Region 4 — the presenting swap chain's display facts (layout 4, 2026-09-27, beta.10).** The owner asked for the game's
window size and display mode (exclusive fullscreen / borderless / windowed) and the share of a session each took. The two
facts only the process knows — whether the chain is in exclusive fullscreen, and which window it presents to — are
getters on the chain the title passed to the hooked Present (`GetFullscreenState`, `GetDesc`), asked at most every 500 ms
per chain; everything else — the window's rectangle and style, its monitor, the classification — is the Agent's, read
out of process with user32 at the drain tick, exactly as the foreground sample is (`03_METRICS` §Display mode). The
region describes ONE chain: the largest back buffer, and a chain silent for 2 s gives way; `chainId` names it. It is a
seqlock the writer never waits on — a writer that finds `seq` odd (another presenting thread inside) skips the sample and
the next present retries — and `ShmRingReader.DisplayState` takes a copy between two reads of an even, unchanged `seq`
(eight attempts, then null for that tick). The Vulkan layer never writes it (all zeros: nothing sampled); an OpenGL stream
writes the window and client size with no exclusive bits, which a reader treats as *unknown*, never as *windowed*. A
minimised game presents only `DXGI_PRESENT_TEST`, which the hook drops before sampling, so a `sampleQpc` older than 2 s
leaves the exclusive bits unknown.
The cross-process fields are declared as plain integers and accessed through
`std::atomic_ref` rather than as `std::atomic<T>` members. `std::atomic<T>` has
no guaranteed layout, cannot be memcpy'd, and cannot be mirrored by a C#
@@ -260,6 +303,28 @@ same class of bug as record drift.
Agent is inert from the beginning rather than enjoying a grace window.
- If `unhookRequested` is set, the Overlay disables hooks within one frame and sets `status = unhooked`. This path must be the fastest, most-tested code in the DLL: it is the safety stop.
## D — the tolerance mapping (`Local\FrameLedger.Tolerate.<pid>`), D33 (2026-09-26)
Agent → Overlay, once, BEFORE the injection it concerns: the anti-cheat family NAMES a game's user-mode exception
covers (`19_SAFETY` §The user-mode exception). It cannot live in A + B: the Overlay creates that mapping on init and the
Agent opens it afterwards, while the Overlay's loader detour must know the tolerance from the moment it exists.
```cpp
struct FlTolerance { // fl_tolerance.h; 16 + 8 x 64 = 528 B, no padding
uint32_t magic; // @0 FL_TOLERANCE_MAGIC ("FLTL")
uint32_t version; // @4 FL_TOLERANCE_VERSION (1)
uint32_t count; // @8 names used, <= 8
uint32_t reserved; // @12 zero
char families[8][64]; // @16 NUL-terminated ASCII family names
};
```
Created by the Agent for the game's pid, current user only, held for the session; read once by the Overlay's
`InitThread` before `InstallLoaderHook`, which resolves every name against its own compiled floor and honours only a
user-mode family. Absent, malformed or naming anything else: nothing is tolerated. Mirrored as `FlTolerance` /
`ToleranceLayout` in `FrameLedger.Shared` and held to the native layout by `ShmLayoutMirrorTests` through
`fl-layout-dump`. *(Built in beta.9: PR-1, the Overlay reads it; PR-2, the Agent writes it — `Infrastructure.Capture.OverlayToleranceChannel`, security descriptor `O:<user>D:P(A;;GR;;;<user>)` stated rather than defaulted (an elevated Agent's default DACL omits the user, and the Overlay in an unelevated game could not open it), a name that already exists refused as not ours, and a channel that cannot be published is no exception: the session then names no family and the blocked game is refused as before.)*
## C — command pipe (`\\.\pipe\FrameLedger.v2`)
Unchanged in spirit from v1, bumped to `v2` for the new message set.
@@ -291,7 +356,24 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
SDDL `D:P(A;;GA;;;<user SID>)(A;;GA;;;BA)` on the instance — `PipeAccessControl.Sddl`, what `20_OPEN_QUESTIONS`
§G asked for — and the token check by impersonation on the client's FIRST frame, because the kernel refuses
`ImpersonateNamedPipeClient` before the client has written; a stranger is disconnected without an answer and
counted. The client side uses `PipeOptions.CurrentUserOnly`, the mirror check on the server's owner.)*
counted. ~~The client side uses `PipeOptions.CurrentUserOnly`, the mirror check on the server's owner.~~)*
> **Amended 2026-09-17: the owner is stated, and the client compares it with its token USER.** The SDDL is now
> `O:<user SID>D:P(A;;GA;;;<user SID>)(A;;GA;;;BA)`. Left to default, a pipe's owner is its creator token's default
> owner, and an elevated token's is `BUILTIN\Administrators` — measured on the owner's machine that morning: the log
> files the elevated Agents created are owned by Administrators, the unelevated ones' by the user.
> `PipeOptions.CurrentUserOnly` compares the pipe's owner with the client token's default OWNER
> (`NamedPipeClientStream.ValidateRemotePipeUser` in dotnet/runtime), so an App started as administrator refused the
> user's own unelevated Agent, silently, as though none were there, and started another on every connect round
> (`01_ARCHITECTURE` §Lifecycle). The client connects without that option and calls
> `PipeAccessControl.RequireOwnedByCurrentUser` before it writes a byte; `PipeServerClientTests` pins the owner and
> drives both directions on a token that owns as Administrators (CI's elevated runner — an unelevated run skips it).
>
> **Accept failures back off.** An instance that cannot be created is retried 250 ms doubling to 10 s and logged on
> the first failure, on a change of error and at 10, 100, 1000… in a row, with the Win32 error. The three extra
> Agents of that morning logged the bare "accept failed" every 260 ms for four hours, 2 MB each. The error is read
> with `GetLastSystemError`: CsWin32 0.3.298 declares `CreateNamedPipeW` without `SetLastError`, so
> `GetLastPInvokeError` read 0.
- Framing: 4-byte LE length + UTF-8 JSON, max 1 MB. `System.Text.Json` source-generated contexts in `FrameLedger.Shared`.
*(Header and body go out in one write, so on the message-mode pipe one frame is one message; the reader
reassembles by length alone. Over the cap, or a stream ending inside a frame, is `IpcFramingException`.)*
@@ -300,29 +382,36 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
makes an additive field safe.)*
- A request the Agent cannot answer gets `Error { code, message }` with the request's `id`: `UnknownType`,
`Malformed` (no `id` when the envelope itself could not be read), `ProtocolMismatch`, `HandlerFaulted`. The
connection survives all four.
connection survives all four. *(Added 2026-10-04: `SetHookEnabled` and `SetAntiCheatException` also answer
`Error UnknownGame` — no row has that id — and `Error ExecutableUnreadable` — nothing scanned, stamped or granted;
the App branches on the second.)*
### Messages
| Type | Dir | Payload / notes |
|---|---|---|
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. `vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered) and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` |
| `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`. *(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.)* |
| `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) · `PackagedGame` (beta.33, D80: the executable's install root is a GDK package root — a game the Xbox app or the Microsoft Store installed, which Windows starts through its package and never by its path, `spike-notes` §25; nothing is started, and the App says to start it from the Xbox app or the Start menu. The App hands such a game to Windows itself and sends this only when it found no package record for it. Additive: an older App says the unknown outcome as a failure). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). **Since D33 (2026-09-26):** for a blocked game whose user-mode exception is in force for the executable on disk (the option on, a grant made on these bytes, the block naming that family) the pre-scan NAMES the family, and a pass under it is stamped as ever and answered `prescan: "exception"`; a finding about the game under it also ends the exception. |
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — ~~the successful Tier-1 sessions (`Refused { reason: "TooFewSessions", signal: <count> }` under two)~~ *(D38, 2026-10-03: no session is needed)*; a game an exception of which ended during its trial is refused before anything is scanned (`Refused { reason: "TrialFailed", family, signal: <unix ms> }`); a tolerant pre-scan of the executable on disk naming the block's family (`Refused { reason, family, signal }` unless the guard let exactly that family through) — and the store writes the grant only over facts that make the game eligible, and never over a failed trial → `AntiCheatExceptionAck { granted, outcome, family }`. **A grant turns nothing on**: hooking is FR-2.1's `SetHookEnabled`, afterwards. Not answered (`UnknownType`) by an Agent composed without the exception. |
| `PauseCapture` / `ResumeCapture` | UI→A | global → `PauseAck { paused }`; `StatusAck.paused` reports it. *(Built 2026-09-13, PR-1b: one in-memory flag, `CapturePause`, read by every session loop at its tick and told to the ring once per transition; supervision — the guard scan, the kill switch, the safety stop — never pauses. Not persisted: an Agent that restarts resumes.)* |
| `StopSession` | UI→A | `{ sessionGuid }` — graceful ~~unhook~~ stop + finalize → `StopAck { sessionGuid, accepted, reason? }`. *(Built 2026-09-13, PR-1b: the orchestrator names every session it starts and cancels THAT session's stop token; the loop reads it at its next tick, drains once more, and ends as `SessionEndReason.StoppedByUser` — `exit_status = normal`, the row stored like any other, the target left running. A guid nobody runs is `accepted: false`. Distinct from the host's cancellation, which leaves a `.partial`.)* |
| `UpdateRules` | UI→A | **no payload** — a trigger, not a source. The Agent re-reads only its own `%LOCALAPPDATA%\FrameLedger\rules\` copy → `UpdateRulesAck { outcome }`. *(Built 2026-09-13, PR-1b: the seeder's `EnsureSeededAsync` outcome; a payload naming a path is ignored, and a test sends one to prove it.)* |
| `Shutdown` | UI→A | graceful stop → `ShutdownAck`, then the host stops (sessions finalize inside its grace window). *(Built 2026-09-13, PR-1b: `IAgentLifetime`, the host's under `--serve`, a logged no-op under `--console`.)* |
| `DeleteSessions` | UI→A | **Added 2026-10-03 (beta.11, D40).** `{ gameId? }` — every session of that game, or of every game when it is null, with their segments, frame and sensor series and annotations (they cascade) → `DeleteSessionsAck { gameId?, games, sessions }`. `Error SessionRunning` and nothing deleted while a session of that game — of any game, for all — is being recorded (`CaptureOrchestrator.IsRecording` / `IsRecordingAny`). The client names no rows beyond the game: they are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the App says as "restart the agent". Carries no safety fact. |
| `SweepRetention` | UI→A | **no payload** — a trigger, like `UpdateRules`: the Agent applies `06_DATA_MODEL` §Retention to every game with the `retention.raw_sessions_per_game` it reads itself → `SweepRetentionAck { keep, games, sessions }` (`keep` 0 = unlimited, and then nothing was swept). *(Built 2026-09-15, P4 PR-7, for Tools ▸ Database maintenance: `Application.Recording.RetentionSweep` over `ISessionRepository.SweepRetentionAllAsync`, composed into `AgentCommandHandler` under `--serve`. The client names no number because the rows are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the dialog reads as "restart the Agent". Carries no safety fact.)* |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt }` — **published at the attach**, i.e. when the session becomes Tier 1 and the live card has something to show; a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2) and, when a refusal or error caused that, the event below that names it |
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus? }` — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **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 }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason` |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal? }` — **guard fired**; UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal? }` — anti-cheat appeared mid-session; prominent UI notice. *(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.)* |
| `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). *(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.)* |
| `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). **`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~~ **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 |
## The pipe is not a trust boundary
@@ -363,10 +452,47 @@ message, and that message always re-scans.
## Client behavior (UI)
- Connect with 250 ms × 8 backoff; on failure start the Agent, retry; then show an Agent status banner with Repair.
- **The running sessions are the status's, then the events' (2026-09-23).** Every list of running sessions the App
keeps is seeded from `StatusAck.activeSessions` on every (re)connect and moved by `SessionStarted` /
`SessionCompleted` after that; a lost Agent empties it. The Dashboard reads the App-lifetime `LiveSessions`
service (it is rebuilt per visit, so a list of its own would start empty); the tray and the updater seed their
own from the same status. Before this a Dashboard opened after a game started read "Nothing is being captured.",
the tray stayed idle for a session that began before the App connected, and the updater held an update at
*Deferred* on a status read hours earlier.
- Connect with 250 ms × 8 backoff; on failure start the Agent, retry; then show an Agent status banner with ~~Repair~~ Retry *(corrected 2026-10-04)*.
> **Amended 2026-09-17: never a second Agent.** A round that ends without a connection starts one only when no
> process holds the user's data folder (`AgentInstanceLock`, probed through `IAgentLauncher.RunningAgent`) and the
> Agent this App started last has exited. Otherwise it starts nothing and logs why the connect failed and that it
> is not starting another — once per distinct reason, not once per round (`AgentConnection.LastConnectFailure`;
> before this the reason was swallowed, and a refusal looked exactly like an absent Agent). The Agent it does start
> is watched until it exits and its exit code logged, so exit 10 — the folder was already claimed — is visible in
> the App's log. `AgentConnectionTests` pins both.
> **Amended 2026-09-27 (beta.10, the admin mode, D34): a start may ask Windows first.** With `capture.run_elevated` on
> and this App a standard user's, the start is a UAC prompt owned by the App's window (`IAgentLauncher.WillAskForElevation`
> turns the pill into *Waiting for administrator permission*), and while it is up the folder's `ElevationMarker`
> (`Local\FrameLedger.Agent.Elevating.<hash>`) is held — `RunningAgent` reads it as "an Agent is coming", so the App never
> prompts beside the logon task's Agent, which holds the same marker while its own prompt waits on the taskbar. A declined
> prompt starts the standard user's Agent with `--elevation declined`; an elevated Agent that exits 11 (another account
> answered) makes the App start standard-user Agents until it restarts.
- **Named objects an elevated process creates state their DACL (beta.10).** An elevated token's default DACL grants
Administrators and SYSTEM and not the user, so an object an elevated Agent creates with it cannot be opened by the same
user's unelevated App or game: the pipe (`PipeAccessControl`), the tolerance mapping (§D) and — since beta.10 — the
ledger's migration lock (`Infrastructure.Startup.SharedMutex`: owner the user, full access to the user, Administrators
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` and `SafetyUnhook` are **never** collapsed into a generic error toast — they get dedicated, explanatory UI (`08_UI` §Notifications).
- `CaptureRefused`, `SafetyUnhook` and (since 2026-09-25) `HookingTurnedOff` are **never** collapsed into a generic error toast — they get dedicated, explanatory UI (`08_UI` §Notifications).
## Versioning
+949 -57
View File
File diff suppressed because it is too large. Load diff
+32 -4
View File
@@ -2,12 +2,32 @@
Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as the rest of the poli0981 portfolio.
> **The user guide is English (beta.12, owner decision D44)**, like the legal documents: `guide/` is Markdown the App
> embeds and renders, not `.resx` text. The UI around it — the menu item, the window's title — is translated.
> **Both string families are given the UI culture explicitly (2026-09-21).** `App.ApplyCulture` sets `Strings.Culture`
> AND `FrameLedger.Shared.Strings.Culture`. The second was missing: the safety family fell back to the thread's
> `CurrentUICulture`, and a culture set inside the App's async start flows with that async context, not to the
> dispatcher's later operations — so on an English Windows a Vietnamese UI showed the consent dialog, the refusal
> notices in English (and, for one day, a guard-override card). A resource accessor that depends on which thread asks is the defect;
> `StringsTests.ApplyingTheUiLanguageSetsTheSafetyFamilyToo` holds it with the thread deliberately left English.
## Mechanics
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` for error codes). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
- XAML binding via `{x:Static res:Strings.Key}` plus a `LocalizeExtension` for the few dynamic cases.
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` ~~for error codes~~ for the safety family, the `Safety_*` keys — corrected 2026-10-04). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
- XAML binding via `{x:Static res:Strings.Key}` ~~plus a `LocalizeExtension` for the few dynamic cases~~ *(corrected 2026-10-04: no `LocalizeExtension` exists; text that varies is composed in the view model from `Strings.*`)*.
- **Runtime switching:** setting change → set `CultureInfo.CurrentUICulture` + `Thread` defaults → re-create the main window shell (cheap; state preserved via VM). Persist in `settings`.
- `SatelliteResourceLanguages` = `en;vi;ja` in the App csproj to keep publish size down.
**The new window opens on the page that was on screen** *(beta.34, owner request 2026-11-06)* — Settings, after a
change made there. `ShellHost` remembered only the pages opened from code (`PageNavigator`), never a click in the
pane, so a language changed on Settings brought back the last game page opened; it now notes every page the live
window's NavigationView shows (`ShellHost.NoteShown`).
**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
@@ -24,7 +44,7 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
- `en` written first, is authoritative.
- `vi` authored by the maintainer.
- `ja` machine-drafted, each entry marked with `<comment>review</comment>` until reviewed; the About dialog credits reviewers.
- `ja` machine-drafted, each entry marked with `<comment>review</comment>` until reviewed; ~~the About dialog credits reviewers~~ *(corrected 2026-10-04: no screen credits reviewers yet, and no `ja` entry has been reviewed — owner-only)*.
- CI check (`tools/resx-audit`): every key present in all three files; ~~missing → build warning list artifact~~ **missing is RED (2026-09-13)**: `tools/resx-audit.ps1` exists since P3 PR-2 as `build.ps1` step 15, self-test first (11 fixture cases, at least four must go red) then the live pass over every `Strings.resx` under `src/`. Per family it requires C#-identifier keys with non-empty neutral values, **exactly** the neutral key set in `vi` and `ja` (a missing key would fall back to English silently; an extra one is dead text), the `Safety_*` rule below, and a current `Strings.Designer.cs`. A tree with no family is red, not green — the gate must not be vacuous.
## Glossary (fixed translations)
@@ -45,6 +65,11 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
| Anti-cheat | Anti-cheat (giữ nguyên) | アンチチート |
| Capture tier | Mức thu thập | 計測ティア |
| Measured / Supports | Đo được / Hỗ trợ | 実測 / 対応 |
| VRAM / RAM (beta.12) | VRAM / RAM (giữ nguyên) | VRAM / RAM |
| Dedicated / Shared GPU memory | Bộ nhớ GPU chuyên dụng / dùng chung | 専用 / 共有 GPU メモリ |
| Private working set / Working set / Commit | giữ nguyên | プライベート ワーキング セット / ワーキング セット / コミット |
| this game / whole graphics card / whole PC | game này / cả card đồ họa / cả máy | このゲーム / グラフィックス カード全体 / PC 全体 |
| Median / Mean / Peak | Trung vị / Trung bình / Đỉnh | 中央値 / 平均 / ピーク |
Technical benchmark vocabulary stays in English across all locales where the community convention is English (1% Low, stutter, present mode, frame pacing).
@@ -55,6 +80,9 @@ Consent, refusal, and safety-unhook text (FR-2.1, `19_SAFETY`) is **reviewed lik
- No machine-drafted `ja` in this category — a mistranslated ban warning is a real harm. These keys are marked `<comment>safety: human review required</comment>` and ~~the `ja` build fails the resx audit until a human reviewer signs off; until then the `en` string is shown as fallback rather than an unreviewed translation~~ **as built (2026-09-13): the audit is red on a `Safety_*` key in `ja` that carries neither `safety: human review required` nor `safety: reviewed by <name>`, and red on one marked review-required whose value is anything but the `en` string verbatim** — the key-set rule forbids leaving it out, so "shown as `en` until signed" is true by construction (the value IS the English), not by a runtime fallback. Signing = replacing the comment with `safety: reviewed by <name>` beside the reviewed text.
- Never soften the wording per locale. "May result in a permanent ban of your account" must survive translation with the same force in all three languages.
- Key prefix `Safety_*` so they are easy to audit as a group.
- **`Safety_Exception_*` (2026-09-26, D33)** is the user-mode exception's disclosure: the same rules — `ja` ships the
English verbatim marked for review — and its own version, `AntiCheatExceptionDisclosure.Version`, bumped when any of
those strings changes meaning, exactly as `SafetyDisclosure.Version` is for `Safety_Consent_*`.
> **What is in scope, stated 2026-08-06 because a binary now exists that is not.** These rules
> govern the **shipped** application's user-visible strings — what `12_BUILD` §Publish & package
+30 -4
View File
@@ -3,9 +3,19 @@
## Serilog configuration
- Sinks: rolling file per process — `logs/ui-.log`, `logs/agent-.log` (`rollingInterval: Day`, `retainedFileCountLimit: 7`, `fileSizeLimitBytes: 10 MB`, `rollOnFileSizeLimit: true`). Console sink in DEBUG builds. *(`ui-.log` is written since 2026-09-13, P3 PR-2, with `Process=ui` enriched and every unhandled path — Dispatcher, AppDomain, unobserved task — logged as Fatal/Error; ~~the crash dialog and minidump of §Crash handling are still P4's~~ — built 2026-09-15, P4 PR-9, §Crash handling's note.)*
- *(beta.15, D52: an App started with `--data-dir <copy>` — a viewer — writes `ui-.log` and its crash dumps under the
copy, never under `%LOCALAPPDATA%\FrameLedger`; its first lines name the folder and say it is a viewer.)*
- Minimum level `Information` (`Debug` toggle in Settings → applies live via `LoggingLevelSwitch`).
- Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).
- ~~Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).~~
- Template: `[{Timestamp:HH:mm:ss.fff} {Level:u3}] {SourceContext} {Message:lj} {Properties:j}{NewLine}{Exception}`.
> **Corrected 2026-10-04 — the four lines above are `ui-.log`'s configuration, not both processes'.** `agent-.log`
> (`FrameLedger.Agent/Program.cs`, since 2026-09-10) is daily with **14** files kept and no size cap, writes Serilog's
> **default** template — `2026-10-04 09:15:02.123 +07:00 [INF] …`, a date first — and its level is fixed at
> Information with `Microsoft.*` at Warning: `log.debug` is the App's alone. Neither process has a console sink, and no
> enricher exists beyond the App's `Process=ui`. The Logs page reads both shapes since beta.12 — until then its level
> filter recognised only the App's `[HH:mm:ss.fff LVL]` prefix, so Warning and Error showed no Agent line at all
> (`LogTail.LevelOf`, `LogTailTests.TheAgentsTemplateIsReadToo`).
- **Never log:** full user paths outside `%LOCALAPPDATA%\FrameLedger` (redact to `<user>`), machine name, any exe arguments of games. ~~A `RedactingEnricher` enforces the path rule.~~ *(No such enricher was ever written: found 2026-09-15, checking `legal/PRIVACY_POLICY.md` §3's "logs are redacted (user directory paths removed) before bundling" against the bundle, which copied the logs verbatim. An enricher could not have kept the rule anyway: exception text and the Overlay's native log never pass through one, and the data directory itself sits under the user's profile, so every run logs a user name. The rule is enforced where a log leaves the machine instead: `App/Services/LogRedactor` over every log copy in the bug bundle, §Bug report flow step 2. The files in `logs\` keep their full paths; they leave the PC only if the user copies them.)*
- Capture hot path logs nothing per-frame; counters summarized at finalize.
@@ -15,6 +25,17 @@
- On fatal: Serilog `Fatal` with full exception → write minidump via `MiniDumpWriteDump` (CsWin32, `MiniDumpWithIndirectlyReferencedMemory | WithThreadInfo`) to `crashdumps/` (keep last 5) → UI shows crash dialog offering the bug-report flow → exit code 1.
- Agent crash mid-session → `.partial` recovery path (04_CAPTURE) on next start finalizes an `interrupted` session.
> **Written by a child process since 2026-09-17.** `MiniDumpWriteDump` on the calling process suspends every other
> thread of it, and a suspended thread holding the process heap or loader lock deadlocks the dumper — Microsoft's
> documentation says to dump "from a separate process if at all possible". The in-process writer below froze the
> Infrastructure test suite one run in eight, and a crashing App or Agent is the unstable process the warning is about.
> `CrashDumpWriter.TryWrite` now starts `FrameLedger.Agent.exe --write-crash-dump <file>` (the Agent beside the App;
> the Agent's own binary for the Agent) and waits up to 30 s; the helper (`ParentDump`) dumps **its parent** with the
> same two flags, and nothing else: it takes no pid, and refuses unless the parent is still running, started before it,
> and has its image in the helper's own directory — the App or the Agent, never a game (CLAUDE.md rule 4). A missing,
> failed or slow helper is a null path and one Warning line, as before. The runtime's `createdump.exe` would have done
> the job, but a self-contained install does not ship it (measured on 0.1.0-beta.1).
>
> **Built 2026-09-15 (P4 PR-9).** `Infrastructure/Diagnostics/CrashDumpWriter` writes
> `crashdumps\<ui|agent>-<yyyyMMdd-HHmmss, UTC>-<pid>.dmp` through CsWin32's `MiniDumpWriteDump` with exactly the two
> flags above, keeps the five newest `*.dmp` of either process after each write, and never throws: a failure is a null
@@ -140,15 +161,20 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
## Diagnostics extras
- `Tools → Agent status…` shows the `HelloAck` capability set (telemetry source, overlay build id, Vulkan layer — ~~tier availability~~, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder) + last 20 Agent log lines.
- `Tools → Agent status…` ~~shows the `HelloAck` capability set (telemetry source, overlay build id, Vulkan layer~~ — ~~tier availability~~, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder ~~) + last 20 Agent log lines~~. *(Corrected 2026-10-04: it opens the Dashboard's Agent card — state, version, telemetry source, overlay build id, elevated, running sessions. The Vulkan layer state is on Settings ▸ Capture and the Agent's log on the Logs page.)*
- **Never include a game's own logs, saves, or config files** in a bug bundle, even when a crash looks game-related. We ship our logs only.
- `--diag` CLI flag on the App prints environment + capability report to stdout (support requests).
> **Read-only since 2026-09-16:** `DiagAsync` opens the ledger through `LedgerDatabase.OpenReadOnlyAsync`, so a
> diagnostic run against a ledger at another schema reports that fact (the schema line reads the refusal) rather
> than migrating the file it was asked to describe.
>
> **Built 2026-09-14 (P3 PR-8a).** `App.OnStartup` sees `--diag` and runs `DiagAsync` instead of the host: no
> window, no Agent, the ledger opened read-only for its schema version and the settings, then
> `Services/DiagReport.Build` (app version, OS and bitness, runtime, locale, elevation, data and logs
> directories, ledger schema or "could not open", whether `FrameLedger.Agent.exe` is beside the App, every
> registry key's effective value) written to `logs/diag-<yyyyMMdd-HHmmss>.txt` **and** to stdout — the App is
> directories, ledger schema or "could not open", whether `FrameLedger.Agent.exe` is beside the App, since
> 2026-09-21 the machine as a session's hardware snapshot records it — CPU, GPU, driver, RAM, display — added to this
> list 2026-10-04, and every registry key's effective value) written to `logs/diag-<yyyyMMdd-HHmmss>.txt` **and** to stdout — the App is
> a WinExe with no console of its own, so stdout carries the report only when the caller attached one or piped
> it (`FrameLedger.exe --diag | more` works; a double-click leaves the file). Exit 0, or 1 with a Fatal line in
> `ui-*.log`. The Agent's `--diag` stays on its `NotImplementedFlags` list — 10_LOGGING names the flag as the
+91 -14
View File
@@ -1,14 +1,17 @@
# 11 — Updater
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. Stable channel only in v1.
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. ~~Stable channel only in v1.~~ *(Corrected 2026-10-04: two channels since P4 PR-5 — `update.channel`, ~~stable by default~~ or beta, which adds pre-releases. Every release so far is a pre-release; see §Built, Channels.)* *(Corrected 2026-10-05: the default is `auto` since beta.14, which follows the running copy — §The update audit, beta.14.)* *(2026-10-31, D73: an **alpha line** beside them, on Velopack's `alpha` channel — §Built, Channels.)*
## Flow
- **Startup silent check** (if enabled): `UpdateManager.CheckForUpdatesAsync()` 5 s after UI idle. Offline/any failure → log `Information`, no dialog (NFR-10). Update found → non-blocking toast "Update vX.Y.Z available" → Downloads in background → "Restart to update" button (never auto-restart; the user may be mid-capture — if a capture is active, defer the prompt until session end).
- **Manual check** (Help → Check for updates): progress dialog; all failures produce the mapped dialog below.
- **A viewer never updates** (beta.15, D52): an App started with `--data-dir <copy>` registers neither Velopack nor the
startup check (`Services.MachineFacingServices` gives it `ViewerUpdateClient`, which answers "not installed"), and
Help → Check for updates and the automatic-check switch are disabled — an update replaces this PC's installed copy.
- **Never apply an update while a game is hooked** (FR-12): the Overlay DLL on disk must not change under a running game, and a mid-session swap would invalidate the ring layout handshake. If a capture is active, defer the prompt and the apply until the session ends.
- Apply: `WaitExitThenApplyUpdates` on restart. Agent is stopped via `Shutdown` before applying and the scheduled task action path is re-validated after update (Velopack keeps a stable `current` path, but verify in P4 and re-register task if the action path changed).
- Release notes (GitHub release body, Markdown) rendered in the update dialog.
- Release notes (GitHub release body, Markdown) rendered in the update dialog. ~~(shown as plain text until beta.12 — §Flow and §Limits below said so)~~ **Rendered since beta.12** by `Controls/MarkdownView` (`08_UI` §Menu, *Documents are rendered*), relative links resolved against `CHANGELOG.md` at this build's source.
## Error mapping (FR-12)
@@ -21,7 +24,7 @@ Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledg
| Package hash mismatch | `Update_Err_Corrupt` | Auto-retry once, then dialog |
| Unknown | `Update_Err_Unknown` + exception logged | "Report a bug" shortcut |
Detection-rules updates share this client, but the **`anticheat` block is fetched and applied on its own schedule regardless of the user's rules-update preference** (`05_DETECTION` FR-7.3) — a user who turned off rules updates must still receive new anti-cheat entries.
~~Detection-rules updates share this client, but the **`anticheat` block is fetched and applied on its own schedule regardless of the user's rules-update preference** (`05_DETECTION` FR-7.3) — a user who turned off rules updates must still receive new anti-cheat entries.~~ *(Corrected 2026-10-04: there is no rules fetch and no rules-update preference. Tools ▸ Update detection rules re-reads the copy seeded from the install (`07_IPC`); FR-7.3 is unmet (`20_OPEN_QUESTIONS` §S20). The sentence is what a fetch must do once built.)*
All update HTTP goes through one `GitHubHttpClient` (also used by rules updates) with: UA `FrameLedger/{version}`, 10 s timeout, ETag cache in `settings`, single retry with jitter for transient failures.
@@ -29,17 +32,27 @@ All update HTTP goes through one `GitHubHttpClient` (also used by rules updates)
Binaries are not code-signed (project policy). Consequences and mitigations, documented in README and the update dialog footer:
- SmartScreen warning on first run of a new version — expected; SHA-256 checksums (`SHA256SUMS.txt`) published with every release; CI prints them into release notes.
- Velopack delta packages reduce download size; full package fallback automatic.
- ~~Velopack delta packages reduce download size; full package fallback automatic.~~ *(Corrected 2026-10-04: no delta has been published — `release.yml` never puts the previous release in `out/release` before `vpk pack`, so every update downloads the full package; a delta needs a `vpk download github` step first.)* **Built in beta.13:**
`release.yml` downloads the previous release into `out/release` before `vpk pack`, so a release carries
`FrameLedger.App-<version>-delta.nupkg` beside the full package; the previous full package is moved out (neither uploaded
nor checksummed) and the feed lists this build alone, as `vpk upload github` would write it. Velopack applies the delta
when the installed copy is the previous release and falls back to the full package otherwise — `0.1.0-beta.13` is the
first release with one, so beta.12 → beta.13 is the first update that can use it (owner-only: HANDOFF item 10).
- Never bypass or suppress OS warnings programmatically.
## Versioning
SemVer `MAJOR.MINOR.PATCH`. Tag `vX.Y.Z` triggers the release workflow (13_CI_CD). `MAJOR` bumps for DB schema or IPC protocol breaks; migrations must cover every released `MAJOR-1` version.
> **Under `0.x` this rule is not applied, and every pre-release says so by shipping one anyway** (SemVer §4: a major version
> zero is initial development). Schemas ~~0008–0015~~ 0008–0017 *(corrected 2026-10-04: 0016 shipped in beta.10 beside 0015, 0017 in beta.11; 0018 rides beta.12)* and the shared-memory layout 4 (2026-09-27, beta.10) each shipped in a
> `0.1.0-beta.N`. What protects a user is not the number: the ledger migrates in place (`06_DATA_MODEL` §Migrations), and a
> layout mismatch is refused at attach with "restart the game" (`07_IPC` §Protocol rules). The rule applies from `1.0.0`.
## Built 2026-09-14 (P4 PR-5) — what exists, and where it deviates from the above
`src/FrameLedger.App/Update/`. Velopack 1.2.0 (`Directory.Packages.props`, pinned since P0, referenced since
this PR) behind the `IUpdateClient` port — `VelopackUpdateClient` is the one implementation, `UpdateService` the
this PR; **1.2.161 since beta.30**, owner decision D71 — the library and `vpk` together) behind the `IUpdateClient` port — `VelopackUpdateClient` is the one implementation, `UpdateService` the
flow, and the tests run the flow over a fake client because nothing here may touch the network in a test.
- **Startup silent check:** `UpdateHostedService`, 5 s after the host starts (the "5 s after UI idle" above —
@@ -50,27 +63,44 @@ flow, and the tests run the flow over a fake client because nothing here may tou
window is off screen (`08_UI` §Notifications policy), and the shell's persistent InfoBar carries the download
and the **Restart to update** button.
- **Manual check:** Help ▸ Check for updates → `UpdateService.CheckInteractivelyAsync` and the dialogs in
`UpdatePrompts` (WPF-UI `MessageBox`): the offer with the release notes (the GitHub release body, shown as text —
no Markdown renderer is shipped), the unsigned-release footer, Download / Later; "up to date"; "not an
`UpdatePrompts` (WPF-UI `MessageBox`): the offer with the release notes (the GitHub release body, ~~shown as text —
no Markdown renderer is shipped~~ rendered since beta.12, at most 260 px tall and scrolling), the unsigned-release footer, Download / Later; "up to date"; "not an
installed copy"; and the error table below. There is no progress *dialog*: progress is the banner's percent. A
package that fails its checksum is downloaded once more before the Corrupt row is shown (the table's "auto-retry
once").
- **FR-12 is the shape of the flow, not a check at the end.** A downloaded package is `Ready` only while the Agent
reports no session (its `StatusAck` at connect, then `SessionStarted` / `SessionCompleted` on the pipe);
otherwise it is `Deferred`, the button is disabled and the body says why, and it becomes `Ready` when the last
session ends. The apply is refused again inside if a session started meanwhile. A recording-only (Tier 2)
session ends. The apply is refused again inside if a session started meanwhile. ~~A recording-only (Tier 2)
session that began before the App connected is covered by the status; one that begins afterwards raises no
`SessionStarted` (that event is the ring's) and is not — a known gap, recorded rather than hidden: the Overlay
is not on disk under such a session, so the rule's reason does not apply to it.
is not on disk under such a session, so the rule's reason does not apply to it.~~ **Closed 2026-09-23:** a held
(Tier 2) session raises its own `SessionStarted`, so it defers an update like any other; and the status read at
connect SEEDS the running set rather than being OR-ed with it forever — before, a session running when the App
connected held every download at `Deferred` until the next reconnect, hours after it ended.
- **Apply:** `Shutdown` to the Agent over the pipe, the connection's relaunch held (`IAgentLink.SetLaunchHold`),
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so),
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so) —
**and since beta.10 the data folder's instance lock watched until it is let go, within the same 10 s**: an Agent run as
administrator (the admin mode) holds the install directory's files exactly as long as its process lives, and one that
holds the folder without answering this App (still starting, another version) is never updated under — the apply is
refused with `Update_AgentStillRunning` instead,
then `WaitExitThenApplyUpdates(asset, silent: false, restart: true)` and the host ends. The restarted App
starts the Agent beside itself as always, and when Velopack reports the restart (`OnRestarted`) the host reads
the logon task: `Stale` (the action path moved) runs `--install-task`, this user's own task, and says so in the
log — the "re-validated after update" above. Velopack keeps `current` stable, so `Installed` is the expectation.
- **Channels:** `stable` = releases GitHub does not mark pre-release; `beta` = those too (`GithubSource(prerelease)`).
Not Velopack's own `--channel` mechanism — one package set per tag, the GitHub flag decides. `13_CI_CD` §Branch &
release policy.
release policy. *(Corrected 2026-10-31, D73: true of the main line, whose packages are on Velopack's default `win`
channel. **The alpha line uses Velopack's channels**: an alpha is packed with `--channel alpha`, so its feed is
`releases.alpha.json`, and an installed copy reads only its own channel's feed — `VelopackUpdateClient` passes no
`ExplicitChannel`, so the channel is the one the installed package was built for (its `sq.version` names it). Velopack's
`GithubSource` merges the assets of every release that carries that feed, so a beta never sees an alpha and an alpha
never sees a beta, under either setting of `update.channel` — and in an alpha build that picker is locked, its line
saying so (`08_UI` §Settings). **One limit follows from the source, read from Velopack's code 2026-10-31:** it asks
GitHub for one page of ten releases, newest first, so ten releases of one line in a row would hide the other line's
newest from its update check. The cadence is one alpha per beta (`13_CI_CD` §The alpha line). Moving between the lines
is a deliberate install, never an update: the other line's `Setup.exe` over the installed copy, which Velopack answers
with its overwrite prompt — the packId, the install folder and the data folder are the same.)*
- **Hooks** (`VelopackHooks`, in the hand-written `Program.Main` so `VelopackApp.Run()` precedes any window):
install registers nothing; uninstall = `UninstallHook` (`12_BUILD` §Publish & package). `Run()` in a copy the
installer did not lay down returns at once and runs no hook (probed on 1.2.0); it does append a line to Velopack's
@@ -92,8 +122,55 @@ flow, and the tests run the flow over a fake client because nothing here may tou
empty token — measured on 1.2.0 by reflection, so the request identifies the product and nothing else. When the rules fetch is built
(`05_DETECTION` FR-7.3, `20_OPEN_QUESTIONS` §S20 feed half) it needs a client of its own; this paragraph no
longer claims the updater provides one.
- Release notes are rendered as plain text, not Markdown.
- ~~Release notes are rendered as plain text, not Markdown.~~ Corrected 2026-10-03: rendered since beta.12 (Markdig; HTML off, no image fetched).
## The update audit, beta.14 (owner request 2026-10-05: "check the update logic")
No failure had been reported; the audit read the flow above against Velopack 1.2.0 and the owner's own updater log
(`%LOCALAPPDATA%\velopack\velopack_FrameLedger.App.log`, read-only) and found two defects that made the flow above
partly fiction, and six smaller ones. Each is fixed in place:
- **A copy left on its defaults never found an update.** `update.channel` defaulted to `stable` while every release is a
GitHub pre-release; the owner's log reads "No releases found" from the day their ledger (and its settings row) was reset.
**Owner decision D47:** the default is `auto`, which follows the running copy — a pre-release asks for pre-releases, a
release for releases (`Update/UpdateChannelPolicy`, SemVer's `-` before any `+`) — and a stored `stable` or `beta` is the
user's choice and wins. Settings shows *Automatic (Beta)* or *(Stable)* first. Only an explicit selection ever wrote the
row (`SettingsViewModel.Persist` is guarded while loading), so existing copies with no row move to `auto`.
- **Velopack applied a downloaded update at the next start, behind FR-12.** `VelopackApp` applies a package waiting in
the install folder on startup unless told not to (`SetAutoApplyOnStartup`, ON by default), and the startup check
downloads in the background — so the next start of `FrameLedger.exe` (the Start menu, the logon Run value, a second
click, `--diag`) applied it inside `VelopackApp.Run()`, before the single-instance claim, before FR-12 could ask
whether a session runs, and before the Agent was asked to stop; its updater killed the Agent instead (the owner's log:
"Auto apply is true, so restarting to apply update…", then "Killing process: …FrameLedger.Agent.exe"). Off now
(`VelopackHooks`, pinned by `VelopackHooksTests` through the builder's private fields); a package an earlier run left
is adopted at start — `UpdateService.AdoptPending`, from `UpdateManager.UpdatePendingRestart`, no feed request — and is
Ready or Deferred like any other.
- **An update Velopack starts itself** (the installer run over an installed copy) asks the Agent to stop first, as the
uninstaller does (`OnBeforeUpdateFastCallback`, 15 s budget, a line in `logs\update.log`). The hook runs in the
version being replaced, so it first works for the update after beta.14.
- **The apply waits while a game still has the Overlay loaded** from the install folder (`Update/PayloadInUse`: a mapped
image refuses an exclusive write — a file-system question, no process opened). The Overlay is never unloaded from a
live game (`17_HOOK_ENGINE`), so after a mid-game stop the swap would fail half way after the App had quit. Asked before
the Agent is stopped; the strip names the file.
- **An Agent waiting on the administrator prompt** (the logon task's, the admin mode) holds only its elevation marker, not
the instance lock; the apply now waits for either (`UpdateService.AgentHolds`).
- **The stop budget is the Agent's own shutdown grace and five seconds** (`IpcProtocol.AgentShutdownGrace`, 15 s, which
the Agent's host now reads too): the App waited 10 s for an Agent that took up to 15 to finalize its sessions.
- **The offer says the download Velopack will make:** the deltas from the installed version when the feed has them
(`UpdateInfo.DeltasToTarget`; 1.6 MB for beta.12 → beta.13) and the full package as the fallback — it said ~102 MB.
Velopack's own lines are in the App's log since beta.14 (`velopack: …`, `VelopackSerilogLogger`), so whether a delta
or the full package came is in the bug report too.
- **Smaller:** an `IOException` is "offline" only from the network (`HttpIOException`, a socket error) — a full disk
read as offline; the uninstaller removes the "Start FrameLedger with Windows" Run value, which named an executable it
deletes.
**What none of this reaches:** a copy still on 0.1.0-beta.13 or older runs its own code for the update to beta.14 —
stable by default, apply-at-start on. Its user chooses *Beta* in Settings ▸ Updates and updates with no game running
(the beta.14 release notes say so); everything above holds from beta.14 on.
`UpdateServiceTests` (App.Tests/Update) cover the two skips, the channels, Deferred ↔ Ready, each error row, and
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; a real feed has
not been exercised — the first tag is the measurement (`13_CI_CD` §release.yml).
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; ~~a real feed has
not been exercised — the first tag is the measurement~~ *(corrected 2026-10-04: the feed has existed since
v0.1.0-beta.1, 2026-09-16, and every release since carries `releases.win.json`; whether an installed copy has updated
through it is not recorded here)*
(`13_CI_CD` §release.yml).
+145 -24
View File
@@ -5,7 +5,7 @@ Mixed toolchain: .NET 10 for managed projects, MSVC for the native layer.
## Prerequisites
- Windows 11 (dev), **.NET 10 SDK**, **Visual Studio 2026** with: .NET desktop development, **Desktop development with C++** (MSVC v143+, Windows 11 SDK ≥ 10.0.22621), C++ ATL not required.
- **Vulkan SDK** (for the layer + validation layers during development).
- **Vulkan SDK** (~~for the layer +~~ validation layers during development, and to run `tools/vklayer-blastradius.ps1`) *(corrected 2026-10-04: the layer builds against the vendored `third_party/vulkan-headers`; CI installs no SDK)*.
- CMake ≥ 3.28 (native projects use CMake; consumed by the solution via a build target — see below).
- Optional: PawnIO for CPU-temperature testing; an NVIDIA GPU for the NVAPI/Reflex paths (dev machine: RTX 5080). AMD/Intel telemetry paths need no SDK — if you have such hardware, testing L1/L2 coverage there is valuable.
- **No admin needed for normal development.** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (CLAUDE.md §Dev mode records the same, and this line contradicted it in the present tense until 2026-08-05). When it exists it runs the whole app with a synthetic source and zero injection. Until then the no-injection development path is `hook-harness`, which needs no admin either.
@@ -23,8 +23,9 @@ Targets:
- `FrameLedger.Overlay` → `FrameLedger.Overlay.dll`
- `FrameLedger.VkLayer` → `FrameLedger.VkLayer.dll` + `VkLayer_FRAMELEDGER_overlay.json`
- `FrameLedger.Injector` → **static lib only.** There is no `FrameLedger.Injector.exe` and none ships (`20_OPEN_QUESTIONS` §S9, decided 2026-08-02). A standalone `LoadLibraryW` injector that users can run is a path into a game process that the guard does not stand in front of — a bypass, and a bad look for a project whose position is "we refuse where we are not welcome". The Agent links the static lib; the guard owns the chokepoint inside it (§S13(b)), so there is no callable entry point that skips the gate. Manual testing uses `hook-harness`, never a real game (§Debugging).
- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other three shipped natives. ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too.
- `FrameLedger.Overlay.Tests` → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too
- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other ~~three~~ shipped natives (five in all since beta.12 — corrected 2026-10-04). ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too.
- `FrameLedger.Guard` → `FrameLedger.Guard.dll` (the guard's C ABI over the Injector library, `src/native/FrameLedger.Injector/CMakeLists.txt`; loaded by the Agent) and `FrameLedger.ProcessStats` → `FrameLedger.ProcessStats.dll` (beta.12, D43: the game process's memory, read by the Agent from outside the game; probe `fl-probe-processstats`) *(both bullets added 2026-10-04; they were missing)*
- ~~`FrameLedger.Overlay.Tests`~~ the ctest executables in `src/native/tests/` (`fl_ring_test`, `fl_guard_test`, `fl_vklayer_test`, … — corrected 2026-10-04: no target of that name has existed) → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too
- `hook-harness` → the dummy **D3D11 + D3D12** app, WARP + composition swapchain so it runs headless on CI (`17_HOOK_ENGINE` §Test harness). D3D12 is device → command queue → swapchain, which is the acquisition asymmetry a D3D11-only fixture cannot exercise. ~~Vulkan and OpenGL modes to follow as those hooks land.~~ **`--vulkan --hold-presenting N` since 2026-09-06 (P1 item 3):** a real swapchain on a hidden window through the real loader, reached by `LoadLibraryW("vulkan-1.dll")` so only the vendored headers are needed and CI (no loader) still builds it; exit 77 = cannot run here, which the ctest reads as SKIP. **`--opengl --hold-presenting N` since the same day (P1 item 4):** a real context on a hidden window, `SwapBuffers`'d through gdi32 as a title does, on Microsoft's generic renderer — so it runs on CI.
- `fl-probe-hookprofile` → build-profile probes for `/guard:cf` and `-D_HAS_EXCEPTIONS=0` (`20_OPEN_QUESTIONS` §H1/§H3)
- `fl-probe-guard` → measures the Windows APIs the guard is built on, unelevated (`spike-notes.md` §1). Not the guard, and takes no injection rights.
@@ -43,11 +44,11 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
**No AMD or Intel GPU *telemetry* SDK is vendored.** Those vendors' sensors are covered by LibreHardwareMonitor and the DXGI/PDH baseline (`18_GPU_VENDOR_APIS`). A build that pulls in Intel IGCL or AMD ADLX material is a licensing regression, not a feature — CI greps for it. **The AMD FidelityFX ffx-api headers (MIT by exception, tag v2.3.0) ARE vendored since 2026-09-04**, for the Overlay's upscaler hook and for types only — `fl_fidelityfx_headers` above, `18_GPU_VENDOR_APIS` §AMD for the licence reading, and `license-check.ps1` §2d for the per-file gate. Intel's XeSS SDK failed the checklist and nothing of it is here.
**VERSIONINFO is mandatory** on `FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`: real `CompanyName`, `ProductName=FrameLedger`, `FileDescription`, version. Identifiability is a requirement (`19_SAFETY`), and a CI check fails the build if the resource block is missing.
**VERSIONINFO is mandatory** on ~~`FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`~~ every shipped native — the five `tools/versioninfo-check.ps1` lists (corrected 2026-10-04): real `CompanyName`, `ProductName=FrameLedger`, `FileDescription`, version. Identifiability is a requirement (`19_SAFETY`), and a CI check fails the build if the resource block is missing. **Since beta.14 (D50) the managed binaries are held to the same** — §Version, *Identity*.
## Managed build & native integration
- **`global.json` pins the SDK band** (`10.0.x`, `rollForward: latestFeature`). Without it `dotnet build` picks the newest installed SDK — on a machine with a .NET 11 preview installed that silently changes analyzer behaviour under `TreatWarningsAsErrors`, and makes local and CI disagree for reasons nobody can see in a diff.
- **`global.json` pins the SDK band** (`10.0.x`, `rollForward: latestFeature`). Without it `dotnet build` picks the newest installed SDK — on a machine with a .NET 11 preview installed that silently changes analyzer behaviour under `TreatWarningsAsErrors`, and makes local and CI disagree for reasons nobody can see in a diff. *(On the `alpha` branch it pins the prerelease SDK instead, on purpose — §The alpha line, 2026-10-31.)*
- `Directory.Build.props`:
- **`TargetFramework` = `net10.0-windows10.0.22621.0`** and **`SupportedOSPlatformVersion` = `10.0.19045.0`**. These are two different knobs and must not be conflated: the TFM platform version selects which Windows API projections are available to compile against, while the supported version is the floor CA1416 enforces. NFR-8 requires Windows 10 **22H2** = build **19045**; letting the supported version default to the TFM's would silently accept installs below the stated floor. Two constraints pin the target to 22621 rather than something closer to the floor: the SDK rejects `SupportedOSPlatformVersion` above `TargetPlatformVersion` (NETSDK1135), and 19045 is not a targeting-pack version in any case — the packs are cut at 19041, 20348, 22000, 22621, 26100. The Windows 11 SDK ≥ 10.0.22621 is already a prerequisite above, so this costs nothing. A bare `net10.0-windows` is wrong for a different reason: it resolves to `net10.0-windows7.0`, and CA1416 would then error on Mica, `MiniDumpWriteDump` and `QueryVideoMemoryInfo` — every Windows-10-era API this app is built on.
- `Platforms`/`PlatformTarget` = `x64`. "x64 only" is asserted in CLAUDE.md and NFR-8 but was previously enforced nowhere except an ad-hoc `-r win-x64` on the publish command.
@@ -55,7 +56,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
> **`RuntimeIdentifier` is NOT set here, and this bullet claimed it was until 2026-08-06.** The props file's own comment explains why: forcing a RID onto class libraries pulls RID-specific assets into their restore for no benefit, so each executable sets it — `FrameLedger.App`, `FrameLedger.Agent` and now `FrameLedger.CaptureHost`, plus its test project, which needs the same RID to reference a RID'd exe. A new project copying this document rather than the props file would have inherited nothing.
- Nullable enable, ImplicitUsings enable, `TreatWarningsAsErrors=true`, `AnalysisLevel=latest-all`, deterministic, `ContinuousIntegrationBuild` on CI.
- `Directory.Packages.props`: central package management, all versions pinned (including `WPF-UI` = 4.3.0 exactly — `16_WPFUI_SYNTAX` §Version hygiene).
- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project.
- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole), and since beta.12 `/FrameLedger.ProcessStats.targets` (the game-memory reader, D43; it also warns rather than fails — an absent reader reads N/A; added 2026-10-04). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project.
> **This bullet was wrong in four ways and is corrected 2026-08-04.** It named a copy of `FrameLedger.Injector.exe`, which §S9 closed and which line 25 above says does not exist, 24 lines earlier in the same document. It attributed the copying to a build target in `FrameLedger.Infrastructure.csproj`, which contains no `<Target>` at all. It said the copies happen there, when the guard DLL was deliberately moved out to a `.targets` file so it would stop flowing to every referencing project (§S18 blocker 3). And it credited the solution with an ordering the solution cannot express.
- **Struct mirror check — ✅ built 2026-08-05.** `ShmLayoutMirrorTests` runs `tools/fl-layout-dump`, reads its JSON, and asserts size plus every field offset against the C# `[StructLayout]` mirrors in `FrameLedger.Shared` — in **both directions**, so a field on either side alone fails. It also asserts blittability, which offsets cannot see. The `struct-mirror` gate reads the run's `.trx` and fails when that test class did not execute, so deleting the test is red as well as breaking it. Struct drift between the two layers is the most dangerous silent bug in this architecture; the build now genuinely catches it.
@@ -64,10 +65,25 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
## Debugging
Launch profiles:
- **"UI + Mock"** — `FL_MOCK=1`, no Agent, no injection. Default for UI work.
- **"UI + Agent"** — both managed processes, real capture against `hook-harness`.
- **"Harness + Overlay"** — starts `hook-harness` under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.
~~Launch profiles:~~
- ~~**"UI + Mock"** — `FL_MOCK=1`, no Agent, no injection. Default for UI work.~~
- ~~**"UI + Agent"** — both managed processes, real capture against `hook-harness`.~~
- ~~**"Harness + Overlay"** — starts `hook-harness` under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.~~
*(Corrected 2026-10-04: none of these is committed, and "UI + Mock" needs `FL_MOCK`, which §Prerequisites says is not
implemented. What exists: `FrameLedger.exe` starts `FrameLedger.Agent.exe --serve` beside itself. To capture against the
harness, run `hook-harness.exe --real --hold-presenting N`, then the Agent's `--console --data-dir <scratch>` verbs
`consent grant --exe` and `capture --exe`, as `AgentEndToEndTests` does — never against your own data folder.)*
**To look at real data with a build of your own (beta.15, D52): `FrameLedger.exe --data-dir <copy>`.** Make the copy with
SQLite's online backup, which is consistent while the Agent writes — in Python,
`sqlite3.connect("file:C:/Users/<you>/AppData/Local/FrameLedger/ledger.db?mode=ro", uri=True).backup(sqlite3.connect(r"<copy>\ledger.db"))`
— or copy the whole folder with every FrameLedger process stopped
(closing the App does not stop the Agent). 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`:**
@@ -88,7 +104,7 @@ Launch profiles:
Native debugging notes: use **`hook-harness`, never a real game**, for step-through debugging — a breakpoint inside a present hook of a real game freezes it in ways anti-cheat and drivers both dislike. Enable the Vulkan validation layers when touching `FrameLedger.VkLayer`. Application Verifier + PageHeap on the harness catches ring-buffer bugs early.
Agent flags: `--serve`, `--console`, ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
Agent flags: `--serve` (since beta.10 with at most one of `--for-user <SID>` — the account an Agent started as administrator must be, else it exits 11 — or `--elevation declined|other-account|failed` — its starter asked Windows and got this; both from the admin mode, `01_ARCHITECTURE` ADR-9), `--console`, `--write-crash-dump <file>` (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — `10_LOGGING` §Crash handling), ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
> **Built 2026-09-10 (P2 PR-F): `--serve` and `--console`; the other five answer "not implemented in P2"
> with exit 2** rather than being silently accepted (`--diag` is the App's anyway, `10_LOGGING`). The console
@@ -100,6 +116,17 @@ Agent flags: `--serve`, `--console`, ~~`--diag`~~ (the App's — `FrameLedger.ex
> shipped `FrameLedger.Agent.exe` against `hook-harness` with a scratch `--data-dir` and reads the one
> `sessions` row back — the milestone's technical half, in the merge gate.
> **The print verbs open the ledger read-only (2026-09-16).** `sessions`, `consent list` and `killswitch status`
> migrate nothing and refuse — exit 7, the reason on stderr — a ledger at a schema older or newer than the build;
> `db path` opens no file at all. Until then every verb went through the migrating open, and `sessions` run against
> the owner's ledger applied two scripts to it (`06_DATA_MODEL` §Migrations). `AgentReadOnlyVerbsTests` pins the set.
> **One capturing process per data folder (2026-09-17).** `--serve`, `capture`, `launch` and `recover` claim the data
> folder (`AgentInstanceLock`) before logging, rules or the ledger, and exit **10** — one line on stderr, nothing
> written — when another process holds it; the other verbs run beside a serving Agent, as the App's `--install-task`
> does. `OneAgentPerDataFolderTests` runs the shipped binary against a claimed scratch folder
> (`01_ARCHITECTURE` §Lifecycle).
## Bundled assets
- ~~`assets/native/PresentMon.exe` (pinned, SHA-256 verified at build) for the Tier-2 fallback~~ — **DROPPED 2026-08-27, and there are no bundled native assets at all.** §S31 measured PresentMon classifying every frame of a ×4 capture as an application frame (row P2); the owner then dropped it outright. It is not bundled, not fetched, not used, and `tools/frametype-oracle.ps1` — the parser that consumed its output — is deleted with it. `assets/` does not exist and now has no reason to. **And since 2026-08-28 Tier 2 is not a measurement at all**: the ladder is two rungs, `EtwFrameSource` is deleted from the design, and whether a shipped build ever regains a no-injection measurement is `20_OPEN_QUESTIONS` §G.
@@ -135,6 +162,45 @@ repairs state, it does not grant machine-wide reach on its own).
> after every sweep; the flag and the button run the same rule. The uninstall hook is still the updater's
> (P4, Velopack).
## The alpha line (owner decisions D73–D76, 2026-10-31)
The owner, 2026-10-31: an alpha build, "a place where new .NET versions are tried", with code updated where needed and a
warning that it is an experiment used at one's own risk. **The alpha line** is the source of a released beta built on a
prerelease .NET — .NET 11 RC3 first (SDK `11.0.100-rc.3.26522.148`, runtime and Windows Desktop
`11.0.0-rc.3.26522.148`) — from the long-lived `alpha` branch, published as `vX.Y.Z-alpha.N` GitHub pre-releases on
Velopack's `alpha` channel (`13_CI_CD` §The alpha line, `11_UPDATER` §Channels).
- **What differs from main, and nothing else** — `git diff main...alpha` is the whole difference: `RELEASE_LINE`
(`alpha`); `global.json` (the prerelease SDK, `allowPrerelease: true`); the TFM in `Directory.Build.props`
(`net11.0-windows10.0.22621.0` — `SupportedOSPlatformVersion` stays `10.0.19045.0`, so CA1416 still holds the code to
Windows 10 22H2 although Microsoft does not support .NET 11 on its Home and Pro editions); the three Microsoft packages
in `Directory.Packages.props` that are serviced with the runtime (`Microsoft.Extensions.Hosting`,
`System.Diagnostics.EventLog`, `Microsoft.Data.Sqlite`, each `11.0.0-rc.3.26522.148` — the last declares SQLitePCLRaw
3.0.5, SQLite 3.53.4, where main's 10.0.14 declares 2.1.13, SQLite 3.53.3); `legal/licenses/nuget/` regenerated for
that package set; and a fix only .NET 11 can take, if one is ever forced. C# is what `LangVersion latest` gives the
SDK — C# 15 on the 11 SDK — and the source uses none of its syntax: **main must keep building on .NET 10** (D76: retarget
only, no preview feature, no runtime-async).
- **Everything else lives on main**, dormant on the main line. `RELEASE_LINE` is read like `VERSION` and stamped into
every assembly as the `FrameLedger.ReleaseLine` metadata (`Directory.Build.props` refuses any value but `main` and
`alpha`); `Shared.BuildLine` reads it back for the App and the Agent, which compose with it rather than reading it
where they act, so a test hands either line to the code it tests. On the alpha line they act on it (D74): the Alpha
notice in the Legal Gate with its own tick box, the Agent's wait for it, the ALPHA badge and banner, the locked update
channel (`08_UI`), and the ledger's copy before an alpha first opens it (D73, `06_DATA_MODEL` §Migrations). What the
alpha's SDK asks of the source and .NET 10 can also take lands on main.
- **The native layer does not change.** MSVC builds it from the same source; only its build id differs (the alpha's
tag). The hook, the guard and the Vulkan layer in an alpha are the beta's.
- **Sync, and the cadence.** After each beta release a pull request merges main into `alpha` with a merge commit (the
repository allows them; the linear rule is main's) and the next alpha is cut from it — **one alpha per beta, never
several in a row**, because Velopack reads only the newest ten releases (`11_UPDATER` §Channels). A conflict in
`legal/licenses/nuget/` is resolved by regenerating it on `alpha` (`tools/license-gather.ps1`). An alpha older than the
ledger's schema refuses to open it (`LedgerSchemaException`), so a beta that adds a migration is followed by an alpha
soon.
- **Building it locally:** check out `alpha` with the prerelease SDK installed — `global.json` selects it — and run
`./build.ps1 check` as on main.
- **The next .NET build** (an RC, the GA on 2026-11-10, a servicing release) is one line of `global.json` and three
package versions on `alpha`; RC3's support ends at the GA.
- **Whether the main line follows** is not decided here: `20_OPEN_QUESTIONS` §G, *The main line's .NET*.
## Version
**One source: the `VERSION` file at the repository root** (`MAJOR.MINOR.PATCH`, nothing else — P4 PR-5,
@@ -153,6 +219,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.
@@ -161,15 +250,24 @@ assumed to.
```
cmake --build --preset x64-release
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -o out/app
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -o out/app
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --releaseNotes out/notes.md --outputDir out/release
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
vpk download github --repoUrl https://github.com/poli0981/frameledger --channel win --pre --outputDir out/release # beta.13: the previous release, for a delta
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
```
> **On the alpha line (D73, 2026-10-31) both vpk commands take `--channel alpha`** — the download, so an alpha's delta
> is made from the previous alpha, and the pack, so its feed is `releases.alpha.json`, which no beta reads. The main
> line's pack keeps the command above exactly (no `--channel`: Velopack's default on Windows is `win`). §The alpha line.
> **Run by `release.yml` since 2026-09-14 (P4 PR-5)** — `13_CI_CD` §release.yml carries the steps around it
> (the version gate, `{{RELEASE_DATE}}`, the published-tree assertion, checksums, the release). Both publishes
> take `-p:Version=<tag>` (§Version). No `--icon`: `assets/icon.ico` does not exist, and this line named it
> for six weeks.
> for six weeks. **Since beta.12 the App also takes `-p:FrameLedgerSourceRef`** — the tag, or for a rehearsal the
> commit — stamped as assembly metadata so its links into the repository open THIS version's documents
> (`Services/RepositoryLinks`); a build without it links to `main`. **Since beta.14 the Agent takes it too**, because
> `Directory.Build.props` stamps it on every assembly and both publishes build the same libraries into `out/app` (§Version,
> *Identity*).
>
> **The package id is `FrameLedger.App`, and this line said `FrameLedger` until 2026-09-14 — which would have
> deleted every user's ledger on uninstall.** Velopack installs into `%LOCALAPPDATA%\<packId>` and removes that
@@ -203,8 +301,8 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
> prevent.
- 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()`.
- 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.
- `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; 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
@@ -212,33 +310,56 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
the repository, and it is deliberate: the effective date of a legal document is
the date it ships, which is not knowable at authoring time. `release.yml` (**built 2026-09-14**, P4 PR-5 — the step runs before the
build, because the App embeds `legal/*.md`)
substitutes it with the tag date when packaging, and `ci.yml` fails the build if
substitutes it with ~~the tag date~~ the run's UTC date (corrected 2026-10-04) when packaging, and `ci.yml` fails the build if
**any other** `{{` token appears in `README.md` or `legal/*.md` (`13_CI_CD.md`
§ci.yml). Everything else — repository URL, slug, developer identity, contact
address — is resolved in the source files, because an unsubstituted token in a
document the app displays for acceptance (FR-11) is a defect, not a template.
**The build id is read before it (beta.18).** The substitution edits tracked files, and the native build id is
`git describe --dirty` at CMake's configure (`src/native/FrameLedger.Shm/CMakeLists.txt`): every release until beta.18
shipped `<tag>-dirty` — the owner's Dashboard read *Overlay build v0.1.0-beta.17-dirty*, and that run's log printed
`FL_BUILD_ID = v0.1.0-beta.17-dirty` two lines after `RELEASE_DATE = 2026-10-07 in 3 file(s)`. `release.yml` now reads
describe from the clean checkout first, refuses one that is already dirty or longer than 31 characters, and passes it
as the environment's `FL_BUILD_ID`, which CMake takes as given (checked for the characters a C string literal carries);
after the publish, `tools/buildid-check.ps1` reads it back out of the four native binaries that compile it, by their
bytes — nothing is loaded. A developer's build still runs describe itself (`+` marks a dirty tree when the long form
would not fit).
## Local quality gate (pre-push)
`./build.ps1 check`:
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`)
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`) — since beta.12 also `FrameLedger.ProcessStats.dll` (the game
process's memory, D43; staged beside the Agent, CaptureHost and Infrastructure.Tests by
`FrameLedger.ProcessStats.targets`), its ctest `fl_process_stats` (GPU_INSTANCE on a machine with a hardware adapter,
NO_GPU_INSTANCE elsewhere) and the instrument `fl-probe-processstats` (`spike-notes` §16)
2. native tests (Catch2)
3. `clang-format --dry-run -Werror` over `src/native`
4. `dotnet restore` + build (warnings as errors)
5. `dotnet format --verify-no-changes`
6. `dotnet test --logger trx` — including `ShmLayoutMirrorTests`; with no switches it also runs the
`Category=Integration` classes, which CI excludes
`Category=Integration` classes, ~~which CI excludes~~ which CI runs too *(corrected 2026-10-04: `ci.yml` and
`release.yml` call `./build.ps1 check` with no switches since 2026-09-06, as the paragraph after this list says;
only `-SkipIntegration`, which nobody passes, leaves them out, loudly)*
7. `tools/coverage-gate.ps1` — reads this run's cobertura reports; self-arming, and armed today for
`FrameLedger.Domain` and `FrameLedger.Application`
`FrameLedger.Domain` and `FrameLedger.Application`. *(Since 2026-10-25 step 6 writes OpenCover beside each
Cobertura report — `--collect:"XPlat Code Coverage;Format=cobertura,opencover"` — for SonarCloud, whose C# importer
reads no Cobertura; `ci.yml`'s `sonarcloud` job takes them from the gate's artifact, `13_CI_CD` §SonarCloud. This
gate still reads Cobertura only.)*
8. `tools/rules-validate.ps1` (schema + `anticheat` block sanity — a malformed or empty blocklist is a safety bug)
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every `FileVersion` against the `VERSION` file (§Version)
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every `FileVersion` against the `VERSION` file (§Version); **since beta.14 (D50) both halves run — the self-test, then the native five and the managed eight from the App's and the Agent's build output** (`-ManagedDir`, `-ExpectedProductVersion` = `VERSION`), one copyright across all of them (§Version, *Identity*). Under `-SkipNative` the managed half still runs
10. `tools/chokepoint-check.ps1` — injection and evasion primitives confined to one file, native **and** managed, plus the `FL_GUARD_TESTABLE` symbol check against the shipped artifacts
11. **`tools/hookinventory-check.ps1`** — three passes: A resolves every vendor symbol the Overlay names against `docs/vendor-exports.json`, B sweeps for stray literals, C reads the BUILT Overlay's import table and asserts it imports no vendor module. C skips loudly under `-SkipNative`. **Missing from this list until 2026-08-28**, which is §R10 happening again
12. **`tools/package-closure-check.ps1`** — both halves: the self-test (5 cases, 4 of which must go RED) **and** a live pass over this repository. It walks the transitive `ProjectReference` closure of the two publish roots below and fails on anything outside the allowlist, naming the reference edge. `FrameLedger.CaptureHost` is an injecting entry point kept out of the package by construction, and `20_OPEN_QUESTIONS` §S27 is closed on exactly that basis
13. `tools/license-check.ps1` — asserts every vendored third-party has a licence copy in `legal/licenses/`, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that `legal/licenses/nuget/` is exactly what `tools/license-gather.ps1` writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. `license-gather.ps1 -SelfTest` runs first: fourteen fixture cases, five that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture
13. `tools/license-check.ps1` — asserts every vendored third-party has a licence copy in `legal/licenses/`, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that `legal/licenses/nuget/` is exactly what `tools/license-gather.ps1` writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. `license-gather.ps1 -SelfTest` runs first: ~~fourteen~~ sixteen fixture cases, ~~five~~ six that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an expression with no text in the script and no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture. **Since beta.12 (78 packages):** a reviewed override also answers for an expression the script has no text for — Markdig declares BSD-2-Clause and ships no file, and `tools/license-overrides/Markdig.txt` is the project's own `license.txt` at the packaged commit
13b. `tools/accuracy-check.ps1 -SelfTest`, then live — the accuracy block is ONE text (`legal/ACCURACY.md`) embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06)
13c. **`tools/notice-check.ps1 -SelfTest`, then live** (beta.12, owner decision D45, 2026-10-03) — every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`, tracked or new, minus `src/native/third_party/`) opens with `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (`NOTICE` carries them); the second line may name another holder and year in the same form (a contributor's own file).
Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a missing header, and `tools/resx-gen.ps1` generates the accessor with it
13d. **`tools/wiki-build.ps1 -SelfTest`, then `-Check`** (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from `wiki/`, `guide/`, `LIMITATIONS.md` and (beta.35) `ACCESSIBILITY.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~~ Ten self-test cases since beta.35 (the statement's page, D88), 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
+425 -24
View File
@@ -6,9 +6,9 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
## Workflows (`.github/workflows/`)
### `ci.yml` — push to `main` + all PRs · **repo-local**
- `runs-on: windows-latest`, .NET SDK pinned by `global.json` via `actions/setup-dotnet`, MSVC via `ilammy/msvc-dev-cmd`, NuGet cached.
- Single step of substance: **`./build.ps1 check`** — the same script, with the same switches (none), a developer runs before pushing. The gate list lives in `12_BUILD` §Local quality gate, **once**, rather than being restated here where it goes stale.
### `ci.yml` — push to `main` *(and to `alpha` since 2026-10-31, D73 — §The alpha line)* + 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` (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. *(That is the `check` job. Since 2026-10-25 a second job, `sonarcloud`, runs after it — §SonarCloud below; it is not the gate and not a required context.)*
- ~~**`-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
2026-09-10 while merging P2's stack.** Every one was an `Category=Integration` case, every one passed on
@@ -26,6 +26,43 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
wrong by the end of the same evening; it is corrected rather than quietly deleted, because a frequency
claim made from one observation is exactly the shape this file keeps catching.
**Re-run before investigating**; if it reproduces, read the module list and the scan-set reason, not the test.
- **A hang, not a refusal — the first tag run (2026-09-16, run 35111939019).** Every suite green except
`Infrastructure.Tests`, which printed its "test run for …" line and nothing else for 58 minutes until the job's
60-minute limit cancelled the run; the same suite took 42 s in the rehearsal an hour earlier. The log named no
test. ~~`build.ps1` now passes `--blame-hang --blame-hang-timeout 15m --blame-hang-dump-type mini` to `dotnet test`,
so the next hang fails the run in 15 minutes with the test's name in `TestResults\…\Sequence.xml` and a mini
dump beside it — the diagnostic this run lacked. Which test hung is **unmeasured**; the re-run is the measurement.~~
**Found and fixed 2026-09-17.** Reproduced locally one run in eight; the xUnit verbose reporter of a hung run showed
thirteen tests started and none finished, one of them `CrashDumpWriterTests.WritesAMinidumpOfThisProcess…` — which
called `MiniDumpWriteDump` on its OWN process. That call suspends every other thread of the caller, and one holding
the heap or loader lock deadlocks the dumper: the whole test process froze, including xUnit's long-running-test
timer, which is why nothing was ever named. 40 runs without that test: no hang. **The same call was the product's
crash path**, in the App and the Agent — a real crash could have hung instead of dumping. Dumps are written by a
child process now (`Infrastructure.Diagnostics.ParentDump`, `FrameLedger.Agent.exe --write-crash-dump`; `10_LOGGING`
§Crash handling). And **`--blame-hang` did not stop the hung xUnit v3 executable** — still alive four minutes after
a 60 s hang timeout — so `build.ps1` runs `dotnet test` under a 25-minute wall-clock limit instead, kills the tree on
expiry, and names the test projects that wrote no `results.trx`. *(Measured on xUnit v3 3.2.2. The suites moved to
4.0.1 on 2026-09-21 as `xunit.v3.mtp-off`, still under VSTest; whether `--blame-hang` stops a hung 4.x executable is
unmeasured, and the wall clock stays either way.)*
- **Two more shapes had one cause, found and fixed 2026-09-16** after four failures in one evening's merge train:
`AKilledHostLeavesAPartialThatRecoverTurnsIntoAnInterruptedSession` ("the process cannot access the file …
`.partial`") and `WithNoConsentRecordTheHostRefusesAndNothingIsEverInjected` (a leftover consent record). The
suite's `Kill` helper returned before the killed host had released its files, so the next line read a `.partial`
the dead process still held, and the ledger delete in `Dispose` silently failed and left the record for the next
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
@@ -43,7 +80,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
The next Integration failure is the measurement: read the probe step *before* re-running. Struck rather
than deleted because a session planned a workflow change on this bullet's word.
- **Signer probe step** (2026-09-06): `fl-probe-signer` runs as its own step after the gate — `continue-on-error`, a measurement and not a gate — because `ctest fl_signer_probe` passes on a regular expression and prints nothing, so §S19(b)'s CI leg was never readable from the log. Its answers are read off this step.
- Uploads coverage artifacts.
- Uploads coverage artifacts — ~~Cobertura~~ Cobertura and OpenCover since 2026-10-25, one pair per test project, as the `coverage` artifact the `sonarcloud` job reads (§SonarCloud).
- **Changelog gate**, on pull requests only: the changed-file list comes from GitHub's own view of the PR — not `git diff`, so a shallow checkout cannot silently produce a short one — and an empty list is refused rather than read as "no `src/` changes". It is a **step of the required `check` job** and deliberately not a job of its own: `main`'s required contexts are exactly `check` and the two `analyze` jobs, so a new job would go red while the merge button stayed green, which is what already makes `Rules / validate` advisory (§S23-2).
> **Three claims in this section were false and are corrected 2026-08-06.** There is no Vulkan SDK
@@ -55,8 +92,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
> `ShmLayoutMirrorTests` did not execute. `12_BUILD` carried the identical stale sentence and is
> corrected with it; restating the gate list in two documents is what let one of them rot.
- **Licence guard:** `tools/license-check` fails the build if a vendored dependency is missing its licence copy, or if Intel IGCL / AMD ADLX headers appear anywhere in the tree (`docs/18_GPU_VENDOR_APIS.md` §Vendor SDKs we deliberately do not use), or — since P4 PR-6 — if `legal/licenses/nuget/` is not what `tools/license-gather.ps1` writes for the NuGet packages this build ships. A Dependabot bump therefore goes red until someone re-runs the script and commits the texts, which is the point: the new version's licence is read by a person before it ships. Licensing regressions are silent and hard to unwind later — catch them at PR time.
- **Placeholder guard:** fails if any `{{` token survives in `README.md` or `legal/*.md`. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
- `permissions: contents: read`.
- **Placeholder guard:** fails if any `{{` token survives in `README.md` or `legal/*.md` *(other than `{{RELEASE_DATE}}`, which `release.yml` substitutes — added 2026-10-04)*. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
- ~~`permissions: contents: read`.~~ `permissions: contents: read, pull-requests: read` — the second for the Changelog step's list of a pull request's files, read-only *(corrected 2026-10-04)*. *Since 2026-10-25 per job:* the workflow grants nothing (`permissions: {}`), `check` holds those two and `sonarcloud` `contents: read` alone — a workflow-level grant reaches every job (SonarCloud `githubactions:S8264` on the first analysis from CI).
### `codeql.yml` — push, PR, weekly cron · **repo-local**
@@ -65,15 +102,37 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
> CMake preset and that input surface has not been verified. The paragraph below already anticipated
> exactly this outcome; the heading was never updated when it happened.
- Languages: `csharp` **and `cpp`** (manual build mode for C++, driven by the CMake preset). The native layer is where memory-safety bugs would live; excluding it would defeat the purpose. Verify the mixed template exposes a C++ build-command input; if it does not, this one goes repo-local too.
- **And `actions`, since 2026-10-25** (build mode `none`): CodeQL reads `.github/workflows` for injection from event data, untrusted checkouts and over-broad tokens — the class of finding SonarCloud raised once (`githubactions:S7631`, `wiki.yml`, beta.26). Its context, `analyze (actions, none)`, is not one of `main`'s required checks; adding it to them is the owner's setting.
- **Concurrency, since 2026-10-25:** a new push to a pull request cancels that pull request's run; a push to `main` and the weekly scan each run in a group of their own (the run id), so none is cancelled or left pending, and the default branch's alerts come from a finished analysis.
- `permissions: security-events: write, contents: read`.
### `release.yml` — on tag `v*` · **repo-local, built 2026-09-14 (P4 PR-5)**
> **Exercised by a tag on 2026-09-16 — `v0.1.0-beta.1`, run 35111939019 — and the first attempt did not finish.**
> The version gate, the substitution and the quality gate ran; the quality gate then sat in `Infrastructure.Tests` for
> 58 minutes (every other suite green; the same suite 42 s in the rehearsal an hour before) until the job's 60-minute
> limit cancelled it, with no test named. `gh run rerun --failed` on the same tag: the gate in 11 minutes
> (Infrastructure 305 in 17 s), publish (252 MB tree), licences, the tree assertion, `vpk pack` (`Setup.exe` 110 MB,
> portable zip and full nupkg 105 MB), `SHA256SUMS.txt`, and the pre-release created with the section's notes and the
> checksums appended — <https://github.com/poli0981/frameledger/releases/tag/v0.1.0-beta.1>. Two things the tag taught:
> a tag run can be re-run in place after a flake (the Release step is idempotent up to the release existing — it did
> not, so nothing had to be deleted), and a hang eats the whole job budget silently, which is why #196 added
> `--blame-hang` to the gate. The paragraph below is the history as it stood.
>
> This heading said **PLANNED, NOT PRESENT** from 2026-08-06 until the workflow existed, with the note that
> "nothing in this repository has ever run `dotnet publish`". Still true of the *repository's history*: the
> workflow has not been exercised by a tag yet — its publish, tree assertion and `vpk pack` steps were run by hand on
> "nothing in this repository has ever run `dotnet publish`". ~~Still true of the *repository's history*: the
> workflow has not been exercised by a tag yet~~ (struck 2026-09-16, above) — its publish, tree assertion and `vpk pack` steps were run by hand on
> 2026-09-14 (`12_BUILD` §Publish & package has the sizes), the release upload was not. The first tag is the rest of the measurement; until then every other claim below is
> what the file says, not what a run showed.
>
> **A dry run exists since 2026-09-16 (P5 prep).** `workflow_dispatch` with a `version` input runs the identical
> job — gate, publish, runtime licences, tree assertion, `vpk pack`, checksums, the artifact upload — and skips only
> `gh release create`; no tag is made. Two things differ from a tag run, both deliberate: the version comes from the
> input (its numeric core must still equal `VERSION`), and a missing `## [x.y.z]` section is a printed warning with
> placeholder notes rather than a stop, because that section is written in the tag commit and a rehearsal precedes
> it. The artifact is `release-<version>-dry-run`. Run it with `gh workflow run release.yml -f version=0.1.0-beta.1`
> (on the branch that carries the file, `--ref <branch>`); the result is what the first tag will do, minus the
> upload. The rehearsal's outcome is recorded in `CHANGELOG.md` when it has run.
- `runs-on: windows-latest`, the same .NET / MSVC / clang-format pins as `ci.yml`, `permissions: contents: write`
(the Release API) and nothing else.
@@ -81,29 +140,49 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
`VERSION` file (`12_BUILD` §Version); and `CHANGELOG.md` must carry a **non-empty** `## [x.y.z]` section for the
full version, extracted by `tools/release-notes.ps1` (self-tested on every `build.ps1 check`). A missing
section is a red release, not an empty note — the ledger's header said the opposite for five weeks.
- **The build id from the clean checkout** (beta.18): `git describe --always --dirty --abbrev=12` before anything edits a
tracked file — a dirty one or one over 31 characters stops the run — into `FL_BUILD_ID` for CMake. Until beta.18 the
substitution below ran first and every release's natives called themselves `<tag>-dirty` (`12_BUILD` §Release-time
token substitution).
- `{{RELEASE_DATE}}` substituted in `legal/*.md` with the run's UTC date **before the build**, because the App
embeds those documents (FR-11); any `{{` token left anywhere after that fails the job.
- **The identical gate** — `./build.ps1 check`, native first, every tool including `versioninfo-check` against
`VERSION`. A release never skips it.
- `dotnet publish` App + Agent, self-contained + ReadyToRun, `-p:Version=<tag>`, into one `out/app`.
- **The published tree asserted by name**: `FrameLedger.exe`, `FrameLedger.Agent.exe`, the four shipped natives
`versioninfo-check` lists, `rules/detection-rules.json`; `FrameLedger.CaptureHost.exe` absent (`12_BUILD`:
- **The published tree asserted by name**: `FrameLedger.exe`, `FrameLedger.Agent.exe`, the ~~four~~ five shipped natives
`versioninfo-check` lists (`FrameLedger.ProcessStats.dll` since beta.12 — corrected 2026-10-04), `rules/detection-rules.json`; `FrameLedger.CaptureHost.exe` absent (`12_BUILD`:
exactly two roots — `package-closure-check` proves it statically, this reads the directory); `versioninfo-check`
run again over `out/app`, because a `.targets`-staged DLL that failed to copy is a warning to `dotnet publish`.
- `vpk pack --packId FrameLedger.App` (the `vpk` tool pinned to the library's 1.2.0) with the release notes;
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~~ 1.2.161 since beta.30, D71) 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
(`12_BUILD` §Publish & package). No `--icon` until `assets/icon.ico` exists.
- `SHA256SUMS.txt` over every asset, published beside them and printed into the release body (`11_UPDATER`
§Unsigned releases).
- `gh release create` with the assets, `--verify-tag`, and `--prerelease` for a `-beta.N` tag.
- **The alpha line (D73, 2026-10-31):** the version gate reads `RELEASE_LINE` beside `VERSION` and refuses a tag that
disagrees with it — on the `alpha` line only `vX.Y.Z-alpha.N`, and an `-alpha.` tag nowhere else. An alpha's download
and pack take `--channel alpha`, so the feed, the asset list, the legacy index and the installer are named for that
channel (`releases.alpha.json`, `assets.alpha.json`, `RELEASES-alpha`, `FrameLedger.App-alpha-Setup.exe`, and the
packages themselves, `FrameLedger.App-<version>-alpha-full.nupkg` / `-alpha-delta.nupkg` — measured on the first alpha's
rehearsal, after which the delta check reads the name from `assets.<channel>.json` rather than building it) and its delta
is made from the previous alpha; the main line's pack is unchanged. The release is titled *(experimental alpha)*, and
its notes — the alpha's own file, `docs/changelog/x.y.z-alpha.N.md` — open with the warning (§The alpha line).
- The assets and the notes are also uploaded as a workflow artifact for the smoke checklist (`14_TESTING`
§Release smoke).
- ~~Optional final step: submit installer hash to VirusTotal~~ — not built; an upload of the installer to a third
party is a decision the owner makes, not a step a workflow adds quietly.
### `rules-publish.yml` — on change to `rules/detection-rules.json` in `main`
- Runs `tools/rules-validate` and fails on anti-cheat removals. The raw file on `main` **is** the distribution endpoint (05_DETECTION), so this workflow only gates correctness.
### `rules-publish.yml` — ~~on change to `rules/detection-rules.json` in `main`~~ on a PR or push to `main` touching the rules file, its schema, `rules-validate.ps1` or this workflow (corrected 2026-10-04)
- Runs `tools/rules-validate` and fails on anti-cheat removals. ~~The raw file on `main` **is** the distribution endpoint (05_DETECTION), so this workflow only gates correctness.~~ *(Corrected 2026-10-04: there is no feed — §S20's feed half is deferred and nothing in `src` fetches. A rules change reaches users only inside a release, seeded by the Agent from the packaged copy; this workflow only gates correctness.)*
> **There is no `rulesVersion` bump check, and this line used to claim one.**
> `rules-validate.ps1` checks the field's *format* and nothing compares it
@@ -127,35 +206,357 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
> evaluator through the real probe. Both halves run on the same PR; only the
> coverage half fires on a rules-only change, which is why the two are
> described separately rather than as one gate.
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix.
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix. *(Added 2026-10-04: the PR-only removal step fails the job on any removal, a shrunk per-title list or an added trusted signer, whatever the body says — the justification is for the reviewer, and the job stays red.)*
- `permissions: contents: read`.
## Dependabot (`.github/dependabot.yml`)
### `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` and, since
beta.35 (D88), `ACCESSIBILITY.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*, `ACCESSIBILITY.md` as *Accessibility*), 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 in this repository (`head_repository` is checked since beta.26: a fork cannot start the Release run,
and the condition now says so — SonarCloud `githubactions:S7631`), 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. **Not after an
alpha's release** (D73, 2026-10-31: a `-alpha.` tag is skipped): the wiki shows the newest beta. 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.
## The alpha line — the `alpha` branch (owner decisions D73–D76, 2026-10-31)
What it is and what differs on the branch: `12_BUILD` §The alpha line. What CI and the release do with it:
- **`ci.yml`** runs `check` on a push to `alpha` and on every pull request into it, under the branch's own `global.json`
— `setup-dotnet` installs the exact prerelease SDK it names whatever the `rollForward`. The `sonarcloud` job does not
run for the branch (the organisation's plan analyses main alone, §SonarCloud), and neither does the `Changelog` step:
what an alpha changes is written in its release's own file on main, never in an `[Unreleased]` entry on `alpha`, which
would collide with main's at every sync.
- **`codeql.yml`** stays on main: the source is main's, and CodeQL's extractor reads C# 14 (CodeQL 2.25.6, June 2026)
while the alpha's compiler is C# 15.
- **The branch is not protected** (an owner's setting; none was asked for): pull requests into it are how changes land
(squash), and the sync from main is a pull request merged with a merge commit — main's linear rule is main's alone.
- **A release of the line**, in order: the alpha's notes on main (`docs/changelog/x.y.z-alpha.N.md` opening with the
warning, its row in `CHANGELOG.md`'s Releases table, a line in HANDOFF's START HERE) → the sync pull request into
`alpha` → a `release.yml` dispatch on `alpha` (`gh workflow run release.yml --ref alpha -f version=x.y.z-alpha.N`) →
the signed tag on `alpha`'s head → the run (§release.yml: the line's tag rule, `--channel alpha`). **No wiki publish**
(`wiki.yml` skips an `-alpha.` tag) and **no release line moves**: README, ACCURACY, the Disclaimer's copy,
LIMITATIONS and ACCESSIBILITY keep naming the newest beta.
- **The cadence:** one alpha per beta, cut from it. Velopack's GitHub source reads the newest ten releases (one page,
`perPage` 10), so ten alphas in a row would hide every beta from the betas' own update check, and the other way round
(`11_UPDATER` §Channels).
## SonarCloud — from CI, `ci.yml`'s `sonarcloud` job (owner decision D68, 2026-10-25)
**D68 — SonarCloud is analysed from CI.** The owner turned SonarCloud's Automatic Analysis off and set the
`SONAR_TOKEN` secret (2026-10-24), and asked for the CI-based analysis with the newest scanner, run until its quality
gate passed on issues and coverage both. It replaces D67 (the subsection below, as it stood): `.sonarcloud.properties`
is gone, `SonarQube.Analysis.xml` holds what it held, and the two rules broken by design everywhere are configuration
rather than marks in the UI.
**How it runs.** A second job of `ci.yml`, after `check` (`needs: check`), on every pull request from this
repository and every push to `main` (or a `workflow_dispatch` of `main`) — never another branch: the organisation's
plan refuses a branch analysis ("Organization is not allowed to access data from non main branches", a dispatch of
the feature branch, 2026-10-25), so a dispatch of any other branch runs `check` alone:
1. a full-depth checkout (blame dates the new code; the tags name the version), .NET, MSVC, the NuGet and
`~/.sonar/cache` caches;
2. the gate's coverage — the `coverage` artifact `check` uploaded, not a second test run;
3. `cmake --preset x64-release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_SCAN_FOR_MODULES=OFF` and the one
header the build generates (`fl_ac_floor_gen`) — the compilation database, with nothing compiled. *Scanning off
because the first run failed on it:* with C++20 and Ninja, CMake gives every compile command an
`@<object>.modmap` response file that only the build writes, and the C/C++ analyser (CFamily 6.85) stops with
`IllegalStateException: unexpanded response file`; no source here uses a module;
4. **SonarScanner for .NET 12.0.0** (2026-10-15, the newest), a local tool (`.config/dotnet-tools.json`, `dotnet tool
restore`; Dependabot's nuget entry moves it), which provisions its own JRE: `begin` with `/s:SonarQube.Analysis.xml`
→ `dotnet build FrameLedger.slnx -c Release` → `end`.
**Why a job of its own, and a build of its own.** The scanner's targets turn `TreatWarningsAsErrors` off and empty
`WarningsAsErrors` in every build they instrument (`SonarQube.Integration.targets`, read in 12.0.0's source), so
wrapping the gate's build would quietly weaken the gate. And the job is **advisory**: `main`'s required contexts stay
`check`, `analyze (csharp, none)` and `analyze (cpp, manual)`. It waits for the quality gate
(`sonar.qualitygate.wait`), so a failed gate — or a SonarCloud outage — is a red job beside a green `check`, never a
blocked merge, and SonarCloud's app still posts its own *SonarCloud Code Analysis* check on the pull request.
**The C++.** The SonarScanner for .NET analyses only files an MSBuild project names: it drops `sonar.sources`, and
its scan of the files outside the projects (`sonar.scanner.scanAll`: PowerShell, YAML, JSON and a dozen more) has no
C or C++ in its list (`AdditionalFilesService`, 12.0.0). So `FrameLedger.Infrastructure.csproj` — the project that
reaches the native layer — names `src/native`'s `.cpp` and `.h` files, `third_party` excepted, as `FlNativeSource`
items, read through the scanner's `SQAdditionalAnalysisFileItemTypes`. The items exist only in a build the scanner
instruments (its ImportBefore targets set `SonarQubeTempPath`), so a normal build, an IDE and a publish never see them;
because they lie outside the project's folder, the scanner analyses them at the root, with the compilation database:
MSVC's own flags and defines, where Automatic Analysis guessed them. Native code has no coverage report (below).
**Coverage.** `build.ps1` collects `"XPlat Code Coverage;Format=cobertura,opencover"`: Cobertura for
`tools/coverage-gate.ps1`, as before, and OpenCover for SonarCloud, whose C# importer reads no Cobertura. The
reports' paths are absolute, and every hosted Windows runner checks out to the same path, so the reports `check`
wrote name the sources this job reads. Only `tests/*/TestResults/<guid>/` is read; the trx logger's second copy under
`In/` is not. **Coverage is the C#'s alone** (`sonar.coverage.exclusions`): SonarCloud counts the executable lines of
a file no report covers as uncovered — the first pull request analysis read `build.ps1`'s 232 lines to cover, every
one uncovered, and failed the gate at 0 % on the two it changed — so the PowerShell tools (proven by their own
`-SelfTest` cases, which no coverage tool reads) and the native code (Catch2 and the injection tests, with no coverage
collector) are left out of the coverage figures; they are analysed for issues as everything else is. Measuring the
native code would be the runner's Visual Studio coverage tool and `sonar.cfamily.*` coverage paths — not done.
**The version, and so the new code.** The project's new-code period is SonarCloud's *Previous version*. Until now
every analysis was "not provided", so the new code was everything since the first analysis (2026-09-27): 34,268 lines
on 2026-10-20. The job now passes `/v:` the newest `v*` tag the commit descends from, so new code is everything
since the last release — **from the second analysis with a version on**, measured on `main` (below): the first,
`main`'s first from CI, still counted from before any version existed; the second set the start at the last analysis
without one (2026-10-20 05:11; 257 new lines on 2026-10-25). An issue the CI analysis raises on an older line is
dated by blame — the newest line of its path — and is new code only when that line is. The gate is *Sonar way*: its
coverage condition (80 % on new code) was skipped while no analysis had coverage, and applies from the first analysis
from CI.
**What it reads** — `SonarQube.Analysis.xml`: the exclusions of `.sonarcloud.properties` (below) and what a build
writes into the checkout, since the scanner walks all of it (`build/`, with the sources CMake fetches there, `out/`,
every `bin/` and `obj/`, `TestResults/`) — SonarCloud also drops what `.gitignore` names (the first run: "63 files
ignored because of scm ignore settings"), and the patterns say it in the file rather than rely on that; the same
duplication exclusions; C++20; UTF-8; the OpenCover paths; the compilation database;
**`sonar.cs.roslyn.ignoreIssues`** — Roslynator, Meziantou, the VS threading and the .NET
analyzers already gate the build, warnings as errors, and what they report at a lower severity is this project's
choice, so only SonarCloud's own rules are imported; and **two rules ignored where they apply by design** — `S8417`
(sequentially consistent atomics) in `src/native`, any repository because a header is indexed as C, and
`csharpsquid:S6640` (unsafe code) in Infrastructure and Shared. Those are the optional rows of the owner's steps below,
which the UI's *Ignore issues on multiple criteria* would have held; a pull request adding atomics no longer fails the
gate on them.
**What it does not cover.** A fork's pull request and Dependabot's get no secrets, so the job is skipped for them;
Dependabot's would run if the owner added `SONAR_TOKEN` to the repository's *Dependabot secrets*. A pull request's
analysis lists only the issues on the lines it changed, and no other branch can be analysed (above), so what the
analysis from CI finds in the older code shows on `main`'s first analysis from CI and nowhere before it.
**The first analyses (2026-10-25, PR #334).** Run 40147463349: the scanner began, the build ran, the C# coverage was
imported (635 files) — and CFamily stopped on the `.modmap` response files (step 3). Run 40148541525, with scanning
off: everything analysed — 1,300 files indexed, 249 left out by the exclusions and 63 by `.gitignore`; of the
compilation database's 181 units, 32 analysed in full (none partly; 118 whose sources are not analysed — the vendor
stubs and what CMake fetched, Catch2 and MinHook —, 18 duplicates, 13 it does not support) in 139 s; 21 C and 32 C++
files indexed (a `.h` is C to SonarCloud) — and the
gate failed on two conditions, both fixed the same day: `githubactions:S8264` (a C security rating: workflow-level
permissions reaching both jobs) and 0 % coverage on new code (`build.ps1`'s lines, before the coverage exclusions).
A dispatch of the branch (40148544753) analysed it and was refused the gate, which is how the plan's limit was found.
**`main`'s first analysis from CI (run 40160302893, the merge of #334).** The gate failed on one condition, a C
reliability rating on new code, and passed the others (84.7 % coverage on new code). The 34 open issues were all C++,
raised there for the first time — the real MSVC flags let CFamily see them — and each dated by blame, 2026-08-02 to
2026-10-19. Two were new code: `hook-harness`'s null dereferences, whose paths reach lines changed on 2026-10-19 — two
MAJOR bugs, so C; the BLOCKERs were older lines. (A pull request's analysis never showed any of them: it reports no new
issue on an old line.) The next analysis, the merge of #335 at 05:20, moved the new code's start to 2026-10-20 05:11
and turned the gate green with nothing fixed; the merge of #336 at 06:17 closed 33 of the 34. The 34th, `S3519` in
`fl_patch_check.h`, stayed open: its `NOSONAR` sat on `p -= 5`, and SonarCloud reports the read on the line after —
moved there by the release pull request. The C# had none open. Beta.29 PR-3 settled them — fixed where the code was
wrong, `// NOSONAR` with its reason above it where the analyser was (five):
| Rule | Where | n | What it was | Done |
|---|---|---|---|---|
| `cpp:S2275` format/argument | `fl-probe-nvapi` | 19 | `%u` for `NvU32`, an `unsigned long` (32 bits on Windows, so nothing printed was wrong) | `%lu`; the machine line `CaptureHost` parses prints the same |
| `cpp:S2259` null dereference | `hook-harness` `main.cpp` ×2, `proxy_swapchain.h` | 3 | **real:** `--vulkan` and `--opengl` create no D3D11 objects, and `--opengl` alone ran the default probes through a null swapchain, as did any D3D11 mode beside either flag | `HaveD3D11`, asked first by every mode that drives the D3D11 swapchain; the duplicate mode flags are one |
| `cpp:S2259` | `fl_ring.h` `Publish` | 1 | the path runs on past a failed `REQUIRE(w.Init(...))` in `ring_test`, which ends the test case; every real caller publishes through a writer whose `Init` succeeded, before any hook is installed | `NOSONAR` — a comment on the per-present path, no code |
| `cpp:S3519` negative offset | `fl_patch_check.h` | 1 | by design: the 5 bytes before a hot-patchable function are its patch area, which the check reads under `StillOurs`' SEH guard | `NOSONAR`, no code |
| `cpp:S6232` union pun | `dllmain.cpp`, the log's QPC epoch | 2 | `LARGE_INTEGER f{}` makes the union's first member, the `LowPart`/`HighPart` struct, the active one, so reading `QuadPart` reads a member that is not — undefined in C++, whatever `QueryPerformanceFrequency` wrote | initialised through the member read, `{.QuadPart = 0}` |
| `cpp:S6232` | `guard_test.cpp` | 2 | a `ULARGE_INTEGER` to take a second off a `FILETIME` | 64-bit arithmetic on the two halves |
| `cpp:S5813` `strlen` | `guard_test.cpp` | 1 | `strlen` of a fixed-size rules value | `strnlen(…, kMaxValueLen)` |
| `cppsecurity:S9340` index from input | `layer.cpp`, `fl-baseline-probe` | 2 | the terminator written at the count `ReadFile` / `fread` returned, which never exceeds the request | the bound tested first (in the layer, its once-per-process enable-list read — whose `LARGE_INTEGER size{}` drew this PR's own `S6232` twice, and is initialised through `QuadPart` too) |
| `cppsecurity:S5145` log injection | `rules_budget_test.cpp`, `fl-baseline-probe` ×2 | 3 | console output of a test and a probe: four numbers, and the ids of the seed rules file fixed at build time | `NOSONAR` |
**The C# gate is the server's profile, not the analyser's defaults.** SonarCloud applies *Sonar way core* here (166 C#
rules, 176 C++). A local build with the `SonarAnalyzer.CSharp` package and its own default rules reports about 240
findings in this code, nearly all from rules that profile does not activate (`S3358`, `S6667`, `S3267`, `S108`,
`S3236`, `S2094`, `S927` among them); chasing them changes code for nothing the gate reads. What counts is
`api/issues/search` for `main` or the pull request.
### Until 2026-10-25 — Automatic Analysis, no workflow (beta.24, owner decision D67)
*The text from here to the end of this section stood as written; what changed is marked.* ~~The project
`poli0981_frameledger` is analysed by SonarCloud's GitHub app in **Automatic Analysis** mode: on every~~ The project
`poli0981_frameledger` was 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~~ *done
2026-10-25 (D68, above)*.
**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 six left open after the trains (2026-10-19, beta.26)** — the analysis of `main` at `e35b971` (0.1.0-beta.25),
after the owner's marking: 366 issues resolved (284 fixed — the exclusions and beta.24 PR-2 —, 49 accepted, 33 false
positives) and six open, all in the new-code period, which is why its quality gate read C for reliability and security.
Five were written after the analysis of `372389c` the table above was built from.
| Rule | Issues | Verdict | Comment for the UI |
|---|---|---|---|
| `csharpsquid:S3869` `DangerousGetHandle` | 1 | **Accept** — the row above | as above |
| `csharpsquid:S1244` floating-point equality | 4 | **False positive** | Exact on purpose. `ColorMath.Hsv` compares `max` with `r` and `g` — `Math.Max` returned one of them, the same double; `MarkdownView`'s `next == _wheelTarget` is true only when `next` was assigned `_wheelTarget` (the snap that ends the easing); `SensorsChart.Line`'s `scale == 1.0` compares a parameter with its own default literal to skip a copy. |
| `githubactions:S7631` untrusted code from a fork | 1 | **False positive**, and hardened in beta.26 | `wiki.yml` checks out `workflow_run.head_sha` only after a successful Release run started by a pushed `v*` tag, which a fork cannot start; since beta.26 it also requires `workflow_run.head_repository` to be this repository. |
**Marked by the owner the same day** (2026-10-19, 14:27–14:29 UTC), each as the table says: the four `S1244` and
`S7631` as false positives, `S3869` accepted. `main`'s next analysis (`6b07eb2`) has no open issue and its quality gate
passes.
**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. *(Since D68 the `S8417` and `S6640` rows are `SonarQube.Analysis.xml`'s, in the
repository; `S6232`'s are not — a union read outside `LARGE_INTEGER` would be a finding — and its 24 stay marked.)*
## Dependabot (`.github/dependabot.yml`) and the NuGet audit
```yaml
version: 2
updates:
- package-ecosystem: nuget
- package-ecosystem: nuget # also .config/dotnet-tools.json (the SonarScanner, since 2026-10-25)
directory: /
schedule: { interval: weekly }
cooldown: { default-days: 7 } # since 2026-10-25
groups: { minor-and-patch: { update-types: [minor, patch] } }
# ignore: WPF-UI*, FluentAssertions majors — the file says why
- package-ecosystem: github-actions
directory: /
schedule: { interval: weekly }
cooldown: { default-days: 7 } # since 2026-10-25
groups: { actions-minor-and-patch: { update-types: [minor, patch] } }
```
Central package management makes Dependabot PRs single-file diffs.
- **Cooldown (2026-10-25):** a version update waits seven days after its release is published, so a release that is
pulled or found compromised in its first week never becomes a pull request here. Security updates do not wait — the
option does not apply to them. The actions' minor and patch releases come as one pull request; a new major comes
alone, because it is the one that changes inputs.
- **No `dotnet-sdk` entry, on purpose:** `global.json` is a floor (10.0.100) with `rollForward: latestFeature`, so a
developer's machine and the runner already build with the newest 10.0 SDK they have (the runner installed 10.0.402
on 2026-10-20). Raising the floor is a decision about what a contributor must install, not an update.
- **Dependabot has never proposed a NuGet library update here — measured 2026-10-25.** Every NuGet pull request it
opened, #66 (2026-08-09) through #314 (2026-10-18), updated analyzers only (Meziantou, Roslynator, the VS threading
analyzers), while Dapper 2.1.89 (published 2026-09-23), coverlet 10.1.0 (09-27), xunit.v3.mtp-off 4.0.2 (10-09) and
the 10.0.13 servicing packages (10-13) were never proposed. Its update runs are GitHub Actions runs of their own (`gh
run list`, event `dynamic`), and the run of 2026-10-18 (39134906593) logs the test projects' resolution failing —
`Requested dependency resolution to include coverlet.collector/10.1.0 but it was instead resolved to 10.0.1`, `The
package FluentAssertions.7.2.2 is not compatible. Incompatible project frameworks: net10.0-windows10.0.22621` — and
opens nothing for them. The run of 2026-10-25 (40160307095), the first with the cooldown, says it of the shipped
libraries too, the versions in use among them — `The package Dapper.2.1.86 is not compatible. Incompatible project
frameworks: net10.0-windows10.0.22621`, and the same of Hosting, Sqlite, EventLog, Markdig and Velopack. Why its
resolver reads a package that targets `netstandard2.0` as incompatible with this framework is **unmeasured**. So a
quiet Dependabot is not evidence that the packages are current: `dotnet list FrameLedger.slnx package --outdated` is,
and the updates it had missed were made by hand in beta.29 PR-2 (#335) — `coverlet.collector` 10.1.0 excepted,
whose reason `Directory.Packages.props` gives beside it.
- **beta.30 (2026-10-26), by hand under the same cooldown** (the owner: "check the dependencies and conflicts, update if
needed"): Velopack and `vpk` 1.2.0 → 1.2.161 (the owner's decision, D71 — never 1.2.158, NuGet-deprecated), Markdig
1.4.0 → 1.4.2 (parser fixes; its licence text unchanged at the packaged commit), and **the `SQLitePCLRaw` pin
dropped**: `Microsoft.Data.Sqlite` 10.0.13 declares the patched 2.1.13, and the 3.0.5 pin had put it on SQLitePCLRaw's
3.x line — a cross-major resolution NuGet does not report, because the declared range has no upper bound. The engine
is now 2.1.13's, SQLite 3.53.3 (it was 3.53.4 under the pin; 2.1.14 carries 3.54.0 and comes with Microsoft's next
servicing). Not taken: the 10.0.14 servicing packages (published 2026-10-25, the out-of-band Brotli fix — which is
the RUNTIME's, shipped by the SDK the release builds with, not in a package referenced here), Markdig 1.5.0
(2026-10-24), CsWin32 0.3.366 (it changes how SafeHandles are generated; 0.3.367, its fix, is from 2026-10-22), and,
as before, `coverlet.collector` 10.1.0 and FluentAssertions 8. Catch2 3.16, NVAPI R615 (its licence file changed),
the Vulkan and Streamline headers and clang-format (paired with Visual Studio's) were read and not needed.
- **beta.31 (2026-10-26), the owner's request — inside the cooldown, on purpose** ("làm thêm bản beta 31 với các deps
còn lại (.net 10.0.14) và 1 số thư viện khác"; owner decision D72): `Microsoft.Extensions.Hosting`,
`Microsoft.Data.Sqlite` and `System.Diagnostics.EventLog` 10.0.14 (published the day before; `Microsoft.Data.Sqlite`
10.0.14 still declares `SQLitePCLRaw` 2.1.13), Markdig 1.5.0 (its licence text again byte-identical at the packaged
commit), CsWin32 0.3.367 (0.3.366 changed how SafeHandles are generated, 0.3.367 fixed its overflow; nothing here
needed a change), Meziantou.Analyzer 3.0.317 (no new finding), Catch2 3.16.1 for the native tests (clean under
`/W4 /WX`, the `/EHsc` fix kept), and `coverlet.collector` 10.1.0 — `NoSecondMatcherTests` now leaves out the
`Coverlet.*` types the collector injects, whose constant reflection cannot read; they were never ours. Still not
taken: FluentAssertions 8 (its licence), and the vendored native SDKs (NVAPI R615's licence file changed; the Vulkan
and Streamline headers follow the measured loader and titles).
- **The NuGet audit** (`Directory.Build.props`, written down 2026-10-25): `NuGetAudit` on, `NuGetAuditMode` `all`
(transitive packages too), `NuGetAuditLevel` `low` — the SDK's defaults for net10.0, stated so that a later SDK's
defaults cannot move them. With `TreatWarningsAsErrors` a vulnerable package is NU1901–NU1904 and the restore, so
the gate, is red — what `SQLitePCLRaw` 2.1.11 did (`Directory.Packages.props`). `dotnet list FrameLedger.slnx
package --vulnerable --include-transitive` read none on 2026-10-25.
- **The repository's own alerts:** Dependabot alerts and security updates are enabled, and so are secret scanning and
its push protection (read from the API, 2026-10-25); no alert of either kind, and no code-scanning alert, was open.
## Branch & release policy
- `main` protected: CI + CodeQL required, linear history, no direct pushes.
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) *(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).
- **Alphas (D73, 2026-10-31):** `vX.Y.Z-alpha.N`, tagged on the `alpha` branch only — `release.yml` refuses one anywhere
else, and any other tag there — published as GitHub pre-releases on Velopack's `alpha` channel. §The alpha line above.
## Repo hygiene checklist (one-time setup)
## Repo hygiene checklist
- [ ] Add repo-local `ci.yml`; add caller stubs for CodeQL + release pointing at `poli0981/.github` with the explicit permissions above
- [ ] Enable Dependabot alerts + security updates
- [ ] Add `bug_report.yml`, `feature_request.yml` issue forms; PR template referencing CLAUDE.md definition-of-done
- [ ] Branch protection as above
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `presentmon`, `game-performance`
> Rewritten 2026-09-16 (P5 prep). The list below had every box unticked while three of them were done in the
> tree, and its first box asked for caller stubs this file's own opening paragraph says were never the design.
> In-tree items are stated as done with their location; the rest are GitHub settings only the owner can set,
> listed as such rather than as work a PR could close.
**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 *(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 *(and since 2026-11-09, beta.35, D88: `accessibility.yml`, the form `ACCESSIBILITY.md` sends a barrier to, and the PR template's user-interface section)*
- [x] The labels the forms apply exist *(2026-11-09: `accessibility`, and `safety` and `priority-high`, which `safety_gap.yml` had named since it was written (2026-08-02) while the repository had neither — GitHub applies only a label that exists, so no Safety gap report was ever labelled)*
- [x] `ACCESSIBILITY.md` — the accessibility statement: WCAG 2.2 AA through WCAG2ICT as a goal, never a claim; how a barrier is reported and handled (2026-11-09, D88)
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly; a seven-day cooldown and the actions grouped since 2026-10-25 — and a NuGet library update it never proposed is `dotnet list package --outdated`'s to find, §Dependabot and the NuGet audit)
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
- [x] A release rehearsal: `release.yml` `workflow_dispatch` runs every step but the Release itself (§release.yml)
**GitHub settings — the owner's (`HANDOFF` §Owner-only):**
- [x] Branch protection as §Branch & release policy states *(marked 2026-10-04, read from the API: required checks `check`, `analyze (csharp, none)` and `analyze (cpp, manual)`; linear history; a pull request required; force pushes off; enforced for admins)*
- [ ] `Rules / validate` as a required check (§S23-2, after its skip-shim)
- [x] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting) *(marked 2026-10-25, read from the API: both enabled, with secret scanning and its push protection)*
- [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)
+91 -6
View File
@@ -1,26 +1,34 @@
# 14 — Testing
Managed: xUnit + FluentAssertions + NSubstitute. Native: Catch2. Coverage goal ≥ 80% on `Domain` + `Application`; **Domain metric calculators ≥ 95% or the PR fails**.
Managed: xUnit.net v3 4.x (the `xunit.v3.mtp-off` variant since 2026-09-21 — `build.ps1` runs the suites under VSTest for the coverage collector and `results.trx`; `Directory.Packages.props` says why) + FluentAssertions 7.x + NSubstitute. Native: Catch2. Coverage goal ≥ 80% on `Domain` + `Application`; **Domain metric calculators ≥ 95% or the PR fails**.
## Safety-guard tests (highest priority — these protect users, not code quality)
The anti-cheat guard is the one component where a bug can cost someone an account. It gets the most rigorous treatment in the codebase:
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. ~~Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).~~ **Landed long since** — `ctest` runs ~~31~~ 32 native suites on every gate (`fl_process_stats` since beta.12 — corrected 2026-10-04) (`fl_guard` alone is ~100 s); the sentence was left in the future tense until 2026-09-21.
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set.
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. ~~Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set.~~ *(Corrected 2026-10-04: both have data since 2026-09-25 — Ricochet a driver and services, VAC per-title lists of Steam ids and executables, which `rules_budget_test.cpp` matches back to "Valve VAC".)* **Since 2026-09-25** the fixture is generated from the shipped seed (`rules_budget_test.cpp`: every entry's every value matches its own family in its own group, which also catches a row an earlier prefix shadows), and Ricochet's fixture asserts its data; VAC's still asserts that no family entry fakes it.
- **A finding turns the game's hooking off (2026-09-22), and the proofs are about WHICH findings.** `AntiCheatVerdictTests` pins `IsFindingAboutTheGame` per reason (in the game: yes; machine-wide driver or service, heuristics, failed scans, the latch: no) and that a finding without a family is not one; `CaptureSessionTests` that a start-time `BlockedModule` writes the block, keeps the consent stamp and says `HookingTurnedOff`, that a `BlockedDriver` refuses the session and leaves the row alone, and that the 30 s re-scan's finding writes the same block; `RecordedSessionEventsTests` and `SafetyNoticesTests` that the flag travels to the notice. The override of 2026-09-21 had its own proofs for one day; they went with it, and `NoSecondMatcherTests` counts the port's four methods again.
- **Fail-closed proofs:** malformed `detection-rules.json`, missing `anticheat` block, unreadable target process, `EnumProcessModulesEx` failure, partial module list → **all must refuse injection**, never allow. Each is a named test.
- **Measured error paths that must be named tests** (`spike-notes.md` §1): `ERROR_PARTIAL_COPY (299)` from a suspended target, `ERROR_ACCESS_DENIED (5)` from a protected one, a driver-list parse whose paths are not native paths, and a service query returning `ACCESS_DENIED` — the last of which **cannot be produced on real services by a standard user**, so it exists only as a fake. Every one means REFUSE.
- Mid-session detection: simulated late-loading anti-cheat module → `unhookRequested` set, hooks disabled within one frame, session finalized `unhooked_safety`. Cover the **driver** scan too, not only modules: a machine-wide driver can start after injection.
- **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**; 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.
- Static pre-scan: a game directory containing `EasyAntiCheat/` renders `hook_enabled` un-settable; API-level attempt to set it is rejected — including via `SetWatchlist`, which no longer carries hooking state at all (`07_IPC` §The pipe is not a trust boundary). ~~**The toggle half needs persistence and is not built yet**~~ **built in P2/P3**: `SqliteGameConsentStore.RecordGuardBlockAsync` forces `hook_enabled = 0`, `AgentCommandHandler.SetHookEnabledAsync` re-runs the pre-scan and answers `Refused`, and `GameDetailViewModel` disables the toggle on a blocked row (corrected 2026-09-21; since 2026-09-22 a finding at a session's start or at the re-scan writes the same block — `CaptureSessionTests`); the scan itself is ctest `fl_prescan`, whose matrix is mostly fail-closed: a listing that FAILED, one that was TRUNCATED, a directory that could not be established, unusable rules, and a missing evidence source must each be *undetermined*, never clean. Two cases exist only to stop the rest passing vacuously — a genuinely clean directory must be **allowed**, and a name matching the wrong group (a directory named like a `files` entry) must **not** fire. One case removes a family from the rules and asserts the hit disappears, which is what proves there is a single matcher rather than a second one that happens to agree.
> **D48 (beta.14):** the module check's one re-read is held both ways in ctest `fl_guard` `[D48]` — a member still
> loading reads clean on the re-read (one pause, two snapshots); one still unreadable refuses; one that exited drops out of
> the fresh set; a target that exited refuses; `ACCESS_DENIED` is never retried; a finding refuses at once and a finding
> the re-read sees refuses — and against the real source (`[live]`: a process created suspended and a pid with no process
> answer `kRetry`). The managed half — a refused re-scan of a game that has exited ends as its exit, never for a finding —
> is `CaptureSessionTests` and `SessionRecorderTests`.
## Native unit tests (Catch2)
- **Ring buffer:** SPSC correctness under a hammering writer thread; seqlock torn-read detection; wrap and overwrite-oldest semantics; power-of-two capacity assumptions. Include the **one-full-lap case**: a reader stalled exactly `capacity` records must not validate a different frame as unchanged (this is what the never-reset `seq` counter defends, `07_IPC` §Protocol rules).
- **Drop accounting:** the reader-side computation (`writeIndex - readIndex > capacity`) reports the right count and resumes at the right index. The writer has no drop counter to test — by design.
- **Torn records produce gap markers,** not silently shortened streams; a golden test asserts the gap does not appear as a stutter.
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all three header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`) — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all ~~three~~ four header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`, and `FlDisplayState` since layout 4, beta.10) — plus D33's `FlTolerance`, mirrored the same way *(corrected 2026-10-04)* — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
- **Fault policy:** injected SEH faults in a fake hook body → counter increments, original still called, self-disable at 3.
- **Hook index verification, by behaviour.** A vtable slot carries no identity, so "check that slot 8 *is* `Present`" is not a question the runtime can answer — the earlier wording here required something unimplementable. What is answerable: patch the slot, call the method, see whether the detour ran (`17_HOOK_ENGINE` §Getting vtable addresses; proved for slots 8, 13 and 22 in `spike-notes.md` §H4). Runs headless on CI via WARP and `CreateSwapChainForComposition`. A deliberate mismatch aborts installation instead of patching.
- **Every probe must be shown to fail.** A probe that ends in an unconditional assertion is green by construction and its ctest is decorative — `fl_proxy_swapchain` shipped in exactly that state. Before a probe counts as a regression net, break the thing it watches and watch it go red.
@@ -43,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:
@@ -61,6 +115,31 @@ 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.
- **Test readiness: an injection test waits for the harness to say it presents** (beta.27). The suites that start
hook-harness and then inject into it or look for it — `ShmDrainIntegrationTests`, `CaptureHostEndToEndTests`,
`AgentEndToEndTests`, `PartialRecoveryEndToEndTests` — slept 800 ms after starting it, a guess at when it presents.
They now wait, bounded at 30 s, for the line the harness prints and flushes right before its present loop
(`tests/Shared/HarnessReady.cs`, compiled in by `FrameLedger.DrainFixtures.targets`), and the pause case — which read
the writer's status as INIT once under a full gate on 2026-10-19 — waits for the writer's READY
(`WaitUntilInitFinishedAsync`) before it pauses.
- **The guard reads the test host too** (beta.27). The guard's scan set is the target and its ancestors up to a platform
launcher, so for an injection test it includes the test host that started the harness, `dotnet test` and the shell
above them. Under a full gate the test host is still starting its other test classes, and a module it releases
between the guard's list and the module's name refuses as `ModuleScanFailed` — measured 2026-10-20, once in the gate
and once in twelve runs of `FrameLedger.Infrastructure.Tests` with coverage, never in a run of the class alone;
`ProcessUnreadable` (2026-10-19, twice) is the same race met at the list. `ShmDrainIntegrationTests.InjectAsync` asks
again, four times at most, on those two reasons only. The end-to-end suites inject through the Agent or the capture
host, which records such a session as Tier 2; they have the same exposure and have not shown it.
- 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)
@@ -130,8 +209,14 @@ 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) |
| Accessibility *(added 2026-11-09, beta.35, D88)* | **keyboard only** with the mouse disconnected — every page, menu and dialog, Ctrl+1…5, Esc · **Narrator** — names, values, headings, the notices as they appear · a **contrast theme** on and off (Aquatic, Desert) · Windows **animation effects** off · a large **display scale**. The owner's first pass: 2026-11-09, keyboard only and Narrator on 0.1.0-beta.34 and 0.1.0-alpha.3, no fault (`ACCESSIBILITY.md` §How it is checked; the automated half is `08_UI` §Accessibility) |
| 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
Clean-VM install → Legal Gate → Agent setup (unelevated) → add a game → consent dialog → hooked 2-min session → charts render → CSV opens in Excel → Vulkan layer registered/unregistered cleanly → uninstall removes layer registration, task, and asks about data.
*(Added 2026-11-09, beta.35, D88:)* and an **accessibility smoke**, the same build: the Legal Gate, the consent dialog and
the session summary reached and answered with the keyboard alone; Narrator reads the notice a refused game raises; the
window readable under one contrast theme. The release's owner-only item in `HANDOFF` lists what that release moved.
+19 -11
View File
@@ -151,7 +151,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> the hard gate, against NFR-10 — but the evidence changed, and the consequence is
> live: the drain tests are skipped in CI until it is fixed.
0. **The guard.** Module + driver enumeration, blocklist matching, fail-closed behaviour on every error path. **Moved from item 8**: items 1 and 6 below inject into real games, and CLAUDE.md rule 2 plus P1's own "it ships before the first real injection, not after" both forbid that ordering. **◐ Every documented check now has a call site; one half of one check does not.** `EvaluateImpl` runs checks 1, 2, 2b, 3 (executable half) and 4 — five, not four, because 2b (`services`) is the only tier ever measured firing on real anti-cheat and every count that says "four" omits it. The guard is built (`FrameLedger.Injector`, native per §S13(a)), owns the chokepoint, and its fail-closed matrix is Catch2-driven. The injection primitive landed after it, in that order. Reached from managed code through one P/Invoke facade — never a second matcher (§S15). Evidence: `spike-notes.md` §1; §S7, §S8, §S16 closed.
0. **The guard.** Module + driver enumeration, blocklist matching, fail-closed behaviour on every error path. **Moved from item 8**: items 1 and 6 below inject into real games, and CLAUDE.md rule 2 plus P1's own "it ships before the first real injection, not after" both forbid that ordering. ~~**◐ Every documented check now has a call site; one half of one check does not.**~~ **Every documented check has a call site since 2026-09-25 (§S14) — corrected 2026-10-04.** `EvaluateImpl` runs checks 1, 2, 2b, 3 (executable half) and 4 — five, not four, because 2b (`services`) is the only tier ever measured firing on real anti-cheat and every count that says "four" omits it. The guard is built (`FrameLedger.Injector`, native per §S13(a)), owns the chokepoint, and its fail-closed matrix is Catch2-driven. The injection primitive landed after it, in that order. Reached from managed code through one P/Invoke facade — never a second matcher (§S15). Evidence: `spike-notes.md` §1; §S7, §S8, §S16 closed.
> **This line said ✅ DONE, and it was wrong in a way worth recording.**
> `19_SAFETY` specifies four pre-injection checks. **Check 4** (the static
@@ -174,6 +174,12 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> > deleted: it is the third place that had to be corrected for one PR, and the
> > count is the point.
> >
> > *(Corrected 2026-10-04: the paragraphs below were overtaken on 2026-09-25 — both halves of check 3 are wired
> > and seeded. `CheckBlockedStoreId` reads Steam's `appmanifest_*.acf` and GOG's `goggame-*.info` through a
> > guard-owned seam; an install no store names is not refused, unreadable store metadata is; Epic has no reader.
> > Rules 2026.10.1 list 33 executables and 33 Steam ids, floored. The owner question about a permanently
> > uncallable sub-check is moot.)*
> >
> > **This item stays ◐, on a different and narrower reason.** Check 3's
> > **store-id half** has no call site and cannot be given one: nothing produces
> > a `store_id` — the platform metadata extractors are unbuilt, which is the
@@ -186,7 +192,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> > uncallable is an owner decision, not a coding one. And unchanged either way:
> > `blockedExecutables` **ships empty**, so check 3 refuses nothing today. What
> > #52 changed is that populating it would now do something.
1. **Vulkan layer passthrough.** Minimal implicit layer registered under `HKCU`, with the opt-in checks that keep it passthrough for non-enabled processes. **Moved from item 7**: a passthrough bug loads FrameLedger into every Vulkan process on the machine, which is the highest blast radius in the spike. **◐ Gates done, interception not started.** `enable_environment` measured against loader 1.4.357, blast radius verified, in-layer blocklist self-scan built and proven both directions. `vkQueuePresentKHR` is **not** hooked — that is P1, and §S2's in-layer supervision check lands with it.
1. **Vulkan layer passthrough.** Minimal implicit layer registered under `HKCU`, with the opt-in checks that keep it passthrough for non-enabled processes. **Moved from item 7**: a passthrough bug loads FrameLedger into every Vulkan process on the machine, which is the highest blast radius in the spike. **◐ Gates done, ~~interception not started~~.** `enable_environment` measured against loader 1.4.357, blast radius verified, in-layer blocklist self-scan built and proven both directions. ~~`vkQueuePresentKHR` is **not** hooked — that is P1, and §S2's in-layer supervision check lands with it.~~ *(Corrected 2026-10-04: landed 2026-09-06, P1 item 3 — present and swapchain interception plus §S2's in-layer supervision, ctests `fl_vklayer_real` and `fl_vklayer_supervision`. The ray-tracing and pipeline entries are still unbuilt.)*
2. **Hook viability.** `hook-harness` (D3D11 + D3D12) + MinHook: dummy-device vtable probe, verify present indices at runtime, install/uninstall cleanly, measure per-present cost. Confirm `/MT` DLL loads into a real (offline, non-AC) game without incident. **✅ DONE.** Vtable indices proved by behaviour (§H4), unhook proved not to clobber a later hooker (§H7), per-present cost measured at 8.4 ns against a 1,000 ns budget — and **the `/MT` DLL is now loaded into a real title**: Lies of P, attach mode, guard passing, module verified present by re-enumeration, game still rendering afterwards (`spike-notes.md` §7).
> **Attach mode only when this ran.** Launch mode was blocked by §S18 — the
@@ -224,7 +230,9 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> (Steam `.acf`, GOG `.info`, Epic `.item`) — every platform rule is
> `sibling_glob`/`path_contains`, so identification is unaffected but
> **`store_id` is null for every title**. No SQLite, so nothing is persisted
> and `field_provenance` is decided-but-unimplemented (P2). The engine and
> and `field_provenance` is decided-but-unimplemented (P2). *(Overtaken — corrected 2026-10-04: the store import
> writes `store_id` since P4 PR-4, the guard reads the stores' metadata for check 3 since 2026-09-25, and
> `field_provenance` is written since 2026-09-14.)* The engine and
> platform fixture families are **P4 library metadata shipped early** under
> P0's name.
>
@@ -264,7 +272,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
8. **Telemetry layering.** Fill the `18_GPU_VENDOR_APIS` capability matrix on real hardware:
- L1 baseline (DXGI + PDH counters) working vendor-neutrally; decide whether the `D3DKMT` perf-data probe is stable enough on Win 10 **and** Win 11 to keep. **🅓 Deferred to Win 11 only, 2026-08-05** — one machine, and it is Win 11. Win 10 22H2 stays a supported floor and is explicitly unmeasured; the deferral holds only for as long as the probe stays non-load-bearing, which `18_GPU_VENDOR_APIS` §L1 now states as the condition rather than as advice.
- L2: which fields LibreHardwareMonitor actually returns per vendor, and **whether GPU sensors work unelevated without PawnIO** — this decides whether the default unelevated Agent has temperatures. **◐ NVIDIA measured 2026-09-03: yes (§M5 row R1), eight fields unelevated, `LhmTelemetrySource` written.** AMD / Intel remain 🅓 (§R5/§R6).
- L3: NVAPI linked from vendored MIT headers; Reflex latency, throttle reasons, per-domain utilisation.
- L3: NVAPI linked from vendored MIT headers; Reflex latency, throttle reasons, per-domain utilisation. *(Status added 2026-10-04: built 2026-09-10, P2 PR-E2, as `FrameLedger.NvapiBridge.dll` — throttle reasons and utilisation; Reflex latency has no producer.)*
- ~~**Licence confirmations:** LHM free of MPL-2.0 Exhibit B; NVAPI SPDX blocks intact~~ — **done before P0 began, both clear** (`spike-notes.md` §0). `tools/license-check` is in place and proven to fail on a planted violation.
*(The former items 7 "Vulkan layer" and 8 "Guard prototype" are now items 1 and 0. §R1/§R2 are folded in, not pending.)*
@@ -298,7 +306,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> `logs\overlay-<pid>-*.log` (init / Agent request / stop), `opengl32!wglSwapBuffers` with the harness's
> `--opengl` mode. **D3D9 is not built and will not be**: `20_OPEN_QUESTIONS` §Scope decisions rules it out
> of v1 (the Overlay is x64-only and those titles are 32-bit); listing it here was the roadmap's, not the
> scope's. What P1 still leaves ⏳ in `17_HOOK_ENGINE` §Hook inventory: `SetFullscreenState`,
> scope's. What P1 still leaves ⏳ in `17_HOOK_ENGINE` §Hook inventory: ~~`SetFullscreenState`~~ (polled instead, 2026-09-27),
> `SetColorSpace1`, `CreateSwapChain*`, `ID3D12Device5::CreateStateObject`, the Vulkan RT / pipeline entries,
> §Pipeline and §Memory/latency — feature rows, each with its own measurement question, not P1's core. P2
> (the Agent, the recorder, SQLite) is next per this file.
@@ -311,16 +319,16 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> re-scan wired to a real Overlay.
## P2 — Capture pipeline (1 week)
Agent: watcher, tier selection, injection orchestration, shm drain, telemetry poller (NVAPI first), session recorder, segments, `.partial` recovery, ~~Tier-2 `EtwFrameSource` retained as fallback.~~ **There is nothing to retain: Tier 2 has no mechanism as of 2026-08-27** (§G). `EtwFrameSource` is a port with no adapter, and P2 should not be planned as though writing one were scoped. SQLite v2 schema + migrations. Domain metric calculators + golden tests. **Milestone: first real hooked session persisted with measured upscaler/RT data.** *Technical half reached 2026-09-10 (P2 PR-F): the shipped `FrameLedger.Agent.exe --console capture` against `hook-harness` ends as one hooked `sessions` row, in the merge gate (`AgentEndToEndTests`). **P2's code is complete as of PR-G (2026-09-10)** — kill-and-recover is in the gate too (`PartialRecoveryEndToEndTests`) and `tools/fps-impact-runbook.ps1` exists. What P2 still owes is two MEASUREMENTS, not code: the real-title milestone read against the game's own menus, and the ≤ 0.5 % FPS-impact run. Both are the owner's; `spike-notes` §14 holds their slots and the exact commands.*
Agent: watcher, tier selection, injection orchestration, shm drain, telemetry poller (NVAPI first), session recorder, segments, `.partial` recovery, ~~Tier-2 `EtwFrameSource` retained as fallback.~~ **There is nothing to retain: Tier 2 has no mechanism as of 2026-08-27** (§G). `EtwFrameSource` is a port with no adapter, and P2 should not be planned as though writing one were scoped. SQLite v2 schema + migrations. Domain metric calculators + golden tests. **Milestone: first real hooked session persisted with measured upscaler/RT data.** *Technical half reached 2026-09-10 (P2 PR-F): the shipped `FrameLedger.Agent.exe --console capture` against `hook-harness` ends as one hooked `sessions` row, in the merge gate (`AgentEndToEndTests`). **P2's code is complete as of PR-G (2026-09-10)** — kill-and-recover is in the gate too (`PartialRecoveryEndToEndTests`) and `tools/fps-impact-runbook.ps1` exists. What P2 still owes is two MEASUREMENTS, not code: the real-title milestone read against the game's own menus, and the ≤ 0.5 % FPS-impact run. Both are the owner's; `spike-notes` §14 holds their slots and the exact commands. **The milestone's row half exists as of 2026-09-16** — the shipped Agent's Lies of P session with `fsr3`, 1506×848 → 2560×1440, FG ×2.04 and `rt = no` (`spike-notes` §14.1); the menu column is still the owner's, as is the FPS-impact run.*
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; the owner's merges of the stack are the remaining act)**
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). *Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; ~~the owner's merges of the stack are the remaining act~~ merged 2026-09-13/14, #152–#165)**
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). ~~*Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*~~ *(Struck 2026-10-04: false since PR-2 — the App shell, the en/vi/ja `.resx`, `Shared/Ipc`.)*
## P4 — Detection & product polish (1 week)
~~Static rules engine + `detection-rules.json` (engines, platforms, capabilities, **anticheat blocklist**) + validator + fixtures~~ **landed 2026-09-14 (P4 PR-1: the engine existed since P0; the Agent's `DetectionSweep` is its first caller, `ApplyDetectionAsync` its first writer — HANDOFF §P4)**; ~~store auto-import~~ **landed 2026-09-14 (P4 PR-4)**; ~~capability-vs-measured UI separation~~ **(PR-1: the Supports row reads the sweep's flags)**; ~~i18n en/vi/ja; Legal Gate;~~ ~~Velopack + updater (with the hooked-session deferral)~~ **landed 2026-09-14 (P4 PR-5 — the deferral is `UpdateService`'s shape, not a flag)**; ~~bug bundle incl. overlay logs~~ **landed (overlay logs since P3 PR-8a; 2026-09-15, P4 PR-9: the crash dialog, the minidump in both processes and the dump as the bundle's opt-in — `10_LOGGING` built notes)**; ~~tray + toasts; Settings;~~ ~~DB maintenance~~ **landed 2026-09-15 (P4 PR-7: the sweep is the Agent's over `SweepRetention`; integrity, backup and compaction in the App)**; ~~accessibility pass~~ **landed 2026-09-15 (P4 PR-8: `08_UI` §Accessibility written first — Ctrl+1…5, Esc on every dialog, an automation name on every textless input, theme colours only — each held by `AccessibilityTests`)**; ~~the scheduled task (`--install-task`)~~ (P3 PR-8b) and ~~the Velopack install hooks~~ **(PR-5: the uninstall hook; install registers nothing, by design — `12_BUILD` §The Vulkan layer is not registered at install time)**. *(The struck items moved to P3 on 2026-09-13 — see §P3.)*
## P5 — Ship (3–4 days)
CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 — untested by a tag yet); 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`.
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.
@@ -336,10 +344,10 @@ CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 —
- ~~PresentMon Service + API2 for a richer Tier 2~~ — **struck 2026-08-27**, and the shape hardened 2026-08-28: v1's ladder has two rungs and Tier 2 is not a measurement. What v2 may want is **a no-injection measurement at all** — which would restore two things at once: the FG oracle §S31 spent four attempts looking for, and `14_TESTING`'s Tier-1 accuracy cross-check, which is struck for the same reason (§G)
- **YouTube overlay export**: frametime/FPS graph as transparent PNG sequence for DaVinci Resolve benchmark videos (SkullMute workflow)
- CapFrameX-compatible CSV import/export
- Microsoft Store / Game Pass titles (packaged-app injection constraints)
- ~~Microsoft Store / Game Pass titles (packaged-app injection constraints)~~ *(struck 2026-11-03: GDK titles from the Xbox app and the Microsoft Store are imported, played and measured since beta.33, D77–D82, `spike-notes` §25; UWP apps stay out, refused with a reason of their own)*
- AFK segmentation via `GetLastInputInfo`
- GPU frame time via timestamp queries (needs care: injecting queries into the game's command lists is more invasive than anything in v1 — needs its own risk review)
- Beta update channel; ARM64
- ~~Beta update channel;~~ ARM64 *(struck 2026-10-04: the beta channel shipped with P4 PR-5 — `update.channel`, Settings ▸ Updates; `13_CI_CD` §Branch & release policy)*
## Permanently out of scope
+209 -11
View File
@@ -6,8 +6,8 @@ Mandatory conventions for all XAML/C# in `FrameLedger.App`. WPF UI = lepoco's Fl
| Package (NuGet id) | Pin | Notes |
|---|---|---|
| `WPF-UI` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net10.0-windows10.0.19041.0` TFM (`12_BUILD` §Managed build) |
| `WPF-UI.Abstractions` | transitive | Navigation abstractions (`INavigationViewPageProvider`) |
| `WPF-UI` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net10.0-windows10.0.22621.0` TFM (`12_BUILD` §Managed build; this row said `19041` until 2026-09-21, which is no TFM this repository ever built — `Directory.Build.props` has been `22621` with a 19045 floor throughout) |
| `WPF-UI.Abstractions` | ~~transitive~~ **= 4.3.0**, referenced directly (corrected 2026-10-04) | Navigation abstractions (`INavigationViewPageProvider`) |
| `WPF-UI.DependencyInjection` | match `WPF-UI` | DI glue (`services.AddNavigationViewPageProvider()`); verify exact id/version at scaffold |
| `WPF-UI.Tray` | **not used** | Tray stays on H.NotifyIcon.Wpf (CLAUDE.md stack table) |
@@ -62,6 +62,7 @@ private static readonly IHost _host = Host.CreateDefaultBuilder()
Theme rules:
- Manual Light/Dark: `ApplicationThemeManager.Apply(ApplicationTheme.Dark)`.
- System: `SystemThemeWatcher.Watch(mainWindow)` — call it in the window's `Loaded` handler (needs an HWND), and unwatch when switching to manual.
- A Windows contrast theme (beta.35, D91): wins over all three while it is on, and is never left to the watcher, which would apply WPF UI's own high-contrast files (§Gotchas). `Services/ThemePlan.For` is the table, `Services/WpfThemeApplier` applies it.
- Persist the choice in `settings`; re-apply before the main window shows to avoid a flash. **Measured 2026-09-13: this is a correctness rule, not a cosmetic one** — `ApplicationThemeManager.Apply(theme, backdrop, updateAccent: true)` is what registers the `SystemAccentColor*` resources the control templates `StaticResource` at first Measure; a `FluentWindow` shown before any `Apply` throws `XamlParseException: Cannot find resource named 'SystemAccentColorPrimary'`. The shell applies the theme in its constructor before `InitializeComponent()` and again from `Loaded` for the watcher.
- Subscribe `ApplicationThemeManager.Changed` once, centrally, to re-theme ScottPlot (below).
@@ -81,7 +82,7 @@ Theme rules:
<RowDefinition Height="*"/> <!-- NavigationView -->
</Grid.RowDefinitions>
<ui:TitleBar Grid.Row="0" Title="FrameLedger" Icon="pack://application:,,,/Assets/icon.ico" />
<ui:TitleBar Grid.Row="0" Title="FrameLedger" /> <!-- no Icon: no icon file exists yet (corrected 2026-10-04) -->
<Menu Grid.Row="1"> <!-- classic menu, Fluent-restyled automatically --> </Menu>
@@ -103,7 +104,7 @@ Theme rules:
</ui:NavigationView>
<ui:SnackbarPresenter x:Name="SnackbarPresenter" Grid.Row="2" VerticalAlignment="Bottom" />
<ContentPresenter x:Name="DialogHost" Grid.Row="2" /> <!-- ContentDialogService host -->
<ui:ContentDialogHost x:Name="DialogHost" Grid.Row="2" /> <!-- §Dialogs; a ContentPresenter stood here until 2026-10-04 -->
</Grid>
</ui:FluentWindow>
```
@@ -115,13 +116,21 @@ Code-behind wires services once: `navigationService.SetNavigationControl(RootNav
- Navigate **only** via `INavigationService.Navigate(typeof(SomePage))` — never manipulate `Frame` directly, never `new` a Page.
- Pages implement `INavigableView<TViewModel>` with `ViewModel` injected via constructor DI; `DataContext = this` in the page constructor (WPF UI template idiom) so bindings read `ViewModel.*`.
- Page state: pages are Transient; anything that must survive navigation lives in the ViewModel-backing services/DB, not the Page.
**Except the library, since beta.34** (owner request 2026-11-06, "Games stalls 0.5–1.5 s"; `spike-notes` §27): the window
keeps the `GamesPage` it built — `Services.WindowPageCache`, the window's own `INavigationViewPageProvider`, set after
`INavigationService.SetNavigationControl` (which hands the NavigationView the container's provider) — and its view model
reads the library again each time the page is shown (`GamesViewModel.Attach`). Still Transient in the container; one
instance per window, so a language change's new window builds its own in the new language. **Not**
`NavigationViewItem.NavigationCacheMode`: WPF UI 4.3.0 reads it only when the NavigationView has neither a service
provider nor a page provider (`NavigationView.Navigation.cs`, `GetNavigationItemInstance`), and this App sets one — the
attribute would have changed nothing.
## Control mapping (always prefer these)
| 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 +141,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,9 +152,58 @@ 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
fill)~~ **`Secondary` is refused too since 2026-09-21**: its trigger repaints the background only and keeps the default
badge's on-accent `BadgeForeground`, near-white on near-white in the light theme. Use the `TagPill` + `TagPillText`
styles (`Styles/FrameLedger.xaml`), or the `Pill` style with a `SystemFillColor*BackgroundBrush` and an explicit text
brush; `ContrastTests` refuses all five (`08_UI` §Contrast).
- Do **not** set `Background` on `FluentWindow` (kills Mica). Page backgrounds transparent by default.
- Exception to the no-hex rule: the chart palette — defined once per theme in `Styles/ChartPalette.xaml` (two dictionaries), never inline.
- **Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`** (2026-10-07): the navigation's
Frame passes no text colour into a page, and a text with none is black (§Gotchas).
- Exception to the no-hex rule: the chart palette — defined once per theme in ~~`Styles/ChartPalette.xaml` (two dictionaries)~~ `Styles/ChartPalette.Dark.xaml` and `ChartPalette.Light.xaml` (corrected 2026-10-04), never inline.
- 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.
- The change markers (beta.30, D70) take the palette's `Chart_StutterPso` under `ChartTheme.TextOn` — black or white by
WCAG contrast, black in both themes. The chart reads `ChartTheme.Current` at every render; the WPF chip in the list
(`Controls/ChangeBadge`) follows a switch through the same resource reference as `ArtTint` and `FgMixBar`
(`ChartPalette.ForBackground`). No colour in XAML.
- Third exception (beta.35, D91): **a Windows contrast theme's colours**, read from `SystemColors` in one place
(`Services/ContrastPalette.FromSystem`) and laid over the theme by `Services/ContrastOverlay` — never written in XAML. A
colour the App works out itself reads `Services.ContrastTheme.Active` first (the charts, the badges, the artwork band);
XAML that must change with it binds `{Binding Path=(services:ContrastTheme.IsOn)}`, a static property WPF hears through
its `StaticPropertyChanged` event.
- **`ui:Button Appearance="Danger"` / `Info` / `Success` / `Caution` / `Dark` / `Light` paint fixed colours** — values in
WPF UI 4.3.0's button style (`#F44336` for Danger), not resources, so no theme and no contrast theme reaches them, under
the theme's button text (white on the red in the dark theme, 3.68:1). Danger is the one the App uses: its implicit
`ui:Button` style (`Styles/FrameLedger.xaml`) puts the theme's dark text on the red, and the theme's own button under a
contrast theme — message boxes' buttons included. The other five are refused
(`ContrastThemeTests.NoButtonOrBadgeTakesAnAppearanceThatPaintsAFixedColour`).
- **A snackbar's appearances are fixed colours too** (`ISnackbarService.Show`): Success, Caution, Info, Danger, Primary,
Dark and Light are values under white or black text — Success 2.78:1, Caution 2.16:1 in both themes. Only Secondary is
the theme's: `Services/SnackbarStrip`, the one place a snackbar is shown, uses it for every message.
- **A `ui:Badge` with a BOUND palette appearance** is the same hole as a literal one, and no XAML scan of literals sees it
(the agent's pill, beta.35: `AgentPill` now). A bound badge appearance is refused by the same test.
## FlowDocument (rendered documents, beta.12)
- **WPF UI 4.3.0 styles no `FlowDocument`.** Its own defaults are black Georgia on white, so a document in the dark theme
is unreadable unless the document is themed in code: `Markdown/MarkdownRenderer` sets `TextElement.Foreground` to
`TextFillColorPrimaryBrush` and `TextElement.FontFamily` to `ContentControlThemeFontFamily` **by resource reference**
(`SetResourceReference`, the code form of `DynamicResource`), a transparent background, and resource references for
every other colour (`AccentTextFillColorPrimaryBrush` links, `SubtleFillColorSecondaryBrush` code and table headers,
`ControlStrokeColorDefaultBrush` rules, quote bars and table borders). Never a literal brush.
- Host it in `Controls/MarkdownView` (a `FlowDocumentScrollViewer`, toolbar hidden) — not a `RichTextBox`, which is an
editor. A `Hyperlink` there does not navigate by itself: the view handles `RequestNavigate` and decides
(`Markdown/MarkdownLinks`).
- `AccentTextFillColorPrimaryBrush` is the light accent in the dark theme only after `ApplicationThemeManager.Apply(…,
updateAccent: true)` — measured 2026-10-03 in the test host, which skips it: links drew #003E92 on #202020 there and
#73C2FF once the accent was applied as `WpfThemeApplier` applies it.
## Custom controls (`FpsReadout`, `TriStateChip`, sparklines)
@@ -153,6 +211,9 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `
- `TriStateChip`: `Border` CornerRadius 12, states — Yes: `AccentFillColorDefaultBrush` bg + on-accent text; No: transparent bg + `ControlStrokeColorDefaultBrush` 1px border; N/A: dashed `StrokeDashArray="2 2"` border + `TextFillColorTertiaryBrush` text.
- **Built 2026-09-14 (P3 PR-5):** both derive from `Control` with one dependency property, `Model` (`FpsReadoutModel` / `TriStateChipModel`, decided by `Services.FpsPresentation` and the view models — the control renders, it never decides), templates in `Styles/FrameLedger.xaml` with `DataTrigger`s on the model's flags; the dashed N/A outline is a `Rectangle` behind the `Border` (a `Border` cannot dash). The source suffix icon became the tooltip: the Fluent System Icons names for 🔍/✎/↧ are not certain in this pinned version and a wrong `SymbolRegular` is a build error. The override flyout is PR-6's.
- No `SystemColors.*` anywhere.
- `ChangeBadge` (beta.30): a `Control` with one `Text` property, not focusable (the row's text carries the meaning), its
template a `Border` and a `TextBlock` bound to `Background`/`Foreground`, which the control sets in code from the chart
palette (`Styles/FrameLedger.xaml` writes no colour).
## Dialogs & notifications
@@ -169,9 +230,14 @@ var box = new Wpf.Ui.Controls.MessageBox
var result = await box.ShowDialogAsync(); // Wpf.Ui.Controls.MessageBoxResult.Primary
```
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` and ban the System one (BannedSymbols/analyzer note).
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` ~~and ban the System one (BannedSymbols/analyzer note)~~ *(corrected 2026-10-04: nothing bans it. Three paths use the Win32 box on purpose — the crash dialog, the startup-failure dialog and the uninstall question — because they run when the shell's dialog host cannot be trusted. Use the WPF UI one everywhere else.)*
- Rich in-flow dialogs: `IContentDialogService` (host wired in MainWindow — a `ui:ContentDialogHost`, since 4.3.0 marks `SetDialogHost(ContentPresenter)` obsolete).
- Transient in-app: `ISnackbarService.Show(title, message, ControlAppearance.Success, new SymbolIcon(SymbolRegular.Checkmark24), TimeSpan.FromSeconds(4))`.
- Transient in-app: ~~`ISnackbarService.Show(title, message, ControlAppearance.Success, new SymbolIcon(SymbolRegular.Checkmark24), TimeSpan.FromSeconds(4))`~~
`IMessageStrip` (`Info` / `Success` / `Warn`) — `Services/SnackbarStrip` is the one caller of `ISnackbarService.Show`, and
says each message to a screen reader (beta.35, D89). A view model never holds `ISnackbarService`.
- A change a screen reader must hear goes through `IAnnouncer` (`Services/UiaAnnouncer`, UI Automation's notification
event). **`AutomationProperties.LiveSetting` alone says nothing in WPF**: the app must raise `LiveRegionChanged` itself,
and no XAML of the App's sets one (beta.35).
- System/tray notifications: H.NotifyIcon only (08_UI §Notifications policy).
## ScottPlot theme sync
@@ -187,10 +253,43 @@ On startup and on `ApplicationThemeManager.Changed`: for every live plot set fig
> Pinned `ScottPlot.WPF` 5.1.59: `Add.SignalXY` for the decimated series, `Add.Scatter` (no line) for markers,
> `Add.HorizontalSpan` for the ribbon, `Add.Bars` over `Statistics.Histogram.WithBinCount`, `Add.ScatterLine`
> for the percentile curve, a series' `Axes.YAxis = plot.Axes.Right` for the sensor overlay.
>
> **Accessible charts, beta.35 (D90).** Every plot in XAML is `charts:ChartPlot` (a `WpfPlot` subclass; ScottPlot's
> default style and input stay) with `AutomationProperties.Name` and `HelpText` from `A11y_Chart_*` / `A11y_ChartData_*`.
> `ChartTheme.Attach` adds `Charts/ChartKeys` (arrows and A marked handled after ScottPlot's class handler has acted — an
> instance handler runs after it) and `ResetOnDoubleClick` (`DoubleLeftClickBenchmark(false)` and a `DoubleClickResponse` on
> the left button that autoscales). A series takes `ChartPatterns.Line` / `Points` / `Hatch` by its index — a new series
> without one is red in `NoChartTellsTwoSeriesApartByColourAlone`. Under a Windows contrast theme `ChartTheme.Current` is
> `ChartPalette.ForContrast(ContrastTheme.Active)` — the theme's window under every plot, its text, link, highlight,
> button text and disabled text for the rest — and the patterns carry the series apart (D91).
>
> **The trend's change markers, beta.30 (D70):** `Charts/ChangeMarkerPlottable`, an `IPlottable` + `IRenderLast` added
> with `Add.Plottable` (which assigns no axes: the chart sets `Axes.XAxis`/`YAxis` itself), draws the dashed lines in
> `Render` — clipped to the data area — and the numbered badges in `RenderLast`, after the panels and unclipped, in a
> band kept with `plot.Axes.Top.MinimumSize` (the top axis is unused and measures 15 px; `MinimumSize` clamps it up, and
> `Clear` keeps it, so `Show` sets it every time — 0 with no marker). `LabelStyle.Measure` sizes a badge with a
> `Paint.NewDisposablePaint()`; `Charts/ChangeBadgeLayout` places them. `GetAxisLimits` returns
> `AxisLimits.HorizontalOnly`, so the markers count toward the date axis's autoscale as `VerticalLine`s did.
## Gotchas checklist
- [ ] Dictionaries order: `ThemesDictionary` → `ControlsDictionary` → app styles. Wrong order = default-looking controls.
- [ ] **A ScottPlot `VerticalLine` label grows into a panel nothing sizes for it (5.1.59).** With `LabelOppositeAxis` it is
anchored 5 px above the data area, its box (text + 5 px padding each side) growing up into the top-axis panel, which
an unused axis measures at 15 px; clipping is off, so the control's edge cut it — the owner's "Driver GPU: … → …",
beta.30. `LabelAlignment` is overwritten each frame (only `ManualLabelAlignment` holds), and
`LabelStyle.LastRenderPixelRect` includes the 3 px default `ShadowOffset` even with no shadow. The trend draws its
own badges now (§ScottPlot theme sync).
- [ ] **`WpfPlot.DisplayScale` is read once, in the constructor**, from `VisualTreeHelper.GetDpi` before the control has
a window. Read a pointer with `GetPlotPixelPosition(e)` (the element's DPI now); ScottPlot's pixels are device
pixels while no `Plot.ScaleFactor` is set, and none is.
- [ ] **WPF UI 4.3.0's high-contrast theme cannot be applied as it is** (beta.35, D91). `ApplicationTheme.HighContrast` has
no dictionary (the watcher picks HC1/HC2/HCBlack/HCWhite by Windows' theme name); each of those holds 84 `#FFFF0000`
placeholders among 97 colours and 17 brushes (`SystemFillColor*Brush`, `MenuBar*`) that throw when the file is read
alone — inside the App their forward references fall back to the application's resources and read as the Fluent
theme's fills; their colours are Windows 11's defaults, not the user's; their text on the accent is the window text.
Never let `SystemThemeWatcher` watch while a contrast theme is on: it would apply them. The App reads them for each
key's role only (§Theming & brushes; `08_UI` §Contrast).
- [ ] `SystemThemeWatcher.Watch` after HWND exists (`Loaded`), not in the constructor — but `ApplicationThemeManager.Apply(…, updateAccent: true)` BEFORE the first window's XAML loads, or the accent resources are missing at first Measure (§App bootstrap).
- [ ] Menu row lives **outside** `ui:TitleBar` (its area is the drag region; a Menu inside becomes undraggable/unclickable territory).
- [ ] Don't set `AllowsTransparency`/`WindowStyle` on `FluentWindow` — it manages its own chrome.
@@ -205,9 +304,108 @@ 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.
- [ ] **What a screen reader is given is the UI Automation tree, and WPF builds it with four holes** (beta.35, D88;
`PagesLoadTests.Automation` sweeps every surface for each). (1) **A control with no automation peer** — a plain `Control`
or `ContentControl`, WPF UI's `Image`, `Card`, `Badge`, `InfoBar` (measured on .NET 10.0.14) — is skipped by the tree; if
it is also focusable (a `Control` is, by default) it is a Tab stop Narrator says nothing about. Give a display-only
control a peer (`Controls/SpokenTextAutomationPeer`) and take it out of the tab order; `ui:CardControl` has a peer with an
empty name even with a string `Header` — the App's implicit style takes it out of the tab order. (2) **A list's,
drop-down's or grid row's item is named by its `ToString()`**: a record's is its printed form (`Choice { Value = dark,
Label = Dark }`), a class's its full type name. Every item type overrides it (`Services/SpokenText` builds the words).
(3) **A `TextBlock` written straight into a `ControlTemplate` is no control element** (`TextBlockAutomationPeer`: not when
its templated parent is something other than a `ContentPresenter`): draw a template's text through a `ContentPresenter`
(the App's InfoBar template), or give the control a peer that says it. (4) **A `DataGridTemplateColumn`'s cell has no text
of its own**, so WPF names it `Item: <row>, Column Display Index: n`: name it with `controls:CellName.Path` (a cell style
based on `DefaultDataGridCellStyle`, the one WPF UI's grid gives every cell). Also: a plain `ItemsControl` is focusable
(the App's implicit style says no), and WPF UI's `CardExpander` leaves its expand button (`ExpanderToggleButton`)
unnamed (`Controls/ExpanderToggleName`, set by the App's implicit CardExpander style).
- [ ] **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).
*(Corrected 2026-10-26, beta.30: the CODE handles no key, but `ContentDialog.xaml` does route them — each template
button's `IsDefault` follows `DefaultButton`, Close is `IsCancel`, and while the primary is disabled a trigger makes
Close the default. Enter therefore clicks the default button from a single-line text box: the consent dialog's
`DefaultButton = Close` declined a typed phrase on Enter (the owner's report; D69 made the primary the default and the
content keeps Enter until the phrase matches). Esc through `IsCancel` is read from the template, not measured —
`DialogKeyboard` handles it first.)*
- [ ] **`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.
+70 -29
View File
@@ -22,7 +22,7 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
> ⚠ The CFG result was measured with **strict mode off**. A host that enables CFG strict mode does not auto-validate dynamically generated code and could still `__fastfail`. Rare, but real, and not something the fault policy can catch — see §Fault policy and `20_OPEN_QUESTIONS` §H8.
- No STL container that allocates in a hook path. `std::atomic` and fixed arrays are fine.
- VERSIONINFO populated (`ProductName=FrameLedger`, real company/version) — being identifiable is required by `19_SAFETY`.
- Exports: `FlGetBuildId()`, `FlRequestUnhook()`, `FlGetStatus()`. Real names, no ordinal-only tricks.
- Exports: `FlGetLayoutVersion()` (added to this line 2026-10-04), `FlGetBuildId()`, `FlRequestUnhook()`, `FlGetStatus()`. Real names, no ordinal-only tricks.
## DLL entry
@@ -57,6 +57,16 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
> them and the loader does not list them. Body under `FL_HOOK_GUARD`, no allocation, no lock, no
> logging (rule 5). Exercised by `hook-harness --load-after-ms N PATH` (up to four), against the real
> Overlay in a real target, both jobs.
>
> **D33 (2026-09-26): one family may be tolerated.** Before `InstallLoaderHook`, `InitThread` reads
> `Local\FrameLedger.Tolerate.<pid>` once (`fl_tolerance.h`; absent = nothing tolerated, the ordinary case),
> resolves each name against its OWN compiled floor, honours only a family whose whole footprint there is
> user-mode (`fl::guard::FamilyIsUserModeOnly`) and keeps a 64-bit mask over the floor's module families. The
> detour's only change is one bit test before (b): a tolerated family's module loading late is not an early stop.
> **Overhead:** one relaxed-acquire `uint64` load, a shift and a compare, on the floor-match branch alone — a branch
> that fires approximately never — and nothing on the present path; the tolerance is read on the init thread, not in
> a hook body (and logged there as `TOLERANCE`). ctest `fl_guard` `[D33]` loads a decoy `NEP2.dll` 2.5 s in: the
> Overlay keeps recording when the mapping names NetEase Yidun, and stops when it names Easy Anti-Cheat.
4. Install present hooks for what exists (below).
5. Install feature hooks (upscaler / RT / PSO) lazily — the first time their module appears.
6. Publish `status = ready` in the handshake block.
@@ -72,7 +82,7 @@ void** vtbl = *reinterpret_cast<void***>(dummySwapChain);
MH_CreateHook(vtbl[kPresentIndex], &Hook_Present, reinterpret_cast<void**>(&Orig_Present));
```
Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapChain1`, `ResizeBuffers = 13`) live in `HookIndices.h`.
Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapChain1`, `ResizeBuffers = 13`) live in ~~`HookIndices.h`~~ `FrameLedger.Overlay/include/fl_dxgi_vtable.h`, shared with the harness; the D3D12 command-list slots in `fl_d3d12_vtable.h` (corrected 2026-10-04: no `HookIndices.h` exists).
> ⚠ **"Verified at runtime against the dummy object" is not implementable, and
> must not be reintroduced.** A vtable slot holds a bare function pointer: no
@@ -102,15 +112,19 @@ Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapCha
> restore-only-if-unchanged rule matters, since another overlay may have
> patched the same shared slot after us.
Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards); use MinHook inline hooks for flat C exports (`wglSwapBuffers`, NGX/FFX/XeSS entry points).
~~Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards);~~ *(corrected 2026-10-04: the Overlay swaps no vtable entry. It reads the slot off a throwaway object and MinHooks the function it points at, so one patch covers every instance (§Ray tracing); §Compare-and-restore explains why the swap is not the cleaner uninstall.)* Use MinHook inline hooks for flat C exports too (`wglSwapBuffers`, the Streamline and FidelityFX entry points ~~, NGX/FFX/XeSS~~ — NGX and XeSS have none).
## Hook inventory
Every hook must be listed here with a purpose. Anything not on this list is not allowed to exist (`19_SAFETY` review checklist).
> **This table is a SPECIFICATION. As of 2026-09-04 the Overlay installs TWELVE DETOURS —
> **This table is a SPECIFICATION. ~~As of 2026-09-04 the Overlay installs TWELVE DETOURS —
> the eight of 2026-09-03 plus four `ffxDispatch` trampolines, one per AMD module a game
> calls — and the FidelityFX row below is the ninth ✅.** The counts differed until 2026-09-03, because a
> calls — and the FidelityFX row below is the ninth ✅.~~** *(Corrected 2026-10-04: as of 2026-09-06 it installs up
> to SIXTEEN — the nine `FL_HOOK_INVENTORY` rows (four Streamline including `slSetTagForFrame`, four `ffxDispatch`,
> `ffxFsr3ContextDispatchUpscale`), the three DXGI slots, the two `ID3D12GraphicsCommandList4` methods,
> `wglSwapBuffers` and `LoadLibraryExW`; four hooks landed without this banner moving.)* *(And since beta.25,
> 2026-10-19: up to TWENTY — four `ffxQuery` rows join them, on the same four AMD modules, D65.)* The counts differed until 2026-09-03, because a
> row is a *capability* and a detour is a *patch*, and the FG-count row rode on the
> evaluate detour; it has its own now, `sl.interposer.dll!slGetNewFrameToken`. The AMD row
> is the opposite shape — **one row-family, four modules, four patches from one
@@ -133,7 +147,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
> Reset is load-bearing — and no vendor symbol is resolved by name, so `FL_HOOK_INVENTORY`
> and `hookinventory-check` do not cover them at all.
> **Every other row below is unwritten**, including
> `SetFullscreenState`, `SetColorSpace1`, `CreateSwapChain*`, ~~`wglSwapBuffers`~~ (built 2026-09-06, #141, its row below),
> ~~`SetFullscreenState`~~ (polled instead since 2026-09-27, its row below), `SetColorSpace1`, `CreateSwapChain*`, ~~`wglSwapBuffers`~~ (built 2026-09-06, #141, its row below),
> `ID3D12Device5::CreateStateObject`, §Pipeline and §Memory/latency.
>
> Stated here because the distinction is invisible from the table. What a writer may then
@@ -151,12 +165,12 @@ Every hook must be listed here with a purpose. Anything not on this list is not
> so a shipped hook missing from here is invisible to every gate. Flip the row **and this
> banner** in the same PR that builds a hook.
### The one system-module detour — a hook, and the asymmetry stated
### ~~The one system-module detour~~ The two system exports patched by name — a hook, and the asymmetry stated *(heading corrected 2026-10-04: `wglSwapBuffers` above is the other)*
| Hook | Purpose |
|---|---|
| ✅ `opengl32.dll!wglSwapBuffers` (2026-09-06, P1 item 4) | The OpenGL present hook (§Presentation). A system module, not a vendor one, so — like the row below — it is deliberately **not** in `FL_HOOK_INVENTORY` and `hookinventory-check` does not cover it; listed here so the table above and these two rows together are the whole inventory |
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **It is the only hook on a system module, and it is deliberately not in `FL_HOOK_INVENTORY`:** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **~~It is the only hook on a system module, and~~ Like `wglSwapBuffers` above it, it is deliberately not in `FL_HOOK_INVENTORY` (corrected 2026-10-04):** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
### Watchdog observations — not hooks, and listed here so nobody mistakes them for one
@@ -169,7 +183,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|---|---|
| ✅ `IDXGISwapChain::Present`, `Present1` | Frame boundary, QPC, sync interval, present flags. **`DXGI_PRESENT_TEST` calls are dropped without a record** — the occlusion probe submits nothing, and a minimised game emits a stream of them (`07_IPC` §Protocol rules). **Since 2026-09-05 the hook also reads `IDXGISwapChain::GetLastPresentCount` on the chain it just saw** (rule 4: the same COM object `FindOrAdd` already calls `GetDesc` on, no new hook) and publishes `dxgiPresentSamples` / `dxgiPresentsUnseen` — DXGI's count of presents on that chain that this hook never saw, the in-process half of `20_OPEN_QUESTIONS` §H5 Leg 1. One virtual call per hooked present, costed by `hook-harness --probe-frames`. **And per record since the same night: `dxgiUnseen` @52 under `FL_MEASURED_DXGI_PRESENTS`**, so the consumer's window counts `Displayed = hooked + unseen` per bucket (`03_METRICS` §Displayed may be DXGI-COUNTED) — measured 2.90 / 2.95 on DL:TB at Streamline 2.8.0, 0 on 2.7.3 and 2.10.3. **And since 2026-09-06 (P1 item 2) the same read, at the FIRST hooked present on the first hooked chain, is published once as `FlWriterState.dxgiPresentsBeforeHook` @60** — DXGI's count of presents that ran before the hook was in, launch mode's cost meter (`20_OPEN_QUESTIONS` §S1); 0xFFFFFFFF until a present is seen, set before the present hooks go in. **Corrected 2026-09-14 (`fl_dxgi_count.h`, ctest `fl_dxgi_count`):** a reading that went *backwards* — a chain released and re-created at the same address inherits the slot's old count — used to wrap `now − previous` to ~4e9, saturate the record byte at 255 (the `DxgiSaturated` refusal) and add the wrap to the session total: the owner's ledger held `dxgi_unseen_total = 4294967243`. A regression is now a reset (no delta claimed, nothing added, the slot re-armed) and the total saturates at `UINT32_MAX` rather than wrapping. Cost: one compare on the same virtual call; measured per `14_TESTING` §Hook overhead in the PR |
| ✅ `IDXGISwapChain::ResizeBuffers` · ⏳ `ResizeTarget` | Output resolution changes mid-session. `ResizeBuffers` re-reads the swapchain description *after* the original returns; `ResizeTarget` is not hooked |
| ⏳ `IDXGISwapChain::SetFullscreenState` | Fullscreen ↔ borderless transitions |
| ~~⏳ `IDXGISwapChain::SetFullscreenState`~~ **not hooked — polled (2026-09-27, beta.10)** | ~~Fullscreen ↔ borderless transitions~~ **Region 4, `FlDisplayState` (`07_IPC`, layout 4).** DXGI leaves exclusive fullscreen by itself — focus lost, Alt+Enter inside its own window hook — without the title calling this method, so a hook would miss exactly the transitions a mode share must count. Instead the present hook asks, **at most every 500 ms per chain**, two getters on the chain the title passed: `GetFullscreenState(&fs, nullptr)` (no `IDXGIOutput` taken) and `GetDesc` (the window, the back buffer, the swap effect). Rule 4: the same object `FindOrAdd` already calls `GetDesc` on and the counter reads — no new hook, no read beyond it; the window's geometry and the classification are the Agent's, out of process. `GetDesc` again also refreshes the size every record carries, which closes `IDXGISwapChain3::ResizeBuffers1` (unhooked: a D3D12 title resizing through it kept its old size until now). Published through a seqlock the writer never waits on (a taken lock skips the sample). OpenGL publishes the window and client size `ReadGlSize` already holds, with no exclusive bits. Cost per `14_TESTING` §Hook overhead in the PR |
| ⏳ `IDXGISwapChain3::SetColorSpace1` | HDR output detection. **`IDXGISwapChain3`, not 4** — 4 adds only `SetHDRMetaData` (`20_OPEN_QUESTIONS` §H9 — *answered and removed with H1/H3/H4 in the P0 spike (`6b1fa83`); this row used to say `IDXGISwapChain4`, and the corrected interface here IS the answer, so the citation points at history rather than at a live entry*). Unbuilt, which is why `colorSpace` reads `NOT_REPORTED` and `FL_MEASURED_HDR` stays clear. **When it is built, the writer must initialise `colorSpace = FL_COLOR_SPACE_SDR` at swapchain identification** — an SDR title never calls `SetColorSpace1`, so "hook live, no call" would otherwise sit at `NOT_REPORTED` forever and HDR's definite `No` would be unreachable. DXGI documents G22/Rec.709 as the default, which makes SDR a *measured* default rather than an affirmative negative |
| ⏳ `IDXGIFactory::CreateSwapChain*` | Capture swapchain desc (format, buffer count, swap effect, flags) at creation. Unbuilt — the swapchain description is currently read on demand in the present hook via `GetDesc` |
| ✅ `wglSwapBuffers` (2026-09-06, P1 item 4) | OpenGL titles: one record per `opengl32!wglSwapBuffers`, `api` = OpenGL, the output size from `GetClientRect` on the window the HDC belongs to (first sighting and every 256th present, so a resize is caught without a second hook), **no `FL_MEASURED_PRESENT_ARGS`** — the call has no sync interval and no flags. A MinHook inline patch on the flat export (measured 2026-08-05: a `jmp` thunk into the vendor ICD, relocated like any first instruction), installed at init when `opengl32.dll` is already mapped and lazily on the watchdog otherwise, with the `LoadLibrary` detour waking it for `opengl32.dll`. Exercised by `hook-harness --opengl --hold-presenting N`, which calls **gdi32's `SwapBuffers`** the way a title does — measured to reach the hook (ctest `fl_guard` `[opengl]`, on Microsoft's generic renderer, so it runs on CI too). The one system-module row below carries the inventory asymmetry |
@@ -180,11 +194,12 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|---|---|
| NGX: `NVSDK_NGX_D3D11/D3D12/VULKAN_CreateFeature`, `EvaluateFeature`, `ReleaseFeature` | Which NGX feature is *actually created and evaluated per frame*: SuperSampling (DLSS), RayReconstruction (DLSS-D), FrameGeneration (DLSS-G) |
| NGX parameter accessors (`NVSDK_NGX_Parameter_SetI/GetI/SetUI`) — **exported by `sl.common.dll` only; see below** | `Width`/`Height` (render) vs `OutWidth`/`OutHeight` (output), `PerfQualityValue` (quality preset), sharpness |
| ✅ Streamline: `slEvaluateFeature` · ⏳ `slInit`, `slSetFeatureLoaded`, `slSetConstants`, `slGetFeatureRequirements` | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **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 that may be aggregated as a negative |
| ✅ Streamline: `slEvaluateFeature` · ⏳ `slInit`, `slSetFeatureLoaded`, `slSetConstants`, `slGetFeatureRequirements` | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`; since beta.34 `kFeatureDLSS_NR` — DLSS 5's neural rendering, its own fact bit and family `FL_HOOK_SL_NEURAL_RENDERING`, D84; rule 4: the `feature` argument of the API hooked, nothing else). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **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 that may be aggregated as a negative |
| ✅ Streamline: `slSetTag` — **and, since 2026-09-05, every tag's TYPE** (`slTagCensus`; a HUD-less / UI tag marks the present `FL_FG_DLSS_G`, rule 4: the same argument) | The **global** resource tags, where a title states the size of the buffer it is upscaling *from*: `kBufferTypeScalingInputColor`'s extent → `renderW/H` — **or, since 2026-09-05, the size the tagged `sl::Resource` declares when the extent is zero** (`TagSize` in `fl_sl_inputs.h`, shared by all three tag routes; GUID-checked; a Resource declaring no size is still the honest unknown). **Built 2026-08-15** (`FL_HOOK_UPSCALER_PARAMS`), and it is an ALTERNATIVE to the local tags in `slEvaluateFeature`'s `inputs`, not a layer over them — `sl_core_api.h:258` says global and local tags "do NOT interact", so a title using one yields nothing from the other and both are read. Published only on a frame where an evaluation was also seen, because a tag is viewport state that outlives any one frame. This row was MISSING from this table while the hook shipped, which is the gap the banner above now names |
| ✅ Streamline: `slSetTagForFrame` — **and every tag's TYPE, as above** | The same global tags through **Streamline 2.8's frame-based entry point**, which deprecates `slSetTag`: `(const FrameToken&, const ViewportHandle&, const ResourceTag*, uint32_t, CommandBuffer*)` — the token first, then exactly `slSetTag`'s list, handed to the same tag walk. **Built 2026-09-04** (`FL_HOOK_UPSCALER_PARAMS`, its own trampoline; the family is now **published when whole** — once every tag export the loaded interposer has is patched — because publishing on the first row entitled records the second was not yet producing, 38 of 41 on the fixture: the ffx leaves' #110 defect again, fixed the same way). Measured need: Dying Light: The Beast (SL 2.8.0) published `Dlss` identity on every batch and the params bit on none across three captures, because a 2.8 title that tags per frame never calls the deprecated export. The token is not read; the frame count stays with `slGetNewFrameToken`. The installer picks this detour by SYMBOL (`kSymbolSlSetTagForFrame`, bound to the row by `static_assert`), not by family, since the two rows share a family bit and differ in signature |
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither) + one COUNT; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00 |
| XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute` | `outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG |
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither — *since beta.25 the quality byte is the mode the `ffxQuery` row below names for the dispatched size, `0xFF` when none does*) + one COUNT; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00 |
| ✅ **FidelityFX ffx-api: `ffxQuery` on the same four modules** (beta.25, owner decision D65) — `amd_fidelityfx_dx12.dll`, `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, `amd_fidelityfx_loader_dx12.dll` | **Built 2026-10-19.** The mode an FSR title runs at reaches the vendor only as an argument of `ffxQuery` — "what render size (`…GETRENDERRESOLUTIONFROMQUALITYMODE`, `0x00010003`) or ratio (`…GETUPSCALERATIOFROMQUALITYMODE`, `0x00010002`) does this mode give at this display size?" — asked before the title sizes its targets; the per-frame dispatch carries the size alone. The detour calls the original FIRST, exactly once, and only when it returned `FFX_API_RETURN_OK` reads the descriptor's type, display size and mode and the values the vendor wrote through the title's own out pointers, into a five-slot table (one per `FfxApiUpscaleQualityMode`); the `ffxDispatch` UPSCALE arm names the ONE mode whose kept answer fits the dispatched `renderSize` (and `upscaleSize`, where stated) as `0x10 + mode` in `upscalerQuality`, else `0xFF` (`03_METRICS` §Upscaling). **Rule 4:** the arguments of the API we hooked — the descriptor the title passed and the out values of that same call — never `context`, a resource or anything the title did not hand the hooked export; nothing of the title's is written, and every read is under the hook's SEH guard. Both query layouts and type ids are pinned to literals by `static_assert`s, identical at SDK v1.1.4 and v2.3.0. **Its own family**, `FL_HOOK_UPSCALER_QUALITY` (bit 11 of `hooksInstalledMask`, mirrored in `FlHookFamily` and `HookFamilies`): `InstallByFamily` binds a row by equality, and the query entitles no measured field by itself — the byte rides under `FL_MEASURED_UPSCALER_PARAMS` from the dispatch arm — so the bit says only that the query was hooked, which tells "never asked" from "could not have seen it ask". Published like the dispatch family, once every loaded leaf is patched (`PublishFfxQueryFamilyIfWhole`); the FSR 3.0 host has no `ffxQuery` and no row (`static_assert`). A loader that passes a query on to a leaf's export refreshes one kept answer twice; nothing is counted, so nothing is counted twice. **Measured overhead** (a copy of the two bodies, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3 runs, every slot holding both a size and a ratio — the worst case): 7.6–8.2 ns added per UPSCALE dispatch, i.e. per application frame, and 1.6 ns per query beside the trampoline; the per-present path gains one load. Harness: `--ffx-query sizes|ratios`; `fl_guard` "FSR's quality mode". |
| ~~XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute`~~ **Closed at the census by licence, 2026-09-04** (`20_OPEN_QUESTIONS` §Scope decisions, `18_GPU_VENDOR_APIS` §Intel XeSS SDK): no hook on any `libxess*.dll` export *(corrected 2026-10-04)* | ~~`outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG~~ |
| ✅ **Application frames per present** (`fgEvaluations`) — **`sl.interposer.dll!slGetNewFrameToken` since 2026-09-03** | Native vs Displayed frame counts at Tier 1 — see `03_METRICS` §Frame Generation. **The producer is the frame-token export**: Streamline hands a title one token per application frame and the title must ask; the detour counts distinct tokens between two presents (pointer changes, nothing dereferenced), `FL_HOOK_FG_EVALUATIONS` is its family, and it installs on every Streamline 2 title including the ones that evaluate nothing through `slEvaluateFeature`. Rule 4: the out-parameter of an API we hooked. Premise and its gate in `03_METRICS`; pre-committed table in `20_OPEN_QUESTIONS` §S31. *The row as it stood before:* ~~NGX/SL/FFX/XeSS FG feature evaluations per present. **Built 2026-08-15 for Streamline, and MEASURED TO YIELD NOTHING ON THAT ROUTE**~~ — `slEvaluateFeature(kFeatureDLSS_G)` is never called by Cyberpunk 2077 (0 across ~14,000 batches, four FG settings), so this row installs, is honest, and counts zero; see `docs/HANDOFF.md` item 3. Built on the detour that was already there: `kFeatureDLSS_G` contributes to a saturating COUNT in the same word the feature bits live in (`fl_sl_seen.h`) rather than to a bit, because a bit collapses several evaluations between two presents into one — and under multi-frame generation that is the common case, not the edge. The row's family is therefore compound (`FL_HOOK_UPSCALER_IDENTITY \| FL_HOOK_FG_EVALUATIONS`), pinned by a `static_assert` because `hookinventory-check` reads that column as an opaque identifier. **Counts EVALUATIONS, not generated frames** — the 2026-08-14 owner ruling; the multiplier lives in `sl::DLSSGOptions`, which is only reachable by the route §2b refused. ~~Non-NVIDIA FG vendors are **deferred with a written rationale**: `amd_fidelityfx_framegeneration_dx12.dll` 3.1.5 exports only the five generic `ffx*` entry points, identical to five sibling modules, so identity is in the arguments and we have no headers~~ — **AMD has a producer since 2026-09-04** (the FidelityFX row above: the PREPARE dispatch's `frameID`, or the UPSCALE count on a title that never prepares, feeds `fgEvaluations` when Streamline has never issued a token); Intel stays at the census (`20_OPEN_QUESTIONS` §Scope decisions, by licence); the FSR 3.0 host DLL's UPSCALE (`ffxFsr3ContextDispatchUpscale`, since 2026-09-05) counts like an ffx-api UPSCALE when neither Streamline nor a PREPARE has spoken |
> `GetFrameStatistics().PresentCount` is **not** in this inventory and must not be
@@ -318,7 +333,7 @@ So:
### Memory / latency
| Hook / call | Yields |
|---|---|
| `IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread) | **Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact |
| ~~`IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread)~~ | ~~**Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact~~ **Never built; superseded 2026-10-03 (D43):** the game's memory is read from OUTSIDE the game by the Agent (`18_GPU_VENDOR_APIS` §The game process's memory), so nothing in the Overlay calls it. Only the budget would need it, and that stays open (`20_OPEN_QUESTIONS` §M11) |
| NVAPI Reflex: hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`; call `NvAPI_D3D_GetLatency` | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
### Explicitly not hooked
@@ -349,7 +364,9 @@ Vulkan gets an **implicit layer** (`FrameLedger.VkLayer`), not injection — it
DLL**, and it compares the variable's **value**, so a stray
`FRAMELEDGER_ENABLE_VK_LAYER=0` does not enable us. **This makes Vulkan
Tier 1 launch-mode-only** — the Agent sets the variable when it starts an
opted-in game, so a Vulkan title launched from Steam or GOG is not hooked.
opted-in game, so a Vulkan title launched from Steam or GOG is not ~~hooked~~ observed by the layer *(corrected
2026-10-04: attach mode has no Vulkan rule, so such a title gets the Overlay injected like a D3D one, and what its
DXGI hooks record there is unverified; `kTargetIsVulkanLayered` applies to launch mode only)*.
It is a *loading* gate, not a security gate: anything running as the user can
set the variable.
@@ -464,7 +481,7 @@ struct alignas(64) FlFrameRecord { // 64 bytes exactly, static_assert'd
uint16_t outputW, outputH; // @22
uint8_t api; // @26 d3d11|d3d12|vulkan|opengl
uint8_t upscaler; // @27 0 = NOT_REPORTED; dlss|fsr2..4|xess|nis|none(8)|unknown(0xFF)
uint8_t upscalerQuality; // @28 vendor enum; 0xFF = a hook ran and could not tell
uint8_t upscalerQuality; // @28 vendor enum (FSR: 0x10 + mode, beta.25); 0xFF = a hook ran and could not tell
uint8_t fgMode; // @29 0 = NOT_REPORTED; dlss_g|fsr_fg|xefg|none(4)|unknown(0xFF)
uint8_t rtFlags; // @30 bit0 asBuildOBSERVED, bit1 dispatchOBSERVED, bit2 psoCreatedEver
uint8_t colorSpace; // @31 0 = NOT_REPORTED, 1 SDR, 2 HDR10, 3 scRGB
@@ -477,7 +494,9 @@ struct alignas(64) FlFrameRecord { // 64 bytes exactly, static_assert'd
uint8_t fgEvaluations; // @43 FG feature evaluations observed this frame
uint32_t vramUsedMb; // @44 MiB, matching vramBudgetMb
uint32_t reflexLatencyUs; // @48 0 = unavailable
uint32_t reserved; // @52 must be zero
uint8_t dxgiUnseen; // @52 DXGI-counted presents the hook did not see (2026-09-05; this listing
// showed a uint32 reserved here until 2026-10-04)
uint8_t reserved[3]; // @53..55 must be zero
uint32_t seq; // @56 seqlock counter (see 07_IPC §Protocol rules)
uint32_t swapchainId; // @60 which swapchain this present came through; 0 = unidentified
};
@@ -515,8 +534,9 @@ Field notes — each of these was a defect in an earlier revision:
uncomputable from a pinned counter. `rays_per_pixel` divides this by output
pixels.
- **`maxTraceRecursionDepth`** is the second of the four stated inputs to
`pt_confidence`. It is read at `CreateStateObject` (§Hook inventory) but
previously had no transport to the Agent and no column to land in.
`pt_confidence`. It ~~is~~ would be read at `CreateStateObject` (§Hook inventory) but
previously had no transport to the Agent and no column to land in. *(Corrected 2026-10-04: `CreateStateObject` is
not hooked, so nothing writes it yet.)*
- **`_pad0` and `_pad1` were explicit holes and are now carrying data.** Both were
named only so every offset could be asserted; spending them costs nothing,
because both bytes ranges were already inside the record and already written
@@ -551,14 +571,15 @@ Field notes — each of these was a defect in an earlier revision:
- **SPSC lock-free ring**, capacity a power of two (default 8192 records = 512 KB), overwrite-oldest.
- Writer/reader seqlock protocol, including the rule that the payload write must
**exclude** the `seq` field and that `seq` is never reset: `07_IPC` §Protocol rules.
- Header: three separate 64-byte lines before the ring — `FlShmHandshake` (write-once),
- Header: ~~three~~ **four** separate 64-byte lines before the ring *(corrected 2026-10-04: since layout 4, 2026-09-27,
beta.10, `FlDisplayState` at 0xC0 — Overlay-written at most every 500 ms; the ring starts at 0x100)* — `FlShmHandshake` (write-once),
`FlWriterState` (Overlay-written: `writeIndex`, `status`, `apiMask`, `faultCount`),
and `FlControlBlock` (**Agent**-written: `pauseRequested`, `unhookRequested`,
`overlayEnabled`, `guardTicks`). The control flags are *not* in the Overlay's
header — they are written by the other process, and mixing them into an
Overlay-written line reintroduces exactly the false sharing the split exists to
prevent. Layout is normative in `07_IPC` §A + B.
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present.
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present. *(Added 2026-10-04: the summary leaves out the per-present `IDXGISwapChain::GetLastPresentCount` call (§H5, the `dxgiUnseen` count) and the display sample every 500 ms at most (region 4).)*
- Per-frame mutable state (current upscaler, render res, dispatch counts) lives in a small struct updated by the feature hooks and *read* by the present hook; counters reset at present.
## The watchdog thread — the only thread we add to the game
@@ -567,6 +588,11 @@ One thread, started on the init thread *after* the hooks are installed, sleeping
`1000 ms` at a time. It evaluates `unhookRequested` and the `guardTicks` deadline,
calls `StopObserving` when either fires, and **exits** once stopped.
> **Corrected 2026-10-04 — this describes the thread as it was first written.** Since the lazy installers landed
> (`slEvaluateFeature`, 2026-08-09) the loop also installs feature hooks, runs the runtime census, publishes counters,
> appends the native log, and stops on the loader detour's early-stop family; it waits on that detour's wake event with
> a 1000 ms timeout rather than sleeping. `legal/DISCLAIMER.md` §2 says so to users since beta.12 (Disclaimer 2.10).
**Why it exists.** Both stops used to be evaluated only on the present path, and
`MayObserve` is reachable only from `RecordPresent`, which is reachable only from
the two present hooks. In a process that had stopped presenting — hung,
@@ -590,9 +616,12 @@ we do not own; the re-scan it would have run allocates ~1.15 MB transiently; and
it would have called `NtQuerySystemInformation` and probed the SCM from inside a
game, which is the behavioural signature of anti-analysis code (CLAUDE.md rule 3).
None applies to the Overlay, which is loaded by documented `LoadLibraryW` and is
never `FreeLibrary`'d from a live process. **This thread enumerates nothing,
never `FreeLibrary`'d from a live process. ~~**This thread enumerates nothing,
probes nothing and allocates nothing** — it reads two `uint32`s from our own
mapping and sleeps. That distinction is the whole justification and must survive
mapping and sleeps.~~ *(Corrected 2026-10-04: it enumerates no process, module list or service — the rule-3 line, which
holds — but it asks the loader for fixed module names, allocates through MinHook and, for ray tracing, creates one
command allocator and list on the game's own D3D12 device, and writes the log file. The justification below is
restated for that scope: what it must never start doing is scanning.)* That distinction is the whole justification and must survive
any future change: a watchdog that starts scanning is a different object under
rule 3.
@@ -614,7 +643,7 @@ Every hook body is wrapped:
```
- Any SEH exception inside our code ⇒ increment `faultCount`, record which hook, **return control to the original function** so the game continues.
- 3 faults total ⇒ set `status = self_disabled`, uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
- 3 faults total ⇒ set `status = self_disabled`, ~~uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`)~~ restore each patch's prologue only while its bytes are still our jump (compare-and-restore per patch through `StopObserving`, §Unhooking, §H7 — `MH_ALL_HOOKS` would have removed an overlay chained after us; corrected 2026-09-27), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
- Never `__try` around the call to the original function — only around *our* code, so we never mask a game bug as ours or vice versa.
- The trampoline call to the original is always executed exactly once, on every path, including error paths.
@@ -635,7 +664,7 @@ Every hook body is wrapped:
> against the injected Overlay in ctest `fl_guard` `[log]`, where every patch reads `UNHOOK_RESTORED`
> because the harness is alone in its process.
`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status. **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
~~`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status.~~ *(Corrected 2026-10-04: both reach `StopObserving` — compare-and-restore per patch as the note above says, then the status; there is no `MH_ALL_HOOKS`, no vtable entry and no ring flush. The watchdog flushes the native log on its way out.)* **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
### Compare-and-restore, never unconditional restore
@@ -678,11 +707,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
@@ -704,7 +745,7 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
## Test harness
`src/native/tools/hook-harness` — a minimal D3D11 app that presents at a controlled rate. It lets CI and local dev exercise hook paths with **no game and no anti-cheat surface at all** (`14_TESTING`).
`src/native/tools/hook-harness` — a ~~minimal D3D11~~ D3D11/D3D12 app (plus `--vulkan` / `--opengl` modes — corrected 2026-10-04) that presents at a controlled rate. It lets CI and local dev exercise hook paths with **no game and no anti-cheat surface at all** (`14_TESTING`).
Two choices make it run on a hosted CI runner, which is what made vtable-index
verification a dev-machine-only affair before:
@@ -712,8 +753,8 @@ verification a dev-machine-only affair before:
- **WARP** (`D3D_DRIVER_TYPE_WARP`) — a software rasteriser, so no adapter is required.
- **`CreateSwapChainForComposition`** — no `HWND`, so no dependency on a window station or an interactive session.
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**, **`--vulkan --hold-presenting N`** (P1 item 3, real loader, exit 77 = cannot run here) and **`--opengl --hold-presenting N`** (P1 item 4, gdi32 `SwapBuffers` on a hidden window, Microsoft's generic renderer — runs on CI).
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**, **`--vulkan --hold-presenting N`** (P1 item 3, real loader, exit 77 = cannot run here) and **`--opengl --hold-presenting N`** (P1 item 4, gdi32 `SwapBuffers` on a hidden window, Microsoft's generic renderer — runs on CI). *(Added 2026-10-04, each with its own ctest: `--probe-d3d12-vtable`, `--probe-dxr`, `--probe-dxr-inputs`, `--probe-upscaler-resolve`, `--probe-sl-abi`, `--probe-ffx-resolve`, `--probe-sl-inputs`, `--probe-sl-seen`, `--probe-dxgi-count`; and the `--hold-presenting-*` injection fixtures with `--load` / `--load-after-ms`.)*
> **Every present here used to carry `DXGI_PRESENT_TEST`, which submits nothing.** Measured: 500 of them leave `GetLastPresentCount` at 0 while 37 real presents move it by 37. "N presents → N records" was therefore satisfiable only by a writer counting non-frames. `--real` issues real presents; the test-present path is kept as a named mode because it is what an alt-tabbed title actually runs.
Still to add as the hook layer grows: Vulkan devices, RT PSO creation and ray dispatch, stub upscaler exports with the real vendor names, a PSO-compile spike generator, and a fault-injecting hook body for the self-disable path (`14_TESTING` §Integration tests).
Still to add as the hook layer grows: ~~Vulkan devices, RT PSO creation and ray dispatch, stub upscaler exports with the real vendor names,~~ *(the struck three exist — corrected 2026-10-04)* a PSO-compile spike generator, and a fault-injecting hook body for the self-disable path (`14_TESTING` §Integration tests).
+93 -12
View File
@@ -33,7 +33,7 @@ public interface IGpuTelemetrySource : IDisposable
Implementations compose rather than compete:
- `BaselineTelemetrySource` (L1) — always constructed.
- `LhmTelemetrySource` (L2) — constructed when LHM initialises.
- `LhmTelemetrySource` (L2) — ~~constructed when LHM initialises~~ always constructed; a `Computer` that will not open disables the layer for the session (corrected 2026-10-04).
- `NvapiTelemetrySource` (L3) — ~~constructed only on NVIDIA hardware~~ **always constructed since 2026-09-10 (P2 PR-E2)** and disables itself when the bridge DLL or the NVIDIA driver is absent, so the composite's descriptor simply omits `nvapi` and no caller has to know the vendor before composing.
- `CompositeTelemetrySource` merges them with a fixed precedence per field (**L3 > L2 > L1**) and records which layer supplied each value.
@@ -52,20 +52,58 @@ Implementations compose rather than compete:
> `LayerOf(field)` answers per field. It also applies the two-fault rule one level up — a layer
> whose `TryRead` throws (which the port forbids) is excluded on the second throw, the others
> untouched. (3) Identity is its own record, `GpuAdapterIdentity` (name, LUID, ids, memory sizes,
> user-mode driver version), read once per session from DXGI; the Agent hands the handshake's
> `adapterLuid` to `SelectAdapter` so samples describe the adapter the game presented on. Every
> user-mode driver version), read once per session from DXGI; ~~the Agent hands the handshake's
> `adapterLuid` to `SelectAdapter` so samples describe the adapter the game presented on.~~ *(Corrected 2026-10-04:
> nothing calls `SelectAdapter` outside tests. L1 stays on the first hardware adapter in DXGI's high-performance order,
> as `HardwareSnapshotSource` does, and the handshake's `adapterLuid` is read by no managed code — so on a
> multi-adapter machine L1 can describe an adapter the game did not present on. The game's own memory, D43, is
> summed over every adapter and is not affected.)* **Built in beta.13:** the recorder hands the handshake's
> `adapterLuid` to the poller at the first tick that carries one (`CaptureProgress.AdapterLuid`, noted in the
> `.partial`), and `CompositeTelemetrySource.SelectAdapter` points L1 at it (`IGpuAdapterSelector`) and tells the layers
> that read their own GPU its vendor (`IGpuVendorFollower`): L2 maps that vendor's GPU node instead of the first one
> LibreHardwareMonitor lists (on a laptop often the integrated GPU), and L3 contributes nothing when the game's adapter
> is not NVIDIA's — N/A rather than another card's temperature. **What stays first-found:** a session before the game's
> first present, a Tier-2 session (no handshake), a game presenting through OpenGL or Vulkan (they publish no LUID), two
> GPUs of one vendor (L2 and L3 take that vendor's first), and the session's hardware snapshot
> (`HardwareSnapshotSource`, taken before the first present). Every
> poller sample is stamped with QPC (`TelemetrySample.QpcTicks`), the ring's clock, and
> `QpcClockTests` pins `Stopwatch` / `TimeProvider.GetTimestamp` to the real counter.
> Per-process VRAM comes from the **Overlay** (`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game), not from here. Adapter-wide VRAM is a separate series with a different label — they answer different questions and users will otherwise think one of them is broken.
> ~~Per-process VRAM comes from the **Overlay** (`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game), not from here.~~
> **Corrected 2026-10-03 (beta.12, D43): the game process's memory is read from OUTSIDE the game** — §The game process's
> memory below; the Overlay never called `QueryVideoMemoryInfo`. Adapter-wide VRAM is a separate series with a different
> label — they answer different questions and users will otherwise think one of them is broken.
### The game process's memory (beta.12, owner decision D43)
`FrameLedger.ProcessStats.dll` — the third native facade the Agent loads beside itself (`NativeProcessStats`, after the
guard's and the NVAPI bridge's), never into a game — reads one process's memory per call:
- **Video memory:** the documented performance counters `\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated
Usage` and `\Shared Usage` (`PdhAddEnglishCounterW` with a `*` instance, so a localised counter name does not matter;
`PdhGetFormattedCounterArrayW` after each collection), every instance naming the pid **summed** — each adapter and
physical index the process allocated on. This is the per-process figure, so the adapter-wide rule below ("filter to our
adapter, don't sum blindly") does not apply to it. **No handle to the game is needed.**
- **System memory:** `GetProcessMemoryInfo` with `PROCESS_MEMORY_COUNTERS_EX2` (its `PrivateWorkingSetSize` is Task
Manager's "Memory"), retried with `PROCESS_MEMORY_COUNTERS_EX` where the OS refuses the larger structure; an EX2
answer whose private working set was left as written (a sentinel) or reads zero beside a nonzero working set is N/A,
never a measured zero. It needs `PROCESS_QUERY_LIMITED_INFORMATION` and
nothing more: the session's held handle when it has one, else a handle opened for the read and closed after it, whose
creation time must be the watcher's (a reused pid is refused, not read).
- **Not `D3DKMTQueryStatistics`.** It answers the same per-process segment figures, but Microsoft documents it as
"Reserved for system use"; the counters are the documented face of the same accounting.
- Measured on the dev box (`spike-notes` §16): one collect + read costs 0.1 ms (max 0.22 ms), a 512 MiB allocation reads
+512.0 MiB, the private working set equals `\Process V2(…)\Working Set - Private`, 600 collections leak nothing. One
`GameMemoryReader` per session, on the session's `fl-telemetry` thread (`TelemetryPoller`'s third source).
## L1 — baseline (no licence, all vendors)
- **DXGI:** `IDXGIFactory6::EnumAdapterByGpuPreference` → adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes. ~~`IDXGIAdapter3::QueryVideoMemoryInfo` for adapter-wide usage/budget.~~ **Measured wrong, 2026-09-09:** `DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsage` is the *calling process's* usage by the structure's own definition — which is exactly why the Overlay reads it inside the game for `vram_proc` — and from the Agent it read **0 bytes** beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (`DxgiAdapters`, the first CsWin32 consumer in the tree).
- **DXGI:** `IDXGIFactory6::EnumAdapterByGpuPreference` → adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes. ~~`IDXGIAdapter3::QueryVideoMemoryInfo` for adapter-wide usage/budget.~~ **Measured wrong, 2026-09-09:** `DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsage` is the *calling process's* usage by the structure's own definition ~~— which is exactly why the Overlay reads it inside the game for `vram_proc` —~~ *(corrected 2026-10-04: the Overlay never read it, and `vram_proc` was never produced — §The game process's memory)* and from the Agent it read **0 bytes** beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (`DxgiAdapters`, the first CsWin32 consumer in the tree).
- **PDH performance counters** — the same source Task Manager uses, fully documented, vendor-neutral:
- `\GPU Engine(*)\Utilization Percentage` (sum per engine type: 3D, Compute, Copy, VideoDecode)
- `\GPU Adapter Memory(*)\Dedicated Usage`
- `\GPU Process Memory(*)\Dedicated Usage` (cross-check against the Overlay's figure)
- `\GPU Process Memory(*)\Dedicated Usage` ~~(cross-check against the Overlay's figure)~~ — **read since 2026-10-03
as the game process's own figure** (§The game process's memory; the Overlay never produced one)
- Instance names embed the LUID — parse and filter to our adapter, don't sum blindly across GPUs.
> **Built 2026-09-09 (PR-E1), one counter of the three:** `PdhAdapterMemoryCounter` binds
@@ -75,8 +113,10 @@ Implementations compose rather than compete:
> idle desktop, moving tick to tick. A machine without the counter set fails the open and the
> field is N/A with the layer standing — not a fault. **`Utilization Percentage` is deliberately
> not read** (`20_OPEN_QUESTIONS` §M10, decided): `LoadPct` is L2's vendor-reported load and is
> labelled as such. `GPU Process Memory` is not read either — the Overlay's in-process figure is
> the one the pipeline stores, and a cross-check is a diagnostic, not a field.
> labelled as such. ~~`GPU Process Memory` is not read either — the Overlay's in-process figure is
> the one the pipeline stores, and a cross-check is a diagnostic, not a field.~~ **Since 2026-10-03 (D43) `GPU Process
> Memory` IS read** — by `FrameLedger.ProcessStats.dll`, as the game process's dedicated and shared GPU memory; there was
> never an in-process figure to cross-check.
- **Driver version:** ~~`SetupAPI` / registry adapter properties.~~ **`IDXGIAdapter::CheckInterfaceSupport(IDXGIDevice)`** — its documented second output is the user-mode driver version for that interface, four 16-bit fields of one 64-bit value (`32.0.16.1664` on the dev box, 2026-09-09; the WARP adapter answers with the OS build). Neither SetupAPI nor the registry is walked: both need a device-instance enumeration nothing else here has a reason to carry. Feeds the hardware snapshot and the trend-chart change markers (`06_DATA_MODEL`). This is the four-part form the vendor's own tooling shows, not the marketing number (`561.09`), which only L3 knows.
- **Optional probe, P0 evaluation only:** `D3DKMTQueryAdapterInfo` with `KMTQAITYPE_ADAPTERPERFDATA` reportedly exposes temperature, power and fan for any vendor. The D3DKMT structures are **not fully documented and have changed across Windows builds**. Treat as an experiment: if it proves stable on both Win 10 22H2 and Win 11 during P0, keep it as an L1 extra behind a capability flag; if it looks fragile, drop it and let L2 handle temperatures. Never let it be load-bearing.
@@ -105,13 +145,31 @@ L1 gives no temperatures on its own (unless the D3DKMT probe pans out). That is
`LibreHardwareMonitorLib` ≥ 0.9.6, consumed as an **unmodified NuGet package**. It already implements per-vendor GPU sensor access internally — which means the vendor-interop licensing problem is one LHM has solved upstream, under a licence that works for us. That is the entire reason this layer exists.
- `Computer` opened with `IsGpuEnabled` always; `IsCpuEnabled` + `IsMemoryEnabled` only when the Agent is elevated and PawnIO is available.
- `Computer` opened with `IsGpuEnabled` always; ~~`IsCpuEnabled` + `IsMemoryEnabled` only when the Agent is elevated and PawnIO is available~~ nothing else, ever — the CPU temperature uses a separate `Computer` (below) (corrected 2026-10-04).
- Poll on a dedicated thread: `computer.Accept(updateVisitor)` then read mapped sensors. Never faster than 500 ms; default 1000 ms.
- Sensor mapping by `SensorType` + name heuristics per vendor (`GPU Core`, `GPU Hot Spot`, `GPU Memory`, `GPU Package Power`, …), kept in `SensorMap.cs` with unit tests against captured sensor-tree fixtures.
- **P0 verification items:** (a) which fields LHM actually returns per vendor on real hardware — fill the capability matrix below — **NVIDIA filled 2026-09-03, AMD/Intel deferred (§R5/§R6)**; (b) ~~whether GPU-only usage works **without** elevation and without PawnIO (expected yes, since GPU sensors go through user-mode vendor paths, but confirm — it determines whether the default unelevated Agent has temperatures at all)~~ — **confirmed 2026-09-03, §M5 row R1**: eight fields unelevated, the same eight elevated, PawnIO never opened; (c) ~~confirm LHM's sources are not marked with MPL-2.0 Exhibit B~~ — **done, 2026-08-02: clear.** No source file applies the notice; the only repository hit is the `LICENSE` template itself, and every file we depend on carries the permissive Exhibit A. Method and evidence in `docs/spike-notes.md` §0. Re-check on every version bump, and check *source headers*, never the LICENSE file — MPL-2.0's own text contains Exhibit B as a template, so grepping the licence finds it in every MPL project ever published.
CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, and optional.
> **The machine beside the GPU — built 2026-09-21, and deliberately NOT a fourth layer.** `ISystemTelemetrySource`
> (`Telemetry.SystemTelemetrySource`) is read by `TelemetryPoller` on the same tick as the composite and rides each
> `TelemetrySample` as a `SystemReading` — outside `GpuSample`, because the per-field capability bits and layer
> attribution above mean nothing for "how busy was the CPU". Two unprivileged Win32 calls, no process opened:
> `GetSystemTimes` (busy = (kernel + user) − idle over the interval; kernel INCLUDES idle in that API; the first tick has
> no interval and is null) and `GlobalMemoryStatusEx` (physical memory in use). **CPU temperature is the one privileged
> reading**: `LhmCpuTemperatureReader.TryOpen` opens a SEPARATE `Computer` (~~CPU group only~~ CPU and memory groups, GPU off — corrected 2026-10-04 — L2's stays GPU-only and
> unelevated by design, so the unprivileged layer's behaviour never depends on privilege) only when the process is
> elevated AND `PawnIo.IsInstalled`; it takes the package sensor (`CPU Package`, `Core (Tctl/Tdie)`) and falls back to the
> hottest core. **Unmeasured on real hardware**: exercised against a fake `ILhmComputer` only; the first elevated run
> with PawnIO is the measurement — **which the user can now choose to make (beta.10, the admin mode: Settings ▸ Capture
> agent ▸ Run the agent as administrator, `01_ARCHITECTURE` ADR-9)**; until beta.10 an elevated Agent existed only when an
> App started as administrator happened to start it, and `PrivilegeFootprintTests` now asserts on the elevated CI runner
> that opening this CPU group enables no privilege. `HelloAck.cpuTempAvailable` reports those same two conditions (it was a constant
> `false`). A tick only the machine answered is still queued, under a placeholder `GpuSample` with
> `TelemetryLayer.None` and no field. The `.partial` sensor chunk carries the three values in bits 12–14 of the
> existing 16-bit presence mask, so an older file reads back with an empty reading.
## L3 — NVAPI (MIT, NVIDIA only)
**Integration: vendored headers + import library, linked normally. ✅ Vendored 2026-08-05** at `src/native/third_party/nvapi/` — nine headers (`nvapi.h`'s include closure plus `nvapi_interface.h`), `License.txt`, and `amd64/nvapi64.lib`; **x64 only**, `x86/nvapi.lib` deliberately not taken. Consumed through the `fl_nvapi` INTERFACE target. NVIDIA publishes the NVAPI SDK — headers, interface definitions, and `nvapi64.lib` — under the **MIT licence** (verified 2026-08-02 and re-verified on the vendored copy: `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 and not only the headers), so the SDK material can live in our GPL-3.0 repository with only the usual MIT attribution obligation. The runtime implementation lives in `nvapi64.dll`, which ships with the installed NVIDIA driver.
@@ -146,6 +204,29 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
> **Not in this build, stated so nobody infers it from the table below:** VRAM (`FlNvSample.vram` is
> reserved and its bit is never set — see the Memory row), power, hotspot temperature, per-domain
> utilisation beyond the GPU domain, and anything Reflex (§M8: a hook fact, not a poller field).
>
> **ABI 2 (2026-09-25, beta.8): the driver profile, read-only.** The owner asked whether the NVIDIA App overrides a
> game's DLSS (frame generation, ray reconstruction, the model preset). The NVIDIA App writes those overrides into the
> driver's own settings store (DRS), so `FlNvDriverProfile(exePath, ids, count, out)` reads them there: a DRS session
> is created, the settings loaded, the profile the driver applies to that path found (`NvAPI_DRS_FindApplicationByName`
> — a fully qualified path returns the profile the driver will apply on launch; none named → the current global
> profile), each id read with `NvAPI_DRS_GetSetting` (value, where it comes from, whether someone set it), and the
> session destroyed. **No DRS setter exists in the bridge** — not `SetSetting`, not `SaveSettings`, not
> `RestoreProfileDefault`, not `NvAPI_NGX_SetNGXOverrideState`: the overrides are the user's, and this only reports
> them. A path longer than NVAPI's string is refused, never truncated (a truncated path names another program).
> The ids and their values' meanings are NVIDIA's `NvApiDriverSettings.h` (github.com/NVIDIA/nvapi, MIT), written into
> `Application.Capture.NvidiaDriverSettings` as eighteen constants rather than vendored as a header; Smooth Motion
> (`0xB0D384C0`) is not in NVIDIA's header and is documented by community profile tools only, which every surface
> that shows it says. Managed: `NvapiDriverProfileSource` (`IDriverProfileSource`) — the Agent's recorder reads the
> profile beside every session, both tiers, and stores it in `sessions.driver_profile` (schema 0012). Verified by
> ctest `fl_nvapi_bridge` (argument refusals, DEGRADED before init, the global profile of the test's own executable on
> a GPU machine) and `NvapiBridgeMirrorTests` (`FlNvDriverProfileSize`, ABI 2).
>
> **The ctest could not fail on a GPU machine until the same day.** `fl_nvapi_bridge` was registered with
> `PASS_REGULAR_EXPRESSION` alone, which makes ctest ignore the exit code: the AVAILABLE branch's reference-counting
> check (two references, two releases, then a read expected to work) failed on every machine with an NVIDIA GPU while
> ctest reported Passed, and CI — no driver — never takes that branch. The check is corrected and the registration now
> carries a `FAIL_REGULAR_EXPRESSION` on Catch2's failure lines.
| Purpose | Function |
|---|---|
@@ -156,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). *(Beta.27: never read after the game has gone — that reading, the last, had cleared `CREATED \| EVALUATE` on every stored session — and the two bits stand once a reading carried them: `03_METRICS` §The driver-reported rung.)* |
| **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.
@@ -267,7 +348,7 @@ on the NVIDIA dev box even though nothing in it may be hooked or declared.
- Poll at 1 Hz on a dedicated Agent thread. Never from the game process, never from the Overlay.
- Any layer that throws or hangs twice is disabled for the session and its fields report `N/A`, rather than being retried in a loop.
- **Read-only, always.** These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile.
- **Read-only, always.** These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile. *(Since beta.8 the same holds for the driver's settings store: the bridge reads DRS profiles and has no entry point that writes, saves or restores one — §L3, ABI 2.)*
## Capability matrix (fill during P0 on real hardware)
@@ -297,7 +378,7 @@ as the same thing.
|---|---|---|---|
| GPU utilisation | **deferred by decision** (§M10, 2026-09-09) — L2's vendor-reported load is what `LoadPct` carries, labelled as such; the engine counters are not read | untested | untested |
| Adapter VRAM | ✓ **measured 2026-09-09** — PDH `GPU Adapter Memory … Dedicated Usage`, 1301 MB at an idle desktop, RTX 5080 (`QueryVideoMemoryInfo` measured **not** adapter-wide: 0 bytes from the Agent) | untested | untested |
| Per-process VRAM | `arch` for L1 — the Overlay's in-process `QueryVideoMemoryInfo` is the figure stored; `GPU Process Memory` is not read | `arch` | `arch` |
| Per-process VRAM | ~~`arch` for L1 — the Overlay's in-process `QueryVideoMemoryInfo` is the figure stored; `GPU Process Memory` is not read~~ ✓ **measured 2026-10-03** — `GPU Process Memory` Dedicated/Shared by pid from outside the game, +512.0 MiB for a 512 MiB buffer (`spike-notes` §16) | untested | untested |
| Driver version | ✓ **measured 2026-09-09** — `CheckInterfaceSupport(IDXGIDevice)` → `32.0.16.1664` | untested | untested |
| Core temp | ? (D3DKMT probe, Win 11 only — see below) | untested | untested |
| Power | ? (D3DKMT probe) | untested | untested |
+568 -47
View File
@@ -18,11 +18,11 @@ These are permanently out of scope. A PR implementing any of them is rejected re
- Hiding, renaming, or randomizing the DLL, its exports, or its shared-memory object names
- Thread hiding (`NtSetInformationThread`/`ThreadHideFromDebugger`) or debugger-evasion tricks
- Signature-breaking obfuscation/packing of our own binaries
- Any "stealth mode", "bypass" setting, or documentation explaining how to defeat the guard below
- Any "bypass" setting, "stealth mode", or documentation explaining how to defeat the guard below. *(The first two words left this line on 2026-09-21 and returned on 2026-09-22 — §What a finding does to the game. The one exception the owner has granted since, D33 on 2026-09-26, is not a bypass: the guard still runs every check and decides itself which family is user-mode — §The user-mode exception.)*
- Reading or writing game memory outside the arguments of APIs we hooked
- Kernel drivers of our own
The DLL ships with its real filename, a populated VERSIONINFO block (`CompanyName`, `ProductName=FrameLedger`, version), and named kernel objects that clearly say `FrameLedger`. Being identifiable is a feature.
The DLL ships with its real filename, a populated VERSIONINFO block (`CompanyName`, `ProductName=FrameLedger`, version), and named kernel objects that clearly say `FrameLedger`. Being identifiable is a feature. Since beta.14 (D50) the Agent — the process that injects — and the App say the same about themselves: `FrameLedger` as company and product, *FrameLedger Agent* as the Agent's description, the native binaries' copyright line (`12_BUILD` §Version, *Identity*; `tools/versioninfo-check.ps1` reads both kinds).
## The anti-cheat guard (hard gate)
@@ -51,6 +51,19 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> handle rights above are confirmed sufficient for every target this call can
> legitimately reach.
>
> **Amended 2026-10-05 (owner decision D48, beta.14): one re-read, never a pass.** A member of the scan set that
> is still being created answers `ERROR_PARTIAL_COPY` (its loader has not built a module list), and one that exited
> between the snapshot and the open answers `ERROR_INVALID_PARAMETER`. Both refused the whole session — and at the
> 30 s re-scan an engine's crash reporter starting as its game died, or any helper started a moment before the scan,
> turned an ordinary exit into a "safety" unhook, which ends a user-mode exception's trial for good. Such a member
> (`Collected::kRetry`, `fl_guard.h`) is now read once more: the pass finishes (a finding in any member still refuses
> at once), waits `kScanRetryPauseMs` (250 ms), takes a **fresh** scan set and scans it whole. A member still unreadable
> then refuses `kProcessUnreadable`, as before; one that has gone is not in the new set; a target that has gone leaves
> no set, which refuses `kProcessTreeUnavailable`. **`ERROR_ACCESS_DENIED` — a protected process — is never retried**,
> and no other answer of any source is. The sentence above stands: every failure still means REFUSE; what changed is
> how many times "still loading" is asked before it counts as one. ctest `fl_guard` `[D48]` holds both directions,
> against fakes and against the real source (a process created suspended, a pid with no process).
>
> **Launch mode (2026-09-06, P1 item 2) does not weaken this.** `FlGuardedInjectWhenReady` polls
> the same enumeration to learn *when* the launched target has mapped a presentation runtime, and a
> failing enumeration there means "not yet" — the poll continues. That is not a pass: the poll
@@ -91,6 +104,23 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> inspected (`ERROR_ACCESS_DENIED`) refuses too — there is no "scanned what we
> could" state.
>
> **Amended 2026-10-06 (owner decision D51, beta.15): a parent link is followed only while creation times allow it.**
> The set is walked over one process snapshot, which links a process to its parent by pid alone, and Windows reuses
> pids. A launcher that exits after starting its game leaves the game naming a pid that may now belong to anything:
> until beta.15 the walk scanned whatever held it — a protected process refused the session as unreadable, a
> blocklisted one turned the game's hooking off for good — and a cycle of reused pids sent the same processes round
> again. A parent/child link is now cut **only when it is proven wrong**: both creation times read (`GetProcessTimes`,
> under the module scan's own read-only right) and the child created **before** the process whose pid it names as its
> parent, which no real child can be. A cut ancestor link ends the ancestor walk there; a cut child is not walked, nor
> is anything below it. A time that cannot be read keeps the link, equal times keep it, and each pid is walked and
> scanned once (`WalkScanSet`, `fl_guard_scanset.cpp`). Nothing else about the set moved: the launcher boundary, the
> depth (16 ancestors), the frontier (512 — one more refuses) and "a member that cannot be read refuses". **The
> residual:** creation times are wall-clock, so a clock set *backwards* between a parent's start and its child's makes a
> real link look wrong and drops that branch from the module check; the install-folder scan and the machine-wide driver
> and service checks do not depend on the tree. ctest `fl_guard` `[D51]` holds the walk against fixtures (a reused
> parent, an older "child", unread times, equal times, cycles, the limits) and the real source against a child this
> process starts.
>
> **One reviewed exception, decided 2026-08-03 and implemented 2026-08-04
> (§S18), then re-keyed the same day (§S22(b)).** A module that is FrameLedger's
> own does not trip the *fuzzy* fragment tier. The exact blocklist still applies
@@ -217,8 +247,51 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> `NtQuerySystemInformation` is a documented-as-unsupported API and its
> `RTL_PROCESS_MODULE_INFORMATION` layout is version-sensitive; the struct
> offsets must be asserted, not assumed. Treat a parse failure as *refuse*,
> never as *clean*. `20_OPEN_QUESTIONS` §S7 tracks the remaining work.
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, updatable independently of app releases (`05_DETECTION` §Rules updates).
> never as *clean*. ~~`20_OPEN_QUESTIONS` §S7 tracks the remaining work.~~ *(Corrected 2026-10-04: done —
> `fl_guard_sources.cpp` asserts the layout and refuses a parse that yields non-native paths; §S7, closed, is about
> handle rights and WOW64.)*
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, ~~updatable independently of app releases (`05_DETECTION` §Rules updates)~~ shipped with each release; there is no rules-update path yet *(corrected 2026-10-04: `20_OPEN_QUESTIONS` §S20 feed half; `05_DETECTION` §Trust and staleness of the rules feed)*.
> **Both halves are wired and seeded since 2026-09-25** (owner: "as many and as strict as possible"; rules
> `2026.09.4`). The block below is the history it replaces, kept for the reasoning.
>
> **The store half reads the store's own files, through a seam the guard owns.** `Sources::StoreIdentity` takes the
> install root the guard already derives from the pid (check 4's `ImageDirectory`) and answers from disk: under
> `<library>\steamapps\common\<folder>`, the one `appmanifest_<id>.acf` whose `installdir` is `<folder>` →
> `steam:<id>`; a `goggame-<id>.info` in the root → `gog:<id>`. Nothing is handed in by a caller (§S3 is untouched —
> the ABI still takes a pid and nothing else) and nothing is read from the game's process (rule 4).
>
> **The matrix §S14 asked for:** a listed identity refuses (`BlockedStoreId`, naming the family); an install no store
> names — a loose folder, a GOG-less, manifest-less copy — is **not** refused, because "no store identity" is an
> answer, not an unknown, and refusing it would be the gate that cannot pass; a store layout whose metadata could not
> 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~~ 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). **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
> numbered name (`usrdrv017864.sys`, ValveSoftware/Proton#8853), outside the game's folder, so the `.sys` rule cannot
> see it before the first run and no driver token could name it. Each of the three store pages states *"Uses Kernel
> Level Anti-Cheat"* and CrackProof (read 2026-10-03); ANOTHER EDEN, which a community list also names, was left out
> because its store page says nothing of the kind.
> Every app id was checked against its Steam store page; Call of Duty's changed when Activision split CoD HQ, so only
> ids with a live store page are listed. The per-title lists are **floored** like the families: a rules file can
> add a title and cannot take one off. `rules-validate` refuses a name engines and tools share (`Game.exe`,
> `Client-Win64-Shipping.exe`, `hl2.exe`…), an exact rule that names no `.exe`, and duplicates.
>
> **The owner declined the bulk list** (AreWeAntiCheatYet's ~250 Steam ids): community data that keeps listing a game
> after it drops its anti-cheat would turn hooking off for good on a title that no longer needs it.
> ⚠ **◐ The EXECUTABLE half is wired as of 2026-08-05; the STORE-ID half is
> blocked.** `CheckBlockedExecutable` runs inside `EvaluateImpl` between the
@@ -250,8 +323,26 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> rules file — and therefore every title on the machine (§S17).
4. **Multiplayer heuristic** — if the pre-launch file scan finds an anti-cheat SDK shipped alongside the game (e.g. EOS anti-cheat binaries, `EasyAntiCheat/` directory) even when not currently loaded → refuse and explain.
> **Any kernel driver in the install tree counts, since 2026-09-25 (owner decision).** A `*.sys` file that no
> `files` entry names is reported as `AntiCheatFile` under the family **"Kernel driver in the game folder"**. Every
> driver this project has found shipped inside a game — `PGameProtectDriver_X64.sys`, `randgrid.sys`,
> `NeacSafe64.sys`, `BlackCat64.sys`, `mhyprot*.sys` — was an anti-cheat's, and naming each one in data first is how
> the next one walks past, as ACE's did in August. The rule is **code, not data** (`fl_prescan.cpp`,
> `kKernelDriverInTreeFamily`): no rules file can remove it or rename its family. A named `files` entry still wins,
> so `randgrid.sys` reads as Activision Ricochet. **The cost the owner accepted:** a game that ships a driver for
> some other purpose (a wheel, a peripheral, an old disc check) has its hooking turned off like any finding, and
> nothing clears it.
>
> **The advisory pre-scan takes the executable and resolves the install root itself, since 2026-09-25.**
> `FlStaticPreScan(gameDirectory)` scanned the directory it was handed, and its one caller (`SetHookEnabled`) handed
> it the executable's own folder — so for an Unreal title, the scan that decides whether hooking may be turned on
> looked at `<root>\<Project>\Binaries\Win64\`, exactly where the Lies of P measurement below says `EasyAntiCheat/`
> is not. The chokepoint always resolved the root. `FlStaticPreScanGame(exePath)` replaces it: the same
> `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
@@ -262,7 +353,7 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> nothing produced either.
>
> **It runs inside the chokepoint**, as the last of the four checks in
> `EvaluateImpl`. `FlStaticPreScan` also exports it for FR-2.2's pre-launch
> `EvaluateImpl`. ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` (since 2026-09-25 — corrected 2026-10-04) also exports it for FR-2.2's pre-launch
> question, but that export is **advisory**: it gates nothing, and a caller who
> never asks it — or ignores the answer — changes nothing about what injection
> allows.
@@ -271,9 +362,11 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> could. Since 2026-08-04 `FrameLedger.Guard.dll` ships beside the **Agent
> only** (`FrameLedger.Guard.targets`, §S18 blocker 3), so `FrameLedger.App`
> has no `FlStaticPreScan` call site and no DLL to load. FR-2.2's advisory
> answer reaches the UI through the Agent over IPC (`07_IPC`) when that exists.
> answer reaches the UI through the Agent over IPC (`07_IPC`) ~~when that exists.
> Recorded rather than quietly reworded: an advisory export with no consumer is
> a claim about the product that is not true yet.
> a claim about the product that is not true yet.~~ *(corrected 2026-10-04: it does — the Agent's
> `SetHookEnabled` answer carries it since P3, `HookEnabledAck.Prescan`, and the library sweep's
> `hook_prescan_state` since beta.8 is shown on the game's page)*.
>
> **Which directory.** The **install root**, resolved by walking up from the
> executable to a known platform boundary (`steamapps\common\<X>` and
@@ -294,24 +387,56 @@ 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-11-03 (beta.33, `spike-notes` §25): a GDK package root is a boundary too, and `GamesInstalled`
> is one natively.** The Xbox app and the Microsoft Store install to `<games folder>\<Game>\Content\` under a
> folder the user names, which no string can bound — so for the executable the import picks there (an Unreal
> title's `Content\<Project>\Binaries\WinGDK\…-Shipping.exe`), check 4 walked `Binaries\WinGDK` alone, and an
> `EasyAntiCheat\` at `Content`'s root would have read clean: the residual above, on a whole store. The package
> marks its own root — `MicrosoftGame.config` beside `appxmanifest.xml`, both files — so **only when no string
> boundary matched**, the nearest folder at or above the executable's that holds both is the root (at most eight
> levels up, never a drive's root; `ResolveInstallRoot` and the managed `InstallRoot`). Not a blind walk up: a
> marker the package writes, measured as exactly one per package at `Content`'s root on the owner's 11 titles; and
> only ever a widening relative to the executable's folder — a Steam build carrying GDK files keeps its Steam root.
> The native list also gains `GamesInstalled\<X>`, which the managed one had since #17 and the native one never
> did; one case list (`tests/fixtures/install-roots/cases.txt`), read by both suites, holds the two resolvers
> together from now on.
>
> **Amended 2026-10-13: the root AND the executable's folder.** The root replaced the executable's folder, and
> that was half the answer. The walk reaches three levels below where it starts, and an Unreal executable is
> already three below its root, so a folder **beside** the executable is four: MEASURED on Wuthering Waves, whose
> Tencent ACE lives in `Client\Binaries\Win64\AntiCheatExpert\` (with `ACE-BASE.sys` and `ACE-CORE.sys` in it). The
> walk from the root listed `Win64` and never opened it, so the library pre-scan read the game clean three times,
> hooking stayed available, and the first session was hooked for 37 s until the 30 s re-scan met ACE's driver —
> machine-wide, so nothing was turned off (`spike-notes.md` §19). Neverness To Everness keeps a second
> `AntiCheatExpert\` beside its `HTGame.exe`, six levels down, that no walk had seen either. Check 4 now walks the
> root and then, when the executable lives below it, the executable's own folder — same walk, same reach, its own
> 4096-entry budget, the same matcher and the same D33 tolerance (`ScanGameFolders`). `ImageDirectory` names the
> executable's folder and the checks resolve the root from it. Raising the reach instead was measured and rejected:
> depth 4 still misses NTE's folder, and at depth 5 three installed titles overrun 4096 entries (Yu-Gi-Oh! Master
> Duel: 41,251), which would refuse them. Measured across the owner's 83 Steam installs, the second walk costs at most
> 103 entries and newly finds exactly those two folders.
>
> **What it does not cover.** Beyond the above, the residual is an anti-cheat
> SDK sitting on disk whose service is not installed and whose module is not
> loaded; checks 1, 2 and 2b already cover the rest. And today the `directories` + `files`
> groups carry only three tokens between them, so "check 4 ran" is a much
> groups carry ~~only three tokens~~ 67 tokens between them since 2026-09-25, plus any `.sys` by code *(corrected
> 2026-10-04; documented names, not measured ones)*, so "check 4 ran" is a much
> narrower statement than "this game ships no anti-cheat". Widening it needs
> **verified** file and directory names — the seed table below deliberately
> carries "no data yet" rows rather than guesses, because a wrong token fails
> closed by never firing, which is a silent hole.
>
> **Every uncertainty refuses**, with `Reason::kPreScanFailed` rather than a
> hit: directory absent or unlistable, either bound exceeded, a name we could
> hit: directory absent or unlistable, ~~either bound exceeded~~ the 4096-entry bound exceeded, a name we could
> not convert, or a reparse point — which is never followed, because a
> junction can hide an `EasyAntiCheat/` beneath it. **Unmeasured:** how often
> junction can hide an `EasyAntiCheat/` beneath it. *(Corrected 2026-10-13: the DEPTH bound never refused. It is a
> reach — a folder at the last level is named and not opened, and the walk still reads as complete — which is how
> Wuthering Waves' ACE was missed; the paragraph above is what answers it.)* **Unmeasured:** how often
> a legitimate library trips the reparse-point rule or the 4096-entry bound.
> That needs a real game library, and it is a false-refusal path, so it is
> recorded rather than assumed benign.
Any check failing ⇒ **injection is refused**. The UI shows which check fired and offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing (`04_CAPTURE` §Frame source abstraction).
Any check failing ⇒ **injection is refused**. The UI shows which check fired and ~~offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing (`04_CAPTURE` §Frame source abstraction)~~ **records the session unmeasured — Tier 2: its duration, the machine's sensors and the reason — which needs no injection and no elevation; there is no ETW rung and no Tier 3 since 2026-08-28** (corrected 2026-09-27: this sentence outlived the ladder it described by a month).
### The payload is checked too, and for a long time it was not
@@ -348,7 +473,214 @@ the injection primitive, not a fifth question about the title.
- **Absent** is still `kInjectionFailed`, not `kPayloadNotOurs`. A damaged install
and a misuse of the ABI are different problems and must not share a reason.
> There is no override. No hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch. If a user disagrees with a specific entry, the path is a GitHub issue against the rules file, reviewed in public — not a local bypass.
> **There is no override.** ~~There is one, since 2026-09-21, and it is none of the things this paragraph named~~ *(one day; withdrawn 2026-09-22)*: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below — and since 2026-09-26 (D33), one narrow, evidence-bound exception for anti-cheat that is user-mode throughout, which lets a named family through while every check still runs (§The user-mode exception).
### The target must be able to take the Overlay — beta.33 (D78)
The last question before the primitive, after checks 1–4 and the payload's identity passed: **can this process take the
Overlay at all?** The guard reads it from the target itself (`Sources::TargetIsolationFacts`, one
`PROCESS_QUERY_LIMITED_INFORMATION` handle — measured 2026-11-03 to answer both questions, `GetProcessMitigationPolicy`
needing no more):
| Read | Refusal | Why it cannot work |
|---|---|---|
| `TokenIsAppContainer` | `kTargetAppContainer` | a Microsoft Store app of the UWP kind: the Overlay's shared memory, its `Local\` names and the rules file live in the user's session namespace and profile, which an AppContainer cannot open. D78: GDK games are in, UWP apps are out |
| `ProcessSignaturePolicy`: `MicrosoftSignedOnly` or `StoreSignedOnly` | `kTargetMitigation` | the Overlay is neither (CLAUDE.md rule 9: unsigned): the remote `LoadLibraryW` fails |
| `ProcessDynamicCodePolicy`: `ProhibitDynamicCode` | `kTargetMitigation` | MinHook's trampolines are dynamic code: the Overlay would load and hook nothing |
| `ProcessUserShadowStackPolicy`: strict mode, or `BlockNonCetBinaries` / `BlockNonCetBinariesNonEhcont` | `kTargetMitigation` | the Overlay is not marked CET-compatible: refused at load, or a violation ends the game |
| `ProcessControlFlowGuardPolicy`: `StrictMode` | `kTargetMitigation` | `native/CMakeLists.txt` H1: measured safe with strict mode off only; a host in strict mode could still `__fastfail` on the trampolines, which no fault policy can catch (rule 5) |
**The policy is the signal**, and only the enforcing flags count: an `Audit*` flag refuses nothing, and
`SetContextIpValidation` without strict mode is what every CET-compatible process carries (measured: `pwsh.exe`
`0x105`). A policy the running Windows does not know answers `ERROR_INVALID_PARAMETER` (measured) and cannot be in
effect. **"Could not tell" refuses** — a seam that fails, or none wired — as `kProcessUnreadable`, the module check's word
for a process it could not read. ctest `fl_guard` `[isolation]` holds each refusal through fakes, and two of them against
Windows itself: a child started under "no dynamic code" and "Microsoft-signed images only".
**Neither is a finding.** Nothing is written to the game's row and no family is named; the session is Tier 2 with the
reason, as for a 32-bit game. **No game that measured before is refused now**: each of these ended as a failed injection,
an Overlay that installed no hooks, or a risk of ending the game. It is asked once, before the injection — never by the 30 s
re-scan, which runs inside a process the Overlay is already in — and, like the payload check, it is not numbered as a
check: it is a precondition of the primitive, not a question about the title.
**A GDK game's tree, measured (`spike-notes` §25, six titles activated through their packages):** the chain is
`GameLaunchHelper.exe` → `gamingservicesui.exe` → `XboxPcTray.exe` → the launch executable (→ an Unreal title's shipping
executable), `GameLaunchHelper` exits first, and its parent is the activator — the user's shell when **Play** starts it,
which is where the scan set already stops. Every member opened with the guard's rights as a standard user, none is an
AppContainer, none runs under any of the policies above, and no member's module matched a fuzzy fragment or a blocklist
name. So the scan set needs nothing new for these titles; an Xbox title that ships anti-cheat is unmeasured
(`20_OPEN_QUESTIONS` §G).
### What a finding does to the game — owner decision 2026-09-22
**The per-game override of 2026-09-21 is withdrawn.** It shipped in `0.1.0-beta.3` and `beta.4`. Its first real use
(D21, below) showed that it 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 disclosure described. The owner withdrew it on 2026-09-22: the native entries, the
pipe message, the App's dialog and card, the strings and the five columns of schema 0007 are gone (schema 0008 drops
them). Sessions that ran under it keep `guard-bypass=` in `capture_notes`; nothing else remembers it.
**What replaced it is the opposite of an override: a finding turns the game's hooking off.** The pre-scan has done
this since P2 (`RecordGuardBlockAsync`: `hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`).
Every later moment the guard can find something writes the same block — a fourth since 2026-09-25:
| Moment | Where | What it sees |
|---|---|---|
| hooking is turned on | `AgentCommandHandler.SetHookEnabledAsync` | checks 3 and 4 over the executable and its install root (`PreScanGameAsync`; check 4 over the executable's own folder until 2026-09-25) |
| a session starts | `CaptureSession.SessionAsync`, after the gate | checks 1–4 over the live process, its tree, the drivers, the folder |
| the 30 s re-scan | `CaptureSession.DrainAsync`, on a `SafetyUnhook` | the same, for an anti-cheat that loaded late |
| the Agent's pre-scan of the library | `AntiCheatPreScanSweep`, under `--serve` | checks 3 and 4 over every entry, whether or not its hooking was ever on |
**The Agent's pre-scan of the library — owner decision 2026-09-25 (beta.8).** Until then the first three moments were
the only ones, and each needs the user to have asked for hooking: a game nobody enabled stayed
`hook_prescan_state = 'not_run'`, so the App could not tell an anti-cheat game from any other. The owner asked for the
hooking part of anti-cheat games to be hidden, which needs to know which they are, so the Agent now asks the advisory
question itself (`AntiCheatPreScanHostedService`: at start, every 15 s, and at once after `UpdateRules`):
- **Which entries.** Every library row not removed, once per rules version and executable — the key is its own
(schema 0010: `hook_prescan_rules_version`, `hook_prescan_exe_size_bytes`, `hook_prescan_exe_mtime_ms`), so a rules
update that names a game already in the library, or a game update that adds anti-cheat, is a re-scan. Skipped: a
blocked row (it is never asked again), an executable that cannot be read, an entry whose session is running (that
session's own checks are). *Change executable* clears the key with the state, so the new binary is scanned.
- **What it writes** (`IGameConsentStore.RecordPreScanAsync`): a finding about the game is the block above, the
consent stamp kept; a pass is `'clean'`; a scan that could not answer is `'unverified'`, which leaves the toggle
alone. It never writes over a block and never adds a row — the `UPDATE` itself requires both, so a block written
between the sweep's read and its write still stands.
- **What it tells.** A `HookingTurnedOff` event (`07_IPC`) only when the entry's hooking was on: the one case where
something the user switched on changed. Every other finding changes only the game's page and card.
- **What it is not.** It gates nothing: every session start still runs checks 1–4 against the live process, whatever
the sweep wrote. It opens no process — the scan reads the executable's path, its install folder and the stores'
files. It holds the guard's lock for one walk at a time (`NativeAntiCheatGuard` serialises every native call), so a
session start waits for at most the one walk in flight.
**Which findings** — `AntiCheatVerdict.IsFindingAboutTheGame`: an anti-cheat *named* (family non-empty) in the game's
own process (`BlockedModule`), on its title lists (`BlockedExecutable`, `BlockedStoreId`) or in its folder
(`AntiCheatDirectory`, `AntiCheatFile`). **Not** a machine-wide driver or service (`BlockedDriver`, `BlockedService`):
a driver running for another game says nothing about this one, so that refuses this session and writes nothing. Not a
scan that could not look, not unusable rules, not the unsigned-module heuristic, not the latch of an earlier block.
**What the user sees.** The refusal or unhook notice ends with `Safety_HookingTurnedOff`; the game's page shows the
block (`Safety_Blocked_Toggle_Format`) with the toggle disabled; `capture_notes` carry
`hooking-turned-off=<reason>/<family>`; the Agent's session line carries `; hooking-turned-off`; `CaptureRefused` and
`SafetyUnhook` carry `hookingTurnedOff` (`07_IPC`). `CaptureOutcome.HookingTurnedOff` is the loop's word for it.
Since 2026-09-25 (beta.8): the block is stored as `Reason|Family|Signal` so the App says what was found in the user's
language (rows written before keep `"Reason: Family Signal"` and are shown as stored); the library card says
*Anti-cheat* instead of *Hooking off*; and the game's page shows the finding **in place of** the Hooking card, whose
switch could only be refused, while `ui.hide_anticheat_hooking` is on — its default (`08_UI` §Game detail). Off, the
card is back with the finding under its disabled switch. The finding itself is on the page either way (FR-2.2).
**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.)* *(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).
Nothing will be built that opens it — that would be defeating another product's protection, which is rule 3. The same
reason covers a game that runs as administrator while the Agent does not.
**What did not change.** `InjectViaLoadLibrary` keeps internal linkage in `fl_guard.cpp` and `tools/chokepoint-check.ps1`
still finds the injection primitives in exactly that file and the evasion primitives nowhere. `IAntiCheatGuard` is back
to four methods (`NoSecondMatcherTests`). `FloorFamilies` is untouched.
### The user-mode exception — owner decision 2026-09-26 (D33)
**Why it exists.** The beta.8 library sweep turned hooking off for *GIRLS' FRONTLINE 2: EXILIUM* on a documented,
unmeasured rule — NetEase Yidun, `AntiCheatFile NEP2.dll` — after FrameLedger had measured that game hooked (three
normal Tier-1 sessions in the owner's ledger, 474,143 frames). The owner asked for a way to keep measuring a game like
that, and chose, against the rule this document had kept since 2026-09-22 and with that rule quoted back to them, **an
exception the user grants per game, bound to evidence, and only for anti-cheat that is user-mode throughout.** The
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — ~~an exception is only
offered where FrameLedger has already measured the game hooked~~ *(D38 below: the measurement now comes under the grant,
as its trial)*; it "only exposed the user to the risk its own disclosure described" — that risk stands, and the disclosure
says so, including that a ban can arrive days later and that FrameLedger cannot know.
> **Amended 2026-10-03 (owner decision D38): the evidence comes after 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. The rule
> below was a catch-22 for every game it could ever meet again: since beta.8 the library sweep blocks a game the moment
> it is added, a blocked game is never hooked without a grant (`CaptureSession` sends it to Tier 2 before the resolver),
> so it can never earn the two sessions, and a reset ledger loses the ones it had. D33's evidence was reachable only for a
> game measured before its block, and only while those rows lasted. Asked with that, the owner chose: **a grant needs no
> session; the first two hooked sessions under it are a trial; any of them that does not go well ends the exception for
> good** (`games.ac_exception_trial_failed_at`, schema 0017, which nothing clears). Every other condition is unchanged.
**What may be excepted — all of it must hold:**
- every finding about the game is `BlockedModule`, `AntiCheatFile` or `AntiCheatDirectory` of **one** family;
- that family's whole footprint is user-mode — no `drivers` entry, no `services` entry and no `*.sys` among its `files`, in
the compiled floor or the rules file (`fl::guard::FamilyIsUserModeOnly`). The floor cannot be shrunk, so data can make a
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain,
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 *(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`
(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.~~
**Since D38 (2026-10-03): no session is needed** — and no exception of the game has ever ended during its trial
(`ac_exception_trial_failed_at` is NULL).
**Never excepted, whatever the user ticked:** a machine-wide `BlockedDriver` or `BlockedService`, the fuzzy tier
(`SuspiciousUnsigned`), a scan that could not look or finish, unusable rules, `TargetUnreadable` (D21), a 32-bit target,
the kill switch, and a Vulkan target (the implicit layer's own self-scan stays strict).
**How the guard takes it.** The four evaluating ABI entries carry `toleratedFamilies` — a NAME, never evidence
(`fl_guard_abi.h`). The guard resolves it against its own rules (`ResolveTolerance`), keeps only a user-mode family,
runs every check, lets that family's modules, files and folders through **and keeps scanning past them**, so a second
family, a suspicious module or a `.sys` further in still refuses. A pass that let something through is
`kAllowedUserModeException` (reason 28, the slot the withdrawn bypass left) with the family and the signal; the session it
starts is marked with them.
**How the Overlay takes it.** The Overlay stops observing when a floor module loads after injection, so the Agent
publishes the exception's family names in `Local\FrameLedger.Tolerate.<pid>` (`fl_tolerance.h`) before it asks the guard
to inject, and the Overlay's init thread reads them once, before its loader detour exists — resolving each against its
own compiled floor and honouring only a user-mode family. A mapping that names anything else tolerates nothing, and the
Agent's 30 s re-scan keeps judging every other signal.
**What ends it.** A new finding outside the excepted family at any of the four moments above writes the block as before
and revokes the exception; a session under it that crashes, is unhooked for safety or is stopped by the Overlay's
in-process floor stop revokes it; an executable change ends it with the consent it shared a fingerprint with; turning
the option off suspends every exception. **The block itself is never cleared** — the exception is a separate layer over
it, and the finding stays on the game's page (FR-2.2).
**The trial (D38).** Until two sessions under a grant have succeeded — hooked, stored, frames recorded, `normal`
(`ISessionRepository.CountSuccessfulUnderGrantAsync`: under that family, started at or after the grant) — the grant is in
its trial, and the App says so ("trial: 1 of 2"). During the trial **any** end of the list above ends the exception
**for good**, and so does a stored hooked session that recorded no frame or did not end normally
(`UserModeExceptionLapse.TrialFailed`, decided by `UserModeExceptionLapsePolicy` when the recorder stores the row): the
end is recorded with its own reason and `ac_exception_trial_failed_at` is set. While it is set the sweep writes the game
not eligible, the Agent refuses a grant (`Refused.reason = TrialFailed`, the signal is when) and the store refuses one in
SQL; withdrawing, a game update, *Change executable* and a twin merge all keep it. A session too short to be stored, or
one that was never hooked, is not judged by its frames or its exit — it neither counts toward the two nor fails the
trial that way — but an end of the list above still ends the exception for good during the trial: a crash while
hooked, however short, or a finding about the game at the start. After the trial, an end is what it was under
D33: the exception may be made again once the sweep finds the game eligible. Deleting sessions can only lengthen a trial
— the count is read, never stored as a grant's own fact.
**What it is not.** Not a bypass of a live refusal, not a global switch (a Settings option off by default enables the list,
and the user ticks each game), not reachable from the command line, and not evasion: the DLL stays `LoadLibraryW`-loaded,
named and visible (rule 3). `InjectViaLoadLibrary` still has internal linkage in `fl_guard.cpp`; `tools/chokepoint-check.ps1`
is unchanged.
*Built in beta.9. PR-1: the guard's tolerance and the Overlay's channel. PR-2: the Agent — the option
(`hooking.usermode_ac_exceptions`, off), the sweep's eligibility pass (a tolerant pre-scan keyed on the rules, the
executable and the block; the session count every pass), the `SetAntiCheatException` command (the Agent gathers the
facts itself; the store applies the rule), the gate's one branch with the channel published before the request, the
re-scans naming the family, the session's mark, and every end (`UserModeExceptionLapse`) — schema 0014. PR-3: the
option and the list in Settings, the versioned disclosure (`Safety_Exception_*`, `AntiCheatExceptionDisclosure`), the
game page's exception card and its usable switch under an exception in force, the marks, and the legal text
(Disclaimer §2A 2.7, EULA 1.3, the accuracy block, SECURITY.md) — `08_UI` §Games.*
*D38 in beta.11 (2026-10-03): `UserModeExceptionRules.TrialSessions` replaces `RequiredSessions`; eligibility is the
guard's answer and the trial mark; `ac_exception_sessions` is the trial's progress; schema 0017
(`ac_exception_trial_failed_at`); `Refused.reason` `TrialFailed` replaces `TooFewSessions`; the disclosure is
`ac-exception-dialog/2` (its `Why` names no count, a new `Trial` paragraph); the Settings list shows only games it can act
on; and a sweep that cannot read the executable answers "could not verify" instead of leaving the row "checking" for ever.
Legal text: Disclaimer §2A 2.9, EULA 1.4, the accuracy block, SECURITY.md, LIMITATIONS.md.*
### The floor data cannot remove
@@ -422,32 +754,112 @@ earlier version of this table produced an entry that was matched *literally* and
therefore never fired. A silent hole in the blocklist, created by its own
normative documentation. Write tokens here exactly as the data must hold them.
| Family | Group | Match | Tokens |
|---|---|---|---|
| Easy Anti-Cheat | `modules` | prefix | `EasyAntiCheat`, `EasyAntiCheat_EOS` |
| Easy Anti-Cheat | `directories` | name | `EasyAntiCheat` |
| Easy Anti-Cheat | `services` | name | `EasyAntiCheat`, `EasyAntiCheat_EOS`, `EasyAntiCheat_EOSSys` |
| Easy Anti-Cheat | `drivers` | prefix | `EasyAntiCheat` — **machine-wide refusal** (check 2) |
| BattlEye | `modules` | prefix | `BEClient`, `BEService` |
| BattlEye | `directories` | name | `BattlEye` |
| Riot Vanguard | `drivers` | exact | `vgk.sys` — **machine-wide refusal** (check 2) |
| Riot Vanguard | `services` | name | `vgc` |
| Denuvo Anti-Cheat | `modules` | prefix | `denuvo` |
| nProtect GameGuard | `modules` | prefix | `GameGuard`, `npgg`, `GameMon` |
| Xigncode3 | `modules` | prefix | `xhunter` |
| Xigncode3 | `files` | name | `x3.xem` |
| mihoyo protect | `drivers` | prefix | `mhyprot` |
| FACEIT | `modules` | prefix | `faceit` |
| ESEA | `modules` | prefix | `esea` |
| PunkBuster | `modules` | prefix | `PnkBstr`, `pbcl`, `pbsv` |
| Anti-Cheat Expert | `drivers` | exact | `ACE-BASE.sys`, `ACE-ADVT.sys`, `ACE-GAME.sys` — **machine-wide refusal** (check 2) |
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service` |
| Anti-Cheat Expert | `files` | name | `PGameProtectDriver_X64.sys` |
| **Activision Ricochet** | — | — | **No data yet** — driver and service names unconfirmed (`20_OPEN_QUESTIONS` §S5) |
| **Valve VAC** | — | — | **No data yet** — needs `blockedStoreIds`, whose half of check 3 **cannot be called** (§S14; the executable half was wired in #52, but a renamed exe defeats it anyway, which is why this row reserves the store-id route). **Measured 2026-08-04: a real VAC title returns `Allow`** (`spike-notes.md` §13) |
| Family | Group | Match | Tokens | Added |
|---|---|---|---|---|
| Easy Anti-Cheat | `modules` | prefix | `EasyAntiCheat`, `EasyAntiCheat_EOS` | seed |
| Easy Anti-Cheat | `drivers` | prefix | `EasyAntiCheat` — **machine-wide refusal** (check 2) | seed |
| Easy Anti-Cheat | `directories` | name | `EasyAntiCheat`, `EasyAntiCheat_EOS` | seed; `EasyAntiCheat_EOS` 2026-09-25 |
| Easy Anti-Cheat | `services` | name | `EasyAntiCheat`, `EasyAntiCheat_EOS`, `EasyAntiCheat_EOSSys` | seed |
| Easy Anti-Cheat | `files` | name | `EasyAntiCheat_EOS_Setup.exe`, `EasyAntiCheat_Setup.exe`, `EasyAntiCheat_x64.dll`, `EasyAntiCheat_x86.dll`, `EasyAntiCheat_EOS.sys`, `start_protected_game.exe`, `eac_server64.dll` | 2026-09-25 |
| BattlEye | `modules` | prefix | `BEClient`, `BEService` | seed |
| BattlEye | `drivers` | exact | `BEDaisy.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| BattlEye | `directories` | name | `BattlEye` | seed |
| BattlEye | `services` | name | `BEService`, `BEDaisy` | 2026-09-25 |
| BattlEye | `files` | name | `BEService.exe`, `BEService_x64.exe`, `BEClient.dll`, `BEClient_x64.dll`, `BEDaisy.sys` | 2026-09-25 |
| Denuvo Anti-Cheat | `modules` | prefix | `denuvo` | seed |
| Denuvo Anti-Cheat | `drivers` | exact | `denuvo-anti-cheat.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Denuvo Anti-Cheat | `services` | name | `denuvo-anti-cheat` | 2026-09-25 |
| Denuvo Anti-Cheat | `files` | name | `denuvo-anti-cheat.sys`, `denuvo-anti-cheat-runtime.dll`, `denuvo-anti-cheat-update-service.exe` | 2026-09-25 |
| nProtect GameGuard | `modules` | prefix | `GameGuard`, `npgg`, `GameMon` | seed |
| nProtect GameGuard | `directories` | name | `GameGuard` | 2026-09-25 |
| nProtect GameGuard | `services` | name | `npggsvc` | 2026-09-25 |
| nProtect GameGuard | `files` | name | `GameGuard.des`, `GameMon.des`, `GameMon64.des`, `npggNT.des`, `npggNT64.des`, `npsc.des` | 2026-09-25 |
| Xigncode3 | `modules` | prefix | `xhunter` | seed |
| Xigncode3 | `modules` | exact | `x3.xem` | 2026-09-25 |
| Xigncode3 | `drivers` | prefix | `xhunter` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Xigncode3 | `directories` | name | `XIGNCODE`, `XIGNCODE3` | 2026-09-25 |
| Xigncode3 | `services` | name | `xhunter1` | 2026-09-25 |
| Xigncode3 | `files` | name | `x3.xem`, `xhunter1.sys` | seed; `xhunter1.sys` 2026-09-25 |
| PunkBuster | `modules` | prefix | `PnkBstr`, `pbcl`, `pbsv` | seed |
| PunkBuster | `drivers` | prefix | `PnkBstrK` — **machine-wide refusal** (check 2) | 2026-09-25 |
| PunkBuster | `directories` | name | `PunkBuster` | 2026-09-25 |
| PunkBuster | `files` | name | `pbsvc.exe`, `PnkBstrA.exe`, `PnkBstrB.exe`, `pbsv.dll`, `pbcl.dll`, `pbag.dll` | 2026-09-25 |
| FACEIT | `modules` | prefix | `faceit` | seed |
| FACEIT | `drivers` | exact | `FACEIT.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| FACEIT | `services` | name | `FACEIT`, `FACEITService` | 2026-09-25 |
| ESEA | `modules` | prefix | `esea` | seed |
| ESEA | `drivers` | prefix | `ESEADriver` — **machine-wide refusal** (check 2) | 2026-09-25 |
| ESEA | `services` | name | `ESEADriver2` | 2026-09-25 |
| Riot Vanguard | `drivers` | exact | `vgk.sys` — **machine-wide refusal** (check 2) | seed |
| Riot Vanguard | `services` | name | `vgc`, `vgk` | seed; `vgk` 2026-09-25 |
| mihoyo protect | `modules` | prefix | `mhypbase` | 2026-09-25 |
| mihoyo protect | `drivers` | prefix | `mhyprot`, `HoYoKProtect` — **machine-wide refusal** (check 2) | seed; `HoYoKProtect` 2026-09-25 |
| 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`, `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 |
| NetEase Anti-Cheat | `modules` | prefix | `NeacSafe`, `NeacClient` | 2026-09-25 |
| NetEase Anti-Cheat | `drivers` | prefix | `NeacSafe` — **machine-wide refusal** (check 2) | 2026-09-25 |
| NetEase Anti-Cheat | `files` | name | `NeacSafe64.sys`, `NeacSafe64_ex.sys` | 2026-09-25 |
| NetEase Yidun | `modules` | exact | `NEP2.dll` | 2026-09-25 |
| NetEase Yidun | `files` | name | `NEP2.dll` | 2026-09-25 |
| Nexon Game Security | `modules` | prefix | `BlackCipher`, `BlackCall`, `BlackXchg` | 2026-09-25 |
| Nexon Game Security | `drivers` | exact | `BlackCat64.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Nexon Game Security | `directories` | name | `BlackCipher` | 2026-09-25 |
| Nexon Game Security | `files` | name | `BlackCipher.aes`, `BlackCipher64.aes`, `BlackCall.aes`, `BlackCall64.aes`, `BlackCat64.sys` | 2026-09-25 |
| TenProtect | `modules` | prefix | `TP3Helper`, `TenSafe` | 2026-09-25 |
| TenProtect | `drivers` | exact | `TesSafe.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| TenProtect | `files` | name | `TP3Helper.exe` | 2026-09-25 |
| AhnLab HackShield | `modules` | prefix | `EhSvc`, `HShield`, `HSInst` | 2026-09-25 |
| AhnLab HackShield | `directories` | name | `HShield` | 2026-09-25 |
| AhnLab HackShield | `files` | name | `HSInst.dll`, `EhSvc.dll` | 2026-09-25 |
| Anybrain | `modules` | exact | `anybrainSDK.dll`, `Cerebro.dll` | 2026-09-25 |
| Anybrain | `files` | name | `anybrainSDK.dll`, `Cerebro.dll` | 2026-09-25 |
| Roblox Hyperion | `modules` | exact | `RobloxPlayerBeta.dll` | 2026-09-25 |
| Roblox Hyperion | `files` | name | `RobloxPlayerBeta.dll` | 2026-09-25 |
| EQU8 | `modules` | prefix | `equ8` | 2026-09-25 |
| EQU8 | `drivers` | prefix | `EQU8_HELPER` — **machine-wide refusal** (check 2) | 2026-09-25 |
| EQU8 | `files` | name | `equ8_conf.json` | 2026-09-25 |
| Activision Ricochet | `drivers` | exact | `randgrid.sys`, `brynhildr.sys`, `atvi-brynhildr.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Activision Ricochet | `services` | name | `atvi-randgrid_sr`, `atvi-randgrid_msstore` | 2026-09-25 |
| Activision Ricochet | `files` | name | `randgrid.sys` | 2026-09-25 |
| FredaikisAntiCheat | `directories` | name | `FredaikisAntiCheat` | 2026-09-25 |
| **Valve VAC** | — | — | ~~**No data yet** — needs `blockedStoreIds`, whose half of check 3 **cannot be called**~~ **Per-title lists since 2026-09-25** (check 3): 13 Steam app ids and 8 executables, the store half wired. VAC runs inside Steam, so no module, driver or file of the game's own can name it — this row stays a dash on purpose. (**Measured 2026-08-04: a real VAC title returned `Allow`**, `spike-notes.md` §13 — the gap these lists close.) | 2026-09-25 |
| **CrackProof** | — | — | **Per-title list since 2026-10-03** (check 3, rules `2026.10.1`): 3 Steam app ids, no executables. Its kernel driver loads from `System32` under a numbered name, so no module, driver or file of the game's own can name it — this row stays a dash on purpose, like VAC's. | 2026-10-03 |
The "no data yet" rows are deliberately kept rather than deleted. An admitted
gap is reviewable; a deleted row is invisible.
gap is reviewable; a deleted row is invisible. ~~Activision Ricochet's was one of them~~ — it has data since
2026-09-25 (~~below~~ above); ~~VAC's stays until its per-title route exists~~ VAC's became per-title lists the same day,
13 Steam ids and 8 executables *(corrected 2026-10-04)*.
> **Expanded 2026-09-25 (owner: "as many anti-cheats and as strict as possible").** Eleven families became
> twenty-two and 19 entries became 74: EA AntiCheat, Activision Ricochet, NetEase Anti-Cheat, NetEase Yidun, Nexon
> Game Security, TenProtect, AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion are new, and
> most existing families gained the groups they lacked — BattlEye's `BEDaisy.sys`, FACEIT's and ESEA's drivers,
> `HoYoKProtect.sys` (which the `mhyprot` prefix never matched), Xigncode3's driver and service, Denuvo's driver.
> **Every new token is DOCUMENTED, not measured**: the sources are SteamDB's `FileDetectionRuleSets` (MIT), the
> vendors' own support pages (Activision RICOCHET, EA, FACEIT, BattlEye), LOLDrivers and DRML, named per entry in
> the data's `note`. The ACE rule above still holds — a blocklist may over-cover and must never under-cover, and a
> wrong token fails closed by never firing — so an unmeasured token is admitted, labelled, and left for a real title
> to confirm. `kMaxFamilies` went 64 → 256 with it (2 × 74 no longer fitted).
>
> **Three services are deliberately absent**, and the reason is the RUNNING rule above: a service counts while it
> runs, and a service that runs outside play refuses every session on the machine. `EAAntiCheatService` can be set
> to start automatically; PunkBuster's `PnkBstrA` runs at every boot once installed; Denuvo's update service runs
> apart from the game. Each family is caught through its driver, its modules or its files instead.
>
> **New `modules` rows are appended, never inserted.** The Overlay's `LoadLibrary` detour reports a 1-based index
> into this group's order (`FlWriterState.earlyStopFamily` → `sessions.early_stop_family`), so a row inserted above
> an existing one would change what indexes already stored mean.
> **Anti-Cheat Expert was added 2026-08-04 from measurement, not from reading.**
> `ACE-BASE.sys` and `ACE-ADVT.sys` were found installed under `System32\drivers`
@@ -474,7 +886,7 @@ gap is reviewable; a deleted row is invisible.
> *every* title, which is how a user ends up hunting for the override that
> CLAUDE.md rule 2 says does not exist.
The list is data, versioned in `detection-rules.json`, expandable without a release. Unknown-but-suspicious modules (filename containing one of the `nameFragments` — today `anticheat`, `antitamper`, `guard`, `protect` — plus unsigned-by-known-vendor) produce a **warn-and-refuse** with a "report this to us" link rather than silently allowing.
The list is data, versioned in `detection-rules.json`, expandable without ~~a release~~ a code change, still delivered by a release (§S20 feed half — corrected 2026-10-04). Unknown-but-suspicious modules (filename containing one of the `nameFragments` — today `anticheat`, `antitamper`, `guard`, `protect` — plus unsigned-by-known-vendor) produce a **warn-and-refuse** with a "report this to us" link rather than silently allowing.
> **Three corrections to that sentence, all recorded in §S19; one is now closed.**
> It listed four fragments while the data carried five (`gameguard` was missing
@@ -531,6 +943,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`,
@@ -599,12 +1020,32 @@ injected or layered**.
> stop). Modules loaded **before** the Overlay attached are the pre-injection scan's, as always. The
> detour supplements the poll; it replaces nothing (§S6's own ruling).
> **This sentence used to say the hook "already exists and is currently unused", which was false.** Corrected 2026-08-04: the Overlay installs no hooks at all — `dllmain.cpp` exports one function and nothing in the tree calls `MH_CreateHook` outside a probe. §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
> **This sentence used to say the hook "already exists and is currently unused", which was false.** Corrected 2026-08-04: the Overlay installs no hooks at all — `dllmain.cpp` exports one function and nothing in the tree calls `MH_CreateHook` outside a probe. *(Overtaken 2026-09-06: P1 installed the hooks and the `LoadLibraryExW` detour above; the Overlay exports four functions. Marked 2026-10-04.)* §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
### Elevated / protected targets
If `OpenProcess` with the needed rights fails (protected process, higher integrity), do **not** escalate creatively. Report "cannot attach" and offer Tier-2. Never attempt to acquire privileges beyond running the Agent elevated at the user's explicit request.
> **The explicit request exists since beta.10 (owner decision D34, 2026-09-27): the admin mode.** An option off by default,
> turned on through a versioned disclosure (`Safety_AdminMode_*`, `agent-admin-dialog/1`) that states what it adds, what it
> does not change, how Windows asks and the risk of a per-user install; then **Windows asks at every start of the Agent**
> (`01_ARCHITECTURE` ADR-9). What it does NOT do, each held by code rather than by this paragraph:
>
> - **It clears no finding and opens no protected process.** The guard runs exactly as unelevated: the driver scan asks
> `NtQuerySystemInformation`, and a process an anti-cheat driver protects stays `TargetUnreadable` (D21) — elevation turns
> "could not look" into an answer only where Windows would give any administrator one.
> - **It enables no privilege.** An elevated token holds `SeDebugPrivilege` and `SeLoadDriverPrivilege` disabled and they
> stay so: `AdjustTokenPrivileges`, `RtlAdjustPrivilege`, `EnterDebugMode` and the debug privilege's name may not appear
> under `src/` (`tools/chokepoint-check.ps1`), and `PrivilegeFootprintTests` asserts on the elevated CI runner that opening
> targets and LibreHardwareMonitor's CPU group enabled none.
> - **It elevates no game.** A game started from FrameLedger gets the desktop shell's token (`UnelevatedProcess`); with no
> shell to take one from, the launch is refused with that reason (`Launch_Error_1400`), never made elevated instead.
> - **It is not silent.** Every start asks; a start that was declined serves as a standard user and says so; the prompt
> answered by another account ends that Agent before it touches anything (exit 11).
>
> The residual risk is stated to the user, not solved: FrameLedger installs per user and unsigned, so a program running
> under the account could replace its files and be run as administrator the next time the user accepts the prompt.
## User-facing consent
Enabling hooking is a **per-game** action, gated by a one-time dialog per game that states, in plain language:
@@ -644,7 +1085,8 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
> neither choice), what is injected and why, **Tier 1 and Tier 2 as two paragraphs of the same shape** (each
> enumerating what the session records; Tier 2 is described by what it does, never as less), the anti-cheat
> statement including the 30 s unhook, the terms-of-service statement, and the typed acknowledgement — the
> primary button is disabled until the phrase is typed exactly, and Enter never enables. `en` and `vi` are
> primary button is disabled until the phrase is typed exactly~~, and Enter never enables~~ *(Enter enables once the
> phrase matches since beta.30, owner decision D69 — below)*. `en` and `vi` are
> written (the owner reviews `vi`); **`ja` is the English verbatim, marked `safety: human review required`**,
> which the resx audit enforces (`09_I18N` §Safety-critical strings). The wording carries a version
> (`Shared.Safety.SafetyDisclosure.Version = consent-dialog/1`; bump on any change of meaning in any
@@ -656,6 +1098,18 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
> `PipeEndToEndTests` (the real pipe, the real pre-scan, the row read back) pin each half. The toggle that opens
> it is the game page's, PR-5.
> **Amended 2026-10-26 (beta.30, owner decision D69): Enter enables once the phrase is typed exactly.** "Enter never
> enables" was built as `DefaultButton = Close`, and WPF UI 4.3.0's template sends Enter to the default button (each
> button's `IsDefault` follows `DefaultButton`, read at the tag) — so the owner typed the phrase, pressed Enter and
> declined without a word, while the game page's switch went on showing *on* beside *off*. Asked with that, the owner
> chose: the primary button is the default; while the phrase does not match, the dialog's content keeps Enter
> (`ConsentDialogContent.SwallowsEnter`) and nothing happens; once it matches, Enter enables, as a click on the
> then-visible *Enable hooking* does. **The typed phrase is still the gate**: the button Enter reaches is disabled — and
> hidden — until the phrase is typed exactly, so a reflexive Enter cannot enable; Esc and *Keep hooking off* still
> decline. No `Safety_Consent_*` string changed, so `consent-dialog/1` stands. `ConsentDialogKeysTests` holds both
> halves on the real template. The tick-box dialogs (D33's exception, D34's admin mode) are unchanged: Enter keeps them
> declined.
> **The Agent stamps one since 2026-09-10 (P2 PR-F, HANDOFF §P2 decision D4):** `FrameLedger.Agent --console
> consent grant` shows `OperatorDisclosure` (the same four statements, first line naming the surface), requires
> the typed phrase, refuses redirected stdin, and records `ConsentProvenance.AgentConsoleOperator` with the
@@ -668,7 +1122,60 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
> publishing `unhookRequested`, and keeps the Vulkan layer off by never setting `FRAMELEDGER_ENABLE_VK_LAYER`
> on a launch.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection). *(Corrected 2026-10-03, beta.12, owner
decision D43: such a hold now reads the game process's own memory once a second — its video memory from performance
counters that open nothing, its system memory through a handle opened with `PROCESS_QUERY_LIMITED_INFORMATION` for the
read and closed after it, the same least right the watcher's snapshot already opens every process with, each second. No
handle is held, nothing is injected, the guard is not involved, and what is read is the kernel's accounting about the
process, never its memory — rule 4 is untouched. A process that refuses even that right reads N/A.)*
### A moved drive is the same executable — owner ask 2026-09-22
Every row is keyed on its executable's path, and consent is a record about one executable: path, size, mtime
(`ExecutableFingerprint`). On 2026-09-21/22 the owner's external drive came back as `H:` instead of `D:`, and
every one of 46 games read "executable unreadable" until the letter came back; a game launched from `H:` matched
its row by file name only and ran as a stranger, keyed on the new path, with no consent. **The path is where the
bytes live; the size and the mtime are what the consent is about.** So `ExecutableRelocator` may move a row to the
same file under another drive-letter root — and only then — with everything kept: consent, block, pre-scan state,
detection. The conditions are the safety of it:
- the file is gone from the row's path (both files present is two copies, not a move; nothing happens);
- exactly one other root holds a file with the same size and the same mtime (two is an ambiguity, and ambiguity
refuses, as it does in the resolver);
- the repository's write requires the same size and mtime again (`RelocateExecutableAsync`), so no caller can point
a consent at a different binary through it;
- no process is opened for any of this; the relocator reads files. It is asked by the 15 s sweep, by the watcher on
a file-name match, and by the enable-hooking command before it says "unreadable".
- **the candidate is the row's own path with only the drive letter changed — for every caller (2026-09-23).** The
watcher's adopt used to accept ANY running path with the row's size and mtime, and every RPG Maker MV game ships
the same NW.js `Game.exe`, byte for byte, with the mtime an unzip keeps: a hooking-on entry whose drive was unplugged
could have followed another game's executable, consent and all. The adopt now requires the drive-letter twin and the
same one-candidate rule as the sweep (over the drive list plus the running file's own drive). A file-name match that
is not adopted records nothing at all (`04_CAPTURE` §Process watcher, HANDOFF D25).
*Change executable* is the other operation and stays what it was: a different binary, so hooking off, consent gone,
pre-scan not run — it is the user saying "that file", not "that file moved".
**Two more answers, 2026-09-23 (owner decisions D26, D27).** Both are downgrades or neutral by construction; neither
can move a consent onto a binary it was not given for.
- **D27 — the file moved and changed.** When the row's file is gone and the only file at its path under another
letter has OTHER bytes (the game updated while the drive had another letter), the row follows it through *Change
executable*'s write (`ChangeExecutableAsync`): the new size and mtime, hooking off, consent cleared, the pre-scan
back to not run, the block kept. The user turns hooking on again for the new binary, through the disclosure, as
for any changed executable. Two such files (two drives) is an ambiguity and refuses. The same rule holds for the
watcher's adopt, whose session is then Tier 2 until the user does.
- **D26 — two entries for one file.** When the move is refused because another entry already holds the target path
— a twin made while the letter was different, as the owner's `H:` entries were — and the file there has the bytes
the stale entry recorded, the two become one (`IGameMerge`, one transaction): the entry made first stays (its name,
notes, consent and history), the other's sessions are re-parented to it, a block either carried is kept (hooking
off; nothing clears a block, and a merge must not be how one disappears), a crash auto-disable still in force is
kept, the crash counts add, and the dropped row is deleted. **Nothing about consent moves between the rows:** the
survivor keeps its own record — which, when it is the entry that moves, is about these same bytes — and the dropped
row's goes with it. A merge waits while a session of either entry runs or waits in a `.partial` to be recovered (a
session finalized under a deleted entry would be dropped), and it is never done with an entry removed from the
library. Other bytes under the twin are not merged: they do not prove the other entry is this game, so the log says
so once and the user removes the entry they do not want.
### A game already enabled can become blocked later
@@ -686,20 +1193,34 @@ game's executable** (path, size or mtime). If it now matches:
§games), so this needs no schema change, and a non-null value already means
"toggle disabled in the UI".
3. `hook_consent_at` is **preserved**. The user did consent; the block is not a
withdrawal of consent and must not silently require them to consent again if
the title is later cleared.
withdrawal of consent and must not silently require them to consent again ~~if
the title is later cleared~~ *(corrected 2026-10-04: nothing clears a block since D22; the stamp is kept for the
record and for a D33 exception)*.
4. The UI shows a persistent notice, not a transient toast — the user needs to
understand why a game they enabled stopped being captured at Tier 1.
A rules update that *removes* a match does **not** re-enable hooking on its own.
A rules update that *removes* a match does **not** re-enable hooking ~~on its own.
Turning it back on is a user action, because re-enabling silently would mean the
rules feed can switch injection on for a game without anyone looking.
rules feed can switch injection on for a game without anyone looking.~~ — nothing does *(corrected 2026-10-04: the block
outlives a rules change, a game update and *Change executable*; §What a finding does to the game)*.
## Crash & stability safety
- Two crashes of the same game within 60 s of injection ⇒ hooking auto-disabled for that game, UI explains, Tier-2 takes over. Recorded in `games.hook_autodisabled_reason`.
- 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).*
- **Measured 2026-10-19/20 (`spike-notes` §23): direct starts turned hooking off for exits no hook caused.** Lies of P
started by **Play** ▸ *Start directly* hands itself to Steam within seconds — its process leaves with nothing
presented and Steam starts the game again —, and Clair Obscur: Expedition 33 started directly closes within five
seconds and reads *crashed*, hooked or not (its third start, refused and unhooked, closed the same way). Each was a
hooked session's early abnormal end; the policy counted them, and two turned hooking off. It cannot tell either from
the hang it exists for, so it stands as written; whether a witness — the same executable started again within
seconds — may exempt a hand-off is the owner's decision, not taken. Users are told in `LIMITATIONS.md` §Play.
- **What reads as a crash changed in beta.14, in both directions** (`04_CAPTURE` §Crash & exit classification): a
Windows report that is not a crash (a memory-leak or hang report) no longer makes one, and an engine's crash reporter
started by a game that then left does — Unreal's crash ended with exit code 3 and read `normal`. Both feed this policy,
the D33 lapse and D38's trial as `crashed` always has: an Unreal game that crashes under a user-mode exception ends it
now, where before beta.14 the crash went unseen; a leak report no longer ends one.
- The Overlay DLL self-disables after 3 faults in hook bodies (`17_HOOK_ENGINE` §Fault policy) and reports it.
- Every hooked session writes a breadcrumb file before injection; if the game process dies before the first frame record arrives, the next run is recorded as suspect.
- Every hooked session writes a breadcrumb file before injection~~; if the game process dies before the first frame record arrives, the next run is recorded as suspect~~ *(corrected 2026-10-04: no "suspect" mark exists; the breadcrumb is the `.partial` file, and an early death counts toward the two-within-60-s auto-disable above)*.
> **"Cautious mode" is deferred to v1.1 (`20_OPEN_QUESTIONS` §S12).** It was
> described as "hooks installed, overlay drawing disabled" — but **v1 draws no
+119 -2514
View File
File diff suppressed because it is too large. Load diff
+429 -1608
View File
File diff suppressed because it is too large. Load diff
+107
View File
@@ -0,0 +1,107 @@
# Games FrameLedger has been run with
*As of 2026-11-06 (0.1.0-beta.34). Built from a copy of the developer's own FrameLedger database and the repository's
measurement notes, and reviewed by the project's owner before it was published. It lists what happened on one machine;
it promises nothing about any other.*
*~~(Not re-read for 0.1.0-beta.11 or 0.1.0-beta.12 — noted 2026-10-04. Refreshing it needs a new copy of the database and
the owner's review; sessions since 2026-09-27, and the game-memory figures beta.12 adds, are not here.)~~ Refreshed
2026-11-06 from a copy of the database taken that day, and reviewed by the owner with the plan of 0.1.0-beta.34: the
sessions since 2026-09-27 are below, with the graphics memory a game used where it adds something.*
**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; the graphics
driver went from 32.0.16.1714 to 32.0.16.2114 over the sessions in the database. **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~~ **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
app and agent recorded them as a user would; ~~the database holds the sessions from 2026-09-22 on~~ the copy of
2026-11-06 holds the sessions from 2026-10-04 on — earlier ones went with the 2026-09-16 recovery and with library
entries and sessions removed since; a row citing the database before 2026-10-04 was read from the copy of 2026-09-27.
## Measured — hooked (Tier 1)
| Game | Engine | API | What was measured | When | Evidence |
|---|---|---|---|---|---|
| Cyberpunk 2077 | — | D3D12 | DLSS Balanced 1485×835 → 2560×1440, exact against its settings file; DLSS Frame Generation off ×1.00, ×3 (61.4 → 183.5 FPS), ×4 (58.7 → 234.1); FSR 3 + FSR frame generation ×2 (74.3 → 148.6); ray tracing *Yes* with path tracing on and *No* with it off, as set; on 2026-10-20, ×2, ×3 and ×4 chosen in the game's menu within one session read as separate states, ×4.0 at 63.8 → 255.3 FPS, with ray tracing and Ray Reconstruction *Yes* | 2026-08-15 → 10-20, about 26 runs | [spike-notes §8, §9, §11, §23](spike-notes.md), database |
| Dying Light: The Beast | — | D3D12 | DLSS Frame Generation ×4: Native 70.5 → Displayed 282.1 FPS, counted through DXGI; FSR + FSR frame generation ×2 (70.5 → 140.9); ray tracing *Yes* | 2026-09-04 → 09-06 | [spike-notes §9](spike-notes.md), [03_METRICS §Frame Generation](03_METRICS.md) |
| Hell Is Us | Unreal Engine 5.5.4 | D3D12 | DLSS Frame Generation ×4 (76.5 → 306.2); DLSS shown as *driver-reported* (it bypasses Streamline); FSR + FSR frame generation ×2 (85.7 → 171.4); XeSS frame generation shown as Presented FPS only; ray tracing *No* | 2026-09-03 → 09-16 | [spike-notes §8, §9](spike-notes.md) |
| Black Myth: Wukong | Unreal Engine 5.0.0 | D3D12 | DLSS Frame Generation ×4 (55.4 → 221.5); ray tracing *Yes* (16.2 % of frames in the app's session); a session that changed state showed its steady state (×4.1) instead of an average | 2026-08-20 → 09-16 | [spike-notes §9, §14](spike-notes.md) |
| Clair Obscur: Expedition 33 | Unreal Engine 5.4.4 | D3D12 | DLSS + Frame Generation ×4 (54.9 → 218.4) and ×2 (76.0 → 149.8); frame generation off read *none*, with DXGI agreeing; ray tracing *No*; the NVIDIA App's *Fixed ×6* read ×6.0 (81.8 → 490.9) on 2026-10-20 | 2026-09-04 → 10-20 | [spike-notes §9, §23](spike-notes.md), database |
| Rune Factory: Guardians of Azuma | Unreal Engine (version not in the executable) | D3D12 | DLSS Frame Generation ×4 (128.9 → 513.0); FSR frame generation compiled into the game counted ×2 but not named; ray tracing *No* (the game has none) | 2026-08-20 → 09-06 | [spike-notes §9](spike-notes.md) |
| Kingdom Come: Deliverance II | — | D3D12 | FSR (3.1 or 4) at 1505×847 → 2560×1440; frame generation *none* (the game ships none); ray tracing *No* | 2026-09-04 | [spike-notes §9](spike-notes.md) |
| Lies of P | Unreal Engine 4.27.2 | D3D12 | FSR 3 at 1506×848 → 2560×1440 with FSR frame generation ×2.04 (57.1 → 116.4) in the app; frame generation off read *none*; DLSS shown as *driver-reported*; ray tracing *No*; on 2026-10-19 and 10-20, FSR 3 at 1707×961 and at 1280×720 → 2560×1440 with FSR frame generation ×2.0 (54.6 → 109.6, 57.6 → 116.7) and no FSR quality mode — the game never asked for one while the hook was in | 2026-08-03 → 10-20 | [spike-notes §7, §9, §14, §22, §23](spike-notes.md), database |
| Onimusha: Way of the Sword (demo) | RE Engine | D3D12 | DLSS + DLSS Frame Generation: ×3.67 and ×3.93 with the capture tool, ×4.00 in the app's steady state (60 → 240 FPS), ×3.0 (60 → 180) in the app on 2026-09-22; ray tracing *Yes* | 2026-09-05 → 09-22 | [spike-notes §9, §14](spike-notes.md), database |
| Cronos: The New Dawn (demo) | Unreal Engine (version not in the executable) | D3D12 | DLSS with frame generation off (105 FPS, *none*); on ×2 (86.8 → 172.7), DLSS Frame Generation named; ray tracing *Yes* | 2026-09-06 → 09-16 | [spike-notes §9, §14](spike-notes.md) |
| Alan Wake 2 | — | D3D12 | Path tracing Ultra with DLSS and Ray Reconstruction: ray tracing *Yes* (96.8 % of frames), frame generation read ×1.00 (the game did not apply the setting that run). On 2026-09-04: DLSS with ray tracing *Yes* (99 % of frames), 92.5 FPS, frame generation *none* by count; then ray tracing off (*No*), DLSS, Presented 114.5 FPS. The quality preset was never read | 2026-08-04 → 09-04 | [spike-notes §8](spike-notes.md), run reports |
| SILENT HILL 2 | Unreal Engine 5.1 | D3D12 | DLSS Frame Generation identified, frames not counted (Presented 78 FPS) on 2026-09-25; then under the NVIDIA App's *Fixed ×6* ×6.0 (53.3 → 320.0) and under its *Dynamic, up to ×6* states ×2.0, ×3.0 and ×6.1; DLSS *driver-reported*; ray tracing *Yes* | 2026-09-25 → 10-20 | database, [spike-notes §22, §23](spike-notes.md) |
| DARK SOULS III | FromSoftware | D3D11 | Presented 59.8 FPS; no upscaler, frame generation or ray tracing loaded; then 34 sessions at the game's 60 FPS cap, the longest 6 h 12 min, four of them ended by the game crashing | 2026-09-03 → 10-25 | [spike-notes §9](spike-notes.md), database |
| Sekiro: Shadows Die Twice | FromSoftware | D3D11 | Presented 60 FPS (the game's cap): two sessions of 15 min and 2 h 18 min, then three more of up to 1 h 6 min | 2026-09-26 → 10-29 | database |
| Yu-Gi-Oh! Master Duel | Unity 6000.0 | D3D11 | Presented 239 FPS across six sessions (up to 5 h 25 min) | 2026-09-22 → 09-25 | database |
| GIRLS' FRONTLINE 2: EXILIUM | Unity 2019.4 | D3D11 | Presented 53–101 FPS; the last three sessions under the user-mode anti-cheat exception (NetEase Yidun), one of them 3 h 9 min, all ended normally; ten more under the exception, 28–72 FPS, the longest 2 h 9 min, all ended normally | 2026-09-21 → 10-20 | database, [HANDOFF](HANDOFF.md) |
| Aniimo | Unity 2022.3 | D3D12 | DLSS at 1707×960 → 2560×1440, frame generation *none* (×1.00, 205 FPS), ray tracing *No* — then blocked (below) | 2026-09-22 | database |
| AbyssMemory | Unreal Engine 4.26.1 | D3D11 | Presented 55 FPS, one short session | 2026-09-22 | database |
| Umamusume: Pretty Derby | Unity 2022.3 | D3D11 | Presented 37 FPS, one session | 2026-09-27 | database |
| 恋しかるべき (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)* |
| The Witcher 3: Wild Hunt — Remastered | — | D3D12 | DLSS 1707×960 → 2560×1440 with DLSS Frame Generation ×2.0 (118.8 → 237.4 FPS); ray tracing and Ray Reconstruction *Yes*; under the NVIDIA App's *Fixed ×6* it still presented ×2.0 — the setting is not the frames | 2026-10-04 → 10-20 | database, [spike-notes §23](spike-notes.md) |
| Phantom Blade Zero | Unreal Engine (version not in the executable) | D3D12 | DLSS *driver-reported*; DLSS Frame Generation under the NVIDIA App's *Dynamic* mode: up to ×6 held ×4.0 (59.5 → 235.6 FPS) and ×5.2 (44.3 → 231.2), up to ×3 held ×3.0 (58–76 → 175–227) for 75–94 % of each session longer than an hour; ray tracing *Yes*; thirteen sessions, the longest 6 h 29 min (5.26 million frames); up to 9.6 GB of graphics memory | 2026-11-01 → 11-05 | database, [spike-notes §26](spike-notes.md) |
| Hogwarts Legacy | Unreal Engine (version not in the executable) | D3D12 | With the game's *Neural Rendering* on, DLSS 5's runtime (`nvngx_dlssnr.dll` 310.9.16.0) loaded from the game's folder — the first game seen loading it; DLSS *driver-reported*; DLSS Frame Generation not counted (non-uniform, ×1.97 overall), Presented 140.2 FPS; ray tracing *Yes*, Ray Reconstruction *No* | 2026-11-06 | database, [spike-notes §26](spike-notes.md) |
| Valor Mortis (Xbox app) | Unreal Engine | D3D12 | DLSS Frame Generation ×6.0 (39.9 → 239.2 FPS), DLSS *driver-reported*, ray tracing *No*; recorded in attach mode | 2026-11-04 | database |
| inKONBINI (Xbox app) | Unity 6000.0 | D3D11 | Presented 205.9 FPS, one short session | 2026-11-03 | database |
| DARK SOULS II: Scholar of the First Sin | FromSoftware | D3D11 | The game's 60 FPS cap, nine sessions up to 5 h 29 min; one was unhooked by the safety check and recorded on | 2026-10-09 → 10-12 | database |
| Mithril | Unreal Engine (version not in the executable) | D3D12 | Presented 91.5–119.4 FPS, ray tracing *Yes*, four sessions up to 3 h 4 min | 2026-10-12 → 10-16 | database |
| KEEP IT ON HER | Unreal Engine 5.8 | D3D12 | Presented 59.5–108.8 FPS, ray tracing *Yes* | 2026-10-12 → 10-13 | database |
| WALTO | Unity 6000.3 | D3D12 | Presented 212.5 FPS over 2 h 41 min (2,057,022 frames) | 2026-10-08 | database |
| White Mask Mansion | Unity 6000.1 | D3D12 | Presented 286–309 FPS, five sessions | 2026-10-27 | database |
| LIMINAL: Within Demo | Unity 2022.3 | D3D11 | Presented 222.5–228.6 FPS | 2026-10-12 | database |
| Sleepytime Village | Unity 2021.3 | D3D11 | Presented 906–1,440 FPS (the game sets no cap) | 2026-10-25 → 10-26 | database |
| Scarlet Wolf | Unity 2021.3 | D3D11 | Presented 128.5 FPS | 2026-10-15 | database |
| March Out! Playtest | Unity 2022.3 | D3D11 | Presented 118.2 FPS | 2026-10-08 | database |
| A Space for the Unbound – Prologue (GOG) | Unity 2019.4 | D3D11 | Presented 61.0 FPS, started by FrameLedger | 2026-10-20 | 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. *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 | Two sessions played with hooking switched off | 2026-09-25, 10-07 | 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 |
| Bound Between Desks | Two sessions with hooking switched off (a Ren'Py 8.5 game) | 2026-10-15 → 10-20 | database |
| Phantom Blade Zero | Three sessions after a game update changed its executable on 2026-11-04, until hooking was consented to again on 11-05; one refused because a module list came back incomplete | 2026-11-04 → 11-05 | database |
| The Witcher 3: Wild Hunt — Remastered | Three sessions before hooking was consented to | 2026-10-13 → 10-20 | database |
| Mithril | Two sessions before hooking was consented to | 2026-10-16 | database |
| Hogwarts Legacy | One session with hooking switched off; Windows logged a crash of the game | 2026-11-06 | database |
| Valor Mortis, WALTO, Scarlet Wolf, Lies of P, A Space for the Unbound – Prologue | One session each with hooking switched off | 2026-10-08 → 11-04 | database |
## Refused by the anti-cheat guard
| Game | What was found | When | Evidence |
|---|---|---|---|
| ELDEN RING | Easy Anti-Cheat: its folder, and a process Windows would not let FrameLedger open. Nothing was ever injected; eight sessions recorded without measurement | 2026-09-21 → 09-27 | [CHANGELOG](../CHANGELOG.md), database |
| GIRLS' FRONTLINE 2: EXILIUM | NetEase Yidun (`NEP2.dll`, user mode) — turned hooking off after it had been measured; measured again since 2026-09-26 under the user-mode exception its owner made | 2026-09-25 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
| 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)*; two sessions recorded without measurement on 2026-10-31 | 2026-10-12 → 10-31 | [spike-notes §19](spike-notes.md), database |
| Arknights: Endfield | Anti-Cheat Expert's folder (`AntiCheatExpert`) beside the game; one session recorded without measurement | 2026-10-31 | database |
| Stella Sora | Anti-Cheat Expert's folder (`AntiCheatExpert`); three sessions recorded without measurement | 2026-10-30 → 10-31 | database |
| Umamusume: Pretty Derby | CrackProof, on FrameLedger's title list since beta.11 (Steam 3224770) — measured before the list named it (above) | 2026-10-03 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.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).
## Engine version read from the executable only
The Unreal Engine version (beta.10) was checked against ten installed Unreal games without running them: Hell Is Us
5.5.4, Black Myth: Wukong 5.0.0, Clair Obscur: Expedition 33 5.4.4, Lies of P 4.27.2, SILENT HILL 2 5.1, UMIGARI 5.5.4,
AbyssMemory 4.26.1, **Martha Is Dead 4.27.0**; Cronos (demo) and Rune Factory name no version in their executables and
read *not found*. ([spike-notes §15](spike-notes.md), [05_DETECTION §Engine version](05_DETECTION.md)) Read since on the games
in the database: KEEP IT ON HER 5.8 and Wuthering Waves 4.26.2; Phantom Blade Zero, Hogwarts Legacy and Mithril name no
version in their executables, and an Xbox game's executable cannot be read outside its package (Valor Mortis).
+95
View File
@@ -0,0 +1,95 @@
# FrameLedger developer documentation
This folder is for people who build, change or review FrameLedger. **If you only want to use it, read the
[user guide](../guide/README.md) instead** — it is also in the app, under Help ▸ User guide.
## Where to start
| You want to… | Read |
|---|---|
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (~~D1…D46~~ D1 onward — *corrected 2026-10-07: the range grows with every train*) and the traps that each cost a cycle. It carries no status on purpose |
| Find your way around first | The [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages (source: [`../wiki/`](../wiki/), beta.17) — a short page per part, each linking here |
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE), [`../CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) *(it and `SECURITY.md`, below, added 2026-11-09: the index named neither)* |
**Status lives in four places, and nowhere else** — check a status claim against the code before you plan on it:
| Question | File |
|---|---|
| What is unresolved, and what does it block? | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) |
| What was measured, on what machine? | [`spike-notes.md`](spike-notes.md) |
| Which phase is where? | [`15_ROADMAP.md`](15_ROADMAP.md) |
| What landed, in which release? | [`../CHANGELOG.md`](../CHANGELOG.md) |
What the software promises users is the accuracy block in [`../legal/ACCURACY.md`](../legal/ACCURACY.md), copied
verbatim into the README and the Disclaimer and bound to its source by `tools/accuracy-check.ps1`.
## Reading order
1. [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) — the guard, the refusal list, what will not be built. It
constrains everything else.
2. [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) — processes, the injection flow, lifecycles, the ADRs.
3. [`02_SPEC.md`](02_SPEC.md) — the FR / NFR ids used everywhere.
4. [`03_METRICS.md`](03_METRICS.md) — the metric math; the source of truth for every number shown.
5. [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) — the C++ hook layer inside the game.
6. [`04_CAPTURE.md`](04_CAPTURE.md) — capture orchestration on the Agent's side.
7. [`05_DETECTION.md`](05_DETECTION.md) — engine, upscaler, frame-generation and ray-tracing facts.
8. [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) — layered telemetry, the game process's memory, vendor-SDK licence rules.
9. [`06_DATA_MODEL.md`](06_DATA_MODEL.md) · [`07_IPC.md`](07_IPC.md) · [`08_UI.md`](08_UI.md) ·
[`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md)
10. The rest: [`09_I18N.md`](09_I18N.md), [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md),
[`11_UPDATER.md`](11_UPDATER.md), [`12_BUILD.md`](12_BUILD.md), [`13_CI_CD.md`](13_CI_CD.md),
[`14_TESTING.md`](14_TESTING.md), [`15_ROADMAP.md`](15_ROADMAP.md).
**Before you write native or capture code, read [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md):** its S-series items
are safety items, and something listed there as unresolved should not be built the way an older document describes it.
## Every document, in one line
| Document | What it is for |
|---|---|
| [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) | The processes (App, Agent, Overlay, Vulkan layer), how injection flows, the architecture decisions |
| [`02_SPEC.md`](02_SPEC.md) | Functional and non-functional requirements, by id |
| [`03_METRICS.md`](03_METRICS.md) | How every number is computed: frame times, lows, stutter, frame generation, display mode, the game's memory, sensor statistics, the export schema |
| [`04_CAPTURE.md`](04_CAPTURE.md) | The Agent's capture loop, the tiers, finalizing and recovery, the threading model |
| [`05_DETECTION.md`](05_DETECTION.md) | Detecting engines, platforms and capabilities; the detection rules |
| [`06_DATA_MODEL.md`](06_DATA_MODEL.md) | The SQLite schema, every migration, who writes what, retention |
| [`07_IPC.md`](07_IPC.md) | The shared-memory ring between the game and the Agent, and the named pipe between the Agent and the App |
| [`08_UI.md`](08_UI.md) | Every screen of the App, as specified and as built |
| [`09_I18N.md`](09_I18N.md) | English / Vietnamese / Japanese strings, the glossary, the safety-string review rule |
| [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md) | Logs in every process, the bug-report bundle, redaction |
| [`11_UPDATER.md`](11_UPDATER.md) | Velopack updates from GitHub Releases, and when an update may apply |
| [`12_BUILD.md`](12_BUILD.md) | The toolchain, the build, the quality gate step by step, publishing and packaging |
| [`13_CI_CD.md`](13_CI_CD.md) | The CI and release workflows |
| [`14_TESTING.md`](14_TESTING.md) | The test strategy, hook overhead, the hardware matrix |
| [`15_ROADMAP.md`](15_ROADMAP.md) | The phases and where each stands |
| [`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md) | WPF UI (lepoco) rules, theming, rendered documents, gotchas |
| [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) | The hooks inside the game: inventory, fault policy, the ring writer, Vulkan |
| [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) | Telemetry layers (DXGI/PDH, LibreHardwareMonitor, NVAPI), the game process's memory, licences |
| [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) | The anti-cheat guard, what a finding does, the user-mode exception, what will never be built |
| [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) | Every unresolved question, defect and measurement, with its status marker |
| [`HANDOFF.md`](HANDOFF.md) | Sequencing, the 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 |
| [`vendor-exports.json`](vendor-exports.json) | The vendor DLL exports the hooks are allowed to bind, checked by `tools/vendor-exports` |
## Beside this folder
- [`../guide/`](../guide/README.md) — the user guide (players, English); since beta.17 (D54) also the wiki's End-user part.
- [`../wiki/`](../wiki/Home.md) — the wiki's own pages: Home, the sidebar, the developer pages (D53). `wiki.yml`
publishes them with the guide to the Wiki tab when a release is made; `build.ps1`'s `wiki-check` holds every link.
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
texts, the trademark note.
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
- [`../ACCESSIBILITY.md`](../ACCESSIBILITY.md) — the accessibility statement (beta.35, D88): the goal, what works with the
keyboard, a screen reader and contrast themes, the known limits and how a barrier is reported; shown in the App under
Help ▸ Accessibility. Its checks are [`08_UI.md`](08_UI.md) §Accessibility.
- [`../SECURITY.md`](../SECURITY.md) — the private route for a vulnerability, and why the guard has no override.
- [`../rules/detection-rules.json`](../rules/detection-rules.json) — engine, platform and capability signatures and the
anti-cheat blocklist, validated by `tools/rules-validate.ps1`.
+40
View File
@@ -0,0 +1,40 @@
<!-- The first alpha's notes (D73-D76), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
## [0.1.0-alpha.1] - 2026-10-31
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK.** This is an **alpha**: the source of `0.1.0-beta.32` built on
> **.NET 11 Release Candidate 3** (SDK `11.0.100-rc.3.26522.148`, runtime `11.0.0-rc.3.26522.148`), a version of .NET
> Microsoft has not finished, with the C# 15 compiler. It has not been tested the way a beta is, and it can crash, record
> wrongly or fail to update in ways no beta has. **If you want results you can rely on, use the beta.** Before it runs it
> shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.0), which you must accept, with its own box to tick.
**The first alpha.** What it is and how to go back: the user guide's *Alpha builds* page
(`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
**Installing it:** download `FrameLedger.App-alpha-Setup.exe` below, verify its hash against `SHA256SUMS.txt`, run it,
and let it replace the FrameLedger already installed. **It replaces the beta** — one of them is installed at a time — and
uses the same data folder: before it first opens your database it copies it to
`%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.1.db`, and it does not open the database if the copy cannot
be made. It never arrives as an update to a beta, and it updates only to newer alphas.
**Going back:** install the newest beta's `FrameLedger.App-win-Setup.exe` over it; your database stays where it is, with
any sessions the alpha recorded.
**Windows and your PC:** Microsoft supports .NET 11 on Windows 11 24H2 and later, and on Windows 10 only in its LTSC and
IoT editions; on Windows 10 22H2 Home or Pro this alpha may run, but nobody supports it there. It needs a processor with
SSE4.2 and POPCNT. .NET 11 RC3 is supported by Microsoft until .NET 11 ships (10 November 2026); the next alpha moves to
the final release.
### What differs from 0.1.0-beta.32
- **The runtime and the compiler**: .NET 11 RC3 in place of .NET 10.0.14, self-contained as always; C# 15. The source
uses no C# 15 syntax and no preview feature (owner decision D76) — what .NET 11's SDK asked of it was taken on main in
forms .NET 10 also compiles (`docs/spike-notes/24-dotnet11-probe.md`), so a beta and this alpha are the same code.
- **Three libraries serviced with the runtime**: `Microsoft.Extensions.Hosting`, `System.Diagnostics.EventLog` and
`Microsoft.Data.Sqlite` `11.0.0-rc.3.26522.148`. The database engine is SQLite 3.53.4 (`SQLitePCLRaw` 3.0.5, which
`Microsoft.Data.Sqlite` 11 declares), where the beta's is 3.53.3; the database file is the same format. Nine
`Microsoft.Extensions.*` libraries are now part of the runtime and no longer ship beside it.
- **What .NET 11 itself changes**: a failure in the capture agent's own background work ends the agent with a crash report
where the beta's exits quietly (`IHost` now reports it); the runtime's ReadyToRun code targets processors with AVX2, so
an older processor starts the program a little slower.
- **The part of FrameLedger loaded into a game is the beta's**, built from the same C++ source: it does not use .NET.
+33
View File
@@ -0,0 +1,33 @@
<!-- The second alpha's notes (D73, D82), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
## [0.1.0-alpha.2] - 2026-11-03
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK.** This is an **alpha**: the source of `0.1.0-beta.33` built on
> **.NET 11 Release Candidate 3** (SDK `11.0.100-rc.3.26522.148`, runtime `11.0.0-rc.3.26522.148`), a version of .NET
> Microsoft has not finished, with the C# 15 compiler. It has not been tested the way a beta is, and it can crash, record
> wrongly or fail to update in ways no beta has. **If you want results you can rely on, use the beta.** Before it runs it
> shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.0), which you must accept, with its own box to tick.
**The second alpha: `0.1.0-beta.33` on .NET 11 RC3** — games from the Xbox app and the Microsoft Store (the beta's
notes, `docs/changelog/0.1.0-beta.33.md`, say what that brings). What an alpha is and how to go back: the user guide's
*Alpha builds* page (`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
**Updating from `0.1.0-alpha.1`:** Help ▸ Check for updates, then *Restart to update* with no game running — an alpha
updates only to newer alphas. Before it first opens your database it copies it to
`%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.2.db` (the newest three copies are kept). The terms window
shows the **Privacy Policy 2.13** once and, as every time an alpha's terms window opens, waits for the Alpha notice's box
to be ticked again; the notice itself stays 1.0. The ledger stays at schema 21; the detection rules move to `2026.11.1`.
**Installing it over a beta:** download `FrameLedger.App-alpha-Setup.exe` below, verify its hash against
`SHA256SUMS.txt`, and let it replace the FrameLedger already installed; the Alpha notice is shown first. **Going back:**
install the newest beta's `FrameLedger.App-win-Setup.exe` over it; your database stays where it is.
**Windows and your PC:** as for the first alpha — Microsoft supports .NET 11 on Windows 11 24H2 and later, and on Windows
10 only in its LTSC and IoT editions; it needs a processor with SSE4.2 and POPCNT. .NET 11 RC3 is supported until .NET 11
ships (10 November 2026); the next alpha moves to the final release.
### What differs from 0.1.0-beta.33
The same as `0.1.0-alpha.1` differed from `0.1.0-beta.32` (`docs/changelog/0.1.0-alpha.1.md`): the runtime and the
compiler, the three libraries serviced with the runtime, what .NET 11 itself changes — and the part of FrameLedger loaded
into a game is the beta's.
+36
View File
@@ -0,0 +1,36 @@
<!-- The third alpha's notes (D73, D87), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
## [0.1.0-alpha.3] - 2026-11-06
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK.** This is an **alpha**: the source of `0.1.0-beta.34` built on
> **.NET 11 Release Candidate 3** (SDK `11.0.100-rc.3.26522.148`, runtime `11.0.0-rc.3.26522.148`), a version of .NET
> Microsoft has not finished, with the C# 15 compiler. It has not been tested the way a beta is, and it can crash, record
> wrongly or fail to update in ways no beta has. **If you want results you can rely on, use the beta.** Before it runs it
> shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.0), which you must accept, with its own box to tick.
**The third alpha: `0.1.0-beta.34` on .NET 11 RC3** — DLSS 5 and DLSS 4.5 named from what the game and the driver did,
filters on Games and Compare, and a Games page that opens at once (the beta's notes, `docs/changelog/0.1.0-beta.34.md`,
say what that brings). What an alpha is and how to go back: the user guide's *Alpha builds* page
(`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
**Updating from `0.1.0-alpha.2`:** Help ▸ Check for updates, then *Restart to update* with no game running — an alpha
updates only to newer alphas. Before it first opens your database it copies it to
`%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.3.db` (the newest three copies are kept). The terms window
shows the **Disclaimer 2.13** and the **Privacy Policy 2.14** once and, as every time an alpha's terms window opens, waits
for the Alpha notice's box to be ticked again; the notice itself stays 1.0. The ledger moves to schema 22, which an
alpha.2 cannot open (the copy is the database as alpha.2 left it; going back is to the newest beta, which opens it); the
detection rules move to `2026.11.2`.
**Installing it over a beta:** download `FrameLedger.App-alpha-Setup.exe` below, verify its hash against
`SHA256SUMS.txt`, and let it replace the FrameLedger already installed; the Alpha notice is shown first. **Going back:**
install the newest beta's `FrameLedger.App-win-Setup.exe` over it; your database stays where it is.
**Windows and your PC:** as for the first alpha — Microsoft supports .NET 11 on Windows 11 24H2 and later, and on Windows
10 only in its LTSC and IoT editions; it needs a processor with SSE4.2 and POPCNT. .NET 11 RC3 is supported until .NET 11
ships (10 November 2026); the next alpha moves to the final release.
### What differs from 0.1.0-beta.34
The same as `0.1.0-alpha.1` differed from `0.1.0-beta.32` (`docs/changelog/0.1.0-alpha.1.md`): the runtime and the
compiler, the three libraries serviced with the runtime, what .NET 11 itself changes — and the part of FrameLedger loaded
into a game is the beta's.
+59
View File
@@ -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.
+95
View File
@@ -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.
+94
View File
@@ -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.
+153
View File
@@ -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`.
+49
View File
@@ -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.
+117
View File
@@ -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.
+49
View File
@@ -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.
+17
View File
@@ -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.
+37
View File
@@ -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).
+48
View File
@@ -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`).
+53
View File
@@ -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.
+114
View File
@@ -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.
+19
View File
@@ -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.
+64
View File
@@ -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).
+19
View File
@@ -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).
+55
View File
@@ -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`).
+99
View File
@@ -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.
+27
View File
@@ -0,0 +1,27 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.25 was cut, 2026-10-19 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.25] - 2026-10-19
**The twenty-fifth pre-release: FSR's quality mode.** The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.24`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
no game is read again: the detection rules (`2026.10.4`) are beta.24's. FSR's quality mode is recorded for sessions
from now on; a session recorded before keeps what it had.
### Added
- **FSR's quality mode** (owner decision D65, planned for beta.24 and moved to this release). For a game that runs FSR
through AMD's FidelityFX libraries, the summary, the Sessions tab, the game page and the live card name the mode —
*FSR 3 Quality*, *FSR Performance*, *FSR Native AA* — when the game asked AMD's library what render size that mode
gives and then rendered at that size. A game at a dynamic resolution, one that sizes its frames without asking, and
one FrameLedger joined after it asked show none. FrameLedger reads one more call in those libraries (`ffxQuery`,
beside the `ffxDispatch` it already reads): the size or ratio AMD's library answered, nothing else — about 8 ns per
upscaled frame. The CSV export's `# quality_mode:` carries it (`native_aa (game)` for Native AA).
`legal/ACCURACY.md`'s *Quality mode* bullet gains its FSR clause, in the words approved with the beta.24 plan; the
Disclaimer stays 2.11, as it did for the accuracy statement's additions in beta.19 and beta.20. Checked with AMD's
interface on the test program; a real game is owner-only item 21. Developers: the hook has its own family bit
(`FL_HOOK_UPSCALER_QUALITY`, bit 11 of `hooksInstalledMask`), the byte is `0x10 + FfxApiUpscaleQualityMode`, the
harness asks with `--ffx-query sizes|ratios`, and `Domain.Metrics.QualityByte` is the one rule a session, its
segments and the live card read.
+35
View File
@@ -0,0 +1,35 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.26 was cut, 2026-10-19 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.26] - 2026-10-19
**The twenty-sixth pre-release: a frame-generation state no frame generation produces, fixed.** The same unsigned
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.25`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
no game is read again: the detection rules (`2026.10.4`) are beta.25's. Sessions you already recorded read by the new
rule at once — nothing in them is rewritten.
### Changed
- **SonarCloud's last six findings on `main`, triaged** (developers only; D67's follow-up). After the owner's marking,
the analysis of 0.1.0-beta.25 left six open: `docs/13_CI_CD.md` §SonarCloud lists them with a verdict and the comment
to paste — one to accept as the table already said, four false positives (exact floating-point comparisons that are
exact on purpose), and one fixed here: `wiki.yml` publishes only after a Release run started by a tag pushed to this
repository, now checked by the repository's name in its condition as well as by the run's trigger.
### Fixed
- **A frame-generation "state" of ×1336.0.** The owner's Silent Hill 2 session (0.1.0-beta.25, the NVIDIA App's
*Dynamic* multi frame generation) listed a ×1336.0 state — 0.20 → 267.20 FPS for ten seconds — under *Frame
generation in this session*, and the DLSS line cited it: *DLSS 4.5 (a ×1336.0 frame-generation state)*. Those ten
seconds — the game compiling its shaders at start — were presented with one application frame counted per
five-second window, and a window needed eight presents but only one counted frame to be read. A window now needs eight
application frames and a ratio no higher than ×8 — more than any frame generation produces (DLSS 4.5's ×6 is the
most); every other window is *Not classified*, and the steady state reads the same windows. A session-wide or live ratio that held above ×8 is
refused and says why (*the ratio is beyond what any frame generation produces*), in en/vi/ja. Sessions already
recorded are read by the same rule, so that session now lists ×2.0, ×3.0, ×6.1, no frame generation and 30 seconds
not classified, and its DLSS line cites ×6.1. The owner's runs of beta.24 and beta.25 are recorded in
`docs/spike-notes/22-owner-runs-2026-10-19.md`: the *Dynamic* settings line matched the NVIDIA App's own words, the
override's two library names are written down, and Lies of P read no FSR mode with the query hooked — the title
rounds its own render size and asked nothing the hook kept.
+56
View File
@@ -0,0 +1,56 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.27 was cut, 2026-10-20 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.27] - 2026-10-20
**The twenty-seventh pre-release: the owner's eight sessions of 2026-10-20, checked — six faults fixed, and *Start
directly* says what a Steam game may do.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
*More info → Run anyway*.
**Updating from `0.1.0-beta.26`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
no game is read again: the detection rules (`2026.10.4`) are beta.26's. Sessions you already recorded read the
frame-generation fix at once; the driver's DLSS report, the display sizes and the game Steam starts are recorded from
this version on — nothing already stored is rewritten.
### Changed
- **Play ▸ *Start directly* says what a Steam game may do.** Some Steam games hand themselves to Steam when
FrameLedger starts them — Lies of P closes within seconds and Steam starts it again. Starting a game Steam installed,
the notice now says it may hand itself to Steam first and that the game Steam then starts is recorded; the *Start
directly* tooltip and Settings ▸ Games ▸ *Play button* say so too, adding that a few will not start outside Steam at
all. Steam games keep *Start directly*: three of the five started directly on 2026-10-20 ran and were measured from
their first frame, and a Vulkan game is measured only when FrameLedger starts it. In en/vi/ja (ja marked for review).
### Fixed
- **A frame-generation "state" of ×2.52.** The owner's Silent Hill 2 session under the NVIDIA App's *Dynamic* multi
frame generation listed ×2.52 for 13 seconds beside ×2.0 and ×3.0: the five-second windows in which the multiplier
stepped from ×2 to ×3 read in between, and three of them formed a state nobody held. Every frame generation that
ships multiplies by a whole number, so a window now counts toward a state only within 10 % of one; the others are
*Not classified*. Sessions already recorded are read by the same rule: that session lists ×2.0, ×3.0, no frame
generation and 7.36 % not classified. The owner's runs of 2026-10-20 are recorded in
`docs/spike-notes/23-owner-runs-2026-10-20.md`.
- **The NVIDIA driver's DLSS report was lost from every stored session.** FrameLedger asked the driver one last time
after the game had closed, and that answer — which no longer says DLSS ran — replaced the ones read while the game
ran. So no session said *DLSS (driver-reported)* where no hook saw DLSS, and none named the NVIDIA App's quality mode
on such a game: Clair Obscur: Expedition 33 under the App's override read *Upscaler not identified*. The driver is no
longer asked once the game has closed, and once it reports that DLSS ran, the session keeps it. Sessions recorded
before keep what they stored.
- **Play ▸ *Start directly* recorded nothing of a game that hands itself to Steam.** Lies of P, started directly, closes
within seconds and Steam starts it again; the game Steam started was turned away while the first session ended and
never recorded. It is now recorded once that session ends, as a game started again already was. Each such start
still counts toward the two early exits that turn hooking off for a game, so Limitations ▸ Play advises starting such
a game through its store.
- **Opening a session's summary twice opened two windows.** The open window comes forward instead, restored if
minimised.
- **No window or monitor size for a game in exclusive full-screen.** A game leaving exclusive full-screen closes its
window a moment before its swap chain says so, and those last samples replaced the sizes: two Lies of P and three
Dark Souls III sessions show none. The sizes are now the last ones the mode saw.
- **A DLSS line that said only "DLSS"**, under a header that already did, is no longer shown: the NVIDIA App's override
loads its libraries under names FrameLedger does not list (The Witcher 3), and the *Loaded:* line prints them.
- **Two integration tests that failed under load** (developers only). The guard reads every process above the test
harness too, the test host among them, and under a full `build.ps1 check` the test host is still starting its other
test classes: a module it released while the guard read its list refused the injection (`ModuleScanFailed`, and
`ProcessUnreadable` on 2026-10-19). The drain suite asks the guard again on those two reasons, four times at most;
the pause case, which once read the writer still starting, waits for it to be ready; and every injection test waits
for the harness's own "presenting" line instead of 800 ms (`tests/Shared/HarnessReady.cs`).
+26
View File
@@ -0,0 +1,26 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.28 was cut, 2026-10-20 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.28] - 2026-10-20
**The twenty-eighth pre-release: the Dashboard shows every game being recorded.** The same unsigned installer: verify
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.27`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
no game is read again: the detection rules (`2026.10.4`) are beta.27's. Only the App changes; the capture agent and
what it records are beta.27's.
### Added
- **The Dashboard shows every game being recorded.** Two games running at once are two sessions, and until now the
Dashboard's *Live capture* card showed one of them — a measured one first — while the other appeared only as
*Running sessions: 2*. Each running game now has its own card, side by side, with its own frame rate, settings,
elapsed time and memory, or why it is recorded without being measured; measured games come first, and the title
says how many games are being recorded (*2 games recording*). In en/vi/ja (ja marked for review).
### Fixed
- **A native injection test that failed under load** (developers only). Two `fl_guard_test` cases — the OpenGL hook,
and a swap chain on a real window — waited 4 seconds for twenty frames, and on a loaded CI runner (the suite took
115 s) the OpenGL hook, installed, had recorded none. They now wait up to 12 seconds, the harness presenting for 16,
and a failure says the writer's state.
+55
View File
@@ -0,0 +1,55 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.29 was cut, 2026-10-25 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.29] - 2026-10-25
**The twenty-ninth pre-release: updated libraries, and SonarCloud analysing every change from CI.** The same unsigned
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.28`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
no game is read again: the detection rules (`2026.10.4`) are beta.28's. What you see and what is recorded are
beta.28's; the libraries under them are newer.
### Changed
- **SonarCloud analyses the repository from CI** (developers only; owner decision D68). The owner turned SonarCloud's
Automatic Analysis off and set the `SONAR_TOKEN` secret; `ci.yml`'s new `sonarcloud` job runs the SonarScanner for
.NET 12.0.0 (a local tool, `.config/dotnet-tools.json`) after `check`, in a build of its own — the scanner turns
warnings-as-errors off in the build it instruments, so it cannot wrap the gate's — with the gate's own test coverage
(`build.ps1` now writes OpenCover beside Cobertura; the C# only, since the PowerShell tools and the native code have
no coverage report) and CMake's compilation database for the C++, which
`FrameLedger.Infrastructure.csproj` names to the scanner only in that build. `SonarQube.Analysis.xml` replaces
`.sonarcloud.properties`. The job is advisory, not a required check, and waits for the quality gate, so a failed gate
is a red job (`docs/13_CI_CD.md` §SonarCloud).
- **Dependabot, the NuGet audit and CodeQL** (developers only). Dependabot's version updates wait seven days after a
release (security updates do not), and the actions' minor and patch releases come as one pull request a week. The
NuGet audit is written down in `Directory.Build.props` (the whole graph, every severity — the SDK's defaults for
net10.0), so a later SDK cannot move it. CodeQL also reads the workflows (`analyze (actions, none)`, not required),
and a new push to a pull request replaces its CodeQL run.
- **The libraries Dependabot never updated.** Every NuGet pull request Dependabot opened here updated analyzers only,
so the libraries fell behind with nothing to say so (`docs/13_CI_CD.md` §Dependabot and the NuGet audit). Updated by
hand, each release at least seven days old (the cooldown Dependabot now keeps): the October .NET servicing release of
`Microsoft.Extensions.Hosting`, `Microsoft.Data.Sqlite` and `System.Diagnostics.EventLog` (10.0.13) and `Dapper`
2.1.89, which ship; the CsWin32 source generator 0.3.363, which writes the Win32 declarations the shipped code calls;
for developers, the test SDK 18.11.0 and xunit 4.0.2. The licence texts under `legal/licenses/nuget/` name the new
versions; no licence changed. Not taken: Markdig 1.5.0 (published the day before, and its licence is a reviewed copy
at the packaged commit), Velopack 1.2.161 (the updater itself — a change to how updates install is the owner's to
try), FluentAssertions 8 (its licence) and `coverlet.collector` 10.1.0: the tracker it adds to each assembly it
instruments declares a constant whose value reflection cannot read ("Literal value was not found"), and
`NoSecondMatcherTests` reads every string constant in three of ours. The first CI run blamed CsWin32 for it; with
coverage collected locally the failure followed coverlet, and 10.0.1 passes (`Directory.Packages.props` says so
beside it).
### Fixed
- **The 34 C++ issues of `main`'s first SonarCloud analysis from CI** (developers only). Read with MSVC's real flags,
the native code showed issues Automatic Analysis had not, on older lines; SonarCloud dates each by blame, and the
two on lines changed since its new code began failed `main`'s gate on reliability. One was a defect in a test tool: `hook-harness --opengl` or `--vulkan` beside
a D3D11 mode — or `--opengl` alone, which ran the default probes — called through a null swapchain; every mode that
drives the D3D11 swapchain now asks first. The rest: `NvU32` printed with `%u` in `fl-probe-nvapi` (`%lu`; its
machine line reads the same), a union and a `strlen` in the guard's tests, a `LARGE_INTEGER` read through
`QuadPart` after `{}` had made its other member the active one (the Overlay's clock epoch, and the Vulkan layer's
once-per-process enable-list read — now initialised through `QuadPart`), two terminators written after a read whose
bound is now tested first, and five marked `// NOSONAR` with the reason above each. The Overlay compiles to the same
instructions: built from either side, in one folder with one build id, its `.text` is byte-identical
(`docs/13_CI_CD.md` §SonarCloud has the table).
+140
View File
@@ -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.
+53
View File
@@ -0,0 +1,53 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.30 was cut, 2026-10-26 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.30] - 2026-10-26
**The thirtieth pre-release: Enter in the consent dialog, readable hardware-change markers, updated libraries, and the
.NET 10.0.14 runtime.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run
anyway*.
**Updating from `0.1.0-beta.29`:** Help ▸ Check for updates, then *Restart to update* with no game running — a download
of about 5 MB. Nothing is shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger
stays at schema 21, and no game is read again: the detection rules (`2026.10.4`) are beta.29's. This update is installed
by beta.29's updater; the next one is the first that this release's updater installs.
### Changed
- **Updated libraries, and a version conflict removed** (owner decision D71 for the updater). Velopack, the installer
and updater, 1.2.0 → 1.2.161 with its packing tool: the update from beta.29 to this release is still installed by
beta.29's updater, and the next one is the first this one installs. Markdig, which draws the documents the App shows,
1.4.0 → 1.4.2 (parser fixes; its licence text is unchanged). The database's `SQLitePCLRaw` is again the version
`Microsoft.Data.Sqlite` declares, 2.1.13: a pin kept since August for a security issue fixed since had put it on
another major version with nothing to say so; the SQLite engine is 3.53.3 (it was 3.53.4). Not taken, each with its
reason in `docs/13_CI_CD.md` §Dependabot and the NuGet audit: the .NET 10.0.14 packages (a day old), Markdig 1.5.0,
CsWin32 0.3.366 and 0.3.367, `coverlet.collector` 10.1.0 and FluentAssertions 8.
### Fixed
- **Enter in the consent dialog declined, and the hooking switch then showed on beside "off"** (owner decision D69).
The dialog's default button was *Keep hooking off* — the rule was "Enter never enables" — and WPF UI's template sends
Enter to the default button, so typing `I ACCEPT THE INJECTION RISK` and pressing Enter kept hooking off without a
word. Asked with that, the owner chose: Enter enables once the phrase is typed exactly, as a click on *Enable hooking*
does, and does nothing before it; Esc and *Keep hooking off* still decline. The typed phrase is still the gate — the
button Enter reaches stays disabled and hidden until the phrase matches — and no text of the dialog changed
(`consent-dialog/1`). The game page's two switches, Hooking and Recording, now read their row again after every
click: a click that changed nothing — the dialog declined, a refusal, no agent running — left the switch on while the
text beside it said off, and the next click asked to enable again (`docs/19_SAFETY_AND_ANTICHEAT.md` §User-facing
consent, `docs/08_UI.md` §Keyboard).
- **A hardware change on a game's charts was cut off and hard to read** (owner decision D70). *Sessions at a glance* and
the *Trend* marked each day the GPU driver, GPU, CPU, display or Windows changed with a dashed line labelled with the
change itself — white on orange, its top cut off by the chart's edge, and a day with several changes showed one at
most. Each such day now carries a number — 1 for the oldest, the same on both charts — in a band kept above the chart,
dark on the orange in both themes, never cut off and never over another: badges too close for their lines stand aside,
joined to them, and a run that still cannot stand side by side is one badge (*3–5*). The list under each chart gives
each number's day and every change in full, and pointing at a line or a badge shows the same text. In en/vi/ja (ja
marked for review). A click on *Sessions at a glance* now reads the pointer at the monitor's own scale
(`docs/08_UI.md` §Games, §DPI).
### Security
- **The .NET runtime inside is 10.0.14**, Microsoft's out-of-band security release of 2026-10-25 (CVE-2026-111497, a
Brotli decompression flaw; it also completes the SocketAsyncEventArgs fix, CVE-2026-70197, that 10.0.13 left
incomplete). FrameLedger is self-contained, so
it ships the runtime of the SDK that builds it: beta.29 carried 10.0.13; this release was built with SDK 10.0.403 and
carries 10.0.14 — read from the published package's `FrameLedger.deps.json` in the release rehearsal.
+24
View File
@@ -0,0 +1,24 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.31 was cut, 2026-10-26 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.31] - 2026-10-26
**The thirty-first pre-release: the remaining library updates.** The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.30`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
no game is read again: the detection rules (`2026.10.4`) are beta.30's. This is the first update that beta.30's updater
(Velopack 1.2.161) installs; if it downloads the whole package rather than a few megabytes, or the App does not come back,
the installer on this page puts it right. What you see and what is recorded are beta.30's; the libraries under them are
newer.
### Changed
- **The remaining library updates** (the owner's request after beta.30, owner decision D72 — inside the seven-day wait
the project otherwise keeps). The .NET 10.0.14 servicing packages the App and the agent use
(`Microsoft.Extensions.Hosting`, `Microsoft.Data.Sqlite`, `System.Diagnostics.EventLog`; beta.30 already carried the
10.0.14 runtime) and Markdig 1.5.0 (its licence text unchanged); for developers, the CsWin32 generator 0.3.367,
Meziantou.Analyzer 3.0.317, `coverlet.collector` 10.1.0 — a test that reads every constant of three assemblies now
leaves out the types the coverage tool adds to them — and Catch2 3.16.1 for the native tests. The SQLite engine stays
3.53.3 (`SQLitePCLRaw` 2.1.13, which `Microsoft.Data.Sqlite` 10.0.14 still declares). Still not taken: FluentAssertions
8, for its licence (`docs/13_CI_CD.md` §Dependabot and the NuGet audit).
+45
View File
@@ -0,0 +1,45 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.32 was cut, 2026-10-31 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.32] - 2026-10-31
**The thirty-second pre-release: the alpha line's groundwork.** An *alpha* — the same program built on a version of .NET
Microsoft has not finished, .NET 11 first — is published beside the betas from now on, and this beta carries what that
needs; nothing in a beta's measuring changed. The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
*More info → Run anyway*.
**Updating from `0.1.0-beta.31`:** Help ▸ Check for updates, then *Restart to update* with no game running. The terms
window shows the **EULA 1.6** and the **Disclaimer 2.12** once — each now says the builds are pre-releases, betas *and
alphas*; nothing else in them moved — and the Privacy Policy stays 2.12. The ledger stays at schema 21 and the detection
rules at `2026.10.4`. A beta never updates to an alpha: an alpha is installed only on purpose, from its own release page
(the user guide's new page, *Alpha builds*).
### Added
- **The alpha line** (the owner's request of 2026-10-31, owner decisions D73–D76): an `alpha` branch builds this source
on a prerelease .NET — .NET 11 RC3 first — and publishes it as `x.y.z-alpha.N` pre-releases on an update channel of
their own, so a beta never updates to an alpha and an alpha never to a beta. What the line needs on main changes nothing
in a beta: the `RELEASE_LINE` file and the line every assembly is stamped with (`Shared.BuildLine`), `release.yml`'s
rule that an alpha is tagged on the alpha line and nowhere else and packed on Velopack's `alpha` channel, CI on the
`alpha` branch, and no wiki publish for an alpha (`docs/12_BUILD.md` §The alpha line, `docs/13_CI_CD.md` §The alpha
line, `docs/11_UPDATER.md` §Channels). Whether the main line ever leaves .NET 10 is an open question whose decision
table is written before the evidence (`docs/20_OPEN_QUESTIONS.md` §G, *The main line's .NET*).
- **An alpha says what it is, and asks first** (owner decisions D73 and D74; none of it shows in a beta). Its terms window
shows the **Alpha notice** (`legal/ALPHA_NOTICE.md` 1.0) with the other documents and a box of its own to tick — *I
understand that this is an experimental build and I use it at my own risk* — and Accept waits for it; until it is
accepted the alpha's capture agent does not run. The title bar carries an **ALPHA** badge, a banner says what the build
is at every start, Help ▸ About and `--diag` name the .NET it runs on, and its update channel is locked: an alpha updates
only to newer alphas. It replaces the beta and shares its data, so before it first opens the database it copies it to
`backups\ledger-before-<version>.db` (the newest three are kept) and does not open it if the copy cannot be made. The
user guide has a page for it, *Alpha builds*, and `LIMITATIONS.md` a section.
### Changed
- **The EULA (1.6) and the Disclaimer (2.12) say the builds are pre-releases — betas, and alphas** (owner decision D75):
they said every build was a beta, which an alpha would make untrue. Nothing else in them moved; the terms window shows
them once more after the update. About ▸ Legal documents lists the Alpha notice on every build, for information.
- **What .NET 11's SDK asks of the source, taken where .NET 10 can take it too** (owner decisions D73–D76): the whole
gate run on .NET 11 RC3 before the alpha line was cut found 21 places its analyzers flag — `LastIndexOf`,
`StartsWith` and `EndsWith` of a single character, which .NET 11 overloads with a comparison; string sets and maps
built with `[]`, which C# 15 can give a comparer; one undisposed `JsonDocument` in a test. Each is rewritten in a form
both SDKs compile and that answers exactly as before (ordinal, as it was). Every test suite passed on .NET 11 with no
change of answer (`docs/spike-notes/24-dotnet11-probe.md`).
+71
View File
@@ -0,0 +1,71 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.33 was cut, 2026-11-03 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.33] - 2026-11-03
**The thirty-third pre-release: games from the Xbox app and the Microsoft Store.** PC Game Pass games included: Import
library finds the games those apps installed, a game's page shows its own logo and splash image, **Play** starts one
through Windows as its Start-menu tile does, and, with your consent, FrameLedger hooks it like any other game. How these
games are laid out, how Windows starts them and what it lets another program read were measured first on the owner's
eleven titles; a hooked session of one is still to be run. The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.32`:** Help ▸ Check for updates, then *Restart to update* with no game running. The terms
window shows the **Privacy Policy 2.13** once — it names what the Xbox library reads, that Play asks Windows to start
such a game, and the two facts read from a game before any injection; the EULA and the Disclaimer do not change. The
ledger stays at schema 21; the detection rules move to `2026.11.1`, so every game in the library is read again once.
### Added
- **Games from the Xbox app and the Microsoft Store** (the owner's request of 2026-11-03, owner decisions D77–D81; PC Game
Pass games included): **Import library** finds the games those apps installed into a games folder — each drive's
`.GamingRoot` names the folders, each game's own `MicrosoftGame.config` and `appxmanifest.xml` say what it is, and
Windows says whether its package is installed for you — and lists them as **Xbox**, with the process that actually
draws (an Unreal title's shipping executable, not the stub its package launches; never the GDK's `gamelaunchhelper.exe`).
A game's page shows its own square logo and splash image, read from its folder, and its package version (*Xbox version
1.3.5124.0*). Only games built on Microsoft's GDK are listed; an older Store app (UWP) is not (`docs/05_DETECTION.md`
§Platform signatures & metadata, `LIMITATIONS.md`, the user guide). Everything was measured first, on the owner's eleven
titles: the layout, and what Windows lets another program read there — every game executable refuses to be read, so no
Unreal Engine version is shown for these games (`docs/spike-notes/25-xbox-gdk.md`).
- **The detection rules know Xbox games** (rules `2026.11.1`, so every game in the library is read again once): an `xbox`
platform, first in the list — a GDK FINAL FANTASY ships Steam's DLL and read *Steam* — decided by a new signal,
`root_file`, from the install folder's own listing, so a very large install whose deep walk ran short still reads as
its store (`docs/05_DETECTION.md`).
- **Play starts a game from the Xbox app or the Microsoft Store through Windows** (D80), in either Play mode and from an
App running as administrator: the user's shell activates the game's package as its Start-menu tile does
(`explorer.exe shell:AppsFolder\<AUMID>`), because started by its path such a game is never the game in its package —
measured on the owner's titles (`docs/spike-notes/25-xbox-gdk.md`). The capture agent refuses to start one by its path
(`LaunchGame` answers `PackagedGame`), and the game is recorded once it appears, a few seconds after its start
(`docs/04_CAPTURE.md`, `docs/08_UI.md`, `LIMITATIONS.md`).
- **The anti-cheat guard says when a game cannot take the hook at all** (D78), read from the game's own token and code-protection
settings just before the injection: `TargetAppContainer` — an older Microsoft Store app (UWP) — and `TargetMitigation` —
only Microsoft- or Store-signed code, no generated code, a strict or non-CET-blocking user shadow stack, or strict Control
Flow Guard. Neither is a finding: nothing is written to the game, and the session keeps its duration, the sensors and the
reason. Each ended before as a failed injection, a hook that installed nothing, or a risk of ending the game, so no game
that measured before is refused now (`docs/19_SAFETY_AND_ANTICHEAT.md`).
### Changed
- **The Privacy Policy is 2.13**, shown once at the next start: it names what the Xbox library reads — the games folders
`.GamingRoot` names, each game's package files, Windows' answer whether its package is installed for you, and the
pictures a game ships in its own folder — that Play asks Windows to start such a game, and that before any injection
FrameLedger reads whether a game runs in an app container and which of Windows' code protections it runs under. The
EULA and the Disclaimer do not change.
- **The capture path reads a game's executable path one way** (for developers): `TargetResolver`, which finds the game again
just before the guard, read the loader's spelling (`Process.MainModule`) where the watcher had the kernel's, so a game
started through a junction could end `TargetNotRunning` about a process the watcher had just matched. Both read
`ProcessImagePath` now, and the resolver still opens a candidate with the guard's own rights, so a process an anti-cheat
driver closes stays `TargetUnreadable` (`docs/04_CAPTURE.md` §Process watcher).
### Fixed
- **The anti-cheat check saw only part of an Xbox game's folder** (safety): no install-root boundary matched the
`<games folder>\<Game>\Content\` layout, so for an Unreal title's executable, three levels down, check 4 walked only its
`Binaries\WinGDK` folder, and anti-cheat at the root of `Content` would have read clean. A GDK package root — the folder
holding `MicrosoftGame.config` beside `appxmanifest.xml` — is now a boundary for the guard and for detection alike, used
only where no store boundary matched, so it can only widen what is walked. The guard also gained `GamesInstalled\<X>`,
which detection had had alone since #17; one case list read by both test suites now holds the two resolvers together
(`docs/19_SAFETY_AND_ANTICHEAT.md`, `tests/fixtures/install-roots/cases.txt`).
- **The second alpha's release would have stopped at its delta check** (for developers): Velopack names a non-default
channel's packages with the channel (`FrameLedger.App-<version>-alpha-delta.nupkg`), and `release.yml` looked for the
default channel's name. It now takes the delta the pack listed in `assets.<channel>.json`; the betas' packages are named
as before (seen on the `0.1.0-alpha.1` rehearsal, which had no delta to make).
+81
View File
@@ -0,0 +1,81 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.34 was cut, 2026-11-06 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.34] - 2026-11-06
**The thirty-fourth pre-release: DLSS 5 and DLSS 4.5 named from what the game and the driver did, filters on Games
and Compare, and a Games page that opens at once.** The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.33`:** Help ▸ Check for updates, then *Restart to update* with no game running. The
Disclaimer (2.13) and the Privacy Policy (2.14) are shown once for you to accept; the EULA does not change. The ledger
moves to schema 22, which a beta.33 cannot open. The detection rules move to `2026.11.2`, so every game in the
library is read again once. DLSS 4.5 under the NVIDIA App's *Dynamic* frame generation reads on sessions you already
have; whether DLSS 5's neural rendering ran is kept for sessions recorded from now on.
### Added
- **Filters on Games and Compare** (owner request 2026-11-06, decision D85). Games: store, engine, state, installed and
played, beside the search and sort, with *Clear filters*; the title counts what is shown of all. Compare: game, tier
and frame generation over every session (it listed the newest 200), with a count; a ticked session stays listed.
### Changed
- **The list of games FrameLedger has been run with is current again** (`docs/LIST_GAME_TESTED.md`, decision D35's
method): refreshed from a copy of the owner's database taken 2026-11-06 and reviewed by the owner — fifteen more
games measured hooked, among them Phantom Blade Zero under the NVIDIA App's *Dynamic* mode, Hogwarts Legacy loading
DLSS 5's runtime and the first two Xbox app games — and the sessions recorded without measurement or refused by the
guard since 2026-09-27. The guide's Settings page says a language change stays on Settings; the closed §S30 notes the
fifth Streamline id decoded (`docs/open-questions/closed-s.md`).
- **The Compare page's layout** (the owner's screenshot): the selection bar beside the list instead of a window's width
away, with *Clear selection*; columns sized to what they hold — *Tier* and *FPS* touched, and wide gaps split the rest —;
the date sorts by when; the settings-changed column says so in words or shows a dash (it was blank); the result
table's session labels sit over their columns.
- **The selected page keeps its name in the left pane** (D86): WPF UI's pane animates the selected item's label away
(Compare's, in the screenshot — every page's while selected); FrameLedger uses a copy of its template without that.
- **Games opens at once from any page** (owner request 2026-11-06: switching to Games stalled 0.5–1.5 s). The window
keeps the library page it built and shows it again on every later visit, reading the library again behind it; the
library is read off the UI thread; the cards appear before the executables are checked — a USB drive that sleeps
took a second or more to answer, and no card was shown until every one had — and each card gets its *Not installed*
pill when its check answers; a read keeps every card that would look the same instead of rebuilding them all; the
list view builds only the rows on screen (`spike-notes` §27).
- **Changing the language keeps the page you are on** — Settings, after a change made there. The App remembered only
the pages it opened from code, so the language changed on Settings came back on the last game page opened
(`src/FrameLedger.App/Services/ShellHost.cs`).
- **DLSS 5 is named where the game ran it** (owner decision D84, amending D64). The owner's Hogwarts Legacy, Neural
Rendering on, loaded DLSS 5's runtime (`nvngx_dlssnr.dll` 310.9.16.0, from the game's folder) and the session could say
only *DLSS 5 runtime loaded* — nothing measured whether it ran. The Overlay's Streamline hook now decodes DLSS 5's
feature (`kFeatureDLSS_NR`, Streamline 2.14) into its own per-frame fact, and the Agent keeps the share of the frames
the game rendered through Streamline that carried it (`sessions.dlss_nr_pct`, **schema 0022** — a ledger this build
migrated no longer opens in an earlier one). Seen running, the DLSS line reads *DLSS 5 (neural rendering on 97.3% of
rendered frames)*, above every other generation; loaded and seen not running, *DLSS 5 runtime loaded, not seen
running*; where nothing could tell (an earlier Overlay, a title outside Streamline), *DLSS 5 runtime loaded*, as
before. Its library is listed with its version and source like the others, its Streamline plugin `sl.dlss_nr.dll`
is recorded when loaded, and a game shipping either file shows *Supports DLSS 5 Neural Rendering* (rules
`2026.11.2`, capability `dlss_nr`). The **Privacy Policy 2.14** names neural-rendering libraries among those whose
versions are read; the **Disclaimer 2.13**'s accuracy block says when DLSS 5 is named. One hook-path change: one more
compare in the `slEvaluateFeature` detour and one more test where a present is recorded (`spike-notes` §26).
- **Streamline's headers are `v2.14.16`'s** (developers): the vendored copy was `v2.12.0`, byte for byte; three of its
eleven files change — `kFeatureDLSS_NR`, the uplift buffer types 70–72, `kStructVersion7`, the version — and
nothing FrameLedger consumed otherwise (`src/native/third_party/streamline/README.md`).
- **A session under the NVIDIA App's *Dynamic* frame generation reads DLSS 4.5** (owner decision D83, amending D64).
Dynamic and its ×6 mode exist only in DLSS 4.5, and the DLSS line named a generation from the measured multiplier
alone: the owner's Phantom Blade Zero under *Dynamic, up to ×3* held ×2.0 and ×3.0 and read *DLSS 4 (a ×3.0
frame-generation state)*. It reads *DLSS 4.5 (Dynamic multi frame generation, set in the NVIDIA App)* where the game's
driver profile sets Dynamic, the driver reports its frame-generation override applied in the game's process, and DLSS
Frame Generation was identified (whether or not its factor was counted); a state measured at ×5 or more still ranks first, and a *Fixed* multiplier names nothing
by itself (The Witcher 3 under Fixed ×6 still presented ×2.0). The game page's chip and the CSV's `# dlss:` line
(`basis=dynamic_frame_generation`) follow; the **Disclaimer 2.13** says so in its accuracy block
(`src/FrameLedger.Domain/Detection/DlssGeneration.cs`, `src/FrameLedger.App/Services/DlssText.cs`; `spike-notes` §26).
- **The guard's source reads in order again** (developers only; no behaviour changes): the note that says what runs only
for a target the anti-cheat evaluation allowed sits above the function it describes again — beta.33's two isolation
checks had come between them — and names that isolation check among what runs
(`src/native/FrameLedger.Injector/src/fl_guard.cpp`).
### Fixed
- **An Xbox game's page no longer fails on a strange picture name** in the game's own `MicrosoftGame.config` (beta.33's):
a name that points at a stream of a file (`a:b.png`) made the search for its scaled variants throw — the page then
showed no picture and logged an error, and an action on the page that reloads it could end in the crash report. Such a
name is no picture a package ships, so it is passed over like a name outside the package
(`src/FrameLedger.Infrastructure/Art/XboxArtCache.cs`). Found by a self-review of #351 and #352 after their gates
passed; no install of the owner's eleven titles has such a name.
+91
View File
@@ -0,0 +1,91 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.35 was cut, 2026-11-09 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.35] - 2026-11-09
**The thirty-fifth pre-release: accessibility.** An accessibility statement (Help ▸ Accessibility); a screen reader
that reads every control and value in its words and is told what appears; headings and charts it can use; Windows
contrast themes followed; the keyboard following a page shortcut, and a message box opening over the window. And three
places where text read below WCAG's 4.5:1 in a Fluent theme, found on the way: the agent's pill, two kinds of short
message, a destructive button. The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info →
Run anyway*.
**Updating from `0.1.0-beta.34`:** Help ▸ Check for updates, then *Restart to update* with no game running. The legal
texts keep their versions, so nothing is shown for you to accept; the ledger stays at schema 22 and the detection rules
at `2026.11.2`. Nothing about capture or measurement changes.
### Added
- **An accessibility statement** (owner request 2026-11-09, decision D88). `ACCESSIBILITY.md` says what FrameLedger aims
for — WCAG 2.2 at level AA as W3C's WCAG2ICT applies it to desktop software, a goal and not a claim of conformance —
what works with the keyboard alone, a screen reader, a contrast theme or Magnifier, how it is checked (the project's
tests, and the owner's pass of 2026-11-09: keyboard only and Narrator on 0.1.0-beta.34 and 0.1.0-alpha.3, no fault),
what does not work yet and what to do instead, and how a barrier is reported and handled — by severity, with no
promised times. The app shows it under **Help ▸ Accessibility**, and after Limitations in the user guide's window; the
wiki gets an *Accessibility* page.
- **An *Accessibility problem* issue form** (`.github/ISSUE_TEMPLATE/accessibility.yml`) asking what was tried, what
happened and what the reporter uses — never anything about the reporter themself — and a user-interface section in the
pull-request template. The `accessibility` label exists, and so do `safety` and `priority-high`, which the *Safety gap*
form had named since its first day without either existing — so GitHub had never applied them.
- **A screen reader reads what the window shows** (decision D88's goal; measured in the UI Automation tree WPF builds on
every page, window and dialog, every tab — `PagesLoadTests.Automation`). Drop-down options were read as an internal
record (*Choice { Value = dark, Label = Dark }*), lists and table rows by their program names, table cells drawn by a
template as *Item: …, Column Display Index: n*, and the terms window's list by each document's whole text; each now
reads the words it shows, and an empty cell reads *empty*. The frame-rate readout says Native, Displayed and the
factor together (CLAUDE.md rule 6, in speech), a ray-tracing chip its value and where it came from, a change badge its
number. The safety notices' title and message reach a screen reader (they were hidden inside the notice's template),
and the notice's button says which notice it answers. A button repeated on each row names its row (*Open: …*, *Play:
…*, *Turn off: …*). Tab no longer stops on pictures, lists, Settings' rows, the FPS readout, the chips or the dialog
host, where it found nothing to say; an expander's button is named after its header.
- **A screen reader is told what appears** (owner decision D89): a safety notice as it arrives, the capture agent going
offline and coming back, an update's steps (not each percent), every short message at the bottom of the window, a
notice on a game's page and each result of Tools ▸ Database maintenance — in the words shown, and only while
FrameLedger's window is the active one, so a game that has the screen is never interrupted. The database line's live
region, which announced nothing, is gone.
- **Headings and charts a screen reader can use** (owner decision D90). Every page's title is a first-level heading and
each section title a second-level one, so a screen reader's heading keys move between sections. Every chart says what
it is and where its numbers are written as text; its keys — arrows to move, Ctrl with an arrow to zoom, A to see all of
it — now stay with the chart instead of also scrolling the page or moving the focus on, and its focus is drawn. No
chart tells two series apart by colour alone any more: Compare's five sessions, the GPU's temperature and its hot spot,
the two kinds of stutter, the two lows and the two limits each have their own line pattern, marker or hatch.
- **Windows contrast themes are followed** (owner decision D91). With a contrast theme on — Aquatic, Desert, Dusk, Night
sky, or one whose colours were edited, on Windows 10 or 11 — every colour in FrameLedger's windows is one of that
theme's, whatever Settings ▸ Theme says, and it changes the moment the theme is turned on, edited or turned off;
Settings ▸ Theme says so under its box. Before, *System* could apply WPF UI's own high-contrast files, most of whose
colours are a red placeholder, and the next window opened put the light or the dark theme back. The charts draw in the
theme's colours, their patterns telling the series apart; the frame-generation, ray-tracing and upscaler chips are the
theme's highlight and its text (WPF UI's files put the window text there, 1.26–1.78:1); a destructive button is the
theme's own button; a pressed menu item is no longer white on white; nothing is drawn translucent, and a game's picture
lends its page no colour, as before.
- **The keyboard follows a page shortcut.** **Ctrl+1** … **Ctrl+5** now move the focus into the page they open — its
first control — and a screen reader hears the page's title; before, the focus stayed where it was, often on the page
that had just gone, and Tab began again at the top of the window.
- **Pages no longer slide in while Windows' animation effects are off** (Settings ▸ Accessibility ▸ Visual effects),
followed as the setting changes.
### Fixed
- **A message box opens over FrameLedger's window** — Remove game, Delete sessions, the database's and the update's
questions. It had no owner, so it could fall behind the window it came from and, closing, give the focus to another
program; it is owned by the window that opened it now, and the focus comes back there.
- **A double-click on a chart shows all of it again**, as the user guide said; it toggled ScottPlot's render-time overlay.
- **The capture agent's state in the title bar reads in the light theme.** It was drawn on WPF UI's fixed green, blue,
orange and red under white — 2.78, 2.63, 2.16 and 3.68:1 — and is on the theme's own success, caution and critical
fills now, as the notices are; its words say the state.
- **The short messages at the bottom of the window read.** A *done* or a *warning* message was white on a fixed green or
orange, 2.78:1 and 2.16:1 in both themes; every message is in the theme's colours now, its icon saying which kind.
- **A destructive button's label reads in the dark theme** — Remove on a game's page, Delete in the confirmations: the
theme's dark text on the red, 5.3:1 and 5.7:1, where white read 3.68:1.
### Changed
- **Documents corrected**: charts do take focus and keys (`docs/08_UI.md` said neither — `ChartKeyboardTests` measures
it); the database-maintenance result's live region announced nothing, since WPF raises one only when the app does; the
"no Narrator pass" gap is the owner's pass now, beside what that pass could not show; the open question "Accessibility
/ DPI: no design anywhere" is closed; NFR-9 names screen readers and contrast themes (D88–D91). `LIMITATIONS.md` gains an
*Accessibility* section and loses its one struck sentence — a screen reader reads struck text as current, so no page
the app shows strikes text through. The guide's menu table names its menu on every row, read one row at a time.
+59
View File
@@ -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.
+86
View File
@@ -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.
+96
View File
@@ -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`.
+36
View File
@@ -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.
+168
View File
@@ -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.
+65
View File
@@ -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
+61
View File
@@ -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.
+56
View File
@@ -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.
+69
View File
@@ -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.
+39
View File
@@ -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.
+67
View File
@@ -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.
+45
View File
@@ -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.
+32
View File
@@ -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.
Loaded 100 of 1670 files, more files were not shown because too many files have changed in this diff. Show more