Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 562f2ff767 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
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:29:57 +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
poli0981andClaude Opus 5 5ae5c14e1b feat(app): the bug report's last optional item, the last session's summary when ticked (#185)
10_LOGGING's bug report step 2 listed "last session metadata + aggregates JSON (never raw blobs by default)" beside
the crash dump, and the privacy policy promises both only when ticked. The Optional items dialog now shows a
checkbox 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 with a
BugBundleOffer. Two strings in en/vi/ja.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 22:06:15 +07:00
poli0981andClaude Opus 5 3efe89facc docs(legal): the accuracy block says what the code measures on 2026-09-15 (#184)
legal/ACCURACY.md, embedded in README.md and legal/DISCLAIMER.md, was dated 2026-09-06 and still said there was no
Agent loop, storage, charts, library import or UI, that OpenGL intercepted nothing, that no shipped component ran
the 30 s re-scan and that video memory was not measured. Every sentence was re-checked against the code: OpenGL
is measured; Vulkan only when FrameLedger starts the game; FSR is named FSR 3 or unversioned; the preset is not
reported; frame generation is Direct3D-only; whole-card VRAM is recorded while per-game VRAM, shader-stutter
attribution, Reflex, HDR and CPU temperature are not; the shipped Agent runs the re-scan; nothing is released.

README outside the block and DISCLAIMER (now 2.1-draft) drop the claims the code no longer supports. Docs that
contradicted the code are corrected, including 04_CAPTURE's "attach mode on a running Vulkan title stays Tier 2",
which it does not: attach mode injects the Direct3D Overlay, an open decision for the owner. Stale comments in
dllmain.cpp, layer.cpp and fl_guard.cpp now describe the code; no behaviour changes.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 21:55:07 +07:00
poli0981andClaude Opus 5 7a596a3697 fix(capture): a quality the hook could not tell and an unmeasured Reflex are no longer stored as values (#183)
The quality byte's 0xFF is the Overlay's "a hook ran and could not tell" (fl_shm.h upscalerQuality), and every
AMD dispatch carries it. SessionAggregator (row and segments) and SessionProgressCalculator took it 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: an FSR title would read "FSR 255". Frames that did not tell are now left out, and a quality
nobody told is null (FrameSample.QualityNotTold).

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.

Found while checking legal/ACCURACY.md against the code.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 21:32:19 +07:00
poli0981andClaude Opus 5 a7075547e1 fix(app): a start that fails says so on screen instead of exiting silently (#182)
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.

It now shows StartupFailureDialog, a Win32 message box like the crash dialog, because 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 in en/vi/ja.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 21:18:56 +07:00
poli0981andClaude Opus 5 dcf5796bf2 fix(app): bug bundles no longer carry the user's name in log paths, as the privacy policy already promised (#181)
legal/PRIVACY_POLICY.md section 3 says logs are redacted (user directory paths removed) before bundling, and
10_LOGGING named a RedactingEnricher. Neither existed: BugBundleBuilder copied ui-*.log, agent-*.log and
overlay-*.log verbatim, on the 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.

LogRedactor 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-question-mark spellings. The file is read through Latin-1, so UTF-8 and ANSI logs come out byte for byte
except the names. The files on disk keep their paths, and the policy's sentence is now true unchanged. The enricher
claim is struck in 10_LOGGING with where the rule is enforced instead.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 21:04:10 +07:00
poli0981andClaude Opus 5 f94687f42f test: the harness's overlay logs leave with the test run that wrote them, and a gate keeps it so (#180)
The injection tests inject the shipped Overlay into hook-harness, and the Overlay logs to the real
%LOCALAPPDATA%\FrameLedger\logs by design (SHGetKnownFolderPath, not the environment, per S21). The owner's folder
held 2506 overlay logs on 2026-09-15, 2492 of them hook-harness's from test runs, beside 14 from real titles.

No switch goes into the injected DLL. Each test binary removes, when its run ends, the logs it caused: an
overlay-*.log created after the run started whose first line names a hook-harness image it owns. Natively a Catch2
listener in guard_test.cpp over src/native/tests/overlay_log_sweep.h (the image must be FL_HARNESS_EXE); in managed
code tests/Shared/HarnessOverlayLogSweep.cs, an xUnit assembly fixture that FrameLedger.DrainFixtures.targets compiles
into every test project staging the harness, with PipeEndToEndTests registering its renamed copy's directory. Parallel
assemblies own different copies, so none removes a log another is about to read, and a game's log is never touched.

tools/test-artifacts-check.ps1 (seven self-test cases) is a new gate step: a hook-harness log created during the gate
and still there fails it, which is what makes a missing sweep red. Existing logs are left for the owner.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 20:33:23 +07:00
poli0981andClaude Opus 5 2519864f2f feat(app): the crash dialog, the minidump in both processes, and the crash dump as the bug report's opt-in (P4 PR-9) (#179)
10_LOGGING's crash handling specified Fatal, MiniDumpWriteDump, a dialog offering the bug report and exit code 1;
only the Fatal line existed. Infrastructure's CrashDumpWriter writes crashdumps\<ui|agent>-<UTC time>-<pid>.dmp with
the spec's two flags, keeps the five newest and never throws.

The App marks a dispatcher exception handled; CrashReporter logs it, writes the dump and shows a Win32 message box
whose Yes runs BugReportFlow, then the host stops and RunAsync exits with code 1. One dialog per process: further
exceptions are logged once and counted, since a layout fault repeats while the dialog pumps. Another thread's
exception is Fatal and a dump only. The Agent logs and dumps from AppDomain.UnhandledException and from Main's own
catch, 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,
with its size and what a dump can hold, which is what PRIVACY_POLICY section 3 already promised; Cancel writes
nothing and WriteAsync refuses a dump from outside crashdumps\. Crash_Body becomes Crash_Body_Format; seven more
strings in en/vi/ja.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 09:22:29 +07:00
poli0981andClaude Opus 5 f7f7195d69 feat(app): the accessibility pass -- Ctrl+1..5, Esc closes dialogs, an automation name on every textless input (P4 PR-8) (#178)
08_UI gains an Accessibility section first, then the build it describes. Ctrl+1..5 (and the keypad)
open Dashboard, Games, Compare, Logs and Settings through ShellShortcuts, the one place that knows
which number is which page. Esc closes the open ContentDialog or MessageBox with no result through
the dialog's own Close path, and never one that offers no Close button: WPF UI 4.3.0 handles no key
in either, ContentDialog.CloseButtonText defaults to "Close", and MessageBox.Close() is obsolete, so
DialogKeyboard uses the Close button's TemplateButtonCommand from one class handler on Window.

Thirty controls that announced only their type carry an AutomationProperties.Name from .resx; four
new strings (en/vi/ja) name the ones with no label to borrow. The maintenance dialog's status line is
a polite live region. AccessibilityTests hold all of it: every textless input is named (proven red on
the kill switch), no XAML hard-codes a colour, the manifest is Per-Monitor V2, the shortcuts follow the
NavigationView's order, and Esc closes a real ContentDialog with no result.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 01:25:10 +07:00
poli0981andClaude Opus 5 00f098442a feat(app): Tools > Database maintenance -- integrity check, backup, the retention sweep on demand, compaction (P4 PR-7) (#177)
The sweep is the Agent's, because frame_blobs and sensor_blobs are: the App sends the new
SweepRetention command (no payload) 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, a removed game's kept sessions included. Unlimited
never reaches the repository, which refuses a keep below 1.

The App's LedgerMaintenance changes no row: PRAGMA integrity_check; a VACUUM INTO backup that refuses
the ledger, its WAL and its shm file as the destination (the save dialog's "replace?" would otherwise
have deleted the live database); and VACUUM + wal_checkpoint(TRUNCATE), refused while a fresh
GetStatus reports a session. LedgerDatabase.MaintainAsync runs these outside a transaction.

A ContentDialog with four cards and a status line; the sweep confirms with a Danger button. The last
NotYetCommand and its strings are gone.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 01:01:43 +07:00
poli0981andClaude Opus 5 e149bf251d feat(legal): every NuGet package the App and the Agent ship has its licence text, and the gate keeps it true (P4 PR-6) (#176)
tools/license-gather.ps1 reads the two publish roots' restore output and writes one text per shipped
package into legal/licenses/nuget/ (77 packages; the notices table named about fifteen): the package's
own licence file verbatim, a reviewed override for a URL-only package (Mono.Posix.NETStandard,
OpenTK.GLWpfControl), or MIT under the package's own copyright field / a pointer to the shared
Apache-2.0 and MPL-2.0 texts. Distinct third-party notices are written once. An MPL-2.0 package that
applies Exhibit B is red; the MPL text itself, which carries it as a template, is not.

license-check section 3 runs -Check (regenerate, compare both directions); build.ps1 runs the
fourteen-case self-test first, one case under tr-TR in a child process -- the output was
culture-dependent until file names matched CultureInvariant and ordering became ordinal.

The App's publish carries legal/licenses/ as licenses/; release.yml adds the .NET runtime's licence
and notices from the packs the publish used and asserts the licence files in the published tree.
LHM's three transitive MPL-2.0 packages are recorded Exhibit-B clear from an upstream code search.
The directory is nuget/, not packages/, which .gitignore ignores.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 00:48:56 +07:00
poli0981andClaude Opus 5 c2ec121c8a test(native): the log test reads this child's log, not a stale one under a reused pid (#175)
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 read a finished
log from an earlier process and failed on the STOP line; a re-run drew a fresh pid and passed, so it
was filed as a flake four times while the failure output printed the stale path.

The lookup now takes the newest log created at or after the child started, and the test plants a
1999-dated log under the child's pid first, so the old behaviour is red on every run (9 of 18
assertions with the lookup reverted) and the fix is green (18 of 18). Test-only.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 00:33:12 +07:00
poli0981andClaude Opus 5 1776a22907 feat(app): Velopack, the updater with FR-12 as its shape, release.yml, and one VERSION source (P4 PR-5) (#174)
* feat(app): Velopack, the updater with FR-12 as its shape, release.yml, and one VERSION source (P4 PR-5)

The updater of 11_UPDATER behind an IUpdateClient port (VelopackUpdateClient over Velopack 1.2.0's
GitHub source; stable = releases GitHub does not mark pre-release, beta adds them): the startup silent
check 5 s after start for an installed copy with update.auto_check on, Help > Check for updates with
the dialogs and the six error rows, the background download (a checksum failure retried once), and the
apply -- refused while any session runs, Deferred until the last SessionCompleted, then Shutdown to the
Agent, the connection's relaunch held, the pipe watched until it drops, WaitExitThenApplyUpdates, the
host ended. Program.Main runs VelopackApp first; the uninstall hook stops the Agent, unregisters the
layer, removes the logon task and asks about the data folder.

The package id is FrameLedger.App, not FrameLedger: Velopack installs into and deletes
%LOCALAPPDATA%\<packId>, which with the documented id is the data folder holding ledger.db.

VERSION at the root feeds Directory.Build.props and the native CMake project; versioninfo-check
compares every binary against it. release.yml gates the tag against VERSION and CHANGELOG
(tools/release-notes.ps1), substitutes {{RELEASE_DATE}}, runs the identical gate, publishes, asserts
the published tree, packs, checksums and releases.

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

* fix(app): the private constant's name, Velopack's copyright as its package states it, and the measured pack

- UpdateService: _idleState (IDE1006, the repository's private-field rule; dotnet format caught it).
- legal/licenses/velopack-MIT.txt and THIRD_PARTY_NOTICES: the copyright line is the package's own
  <copyright> field ("Velopack Ltd."), not a name written from memory.
- 12_BUILD / 13_CI_CD / CHANGELOG: vpk pack 1.2.0 run by hand over the published tree -- Setup 104 MB,
  VelopackApp.Run() verified in Program.Main.

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 23:56:55 +07:00
poli0981andClaude Fable 5.1 603795f49d feat(app): the library import -- Steam, GOG Galaxy, Epic and itch.io through a review checklist, hooking off for every row (P4 PR-4) (#173)
LibraryImporter over four IStoreLibrarySource adapters: Steam
(libraryfolders.vdf + appmanifest_*.acf through a ValveKeyValues
reader), GOG (the HKLM registry keys, read-only, under whichever hive
and key a caller names), Epic (Manifests\*.item), itch (gzipped
receipts). Steam and itch do not name the game's executable:
ExecutableLocator walks three levels, drops helpers by name fragment
and takes the largest -- a guess the review marks as such.

File > Import library... shows the checklist, adds what was ticked
exactly as File > Add game... would -- hooking off, FR-1.2 -- and
writes the store's platform, id and version through the new
IGameRepository.ApplyStoreMetadataAsync under the same provenance rule
as a detection write. Nothing is launched, nothing is fetched.

Tests: ValveKeyValuesTests, StoreLibrarySourcesTests,
LibraryImporterTests, ImportLibraryFlowTests, SqliteGameRepositoryTests.
15 App strings en/vi/ja. Docs: 05_DETECTION, 06_DATA_MODEL, 08_UI,
14_TESTING, HANDOFF, 15_ROADMAP, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 23:32:07 +07:00
poli0981andClaude Fable 5.1 d0461237eb feat(app): the bug report's steps 3-4, Help > Documentation, and File > Export as the submenu it was specified as (P4 PR-3) (#172)
BugReportFlow is the one flow behind Help > Report a bug... and the
Logs page's button: the zip where the user says, the preview dialog
listing every entry the builder wrote, then "Open GitHub issue" (the
form's real hyphenated field ids prefilled, the OS in the form's own
spelling) or "Copy summary as Markdown". Nothing is ever sent by itself.
Three ports keep it testable without a desktop: IBugReportPreview,
IUrlOpener, IClipboard.

Help > Documentation opens the README. File > Export is the three-leaf
submenu 08_UI specifies: Session CSV / Session JSON for the session last
selected on a Sessions tab or opened in a summary window
(SessionSelection, SessionExportService over the summary window's own
writers), Chart PNG opening that session's summary window.

Tests: BugReportFlowTests, SessionExportServiceTests, LogsViewModelTests
over the flow. 14 App strings en/vi/ja. Docs: 10_LOGGING, 08_UI,
HANDOFF, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 22:22:18 +07:00
poli0981andClaude Fable 5.1 e88dd3dbbb feat(vulkan): the "is Vulkan" fact from the executable, and the layer's registration following the ledger (P4 PR-2) (#171)
12_BUILD's rule -- the layer is 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".

The fact is static now: GameFileProbe reads the executable's import and
delay-load tables (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.

VkLayerReconciler over the IVkLayerRegistrar port (VkLayerRegistrar:
the manifest and HKCU value --register-vklayer writes) computes the
desired registration from the 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. --register-vklayer runs it and refuses when no
hook-enabled game references the loader; the Settings button follows
the same rule.

Tests: VkLayerReconcilerTests, PeImportsTests (a synthetic PE32+),
DetectionSweepTests, StaticGameDetectorTests, SettingsViewModelTests.
Docs: 17_HOOK_ENGINE, 12_BUILD, 05_DETECTION, 08_UI, HANDOFF, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 20:01:18 +07:00
poli0981andClaude Fable 5.1 8a7f6fe6e2 feat(detection): the rules engine wired into the Agent -- DetectionSweep under --serve, ApplyDetectionAsync under the provenance rule, schema 0004, the Supports row (P4 PR-1) (#170)
The engine, schema, validator and fixture corpus existed since P0 with
no production caller and no writer. DetectionSweep runs
StaticGameDetector over the real GameFileProbe for every library game
whose DetectionCacheKey is stale and persists through the new
IGameRepository.ApplyDetectionAsync; DetectionHostedService hosts it
under --serve on its own task (the probe blocks on file I/O), every
15 s and at once when UpdateRules re-seeds the rules file.

Schema 0004 gives the key's exe half its own columns: exe_size_bytes /
exe_mtime_ms are the consent fingerprint the gate reads and a background
scan must never refresh them. 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 a fresh game could never receive an engine), a
null detected value erases nothing -- and writes capability_flags whole
as the rule ids.

App: Tools > Update detection rules is a real command; the Supports row
shows what the sweep wrote. Tests across Application, Infrastructure and
App. Docs: 05_DETECTION, 06_DATA_MODEL, 04_CAPTURE, 08_UI, HANDOFF,
15_ROADMAP, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 19:32:48 +07:00
dependabot[bot]andpoli0981 b73d7632b2 Bump Meziantou.Analyzer and Roslynator.Analyzers (#157)
Bumps Meziantou.Analyzer from 3.0.141 to 3.0.257
Bumps Roslynator.Analyzers from 4.16.0 to 4.16.1

---
updated-dependencies:
- dependency-name: Meziantou.Analyzer
  dependency-version: 3.0.257
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: minor-and-patch
- dependency-name: Roslynator.Analyzers
  dependency-version: 4.16.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-09-14 18:52:51 +07:00
poli0981andClaude Fable 5.1 cae65cf776 fix(overlay): a DXGI present counter that went backwards is a reset, not four billion unseen presents (#169)
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 owns the arithmetic now: 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. static_asserts 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: 6.3 ns/present delta on this branch vs 7.4 ns on main
(both the harness's empty-detour floor; noise).

Docs: fl_shm.h @48/@52, 17_HOOK_ENGINE hook inventory, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 18:42:46 +07:00
poli0981andClaude Fable 5.1 a09089a238 fix(fg): an identified frame generation whose count refused reads as Presented FPS naming the technology, not N/A -- schema 0003 fg_refusal (#168)
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. Every FG surface said
N/A. The readout fell into the "detected" shape and printed
"N/A -> N/A FPS (x0.0 FG)" from `factor ?? 0`; the game page said
"DLSS-G " with a trailing space; the grid said N/A with no reason; and
the reason existed nowhere -- FgWindow.Refusal was computed and dropped.

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. 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 FGx.
GeneratedLine no longer accepts a missing factor. The fg_runtime_loaded
chip names the module from the census, as 08_UI asked from the start.

15 App strings en/vi/ja. Tests across App, Application, Infrastructure.
Docs: 03_METRICS, 08_UI, 06_DATA_MODEL, 07_IPC, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 18:31:04 +07:00
poli0981andClaude Fable 5.1 4a79214760 fix(app): the safety notices render their one button -- ui:InfoBar re-templated with a ContentPresenter (#167)
WPF UI 4.3.0's InfoBar template has no ContentPresenter, so the action
button 08_UI puts on every persistent banner -- "Record this session
without measuring it" on a refusal, Dismiss otherwise, the only exit once
IsClosable="False" removed the X -- compiled, bound and was never drawn.
The owner met a red bar with no way to close it. The Agent-offline
banner's Retry and the game page's Re-enable were dropped the same way.

Styles/FrameLedger.xaml now carries 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. The STA harness became one queue-fed thread: a thread
per test shared unfreezable DynamicResource brushes across threads the
moment two tests rendered a ui:Button.

legal/licenses/wpfui-MIT.txt added. Docs: 08_UI, 16_WPFUI_SYNTAX,
HANDOFF traps, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 18:12:09 +07:00
poli0981andClaude Fable 5.1 4a46902efb fix(app): left-align the two wrapped descriptions on the Settings page (#166)
A TextBlock with a MaxWidth inside a stretched StackPanel is centred by WPF once the text wraps,
so "Record games launched outside FrameLedger" and "Fetch store metadata online" showed their
second line offset under the header (owner's screenshots, 2026-09-14, en and vi). The Vulkan
layer and logon task rows already carried HorizontalAlignment="Left"; these two now do too.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 10:54:31 +00:00
poli0981andClaude Fable 5.1 06440454e2 feat(app): first run, the Legal Gate (FR-11), and P3's closing sweep (P3 PR-9) (#164)
FirstRunWindow / FirstRunContent / FirstRunViewModel, shown by ApplicationHostService before the
shell whenever LegalGate says a document has no acceptance at this build's version -- a first run,
or a document whose version moved. The four documents ride in the assembly (legal/EULA.md, LICENSE
as the GPLv3 text, legal/DISCLAIMER.md, legal/PRIVACY_POLICY.md; embedded at build so the App shows
the text this build was reviewed with; authoring comments stripped; {{RELEASE_DATE}} left for
release.yml). One Accept writes four legal_acceptance rows with each document's own **Version:**
line (GPL-3.0-only for the licence); Decline ends the host; a closed window is a decline. Step 2
is the Agent setup (unelevated by default, elevation optional and required by no tier, the
HelloAck facts as they arrive); step 3 the hooking explainer, reusing the consent dialog's reviewed
Tier 1 / Tier 2 paragraphs and saying hooking stays off until enabled per game; step 4 the import
placeholder. Settings > Reopen the legal documents shows them read-only. D8 unchanged.

NFR-4: the first window's time from process start is logged every run (0.83 s for the first-run
window, 1.3-1.5 s for the shell on the dev box); the 100-session query is asserted under 500 ms;
charts draw at most 2 x 2000 points per series per draw.

Closing sweep: 08_UI first-run built note with the numbers, 06_DATA_MODEL legal_acceptance (who
writes the version), 20_OPEN_QUESTIONS section 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.

Tests: App 120 (LegalDocumentsTests, FirstRunViewModelTests, the Settings reopen, both first-run
steps in PagesLoadTests). 29 App strings en/vi/ja.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 14:35:45 +07:00
poli0981andClaude Fable 5.1 0fbaecb05f feat(app,agent): the tray, the Agent's maintenance flags, and the Settings buttons over them (P3 PR-8b) (#163)
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 -- with the game in the tooltip; 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 is honoured through WindowClosePolicy while a tray icon exists;
Exit through ShellHost.Quit is a real exit. FR-3.8's balloon "Session saved -- game -- click to
view" is raised only while the window is off screen (the Dashboard's snackbar carries it
otherwise: one event, one channel) and its click opens the summary; a safety event is never a
balloon. Tools > Agent status... and Vulkan layer registration... navigate.

Agent flags: --install-task / --uninstall-task (Infrastructure.Startup.LogonTask: the task
\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, --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 reads the key at start. --diag stays the one
flag the Agent answers "not this binary's".

Settings: Register / Unregister the layer, Register / Repair / Remove the task -- each runs the
flag as a child process (IAgentTool) and re-reads the machine (IMaintenanceState); Register is
enabled only while the layer is staged, unregistered, and a game has hooking on.

Two gaps stated in 17_HOOK_ENGINE's built note rather than implied: register/unregister on the
consent transition needs the "is Vulkan" fact (P4 capability flags), and a registration buys
nothing until background capture sets the enable variable.

Tests: App 110 (TrayViewModelTests, Settings additions), Infrastructure VkLayerRegistrationTests
(a test's own key) and LogonTaskTests (Integration, a real task under a test's own name), Agent
surface + e2e flags case. 27 App strings en/vi/ja. Docs: 08_UI, 17_HOOK_ENGINE, 12_BUILD,
HANDOFF row 8 struck, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 14:25:08 +07:00
poli0981andClaude Fable 5.1 975fb343c2 feat(app): Settings over the registry, the safety notices, the Logs page and --diag (P3 PR-8a) (#162)
The Settings page (08_UI §Settings, FR-10) over RegisteredSettings: Capture first -- the global
kill switch (hooking.kill_switch, the gate's fourth input; a measured session stops at its next
30 s re-scan), 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 min session / sensor interval /
retention as bounded NumberBoxes 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-with-Windows as
this user's HKCU Run value (Infrastructure.Startup.RunAtLogon), minimize-to-tray and the update
channel stored for later builds, online metadata (off), debug logging (moves the App's Serilog
LoggingLevelSwitch at once), Legal reopen as "not yet" until PR-9.

Safety notices (08_UI §Notifications policy): CaptureRefused, SafetyUnhook and CaptureDegraded
become persistent InfoBars above every page with the family and signal named from Safety_*,
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 (10_LOGGING §In-app log viewer): the newest ui-*.log / agent-*.log with shared read and a
2 MB cap, level filter over the template prefix, search, pause, a 2 s refresh only while shown,
Open logs folder, and Export bug bundle = step 2 of the bug-report flow (our logs of seven days
verbatim, the five newest overlay logs, sysinfo.json, settings.json; nothing sent, steps 3-5 P4).

FrameLedger.exe --diag writes the environment and capability report to logs/diag-<ts>.txt and
stdout without starting the host.

Tests: App 100 (SettingsViewModelTests, SafetyNoticesTests, LogTailTests, LogsViewModelTests,
BugBundleBuilderTests, DiagReportTests, both pages in PagesLoadTests), Infrastructure
RunAtLogonTests. 69 App strings en/vi/ja. Docs: 08_UI, 10_LOGGING built notes, HANDOFF row 8
amended (8b: tray, layer and task verbs), CLAUDE.md App line, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 14:14:27 +07:00
poli0981andClaude Fable 5.1 3a92255076 feat(app): Trend, Sensors, Latency, and Compare with the mixed-tier guard (P3 PR-7) (#161)
Game page tabs 2-6: Frametime and Distribution of the selected session (the summary
window's own charts, with a note when the selection is Tier 2 or swept); Trend through
Charts/TrendSeriesBuilder -- one point per hooked session oldest first under the selector
(Average = Native where FG was measured, Presented where not, and the note says so;
Displayed only where measured; 1% / 0.1% Low; max GPU C), FR-6.4's exclusion of
settings_changed_midsession 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 dashed lines on a date axis; Sensors
(core/hotspot C, load %, power W right axis; VRAM with the game's own per-present
vram_proc and the adapter-wide vram_adapter as two differently-labelled series);
Latency (the latency_us blob with the stored avg/p95 lines, only when Reflex reported).

Compare (CompareViewModel over the last 200 sessions across games): a checkbox picker
enabled at 2-5 with the FR-6.4 warning icon; IMixedTierPrompt -- a blocking ContentDialog
with Cancel as the default -- asked when the selection mixes tiers, comparing nothing on a
decline (FR-6.2); on proceed the tier legend is the plot's title and an InfoBar; one
percentile curve per hooked session (Charts/PercentileCurve, shared with the
distribution); the stat table with Native / Displayed / Presented FPS as three separate
rows, Median, the lows, stutter time %, max GPU C, duration; the best of each row bold
and accent (higher wins for FPS, lower for temperature and stutter, N/A never); Tier-2
cells at N/A; PNG export.

Tests (App, 74): TrendSeriesBuilderTests, CompareViewModelTests, the selected-session
series + trend toggles on the game page, all four new charts rendered through Skia in
PagesLoadTests. 65 new App strings in en/vi/ja.

Docs: 08_UI §Games tabs 2-6 and §Compare built notes; HANDOFF row 7 struck (the tier
rule is held in memory by TrendSeriesBuilder and CompareViewModel, not by a SQL GROUP
BY -- stated rather than a query claimed). CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 14:03:40 +07:00
poli0981andClaude Fable 5.1 f0da7e5cf7 feat(app): the session summary window and the charts -- ChartTheme over two palettes, min/max decimation, the frametime timeline, the distribution, FR-8.3's override, tags/notes, CSV/JSON/PNG export (P3 PR-6) (#160)
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 -- the stored count's own rule -- segments from frame index to seconds, sensors
aligned to t_ms with -1 dropped). 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: application frames by default, the every-present series behind the
FR-5.4 toggle only when generated frames exist, PSO-compile stutter coloured apart
(FR-5.5), alternating segment spans, GPU temperature/load on the right axis.
DistributionChart: FPS histogram + the percentile curve through Domain.Metrics.Percentile.
ChartTheme.Apply/Attach re-colour every live plot on ApplicationThemeManager.Changed
from Styles/ChartPalette.{Dark,Light}.xaml (the one place hex is allowed);
ChartPaletteTests pins the two files' key parity. ScottPlot.WPF 5.1.59 as pinned.

Windows/SessionSummaryWindow (a secondary FluentWindow with its own ContentDialogHost):
stat cards from the STORED aggregates, never recomputed (lows labelled "(presented)"
when FG was not measured); chips through TriStateResolution with FR-8.3's dialog
writing the override to session_annotations beside the measurement (and the game
default on request; clearing restores the measurement); crash and safety-unhook bars;
tags/notes editor; FR-9 exports -- 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, N/A omitted); PNG via
Plot.SavePng. Opened from a Sessions-tab row (double-click or Open) and from the
Dashboard's recent list. FR-3.8 is an in-app notice on SessionCompleted until the
tray exists (PR-8).

Tests (App, 68): DecimatorTests, ChartPaletteTests, SessionSeriesLoaderTests,
SessionExporterTests (schema, header, invariance under vi-VN, Tier-2 no rows, JSON),
SessionSummaryViewModelTests (cards, override + clear, tags de-duplicated, exports
through a scripted saver), and the charts drawn through Skia under the theme
dictionaries in PagesLoadTests. 57 new App strings in en/vi/ja.

Docs: 08_UI §Session summary + 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). CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 13:52:58 +07:00
poli0981andClaude Fable 5.1 c36038dd86 feat(app): Games and Dashboard -- the grid, the game page with the hooking control and the Sessions tab, the live card, FpsReadout and TriStateChip (P3 PR-5) (#159)
Services.FpsPresentation decides CLAUDE.md rule 6 in ONE place, for rows and for 1 Hz
progress events: generated (`62 -> 118 FPS (x1.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. Controls/FpsReadout and
Controls/TriStateChip render a model and decide nothing (templates in
Styles/FrameLedger.xaml, theme brushes only).

Games: GamesViewModel (cards from GameLibrary.ListCardsAsync with the per-game
aggregate; search and sort in memory), FR-1.1 by pick, File menu or a dropped .exe
(AddGameFlow, one flow; a game is added hooking OFF and the watcher reads the same
table), FR-1.4 with Keep sessions / Delete sessions too, revoking consent over the
pipe FIRST when it was on. GameDetailViewModel: header, Supports (capability_flags;
empty until P4) beside Last session measured (from the hooks), FR-1.3's edit dialog
badging detected fields, the hooking toggle through HookingConsent -- a refusal, a
mismatch or a failure is a persistent InfoBar on the page, never a toast; a blocked
row disables the switch with Safety_Blocked_Toggle_Format inline; unverified stays
enabled and says so; auto-disabled shows Safety_AutoDisabled_Format with re-enable --
and the Sessions DataGrid of FR-6.1 with the chips resolved through TriStateResolution.

Dashboard: LiveCaptureViewModel over SessionStarted / SessionProgress /
SessionCompleted (game, tier, elapsed, the readout at 1 Hz, measured resolution,
upscaler + quality, RT, temps, VRAM), the recent list with game names, the totals
strip (ISessionRepository.CountSinceAsync is new; the Sqlite and fake repositories
implement it).

Seams: IAgentLink (AgentConnection), IPageNavigator, GameSelection, IGamePicker,
IConfirmations, IEditGamePrompt, IMessageStrip. 130 new App strings in en/vi/ja.

Tests (App, 54): FpsPresentationTests (three shapes, both negatives, live events),
FormatsTests, GameLibraryTests (scratch ledger), GameDetailViewModelTests (toggle on ->
dialog -> SetHookEnabled -> reload; refusal -> notice, blocked -> disabled switch;
remove revokes first; edit; not found; capability flags), DashboardViewModelTests
(totals, recent, the three events), PagesLoadTests -- every page and both templates
load under the real theme dictionaries on an STA thread.

Docs: 08_UI §Dashboard + §Games built notes, 16_WPFUI §Custom controls as built,
HANDOFF row 5 struck (deferred: sparkline + override flyout -> PR-6, Agent card badges
+ Repair -> PR-8, dropped .lnk). CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 06:32:19 +00:00
poli0981andClaude Fable 5.1 57e068dbfd feat(consent): FR-2.1's consent dialog -- the reviewed Safety_* family in Shared, ConsentProvenance.ConsentDialog, and the Agent's stamp behind the disclosure-version handshake (P3 PR-4) (#165)
Shared: Strings.resx + .vi + .ja with 20 Safety_* keys -- the dialog (an intro that
recommends 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; 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/PR-8 will
render (Safety_Refused_*, Safety_Blocked_Toggle_Format, Safety_AutoDisabled_Format,
Safety_Unhooked_Format, Safety_RecordWithoutMeasuring). en + vi written (owner reviews
vi); ja is the English verbatim under `safety: human review required`, enforced by
resx-audit (2 families now). Shared.Safety.SafetyDisclosure.Version = consent-dialog/1.

Domain: ConsentProvenance.ConsentDialog = 3, the only member a shipped user path
produces; GameConsentRecordTests pins the four names and the number.

Agent side: HelloAck.disclosureVersion (AgentIdentity carries it, --serve sets it);
AgentCommandHandler.StampAsync -- after the pre-scan, the client's version must equal
this Agent's: equal -> RecordOperatorAcknowledgementAsync with ConsentDialog provenance
and the Agent's clock, answered HookEnabledAck { enabled, outcome, prescan: "clean" };
otherwise Error DisclosureVersionMismatch (new code), nothing written. A composition
that wired no version still answers DisclosureUnavailable (never --serve).

App side: IAgentRequests (AgentConnection implements it; PipeClient gains
RequestEnvelopeAsync so a Refused is an answer, not an UnexpectedAck), HookingConsent
(agent unavailable / version mismatch -> no dialog; declined -> nothing sent; accepted
-> SetHookEnabled with the version shown; stamped / refused / error interpreted),
ConsentPrompt over WPF UI's ContentDialog (primary bound to the typed phrase, Enter
keeps hooking off), ConsentDialogViewModel + ConsentDialogContent. The toggle that
opens it is PR-5's.

Tests: HookingConsentTests (7), SafetyStringsTests (every key in three languages via
the satellites; vi translated; ja the English; no degrading word in any consent
string), AgentCommandHandlerTests mismatch + stamp with a fake clock, PipeEndToEndTests
wrong version -> mismatch, our version -> ConsentDialog on the row.

Docs in place: 19_SAFETY §User-facing consent (built; console verb = developer path),
09_I18N (four members; the family arrived), 07_IPC (HelloAck, SetHookEnabled as built),
06_DATA_MODEL (fourth name), HANDOFF item 2 + row 4 struck, D14 as built, CLAUDE.md,
CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 13:13:58 +07:00
poli0981andClaude Fable 5.1 e41a28f45a feat(persistence): the ports the UI reads and writes, the settings registry (D16), schema 0002 with the FR-8.3 overrides on the UI's table, and the display producer (P3 PR-3) (#156)
Ports (Application.Persistence): ISessionRepository gains FindByIdAsync, ListByGameAsync
(newest first, bounded), SummariseByGameAsync (count / hooked / playtime / last played per
game in one query), FindSegmentsAsync, FindSensorsAsync. ISessionAnnotationRepository (new):
tags as a JSON array, notes, and FR-8.3's per-session overrides -- on session_annotations,
the UI-owned table, NEVER on sessions (06_DATA_MODEL §Writer ownership), beside the
measurement rather than over it so clearing an override 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, changed fields marked `user` in field_provenance), SetTriStateDefaultAsync,
RemoveAsync(keepSessions) (FR-1.4: keep = games.removed_at and a later launch restores the
row; delete = the cascade). ILegalAcceptanceStore.RecordAsync / ListAsync. GameRow carries
the metadata, the defaults, hook_consent_at, hook_prescan_state, removed_at.

Settings registry (D16, closes 20_OPEN_QUESTIONS §G's row): SettingsRegistry (12 keys with
kind, default, range/choices, who reads) + RegisteredSettings over ISettingsStore --
validating writes, tolerant reads, nothing cached. SettingsRecorderPolicy resolves
capture.min_session_s, retention.raw_sessions_per_game (0 = unlimited -> a sweep that keeps
everything) and telemetry.interval_ms at each session start through the new IRecorderPolicy
on SessionRecorder, whose poller factory now takes the session's options; an operator's
bounded --seconds N keeps its bound. The App's appearance keys are the registry's.

Schema: 0002_annotation_overrides_and_removal.sql -- the first append, ALTER TABLE ADD
COLUMN only (three override columns, games.removed_at); LatestVersion = 2.

Display: Infrastructure.Recording.PrimaryDisplay (EnumDisplaySettingsW via CsWin32) fills
hardware_snapshots.display_res / display_hz, "null until P3" since PR-B.

Tests: the four PR-B adapters that had none (game, hardware snapshot, settings, legal),
the annotation repository incl. the resolution over stored rows, the session queries incl.
NFR-4 measured (100-session game lists in a few ms against the 500 ms ceiling), the
registry both directions, the policy, the resolution, the display producer. 224
Application, 264 Infrastructure.

Docs: 06_DATA_MODEL §Settings registry (new), §Writer ownership, the tables, §Retention,
§Migrations (0002); 20_OPEN_QUESTIONS §G row closed; HANDOFF §P3 row 3 struck with the one
deviation (no IRtOverrideRepository -- the overrides are the annotation row's) and D16/D8
amended; ISettingsStore's own doc no longer calls the registry open. CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 12:59:33 +07:00
poli0981andClaude Fable 5.1 e16185f60e feat(app): the first .resx family with its generator and gate, and the App shell -- Generic Host, FluentWindow, the Agent pill over the pipe, theme + language persisted (P3 PR-2) (#155)
resx: src/FrameLedger.App/Strings.resx + .vi + .ja (65 keys; ja machine-drafted,
marked `review`), tools/resx-gen.ps1 writing the committed Strings.Designer.cs (the
SDK-style WPF project runs no ResXFileCodeGenerator), tools/resx-audit.ps1 as
build.ps1 step 15: -SelfTest (11 fixture cases, 9 red) then live. Per family:
identifier keys, non-empty neutral values, EXACT key sets in vi/ja, Safety_* in ja
marked `safety: human review required` with the English verbatim (that is how "shown
as en until signed" is true by construction) or `safety: reviewed by <name>`, and the
accessor current. No family under src/ is red, not green.

App: Generic Host per 16_WPFUI §App bootstrap; FluentWindow with the Agent pill in
the TitleBar, the Menu row (unbuilt items say so in a snackbar), NavigationView with
Settings in the footer, the offline InfoBar + Retry, SnackbarPresenter,
ContentDialogHost. Theme (Light/Dark/System + SystemThemeWatcher) and language
(rebuilds the shell in the new culture) persisted in `settings` under D16's
ui.theme/ui.language through SqliteSettingsStore -- the App opens ledger.db directly
(06_DATA_MODEL §Writer ownership, D15). Services.AgentConnection is 07_IPC §Client
behavior as a state machine over PipeClient: 8 x 250 ms, start
FrameLedger.Agent.exe --serve beside the App when absent, Hello/GetStatus, keepalive,
the event stream, retry every 5 s. Dashboard shows the Agent card with N/A until
answered; Games/Compare/Logs are empty states. Serilog logs/ui-.log per 10_LOGGING.

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 (async void overrides are VSTHRD100 here); and
ApplicationThemeManager.Apply(..., updateAccent: true) must precede the first
window's XAML or the accent resources are missing at first Measure (measured:
XamlParseException 'SystemAccentColorPrimary').

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; 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. First window measured at 1.3 s.

Docs corrected in place: 09_I18N (generator, audit as built, the ja Safety_* rule),
12_BUILD line 15, 13_CI_CD, CLAUDE.md (App is the shell; resx-audit exists),
08_UI §Shell built note, 16_WPFUI deviations + gotcha, 10_LOGGING ui log, HANDOFF
§P3 row 2 struck (Shared's family waits for PR-4 on purpose). CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 12:45:40 +07:00
poli0981andClaude Fable 5.1 bf3e9f22ba feat(ipc): the command pipe, command half -- SetWatchlist, LaunchGame, SetHookEnabled (pre-scan, no stamp yet), pause/resume, StopSession, UpdateRules, Shutdown (P3 PR-1b) (#154)
07_IPC §Messages' UI->Agent rows, built under the one rule of §The pipe is not a
trust boundary: the Agent establishes each fact itself. Application.Ipc.AgentCommandHandler:

- 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; 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 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. AgentRequestHandler resolves the command handler lazily: eagerly it is a
DI cycle (server -> handler -> commands -> orchestrator -> recorder -> observer ->
publisher -> server) that hung the first e2e run, measured and recorded.

Tests: AgentCommandHandlerTests (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), ExitStatusMapper / RecordedSessionEvents
rows for StoppedByUser, and PipeEndToEndTests grows two scenarios over the real
composition and a real ring: watched -> narrated -> paused (status says so, state
stays capturing) -> resumed -> stopped by guid (StoppedByUser, normal, harness alive)
-> the session-less commands incl. a real pre-scan answered DisclosureUnavailable;
and LaunchGame starting the harness in launch mode, narrated to TargetExited.

Docs: 07_IPC §Messages (each command row as built), 04_CAPTURE (watcher row, the
user stop), 01_ARCHITECTURE, HANDOFF §P3 (row 1b landed, D12 as built), CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-13 20:26:56 +07:00
poli0981andClaude Fable 5.1 9c8c4ec099 feat(ipc): the command pipe, read half -- Shared.Ipc contracts + framing, the Agent's pipe server under --serve, the session narration and the 1 Hz live progress (P3 PR-1) (#153)
07_IPC §C's read half, built. FrameLedger.Shared.Ipc: the envelope, the read-half
message set (Hello/HelloAck, GetStatus/StatusAck, Ping/Pong, Error, seven Agent->UI
events), IpcJsonContext (source-generated, camelCase, nulls omitted, unknown members
skipped both ways) and IpcFraming (4-byte LE length + UTF-8 JSON <= 1 MB, one write
per frame). Infrastructure.Ipc.PipeServer creates the pipe through CreateNamedPipe
(CsWin32) with the DACL stated as SDDL -- D:P(A;;GA;;;<user>)(A;;GA;;;BA), what
20_OPEN_QUESTIONS §G asked for -- PIPE_REJECT_REMOTE_CLIENTS, two instances with a
slot each, and the client's token user compared by impersonation on its first frame; a
stranger is disconnected unanswered and counted. PipeClient is the UI's end.

Application.Ipc: AgentRequestHandler answers the three requests (Error for unknown /
malformed / protocol mismatch / handler fault, connection kept); SessionEventPublisher
is the recorder's new second observer (ISessionObserver, HANDOFF §P3 D13) --
SessionStarted at the attach, SessionProgress once a second only while a client
listens, the finished session's events through RecordedSessionEvents' reason->event
table; AgentStatus is the snapshot GetStatus reads. SessionProgressCalculator
computes the 5 s 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 -- FgLadder.PresentedQualifier now,
one function for the row and the pipe. Vocabulary.ExitStatusText is the one spelling
of exit_status. CaptureOutcome.Verdict carries the verdict that FIRED on a safety
unhook. The Agent hosts the server under --serve only (PipeServerHostedService);
--console composes it inert. HelloAck drops etwAvailable, gains pid.

Tests: IpcFramingTests, IpcCodecTests, PipeServerClientTests (a real pipe in-process:
the SDDL, round trips, an event to two clients, a third client waiting, a malformed
frame, the refused stranger), the calculator / events / publisher suites, and
PipeEndToEndTests (Integration, agent-harness): the Agent's composition in-process on a
test-named pipe, the watcher finding a run-unique copy of hook-harness, and a client
hearing SessionStarted -> >= 3 SessionProgress a second apart -> SessionCompleted.
That test measured the watcher's file-name fallback adopting a sibling suite's harness
(recorded in CHANGELOG). Docs: 07_IPC §C, 04_CAPTURE §Threading model + §Live progress,
01_ARCHITECTURE, HANDOFF §P3 (row 1 landed, D11 as built), §G's pipe row closed.

./build.ps1 check: exit 0, 30/30 native, 736 managed tests green (Integration included).
A first run hit fl_guard's native-log case reading a 4-day-old overlay log of a recycled
pid (1008 files under the profile's logs folder); green on the rerun, not this PR's
code, and a §Traps note for the next sweep.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-13 16:59:14 +07:00
poli0981andClaude Fable 5.1 d5c801a516 docs: P3 PR-0 -- the P2 sweep; HANDOFF §P3 START HERE with the slice table and D11-D17; roadmap §P3 takes the full 08_UI (#152)
Docs and tools only, no src/. What PR-G's closing sweep left stale, corrected in
place: coverage-gate.ps1's "empty today" prose (armed since PR-A/C), 13_CI_CD's
"nine" Integration cases (20 across six classes) and its claim that the signer
probe lacks `if: always()` (it has carried it since #137, before the failure the
bullet describes -- why the probe was not read is now recorded as unmeasured),
09_I18N's "two members" (three since PR-F), 17_HOOK_ENGINE's cite of a §H9 that
the P0 spike answered and removed, ci.yml's census comment still promising "the
next PR wires the script" after vulkaninfo.exe read absent twice.

HANDOFF: P2's START HERE struck; §P3 is the head, with the slice order (0, 1,
1b, 2, 2b, 3-9), what makes each fail on unmodified main, and decisions D11-D17
(pipe transport + ACL, commands as one more Channel producer, SessionProgress as
a third ICaptureObserver, Safety_* in Shared with a version in HelloAck, the App
opening ledger.db under 06_DATA_MODEL's writer ownership, the settings registry,
FL_MOCK under --data-dir only). D1/D5/D6/D10 labelled where they were cited by
number; 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.

What P2 still owes is unchanged: spike-notes §14's four slots, all empty, all
the owner's.

./build.ps1 check: exit 0, 30/30 native, 671 managed tests green.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-13 08:39:30 +00:00
poli0981andClaude Opus 5 9b3f5f5fb3 test(agent): kill-and-recover end to end, the FPS-impact runbook, and P2's closing sweep (P2 PR-G) (#151)
PartialRecoveryEndToEndTests 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 and the session is past the product's 30 s discard threshold,
Process.Kill's 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.

Three things the first version got wrong, kept as comments where they bit:
the two Integration classes ran in parallel and started two harnesses of one
image, which TargetResolver correctly refused as ambiguous (they now share an
xUnit collection); PartialSessionFile.Read cannot open a file a live Agent
holds, so the test reads the bytes with FileShare.ReadWrite and calls the same
Parse; and a 2.5 s prefix was DISCARDED by recovery, correctly -- the test
waits the threshold out rather than adding a knob to shrink it.

--partial-flush-seconds 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
14_TESTING 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 itself, prompts for the game's
own benchmark average, and prints the spike-notes block. It does not measure
FPS and says so first: FrameLedger's frame times exist only in the hooked leg,
so they cannot be both sides of the comparison. Overlay resident size is left
unmeasured rather than guessed -- reading the target's memory is rule 4.

spike-notes §14 holds three empty slots with the exact commands (the milestone
row against a title's menus, §S1's launcher-fronted election, the FPS table)
and says in its first line that nothing in it has been run. 14_TESTING item 2
now reads "not measured" rather than nothing. HANDOFF's P2 section states what
is left -- two measurements, no code -- and gains a P3 head: the pipe (D10),
and FR-2.1's dialog, which retires ConsentProvenance.AgentConsoleOperator and
must not gain its enum member before the reviewed text exists.

Also carries what merging P2's stack measured about CI itself: THREE failures
in eight gate runs, every one a Category=Integration case, every one green on a
re-run of the identical commit, none caused by the code under review. Two were
guard scans failing -- GuardedInjectAsync(...).IsAllowed false (§S19(b)'s
fragment/signer shape) and ProcessTreeUnavailable, "could not establish the
scan set", which §S19(b) does NOT cover -- and one was ours: CaptureSessionTests
opens a real SQLite ledger, Microsoft.Data.Sqlite pools connections, and the
pooled handle on ledger.db outlived DisposeAsync, so the recursive
Directory.Delete threw IOException and xUnit blamed an unrelated test. That
fixture was the ONLY one in the repository catching just DirectoryNotFoundException
-- every sibling already catches IOException -- and it is the one holding a
database. Fixed here.

13_CI_CD and HANDOFF carry the rest as observations rather than fixes: re-run
first, and if it reproduces read the module list and the scan-set reason rather
than the test. Two traps inside that one, both recorded: ci.yml's signer probe,
the step that would name the refusing module, runs AFTER the gate, so the one
run that needed it printed nothing; and `gh run rerun --failed` rewrites the
original run's conclusion, so the run history shows those three failures as
successes and anyone measuring the flake rate from it measures zero. An earlier
draft of this PR said the refusal fires "one run in the low tens" -- written
after the first failure and wrong by the end of the same evening. Corrected in
place rather than deleted.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 08:53:28 +07:00
poli0981andClaude Opus 5 dad3adbff6 feat(agent): the Agent host -- --serve (watcher -> orchestrator -> recorder), --console verbs, the consent grant (D4) and the kill switch as the gate's fourth input (D7) (P2 PR-F) (#150)
FrameLedger.Agent is a Generic Host now. Composition.AgentServices registers
every Application port to its one shipped Infrastructure 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. The orchestrator decides nothing
about hooking: the recorder's loop reaches HookedCaptureGate as a console
verb does.

--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. The surface is pinned by AgentCommandLineSurfaceTests.

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; 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 GuardMirrorTests 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 Vulkan 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, the unbuilt flags' exit 2. ProcessWatcherTests,
ProcessTreeAndElectionTests, CaptureOrchestratorTests,
ToolhelpProcessSnapshotSourceTests, SettingsKillSwitchTests, the gate's
kill-switch case, the loop's mid-session case, the store's provenance
round-trip; GameConsentRecordTests pins three provenance names.

Docs: 04_CAPTURE (watcher built, election, threading row), 12_BUILD (the
surface), 07_IPC (pipe is P3), 19_SAFETY (D4/D7 built), 20_OPEN_QUESTIONS
(S27 restated for PR-F, S24 answers, G Agent lifecycle), 01_ARCHITECTURE,
06_DATA_MODEL (third provenance, settings key), 15_ROADMAP (milestone's
technical half), CLAUDE.md, HANDOFF (D4/D7 built, two traps), CHANGELOG.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-10 08:43:06 +07:00
poli0981andClaude Fable 5.1 222dd10083 feat(telemetry): the NVAPI bridge -- FrameLedger.NvapiBridge.dll, L3 NvapiTelemetrySource, and the NGX probe in-process (P2 PR-E2) (#149)
A new native target, src/native/FrameLedger.NvapiBridge/, is the C ABI the
managed side reaches NVAPI through: 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 (FL_NV_BAD_SIZE) rather than read. It 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)
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 no non-deprecated memory-info call, so L1's PDH
counter keeps it), and NvapiNgxStateProbe, the INgxDriverProbe in-process.
The capture host composes L1 + L2 + L3 under the composite 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 run of the mirror
test found (TypeInitializationException: a resolver is already set). The
guard claims its name as required (absent throws); the bridge as optional
(absent is a missing layer that reports itself).

Tests: ctest fl_nvapi_bridge (every export, BRANCH: line required);
NvapiBridgeMirrorTests (both mirrors' sizes against the DLL's answers, fails
rather than skips when the DLL is not staged); NvapiTelemetrySourceTests and
NvapiNgxStateProbeTests over a scripted bridge. versioninfo-check.ps1
requires the new DLL's version block.

Measured on the dev box (RTX 5080, 616.64 r616_41), written into
18_GPU_VENDOR_APIS §L3: core 35 °C, GPU domain 0 %, 2670 / 15001 MHz,
throttle mask 0, PCIe x16; memory-temperature and fan bits clear at an idle
desktop.

Docs: 18_GPU_VENDOR_APIS (§Abstraction, §L3 built note, function table,
measured matrix), 12_BUILD (§Targets, the .targets list), 03_METRICS and
20_OPEN_QUESTIONS §H5 (probe in-process), CLAUDE.md (pinned stack, the two
facades), legal/THIRD_PARTY_NOTICES (NVAPI row), CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-10 08:18:23 +07:00
poli0981andClaude Fable 5.1 b881ed2297 feat(recording): the session recorder -- .partial, five-step finalize, exit classification, crash auto-disable, recovery; the first hooked session in SQLite (P2 PR-D) (#148)
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 (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 --
per-stream frame times with the gap bit where an interval is not a frame
time, 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;
CrashAutoDisablePolicy counts only crashes within 60 s of the attach and
disables on the second.

The .partial: 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, HardwareSnapshotSource. 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 (ledger: session ... SAVED as
sessions.id=N; a 5 s discard threshold for bounded operator captures; a
recover verb) and CaptureHostEndToEndTests asserts the row, the blobs and
the deleted .partial after a real launch.

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 (pre-injection; the Overlay is untouched).

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-10 07:56:24 +07:00
poli0981andClaude Fable 5.1 97fc9d9707 refactor(capture): promote the capture path into Application and Infrastructure -- CaptureSession over ports, the CaptureHost a thin shell (P2 PR-C) (#147)
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. ICaptureSink,
CaptureOptions, CaptureOutcome (was CaptureResult), SessionEndReason,
SessionEndClassifier, FocusTally, RuntimeModuleSet/Info, CensusNames,
SlTagCensusNames, ExecutableMarkers/Marker, NgxDriverState/NgxOverrideFlags/
NgxProbeOutcome move beside it.

Infrastructure.Capture holds the OS adapters: ShmRingAttacher + ShmCaptureSink
over ShmRingReader (no interface, no second consumer), HeldProcessLivenessSource
+ ProcessTargetLiveness (§S29(e)), TargetResolver (path only, never a pid; its
one report line through a callback, not the host's console) + ChromiumGpuProcess,
ProcessLauncher (an instance over the Vulkan layer's environment; the duplicated
enable-variable constant is gone), RuntimeModuleSnapshot, ExecutableMarkerScan.
DrainResult moves to Shared so Application can read it.

Report text stays with the report (NgxDriverStateText, ExecutableMarkersText);
NgxDriverProbe stays in the host until PR-E2 puts it in-process. The loop's
tests move 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).

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09 19:02:43 +00:00
poli0981andClaude Fable 5.1 81aa925bdd feat(telemetry): L1 BaselineTelemetrySource, CompositeTelemetrySource and the 1 Hz fl-telemetry poller (P2 PR-E1) (#146)
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. The
engine-utilisation counters are deliberately not read (§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.

Measured on the dev box (RTX 5080): identity 32.0.16.1664, 1301 MB dedicated
in use at an idle desktop, moving tick to tick. §M7 and §M8 closed by the
code taking the shape they asked for; §M10 decided. Hook-path overhead: none
(managed only, nothing in the game). 18_GPU_VENDOR_APIS §Abstraction/§L1/
matrix and CLAUDE.md corrected in place.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09 14:25:49 +00:00
poli0981andClaude Fable 5.1 32eb941c46 feat(infrastructure): the SQLite ledger -- 0001_init.sql, migrations, SqliteGameConsentStore, the repositories and the blob codecs (P2 PR-B) (#145)
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 (embedded scripts, one
transaction each, under a session-local mutex; a ledger newer than the build
is refused via LedgerSchemaException rather than 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, driver-reported rungs, the withheld none),
fg_source with none in its domain and NULL = not measured,
games.hook_prescan_state (nothing clears hook_blocked_reason -- decision D9),
consent provenance + disclosure version, the fingerprint. Every *_at is
unix-ms UTC, stated in the script.

SqliteGameConsentStore replaces the capture host's file store: every case of
FileGameConsentStoreTests re-targeted, the host opens its OWN ledger.db
beside its binary (decision D5) so the Agent stays the sole owner of
%LOCALAPPDATA%\FrameLedger, and CaptureHostEndToEndTests run consent-from-
SQLite through to FlGuardedInject. Domain's InternalsVisibleTo names
Infrastructure now, not the CaptureHost; 20_OPEN_QUESTIONS §S27 is restated
on that basis.

Also: SqliteGameRepository, SqliteSessionRepository (row + segments +
frame_blobs + sensor_blobs in ONE transaction; ExistsAsync by guid;
retention), SqliteHardwareSnapshotRepository (hash-deduplicated),
SqliteSettingsStore, SqliteLegalAcceptanceStore (read-only -- decision D8),
the Application ports and DTOs (SessionRow generated column for column from
one table), Domain.Sessions, and Infrastructure.Blobs.SeriesCodec /
RenderResCodec (deflate-le-v1, NaN refused at encode time).

ShmDrainIntegrationTests.TheReaderReportsRecordsItLostWhileItWasNotDraining
now polls for the writer to leave INIT before asserting READY: the handshake
is published before the present hooks and the present hook records frames
before the READY store, so a case that laps the ring in ~50 ms read INIT
about one run in four -- on unmodified main as well as here.

Not in this PR: any producer of a sessions row (PR-D), the Agent's consent
verb (PR-F), a pipe. Hook-path overhead: none (managed only). 06_DATA_MODEL,
04_CAPTURE §The guard, 20_OPEN_QUESTIONS §S27 + §G, CLAUDE.md corrected in
place.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09 13:52:27 +00:00
poli0981andClaude Fable 5.1 d9f2f4ae28 feat(domain): FrameLedger.Domain.Metrics -- the 03_METRICS calculators with their goldens, and the capture host's consumer re-pointed at them (P2 PR-A) (#144)
Domain gains Metrics/: FrameTimeSeries (QPC -> ms, gap intervals EXCLUDED),
Percentile (linear), FrameStatistics (median / lows / min / max / sigma with
the FR-4.8 guards at exactly 1,000 and 10,000), RollingMedian (19, truncated
symmetric edges) + StutterDetector, VramAggregates / LatencyAggregates /
SeriesAggregates, and — ported out of FrameLedger.CaptureHost with their
tests — FgWindow (refusals as FgRefusalKind + numbers; the English stays with
the report as FgRefusalText, byte-identical), UpscaleExtent, SegmentBuilder,
RecordWindow, Tri, RtVerdict (+ RtSummary) and HdrVerdict.

Domain references nothing, so the calculators consume FrameSample /
WriterFacts with Domain's own enums; Application gains a reference to Shared
(HANDOFF §P2 decision D1) and Application.Metrics.FrameSampleMapper is the one
place a record becomes a sample, resolving the two writer-state sentinels to
null. MetricEnumMirrorTests pins every Domain enum to its Shared twin in both
directions.

coverage-gate now evaluates the 95% floor it had never evaluated: 20 classes
at or above it, Domain at 98.2%. Canary: nearest-rank in Percentile.Linear
turns exactly the six interpolation goldens red and nothing else.

Not in this PR: the FG ladder as a Domain verdict (still MeasuredFacts'
strings; lands with the recorder that stores fg_mode, PR-D). Hook-path
overhead: none (managed only). 03_METRICS, 14_TESTING's stale FG-ladder
golden and CLAUDE.md §Solution layout corrected in place.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09 09:48:42 +00:00
poli0981andClaude Fable 5.1 6abc58584e docs: P2 kickoff -- HANDOFF "P2 START HERE" with the owner's decisions, §S24's "◐ zero" corrected, CLAUDE.md's stale harness and telemetry lines (PR-0) (#143)
HANDOFF held one live START HERE that was already CLOSED and none for what
comes next. The new §P2 carries the PR order (A, B, C, E1, D, F, E2, G),
what each fails on unmodified main, why that order, and the four decisions
the owner took on 2026-09-09: the Agent ships a console consent verb (the
§S27 basis change), the FR-2.4 kill switch is HookedCaptureGate's fourth
input, FR-11 is not a consent precondition in P2, and the NVAPI bridge
lands after the milestone. §S24's "◐ zero" is corrected in place (S1 and
H11 are ◐); CLAUDE.md no longer says the harness's Vulkan/OpenGL modes and
the first telemetry source are unwritten.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09 09:09:54 +00:00
poli0981andClaude Fable 5.1 d9f443ecf7 feat(overlay): compare-and-restore per inline patch, the native event log, and opengl32!wglSwapBuffers (P1 item 4) (#141)
* feat(overlay): compare-and-restore per inline patch, the native event log, and opengl32!wglSwapBuffers (P1 item 4)

Unhook path. StopObserving no longer calls MH_DisableHook(MH_ALL_HOOKS): every
patch this DLL makes is in a registry (target, detour, name -- PatchTarget and
the two direct sites), and each is restored only while the bytes at its target
are still the jump MinHook wrote for us (fl_patch_check.h StillOurs: E9 rel32
-> FF 25 relay -> our detour, or the hot-patch EB F9 form). An overlay that
patched after us chains through our jump and the blanket restore would have
removed its hook silently -- §H7 in its inline form. A patch that is no longer
ours is left in place (UNHOOK_DECLINED) and our detour stays forwarding.
ctest fl_unhook_inline proves the predicate both directions against a real
MinHook patch and a simulated foreign relay (placed within 2 GB, as MinHook's
own relays are -- the first run crashed on a truncated rel32).

Native logging (17_HOOK_ENGINE §Native logging). A static ring of 256 x 64-byte
events -- RING_CREATED, PRESENT_HOOKS, HOOK_INSTALLED (per patch, with the
target), SYMBOL_MISSING (once, only when the module is mapped), FAULT (the
exception code and the hook's __func__, from the SEH handler, never a body),
STOP, UNHOOK_RESTORED / UNHOOK_DECLINED, LOADER_DETOUR, SUPERVISION_LOST --
flushed to %LOCALAPPDATA%\FrameLedger\logs\overlay-<pid>-<stamp>.log at the end
of InitThread, when the Agent bumps the new FlControlBlock.logFlushRequested
counter (@16, from reserved[]; mirror + layout dump updated) and when the
watchdog exits after any stop. Never mid-frame, no allocation. The CaptureHost
requests the flush at session end and prints the file's notable lines.

OpenGL. opengl32!wglSwapBuffers is a MinHook inline patch on the flat export:
api = OpenGL, output size from GetClientRect on the DC's window (first sighting
and every 256th present), no PRESENT_ARGS. Installed at init when opengl32 is
mapped and lazily on the watchdog, which the LoadLibrary detour now wakes for
opengl32.dll. hook-harness --opengl --hold-presenting N: a real context on a
hidden window, SwapBuffers'd through gdi32 as a title does, on Microsoft's
generic renderer -- runs on CI. ctest fl_guard [opengl] / [log].

D3D9: struck from the P1 line per 20_OPEN_QUESTIONS §Scope decisions (x64-only
Overlay; those titles are 32-bit); nothing built.

Docs: 17_HOOK_ENGINE §Unhooking / §Native logging / §Presentation row / the
system-module rows / §Test harness, 07_IPC control block, 10_LOGGING, 12_BUILD,
15_ROADMAP (P1 core done, feature rows listed), HANDOFF (P2 next), CHANGELOG.

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

* fix(guard,tests): a target that dies under the launch-mode scan reads LaunchTargetExited, and the Vulkan e2e case skips on the harness's own [SKIP] line (CI: a runner with a loader but no ICD)

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 20:44:13 +07:00
poli0981andClaude Fable 5.1 1ed67ba7f2 feat(vklayer): vkQueuePresentKHR intercepted -- the layer owns the ring, records every present, and stops itself on the present path (P1 item 3, §S2 part three) (#140)
In a process both gates admitted, the layer creates the same ring the Overlay
would -- fl_shm_host.h is now the one home of the DACL, the name, the mapping
and the handshake for BOTH capture sides (the Overlay calls it too) -- 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. One ring per process: the first creator owns it,
the other stays inert AND forwarding -- the first fixture run measured
VK_ERROR_DEVICE_LOST when the layer had registered no next pointer, so the next
pointers now come before the ring and the ring failing only ever means
"observe nothing".

§S2 part three lands with it, on the present path (the layer owns no thread):
unhookRequested -> UNHOOKED within one present; guardTicks not advancing for the
07_IPC deadline -> UNHOOKED; pauseRequested -> no record, still forwarded.
"Stops" is passthrough forever 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: ticks every 600 ms keep it alive past the deadline,
1.8 s without one stops it).

Real loader: hook-harness --vulkan --hold-presenting N (vulkan-1 via
LoadLibraryW, hidden window, exit 77 = cannot run here) and ctest
fl_vklayer_real, which points the loader at the build tree's manifest through
VK_ADD_IMPLICIT_LAYER_PATH -- measured honoured by 1.4.357 with no registry --
and skips on CI: 241 records in 4 s. vklayer-blastradius.ps1 hand-run, green.

Launch mode: a target that mapped vulkan-1.dll is the layer's --
Reason::kTargetIsVulkanLayered (26): the full guard runs, nothing is injected,
the host attaches to the layer's ring with launch mode's budget. Vulkan WINS
over a D3D runtime beside it, because the NVIDIA Vulkan ICD maps dxgi + d3d12
itself and presents through a DXGI chain (measured: the injected Overlay
recorded 295 DXGI presents of a Vulkan swapchain). The CaptureHost's launch
hands the process the layer's environment (VkLayerLaunchEnvironment: manifest
under %LOCALAPPDATA%\FrameLedger\vklayer, enable variable, enable-list line for
the session) and stages FrameLedger.VkLayer.dll beside itself.

Docs: 17_HOOK_ENGINE §Vulkan + Presentation row, 20_OPEN_QUESTIONS §S2 ✅ /
§S24 / §S29(d), 04_CAPTURE, 12_BUILD, spike-notes §2 (two measurements),
legal/ACCURACY.md + its two copies, README, DISCLAIMER §2, 15_ROADMAP, HANDOFF,
CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 19:38:20 +07:00
poli0981andClaude Fable 5.1 f61d35f7f6 feat(injector): launch mode as "inject late" -- the guard waits for a presentation runtime, then runs in full (P1 item 2, §S1 / §S13(c)) (#139)
A CREATE_SUSPENDED target has loaded nothing and EnumProcessModulesEx fails
against it (§S1, measured), so launch mode cannot be create -> guard -> inject
-> resume. Built shape: start -> the guard WAITS -> the full guard -> inject.

Guard: GuardedInjectWhenReady(pid, dll, timeoutMs) / ABI FlGuardedInjectWhenReady
polls the target every 50 ms through the module seam -- matching no blocklist;
a failing enumeration is "not yet", never a pass -- until dxgi+d3d11/d3d12,
opengl32 or vulkan-1 is mapped, then runs GuardedInjectImpl unchanged. Two new
reasons end the poll with nothing injected: LaunchTargetExited (24) and
LaunchNoPresentationRuntime (25). ctest fl_guard [launch], five cases: injects
on the first enumeration showing the runtime and not one before; exit-first and
budget-out each answer their own reason; anti-cheat mapped beside the runtime is
the full scan's refusal; the real seam against hook-harness injects in 15 ms.

Overlay: FlWriterState.dxgiPresentsBeforeHook @60 -- GetLastPresentCount at the
first hooked present on the first hooked chain, i.e. presents that ran before
the hook was in; 0xFFFFFFFF until a present is seen, set BEFORE the present
hooks go in (the first placement, after them, lost the race to an 8 ms
presenter -- caught by the fixture). Took the last reserved word; no layout
bump; the writer state now has no slack.

CaptureHost: `launch --exe <path> [--args "..."] [--seconds n]`; ProcessLauncher
(handle held from birth, FRAMELEDGER_ENABLE_VK_LAYER=1; the host never
terminates what it launched); CaptureLoop.RunLaunchedAsync sharing the gate,
attach and drain with attach mode; HookRequest.WaitForPresentationRuntimeMs
routes the same gate through IAntiCheatGuard.GuardedInjectWhenReadyAsync (the
port's fourth method, primitives only); the report prints the wait and the
before-hook count (LaunchNote). NoSecondMatcherTests 3 -> 4 as a reviewed act.

Docs: 04_CAPTURE §Launch mode (the shape, why not CREATE_SUSPENDED, what it
measures), 01_ARCHITECTURE, 19_SAFETY item 1, 20_OPEN_QUESTIONS §S1 ◐ /
§S13(c) ✅ / §S24, 17_HOOK_ENGINE, 15_ROADMAP, HANDOFF, spike-notes, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 17:42:01 +07:00
poli0981andClaude Fable 5.1 627995068d feat(overlay): the LoadLibrary detour -- lazy-install wake within milliseconds + the in-process anti-cheat stop (P1 item 1, §S6) (#138)
kernelbase.dll!LoadLibraryExW is patched from InitThread after the present hooks
(17_HOOK_ENGINE §DLL entry step 3). The body calls the original first, skips
data-file / resource mappings, reads the mapped module's own file name into a
stack buffer and compares its base name against two fixed tables:

- FL_HOOK_INVENTORY + FL_RUNTIME_CENSUS: a match bumps a saturating 15-bit wake
  count and signals the watchdog's new auto-reset event, so the lazy installers
  run within milliseconds of the module rather than on the next 1 Hz tick.
  Measured in ctest fl_guard [loader]: 94 ms against a 500 ms bound.
- the compiled floor's MODULE families (fl_ac_floor.generated.h, prefix,
  case-insensitive, allocation-free): a match CASes the family's 1-based index
  into earlyStopFamily; MayObserve or the watchdog, whichever is first, calls
  StopObserving(FL_STATUS_STOPPED_BLOCKLISTED). ctest fl_guard [S6]: a decoy
  named EasyAntiCheat_fl_fixture.dll loaded 2.5 s in stops the Overlay with the
  index the test computes from the same table, unhookRequested still 0,
  writeIndex frozen.

The detour installs nothing inline (§H2). Exact names only: the fragment and
signer tiers stay the host's 30 s scan, so the Disclaimer's window is unchanged
(19_SAFETY §During a session, the in-process half).

FlWriterState gains loaderSignals @56 and earlyStopFamily @58 from reserved[]
(no layout bump; mirror + fl-layout-dump updated). hook-harness gains
--load-after-ms N PATH. The CaptureHost reads both words (Consume/EarlyStop.cs):
"loader detour:" and "EARLY STOP" report lines, the family named from the staged
rules file, SessionEndReason.WriterStoppedBlocklisted -> exit 5.

Docs: 17_HOOK_ENGINE §DLL entry + the one system-module hook row, 19_SAFETY,
20_OPEN_QUESTIONS §S6 ✅ / §S24 / §H2, 15_ROADMAP P1, HANDOFF, CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 09:46:03 +00:00
poli0981andClaude Fable 5.1 c5932cc115 P0 closing sweep — criterion 1 amended, criterion 2 met; §S19(c) and §S23-6 closed by a gate each, §S29(d) on a CI measurement, six deferrals written (#137)
* docs+tools: P0's closing sweep -- criterion 1 amended, criterion 2 met; §S19(c) and §S23-6 closed by a gate each, §S29(d) pre-committed on a CI measurement, six items deferred with rationale

The owner's "theo bảng" (2026-09-06). Criterion 1: the quality preset reads N/A on every
title by measurement (tags carry no size or preset on D3D12, NVIDIA's override fields are
the override's, XeSS is closed by licence) and an honest N/A is the correct value rule 7
asks for; upscaler, render->output, FG factor and RT verified against nine titles' menus.
Criterion 2: §S24 counts zero S-items against it, with S23-2 (a GitHub setting) outside
any PR.

- §S19(c): rules-validate gains canary 3 -- the shipped document mutated to action
  "allow" and to signerField "CN" must be rejected by the schema (proven red by loosening
  the const in a temp copy). The policy is code; the fields exist so the data cannot say
  otherwise.
- §S23-6: legal/ACCURACY.md is the one accuracy block, embedded verbatim in README.md
  and DISCLAIMER.md §4 between markers; tools/accuracy-check.ps1 (build.ps1 gate, four
  self-test cases both directions) fails on drift, missing markers or an empty source.
  The block is 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; rows pre-committed -- present: the
  blast-radius script becomes a CI step; absent: deferred on that measurement.
- Deferred with rationale in the entry and phase in §S24: S6 and S2 part three (P1),
  S23-3 (P3), S4 signing, S20 feed half, S14 store-id half (P4).
- 15_ROADMAP and HANDOFF: P0 closed, P1 starts.

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

* docs: §S29(d)'s census read off the sweep run -- loader present, vulkaninfo and ICD absent; deferred on that measurement with the reopen condition written

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 09:07:04 +00:00
poli0981andClaude Fable 5.1 42e15c9dbd feat(guard): the signer half -- "name fragment AND not signed by a known vendor", under a compiled-in bound; -SkipIntegration dropped from CI (§S19(b) row G1) (#136)
Since 2026-08-05 the guard refused FrameLedger's own test host on CI: a .NET host
loads System.Security.Cryptography.ProtectedData.dll, `protect` is a heuristic
fragment, and the signer conjunct was unwired. 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 in ~2-4 ms and no verdict changes
without a network. The owner chose the bound (option 1) on 2026-09-06.

- Sources::ModuleSignerOrganisation (fl_guard_sources.cpp, never fl_ac_rules.cpp):
  WinVerifyTrust WTD_CHOICE_FILE under WTD_REVOKE_NONE | WTD_CACHE_ONLY_URL_RETRIEVAL |
  WTD_SAFER_FLAG, then the signing certificate's subject O= -- fixed buffers, no
  allocation; kFailed for everything short of a verified, readable organisation.
- IsCompiledTrustedSigner: the five organisations compiled in; IsTrustedSigner now
  requires the rules file AND the binary, so a rules push can narrow and never widen.
- ModuleSinkFn: after the ours exemption, a fragment-matching module signed by a
  trusted organisation returns keep-looking (the load-order fail-open stays closed);
  the target is judged like its ancestors; everything else latches SuspiciousUnsigned.
- hook-harness --load PATH; fl_guard proves both directions against the real seams
  (the NuGet blocker allowed and the Overlay injected; our own unsigned Overlay under
  a `protect` name outside the guard's directory refused, by name) plus nine fake-seam
  cases (both lists, the target, kFailed, missing seam, pathless, load order, exact-hit
  precedence). The catalog half stays deferred with its rationale.
- ci.yml runs ./build.ps1 check with no switches: the nine Category=Integration cases
  are in the merge gate. The switch stays in build.ps1, loud.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 15:25:11 +07:00
poli0981andClaude Fable 5.1 1d72021a8a docs: the signer probe's two remaining legs read -- CI (rows G3/G4/G5 do not fire) and adapters-disabled (every verdict unchanged, row G1); the bound is what remains (#135)
The CI leg, off the new ci.yml step: the runner's NuGet copy of the blocker verifies
embedded/offline in 3.47 ms with O= Microsoft Corporation; mskeyprotect.dll is catalog-only;
cryptnet.dll loads under the offline flags; canary TRUST_E_NOSIGNATURE. The
adapters-disabled leg, the owner's run: every verdict unchanged, faster (2.14 ms), the
blocker's subject now CN=.NET with the same O= -- signerField "O" confirmed on a subject
class it had never met. Row G1 reads. The trustedSigners allow-widening bound is the
owner's decision and is asked for beside the reading.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 08:01:59 +00:00
poli0981andClaude Fable 5.1 bed369b21c ci: the signer probe's CI leg, printed -- §S19(b) rows G3/G4/G5 were never readable (#134)
ctest fl_signer_probe passes on a regular expression and prints nothing for a passing
test, so the CI leg §S19(b) pre-committed rows for was never in any log; and the native
tests run before dotnet restore, so a cold runner may not even have the NuGet copy the
probe searches first. ci.yml now runs the probe as its own step after the gate
(continue-on-error: a measurement, not a gate). HANDOFF's Separable item carries the
sequence: this leg, the owner's adapters-disabled leg, the owner's allow-widening bound,
then the guard PR that drops -SkipIntegration.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 07:41:06 +00:00
poli0981andClaude Fable 5.1 7dbfb5cb6f feat(capturehost): the FG N/A and the upscaler N/A carry their witnesses -- Hell Is Us at XeSS + XeSS-FG, and 7c item 4's string change (#133)
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 strings all had
something to say. The N/A now prints the same exclusion clauses as rung 3; the upscaler N/A
says libxess.dll is loaded and XeSS cannot be hooked or declared under Intel's licence, so
the N/A is by policy, not by ignorance. Rune Factory at FSR + FSR FG printed the
pre-committed 7b line verbatim on the same run; Cronos at XeSS read none by count.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 14:27:45 +07:00
poli0981andClaude Fable 5.1 8cf3d6f3eb feat(capturehost): rung 3 by elimination, and the executable file as the census's second witness -- HANDOFF 7b / §H11, the owner's choice over "return native" (#132)
- `frame generation: Active (technology not identified)` now prints every exclusion the
  session can make: not DLSS-G when the driver's FG word reports no feature created and no
  HUD-less / UI tag was sent (or "not excluded" without the driver's 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 (XeFG cannot be hooked or declared by licence; a
  compiled-in FSR 3 has no module), and the line says a frame generator compiled into the
  executable would read the same.
- ExecutableMarkerScan reads the exe FILE on disk once after the session (chunked with
  overlap, hits capped; ffxFsr3, ffxFrameInterpolation, xefgSwapChain move the sentence;
  FidelityFX, ffxFsr2, NVSDK_NGX, xessD3D12 are printed for the reader) and the report
  prints `executable markers:`. With no module loaded and a frame-generation-capable
  string in the file, the Presented qualifier reads MAY include generated frames instead
  of cannot -- the sentence that was wrong in the dangerous direction on Rune Factory.
- Consumer only; no hook-path change. 8 new cases; one superseded expectation updated.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 06:36:12 +00:00
poli0981andClaude Fable 5.1 237765dede docs: the AMD half of 7c complete on Lies of P; the Intel licence re-checked and unchanged; identity by elimination proposed for XeFG (#131)
Lies of P at FSR 3.1 + FSR FG on #129: Fsr3 / FsrFg / 59.77 -> 119.55 (x2 FG) / 2560x1440 ->
2560x1440, presents/frame 2.00, frames/upscale-drained 1.00, unseen 0, the NVIDIA driver's
word saying nothing was created. The owner called the AMD half done.

Intel: LICENSE.txt and inc/xess/xess.h re-fetched 2026-09-06 -- Intel Simplified Software
License, unchanged; the reversal condition has not fired. Intel's README says XeSS-FG runs
on non-Intel GPUs with SM 6.4, so an XeFG session is measurable here. §H11 carries the
in-policy proposal: identity by elimination, labelled, never XeFg as a measured identity.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-06 06:16:19 +00:00
1351 changed files with 131420 additions and 5652 deletions

No files matched your search

+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.
+48 -17
View File
@@ -92,25 +92,21 @@ jobs:
# not part of `build.ps1 check`: it mutates HKCU, and a CI runner is the
# wrong place to be registering machine-wide Vulkan layers.
# -SkipIntegration, and the reason is a MEASURED property of the hard gate
# rather than CI being awkward.
#
# The drain end-to-end tests inject the Overlay into hook-harness, which
# makes the TEST HOST the target's parent — and §S16 puts a target's
# ancestors in the scan set. A .NET host can load
# System.Security.Cryptography.ProtectedData.dll, whose name contains the
# heuristic fragment `protect`, so the guard refuses our own harness with
# SuspiciousUnsigned. Measured here on 2026-08-05; it passes on a dev box
# whose test host happens not to load that assembly, which is why CI is the
# machine that found it.
#
# That is the guard behaving as specified. The defect is §S19(b) — the
# fragment matching a benign, widely-loaded Microsoft assembly — and fixing
# it is a guard change with its own PR, not something to work around here.
# Until then these run locally and CI says out loud that it skipped them.
# NO -SkipIntegration, since 2026-09-06, and the reason it was here is worth
# keeping: the drain end-to-end tests inject the Overlay into hook-harness,
# which makes the TEST HOST the target's parent — §S16 puts ancestors in the
# scan set — and a .NET host loads System.Security.Cryptography.ProtectedData.dll,
# whose name carries the heuristic fragment `protect`. From 2026-08-05 the
# guard refused our own harness here with SuspiciousUnsigned, and CI said out
# loud that it skipped nine cases. §S19(b)'s signer half now verifies that
# module's embedded signature offline and reads O=Microsoft Corporation, so
# the refusal is gone for the reason 19_SAFETY always gave ("fragment AND not
# signed by a known vendor"), and the nine cases are in the merge gate. The
# switch still exists in build.ps1 for a developer who must, and it skips
# loudly; CI is no longer a place it is passed.
- name: Quality gate
shell: pwsh
run: ./build.ps1 check -SkipIntegration
run: ./build.ps1 check
env:
CI: 'true'
@@ -135,6 +131,41 @@ jobs:
# from `git diff`, so a shallow checkout cannot silently produce a short
# list — and the script refuses an EMPTY list rather than reading it as
# "no src/ changes, therefore fine".
# THE SIGNER PROBE'S CI LEG, printed. `ctest fl_signer_probe` runs inside the
# gate and passes on a regular expression, so its ANSWERS never reach this
# log — and §S19(b)'s rows G3/G4/G5 are pre-committed for exactly this
# machine's copy of the blocker. Run here, AFTER the gate, because the gate's
# restore is what fills the NuGet cache the probe searches first. A
# measurement, not a gate: continue-on-error so a surprise (row G6) is
# printed rather than turned into a red that hides it. Reading the row off
# the table is a separate PR (the probe says so itself).
- name: Signer probe (§S19(b) CI leg — measurement, not a gate)
if: always()
continue-on-error: true
shell: pwsh
run: ./build/native/x64-release/tools/fl-probe-signer/fl-probe-signer.exe
# §S29(d)'s pre-committed measurement: can tools/vklayer-blastradius.ps1 run
# HERE? It needs a Vulkan loader and vulkaninfo.exe, which ship with a GPU
# driver's runtime, not with Windows. A census, printed, never a gate.
# READ 2026-09-06 and again 2026-09-10 (run 34427267214): vulkan-1.dll
# PRESENT, vulkaninfo.exe ABSENT (System32 and PATH), no ICD registry key.
# So the "absent" row of 20_OPEN_QUESTIONS §S29(d) applies — deferred on
# that measurement, the script stays hand-run — and the "next PR wires the
# script" clause this comment used to carry is struck (2026-09-13). The
# step stays so a change in the runner image is noticed rather than assumed.
- name: Vulkan runtime census (§S29(d) — measurement, not a gate)
if: always()
continue-on-error: true
shell: pwsh
run: |
foreach ($f in 'C:\Windows\System32\vulkan-1.dll', 'C:\Windows\System32\vulkaninfo.exe') {
Write-Host ("{0}: {1}" -f $f, (Test-Path $f))
}
$cmd = Get-Command vulkaninfo.exe -ErrorAction SilentlyContinue
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'))
- name: Changelog
if: github.event_name == 'pull_request'
shell: pwsh
+261
View File
@@ -0,0 +1,261 @@
# FrameLedger release (docs/13_CI_CD.md §release.yml, docs/12_BUILD.md §Publish & package).
#
# On a tag `v*`: the same gate ci.yml runs, then publish → pack → checksums →
# a GitHub Release whose body is CHANGELOG.md's section for the version. Three
# things are refused loudly rather than papered over, because a release is the
# one artefact nobody can re-run:
# - the tag's numeric core must equal the VERSION file (the one version source;
# the native VERSIONINFO blocks are built from it and versioninfo-check
# compares them);
# - CHANGELOG.md must carry a non-empty `## [x.y.z]` section for the tag
# (tools/release-notes.ps1) — an empty release body is a defect, not a default;
# - the published tree must hold both entry points and every shipped native
# binary, checked by name, because `dotnet publish` warns rather than fails
# when a .targets-staged DLL is missing.
#
# Unsigned by policy (11_UPDATER §Unsigned releases): SHA256SUMS.txt is published
# beside the assets and printed into the release body.
#
# A pre-release tag (`v0.1.0-beta.1`, 13_CI_CD §Branch & release policy) marks the
# GitHub release as pre-release; the App's stable channel ignores it and the beta
# 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).
#
# 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:
contents: write
concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false
jobs:
release:
runs-on: windows-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@v7
- name: Set up .NET
uses: actions/setup-dotnet@v6
with:
global-json-file: global.json
- name: Set up MSVC (x64)
uses: ilammy/msvc-dev-cmd@v1
with:
arch: x64
# Same pin as ci.yml, for the same reason (the gate's clang-format step).
- name: Pin clang-format
shell: pwsh
run: |
pip install --disable-pip-version-check "clang-format==22.1.3"
clang-format --version
- 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 }}-
- 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'
$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)
$core = $m.Groups[1].Value
$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" }
New-Item -ItemType Directory -Force out | Out-Null
./tools/release-notes.ps1 -Version $full -OutFile out/notes.md
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
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
# 12_BUILD §Release-time token substitution: the effective date of a legal
# document is the date it ships. The only placeholder that survives into the
# repository, substituted here and nowhere else; the App embeds legal/*.md at
# build time, so this runs BEFORE the build.
- name: Substitute {{RELEASE_DATE}}
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$date = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd')
$n = 0
foreach ($f in Get-ChildItem legal -Filter *.md) {
$t = Get-Content $f.FullName -Raw
if ($t.Contains('{{RELEASE_DATE}}')) {
[System.IO.File]::WriteAllText($f.FullName, $t.Replace('{{RELEASE_DATE}}', $date), [System.Text.UTF8Encoding]::new($false))
$n++
}
}
Write-Host "RELEASE_DATE = $date in $n file(s)"
if (Select-String -Path legal/*.md, README.md -Pattern '\{\{' -Quiet) { throw 'a {{ token survived substitution' }
# The identical gate ci.yml runs — native build, tests, every check including
# versioninfo-check against VERSION. A release never skips it.
- name: Quality gate
shell: pwsh
run: ./build.ps1 check
env:
CI: 'true'
- name: Publish App + Agent (self-contained, ReadyToRun)
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$v = '${{ steps.version.outputs.version }}'
# 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
if ($LASTEXITCODE -ne 0) { throw 'Agent publish failed' }
# A self-contained package redistributes the .NET runtime, and its licence and
# third-party notices are ours to pass on (P4 PR-6). Not committed with the
# NuGet texts in legal/licenses/nuget: the runtime version follows the SDK of
# the machine that publishes, so the exact packs are read from the published
# runtimeconfig and copied from the NuGet cache the publish just used.
- name: Ship the .NET runtime's licence and notices
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$config = Get-Content out/app/FrameLedger.runtimeconfig.json -Raw | ConvertFrom-Json
$frameworks = @($config.runtimeOptions.includedFrameworks)
if ($frameworks.Count -eq 0) { throw 'FrameLedger.runtimeconfig.json lists no included framework -- the publish was not self-contained' }
$cache = if ($env:NUGET_PACKAGES) { $env:NUGET_PACKAGES } else { Join-Path $HOME '.nuget/packages' }
$dest = New-Item -ItemType Directory -Force out/app/licenses/dotnet
foreach ($fw in $frameworks) {
$pack = Join-Path $cache ('{0}.runtime.win-x64/{1}' -f $fw.name.ToLowerInvariant(), $fw.version)
$files = @(Get-ChildItem $pack -File | Where-Object { $_.Name -match '^(LICENSE|THIRD-PARTY-NOTICES)(\.TXT)?$' })
if ($files.Count -eq 0) { throw "no licence file in $pack" }
foreach ($f in $files) {
Copy-Item $f.FullName (Join-Path $dest ('{0}-{1}-{2}' -f $fw.name, $fw.version, $f.Name))
}
}
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 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).
- name: Assert the published tree
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$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
if ($LASTEXITCODE -ne 0) { throw 'versioninfo-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)
# Velopack's packer, pinned to the library version the App references
# (Directory.Packages.props). No --icon: assets/icon.ico does not exist yet
# (12_BUILD §Publish & package says so rather than pointing at a file that is not there).
#
# --packId is FrameLedger.App, NOT FrameLedger, and that is a data-loss rule:
# Velopack installs into %LOCALAPPDATA%\<packId> and deletes that directory on
# uninstall, and %LOCALAPPDATA%\FrameLedger is the DATA folder (LedgerPaths:
# 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".
- name: Pack (Velopack)
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
dotnet tool install -g vpk --version 1.2.0
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
$v = '${{ steps.version.outputs.version }}'
vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
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)' }
- name: Checksums
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$lines = Get-ChildItem out/release -File | Sort-Object Name | ForEach-Object {
'{0} {1}' -f (Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLowerInvariant(), $_.Name
}
[System.IO.File]::WriteAllLines('out/release/SHA256SUMS.txt', $lines, [System.Text.UTF8Encoding]::new($false))
$notes = Get-Content out/notes.md -Raw
$notes += "`n`n## SHA-256`n`nReleases are not code-signed (11_UPDATER). Verify before running:`n`n``````text`n" + ($lines -join "`n") + "`n``````"
[System.IO.File]::WriteAllText('out/notes.md', $notes, [System.Text.UTF8Encoding]::new($false))
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')
if ('${{ steps.version.outputs.prerelease }}' -eq 'true') { $ghArgs += '--prerelease' }
$ghArgs += Get-ChildItem out/release -File | ForEach-Object { $_.FullName }
gh @ghArgs
if ($LASTEXITCODE -ne 0) { throw 'gh release create failed' }
- name: Upload the published tree (for the smoke checklist)
if: always()
uses: actions/upload-artifact@v7
with:
name: release-${{ steps.version.outputs.version || github.ref_name }}${{ steps.version.outputs.dry_run == 'true' && '-dry-run' || '' }}
path: |
out/release/**
out/notes.md
if-no-files-found: warn
retention-days: 30
+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
+2229 -7
View File
File diff suppressed because it is too large. Load diff
+92 -31
View File
@@ -12,16 +12,24 @@ 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, 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).
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*).
@@ -39,7 +47,8 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
| UI | WPF + WPF UI (`WPF-UI` pinned = 4.3.0) + CommunityToolkit.Mvvm — `docs/16_WPFUI_SYNTAX.md` |
| App composition | .NET Generic Host + DI in `FrameLedger.App` |
| Charts | ScottPlot 5 |
| GPU telemetry | Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. **No telemetry source exists in code yet** — `ctest fl_nvapi_probe` is the only consumer, and it exists so the vendoring is verified rather than asserted. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
| Markdown in the App | **Markdig** (BSD-2-Clause, pinned 1.4.0) → WPF `FlowDocument`, HTML off, no image fetched — the Legal Gate, the user guide, Help ▸ Limitations, the update notes, About (beta.12; row added 2026-10-04) |
| GPU telemetry | **The game process's own memory since beta.12 (D43):** `FrameLedger.ProcessStats.dll` (C++, loaded by the Agent, never into a game) reads its dedicated/shared GPU memory from the `GPU Process Memory` counters and its working sets from `GetProcessMemoryInfo` — `18_GPU_VENDOR_APIS` §The game process's memory. Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
| CPU/board sensors | LibreHardwareMonitorLib ≥ 0.9.6 (PawnIO) — **optional**, elevated only |
| Tier-2 fallback | **There is none, and Tier 2 is not a measurement.** Owner decision 2026-08-28: the ladder is two rungs — hooked, or duration + sensors + the reason. ~~ETW-based, no injection~~; ~~Intel PresentMon console binary~~ dropped 2026-08-27 after §S31 retired it. Whether a shipped build ever regains a no-injection measurement is `docs/20_OPEN_QUESTIONS.md` §G |
| Storage | SQLite via Microsoft.Data.Sqlite + Dapper (no EF) |
@@ -54,6 +63,8 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
```
FrameLedger.slnx # XML solution format (SDK default since .NET 10)
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
global.json # pins the SDK band — see 12_BUILD
build.ps1 # the quality gate; CI runs this identical script
src/
@@ -62,52 +73,98 @@ src/
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe
FrameLedger.VkLayer/ # C++20 Vulkan implicit layer DLL + manifest JSON
FrameLedger.Shm/ # header-only: ring buffer + record layout, shared by native & C# (mirrored)
FrameLedger.NvapiBridge/ # C++ DLL loaded by the Agent (never a game): NVAPI telemetry, NGX state (P2 PR-E2)
FrameLedger.ProcessStats/ # C++ DLL loaded by the Agent (never a game): the game process's memory (beta.12, D43)
tests/ tools/ third_party/ # ctest suites; probes, hook-harness, vendor stubs; vendored headers
# (these three lines added 2026-10-04 — the list stopped at Shm)
FrameLedger.Domain/ # entities, metric calculators — zero dependencies
# (calculators UNWRITTEN: Domain holds AntiCheat/,
# Consent/ and Detection/ only. Nothing in Domain
# computes a frame time or an FPS low. measuredMask ->
# rule 7's tri-state and Displayed FPS now exist, in the
# UNSHIPPED FrameLedger.CaptureHost as a throwaway that
# P2's recorder replaces — deliberately not in
# Domain.Metrics.*, which carries a 95% coverage floor)
FrameLedger.Application/ # use cases, ports
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + ShmRecord struct mirror
# (Metrics/ WRITTEN 2026-09-09, P2 PR-A: frame times,
# percentiles, lows, stutter, the FG window and its
# refusals, extent, segments, RT/HDR tri-states,
# aggregates — over Domain's own FrameSample, under the
# 95% per-class floor. The CaptureHost's consumer now
# calls it; the FG ladder's prose is still there, PR-D's)
FrameLedger.Application/ # use cases, ports — incl. Capture/ since 2026-09-09 (P2 PR-C):
# CaptureSession (the loop: gate -> inject -> attach -> drain
# under the 30 s re-scan), ICaptureSink and the ports the Agent
# composes it from, SessionEndReason, the census/NGX/marker facts;
# and Recording/ since 2026-09-10 (PR-D): SessionRecorder,
# SessionAggregator + FgLadder, SessionFinalizer, the .partial
# writer and PartialRecovery, ExitStatusMapper, the crash policy
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
# 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) + 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
FrameLedger.App/ # WPF UI
FrameLedger.CaptureHost/ # UNSHIPPED. The first production driver of the guard loop:
# HookedCaptureGate -> FlGuardedInject -> ShmRingReader ->
# 10 Hz drain + GuardSupervisor + PublishGuardResult, plus the
# file-backed consent store and a throwaway consumer.
# 12_BUILD publishes App and Agent ONLY, and neither references
# this — tools/package-closure-check.ps1 is what keeps that true.
# §S27 is closed on exactly that basis.
# BUILT 2026-09-10 (P2 PR-F): a Generic Host. `--serve` = watcher
# (Application.Watch: ProcessWatcher, ProcessTree, DescendantElection,
# CaptureOrchestrator over ISessionRecorder) -> recorder -> the gate;
# `--console` = the operator's verbs incl. `consent grant` (decision D4,
# ConsentProvenance.AgentConsoleOperator — the DEVELOPER path since P3 PR-4
# built FR-2.1's dialog, ConsentProvenance.ConsentDialog) and `killswitch` (FR-2.4,
# the gate's FOURTH input, decision D7). --data-dir under --console only.
FrameLedger.App/ # WPF UI — the SHELL since 2026-09-13 (P3 PR-2): Generic Host,
# FluentWindow + TitleBar/Menu/NavigationView, theme + language
# persisted in `settings`, the Agent pill over the pipe (starts
# `FrameLedger.Agent.exe --serve` beside itself when absent),
# ~~five pages of which four are empty states~~ — every 08_UI screen
# 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
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
# adapters — the loop itself no longer lives here. Its consent
# store is SQLite (PR-B) over its OWN ledger.db beside the binary,
# never the Agent's (D5). 12_BUILD publishes App and Agent ONLY,
# and neither references this — tools/package-closure-check.ps1
# keeps that true. §S27 was closed on that basis and is RESTATED
# there: the consent adapter AND the loop now ship, so packaging
# 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
# (six names added 2026-10-04)
# (PowerShell). This line used to name three, one of which
# — resx-audit — does not exist.
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
# resx-gen (the committed Strings.Designer.cs generator).
# native tooling lives under src/native/tools:
# fl-layout-dump -> struct offsets for the C# mirror test
# hook-harness -> dummy D3D11 + D3D12 app (Vulkan/OpenGL unwritten)
# 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.
docs/ legal/ legal/licenses/
```
Dependency direction unchanged: `App/Agent → Application → Domain`; `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else.
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **~~Two~~ Three facades since ~~2026-09-10~~ 2026-10-03:** `NativeAntiCheatGuard` (required — absent throws), `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself) and, since beta.12 (D43), `NativeProcessStats` (optional — the game process's own memory, read from outside the game; absent reads N/A), all by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why the third facade claims a name there rather than setting its own.
## Coding conventions
**C# —** `Nullable enable`, `TreatWarningsAsErrors`, `AnalysisLevel latest-all`, file-scoped namespaces, Roslynator + Meziantou + VS Threading analyzers, `dotnet format` clean. Async suffixed `Async`, `ConfigureAwait(false)` off the UI. All user-visible strings from `.resx`. Timestamps UTC (unix-ms in SQLite); QPC ticks only inside the capture pipeline.
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: `/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`).
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: ~~`/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`)~~ CodeQL (`codeql.yml`, a required check); `/analyze` and clang-tidy are not configured *(corrected 2026-10-04)*.
**Struct mirroring —** `FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock` each exist twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by `tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
**Licence header —** every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`) opens with two comment lines, `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` (beta.12, owner decision D45). GPLv3 §7 requires additional terms to be named in the source files, and `NOTICE` holds them — (b) preserve the notices, (c) mark modified versions, (e) no trademark rights in the name. `tools/notice-check.ps1` is a `build.ps1` gate; `-Fix` writes a missing header. `src/native/third_party/` is excluded.
**Struct mirroring —** ~~`FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock`~~ `FlShmHandshake`, `FlWriterState`, `FlControlBlock`, `FlDisplayState` (layout 4, beta.10), `FlFrameRecord` and `FlTolerance` (D33, beta.9) each exist twice *(corrected 2026-10-04)*: `src/native/FrameLedger.Shm/include/fl_shm.h` / `fl_tolerance.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by ~~`tools/fl-layout-dump`~~ `src/native/tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReferences`), because offsets cannot see it: measured 2026-08-05, swapping the `fixed byte BuildId[32]` for this repo's own `[MarshalAs(ByValTStr)] string` idiom keeps `Marshal.SizeOf` at 64 and every offset correct while `Unsafe.SizeOf` collapses to **40** — a mirror that passes the obvious checks and cannot be read out of a memory-mapped view.
@@ -115,7 +172,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** app used to exercise hooks without a real game; Vulkan and OpenGL modes are unwritten (`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)
@@ -141,6 +198,10 @@ 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). **`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
lists the defects and gaps that survived the doc audit — things the other
+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.
+71
View File
@@ -0,0 +1,71 @@
# Contributing to FrameLedger
Thank you for looking. FrameLedger is a small project with strict rules, because it loads code into games and a mistake
can cost a user their account. This page says how to build it, what a change has to bring with it, what will not be
merged, and under what licence your contribution is accepted.
## Before you start
- **Read `CLAUDE.md`'s *Non-negotiable rules* and `docs/19_SAFETY_AND_ANTICHEAT.md` first.** They constrain everything
that touches a game.
- **Open an issue before anything larger than a fix**, so the approach can be agreed before the work is done.
- **A game with anti-cheat that FrameLedger fails to detect** is a safety bug: use the *Safety gap* issue form.
- **A vulnerability in FrameLedger itself** goes the private route in `SECURITY.md`, never a public issue.
- Everyone who takes part follows the `CODE_OF_CONDUCT.md`.
## Building
You need Windows 10 22H2 or later (x64), Visual Studio 2022 with the C++ workload (MSVC v143), CMake 3.28 or later,
PowerShell 7, and the .NET SDK that `global.json` pins. Then:
```powershell
./build.ps1 check
```
That is the whole quality gate, and continuous integration runs the identical script: the native build and its tests,
`clang-format`, the managed build with warnings as errors, `dotnet format`, every test project, and the repository's own
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
## What a pull request brings with it
The definition of done is the one in `CLAUDE.md`:
- it builds without warnings (C# and C++), the tests are green, and `dotnet format` and `clang-format` are clean;
- a change to the hook path states its measured overhead in the PR (`docs/14_TESTING.md` §Hook overhead);
- a new hook is listed in `docs/17_HOOK_ENGINE.md` §Hook inventory and justified against rule 4;
- every new user-visible string exists in `en`, `vi` and `ja` (`docs/09_I18N.md`);
- a change that makes a document wrong updates that document in the same PR;
- a change under `src/` adds an entry under `## [Unreleased]` in `CHANGELOG.md`;
- every new source file carries the licence header — `./tools/notice-check.ps1 -Fix` writes it. A file you wrote
yourself may name you in its second line instead, in the same form:
`Copyright (C) <year> <your name> - additional terms under GPLv3 section 7: see NOTICE`.
The pull-request template lists the safety checks for changes to the capture layer.
## What will not be merged
Whatever its other merits, a change that
- adds any way to override, weaken or skip the anti-cheat guard (rule 2);
- makes FrameLedger harder to detect — manual mapping, header erasure, thread hiding, unlinking modules, obfuscation,
renamed binaries (rules 3 and 9);
- reads or writes game memory outside the hooked calls (rule 4), or makes a hook able to crash a game (rule 5);
- adds telemetry, analytics or any network request beyond the ones `legal/PRIVACY_POLICY.md` lists (rule 8);
- turns injection on for a game the user did not individually enable (rule 1).
## Licensing of contributions
FrameLedger is licensed under the GNU GPL, version 3 only, with the additional terms in `NOTICE`. **By opening a pull
request you confirm that you have the right to submit the change, and you license it under GPL-3.0-only, with the
additional terms in `NOTICE` (GPLv3 §7 (b), (c) and (e)) applying to it as they apply to the rest of FrameLedger's own
material.** There is no contributor licence agreement and no copyright assignment: you keep the copyright in your
contribution. Code from elsewhere must come with a licence compatible with GPL-3.0-only and be listed in
`legal/THIRD_PARTY_NOTICES.md`.
Changes written with AI assistance are welcome on the same terms — you are responsible for what you submit, as for any
other change.
## Questions
Open an issue, or write to contact@poli0981.dev.
+13
View File
@@ -54,6 +54,19 @@
<SatelliteResourceLanguages>en;vi;ja</SatelliteResourceLanguages>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<!-- ONE version source (P4 PR-5, docs/12_BUILD.md §Version): the VERSION file
at the repository root. src/native/CMakeLists.txt reads the same file for
the VERSIONINFO blocks, and tools/versioninfo-check.ps1 compares the built
binaries against it, so the managed and native halves cannot drift. The
condition lets release.yml pass -p:Version=<tag> for a pre-release
(0.1.0-beta.1 is not a number CMake's project() accepts, so the native
FileVersion stays the numeric core). SourceLink's "+sha" suffix is off so
About, Hello and the bug bundle print the version a user can find on the
releases page. -->
<FrameLedgerVersionFile>$(MSBuildThisFileDirectory)VERSION</FrameLedgerVersionFile>
<Version Condition="'$(Version)' == '' And Exists('$(FrameLedgerVersionFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerVersionFile)').Trim())</Version>
<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
</PropertyGroup>
<!-- Test projects: documentation comments are noise, and xUnit's own
+28 -11
View File
@@ -3,7 +3,7 @@
<!--
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.
-->
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
@@ -25,10 +25,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.4.0" />
</ItemGroup>
<ItemGroup Label="Hosting and logging">
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.10" />
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.12" />
<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,8 +44,8 @@
<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.12" />
<PackageVersion Include="Dapper" Version="2.1.86" />
<!--
Transitive pin, not a direct dependency.
@@ -56,24 +63,34 @@
</ItemGroup>
<ItemGroup Label="Interop, telemetry and packaging">
<PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.298" />
<PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.333" />
<PackageVersion Include="Velopack" Version="1.2.0" />
<!-- 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.12" />
</ItemGroup>
<ItemGroup Label="Analyzers (build-time only)">
<PackageVersion Include="Roslynator.Analyzers" Version="4.16.0" />
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.141" />
<PackageVersion Include="Roslynator.Analyzers" Version="5.0.0" />
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.266" />
<PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="18.7.23" />
</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.10.1" />
<!--
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.1" />
<PackageVersion Include="xunit.runner.visualstudio" Version="4.0.0" />
<!--
FluentAssertions is pinned to the 7.x line ON PURPOSE, and must not be
bumped to 8.x without redoing the licence analysis.
@@ -91,7 +108,7 @@
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="NSubstitute" Version="6.2.0" />
<PackageVersion Include="coverlet.collector" Version="10.0.1" />
</ItemGroup>
+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` in `src/native/CMakeLists.txt`, and the `ProductName` that `tools/versioninfo-check.ps1` requires | anti-cheat vendors and users identify the DLLs loaded into games by it (`docs/19_SAFETY_AND_ANTICHEAT.md`); it must name your project |
| 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)
+12
View File
@@ -39,6 +39,18 @@
</None>
</ItemGroup>
<!--
THE HARNESS'S LOGS LEAVE WITH THE ASSEMBLY THAT CAUSED THEM. The Overlay logs to the real
%LOCALAPPDATA%\FrameLedger\logs by design (§S21), so every TEST project that stages hook-harness
compiles tests/Shared/HarnessOverlayLogSweep.cs, an xUnit assembly fixture that removes, when the
assembly finishes, the overlay logs of the harness copies it owns (17_HOOK_ENGINE §Native logging).
The CaptureHost imports this file too and is not a test project, so it does not get the sweep.
tools/test-artifacts-check.ps1 is what makes a missing sweep red.
-->
<ItemGroup Condition="'$(IsTestProject)' == 'true'">
<Compile Include="$(MSBuildThisFileDirectory)tests\Shared\HarnessOverlayLogSweep.cs" Link="Shared\HarnessOverlayLogSweep.cs" />
</ItemGroup>
<!--
Warn at build, fail at test. build.ps1 runs the native build first, so by the
time this evaluates both exist; a hard error here would break `dotnet build` on
+40
View File
@@ -0,0 +1,40 @@
<Project>
<!--
Ships FrameLedger.NvapiBridge.dll beside the importing project's output (P2 PR-E2).
The second P/Invoke facade after the guard's (docs/18_GPU_VENDOR_APIS.md §L3):
NativeNvapiBridge 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 telemetry read and the NGX per-process word.
Imported by exactly three projects, for the same reasons the guard's is:
- FrameLedger.Agent — the host of the telemetry stack.
- FrameLedger.CaptureHost — the unshipped driver, same stack, own ledger.
- FrameLedger.Infrastructure.Tests — NvapiBridgeLayoutTests and the real-hardware
case P/Invoke into the real DLL.
Warn rather than fail when absent: build.ps1 runs the native build first, so by
the time this evaluates the DLL exists; a hard error would fail `dotnet build`
on a fresh clone for a reason that has nothing to do with the managed code.
Unlike the guard, an absent bridge is NOT a safety hole — L3 disables cleanly
and the session records `telemetry_source` without `nvapi`.
-->
<PropertyGroup>
<FlNvapiBridgeOutDir>$(MSBuildThisFileDirectory)build\native\x64-release\FrameLedger.NvapiBridge\</FlNvapiBridgeOutDir>
</PropertyGroup>
<ItemGroup>
<None Include="$(FlNvapiBridgeOutDir)FrameLedger.NvapiBridge.dll" Condition="Exists('$(FlNvapiBridgeOutDir)FrameLedger.NvapiBridge.dll')">
<Link>FrameLedger.NvapiBridge.dll</Link>
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
</ItemGroup>
<Target Name="FlWarnOnMissingNvapiBridge" AfterTargets="Build"
Condition="!Exists('$(FlNvapiBridgeOutDir)FrameLedger.NvapiBridge.dll')">
<Warning Text="FrameLedger.NvapiBridge.dll was not found at $(FlNvapiBridgeOutDir). Run build.ps1 native first; L3 telemetry will report itself unavailable." />
</Target>
</Project>
+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>
+2
View File
@@ -9,6 +9,8 @@
<Project Path="src/FrameLedger.Shared/FrameLedger.Shared.csproj" />
</Folder>
<Folder Name="/tests/">
<Project Path="tests/FrameLedger.Agent.Tests/FrameLedger.Agent.Tests.csproj" />
<Project Path="tests/FrameLedger.App.Tests/FrameLedger.App.Tests.csproj" />
<Project Path="tests/FrameLedger.Application.Tests/FrameLedger.Application.Tests.csproj" />
<Project Path="tests/FrameLedger.CaptureHost.Tests/FrameLedger.CaptureHost.Tests.csproj" />
<Project Path="tests/FrameLedger.Domain.Tests/FrameLedger.Domain.Tests.csproj" />
+143
View File
@@ -0,0 +1,143 @@
# 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.12.*
## 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; 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))
## 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))
## Upscaling and ray tracing
- The upscaler is read from the game's calls: DLSS and NIS through NVIDIA Streamline, and FSR through AMD's
FidelityFX libraries. **Intel XeSS is not read** (its licence forbids it), FSR 2 and upscalers built into the
game are not identified, and Vulkan and OpenGL games read N/A. Where no hook saw DLSS but the NVIDIA driver
reports it, the page says it is the driver's report.
- **The quality preset** (Quality, Balanced, …) has not been reported on any game yet, and the render
resolution is N/A where the game's own calls do not carry it (DLSS without Streamline, for one).
- **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. ([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.** 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.
- **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))
## 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.
- **No real Vulkan or OpenGL game has been measured yet** — only FrameLedger's own test program.
- There is **no in-game overlay**; everything is shown in the FrameLedger window.
## 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.
+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
+135 -52
View File
@@ -4,38 +4,111 @@
> No telemetry. No accounts. All data stays on your machine.
> ⚠ **Accuracy note — 2026-08-05. This README describes the finished product; the software
> is pre-alpha and most of what follows is not built yet.** Added because every other
> user-facing document here carries such a note and this one — the first thing anyone
> reads — carried none, while `legal/DISCLAIMER.md` had already been through two rounds of
> exactly this correction.
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
anti-cheat, and look after your data, a page each. What FrameLedger cannot do is on one page:
[Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User guide, Help ▸ Limitations).
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-10-04.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.12`** (2026-10-04), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> and only past the safety guard, and
> stores sessions in a local database. What that path measures:
>
> **What actually works today:** frame boundaries, frame times and output resolution, from
> a Direct3D 11/12 present hook, written into shared memory and read back by the Agent's
> ring reader. Plus, for titles that go through NVIDIA Streamline, **which upscaler is
> executing** and **whether Ray Reconstruction is running with it** — identity only, not the
> quality preset and not the render resolution. The anti-cheat guard runs all of its
> pre-injection checks and refuses.
> - **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
> 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 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.
> - **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
> and OpenGL titles.
> - **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. 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. 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. 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:** 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.
> - **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.** 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.
>
> **What does not yet exist**, and is written above in the present tense: every bullet
> under *What makes it different* except output resolution and upscaler identity — no
> quality preset, render resolution, frame generation, ray tracing, VRAM, shader-stutter or
> Reflex hook has been written. The capture side says so in its own data rather than defaulting to "none"
> (`docs/03_METRICS.md`, CLAUDE.md rules 6 and 7). There is also no storage, no charts, no
> library import, no UI and no installer.
>
> The two rows that describe **safety behaviour** are qualified where they sit, rather than
> here, because that is where a reader checking their own risk will look.
> 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
> yours. The software never substitutes an estimate.
<!-- accuracy-block:end -->
> The rows below that describe **safety behaviour** are qualified where they sit, rather than
> here, because that is where a reader checking their own risk will look. What this README
> describes beyond the block above is the finished product; the block is what exists.
## What makes it different
Most tools tell you your frame rate. FrameLedger tells you **what produced that frame rate**:
- **Real render resolution vs output resolution** — the actual internal resolution, not the one in the settings menu.
- **Which upscaler is running, at which quality preset** — DLSS / FSR / XeSS, read from the API the game calls, not guessed from files on disk.
- **Frame Generation, measured** — native and generated frames counted separately. Always shown as `62 → 118 FPS (×1.9 FG)`, never as one inflated number.
- **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.
@@ -43,7 +116,7 @@ Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distri
## How it works — and the trade-off, stated plainly
None of the settings data above is visible from outside a game process. To read it, FrameLedger loads a component into the game and observes the calls the game makes to graphics APIs — the same class of technique used by frame-rate overlays, recording software, and post-processing injectors. Vulkan titles use a standard Vulkan layer instead.
None of the settings data above is visible from outside a game process. To read it, FrameLedger loads a component into the game and observes the calls the game makes to graphics APIs — the same class of technique used by frame-rate overlays, recording software, and post-processing injectors. Vulkan titles use a standard Vulkan layer instead, when FrameLedger starts them.
**That carries a real risk: anti-cheat systems can detect injected code and may ban accounts.**
@@ -52,7 +125,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>⚠ **Half of this is built.** The *pre-injection* refusal is real and runs every documented check. The **in-session re-scan does not run at all**: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner — but nothing yet drives the scanner during a session, so nothing ever tells it. `legal/DISCLAIMER.md` §2 states this in full. The Vulkan layer additionally intercepts nothing yet, so there is no Vulkan capture to stop. |
| **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 |
@@ -64,57 +137,67 @@ 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, 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, Vulkan, or OpenGL game for full (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 (GPU telemetry works without it, through your graphics driver's own libraries)
- A 64-bit DirectX 11/12 or OpenGL game, or a Vulkan game FrameLedger starts, for hooked (Tier-1) capture. **32-bit games — including most DirectX 9 titles — cannot be measured at all**: the component FrameLedger loads is x64 and an x64 DLL cannot enter a 32-bit process. Such a title records duration and hardware telemetry and nothing else. *(This line previously said "supported at Tier 2 only", which meant frame times without injection. That tier no longer exists.)*
- Optional: [PawnIO](https://pawnio.eu/) for CPU temperature, read only when the Agent runs as administrator (since 0.1.0-beta.3; not yet checked on real hardware). CPU load, memory in use and all GPU telemetry work without it
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (~~not read yet~~ read with PawnIO, not yet checked on real hardware — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on. **Since beta.10 it is a choice in Settings** — *Run the agent as administrator*, off by default: Windows asks every time the agent starts, games you start from FrameLedger still run as you, and `LIMITATIONS.md` says what it does not change.
## Install
1. Download the latest `FrameLedger-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases).
> **The latest pre-release is `v0.1.0-beta.12` (2026-10-04); before it `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
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**.
3. Follow the first-run Legal Gate and Agent setup. Nothing is injected until you enable it for a specific game.
## Privacy
Everything lives locally in `%LOCALAPPDATA%\FrameLedger`. The only network calls FrameLedger will ever make: update checks against GitHub Releases, detection-rules updates from this repository, and *optional, opt-in* store metadata lookups. Bug reports are always built locally, shown to you, and submitted by you. Full policy: [`legal/PRIVACY_POLICY.md`](legal/PRIVACY_POLICY.md).
**Today it makes none of them.** The rules feed in particular does not exist — the blocklist ships with the build and updates only when you install a new one (`docs/20_OPEN_QUESTIONS.md` §S20). Listing a fetch that has no code is over-disclosure, and this document was already corrected once for describing a weekly outbound request the software never made.
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 such as Reflex latency. 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).
- **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.
- **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). Twelve tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
+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.
+1
View File
@@ -0,0 +1 @@
0.1.0
+99 -33
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
@@ -29,18 +32,18 @@ param(
# Excludes tests traited Category=Integration -- today, the drain end-to-end
# cases, which inject the Overlay into hook-harness.
#
# CI PASSES THIS AND A DEVELOPER MUST NOT. The reason is a MEASURED property of
# the hard gate, not flakiness: §S16 puts the injecting process's ancestors in
# the scan set, so the test host is scanned, and a .NET host can load
# System.Security.Cryptography.ProtectedData.dll -- which contains the
# heuristic fragment `protect`. The guard then refuses our own harness with
# SuspiciousUnsigned. That is the gate working exactly as specified;
# 20_OPEN_QUESTIONS §S19(b) is the defect, and it is a guard change with its
# own PR rather than something to paper over here.
# NOBODY PASSES THIS ANY MORE, and it is kept so that the day someone must, the
# skip is loud. CI passed it from 2026-08-05 to 2026-09-06 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 (heuristic fragment
# `protect`), and the guard refused our own harness with SuspiciousUnsigned.
# 20_OPEN_QUESTIONS §S19(b)'s signer half now verifies that module's embedded
# signature offline (O=Microsoft Corporation, on the compiled-in bound), so the
# refusal is gone for the reason the heuristic always stated, and CI runs
# `./build.ps1 check` with no switches — the same command a developer runs.
#
# It skips LOUDLY, because a suite that quietly stops running one class is how
# a gate rots. Whatever CI does, `./build.ps1 check` with no switches runs
# everything.
# a gate rots.
[switch]$SkipIntegration
)
@@ -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,24 @@ 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.
$testArgs = @('test', "`"$solution`"", '-c', $Configuration, '--no-build', '--collect:"XPlat Code Coverage"',
'--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 +302,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,12 +314,8 @@ 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
@@ -387,6 +409,9 @@ 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 (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 }
}
else {
@@ -405,6 +430,26 @@ function Invoke-ProjectGates {
# It found a defect in its own filter on its first run: a whitespace-only path
# is truthy in PowerShell, so the empty-list refusal was unreachable for that
# input.
# §S23-6: the accuracy blocks are one text in legal/ACCURACY.md; a copy that
# drifted is red. Self-test first, both directions, so the gate is seen to work.
Write-Step 'accuracy-check'
$accuracyTool = Join-Path $repo 'tools/accuracy-check.ps1'
if (Test-Path $accuracyTool) {
Invoke-Checked 'accuracy-check (self-test)' { & $accuracyTool -SelfTest }
Invoke-Checked 'accuracy-check' { & $accuracyTool }
}
else {
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 }
Write-Step 'changelog-check'
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
if (Test-Path $changelogTool) {
@@ -414,13 +459,23 @@ function Invoke-ProjectGates {
Skip-Gate 'changelog-check' 'tools/changelog-check.ps1 not implemented yet'
}
# The release body's extractor (P4 PR-5, 13_CI_CD §release.yml): self-test only
# here — the live pass needs a tag's version and runs in release.yml, where a
# missing or empty `## [x.y.z]` section is a red release rather than an empty note.
Write-Step 'release-notes'
Invoke-Checked 'release-notes (self-test)' { & (Join-Path $repo 'tools/release-notes.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.
Write-Step 'resx-audit'
$resxTool = Join-Path $repo 'tools/resx-audit'
$resxTool = Join-Path $repo 'tools/resx-audit.ps1'
if (Test-Path $resxTool) {
Invoke-Checked 'resx-audit' { & $resxTool }
Invoke-Checked 'resx-audit (self-test)' { & $resxTool -SelfTest }
Invoke-Checked 'resx-audit' { & $resxTool -Root $repo }
}
else {
Skip-Gate 'resx-audit' 'tools/resx-audit not implemented yet (no .resx files exist)'
throw 'resx-audit: tools/resx-audit.ps1 is missing — 09_I18N names it and build.ps1 used to skip it loudly'
}
# The shared-memory struct mirror. CLAUDE.md §Struct mirroring calls this the
@@ -463,6 +518,15 @@ function Invoke-ProjectGates {
}
Write-Host " $($mirrorResults.Count) mirror assertion(s) executed and passed (fl_shm.h vs FrameLedger.Shared)" -ForegroundColor DarkGray
# Test hygiene (17_HOOK_ENGINE §Native logging). The injection tests use the shipped Overlay, whose log goes to the
# real data folder by design (§S21), and 2492 hook-harness logs had piled up there by 2026-09-15. Each test binary
# that starts the harness now removes the logs it caused; this is what makes a missing sweep red: a hook-harness
# overlay log created since this gate started and still there after the tests fails it. A game's log never counts.
Write-Step 'test-artifacts'
$artifactsTool = Join-Path $repo 'tools/test-artifacts-check.ps1'
Invoke-Checked 'test-artifacts (self-test)' { & $artifactsTool -SelfTest }
Invoke-Checked 'test-artifacts' { & $artifactsTool -SinceUtc $script:GateStartedUtc }
Write-Step 'placeholder guard'
# {{RELEASE_DATE}} is substituted at release time and is the only token
# allowed to survive. Anything else in a document FR-11 displays for
@@ -478,6 +542,8 @@ function Invoke-ProjectGates {
# --- Entry point ------------------------------------------------------------
$sw = [Diagnostics.Stopwatch]::StartNew()
# The test-artifacts gate counts only what this run could have written.
$script:GateStartedUtc = [DateTime]::UtcNow
switch ($Task) {
'native' { Invoke-Native $false }
'managed' { Invoke-Managed $false }
+57 -9
View File
@@ -23,17 +23,36 @@
│ ├ 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
> matches a blocklist — two matchers that can disagree is a fail-open by
> construction, and a test asserts there is only one (§S15 item 1).
> **The Agent box exists as of 2026-09-10 (P2 PR-F).** `ProcessWatcher` is `Application.Watch`
> (`CaptureOrchestrator` over `ToolhelpProcessSnapshotSource`); `Injector` is the guard facade reached
> through `HookedCaptureGate`; `ShmReader` is `CaptureSession` over `ShmRingReader`; `VendorTelemetry` is
> the L1 + L2 + L3 composite; `SessionRecorder` is `Application.Recording`. ~~The named pipe on the left
> is **not** built (P3, `07_IPC`), so today's Agent has no UI client: `--serve` logs, `--console` prints.~~
> **The pipe's read half is built 2026-09-13 (P3 PR-1):** `--serve` listens on `\\.\pipe\FrameLedger.v2`,
> answers `Hello` / `GetStatus` / `Ping`, and narrates every session (`SessionStarted` at the attach, `SessionProgress`
> at 1 Hz, the safety and error events, `SessionCompleted`); `--console` still prints and hosts no pipe. The
> command half — the messages a client sends to change a state — ~~is PR-1b~~ is built the same day (PR-1b:
> `SetWatchlist`, `LaunchGame`, `SetHookEnabled` with the pre-scan and no stamp until PR-4, pause/resume,
> `StopSession`, `UpdateRules`, `Shutdown`), and the App that connects is PR-2.
## Why this shape
- **Hooking in-process is the only way to get the facts we care about.** Render resolution vs output resolution, upscaler identity and quality preset, whether frame generation is actually running, whether rays are actually being traced — none of these are observable from outside the process. The previous ETW-only design could only guess from file/module presence, which measured badly against real games.
@@ -45,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.
@@ -66,6 +85,11 @@ watcher sees tracked exe launch
**Launch mode (preferred when FrameLedger starts the game):** `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. This catches swapchain creation and early upscaler init, which attach mode can miss. Attach mode remains for games launched from Steam/GOG directly.
> **Built 2026-09-06 as start → the guard waits for a presentation runtime → the full guard → inject**
> (`FlGuardedInjectWhenReady`, P1 item 2), because a suspended target has loaded nothing for the module
> scan to read (`20_OPEN_QUESTIONS` §S1). What it costs is measured by the session itself:
> `FlWriterState.dxgiPresentsBeforeHook`. `04_CAPTURE` §Launch mode carries the shape.
Guard re-runs every 30 s for the life of the session; anti-cheat appearing late ⇒ clean unhook (`19_SAFETY` §During a session).
## Lifecycle
@@ -73,9 +97,19 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
- Agent idles at ~0% CPU: 1 Hz process poll. No capture machinery exists until a tracked game launches.
- Session ends when the process tree exits, or on safety unhook, or on user stop.
- The DLL is **not unloaded** from a live process after unhooking (threads may still be inside trampolines). It disables its hooks, stops writing, and goes dormant until the process exits. Documented, deliberate.
- UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.
- ~~UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.~~ *(Corrected 2026-10-04: closing the UI never stops the Agent. `Shutdown` is sent only for an update, by the uninstall hook and for the admin mode's restart; the background-capture setting was read by nothing, and its switch is gone since beta.12 — `06_DATA_MODEL` §Settings registry.)*
- Single instance via named mutexes; the ring name is per-PID so multiple games can be captured simultaneously (rare but supported).
> **The single instance was specified here and not built until 2026-09-17**, and 0.1.0-beta.1 ran four Agents: an
> 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
| Failure | Behavior |
@@ -83,12 +117,12 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
| Anti-cheat detected pre-injection | Refuse, explain which signal fired, offer Tier 2 |
| Anti-cheat detected mid-session | Immediate clean unhook, `exit_status = unhooked_safety`, prominent notice |
| Injection API fails (access denied, protected process) | Log, no retry loop, offer Tier 2 + "run Agent elevated" hint — elevation here is about *attaching to an elevated target*, not about reaching a tier; Tier 2 needs none |
| Hook faults 3× | DLL self-disables, sets fault flag in handshake block, Agent finalizes session as `degraded` |
| Hook faults 3× | DLL self-disables, sets ~~fault flag in handshake block~~ `FlWriterState.status` to `SELF_DISABLED` *(corrected 2026-10-04)*, Agent finalizes session as `degraded` |
| Game crashes ≤ 60 s after injection, twice | Hooking auto-disabled for that game, Tier 2 takes over |
| Ring overflow (Agent stalled) | Overwrite-oldest; dropped count published in the ring header → session flagged with a data-quality warning |
| Ring overflow (Agent stalled) | Overwrite-oldest; ~~dropped count published in the ring header~~ the Agent counts drops from its own read index *(corrected 2026-10-04: the writer keeps no reader index and publishes no count — `04_CAPTURE` §Ring draining)* → session flagged with a data-quality warning |
| Layout/version mismatch DLL ↔ Agent | Agent refuses to attach, tells user to restart the game after update |
| Vendor API unavailable (no NVAPI etc.) | GPU telemetry degrades to `N/A`; frame metrics unaffected |
| DB locked/corrupt | Integrity check + backup-and-recreate in Tools |
| DB locked/corrupt | Integrity check + backup~~-and-recreate~~ in Tools ▸ Database maintenance *(corrected 2026-10-04: there is no recreate action)* |
## Data directory
@@ -99,9 +133,9 @@ ledger.db SQLite (WAL)
rules\detection-rules.json engine/platform/feature + anticheat blocklist
logs\ui-*.log, agent-*.log, overlay-<pid>-*.log (native log flushed at session end, never mid-frame)
crashdumps\*.dmp
breadcrumbs\<pid>.json pre-injection breadcrumb (19_SAFETY §Crash safety)
breadcrumbs\<pid>.json (corrected 2026-10-04: never created — the breadcrumb is the .partial file's header and notes)
tmp\<sessionGuid>.partial crash-safety flush of raw buffers, every 60 s (04_CAPTURE §Ring draining)
covers\*.jpg
covers\*.jpg (corrected 2026-10-04: never created — nothing writes games.cover_path)
```
## Key design decisions (ADR)
@@ -115,3 +149,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.
+21 -11
View File
@@ -10,12 +10,16 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable.
- FR-1.4 Remove game (asks whether to keep or delete its sessions).
- FR-1.5 "Supports" row shows shipped-capability hints (DLSS/FSR/XeSS/FG) — visually distinct from measured per-session values (`05_DETECTION` §Capability hints).
- FR-1.7 Delete all sessions (beta.11, owner decision D40): of one game from its page, or of every game from Settings ▸ Data, after a confirmation that says how many — with their frame and sensor series and notes; the library, the settings and every consent stay. The Agent deletes them (the rows are its, `06_DATA_MODEL` §Writer ownership) and refuses while a session it would delete under is being recorded.
- FR-1.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.
@@ -26,7 +30,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- 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 +39,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.
@@ -52,13 +56,15 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-6.1 Sessions table per game: date, duration, tier badge, Native, Displayed, FG×, lows, resolution + upscaler, RT/PT/RR chips, crash badge, tags.
- FR-6.2 Compare 2–5 sessions; **mixed-tier comparisons require explicit acknowledgement** and are marked on the chart.
- FR-6.3 Hardware snapshot per session; trend charts mark changes ("GPU driver 572.16 → 576.02").
- FR-6.6 Charts across a game's sessions (beta.11, owner decision D39): the Sessions tab opens with an overview of every hooked session's rate and lows (Presented FPS, or Native and Displayed where frame generation was measured; 1% and 0.1% lows), a click selecting the session; and the Trend draws more metrics beside the selected one, two units at most (the second against the right axis).
- FR-6.4 Sessions with mid-session settings changes are excluded from trends by default, with a toggle.
- FR-6.5 Session tags and notes.
### 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 +77,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 +110,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.
- **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-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.
+227 -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`).
**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** | 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 |
@@ -55,8 +55,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
@@ -369,13 +393,48 @@ 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
`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 —
@@ -423,6 +482,22 @@ rung identified the mode — only the *identification* comes from the ladder.
**Display rule (product requirement, CLAUDE.md rule 6):** wherever FPS appears and FG is active, render `"{native} → {displayed} FPS (×{factor} FG)"`. Cards show Native large, Displayed + factor secondary. Charts default to Native with a Displayed toggle. Exports contain all three.
**Rung 3's line carries its exclusions (2026-09-06, `HANDOFF` 7b / §H11).** `Active (technology not
identified)` is printed *by elimination among what this session saw*: 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 vendor SDK
strings the executable FILE carries. Never a vendor named as measured — XeFG cannot be hooked or
declared (licence), a compiled-in FSR 3 has no module — and the line says a frame generator compiled
into the executable would read the same.
**And the census's "cannot include generated frames" is now second-witnessed by the executable
file (2026-09-06).** A frame generator compiled into the exe loads no module (Rune Factory, Wukong),
so the capture host scans the executable on disk for the SDK strings (`ffxFsr3`,
`ffxFrameInterpolation`, `xefgSwapChain`, and the non-FG ones for the reader) and the clear-census
qualifier reads *MAY include generated frames* when a frame-generation-capable marker is in the
file. A marker is code or a symbol name in the file, never proof it ran, and never an identity.
**And when FG is not measured (2026-09-03):** render the one number as **Presented FPS** —
`144 FPS` with a qualifier chip chosen by the census above, never the word "Native", never
a factor, never `—` (which means `none`, a measured negative). The chip is muted when no
@@ -431,9 +506,18 @@ 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.
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
@@ -444,6 +528,12 @@ 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.
- 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
@@ -475,7 +565,8 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`.
> `18_GPU_VENDOR_APIS` L3) returns a feedback word per feature — and **measured 2026-09-06 (driver
> 616.64) its `CREATED | EVALUATE` bits are set for a process with NO NVIDIA-app override** on both
> no-override titles (`20_OPEN_QUESTIONS` §H5). So the capture host probes it out of process beside
> each module snapshot (`fl-probe-nvapi --ngx-state <pid>`, no injection, no consent), and the
> each module snapshot (in-process through `FrameLedger.NvapiBridge.dll` since 2026-09-10, P2 PR-E2;
> `fl-probe-nvapi --ngx-state <pid>` spawned before that — no injection, no consent either way), and the
> `upscaler:` line has a rung between the hooks and `N/A`:
>
> ```
@@ -498,6 +589,18 @@ 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.
## RT / PT / RR — evidence-based tri-state
@@ -583,15 +686,122 @@ 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; `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)
## 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 |
|---|---|---|
@@ -600,10 +810,13 @@ 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 |
| 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.
@@ -623,13 +836,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.
+306 -16
View File
@@ -4,19 +4,55 @@ The Agent decides *whether* to capture, *how* (tier), starts it, drains data, an
## Frame source abstraction (retained from the ETW design — and now with ONE implementation, which is the point)
```csharp
~~```csharp
public interface IFrameSource : IAsyncDisposable
{
CaptureTier Tier { get; }
IAsyncEnumerable<FrameEvent> StreamAsync(CaptureTarget target, CancellationToken ct);
}
```
```~~
> **Never written, and replaced rather than built — 2026-09-09 (P2 PR-C).** No `IFrameSource`,
> `FrameEvent` or `IAsyncEnumerable` stream ever existed in a `.cs` file; what ran every hooked
> session since 2026-08-06 is a *loop over a sink*, and that is the shape promoted into the
> shipped assemblies:
>
> ```csharp
> public interface ICaptureSink : IDisposable // Application.Capture — what the loop needs from the ring
> {
> 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();
> }
> public sealed class CaptureSession(...) // the loop: gate → inject → attach → drain, until something ends it
> {
> Task<CaptureOutcome> RunAsync(normalisedExePath, observed, payloadPath, ct); // attach mode
> Task<CaptureOutcome> RunLaunchedAsync(normalisedExePath, observed, payloadPath, args, ct); // launch mode
> }
> ```
>
> `CaptureSession` takes ports, not delegates, so the Agent's composition root supplies the
> adapters: `IRingAttacher` (`Infrastructure.Capture.ShmRingAttacher` over `ShmRingReader.TryAttach`
> with `FlGuardBuildId`), `ITargetLivenessSource` (`HeldProcessLivenessSource`, §S29(e)),
> `ITargetResolver` (`TargetResolver`, path only — never a pid), `IProcessLauncher`
> (`ProcessLauncher`, launch mode), `IRuntimeModuleSnapshot`, `INgxDriverProbe`,
> ~~`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.
> `MockFrameSource` / `FL_MOCK=1` remains specified and unwritten (CLAUDE.md §Dev mode); when it
> exists it is a second `ICaptureSink`, not a second loop.
| Implementation | Tier | Notes |
|---|---|---|
| `HookedFrameSource` | 1 | Injects (or relies on the Vulkan layer), maps the ring, drains at 10 Hz |
| ~~`HookedFrameSource`~~ `CaptureSession` + `ShmCaptureSink` | 1 | Injects (or relies on the Vulkan layer), attaches to the ring, drains at 10 Hz under the 30 s re-scan |
| ~~`EtwFrameSource`~~ | — | **Deleted from the design, 2026-08-28.** Tier 2 is not a frame source: it produces no frames. PresentMon was dropped (§S31 row P2), no mechanism replaced it (§G), and a port with no adapter on a tier that measures nothing is a row that only invites someone to implement it. The interface keeps its shape for `MockFrameSource` and for whatever Vulkan needs |
| `MockFrameSource` | dev | Synthetic frames incl. simulated FG/upscaler/RT records; `FL_MOCK=1` |
| `MockFrameSource` | dev | Synthetic frames incl. simulated FG/upscaler/RT records; `FL_MOCK=1` — unwritten; would be a second `ICaptureSink` |
Tier selection per launch:
@@ -41,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
@@ -70,22 +132,107 @@ 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.
- 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`
> (`Infrastructure.Watch`) takes the 1 Hz snapshot — pid, parent pid and image name from
> `CreateToolhelp32Snapshot`; the full image path (normalised the way a consent record's is) and the creation
> time through a `PROCESS_QUERY_LIMITED_INFORMATION` handle, and a process that refuses even that is listed with
> 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 — **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. **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
> at a time through `ISessionRecorder`, attach mode only; it decides nothing about hooking, the recorder's loop
> reaches the gate exactly as a console verb does. `WatcherHostedService` runs `PartialRecovery` first, every
> start, then the orchestrator. There is no `Channel` and no second consumer: `PollOnceAsync` is the only writer
> of the running-session table, and the sessions run on their own tasks. **Since P4 PR-1 (2026-09-14) a second
> hosted service runs beside it under `--serve`: `DetectionHostedService`, the static detection sweep
> (`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`)*: `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
> loaded nothing and the module scan *fails* against it (`ERROR_PARTIAL_COPY`, §S1 measured), so the guard
> cannot run before the loader has. The built order is **start → the guard WAITS → inject**: the host
> starts the consented executable (`ProcessLauncher`: working directory beside the exe,
> `FRAMELEDGER_ENABLE_VK_LAYER=1` in its environment for the Vulkan layer, the handle held from birth so
> the pid cannot recycle), then asks the guard through its new waiting entry, `FlGuardedInjectWhenReady`,
> which polls the loader every 50 ms — through the module seam, matching **no** blocklist — until
> `dxgi.dll` with `d3d11.dll` or `d3d12.dll`, or `opengl32.dll`, or `vulkan-1.dll` is mapped, and *then*
> runs every check and injects exactly as attach mode does. The poll decides **when** the full scan runs,
> never whether it passes. **Vulkan wins over a D3D or OpenGL runtime beside it, and since 2026-09-10 over
> one mapped a poll ahead of it:** a static D3D/OpenGL import is in the module list from the first
> instruction while a Vulkan title's loader arrives milliseconds later, so the guard reads once more, one
> interval later, before it commits to the injecting branch (measured on the harness's own `--vulkan` mode
> the moment PR-D's warmer host reached the poll 20 ms sooner; `fl_guard` pins it in both directions). A target that exits first, or maps no runtime inside the budget (60 s in the
> host), answers `LaunchTargetExited` / `LaunchNoPresentationRuntime` with nothing injected; a launcher
> 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.
> **The host never terminates what it launched**: any refusal after the start
> leaves the title running unhooked, which is Tier 2.
>
> **What it measures about itself, which is the input §S1 deferred on.** The report prints the wait
> (`launch: the guard injected N ms after the process was started`) and `FlWriterState.dxgiPresentsBeforeHook`
> — DXGI's own count, read at the first hooked present on the first hooked chain, of presents completed
> before the hook was in. **0 means nothing ran unhooked on that chain**; N is the early-init cost, per
> title, from the title itself. On `hook-harness` (device at startup, presenting every 8 ms) the real-seam
> fixture injects within one poll and reports the ~1 s of presents the fixture ran before asking — a
> measurement of the fixture, not a bound on a title. What launch mode can *never* see is anything before
> its own injection, and a swapchain created before the runtime-mapped poll fired is exactly that; the
> number says how much.
>
> The CaptureHost's verb is `launch --exe <path> [--args "<game's own arguments>"] [--seconds <n>]`; the
> consent record, the gate and the payload are the ones `capture` uses, reached one process later.
**Attach mode.** Game launched from Steam/GOG/Epic normally; watcher sees it, guard runs, inject. Feature hooks install late, so early-init facts may be missed; the Overlay compensates by re-reading state on the first `EvaluateFeature` call it does observe, and the session is flagged `late_attach = true` so the UI can note that startup-time settings may be incomplete.
Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).
~~Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).~~ *(Corrected 2026-10-04: not built — there is no wrapper entry point and no UI text; a game started from Steam is recorded in attach mode. The parenthesis still holds: never modify a user's Steam config for them.)*
## The guard
The guard is **native** (`20_OPEN_QUESTIONS` §S13(a)) and the Agent reaches it through `IAntiCheatGuard`, a **thin P/Invoke facade over the single implementation** — never a second one. Two blocklist matchers that can disagree is a fail-open by construction: the day they diverge, one is wrong and nothing says which. Nothing managed parses rules or matches a blocklist, and a test asserts it (§S15 item 1).
The facade exposes exactly two operations, and neither hands out a clearance:
The facade exposes ~~exactly two operations~~ four *(corrected 2026-10-04: `GuardedInjectWhenReadyAsync`, launch mode's waiting entry, and `PreScanGameAsync`, the advisory checks 3–4 behind FR-2.2 and the library pre-scan, joined the two below; since D33 each takes `toleratedFamily`, a family name the guard resolves itself)*, and none hands out a clearance:
- `GuardedInjectAsync(pid, payload)` — runs every pre-injection check and, only on a pass, injects. There is no overload that skips the checks and no way to supply evidence; the guard collects its own, so a caller can ask but only the guard answers (§S13(b)).
- `EvaluateAsync(pid)` — the same checks with no injection, for the 30 s in-session re-scan. It cannot be used to pre-authorise anything: it takes no payload and returns no token, so acting on a pass means calling `GuardedInjectAsync`, which re-collects.
@@ -94,13 +241,31 @@ 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
> `Application.Consent.IGameConsentStore`; **SQLite is P2's adapter for it** and is still
> `Application.Consent.IGameConsentStore`; ~~**SQLite is P2's adapter for it** and is still
> unwritten, and `06_DATA_MODEL` declines to guess `0001_init.sql` before its consumers exist.
> The only adapter today is a file-backed store inside the unshipped `FrameLedger.CaptureHost`,
> whose record dies with the build tree and is **not** a migration source.
> whose record dies with the build tree and is **not** a migration source.~~ **Written 2026-09-09
> (P2 PR-B): `Infrastructure.Persistence.SqliteGameConsentStore` over the `games` table of
> `0001_init.sql`, with the file store deleted rather than migrated.** The unshipped host now opens
> its OWN `ledger.db` beside its binary (HANDOFF §P2 decision D5), so the Agent stays the sole owner
> of `%LOCALAPPDATA%\FrameLedger`; the Agent's console verb (PR-F, D4) and the UI's dialog (P3) are
> the producers that stamp from the Agent's clock, which is the property the paragraph below says a
> file could not uphold.
>
> **A file cannot uphold the Agent-stamp property, and saying so is the honest position.**
> `19_SAFETY` §User-facing consent requires the timestamp to be *"stamped by the Agent, never
@@ -140,6 +305,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
@@ -151,11 +317,40 @@ 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
> **Written 2026-09-09 (P2 PR-C), because `20_OPEN_QUESTIONS` §G listed it as unspecified and the
> loop had just become shipped code.** Four kinds of thread, one owner per shared object.
| 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 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 |
| **Pipe** (built 2026-09-13, P3 PR-1: `PipeServer.RunAsync` accepting, one reader and one writer task per client) | Per frame | Each client's bounded outbound queue (drop-oldest, so a publisher never waits) and the answer to each request | `Hello` / `GetStatus` / `Ping` read `AgentStatus`, an immutable snapshot the publisher swaps whole; **never the ring, never the recorder**. The events themselves are handed over ON the session loop's task by `SessionEventPublisher` (`ISessionObserver`, called after the recorder's own work each tick) — the loop enqueues a frame and returns |
Rules the table encodes: **nothing but the session loop touches `ShmRingReader`** — no lock is
added to the reader, because there is no second party; a diagnostic wanting a look at the ring
is a second consumer on a single-consumer ring and is refused by review and by
`NoSecondRingReaderTests`. The ring holds ~16 s at a game's present rate, so a 100 ms cadence
has two orders of magnitude of headroom, and `TotalDropped > 0` stays a session warning rather
than a tuning knob. ~~There is no UI thread in P2; the pipe reader (P3) joins as one more
`Channel` producer, not as a reader of anything above.~~ **The pipe's read half joined 2026-09-13 exactly so** (the row above): nothing on
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
@@ -176,7 +371,21 @@ Idle → Detected(pid) → Guarded → Injecting → Capturing → Finalizing
**Vulkan sessions do not pass through `Injecting`.** The layer is loaded by the
Vulkan loader when the Agent launches an opted-in game, so the path is
`Detected(pid) → Guarded → Capturing`, skipping injection entirely. This is
`Detected(pid) → Guarded → Capturing`, skipping injection entirely.
> **Built 2026-09-06 (P1 item 3), through launch mode.** The guard's waiting entry classifies the
> launched target by what it mapped: `vulkan-1.dll` with no D3D or OpenGL runtime runs the **full** guard
> and, on a pass, injects nothing — `TargetIsVulkanLayered`, which the loop reads as "attach to the
> layer's ring" with launch mode's budget (the ring appears at the title's first `vkCreateDevice`). The
> CaptureHost's `launch` gives the process the layer's environment (`VkLayerLaunchEnvironment`:
> `VK_ADD_IMPLICIT_LAYER_PATH`, the enable variable, the enable-list line for the session); a D3D title
> ignores all of it. One ring per process, the first creator owns it (`fl_shm_host.h`). ~~Attach mode on a
> running Vulkan title stays Tier 2~~ **— not what the code does, found 2026-09-15 while checking `legal/ACCURACY.md`:
> attach mode calls `FlGuardedInject`, which has no presentation-runtime branch (only launch mode's
> `GuardedInjectWhenReady` refuses a Vulkan title with `TargetIsVulkanLayered`), so a running Vulkan title that
> passes the guard gets the Direct3D Overlay injected. What it records there is unverified and nothing tests it;
> whether attach mode should refuse a Vulkan title instead is the owner's open decision.** Only a launch can set
> the loader's environment. This is
stated because the state machine above, read literally, meant the 30 s guard
re-scan — which `19_SAFETY` calls the most important runtime behaviour in the
capture layer — was not specified to run for Vulkan at all. It runs for **every
@@ -186,19 +395,100 @@ 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
> `games` and `hardware_snapshots` rows, the telemetry poller for the session, the `.partial` from before
> the first record to after the last, the loop, the classification, the finalize, the crash policy. The
> loop (`CaptureSession`) owns `Guarded → Injecting → Capturing` and reports them as ONE outcome, so what
> the recorder observes and writes as breadcrumbs is `started` (the file exists) → `attached` (the ring is
> ours; Tier 1 from here) → `ended <reason>` → `finalizing <exit_status>`; a loop that never attached is a
> Tier-2 row with the reason in `capture_notes` (`tier2: attach=…; guard=<reason>/<family>/<signal>`).
> Everything the recorder does runs on the loop's task through `ICaptureObserver`: after every drain it
> drains the poller's queue and, on the flush interval, appends to the `.partial` — the loop stays the
> ring's only reader (§Threading model). **Finalizing as built:** step 1 is the loop's own last drain;
> steps 2–3 are `SessionAggregator` over Domain's calculators and `FgLadder` (the identity and withhold
> rules, moved out of the host's report so the row and the report read one implementation); step 4 is the
> FULL blob set through `ISeriesCodec` — every column of `frame_blobs` that any record claimed, `latency_us`
> included, and one `sensor_blobs` series per field any sample carried, aligned to `t_ms` with −1 where a
> tick had no reading; step 5 is `ISessionRepository.InsertFinalizedAsync` (one transaction) then the
> retention sweep, and the `.partial` is deleted only on `Saved` or `Discarded`. `Interrupted` is
> `PartialRecovery`'s alone: at startup every pending file becomes an `interrupted` row from its valid
> prefix, or is dropped for one of three stated reasons (already stored, too short, unreadable). The
> unshipped host lowers the discard threshold to 5 s for bounded operator captures; the Agent keeps 30 s
> for every session nobody bounded and lowers it to the bound for a `--console capture --seconds N` (PR-F).
## 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]`.
- Normal: presenting PID exit code 0 — **and since beta.8 any exit code that is not an exception's** (End task and taskkill leave 1; a program's own error exit; Ctrl+C's `0xC000013A`), kept in `capture_notes` and said as what it is.
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
- `unhooked_safety`: the guard fired mid-session.
- `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`.
Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking auto-disabled for that game** and the reason stored on the `games` row (`19_SAFETY` §Crash safety). The UI explains it and offers a manual re-enable after the user has, e.g., updated their GPU driver.
> **Built 2026-09-10 (P2 PR-D).** `ExitStatusMapper` is the table above as one function of what the
> session saw: our own safety stop is `unhooked_safety` whatever the process did next; the capture side
> stopping on its own (self-disabled, blocklisted mid-session, supervision lost, hooks never installed) is
> `degraded`; a non-zero exit code — read from the held handle, so it is the target's own — or an
> Application Error (1000) / WER (1001) event naming the executable inside `[start, end + 30 s]`
> (`EventLogCrashSource`, read-only, unprivileged, false when the log cannot be read) is `crashed`; a
> target still running when a bounded capture ends is `normal`. `capture_notes` keeps the fine reason, the
> 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
> Native / Displayed / factor, `UpscaleExtent` for the resolutions — so the live number and the stored one cannot disagree. Rule 6 holds
> at the wire: Native / Displayed / factor appear only when frame generation was measured in the window; otherwise the presented rate
> 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)
+211 -20
View File
@@ -26,6 +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
@@ -37,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
{
@@ -54,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`. 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
@@ -78,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:
@@ -127,12 +144,14 @@ 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+)` |
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | `unreal_build` (since 2026-09-27, §Engine version): the shipping executable's numeric file version and the engine's branch name inside it. ~~ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)`~~ — two capture groups, of which the evaluator returns the first, so every Unreal version it ever stored was a bare `4` or `5` |
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
| 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) | `N/A` — the `.js` header needs a `from` that `strings_regex` lacks |
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `N/A` — one rule, the variant unnamed |
| 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 | — |
@@ -141,26 +160,140 @@ 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.
### Platform signatures & metadata
| Platform | Signals | Metadata |
|---|---|---|
| Steam | `steam_api64.dll`/`steam_api.dll` sibling, or path contains `steamapps\common` | nearest `steamapps/appmanifest_<id>.acf` (walk up): `appid`, `name`, `buildid` → version |
| GOG | `goggame-<id>.info` sibling, or `Galaxy64.dll` | `.info` JSON: `gameId`, `name`, `version` |
| Epic | `EOSSDK-Win64-Shipping.dll`, or path under an Epic install | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
| 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.
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf` except `SteamLibrarySource.KnownTools` (2026-09-22: Steamworks Common Redistributables, Borderless Gaming, Wallpaper Engine, SteamVR, the Proton and Steam Linux Runtime entries, Blender — tools Steam's manifests do not distinguish from games, and which became library rows the watcher recorded); GOG via `HKLM\SOFTWARE\WOW6432Node\GOG.com\Games\*`; Epic via `Manifests\*.item`; itch by receipt scan. Import presents a review checklist; nothing is launched, nothing is hooked on import.
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days.
> **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`~~ — **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
> provenance rule as a detection write (a value the user typed is never overwritten). The table above says
> "walk up to the nearest manifest" for the per-game metadata extractors; those are still unbuilt
> (`GameFileProbe` keeps `manifest_field` uncollected) — the import reads the launchers' own indexes instead.
> **Privacy:** local files and registry keys the launchers already wrote, read-only; no process is touched, nothing
> is fetched (CLAUDE.md rule 8's "opt-in store metadata" is the online lookup, which does not exist). First-run
> step 4 now points at File ▸ Import library… rather than saying "later build".
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days. *(Since beta.8 the PE versions are stored beside the store's rather than instead of it — §What the files say about themselves; the page labels a store's value with its store, "Steam build 20374416".)*
## Capability hints (explicitly labelled as such)
@@ -168,28 +301,86 @@ 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
`GameFileProbe` reads the executable's import and delay-load tables (`Infrastructure.Detection.PeImports`,
bounded and read-only) and looks for the loader's name as an ASCII or UTF-16 string in the bounded scan;
`StaticDetectionResult.UsesVulkan` is true / false / null (could not read), and the sweep stores a true as the
id `vulkan` in `capability_flags` beside the rule ids. It is what `17_HOOK_ENGINE` §Vulkan's register-on-consent
automation keys on, and what the game page shows as "Supports Vulkan". Never a claim about what a session
presented — that is `sessions.api`, measured.
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. The session
summary prints the loaded list and names such a difference ("the game ships 3.7.10.0: another copy was loaded");
it does not claim who loaded it.
## 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).
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).
- **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
- Detection results cached per game; refreshed when exe timestamp/size changes or `rulesVersion` changes. Implemented as `DetectionCacheKey` (path + size + mtime + `rulesVersion`).
- **A re-run never overwrites a field the user supplied.** `games.field_provenance` records where each value came from; anything not marked `detected` is left alone, and an absent or unrecognised provenance reads as *user*. Without this rule the re-run triggered by every rules update silently clobbers every correction the user has ever made — a data-loss bug that surfaces weeks later on somebody else's machine. Stated here because no document said it before, and the safe default is the one that costs a badge rather than a value.
> **Built 2026-09-14 (P4 PR-1), and two things this section did not say.** *When it runs:* the Agent's
> `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 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
> `detection_exe_size_bytes` / `detection_exe_mtime_ms` beside `detection_rules_version`. *And the provenance
> rule, applied per field in the repository:* a `user` entry, an unrecognised entry, or a value with no entry is
> 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`,
> `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.
- Module enumeration uses read-only handles (`PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_VM_READ`); never a handle with write access outside the injection call itself.
- No game memory is read for detection purposes — all runtime facts come from arguments to APIs we hooked (CLAUDE.md rule 4).
+433 -26
View File
@@ -2,30 +2,94 @@
`%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`, and the hook-state columns on `games`. UI writes `games` (user-editable fields), `session_annotations`, `settings`, `legal_acceptance`. Both read everything.
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It is the one Agent write that deletes a `games` row; it never touches a consent column. **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself *(for Delete all sessions; FR-1.4's removal is the App's own cascade, above — corrected 2026-10-04)*. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; ~~never a `hook_*` column~~ **and two downgrades** *(corrected 2026-10-04)*: *Change executable* (2026-09-21, `GameLibrary.ChangeExecutableAsync`) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and *Remove game ▸ Delete sessions too* (FR-1.4) deletes the `games` row, cascading to its sessions, segments, blobs and annotations), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
## Schema (v2 — hook architecture)
> **`src/FrameLedger.Infrastructure/Persistence/Migrations/0001_init.sql` is normative since 2026-09-09
> (P2 PR-B).** The block below is the shape as drafted and is kept for its comments; the script adds
> what this document had no column for, each with the reason beside it in the script:
>
> - `sessions.session_guid` (UNIQUE) — the identity the `.partial` file, the pipe and recovery key on
> (`20_OPEN_QUESTIONS` §G "Session identity"); `qpc_epoch` + `qpc_frequency` — the time base the
> blobs and sensor series are aligned to (`03_METRICS` §Export, §Sensor aggregates);
> `capture_mode` (`attach|launch`); the drain's own accounting (`drain_ticks`, `foreground_ticks`,
> `records_before_attach`, `dxgi_presents_before_hook`, `gap_count`, `guard_ticks_published`,
> `launch_wait_ms`); the 2026-09 metric additions (`presented_fps` + `presented_qualifier`,
> `dxgi_unseen_total` / `dxgi_present_samples` / `displayed_counted_by`, `sl_tag_census`,
> `sl_interposer_version`, `upscaler_driver_reported` / `fg_driver_reported` / `ngx_driver_words`,
> `fg_none_withheld_reason`, `runtime_modules`, `executable_markers`, `writer_status_at_end`,
> `early_stop_family`, `loader_signals`).
> - `games.exe_size_bytes` / `exe_mtime_ms` (the `ExecutableFingerprint`),
> `hook_consent_provenance` (the `ConsentProvenance` NAME, default `NotRecorded`),
> `hook_consent_disclosure_version`, **`hook_prescan_state`** (`not_run|clean|blocked|unverified` —
> the third state one nullable `hook_blocked_reason` could not carry; nothing in P2 clears the
> reason, per the owner question below), `hook_autodisabled_at`, `hook_last_injected_at`.
> - `frame_blobs.frame_index`, `swapchain_ids`; `sensor_blobs` gains the `t_ms` series.
> - **`fg_source`'s domain is `api|cadence|none|manual`, NULL = not measured** — this document said
> `api|cadence|manual` while `03_METRICS` names rung 4 `none`; the CHECK carries the union.
> - **Every `*_at` / `*_ms` INTEGER is unix-ms UTC** (CLAUDE.md §Coding conventions), stated in the
> script because it was stated nowhere in this file. QPC never leaves the pipeline except
> `qpc_epoch` / `qpc_frequency`.
> - `exe_path` is `UNIQUE COLLATE NOCASE`, because consent matches `OrdinalIgnoreCase` on the
> normalised full path and the index must agree with the lookup.
```sql
CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL);
CREATE TABLE games (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
exe_path TEXT NOT NULL UNIQUE,
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|none
store_id TEXT,
engine TEXT, engine_version TEXT,
-- (schema 0015, ALTERed last) engine_version_source TEXT: where engine_version came from — a
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version, or the rule's
-- extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
publisher TEXT, game_version TEXT,
cover_path TEXT, notes TEXT,
removed_at INTEGER, -- schema 0002 (P3 PR-3): FR-1.4 "remove, keep sessions" — the row stays
-- (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)
-- 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 (dlss/dlssg/dlssd/fsr/xess) — never a measurement
capability_flags TEXT, -- JSON: what the game SHIPS — never a measurement. Since P4 PR-1 (2026-09-14) a JSON
-- array of the rule ids of rules/detection-rules.json (dlss, dlss_g, dlss_rr, streamline,
-- fsr, xess, xefg), written whole by the Agent's detection sweep; this line used to spell
-- the App's tokens (dlssg/dlssd), which the App still reads for older rows
-- tri-state defaults inherited by new sessions
rt_default TEXT NOT NULL DEFAULT 'na',
@@ -33,6 +97,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
@@ -51,13 +123,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
> ~~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.
> 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~~ *(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
@@ -68,7 +145,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
@@ -80,12 +158,20 @@ CREATE TABLE games (
> toggle (a false refusal with no appeal) nor be cleared (a fail-open). One nullable
> TEXT column cannot carry three states.
>
> **The file-backed record is NOT a migration source.** It lives in a build output,
> `git clean` removes it, and this section's own argument against guessing a schema
> applies just as well to inheriting one from a throwaway. When the `games` table is
> written it is written from this document.
> **The file-backed record was NOT a migration source, and was not migrated.** It lived in a
> build output, `git clean` removed it, and when the `games` table was written (2026-09-09, P2
> PR-B) it was written from this document — the file store and its DTOs were deleted the same day.
> The two fields the consumer needed and this table lacked are columns now:
> `hook_consent_provenance` and `hook_consent_disclosure_version`; the third pre-scan state is
> `hook_prescan_state`. **`ConsentProvenance` has a third name since 2026-09-10 (P2 PR-F)** — and a fourth, `ConsentDialog`, since 2026-09-13 (P3 PR-4), the only one a shipped user path produces:
> `AgentConsoleOperator`, the Agent's own `--console consent grant` (HANDOFF §P2 decision D4) — a
> 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
@@ -138,7 +224,7 @@ CREATE TABLE sessions (
sync_interval_mode TEXT, -- observed vsync behavior
-- upscaling / FG (measured at tier 1)
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown, and fsr since 2026-09-04 (FL_UPSCALER_FSR_UNVERSIONED; added 2026-10-04)
upscaler_quality TEXT,
upscaler_sharpness INTEGER, -- percent; NULL when the API reports none
render_w INTEGER, render_h INTEGER, -- dominant segment
@@ -154,6 +240,10 @@ CREATE TABLE sessions (
fg_mode TEXT NOT NULL DEFAULT 'na',
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
-- 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
-- the loader reported in the process. NOT a measurement and never a source for fg_mode
-- or upscaler: it qualifies the presented figure when fg_mode is 'na' (03_METRICS §Rung
@@ -193,7 +283,33 @@ 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 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
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);
@@ -230,26 +346,91 @@ 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)
-- 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)
);
CREATE TABLE session_annotations (
session_id INTEGER PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
tags TEXT, notes TEXT
tags TEXT, notes TEXT, -- tags: a JSON string array (P3 PR-3); a row that would be all NULL is deleted
-- schema 0002 (P3 PR-3): FR-8.3's per-session overrides live HERE, on the UI's table, beside the
-- measurement on sessions and never over it — clearing an override restores what was measured.
-- NULL = no override. sessions.rt_source stays the measurement's word.
rt_override TEXT CHECK (rt_override IS NULL OR rt_override IN ('yes', 'no', 'na')),
pt_override TEXT CHECK (pt_override IS NULL OR pt_override IN ('yes', 'no', 'na')),
rr_override TEXT CHECK (rr_override IS NULL OR rr_override IN ('yes', 'no', 'na'))
);
CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
-- keys in use: hooking.kill_switch = '1' (FR-2.4, P2 PR-F; anything else, or no row, is off)
-- the full key list is §Settings registry below (P3 PR-3)
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`
> (`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
HANDOFF §P3 decision D16, built as `Application.Settings.SettingsRegistry` (P3 PR-3, 2026-09-13) and
closing `20_OPEN_QUESTIONS` §G's row. `settings` is key/value TEXT; the registry is the only key list, and
`RegisteredSettings` over `ISettingsStore` **validates writes and tolerates reads** — a hand-edited or
out-of-range row reads as the default, never as an exception. Booleans are exactly `1`/`0` (the kill
switch's rule); integers are invariant-culture within an inclusive range; choices are compared ordinally.
**No "setting changed" message exists:** the Agent re-reads its keys at each session start
(`SettingsRecorderPolicy` → `RecorderOptions`), and the UI owns the rest.
| Key | Kind | Default | Range / choices | Read by |
|---|---|---|---|---|
| `ui.language` | choice | `en` | `en` · `vi` · `ja` | UI |
| `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) |
| `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.library_view` | choice `grid`\|`list` | `grid` | | UI (beta.11, 2026-10-03): the Games library as a grid of cards that fills the width, or as a list; written by the page's own switch, no Settings row (`08_UI` §Games) |
| `capture.background` | bool | `1` | | ~~Agent~~ nobody *(corrected 2026-10-04: no Agent code ever read it, so the watcher recorded every tracked game whatever it said; beta.12 removed its switch from Settings and reserved the key — `SettingsRegistry.CaptureBackground`)* |
| `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) |
| `update.auto_check` | bool | `1` | | UI (P4 PR-5: the startup silent check, `11_UPDATER` §Flow "if enabled") |
| `privacy.online_metadata` | bool | `0` | | *reserved* — no consumer and, since 2026-09-16, no toggle on Settings either: the store request it would enable has no code (CLAUDE.md rule 8), and PRIVACY_POLICY 2.2 removed the row that described it |
| `log.debug` | bool | `0` | | UI |
An operator's bounded capture (`--console … --seconds N`, which lowers the discard threshold to N) keeps
its bound under any `capture.min_session_s`: the setting moves the product's rule, not the operator's.
## Comparison safety
Because Tier-1 and Tier-2 sessions carry different fields, every query that compares sessions **must** filter or group by `capture_tier`. **Since 2026-08-28 the difference is total rather than partial** — a Tier-2 session has no frame data at all — so a mixed-tier overlay is not a degraded comparison, it is a comparison with nothing on one side. The Compare view refuses to overlay mixed tiers without an explicit "compare across tiers anyway" acknowledgement, and marks the chart accordingly. Likewise `settings_changed_midsession = 1` sessions are excluded from trend lines by default (they average across a settings change and are misleading), with a toggle to include them.
@@ -258,23 +439,249 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
`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.
## The `.partial` file
> **Built 2026-09-10 (P2 PR-D), as HANDOFF §P2 pre-committed it.** `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`
> (the unshipped host: `tmp\` beside its binary, decision D5), one per session, append-only, written at every
> state transition and every flush interval (60 s), deleted by the finalize's success, read by recovery at the
> next start. Format: `chunk := u32 type | u32 length | payload | u32 crc32(type ‖ length ‖ payload)`,
> little-endian, and **the valid prefix wins** — the reader stops at the first chunk that is short or fails
> its check, so a kill at any byte loses at most the chunk being written (`PartialSessionFileTests` kills
> at every offset of a fixture and asserts exactly the complete chunks survive). The file is flushed to the
> OS after every chunk; the threat is the Agent dying, not the machine losing power.
>
> | type | payload | when |
> |---|---|---|
> | 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~~ 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
> become `interrupted` rows ended at the last flush (or the last record's clock), with every measured
> 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
Default: raw blobs for the **last 20 sessions per game** (configurable N or unlimited). Aggregates and segments kept forever. Sweep at finalize + on demand (Tools → DB maintenance, which also offers `PRAGMA integrity_check`, `VACUUM`, backup).
Default: raw blobs for the **last 20 sessions per game** (configurable N or unlimited — `retention.raw_sessions_per_game`, 0 = unlimited, §Settings registry). Aggregates and segments kept forever. Sweep at finalize + on demand (Tools → DB maintenance, which also offers `PRAGMA integrity_check`, `VACUUM`, backup).
> **Built 2026-09-15 (P4 PR-7).** The on-demand sweep is the **Agent's**: the App sends `SweepRetention` (`07_IPC`),
> and the Agent runs `ISessionRepository.SweepRetentionAllAsync` — the finalize's per-game rule for every game in one
> transaction, `ROW_NUMBER() OVER (PARTITION BY game_id ORDER BY started_at DESC, id DESC)`, so the two can never
> disagree about which session is the Nth, and a removed game's kept sessions are swept like any other. A keep of 0
> never reaches it: unlimited is honoured by not sweeping. The other three run in the App through
> `Infrastructure.Persistence.LedgerMaintenance` and change no row: `PRAGMA integrity_check`; a backup through
> `VACUUM INTO` (a complete, consistent copy while the Agent keeps writing; never over an existing file and never onto
> the ledger, its WAL or its shared-memory file — the save dialog's "replace?" would otherwise have deleted the live
> database); and compaction, `VACUUM` + `wal_checkpoint(TRUNCATE)`, refused while a fresh `GetStatus` reports a
> session. `LedgerDatabase.MaintainAsync` is the one way to run a statement outside a transaction, and it is for
> these statements only.
## 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 global mutex. Never edit an applied script; only append.
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
> columns on `session_annotations` and `games.removed_at`. `LedgerDatabaseTests` asserts one
> `schema_migrations` row per script, so `LatestVersion` is 2.
> **`0003_fg_refusal.sql` (2026-09-14) — `sessions.fg_refusal`.** The owner's ledger held two hooked rows with
> `fg_mode = 'dlssg'`, `fg_source = 'api'` and `fg_factor` NULL — the identity stood, the count refused — and
> nothing recorded which refusal; every FG surface said N/A beside a detection that had succeeded. One
> `ALTER TABLE ADD COLUMN`, written by the Agent (`SessionAggregator.ApplyFg`), read by the UI for the "factor not
> counted" tooltip (`08_UI` §FPS display rule). `LatestVersion` is 3; `LedgerDatabaseTests` asserts the column.
> **`0004_detection_cache.sql` (P4 PR-1, 2026-09-14) — `games.detection_exe_size_bytes` / `detection_exe_mtime_ms`.**
> The detection cache key's exe half (`05_DETECTION` §Caching), apart from `exe_size_bytes` / `exe_mtime_ms`,
> 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`.
> **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. *(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.
+179 -28
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,23 +53,63 @@ 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
uint32_t overlayEnabled; // @8 in-game overlay draw toggle (v1.1)
uint32_t guardTicks; // @12 completed guard evaluations, NOT a timer
uint32_t reserved[12]; // @16..63 must be zero
uint32_t logFlushRequested; // @16 a COUNTER: bumped by the Agent at session end; the watchdog flushes the native log on a change (17_HOOK_ENGINE §Native logging, 2026-09-06)
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#
@@ -259,36 +303,115 @@ 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.
- Message mode, single server (Agent), max 2 clients (UI + future CLI), `PIPE_REJECT_REMOTE_CLIENTS`.
- ACL: current interactive user's SID + Administrators. Reject clients whose token user differs.
> ~~**P3, not P2** (HANDOFF §P2 decision D10, restated 2026-09-10 with PR-F): the Agent's `--serve` is
> watcher-driven and logs to `logs\agent-*.log`; nothing below exists in code yet, and the P2 Agent has no
> client. The pipe reader joins the threading model as one more producer when it is written (`04_CAPTURE`).~~
>
> **The READ half is built, 2026-09-13 (P3 PR-1; HANDOFF §P3 decisions D11–D13).** `FrameLedger.Shared.Ipc`
> holds the envelope, the message set below (read half only), `IpcJsonContext` and `IpcFraming`;
> `Infrastructure.Ipc.PipeServer` is the Agent's end and `PipeClient` the UI's; `PipeServerHostedService` runs
> the server under `--serve` only — `--console` composes it and never starts it, so it publishes to nobody.
> The events come from `Application.Ipc.SessionEventPublisher`, the recorder's second observer
> (`ISessionObserver`), on each session's own task; `SessionProgress` is computed once a second and only
> while a client is connected. ~~**The command half — `SetWatchlist`, `SetHookEnabled`, `LaunchGame`,
> `PauseCapture`/`ResumeCapture`, `StopSession`, `UpdateRules`, `Shutdown` — is PR-1b**: none of those types
> is declared in `Shared.Ipc` until its handler exists, and the Agent answers them `Error UnknownType` today.~~
> **The command half is built the same day (P3 PR-1b): `Application.Ipc.AgentCommandHandler`**, every row
> below with its ack, and the one rule §The pipe is not a trust boundary states is what each handler does —
> the Agent establishes the fact itself. Two things a reader must not assume: `SetHookEnabled true` **stamps
> nothing yet** (the pre-scan runs, a block is recorded, and a clean scan is answered `Error
> DisclosureUnavailable` until FR-2.1's reviewed text ships in PR-4), and `SetWatchlist` **removes nothing**
> (removal is FR-1.4's, with its "keep the sessions?" question — never a bulk message's).
- Message mode, single server (Agent), max 2 clients (UI + future CLI), `PIPE_REJECT_REMOTE_CLIENTS`. *(Built:
`CreateNamedPipe` through CsWin32 with these flags stated in code, two instances, a semaphore slot per client
so a third connection waits rather than a third instance existing — `PipeServerClientTests`.)*
- ACL: current interactive user's SID + Administrators. Reject clients whose token user differs. *(Built as the
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.~~)*
> **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`.
- Envelope: `{ "type": …, "id": …, "payload": … }`; `Ack` correlates by `id`; events have no `id`.
*(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`.)*
- Envelope: `{ "type": …, "id": …, "payload": … }`; `Ack` correlates by `id`; events have no `id`. *(camelCase
on the wire, nulls omitted, unknown fields skipped both ways — `IpcCodecTests` pins the last, which is what
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. *(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, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, etwAvailable }` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` |
| `SetWatchlist` | UI→A | `{ entries: [{ gameId, exePath }] }` — full replace; UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary) |
| `LaunchGame` | UI→A | `{ gameId }` → suspended-launch + inject path (`04_CAPTURE` §Launch mode) |
| `SetHookEnabled` | UI→A | `{ gameId, enabled }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself** |
| `PauseCapture` / `ResumeCapture` | UI→A | global |
| `StopSession` | UI→A | `{ sessionGuid }` — graceful unhook + finalize |
| `UpdateRules` | UI→A | **no payload** — a trigger, not a source. The Agent re-reads only its own `%LOCALAPPDATA%\FrameLedger\rules\` copy |
| `Shutdown` | UI→A | graceful stop |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, pid, tier, startedAt }` |
| `SessionProgress` | A→UI | 1 Hz: `{ elapsedS, nativeFps5s, displayedFps5s, fgFactor?, fgMode, upscaler, upscalerQuality, renderW/H, outputW/H, rtActive, gpuTempC?, cpuTempC?, vramProcMb, latencyUs? }` |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId, exitStatus, tier }` — UI loads the full row from SQLite |
| `CaptureRefused` | A→UI | `{ gameId, reason, 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) |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from, to, 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 |
| `SafetyUnhook` | A→UI | `{ sessionGuid, signal }` — anti-cheat appeared mid-session; prominent UI notice |
| `CaptureError` | A→UI | `{ code, message }` — `InjectFailed`, `RingVersionMismatch`, `EtwAccessDenied`, ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed` |
| `Ping`/`Pong` | both | 15 s keepalive |
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, exceptionDisclosureVersion /* D33, 2026-09-26: the user-mode exception's disclosure this Agent grants against */, elevationOutcome /* beta.10, D34: the admin mode's answer at this start — granted, declined, other-account, failed — or null when nobody asked */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. ~~`vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered)~~ `vulkanLayerRegistered` is the HKCU implicit-layer registration as the Agent found it at start *(corrected 2026-10-04: since P3 PR-8b; true while `VkLayerReconciler` keeps the layer registered for a hook-enabled Vulkan game, P4 PR-2)* and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` — and `activeSessions[]`, one `{ sessionGuid, gameId, gameName?, pid, tier, startedAt, hold? }` per running session. **`hold` added 2026-09-23, optional:** present on a session held unhooked (Tier 2), with the same words `SessionStarted.hold` carries; a session listed at tier 2 WITHOUT a `hold` has not attached yet — it is starting, not held. The App reads this list on every (re)connect (§Client behavior) |
| `SetWatchlist` | UI→A | `{ entries: [{ gameId?, exePath }] }` — ~~full replace~~ **ensure, never remove** (built 2026-09-13, PR-1b): each entry's path is normalised by the Agent, its row ensured with hooking OFF when new, and the ack is `WatchlistAck { games: [{ gameId, exePath, name }], unreadable: [exePath] }`; `gameId` in a request is a hint and never trusted over the path. UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary). *Since the App writes `games` rows itself under `06_DATA_MODEL` §Writer ownership (HANDOFF §P3 D15), this is the pipe's way of adding a row, not the only one; the watcher reads the table at 1 Hz either way.* |
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable` · `RecordingOff` (2026-09-23: the entry's recording switch is off, FR-1.6 — FrameLedger does not start what it will not record). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). **Since D33 (2026-09-26):** for a blocked game whose user-mode exception is in force for the executable on disk (the option on, a grant made on these bytes, the block naming that family) the pre-scan NAMES the family, and a pass under it is stamped as ever and answered `prescan: "exception"`; a finding about the game under it also ends the exception. |
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — ~~the successful Tier-1 sessions (`Refused { reason: "TooFewSessions", signal: <count> }` under two)~~ *(D38, 2026-10-03: no session is needed)*; a game an exception of which ended during its trial is refused before anything is scanned (`Refused { reason: "TrialFailed", family, signal: <unix ms> }`); a tolerant pre-scan of the executable on disk naming the block's family (`Refused { reason, family, signal }` unless the guard let exactly that family through) — and the store writes the grant only over facts that make the game eligible, and never over a failed trial → `AntiCheatExceptionAck { granted, outcome, family }`. **A grant turns nothing on**: hooking is FR-2.1's `SetHookEnabled`, afterwards. Not answered (`UnknownType`) by an Agent composed without the exception. |
| `PauseCapture` / `ResumeCapture` | UI→A | global → `PauseAck { paused }`; `StatusAck.paused` reports it. *(Built 2026-09-13, PR-1b: one in-memory flag, `CapturePause`, read by every session loop at its tick and told to the ring once per transition; supervision — the guard scan, the kill switch, the safety stop — never pauses. Not persisted: an Agent that restarts resumes.)* |
| `StopSession` | UI→A | `{ sessionGuid }` — graceful ~~unhook~~ stop + finalize → `StopAck { sessionGuid, accepted, reason? }`. *(Built 2026-09-13, PR-1b: the orchestrator names every session it starts and cancels THAT session's stop token; the loop reads it at its next tick, drains once more, and ends as `SessionEndReason.StoppedByUser` — `exit_status = normal`, the row stored like any other, the target left running. A guid nobody runs is `accepted: false`. Distinct from the host's cancellation, which leaves a `.partial`.)* |
| `UpdateRules` | UI→A | **no payload** — a trigger, not a source. The Agent re-reads only its own `%LOCALAPPDATA%\FrameLedger\rules\` copy → `UpdateRulesAck { outcome }`. *(Built 2026-09-13, PR-1b: the seeder's `EnsureSeededAsync` outcome; a payload naming a path is ignored, and a test sends one to prove it.)* |
| `Shutdown` | UI→A | graceful stop → `ShutdownAck`, then the host stops (sessions finalize inside its grace window). *(Built 2026-09-13, PR-1b: `IAgentLifetime`, the host's under `--serve`, a logged no-op under `--console`.)* |
| `DeleteSessions` | UI→A | **Added 2026-10-03 (beta.11, D40).** `{ gameId? }` — every session of that game, or of every game when it is null, with their segments, frame and sensor series and annotations (they cascade) → `DeleteSessionsAck { gameId?, games, sessions }`. `Error SessionRunning` and nothing deleted while a session of that game — of any game, for all — is being recorded (`CaptureOrchestrator.IsRecording` / `IsRecordingAny`). The client names no rows beyond the game: they are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the App says as "restart the agent". Carries no safety fact. |
| `SweepRetention` | UI→A | **no payload** — a trigger, like `UpdateRules`: the Agent applies `06_DATA_MODEL` §Retention to every game with the `retention.raw_sessions_per_game` it reads itself → `SweepRetentionAck { keep, games, sessions }` (`keep` 0 = unlimited, and then nothing was swept). *(Built 2026-09-15, P4 PR-7, for Tools ▸ Database maintenance: `Application.Recording.RetentionSweep` over `ISessionRepository.SweepRetentionAllAsync`, composed into `AgentCommandHandler` under `--serve`. The client names no number because the rows are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the dialog reads as "restart the Agent". Carries no safety fact.)* |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt, hold? }` — **published once per session**: at the attach (tier 1, `startedAt` the attach), or — **since 2026-09-23** — at the first tick of a session held unhooked (tier 2, `startedAt` the session's start, `pid` 0 when the loop never opened the process, as a hooking-off hold never does). ~~a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2)~~ — that was the beta.5 wire, and every hooking-off, refused or unreadable game read "Nothing is being captured." for as long as it ran. **`hold` (optional, tier 2 only)** is why nothing is measured: `{ reason, guardReason?, family?, signal?, hookingTurnedOff }` — the loop's `SessionEndReason` and, when the guard said anything but allow, its reason, family and signal: the same words the row's `capture_notes` will carry, so the live card and the summary read one sentence (`Formats.Tier2HoldReason` / `Tier2Reason`). The refusal's own event (`CaptureRefused` and the rest, below) goes out with this start rather than when the game exits, and is not repeated at the end |
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct?, gameVramDedicatedMb?, gameRamPrivateMb? }` — how long it has run and the machine's sensors (and since beta.12 the game process's own memory, read from outside it — optional, an older client ignores them). **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus?, gameVramDedicatedMb?, gameRamPrivateMb? }` (the last two added 2026-10-03, beta.12, optional: the game process's dedicated GPU memory and private working set, MiB, from the newest telemetry tick; `vramProcMb` stays reserved for the in-process figure and has no producer) — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch`, `PreScanCouldNotVerify` and, since 2026-09-21 (beta.4), `TargetUnreadable` — a protected process the Agent could not open (added 2026-10-04) — `PreScanCouldNotVerify` with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff }` — anti-cheat appeared mid-session; prominent UI notice; `hookingTurnedOff` as on `CaptureRefused`. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
| `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
@@ -328,10 +451,38 @@ 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.
- 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
+639 -9
View File
@@ -24,10 +24,88 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
**Menu bar**
- **File:** Add game… · Import library (Steam / GOG / Epic / itch.io) · Export ▸ (Session CSV / Session JSON / Chart PNG) · Exit
- **Tools:** Agent status… · Update detection rules · Vulkan layer registration… · Open data folder · Database maintenance…
- **Help:** Check for updates · Report a bug… · Documentation · About FrameLedger (App / Developer / Third-party licenses tabs)
- **Help:** User guide (beta.12) · Check for updates · Report a bug… · ~~Documentation~~ Online documentation · Limitations · About FrameLedger (~~App / Developer / Third-party licenses tabs~~ — built beta.12 as *This app* / *Third-party licences* / *Legal documents*, below)
> **Help ▸ Limitations, beta.10 (D36):** `LIMITATIONS.md` as the build embeds it (`Services.LimitationsDocument`), in a
> ~~read-only, scrolling WPF UI `MessageBox` with *Open on GitHub*~~ window of its own since beta.12 (`Windows/DocumentWindow`,
> rendered — below; corrected 2026-10-04). It is information, not one of FR-11's documents:
> nothing is accepted or recorded, and the Disclaimer points at it.
>
> **Help ▸ User guide, beta.12 (D44).** `guide/` — eight short English pages for players (install, record a game, read
> your results, anti-cheat and safety, your data, questions and answers, the terms in plain words) — embedded in the
> App (`Services.EmbeddedDocuments.Guide`, titles from each page's first heading) and shown in a `Windows/DocumentWindow`
> with a page list, Limitations last; a link between guide pages opens the page in the window. Help ▸ Documentation is
> *Online documentation*: the README at this build's source. `GuideDocumentsTests` holds every page listed and titled and
> every link leading somewhere.
>
> **Documents are rendered, beta.12 (owner request 4, D45).** Every Markdown document the App shows — the Legal Gate's
> three texts, Help ▸ Limitations, the update notes, About's documents — is drawn by `Markdown/MarkdownRenderer`
> (Markdig 1.4.0, BSD-2-Clause) into a WPF `FlowDocument` inside `Controls/MarkdownView` (a read-only
> `FlowDocumentScrollViewer`: selectable, Ctrl+C, Ctrl+wheel zoom): headings, emphasis and strikethrough, inline and
> fenced code in monospace, quotes, nested and numbered lists, pipe tables with a header row, rules, links. **HTML is
> off** — a tag is shown as the text it is; **no image is fetched** — its description stands in; a node the renderer
> does not know is shown as its own source text, and `MarkdownRendererTests` proves for every embedded document that
> no word of its plain text is lost and no table is left as `|---|` source. The GPL's `LICENSE` is not Markdown: it is
> shown as written, monospace. Colours and the font are theme resources (`16_WPFUI_SYNTAX` §FlowDocument). Links
> follow `Markdown/MarkdownLinks`: http, https and mailto through `IUrlOpener`; `#section` scrolls to the heading
> (GitHub's anchors); a relative path resolves against the document's place in the repository and opens in the App
> when the window holds that page, on GitHub otherwise — **at this build's own source** (`Services/RepositoryLinks`:
> the release's tag, stamped by `release.yml`; `main` for a local build — every link said `blob/main` before); any
> other scheme (`file:`, `javascript:`, a drive or UNC path) is not followed, its address shown beside its text.
> **Help ▸ Limitations** is a window of its own (`Windows/DocumentWindow`, one page, *Open on GitHub*); **Help ▸ About**
> is `Windows/AboutWindow`, three tabs: *This app* — the version, and the program's Appropriate Legal Notices (GPLv3
> §0, §5(d)): the copyright line, no warranty, the licence with the NOTICE terms, this version's source, *View the
> licence* / *View NOTICE* / *Open the source code*; *Third-party licences* — `legal/THIRD_PARTY_NOTICES.md` and the
> package index, rendered, and *Open the licences folder* (the published `licenses\`; a development build says it has
> none); *Legal documents* — EULA, GPL, Disclaimer, Privacy Policy, NOTICE, Trademarks. Asking again brings the open
> window forward (`Services/DocumentWindows`). Tests: `MarkdownRendererTests`, `MarkdownLinksTests`,
> `DocumentWindowsTests`.
The Menu sits in its own row **below** the TitleBar (never inside the drag region — 16 §Gotchas).
> **Menu bar as of 2026-09-14 (P4 PR-3).** File ▸ Export is the submenu this section specifies — Session CSV /
> Session JSON write the session last selected on a Sessions tab or opened in a summary window
> (`Services/SessionSelection`, `SessionExportService` over the summary window's own writers; no selection says
> so in the strip), Chart PNG opens that session's summary window, where the plot is. Help ▸ Documentation opens
> the README (`IssueLink.Documentation`; `docs/` is developer-facing). Help ▸ Report a bug… runs
> `BugReportFlow` (`10_LOGGING` §Bug report flow steps 2–4). Tools ▸ Update detection rules is PR-1's. **File ▸
> Import library… is PR-4's** (`ImportLibraryFlow` → the review checklist `ImportReviewPrompt` / `Dialogs/ImportReviewContent`,
> a `DataGrid` with a tick column like Compare's picker — store, game, the executable to add, a note for
> "already in the library" / "no executable found" / "guessed — check it"; Add selected lands every row hooking
> off and shows the Games page; `05_DETECTION` §Platform signatures built note). **Help ▸ Check for updates is PR-5's** (`Update/UpdateService.CheckInteractivelyAsync`, the
> dialogs of `11_UPDATER` §Flow; a downloaded update is the shell's persistent InfoBar with the one button,
> disabled while a session runs — FR-12 — and "update available" is a tray balloon only while the window is off
> screen). ~~Still "later build": Tools ▸ Database maintenance.~~ **Tools ▸ Database maintenance… is PR-7's (2026-09-15)**:
> a `ContentDialog` (`Dialogs/DatabaseMaintenanceContent`, `ViewModels/DatabaseMaintenanceViewModel`) with four cards —
> Check integrity, Back up…, Sweep raw data…, Compact — and one status line; the sweep confirms in a `MessageBox` with a
> Danger button (§UX rules) and is sent to the Agent, compaction is refused while a session runs, and a backup is never
> written onto the ledger itself (`06_DATA_MODEL` §Retention built note). No menu item says "not built yet" any more:
> `NotYetCommand` and its two strings are gone.
>
> **Built 2026-09-13 (P3 PR-2): the shell, and only the shell.** `FluentWindow`, the TitleBar with the
> Agent pill as trailing content, the Menu row (every item that a later slice builds says so in a 4 s
> snackbar rather than doing nothing), the NavigationView with the four items and Settings in the footer,
> the offline `InfoBar` with Retry, `SnackbarPresenter` and `ContentDialogHost`. The Dashboard shows the
> Agent status card (`HelloAck`/`StatusAck`, every value `N/A` until answered); Games, Compare and Logs
> are empty states; Settings has Appearance (theme + language, both persisted in `settings` — D16's
> `ui.theme`/`ui.language`). The App starts `FrameLedger.Agent.exe --serve` beside itself when the pipe
> is absent (`07_IPC` §Client behavior, 8 × 250 ms) and shows **Missing** when there is no Agent to start.
> *(Since 2026-09-17: and only when no Agent already holds the data folder — `07_IPC` §Client behavior.)*
> Measured on the dev box: first window at 1.3 s from process start (NFR-4's 2 s). ~~The tray is PR-8's.~~
> **Tray built 2026-09-14 (P3 PR-8b).** `Services/TrayHost` over `TrayViewModel` (no WPF in the view model,
> `TrayViewModelTests`): the four icons are drawn at start (`TrayIcons`, a PNG inside an in-memory `.ico`,
> because H.NotifyIcon 2.4.1 converts only file-backed image sources) and follow the pipe's session events —
> ● when any running session is Tier 1, ◐ when sessions run and none is measured, ⏸ when the Agent reports
> paused, the ring otherwise; the tooltip names the game. Menu: Open, Pause/Resume capture (one
> `PauseCapture`/`ResumeCapture` request; the state shown is the `PauseAck`'s, never assumed), Agent status (the
> Dashboard), Exit (a real exit through `ShellHost.Quit`, whatever minimize-to-tray says); a left click opens the
> window. **Minimize to tray on close** hides the live window when `ui.minimize_to_tray` is on and a tray icon
> exists (`WindowClosePolicy`); a language rebuild's old window is unaffected. **FR-3.8's balloon** — "Session
> saved — <game> — click to view" — is raised only while the window is off screen; on screen, the Dashboard's
> snackbar carries the same event (one event, exactly one channel), and its click opens the summary window.
> A safety event is never a balloon (`TrayViewModelTests` asserts it). Tools ▸ Agent status… and Tools ▸ Vulkan
> layer registration… now navigate (Dashboard, Settings) instead of saying "not yet".
**Tray (H.NotifyIcon):** icon states idle / ● capturing (T1 hooked) / ◐ recording only (T2 — nothing measured) / ⏸ paused; menu: Open, Pause/Resume capture, Agent status, Exit. Closing the window minimizes to tray when enabled.
## Notifications policy
@@ -41,6 +119,41 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
~~The "capture without injection instead" action is **Tier 2, which needs an elevated Agent**~~ — **rewritten 2026-08-28, and the button's whole meaning changed.** There is no no-injection measurement, so this action cannot be offered as an alternative way to measure. What it may offer is **recording the session anyway**: duration, hardware telemetry and the reason nothing was measured. It needs no elevation. **Label it for what it does** — "record this session without measuring it" — because a button that says "capture without injection" beside a refusal reads as a second measurement path, and the previous wording was corrected once already for exactly that.
> **Built 2026-09-14 (P3 PR-8a).** `Services/SafetyNotices` subscribes to the pipe's events and turns
> `CaptureRefused`, `SafetyUnhook` and `CaptureDegraded` into `SafetyNotice`s the shell renders as an
> `ItemsControl` of `ui:InfoBar`s in `MainWindow` row 2, under the Agent banner and above every page — Error for
> a refusal and an unhook, Warning for a degrade, `IsClosable="False"`, no timeout. The text is the `Safety_*`
> family (`Safety_Refused_Named_Format` with the family and the signal, `_Unnamed`, `_CouldNotVerify`,
> `Safety_Unhooked_Format`) followed on a refusal by `Notice_Refused_Recording` ("the session is still recorded —
> duration and hardware telemetry — with every frame-derived value at N/A"). The one button is
> `Safety_RecordWithoutMeasuring` on a refusal and Dismiss otherwise; it removes the notice and does nothing
> else, because the Agent already records Tier 2 on a refusal (owner decision 2026-08-28) — the button is the
> user's acknowledgement, not a second request. *(That sentence became true on 2026-09-22: until then every
> refused session was discarded under the minimum length, and for one day `TargetUnreadable` omitted the
> "still recorded" sentence for that reason. `04_CAPTURE` §Tier selection.)* The session summary of a Tier-2 row
> says WHY under its Tier-2 sentence (`Formats.Tier2Reason` over `capture_notes`: hooking off, the block on the
> row, the guard's family and signal, a process that could not be opened, or the end reason by name —
> `Summary_Tier2_Why_*`). `CaptureError` (non-fatal) goes to the 4 s strip. The safety
> documentation link lives on the Settings page's Capture section rather than in every notice. Tests:
> `SafetyNoticesTests` (the three kinds, the sentence per refusal reason, the strip for errors, nothing for a
> session event, dismiss only by the user).
>
> **Corrected 2026-09-14, after the owner saw a red bar with no way out.** WPF UI 4.3.0's `InfoBar` template has
> **no `ContentPresenter`**, so the action button above — placed as the InfoBar's Content, the only dismissal once
> `IsClosable="False"` removed the X — was never rendered. The view model was right and the screen was wrong.
> `Styles/FrameLedger.xaml` now carries the upstream template verbatim plus the presenter (`16_WPFUI_SYNTAX`
> §Gotchas), the same fix reaching the Agent-offline banner's Retry and the game page's Re-enable. Guarded by
> `PagesLoadTests.TheInfoBarTemplateRendersItsContent`, which renders both templates and fails when upstream
> gains a presenter — the signal to delete the copy.
> **The pre-scan's notice (2026-09-25, beta.8).** The Agent's pre-scan of the library (`19_SAFETY` §What a finding
> does to the game) sends `HookingTurnedOff` when it turned off hooking the user had turned on; `SafetyNotices` makes
> it a `SafetyNotice` of kind `HookingOff` — Error, persistent like the others, titled *"{game}: hooking turned off"*
> (`Notice_HookingOff_Title_Format`), the refusal sentence naming the family and the signal followed by
> `Safety_HookingTurnedOff`. It has **no** `Notice_Refused_Recording` and its button is Dismiss, not
> `Safety_RecordWithoutMeasuring`: no session is running, so there is nothing to record without measuring. A finding
> on a game whose hooking was already off raises no notice; its card and its page say it (§Games).
## FPS display rule (global, FR-4.2 / CLAUDE.md rule 6)
Reusable control `FpsReadout` (custom control styled with WPF UI theme brushes):
@@ -49,12 +162,14 @@ Reusable control `FpsReadout` (custom control styled with WPF UI theme brushes):
- FG **measured `none`** (a hook ran and saw no frame generation — no producer exists yet) → `144 FPS`, nothing else.
- FG **not measured** (`fg_mode = N/A`, every title today) → `144 FPS` as **Presented FPS**, with a mandatory qualifier chip from the runtime census: muted **"FG not observed"** when no frame-generation runtime was loaded in the process (tooltip: *"no frame-generation runtime was loaded; this number cannot include in-process generated frames — statically linked FSR3-FG and driver-level AFMF excepted"*), or a **⚠ warning chip "FG runtime loaded — may include generated frames"** naming the module when one was. Never the word "Native", never a factor, never `—`.
- FG detected → **`62 → 118 FPS (×1.9 FG)`** — Native first and visually primary (`FontTypography="Subtitle"`), Displayed second, factor as a small accent chip. Tooltip: "Native: frames rendered by the game · Displayed: frames shown on screen incl. generated frames".
- **A steady-state factor carries its share (2026-09-17).** When `fg_factor_scope = steady` the readout is the generated shape — `58 → 116 FPS` with the chip **`×2.0 FG · 75%`** — and the share is never omitted: the number describes the state the session spent most of its generating time in, not the session. Tooltip: why there is no session-wide factor (menus, loading, a settings change), what the number covers, and the refusal's own numbers. The "factor not counted" chip below remains for a session with no state long enough (`03_METRICS` §The steady state).
- **FG identified, count refused (2026-09-14 — a fourth shape, `FpsReadoutKind.IdentifiedUncounted`).** `fg_mode` names a technology and `fg_factor` is NULL: the owner's Black Myth: Wukong and Onimusha rows, where the tags named DLSS-G and the token count did not resolve. Until this date the readout fell into the "detected" shape and printed **`N/A → N/A FPS (×0.0 FG)`** — a factor nobody counted — while the game page said `DLSS-G ` and the grid said N/A. Now: **`304 FPS`** as Presented FPS with a **⚠ warning chip "DLSS-G active — factor not counted"**, tooltip = the row's `fg_refusal` in plain words ("no application-frame token was counted", "the frame-generation state changed mid-session", …) plus "read it as Displayed, not Native" — **and since 2026-09-16 the refusal's numbers from `fg_refusal_detail`** ("Bucket 3 of 8 measured 2.25 against 3.65 for the whole session, over 53 samples.", "2 swapchains presented during the session."), because the owner's four DLSS-G rows all read the same sentence and the sentence could not say why; the game page's measured row reads **`DLSS-G · factor not counted`**; Displayed and FG× say `N/A` (no factor exists, and it is not a measured none). Never the word "Native", never a factor. The `fg_runtime_loaded` chip also **names the module** now (`FG runtime loaded (sl.dlss_g.dll) — may include generated frames`) from `fg_runtime_census`, as this rule always asked. `FpsPresentation.FrameGenerationLabel` is the one place the page and the live card build the label.
- Tables get three columns (Native / Displayed / FG×); Displayed and FG× render `—` when `fg_mode = none` and **`N/A` when it is not measured** — the two are different negatives and the table must not collapse them. The Native column carries the Presented figure with its qualifier when FG is not measured.
- Charts: Native series default; "Displayed" toggle appears only when displayed data exists (FR-5.4).
## Tri-state feature chips (RT / PT / RR)
`TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header.
`TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. ~~Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override~~ *(corrected 2026-10-04: the source is the chip's tooltip, and a click opens FR-8.3's dialog, `TriStateOverridePrompt` — no flyout exists)* (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header.
## Screens
@@ -62,53 +177,568 @@ All screens are `Page`s registered with the navigation page provider and navigat
### Dashboard
- Agent status `ui:CardControl` (state, capability badges as `InfoBadge`: telemetry source, Vulkan layer, ~~ETW fallback~~, PawnIO/CPU-temp, elevation — Repair button on error).
- **Live capture card** (visible during capture): game name, **tier badge**, elapsed, live `FpsReadout` (5 s rolling), **measured** `renderW×H → outputW×H` with upscaler + quality, RT-active dot, CPU/GPU temp, per-process VRAM, sparkline (last 120 s) fed by `SessionProgress`. Tier 1 shows measured settings — this is the payoff of hooking and should read as facts, not guesses.
- **Live capture card** (visible during capture): game name, **tier badge**, elapsed, live `FpsReadout` (5 s rolling), **measured** `renderW×H → outputW×H` with upscaler + quality, RT-active dot, CPU/GPU temp, ~~per-process VRAM~~ the game's own VRAM and RAM (beta.12: read from outside the game, so a held session has them too), sparkline (last 120 s) fed by `SessionProgress`. Tier 1 shows measured settings — this is the payoff of hooking and should read as facts, not guesses.
- Recent sessions list (last 10 across games) → click opens session summary.
- Totals strip: games tracked, total playtime, sessions this week (`ui:Card` row).
> **Built 2026-09-14 (P3 PR-5): the Agent card, the live card, the recent list, the totals.** The live card
> is `LiveCaptureViewModel` over the pipe's `SessionStarted` / `SessionProgress` / `SessionCompleted`
> (marshalled through the captured `SynchronizationContext`): game, tier badge, elapsed, the `FpsReadout` at
> 1 Hz under the display rule (Presented FPS with its census chip until frame generation is measured), the
> measured `renderW×H → outputW×H` with upscaler + quality, the RT chip, GPU/CPU temperature, ~~per-process VRAM~~
> (corrected 2026-10-03: that line read the Overlay's per-present VRAM, which nothing produced, so it was always empty;
> since beta.12 it is "This game: VRAM … · RAM …" from the newest telemetry tick, `GameMemoryText.Live`).
> ~~The sparkline is PR-6's.~~ Recent = `ISessionRepository.ListRecentAsync(10)` with game names; a completed
> session reloads the lists (the row is in SQLite, `07_IPC` §Client behavior). Totals = the library's games,
> `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. ~~Capability badges and the Repair button are
> PR-8's with the Agent section.~~ *(Corrected 2026-10-04: PR-6 and PR-8 shipped without them. No sparkline exists,
> here or on the Games cards; the Agent card shows its facts as text, and the Vulkan layer state and the logon
> task's Repair are on Settings.)*
>
> **Amended 2026-09-23: the card shows every running session, measured or not.** A session held unhooked
> (Tier 2 — hooking off, refused, unreadable) shows its name, the T2 badge, the elapsed time and the
> machine's temperatures from `SessionHeld`, the line "Recording duration and sensors only — nothing is
> measured." and **why**, in the sentence its summary will carry (`Formats.Tier2HoldReason` over the start's
> `hold`, the same words `Tier2Reason` reads from `capture_notes`) — and no `FpsReadout` at all. A session the
> status lists at tier 2 with no `hold` has not attached yet: its name and badge until the attach's start arrives,
> never the held line and never the "Attached — waiting" one. A hooked session takes the card from a held one,
> never the reverse. The card is seeded from the
> App-lifetime `LiveSessions` when the Dashboard is built, so a session that started while another page was
> open is on it at once; the completion notice names the session that completed (`SessionCompleted.gameName`)
> and a `faulted` completion is no notice (the strip's `CaptureError` already said it). Until this date the
> Agent announced only hooked sessions: every other game read "Nothing is being captured." while it ran.
### Games (grid → detail)
- `GridView`-style panel of cover cards (`ui:CardAction`): name, platform badge, engine badge, total playtime, last played, mini trend sparkline (avg Native FPS last 10 sessions). Sort/filter/`ui:AutoSuggestBox` search.
> **The library, beta.11 (owner requests 2026-10-03).** *The empty band on the right:* the cards were 300 px in a plain
> `WrapPanel`, so at ~1350 px three fitted and a card's width was left unused; the grid is now
> `Controls.UniformWrapPanel` — as many columns as fit at 300 px or wider, every card an equal share of the width, each row
> as tall as its tallest card — and the pill row wraps instead of cutting its last pill. **Grid or list** (owner's choice:
> switch between the two): the button beside the sort shows the other view; the list is one row per game (name, store,
> engine, status, sessions, played, last played; double-click or Enter opens it), and the choice is `ui.library_view`.
> **The count** is in the title (*Games · 42*). **Refresh** reads the library again, then asks the stores for games installed
> since (`ImportLibraryFlow.RunAsync(onlyNew: true)`: *No new games* and no checklist when there are none), and every entry
> whose executable is not on disk carries a **Not installed** pill — its tooltip is the game page's own sentence for it,
> the drive that is not connected or the path the file is gone from (`GameLibrary.ExecutableExists` and
> `Formats.ExecutableMissingText`, asked off the UI thread on every listing, never stored; nothing is removed for it). **The page reloads by itself** while it is on screen when a session ends (`SessionCompleted`) or an
> import adds games (`LibraryChanges` — navigating to the page already on screen does nothing in WPF UI 4.3.0, so an
> import from the menu never showed until the page was left). **Import** (FR-1.2): the games already in the library — at
> this path or under another drive letter — are hidden by default (*Show the N games already in the library* brings them
> back, dimmed), and a row that cannot be imported has its box disabled; the XAML comment said "cannot be ticked" while a
> tick was taken and ignored. Tests: `GamesViewModelTests`, `ImportLibraryFlowTests.RefreshOffersOnlyNewGamesAndSaysWhenThereAreNone`,
> `…GamesAlreadyInTheLibraryAreHiddenUntilAskedFor`, `PagesLoadTests.TheLibraryGridFillsItsWidthAndTheListViewReplacesIt`,
> `…TheImportChecklistRendersWithTheExistingRowsShown`.
>
- **Game detail:**
- Header: cover, name, publisher, version, platform, engine+version, API + Present Mode of last session, `FpsReadout` (lifetime avg), TriState chips, Edit button.
- **Two clearly separated rows** (`05_DETECTION` §Capability hints — conflating these was the old design's core mistake):
- **Supports** — greyed capability chips from files on disk ("Supports DLSS-G", "Supports XeSS"). Static inference.
- **Last session measured** — accent chips with real values ("DLSS Quality · 1440p → 2160p", "Frame Generation DLSS-G ×1.9", "Ray Tracing: Yes"). Measured.
- **Hooking control** (`ui:CardControl` with `ToggleSwitch`): off by default. Turning it on opens the consent dialog (FR-2.1). When the static anti-cheat pre-scan blocked it, the switch is **disabled** with the reason shown inline and no way to force it. When auto-disabled after crashes, an `InfoBar` explains and offers manual re-enable.
> **Built 2026-09-14 (P3 PR-5): the grid, the detail page's header, the two rows, the hooking control and
> the Sessions tab.** Grid: `ui:CardAction` cards with platform / engine / hooking badges, sessions, playtime,
> last played (~~the sparkline is PR-6's~~ no sparkline was built — corrected 2026-10-04); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's
> button, or an `.exe` dropped on the page (a `.lnk` needs the shell-link reader, later); FR-1.4 through
> `Wpf.Ui.Controls.MessageBox` with **Keep sessions / Delete sessions too**, revoking consent over the pipe
> FIRST when it was on. Detail: header (name, publisher · version · store · engine, last session's date and
> API, the last hooked session's `FpsReadout`, the three chips resolved with the annotation and the game
> default — `Application.TriState.TriStateResolution`), Edit… (FR-1.3, a `ContentDialog` badging detected
> fields), **the row's executable path under the subtitle and Change executable… since 2026-09-21** (a store import
> guesses the executable and everything downstream is keyed on it; the pick re-points the row, which comes back
> hooking-off and unconsented like a new game, consent revoked over the pipe first, a block never cleared —
> `05_DETECTION` §Library import), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), ~~**the guard-bypass switch since 2026-09-21**~~ **withdrawn 2026-09-22** (the card, its dialog, the session mark and the export line are gone; a blocked row's toggle is disabled and `Safety_Blocked_Toggle_Format` is the whole story; a refusal or unhook notice that turned hooking off ends with `Safety_HookingTurnedOff` — `19_SAFETY` §What a finding does to the game), **Supports** (from `capability_flags`; ~~empty until P4's scan writes it, and the card says so~~ **written by the Agent's detection sweep since P4 PR-1, 2026-09-14** — the rule ids as product names via `CapabilityNames`, "not scanned yet" only until the Agent's next tick) beside
> **Last session measured** (upscaler · resolution, frame generation, the non-N/A chips — accent pills, from the
> hooks). Hooking: the toggle is `OneWay` from the row and its command runs `HookingConsent`; a refusal, a
> mismatch or a failure is a persistent `InfoBar` on the page (never a toast); a blocked row disables the
> switch with `Safety_Blocked_Toggle_Format` inline; an unverified pre-scan leaves it enabled and says so;
> auto-disabled shows `Safety_AutoDisabled_Format` with the re-enable button. Sessions tab: the `DataGrid` of
> FR-6.1 — every Tier-2 cell that is Tier-1-only reads `N/A`, a measured-none Displayed / FG× reads `—`, both
> with tooltips. Frametime / Distribution / Trend / Sensors / Latency say which build brings them (PR-6, PR-7).
> `PagesLoadTests` loads every page and both control templates under the real theme dictionaries on an STA
> thread, so a binding typo is red in CI rather than a `XamlParseException` at first navigation.
>
> **The recording switch (2026-09-23, FR-1.6).** A `ui:CardControl` **Recording** above the hooking control, its
> `ToggleSwitch` `OneWay` from `games.record_sessions` and its command writing the row through
> `GameLibrary.SetRecordingAsync` — no dialog (it deletes nothing; sessions already recorded stay) and nothing over
> the pipe (the Agent reads the table each tick). Status line *Recorded when it runs* / *Ignored — nothing is
> recorded*; the body says what off means (the program is not watched; a running session stops) and when to use it
> (a utility that starts with Windows). The library card shows **Not recorded** in place of the hooking badge, since an
> ignored program is never hooked whatever its hooking switch says. The hooking control stays independent: a user can
> keep a consent on an entry they stopped recording for a while.
>
> **Anti-cheat games (2026-09-25, beta.8, owner decision).** The Agent pre-scans every library entry now, so the App
> knows which games ship anti-cheat before anyone asks to hook them (`19_SAFETY` §What a finding does to the game).
> The library card says **Anti-cheat** in place of *Hooking off* — the caution fill with primary text, the warning
> qualifier's pair that `ContrastTests` measures in both themes — for an entry that is recorded (*Not recorded* still
> comes first). On the game's page the Hooking card is a switch that could only be refused, so while
> `ui.hide_anticheat_hooking` is on — its default, Settings ▸ Capture *Hide hooking on anti-cheat games* — the card
> and its lines give way to one **Anti-cheat** card: *"Found: {what}. Hooking is off for this game and cannot be
> turned on; its sessions record play time and sensors only."* Off, the card is back with the switch disabled and
> `Safety_Blocked_Toggle_Format` under it. `{what}` is `Services.BlockedReasonText` over the stored
> `Reason|Family|Signal` — *"BattlEye — its module BEClient_x64.dll was loaded in the game"*, *"Easy Anti-Cheat —
> its folder EasyAntiCheat ships with the game"*, *"… is a listed title"*, *"the game's store id … is listed"* —
> and a row stored before that form is shown as it was. The crash auto-disable's re-enable bar is not offered on a
> blocked row: its one action could only be refused. Tests: `GameDetailViewModelTests` (hidden, shown, the card
> pill), `BlockedReasonTextTests`, `PagesLoadTests.AnAntiCheatGamesPageRendersTheFindingInPlaceOfTheHookingCard`.
>
> **D38 (2026-10-03, beta.11): the trial.** *Not eligible: N successful hooked session(s), two are needed* is gone — a
> grant needs no session. The card reads *Exception in force since … — trial: N of 2 good sessions so far* until the
> trial is over, *Not eligible: an exception of this game ended during its trial on …, so none can be made again* after
> a failed one, and *Not eligible now: {family} was not found in the game's folder when it was checked* where the
> tolerant scan found nothing of the family (it used to say the check "could not finish"). The **Anti-cheat** card of an
> eligible game says hooking is off *unless you make a user-mode exception for it (below)* — "cannot be turned on" beside
> a usable *Make exception…* contradicted itself. The disclosure (`ac-exception-dialog/2`) names no session count and
> has a **Trial** paragraph. Tests: `GameDetailViewModelTests.WhyAGameIsNotEligibleIsSaidOnItsPage`,
> `SettingsViewModelTests.TheExceptionOptionIsOffByDefaultAndItsListFollowsTheAgentsColumns`, `AntiCheatExceptionsTests`.
>
> **The user-mode exception (2026-09-26, beta.9, owner decision D33).** While Settings' option is on, a blocked
> game's page shows a **User-mode exception** card with the Agent's answer about it (`Services.ExceptionView` over
> `GameRow.AcException` — the App reads those columns and writes none): *Eligible — no exception made* with **Make
> exception…**; *Checking…* until the Agent has looked at this block; *Not eligible: N successful hooked session(s), two
> are needed*; *Not eligible: the guard also found {family} ({signal})* — Aniimo's *Kernel driver in the game folder
> (NEPKernel.sys)*; *Not eligible: {family} is not user-mode throughout*; and how the last exception ended. **Make
> exception…** opens the exception's disclosure (`AntiCheatExceptionPrompt`, text `Safety_Exception_*` versioned by
> `AntiCheatExceptionDisclosure.Version`, the primary button bound to the ticked *I accept the risk of a ban for this
> game*, Enter = *Keep it blocked*) and then `SetAntiCheatException`; the Agent gathers the facts and grants or
> refuses, and the page says which. An exception in force brings the Hooking card back — even while anti-cheat cards
> are hidden — with its switch usable through FR-2.1's dialog as ever, the finding still under it; **Withdraw
> exception** ends it and turns hooking off. With the option off a kept exception is shown *suspended* and the switch
> is disabled again. The library card says **Exception** for a game carrying one; a hooked session under it is
> *Hooked · exception* in the Sessions tab (the tooltip names the family) and its summary has one line saying so.
> Tests: `GameDetailViewModelTests.AnEligibleGameOffersTheExceptionAndOneInForceMakesTheSwitchUsable`,
> `…WhyAGameIsNotEligibleIsSaidOnItsPage`, `AntiCheatExceptionsTests`.
>
> **Details (2026-09-25, beta.8, schema 0011).** A `ui:CardExpander` **Details** under the two rows, expanded, says
> what the game's files and its store say (`05_DETECTION` §What the files say about themselves): *Runs as* (64-bit
> (x64) · 32-bit (x86) · ARM64 · .NET, any CPU (runs as 64-bit) · …), *File version* and *Product version* (the
> executable's PE resource — for an Unreal title often the engine's), *Store* ("Steam build 20374416", "GOG version
> 1.2.3" — or *Version* when the user typed it), *Engine*, and *Ships with*, one line per capability file: "DLSS:
> nvngx_dlss.dll 3.7.10.0", "XeSS: libxess.dll (no version)". A row the Agent has not read yet says so. The subtitle
> labels the store's version the same way and then drops the bare store name it would repeat. **An executable that
> cannot run as x64** (x86, 32-bit-preferring .NET, ARM) disables the hooking switch with `Hooking_NotX64_Format` under
> it and no re-enable bar — turning it on could only be refused (the Agent refuses `ExecutableNotX64` anyway); a switch
> already on can still be turned off. Tests: `GameDetailViewModelTests.TheDetailsCardSaysWhatTheFilesSayAndAnX86SwitchCannotBeTurnedOn`,
> `FormatsTests`, and the page renders in `PagesLoadTests`. **The Details card's *NVIDIA App override* row** (same day)
> is the newest session that read a driver profile, in the same words; no row where none did. Tests:
> `NvidiaOverridesTests`, `GameDetailViewModelTests.TheDetailsCardNamesTheNvidiaAppsOverridesFromTheNewestSessionThatReadThem`.
- Tabs (WPF `TabControl`, Fluent-styled):
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. Multi-select → "Compare". Tier-2 rows render `—` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why.
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. ~~Multi-select → "Compare".~~ (not built; Compare's own picker chooses) Tier-2 rows render ~~`—`~~ `N/A` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why *(corrected 2026-10-04: as built — `—` means a measured none, §FPS display rule)*.
2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
3. **Distribution** — FPS histogram + percentile curve of selected session(s).
4. **Trend** — metric-over-date line (selector: Native avg / Displayed avg / 1% Low / 0.1% Low / max GPU temp), vertical **hardware-change markers** with tooltip "GPU driver 572.16 → 576.02" (FR-6.3).
5. **Sensors** — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series.
> **Across sessions, beta.11 (owner decision D39, FR-6.6).** The **Sessions** tab opens with *Sessions at a glance*: a
> `TrendChart` of every hooked session's Presented FPS (sessions that counted no generated frame), Native and Displayed
> (sessions where frame generation was measured — rule 6, never one inflated line) and 1% / 0.1% lows, oldest first,
> partial sessions hollow (`TrendSeriesBuilder.Overview`); a click near a session's points selects it in the grid and
> scrolls to it (`TrendChart.SessionClicked`). Under it, **Delete all sessions…** (FR-1.7) for this game. The **Trend**
> keeps its selector and adds *Also draw*: any other metric ticked is drawn on the same chart, its unit
> (`TrendSeriesBuilder.UnitOf`: FPS, °C, %, W, MB, ×) on the left axis when it is the selected metric's and on the right
> when it is a second one (marked ▸ in the legend); a metric in a third unit cannot be ticked, and when the selected
> metric changes to a third unit only the first ticked unit in the list stays ticked, so every ticked box has its line;
> the selected metric is not offered beside itself. One line alone keeps its name on the axis, as before. After any delete — here or in
> Settings — a summary window still open on a deleted session closes, and File ▸ Export lets go of it (`SessionDeletion`;
> ids are reused once the newest is gone). Tests: `SessionDeletionAndOverviewTests`.
>
> **The display mode, beta.10 (FR-7.4, `03_METRICS` §Display mode).** The **Last session measured** row adds how that
> session was shown — the mode that lasted longest with its share and the window's size (`Display: Borderless 92% ·
> 2560×1440`); the **Sessions** tab has a *Display* column for every session, Tier 2 included (the mode shown longest,
> with a tooltip carrying every share, the changes, the window on its monitor, the back buffer and the witness), `N/A`
> for a session recorded before; the **Trend** has three more metrics — *Exclusive fullscreen share %*, *Borderless
> share %*, *Windowed share %* — over every session whatever its tier, never left out as a mid-session change (a mode
> switch resizes the swap chain, and the share is what that switch was), with no exclusive or borderless point for a
> session that had any time nothing could split (`Services.DisplayText`, `Charts.TrendSeriesBuilder.DisplayShare`).
>
> **The game's own memory, beta.12 (owner decision D43, `03_METRICS` §Game process memory).** Read from outside the game
> once a second in either tier, it is shown wherever a session is (`Services.GameMemoryText`, from the stored columns and
> `sensor_stats_json` — never recomputed). The **Sessions** tab has *VRAM (game)* and *RAM (game)*: the median · the
> peak, in Task Manager's units (MB below 1 GB, GB to two decimals, 1 GB = 1024 MB, `Formats.Memory`), the tooltip
> carrying the mean, the shared GPU memory's peak, the working set's and the commit's peaks, and how many processes were
> added together where an unpinned hold summed more than one. Where Windows did not report the private working set, the
> working set is shown and SAYS so ("(working set)") — never passed off as Task Manager's "Memory". The **Trend** replaces
> *Max VRAM (game)* — which read `vram_proc_max_mb`, a column nothing ever wrote, so it never had a point — with *Median /
> Peak VRAM (game)* and *Median / Peak RAM (game)* in GB, machine metrics that count Tier-2 sessions (the RAM lines are the
> private working set only: a working-set-only session has no point there rather than another quantity on the line);
> *Avg RAM in use* is the whole PC's, now in GB too. **Compare** adds the four as rows that rank nothing — a game that uses
> more of a card it has is not worse. The **Sensors** tab and the summary's Sensors section draw two memory plots in GB:
> *Video memory (VRAM)* — this game's dedicated and shared beside the whole graphics card's — and *Memory (RAM)* — this
> game's private working set (or its working set, labelled) beside the whole PC's; this game is one colour on both. The
> **summary** adds two cards, *VRAM (this game)* and *RAM (this game)* — the median, with "median · peak … · shared …" /
> "… · commit …" beneath — and a table, **Statistics per series**: every stored series' mean, median, minimum, peak and
> number of readings, each in its own unit (`Services.SensorStatsTable`); a session recorded before beta.12 shows one
> sentence instead of the table. The **live card** shows "This game: VRAM … · RAM …" from the newest tick, a held session
> included, and the CSV gains the `# game_memory:` header line. Tests: `GameMemoryTextTests`,
> `SessionSummaryViewModelTests.TheGamesMemoryAndTheStoredStatisticsAreShownForASessionThatWasNotHooked`,
> `TrendSeriesBuilderTests`, `CompareViewModelTests`, `ChartMathTests.TheMemoryPlotFallsBackToTheWorkingSetUnderItsOwnName`,
> `LiveCaptureViewModelTests`, `SessionExporterTests`.
5. **Sensors** — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series. Since beta.12 two memory plots in GB: *Video memory (VRAM)* (this game's dedicated and shared, the whole graphics card's) and *Memory (RAM)* (this game's private working set, the whole PC's).
6. **Latency** *(Tier 1 + Reflex only)* — PC latency timeline, avg/p95.
> **Built 2026-09-14 (P3 PR-7): tabs 2–6.** Frametime and Distribution show the session selected in the
> Sessions tab (the same `FrametimeChart` / `DistributionChart` as the summary window; a Tier-2 or
> retention-swept selection says why there is nothing). **Trend**: `Charts/TrendSeriesBuilder` — one point per
> hooked session oldest first under the selector (Average = Native where frame generation was measured and
> Presented where it was not, the note beside the chart says so; Displayed only where measured; the lows; max
> GPU °C), FR-6.4's exclusion of `settings_changed_midsession` sessions by default with the toggle and the
> excluded count, and FR-6.3's markers — labelled dashed lines wherever two consecutive sessions' hardware
> snapshots differ in GPU driver, GPU, CPU, display mode or OS ("GPU driver: 572.16 → 576.02"). **Sensors**:
> GPU core / hotspot °C, load % and power W (right axis) on one plot; VRAM on another with ~~the game's own
> per-present `vram_proc` (a held 1 Hz sample) and~~ the adapter-wide `vram_adapter` sensor ~~as two
> differently-labelled series~~ (corrected 2026-10-03: the Overlay never produced `vram_proc`, so the game's line was
> never drawn on any session; beta.12's two memory plots are described above). **Latency**: the `latency_us` blob with the stored avg / p95 lines, shown only
> when Reflex reported (`reflex_active`); otherwise the tab says so.
>
> **Trend, corrected 2026-09-25 (beta.8, owner item 6: "does Trend really work?").** It did not, on first open: the
> view model started loading before the page existed, and a load that finished first raised `TrendPresented` to nobody
> — the tab was blank until something reloaded it. The page now draws what the view model holds when it is made
> (`PagesLoadTests.TheTrendIsDrawnWhenThePageIsMadeOnADateAxisThatKeepsItsLabel`). Also: the date axis is created
> BEFORE the theme and the label (`DateTimeTicksBottom` replaces the bottom axis, and made afterwards it dropped both);
> **Average is two metrics** — *Presented FPS* on sessions that counted no generated frame (never on one that did: its
> presented rate includes them, the single inflated number rule 6 forbids) and *Native FPS* where frame generation was
> measured — and the trend opens on Native when the newest measured session counted generated frames; the machine
> metrics count **Tier-2 sessions too** (a game never hooked had no trend); a point that describes part of its session —
> settings changed, or a steady state, for Native and Displayed as well as the factor — is drawn **hollow** and the
> note says so; hardware changes on one day are **one** marker; the metric list is built in the language the page opens
> in; the empty text names the metric.
>
> **FPS with two decimals (same day, owner item 7).** Settings ▸ Window: *Show FPS with two decimals*
> (`ui.fps_decimals`, off by default) — every FPS figure through `Formats.FpsNumber`: "62.40" when on, "62" when off,
> rounded half away from zero both ways (it rounded half to even). `Services.FpsDecimals` holds it for the process
> like `LoggingLevel`: read at start, moved at once by the toggle, shown by a page the next time it formats.
>
> **Rule 6, the places that dropped the share (same day).** A steady-state factor is never shown without its share:
> the readout line ("58 → 116 FPS (×2.0 FG · 75%)"), which the Average card and Compare use, and the Sessions grid's
> FG× column ("×2.0 · 75%"). The header's "Lifetime average" was the last measured session's readout and says so now.
>
> **Compare (same day).** The best cell is in the accent colour — a local `Foreground` on the cell outranked the
> trigger, so it was only ever bold — and "best" is the best as shown (62.4 and 62.3 both read 62, both best); the load
> rows rank nothing; the percentile axis is 0–100 again (`AutoScale` ran after `SetLimitsX` and undid it); exported
> PNGs have an opaque background (`ChartTheme.SavePng`: the window's colour under the transparent figure).
### Session summary (secondary `FluentWindow`, also the post-session toast target)
Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration), TriState chips, API/PresentMode/upscaler line, crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons.
Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration, **Display** — beta.10: the mode shown longest with its share and the window's size, both tiers; **VRAM (this game)** and **RAM (this game)** — beta.12: the median with the peak beneath, both tiers), **Statistics per series** (beta.12: every stored series' mean / median / minimum / peak), TriState chips, API/PresentMode/upscaler line, **the display line** (beta.10: every mode's share, the changes, the window on its monitor at its refresh rate, the back buffer and swap effect, and what the facts rested on — "the swap chain said whether it was exclusive" or "from the window alone: exclusive fullscreen cannot be told from borderless"; absent for a session recorded before), crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons.
> **Built 2026-09-14 (P3 PR-6).** `Windows/SessionSummaryWindow` (a secondary `FluentWindow` with its own
> `ContentDialogHost`), opened from a Sessions-tab row (double-click or Open) and from the Dashboard's recent
> list. Stat cards read the STORED aggregates — never recomputed — with the lows labelled *(presented)* when
> frame generation was not measured (`03_METRICS`); a Tier-2 session shows N/A cards, a sentence, and no
> charts. Chips resolve through `TriStateResolution` and click into FR-8.3's dialog (`TriStateOverridePrompt`:
> measured / Yes / No / N/A, "also this game's default"); the override lands on `session_annotations`, the
> measurement stays, clearing restores it. Bars: crash (`Error`), safety unhook (`Warning`). Charts
> (`Charts/`): `SessionSeriesLoader` decodes the blobs once — cumulative time, the generated and gap bits, the
> application-frame view with `Domain.Metrics.StutterDetector` over it (the stored count's own rule), segments
> mapped from frame index to seconds, sensors aligned to `t_ms` with −1 dropped; `FrametimeChart` draws the
> application-frame series (the every-present series behind the FR-5.4 toggle, shown only when generated frames
> exist), stutter markers coloured by cause where `pso_created` says PSO compile (FR-5.5; the VRAM-budget cause
> has no per-frame source yet), the segment ribbon as alternating spans when there is more than one segment,
> and GPU temperature / load on the right axis behind the sensor toggle; `DistributionChart` draws the FPS
> histogram and the percentile curve (`Domain.Metrics.Percentile`, so the two lows are two points on it).
>
> **Honest charts, 2026-09-25 (beta.8, owner item 8: "fix the charts that are not reasonable").** Measured first on the
> owner's own Onimusha demo capture (DLSS FG ×3, read from a copy of the ledger): the title submits each generated frame
> half a millisecond after its application frame, so the "native" series — each application frame's interval to the
> present before it — was a generated frame's half millisecond, and the stored median read 2,073 FPS on a 60 FPS game.
> What changed, each with a test (`SessionSeriesLoaderTests`, `ChartMathTests`, `PagesLoadTests`):
> - **One stream.** `SessionSeriesLoader` charts the swapchain the statistics are over (`SegmentBuilder.DominantStream`,
> identified first, then the most presents) — the stored intervals are per swapchain, and two streams interleaved on
> one axis drew neither — with that stream's segments; the CSV export is the same stream (its header says so).
> - **Application frame to application frame.** The default series is each application frame's time from the previous
> application frame, the generated presents between them adding their intervals to it; a gap breaks the chain. It is
> labelled *Application frames* where frame generation was counted and *Presents* where it was not — never "Native"
> alone. A session whose presents were all generated (the `no_evaluations` refusal) charts every present and says so.
> - **The every-present line** (FR-5.4's toggle) leaves out the presents after a gap, which were drawn as 0 ms frames,
> and a note says what it is not: presents are timed at submission, and a burst of generated frames is not the
> display's cadence.
> - **Segments are labelled** with their settings (upscaler, render → output, frame generation) where the segment is
> wide enough; the label was computed for every segment and drawn for none.
> - **The sensor overlay is in step.** Schema 0013's `frame_blobs.first_present_ms` says where the first present sits on
> the sensors' clock; the overlay was drawn tens of seconds early (the launch and the loading screen). A session
> recorded before keeps the overlay off rather than drawn out of step; gaps are still closed up on the frame axis, and
> the note says how many when the overlay is on.
> - **Distribution.** The histogram is binned over the 0.5th–99.5th percentile, not min–max (one 0.3 ms non-frame set the
> axis to thousands of FPS), with the frames outside counted in a note, and its bars sit on their bins' centres (they
> sat half a bin left: ScottPlot's bins are lower edges). The percentile curve is drawn only where ten frames lie
> beyond a percentile on each side — FR-4.8's rule, generalised — so its 1% and 0.1% lows are marked exactly where
> the stat cards publish them, and the single shortest interval no longer sets the axis; the 0–100 axis holds.
> - **Sensors** (the tab and a new section of the summary window): power on a watt axis at the right, the second
> plot is *Memory* (the game's VRAM, the adapter's, the system's RAM), ~~a per-present VRAM of 0 is a present the sample
> did not reach and is left out~~ (corrected 2026-10-03: there was no per-present VRAM to draw — the Overlay never
> produced it; beta.12 replaced the plot with two, above), the time axis says where its zero is, and every line has its own colour in both
> themes (the light theme drew power and CPU temperature in one gold). **A session that was not hooked charts its
> sensors** — kept since 2026-09-22, shown nowhere until now.
> - **The game page follows the Agent while it is shown**: a `SessionCompleted` for this game reloads it
> (`GameDetailViewModel.Attach` / `Detach` on the page's Loaded / Unloaded; the link is a singleton and must not hold the
> page). Its sessions, trend and header were the ones it opened with.
> **FR-5.3:** `Charts/Decimator` — every bucket's min and max in order, ≤ 4000 points per series per draw, a
> 500k-point series keeps its spike and its dip (`DecimatorTests`). Zoom and pan are ScottPlot's.
> **FR-9:** `SessionExporter` — the CSV with `03_METRICS` §Export schema's column line verbatim and the `#`
> header block (tier, api, hardware, the tri-states with sources, the segments, ~~the 1 Hz VRAM note~~ — since beta.12
> the `# game_memory:` line, and a note that `vram_mb` is the in-game figure this build does not produce),
> InvariantCulture throughout, no rows for Tier 2; the JSON (`frameledger-session/1`: metadata, the row as
> aggregates with N/A omitted, segments, the annotation); PNG through `Plot.SavePng`. Tags (comma-separated,
> de-duplicated) and notes save to the annotation row. **FR-3.8** is an in-app notice on `SessionCompleted`
> (saved / discarded); the tray toast with "View" arrives with the tray (PR-8).
>
> **The loaded libraries (2026-09-25, beta.8).** Under the hardware line, a Tier-1 session says what it had loaded —
> `sessions.runtime_modules`, written since P2 and shown nowhere until then — sorted, one line: *"Loaded:
> 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) · sl.interposer.dll 2,8,0,0"*. The comparison is with the game's own copy (`games.library_versions`) as the
> same four numbers (`Formats.SameVersion`: Streamline's `2,8,0,0` string equals `2.8.0.0`); it names a difference and
> never who made it. Older rows show their list the day this ships; a Tier-2 row has none and no line.
>
> **The NVIDIA driver's side (2026-09-25, beta.8).** Two more lines where they have something to say
> (`Services.NvidiaOverrides`): the driver profile the game ran under and what it overrides — *"NVIDIA profile “Clair
> Obscur: Expedition 33”: DLSS override (preset K, Quality) · Frame Generation override (×4, latest preset)"*, or "no
> DLSS or frame generation override", or the global profile's when none names the game — and what the driver
> reported applying in the game's process from its override bits (*"NVIDIA driver, for this game's process: DLSS DLL
> chosen by the driver · preset K · Quality"*). Smooth Motion is labelled a setting community tools document, not
> NVIDIA. Neither line is a measurement (`03_METRICS` §Upscaling); a machine without an NVIDIA driver shows neither.
>
> **How it ended, and why (2026-09-25, beta.8, owner item 5).** Under the header line, *"How it ended: …"*
> (`Formats.ExitText`): a crash names its exception ("crashed (0xC0000005 access violation)", "0xC0000006 in-page I/O
> error: a disk or drive failed while the game read its files"), End task's exit code is an ordinary end said as
> what it is, and the event log's witness is named as such. The Tier-2 sentence has words for **every**
> `SessionEndReason` (`Formats.EndReasonText`, an enum-walk test keeps it so) and for every refusal no anti-cheat
> family names (`Formats.GuardSentence`: "The anti-cheat guard did not hook this game: the game is 32-bit…") — the
> safety notice and the enable-time refusal use the same words instead of "<signal> was detected in this game"; a
> launch that could not start says Windows' reason. The game page's missing-executable bar says whether the **drive**
> is not connected (FrameLedger finds the game again when it is) or the file is gone from its path, and so does the
> notice when enabling hooking meets an unreadable executable. Tests: `ReasonTextTests`, `Tier2ReasonTests`.
### Compare
Session picker (2–5, cross-game allowed) → overlaid percentile curves + stat table with best-value highlighting; FG columns always show Native and Displayed separately. Export PNG.
**Mixed-tier guard (FR-6.2):** selecting sessions from different capture tiers shows a blocking `ContentDialog` explaining that they measured different things; proceeding stamps the chart with a tier legend and greys out metrics unavailable in the lower tier. Sessions with `settings_changed_midsession` carry a warning icon and are excluded from trend lines by default.
> **Built 2026-09-14 (P3 PR-7).** `CompareViewModel` over the last 200 sessions across games: a `DataGrid`
> picker with a checkbox column (Compare enabled at 2–5), the FR-6.4 warning icon per row; **Compare** asks
> `IMixedTierPrompt` (a `ContentDialog`, default button Cancel) when the selection mixes tiers and compares
> nothing on a decline; a comparison that proceeds carries `Compare_Mixed_Legend` as the plot's title and an
> `InfoBar`. `CompareChart` overlays one percentile curve per hooked session (`Charts/PercentileCurve`, the
> distribution tab's own); the stat table is one row per metric — Native, Displayed and Presented FPS as three
> separate rows (never one column), Median, the lows, stutter time %, max GPU °C, duration — with the best
> value of each row bold and accent-coloured (higher wins for FPS, lower for temperature and stutter; N/A is
> never best), and a Tier-2 session's cells at N/A. Export PNG through `Plot.SavePng`.
>
> **beta.10:** three rows after Duration — *Display mode* (every share), *Window* and *Monitor* (with its refresh
> rate) — facts, not scores: no mode is better than another, so none is ever marked best, and every tier has them.
### Logs
Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:AutoSuggestBox`), pause-scroll; buttons: Open logs folder, Export bug bundle (routes to 10_LOGGING flow).
> **Built 2026-09-14 (P3 PR-8a).** `LogsViewModel` over `Services/LogTail`: the newest file of the chosen source
> (App / Agent) read with `FileShare.ReadWrite` — Serilog keeps it open — capped at the last 2 MB with the partial
> first line dropped, refreshed every 2 s while the page is on screen (the page's Loaded/Unloaded start and stop
> the timer) and never while paused; the level filter reads the `[HH:mm:ss.fff LVL]` prefix of 10_LOGGING's
> template ~~(continuation lines such as stack frames keep only under All)~~ — the App's; *(corrected 2026-10-04: the
> Agent writes Serilog's default template, a date first, which the filter did not read, so Warning and Error showed no
> Agent line; since beta.12 `LogTail.LevelOf` reads both)* — continuation lines such as stack frames keep only under All; the search is a plain `ui:TextBox`, not
> an `AutoSuggestBox` — there is nothing to suggest. The view is a read-only `TextBox` in Consolas that scrolls to
> the end on every refresh unless paused. "Export bug bundle" is 10_LOGGING's step 2 and nothing more (see there).
> The status line says shown / total / file. Tests: `LogTailTests`, `LogsViewModelTests`, and the page renders in
> `PagesLoadTests`.
### Settings
> **beta.11 (owner request 2026-10-03: "remove the Settings rows that have no button or similar").** Every row has a control
> now: the *Games with hooking on* card shows only while a game has hooking on (its empty sentence is gone); the *Elevation*
> card is gone and its state is the third line of *Run the agent as administrator* (its explanation a tooltip on it); the
> sentence under the language row is gone. A **Data** section has one row, **Delete all sessions…** (FR-1.7): the
> confirmation names how many, the Agent deletes them (`DeleteSessions`), and the strip says what happened or why nothing
> was deleted (a session being recorded, no agent, an older agent). Tests: `SettingsViewModelTests.DeleteAllSessionsAsksWithTheTotalThenGoesThroughTheAgent`.
Sections per FR-10 using the WPF UI settings idiom: `ui:CardControl`/`ui:CardExpander` rows with `ToggleSwitch`, `ComboBox`, `ui:NumberBox` (numeric inputs — min session length, sensor interval, retention). Language switch applies immediately (09_I18N). Theme selector (Light/Dark/System) drives `ApplicationThemeManager` (16 §Theming). **Capture section (top, most important):** the global **hooking kill switch** (`ToggleSwitch`, prominent) with a one-line summary of what it does; a list of games currently hook-enabled with a per-game revoke; Vulkan layer registration state + Register/Unregister; a link to the safety documentation. Turning the global switch off must take effect immediately, including for the Vulkan layer.
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", background capture toggle. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
**System (2026-09-21, FR "show the user's hardware"):** a card above Legal stating this PC as a session's hardware snapshot would record it right now — processor, graphics card, graphics driver, memory, Windows build, primary display — through the same `IHardwareSnapshotSource` the Agent stamps sessions with, read on the thread pool when the page opens, a field that could not be read as N/A, with **Copy** (the same lines as text) and a note that nothing is sent anywhere and what CPU temperature needs. Its own `SystemInfoViewModel`, not `SettingsViewModel`'s. The same snapshot is one tertiary line under the session summary's header (it was loaded for the export and shown nowhere), and `--diag` prints it; the bug bundle's `sysinfo.json` is deliberately NOT given it — its keys are the issue link's prefill.
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", ~~background capture toggle~~ *(removed in beta.12 — nothing read it; corrected 2026-10-04)*. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
> **The admin mode, beta.10 (owner decision D34; `01_ARCHITECTURE` ADR-9).** The Agent section has a switch, *Run the agent
> as administrator* (`capture.run_elevated`, off by default). Turning it on opens a `ContentDialog`
> (`Services.AgentAdminPrompt`, text `FrameLedger.Shared`'s `Safety_AdminMode_*`, version `agent-admin-dialog/1` in its
> corner) whose primary button is enabled only by ticking "I understand…" and whose default button keeps standard rights;
> declined, nothing is written. Either way the row is written and the Agent restarts — asked to stop over the pipe, its
> instance lock waited out, the connection's next round starting it the new way — **except under a running session**,
> which the restart would end: then the snackbar says the change applies at the Agent's next start. The elevation line
> says why a standard user's Agent is one when Windows was asked (`HelloAck.ElevationOutcome`: declined, answered by
> another account, could not start), and while the prompt waits the status pill reads *Waiting for administrator
> permission* (`AgentConnectionState.Elevating`).
> **Built 2026-09-14 (P3 PR-8a), with three rows deferred to PR-8b and one to PR-9.** `SettingsViewModel` over
> `Application.Settings.RegisteredSettings` (the registry of `06_DATA_MODEL` §Settings registry — every write is
> one `settings` row, and a key the Agent reads gets the 4 s "Applied. The capture agent reads it at the next
> session start" line, D16). **Capture, first:** the kill switch as a `CardExpander` whose header is the toggle
> and whose state line says "All hooking is off" / "Per-game settings decide" — it is `hooking.kill_switch`, the
> gate's fourth input (`CaptureSession` consults it at every 30 s re-scan, so a running measured session stops at
> its next scan; nothing else needs pushing); the hook-enabled list is `games.hook_enabled` as the ledger has it,
> and its per-row "Turn off" is `HookingConsent.DisableAsync` — `SetHookEnabled { enabled: false }` over the
> pipe, the Agent clears the column, the App never writes a hook-state column (D15; `SettingsViewModelTests`
> asserts the row is still enabled after a fake Agent acked); the Vulkan layer row reads
> `HelloAck.VulkanLayerRegistered` and says "unknown" without a HelloAck; the safety link opens
> `19_SAFETY_AND_ANTICHEAT.md` at the public repository in the user's browser (nothing is fetched).
> **Recording:** minimum session length, sensor interval and raw-series retention as `ui:NumberBox`es bounded by
> the registry; a value outside the range is refused in place (the previous value comes back, a warning names the
> range, nothing is written); ~~background capture as a toggle with the honest sentence (recorded, measured only if
> hook-enabled and not Vulkan)~~ *(removed in beta.12, 2026-10-04: the toggle wrote `capture.background`, which no Agent
> code read, so turning it off recorded every game anyway; with no way to start a game from the App, "off" could only
> have meant recording nothing. The key is reserved — `06_DATA_MODEL` §Settings registry)*. **Agent:** the elevation state from `HelloAck.Elevated` with the paragraph above
> (not required by any tier; unlocks CPU temperature through PawnIO and attaching to elevated games); the logon
> task row says the scheduled task arrives with the tray build. **Window:** "Start FrameLedger with Windows" is
> `Infrastructure.Startup.RunAtLogon` — this user's `HKCU\…\Run` value, quoted executable path, never HKLM —
> and the Run entry is the truth the toggle loads from; "Minimize to tray on close" is stored now and honoured
> when the tray exists. **Privacy:** ~~`privacy.online_metadata`, off by default, with the network sentence~~ — the card is not shown since 2026-09-16 (no code makes the request; the setting stays reserved).
> **Updates:** `update.channel` is read by PR-5's updater (beta = GitHub pre-releases), and `update.auto_check` — the startup check, on by default — sits beside it. **Logging:** `log.debug` moves this app's `LoggingLevelSwitch` at
> once; the Agent has no reader for the key yet, and the row says so. **Legal:** reopen is a "not yet" line
> until PR-9's gate exists. ~~Register/Unregister the layer, Register/Repair/Remove the task~~ — PR-8b, with the
> Agent flags they need. Tests: `SettingsViewModelTests` (seven cases), `RunAtLogonTests` (Infrastructure, under
> a test's own value name), and the page renders in `PagesLoadTests`.
>
> **8b built 2026-09-14.** The Vulkan layer row gained **Register / Unregister** and the logon task row
> **Register / Repair / Remove**; each button runs the Agent's flag as a child process (`IAgentTool` →
> `FrameLedger.Agent.exe --register-vklayer` / `--unregister-vklayer` / `--install-task` / `--uninstall-task`)
> and then re-reads the machine (`IMaintenanceState`: the HKCU key, Task Scheduler) — the text shown is what the
> machine holds, never what the button assumed. Register is enabled only while the layer DLL is staged, the
> registration is absent and ~~a game has hooking on~~ **a hook-enabled game references the Vulkan loader (P4 PR-2,
> 2026-09-14: `HookedGameViewModel.UsesVulkan` from `capability_flags`)** (the same rule the Agent's reconciler
> enforces on its own after every consent change and every sweep — the button is the repair tool, `12_BUILD`
> §The Vulkan layer is not registered at install time); Repair appears
> when the task's action names another path (a moved install). "Minimize to tray on close" is honoured.
>
> **2026-09-25 (beta.8):** Capture gained *Hide hooking on anti-cheat games* (`ui.hide_anticheat_hooking`, on by
> default) between the kill switch and the Vulkan layer row — §Games says what it hides; the game's page reads it at
> each load. It hides a control that could only be refused, never the finding.
>
> **2026-09-26 (beta.9, D33):** Capture gained *Allow hooking in games with user-mode anti-cheat that were measured
> before* (`hooking.usermode_ac_exceptions`, off by default), below the hide switch, and under it the **User-mode
> exceptions** list — the games the Agent found eligible (**Make exception…**), held back only by the session count,
> or carrying an exception (**Withdraw**), each with its finding, its successful hooked sessions and its state; with
> the option off only kept exceptions are listed, *suspended*. *Checking…* shows until the Agent has answered about
> every blocked game, and **Refresh** re-reads the list (the Agent's sweep runs every 15 s). The option is an
> Agent-read key and takes effect at the next session start and command.
>
> **2026-10-03 (beta.11, D38):** the option reads *Allow hooking in games whose only anti-cheat runs in user mode*, and
> its body names the trial. The list shows **only rows with an action** — eligible (**Make exception…**) or carrying an
> exception (**Withdraw**); "held back only by the session count" is gone with the count, and a game that can never
> qualify is explained on its own page. Each row is the game, its finding and its state — the state carries a grant's
> trial (*Exception in force since … — trial: 1 of 2 good sessions so far*), so the separate count line that repeated it
> is gone. **Refresh** shows only while a row is *Checking…*, the one time it can change anything.
### First-run flow
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept.
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept. **Since beta.12 (D45) Accept covers three** — the EULA, the Disclaimer, the Privacy Policy; the GPL is listed as *your licence*, with a line saying it needs no acceptance (GPLv3 §9), and gets no `legal_acceptance` row (`06_DATA_MODEL`). **Rendered since beta.12** (§Menu, *Documents are rendered*): the Markdown texts drawn, the GPL as written; a link from one document to another the gate shows opens it in the gate; *View on GitHub* opens the document at this build's source, through `IUrlOpener`.
2. Agent setup: runs **unelevated by default** — a short, honest paragraph explains that elevation is optional and unlocks CPU temperature and elevated-game attach. ~~and the Tier-2 ETW fallback. It must be explicit that **without elevation there is no Tier 2**~~ — **struck 2026-08-28: no tier needs elevation, so there is nothing to warn about here.** Capability check results shown afterwards. ~~with Tier-2 availability listed as its own badge~~ — there is no availability to report.
3. Hooking explainer: what Tier 1 vs Tier 2 means — **and it must be explicit that Tier 2 measures nothing**, because the honest version of this screen is the one where a user who declines knows what they are declining — and that hooking stays off until enabled per game.
4. Optional library import.
> **Built 2026-09-14 (P3 PR-9).** `Windows/FirstRunWindow` around `Controls/FirstRunContent` over
> `FirstRunViewModel`, shown by `ApplicationHostService` **before the shell** whenever `Services/LegalGate`
> says so — a first run, or a document whose version moved — and by Settings ▸ "Reopen the legal documents"
> in read-only mode. **(1) The gate:** the four documents ride in the assembly (`LegalDocuments`: `legal/EULA.md`,
> the root `LICENSE` as the GPLv3 text, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md`, embedded at build so the
> App shows the text this build was reviewed with; HTML authoring comments stripped; `{{RELEASE_DATE}}` left for
> `release.yml`), a list on the left, the text in a read-only box (~~raw Markdown~~ rendered since beta.12), "View on GitHub" per document, **one Accept**
> that writes ~~four~~ three `legal_acceptance` rows with each document's own `**Version:**` line ~~(`GPL-3.0-only` for the
> licence)~~ *(corrected 2026-10-04: since beta.12, D45, the GPL is shown for information and gets no row; an older
> `gpl` row is left as written)*, and Decline, which ends the host — the shell never appears. Closing the window without deciding is a
> decline. **(2) Agent setup:** the honest paragraph (unelevated by default; elevation optional, unlocks CPU
> temperature and elevated-game attach, required by no tier) and the facts from `HelloAck` as they arrive —
> state, version, telemetry source, overlay build, CPU temperature, elevated — N/A until the Agent answers.
> **(3) The explainer:** the consent dialog's own reviewed Tier 1 / Tier 2 paragraphs (`Safety_Consent_Hooked` /
> `_NotHooked`, so the two screens cannot drift), that hooking stays off until enabled per game, and that the
> Disclaimer states the risk. **(4)** ~~the import placeholder (P4)~~ **since P4 PR-4 (2026-09-14) a real pointer: the stores' libraries are imported from File ▸ Import library… once inside, every row hooking off** (the step itself stays text — the review dialog needs the shell's dialog host, which the first-run window has not). D8 unchanged: the gate is not a consent
> precondition. Tests: `LegalDocumentsTests`, `FirstRunViewModelTests` (required on empty, one Accept = ~~four~~ three
> rows at the documents' versions, a moved version re-shows only that document, decline/close write nothing,
> read-only records nothing, the Agent facts), the two steps rendered in `PagesLoadTests`.
>
> **NFR-4, measured 2026-09-14 on the dev box (Debug build, warm disk):** the first window (the shell, or the
> first-run window on a first run) is logged every run as "shown N ms after process start" — 1.3–1.5 s for the
> shell across PR-2 to PR-8b's smoke runs and 0.83 s for the first-run window on PR-9's, under the 2 s ceiling; a 100-session game's list + annotations query is a few
> milliseconds (`SqliteSessionQueryTests`, ceiling 500 ms asserted); charts draw at most `Decimator.DefaultBuckets × 2`
> points per series per draw whatever the session size (`DecimatorTests` over 500 000 points), which is what keeps
> pan/zoom interactive. The Win10 22H2 visual pass is the owner's (NFR-8, no VM here).
## UX rules
- Empty states for every list ("No sessions yet — launch a tracked game and FrameLedger will do the rest").
- All destructive actions confirm via `Wpf.Ui.Controls.MessageBox` (async — 16 §Dialogs): delete game/sessions, DB maintenance.
- Notifications strictly per the policy above (snackbar / InfoBar / tray).
- Keyboard: NavigationView items Ctrl+1…5; grids fully navigable; Esc closes flyouts/dialogs.
- Keyboard: ~~NavigationView items Ctrl+1…5; grids fully navigable; Esc closes flyouts/dialogs~~ — §Accessibility below, since P4 PR-8 (2026-09-15); this bullet named three behaviours and none of them was built or checked.
- No blocking dialogs during capture; errors surface as InfoBars/tray toasts.
- Charts and stat numbers use culture-aware formatting per active UI culture (09); colors only from theme resources or the per-theme chart palette (16 §ScottPlot).
## Accessibility
NFR-9 names three things — full keyboard navigation, adequate contrast in both Fluent themes, Per-Monitor V2 DPI —
and this section is what they mean for this app, each with the test that holds it (P4 PR-8, 2026-09-15). Until then
the requirement was one bullet under §UX rules, and nothing checked it.
### Keyboard
| Keys | Does | Where |
|---|---|---|
| **Ctrl+1 … Ctrl+5** (and the numeric keypad's 1–5) | Dashboard · Games · Compare · Logs · Settings | `MainWindow` `InputBindings` → `MainWindowViewModel.NavigateToCommand` → `ShellShortcuts` |
| **Alt**, **F10** | Focuses the menu bar; arrows and Enter walk File / Tools / Help | WPF `Menu`, nothing custom |
| **Tab / Shift+Tab** | Moves through a page in reading order | layout order; no `TabIndex` overrides |
| **Arrows, Home/End, Page Up/Down** | Move within a `DataGrid` (Sessions, Compare picker, Import checklist) | `DataGrid` defaults |
| **Esc** | Closes the open `ContentDialog` or `MessageBox` with no result — the same as its Close/Cancel button | `DialogKeyboard`, one class handler per dialog type registered at start-up |
**Esc is the Close button, never the primary one.** On the consent dialog (FR-2.1) that is "Keep it off": nothing is
stamped. A dialog that offers no Close button is not dismissed by Esc, and the Legal Gate (FR-11) is a window of its own
(`FirstRunWindow`) with explicit Decline and Accept, on which Esc does nothing. WPF UI 4.3.0 handles no key in
either dialog type (its `ContentDialog.cs` and `MessageBox.cs` at tag 4.3.0 have no key handler — read 2026-09-15),
which is why the handler is ours.
### Screen readers
- Every interactive control that shows no text of its own carries `AutomationProperties.Name` from `.resx` — the
toggles and choice boxes on Settings, the hooking switch on a game's page, and the icon-only close button in the
`InfoBar` template. A control *with* visible text needs nothing: its text is its name.
- `PagesLoadTests`-style scan (`AccessibilityTests.~~EveryTextlessControlHasAName~~ EveryInputThatShowsNoTextHasAnAutomationName`
— corrected 2026-10-04): every `Button`, `ToggleButton`, `ToggleSwitch`, `CheckBox`, `RadioButton`, `ComboBox`,
`TextBox`, `NumberBox`, `PasswordBox`, `Slider` and `HyperlinkButton` in the App's XAML either has content or a name. A new
unnamed one is red.
- Status lines that change after an action (the Database maintenance result) are `AutomationProperties.LiveSetting="Polite"`.
### Contrast
Colours come from the WPF UI theme dictionaries and nothing else, so contrast is the Fluent themes' — both of which
meet it — and cannot be broken locally: `AccessibilityTests.NoXamlHardCodesAColour` fails on any `#RRGGBB` or named
colour in the App's XAML. The chart palette is the one deliberate exception (`16_WPFUI_SYNTAX` §ScottPlot: one
palette per theme, chosen with the theme).
> **"Cannot be broken locally" had a hole, closed 2026-09-16.** `ui:Badge Appearance="Info"` — the Games card's
> "Hooking on/off" and the edit dialog's "Detected" — paints its background with WPF UI's `PaletteLightBlueBrush`, a
> fixed Material colour from `Palette.xaml` that is **not** in either theme dictionary, under the theme's white text:
> `#03A9F4` at **2.6:1** in dark, below AA-large, and no `#` in our XAML for the scan to catch. The hooking state is
> now a `Border` in the `HookStatePill` style (ON: the accent pair the ×FG chip uses; OFF: the Pill's muted fill with
> secondary text), the Detected badge is `Secondary`, and `ContrastTests` holds it two ways: **no `ui:Badge` in the App's
> XAML uses `Appearance="Info"`** (or `Caution`/`Danger`/`Success` — the same palette), and the WCAG ratio of every
> pill's (text, fill) pair, composited over the card and window backgrounds, is ≥ 4.5 in **both** theme dictionaries —
> with the old pair asserted *below* it, so the check is known to bite. The accent pair is measured against WPF UI's
> default accent; a user's system accent replaces it at runtime through `ApplicationThemeManager`, and WPF UI picks the
> on-accent text for it.
>
> **And `Secondary` was a second hole, closed 2026-09-21** (the owner's screenshot: two empty white boxes where a Steam
> title's platform and engine were, beside a readable "Hooking off"). WPF UI 4.3.0's `Secondary` trigger repaints only
> the badge's background (`ControlFillColorDefault`); `Foreground` stays `BadgeForeground`, the on-accent colour of the
> DEFAULT badge, which in the light theme is near-white text on a near-white fill. The hooking pill beside it was
> readable because it sets its own foreground. The platform and engine tags and the Detected marker are now a `Border`
> in the `TagPill` style with `TagPillText` (secondary text on the Pill's fill — the pair `ContrastTests` already
> measures in both themes as "hooking off"), and `ContrastTests.NoBadgeUsesTheSecondaryAppearance` refuses a literal
> `Appearance="Secondary"` badge in the App's XAML. The title bar's Agent badge binds its appearance and never binds
> Secondary.
>
> The Dashboard's FG qualifier chip was reported with it and had the other defect: not contrast (caution fill under
> primary text, ≈ 12:1) but **clipping** — the pill sat in a star column with no trimming, so a sentence-length
> qualifier overflowed the row. The qualifier text trims with an ellipsis at 260 px (the readout's tooltip carries the
> full sentence), and the row's readout column is sized to content with the game's name trimming first.
### DPI
`app.manifest` declares Per-Monitor V2 (`AccessibilityTests.TheManifestIsPerMonitorV2`).
### Known gaps, stated
- ScottPlot plots are not keyboard-operable (no focus, no pan/zoom by keys). The numbers behind them are on the
session summary's stat cards and in File ▸ Export (CSV/JSON).
- No screen-reader pass with Narrator has been done; the names above are necessary, not proven sufficient. That pass
is the owner's.
+35 -11
View File
@@ -2,12 +2,22 @@
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).
- 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.
- `SatelliteResourceLanguages` = `en;vi;ja` in ~~the App csproj~~ `Directory.Build.props` (corrected 2026-10-04) to keep publish size down.
## Key conventions
@@ -24,8 +34,8 @@ 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.
- CI check (`tools/resx-audit`): every key present in all three files; missing → build warning list artifact.
- `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 +55,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).
@@ -52,9 +67,12 @@ Technical benchmark vocabulary stays in English across all locales where the com
Consent, refusal, and safety-unhook text (FR-2.1, `19_SAFETY`) is **reviewed like legal text, not like UI text**:
- 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.
- 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
@@ -63,10 +81,16 @@ Consent, refusal, and safety-unhook text (FR-2.1, `19_SAFETY`) is **reviewed lik
> console text is out of `.resx` scope. That is why the PR that introduced it ships no en/vi/ja
> strings.
>
> **It is also why `ConsentProvenance` has no FR-2.1 member.** The host writes a consent record on
> **It is also why `ConsentProvenance` ~~has no FR-2.1 member~~ had no FR-2.1 member until 2026-09-13.** The host writes a consent record on
> the strength of an operator acknowledgement whose first line states, in substance, that it is
> *not* the FR-2.1 dialog. Drafting that dialog's wording English-only inside a developer tool
> would manufacture the reviewed artifact without the review this section requires — no `.resx`
> file exists anywhere in the tree yet, and `tools/resx-audit` does not exist either. The enum has
> exactly two members and a test asserts it, so adding the FR-2.1 value is a deliberate act that
> arrives with its reviewed strings or not at all.
> would manufacture the reviewed artifact without the review this section requires — ~~no `.resx`
> file exists anywhere in the tree yet, and `tools/resx-audit` does not exist either~~ (both exist
> since P3 PR-2, 2026-09-13; the App's family holds ~~shell text~~ every screen's text as of PR-9, 2026-09-14, and still no `Safety_*` key — those live in `FrameLedger.Shared`'s family, shared by both processes). The enum has
> ~~exactly two members~~ ~~**exactly three members since 2026-09-10**~~ **exactly four members since 2026-09-13** (P3 PR-4 added `ConsentDialog`, whose reviewed `Safety_Consent_*` text and whose producer — the Agent's `SetHookEnabled` stamp — landed in the same PR; P2 PR-F had added
> `AgentConsoleOperator`, the shipped Agent's console verb — HANDOFF §P2 decision D4 — which is
> likewise *not* FR-2.1 and says so in its first line; this sentence said "two" for three days after
> that) and a test asserts the list, so adding the FR-2.1 value is a deliberate act that arrives with
> its reviewed strings or not at all. ~~**P3 is where it arrives** (HANDOFF §P3)~~ **It arrived with P3 PR-4 (2026-09-13)**: `Safety_*` in `en` and
> `vi` (`src/FrameLedger.Shared/Strings.resx`, 20 keys), `ja` marked for human review and shown as `en` until signed, and `tools/resx-audit` ~~built in
> the same phase~~ built first (PR-2), so PR-4's family landed under a gate that already existed.
+142 -5
View File
@@ -2,11 +2,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.
- 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.)*
- 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}`.
- **Never log:** full user paths outside `%LOCALAPPDATA%\FrameLedger` (redact to `<user>`), machine name, any exe arguments of games. A `RedactingEnricher` enforces the path rule.
> **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.
## Crash handling (the app's own crashes)
@@ -15,20 +23,134 @@
- 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
> path and a Warning line, and the partial file is removed.
>
> **The App.** A `DispatcherUnhandledException` is marked handled, so the process lives long enough to ask; then
> `Services/CrashReporter` runs Fatal → dump → `Services/CrashDialog` → on Yes, the shell window revealed (a window
> hidden in the tray would hold the report's dialogs where nobody sees them) and `BugReportFlow` → the host's
> `StopApplication`, and `RunAsync` exits with code 1 after the normal teardown (with no host yet, `Shutdown(1)`
> directly). The dialog is a **Win32 `MessageBox`**, not a WPF UI one: the shell's dialog host, theme and dispatcher are
> what a crash cannot vouch for. It says where the dump is (or that none could be written), that the capture agent keeps
> running, and that the report shows every file and includes the dump only when ticked. **One report per process**: a
> further exception while the dialog is up shows nothing; the first of those is logged whole and the rest are counted,
> because a fault in a layout pass repeats on every pass the dialog's own message loop runs and would flood
> `ui-*.log`. A failed dump still asks; a failed report is an Error line, not a second crash. An
> `AppDomain.UnhandledException` (any other thread) is Fatal + dump only: the runtime is already ending the process and
> no dialog can be relied on to appear, so the next bug report offers that dump instead. An unobserved task stays an
> Error line. A startup failure `RunAsync` catches itself (the ledger will not open, the host will not start) is not an
> unhandled exception: ~~it is still a Fatal line and exit code 1 with no dialog~~ **since 2026-09-15 it is the Fatal
> line and `Services/StartupFailureDialog`**, a Win32 message box with the exception's message and the log folder, whose
> Yes opens that folder; exit code 1 either way. Until then nothing on screen said FrameLedger had even tried to start.
> Tests: `StartupFailureDialogTests`.
>
> **The Agent** (no window, so no dialog): the same Fatal + dump from `AppDomain.UnhandledException` and from `Main`'s
> own catch, once per process whichever sees it first, then the exception stays unhandled, so the exit is the runtime's
> and never the Agent's usage code 1. The catch exists because an exception escaping `Main` runs `Main`'s `finally`
> first, which closes the logger; the AppDomain handler alone would dump with no Fatal line.
>
> Tests: `CrashDumpWriterTests` (a real dump of the test process starts `MDMP` and carries the UTC time in its name; the
> prune keeps five and touches no other file; an unusable directory is null and one line), `CrashReporterTests` (the
> order, no report on No, three further exceptions show nothing and are counted, a failed dump still asks, a failed
> report does not throw, the dialog's text with and without a dump).
## In-app log viewer (Logs screen)
Tails the active files (shared read), level filter, text search, pause autoscroll, "Open logs folder", "Export bug bundle". Reads at most last 2 MB per file into the view.
> **Built 2026-09-14 (P3 PR-8a)** — `App/Services/LogTail` + `LogsViewModel`; `08_UI` §Logs carries the built
> note. One file at a time (the newest of the chosen source), not both; the 2 MB cap is `LogTail.MaxBytes` and
> the read is `FileShare.ReadWrite | Delete` so Serilog's open handle and its daily roll never block it.
## Bug report flow (FR-13)
1. Entry points: Help → Report a bug, crash dialog, Logs screen button.
2. **Bundle builder** creates `FrameLedger-bugreport-YYYYMMDD-HHmm.zip` in a user-chosen location:
- `logs/` (last 7 days, redacted copies)
- `sysinfo.json` (app + agent + **overlay build id**, OS build, CPU/GPU name, driver version, telemetry source, Vulkan layer state, PawnIO present?, elevation state, locale)
- `overlay-<pid>-*.log` for the last hooked sessions, plus hook fault details and the ring's dropped/fault counters — these are what make injection bugs diagnosable at all
- `overlay-<pid>-*.log` for the last hooked sessions, plus hook fault details and the ring's dropped/fault counters — these are what make injection bugs diagnosable at all. *(The file exists since 2026-09-06 — `17_HOOK_ENGINE` §Native logging: written at init, on the Agent's request at session end, and on the stop; `FAULT` lines carry the exception code and the hook's name, `UNHOOK_*` lines say per patch whether it was restored or left to a later hooker.)*
- `settings.json` (sanitized — no paths)
- optional checkbox: last session metadata + aggregates JSON (never raw blobs by default)
- crash dumps included only when the user ticks the checkbox (size warning shown)
> **Step 2 built 2026-09-14 (P3 PR-8a), narrower than this list; steps 1 (Help menu, crash dialog), 3, 4 and 5
> are P4's.** `App/Services/BugBundleBuilder` writes the zip where the Logs page's save dialog says
> (`FrameLedger-bugreport-YYYYMMDD-HHmm.zip`): `logs/` = every `ui-*.log` and `agent-*.log` modified in the last
> seven days, ~~**copied verbatim, not redacted** — the files carry no paths beyond the data directory and no
> game data, and a redaction pass that nobody has specified would be a claim~~ **redacted since 2026-09-15, note
> below** (the data directory is under the user's profile, so the claim was false on every machine); `overlay/` = the five newest
> `overlay-<pid>-*.log` (the ring's counters and the `FAULT`/`UNHOOK_*` lines are in those files, not
> separately); `sysinfo.json` = app version, and from the Agent's `HelloAck` when connected its version, the
> overlay build id, telemetry source, Vulkan layer state, elevation, CPU-temperature availability (the
> PawnIO question) and the disclosure version, plus OS version, bitness, locale and the write time — **no
> CPU/GPU name or driver version**, which live in the ledger's hardware snapshots and are the session
> metadata option this list already has; `settings.json` = every registry key's effective value (there is no
> path-valued key). No session JSON ~~and no dumps~~ (PR-9 below). ~~The bundle is written and nothing else happens: no preview
> dialog yet, no browser, no clipboard.~~ Tests: `BugBundleBuilderTests` (the seven-day cut, the overlay cap, a
> `game-crash.log` beside ours is not shipped, both JSON files), `LogsViewModelTests` (the cancelled save writes
> nothing).
>
> **Steps 1 (the Help menu), 3 and 4 built 2026-09-14 (P4 PR-3)** as `App/Services/BugReportFlow`, the one flow
> behind Help ▸ Report a bug… and the Logs page's button: step 2's zip → step 3's `ContentDialog`
> (`BugReportPreviewPrompt` / `Dialogs/BugReportPreviewContent`) listing every entry `WriteAsync` returned, with
> "Show the zip in Explorer" and the drag instruction → step 4 as the dialog's two buttons: **Open GitHub issue**
> opens `issues/new?template=bug_report.yml&title=[Bug]%20&labels=bug&app-version=…&os=…` — the form's field
> ids are **hyphenated** (`app-version`, `os`), which is what GitHub prefills by, not the underscores step 4
> above spelled; the OS is the form's own spelling (`Windows 11 26100.2314`, `IssueLink.OsText`) — and **Copy
> summary as Markdown** puts `sysinfo.json`'s twelve keys on the clipboard as a table. Both behind ports
> (`IBugReportPreview`, `IUrlOpener`, `IClipboard`) so `BugReportFlowTests` pins the exact URL without a browser.
> ~~Still open from this list: the **crash dialog and the minidump** (§Crash handling, step 1's third entry point)
> and the optional session-metadata / dump checkboxes of step 2.~~ PR-9 below, and the session-metadata checkbox after it (2026-09-15).
>
> **The log copies are redacted since 2026-09-15.** `App/Services/LogRedactor` is what the list's "redacted copies"
> and `legal/PRIVACY_POLICY.md` §3 promised: in every `logs/` and `overlay/` entry the name in each
> `X:\Users\<name>` path becomes `<user>`, and so does the last segment of this user's profile directory when it
> lives elsewhere (`D:\Profiles\<name>`). Every spelling a log carries is covered: backslashes, the doubled
> backslashes of Serilog's JSON properties, forward slashes, any case, a name with spaces, and the `?` the Overlay's
> ANSI image path writes for a letter its code page lacks. The file is read as bytes through Latin-1, so a UTF-8
> log and an ANSI one both come out byte for byte except the names. Over-redaction is the chosen failure:
> `C:\Users\Public` reads `<user>` too. The measured need on the dev box: the profile path appeared 8 times in
> `ui-*.log`, 7 in `agent-*.log` and in 175 overlay headers; no machine name or bare user name did. A crash dump is
> memory and cannot be redacted, which its checkbox says. Tests: `LogRedactorTests` (fifteen cases, both
> directions, UTF-8 and ANSI bytes), `BugBundleBuilderTests` (the copies carry no user name, the file on disk is
> untouched).
>
> **The crash dump's checkbox and step 1's third entry point built 2026-09-15 (P4 PR-9).** When
> `BugBundleBuilder.LatestCrashDump` finds a `*.dmp` written in the last seven days under `crashdumps\` (either
> process's), the flow shows **Optional items** before the save dialog (`BugReportPreviewPrompt.AskCrashDumpAsync` →
> `Dialogs/BugBundleOptionsContent`): one checkbox, **clear**, labelled with the dump's local time and its size in MB
> (the size warning), and a line saying a dump is FrameLedger's own memory and can hold file paths, game names and
> settings. Continue with the box clear writes the bundle without it; ticked, `crashdumps/<name>.dmp` goes in;
> Cancel writes nothing. `WriteAsync` refuses a dump from anywhere but that directory, before the zip is created. It
> is a dialog before the save rather than a box on step 3's preview because the preview lists a zip that is already
> written. The crash dialog (§Crash handling) is step 1's third entry point. ~~Still open: the session-metadata
> checkbox.~~ Built the same day, below. Tests: `BugBundleBuilderTests` (only when passed, only from the directory,
> the newest of the week), `BugReportFlowTests` (no dump no question; left clear, ticked, cancelled),
> `BugBundleOptionsViewModelTests`, `PagesLoadTests`.
>
> **The last session's checkbox built 2026-09-15**, which completes this list's optional items. The same **Optional
> items** dialog carries a second box when the ledger holds a session: the newest one (`App/Services/LastSessionSummary`),
> labelled with its game and local start time, with a line saying what the file holds. Ticked, the bundle gains
> `session.json`: File ▸ Export's own JSON (`SessionExporter.Document` — metadata, aggregates, segments, hardware)
> **without the user's notes and tags**, and passed through `LogRedactor` like a log because it names the executable.
> No frame or sensor series, which is the list's "never raw blobs". The dialog now appears when either item exists and
> not at all when neither does; the port's answer is `BugBundleOptions` (closed, or which boxes were ticked) where
> PR-9's was `CrashDumpChoice`. Tests: `LastSessionSummaryTests` (the newest session, no notes or tags, nothing for an
> empty ledger), `BugReportFlowTests` (left clear, and ticked with a profile path redacted in the zip),
> `BugBundleOptionsViewModelTests` (every box clear, an absent item cannot be included), `PagesLoadTests`.
3. **Preview step:** the dialog lists every file included and lets the user open the zip before continuing. Nothing is ever sent automatically.
4. "Open GitHub issue" → launches browser to
`https://github.com/poli0981/frameledger/issues/new?template=bug_report.yml&title=[Bug]%20&labels=bug&app_version=…&os=…`
@@ -37,6 +159,21 @@ 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, 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
> App's. Tests: `DiagReportTests`.
+81 -4
View File
@@ -1,6 +1,6 @@
# 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.)*
## Flow
@@ -8,7 +8,7 @@ Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledg
- **Manual check** (Help → Check for updates): progress dialog; all failures produce the mapped dialog below.
- **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 +21,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,9 +29,86 @@ 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.)*
- 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
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 —
measured from start, because the shell shows synchronously inside it), only for a copy the installer laid down
(`UpdateManager.IsInstalled`; a `bin/` build logs one line and does nothing) and only while `update.auto_check`
is on (Settings ▸ Updates, default on — the "if enabled" above). Every failure is `Information` in the log,
never a dialog. A release found is downloaded in the background; the tray raises a balloon only while the
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~~ 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 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.~~ **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) —
**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.
- **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
own `%LOCALAPPDATA%\velopack\velopack.log` on every start — local, the library's, and stated here because it is a
file outside `%LOCALAPPDATA%\FrameLedger`.
- **Where it installs:** `%LOCALAPPDATA%\FrameLedger.App` (the package id), never `%LOCALAPPDATA%\FrameLedger`, which is
the data folder Velopack would otherwise delete on uninstall (`12_BUILD` §Publish & package).
**Deviations from the table and the paragraph above, stated rather than left to be discovered:**
- `Update_Err_RateLimited` says "try again in about an hour", not "in {n} minutes": Velopack's downloader
surfaces the status code (`HttpRequestException.StatusCode`) and not `Retry-After` / `X-RateLimit-Reset`.
Likewise **no `If-None-Match` ETag** on the check — the request is Velopack's, not ours. The quota is 60/h
anonymous; the App makes one request per start plus manual checks, so the header would change nothing in
practice, but the sentence above promised it and this one withdraws it.
- **No `GitHubHttpClient`**, no 10 s timeout of ours, no jittered retry: the HTTP is Velopack's
`HttpClientFileDownloader`, subclassed as `FrameLedgerFileDownloader` only to put `User-Agent: FrameLedger/{version}`
in place of `Velopack/1.2.0` (a read-only static there). The GitHub source adds no `Authorization` header for an
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.~~ Corrected 2026-10-03: rendered since beta.12 (Markdig; HTML off, no image fetched).
`UpdateServiceTests` (App.Tests/Update) cover the two skips, the channels, Deferred ↔ Ready, each error row, and
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; ~~a real feed has
not been exercised — the first tag is the measurement~~ *(corrected 2026-10-04: the feed has existed since
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).
+110 -27
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,10 @@ 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.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
- `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.
- `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.
- `fl_stub_sl_interposer` → `sl.interposer.dll`, and `fl_stub_sl_common` → `sl.common.dll` (`src/native/tools/vendor-stubs/`). **Fixtures, never shipped**, built under `FL_BUILD_TOOLS`; nothing `12_BUILD` publishes references them. They export the **measured** vendor names from `docs/vendor-exports.json` so the Overlay's symbol resolution is observable, and the second is a **decoy** exporting the same name from a different module — without it, "we resolve module-scoped" is a property no test can falsify. Their **output filenames are the vendor's and their version blocks are ours**: `fl_add_version_resource` takes the real filename so a file called `sl.interposer.dll` in our build tree still says plainly that it is FrameLedger's, which `19_SAFETY` requires of everything we build.
@@ -36,13 +38,13 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
**MinHook** is fetched by CMake `FetchContent` and built from source, pinned to the **commit** behind tag `v1.3.4` (`c3fcafdc`) rather than to the tag name — a tag can be moved, a commit cannot. FetchContent over a submodule so a fresh clone needs no extra step and CI has nothing to remember. Upstream warnings are not subjected to our `/W4 /WX`: warnings in third-party code are upstream's to fix, and failing our build on them would only tempt someone to patch the fetched copy, which drags it out of "consumed unmodified". The BSD-2-Clause notice ships in `legal/licenses/`, and `tools/license-check.ps1` fails the build if it goes missing while the FetchContent declaration is still present.
**NVAPI SDK** (MIT) **is vendored** at `src/native/third_party/nvapi/` — headers, `amd64/nvapi64.lib`, `License.txt`, consumed through `fl_nvapi` and proven by ctest `fl_nvapi_probe`. `legal/licenses/nvapi-MIT.txt` carries the notice and `license-check.ps1` binds the two bidirectionally.
**NVAPI SDK** (MIT) **is vendored** at `src/native/third_party/nvapi/` — headers, `amd64/nvapi64.lib`, `License.txt`, consumed through `fl_nvapi`, proven by ctest `fl_nvapi_probe`, and **linked by a shipped binary since 2026-09-10** (`FrameLedger.NvapiBridge`, above). `legal/licenses/nvapi-MIT.txt` carries the notice and `license-check.ps1` binds the two bidirectionally.
> **This paragraph said "is not vendored yet" until 2026-08-09**, in the present tense, and added that `src/native/third_party/` *"contains `CMakeLists.txt` and `vulkan-headers` only"*. Both were false from #55 (2026-08-05) onward. The sentence was itself a correction — of an earlier claim that NVAPI *was* vendored when it was not — so this file has now been wrong in both directions about the same fact, which is worth more than the fix: **CLAUDE.md's pinned stack and `18_GPU_VENDOR_APIS` §L3 were updated when the vendoring landed and this one was not.** `legal/` is gated bidirectionally and caught its own version; `docs/` is not gated, and this is what that costs. Link it normally; do **not** resolve NVAPI by ordinal (that was a workaround for a licensing constraint that no longer exists, and it breaks across driver versions). Still guard `NvAPI_Initialize` failure as a normal path — plenty of users have no NVIDIA GPU.
**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.
## Managed build & native integration
@@ -54,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) and `/FrameLedger.Rules.targets` (the blocklist seed). 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.
@@ -63,10 +65,15 @@ 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.)*
**Toolchain gotchas, both hit on a real machine and both handled by `build.ps1`:**
@@ -87,7 +94,28 @@ 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`, `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer`.
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
> surface, pinned by `AgentCommandLineSurfaceTests`: `consent list | grant --exe | revoke --exe`, `capture --exe
> [--seconds n]`, `launch --exe [--args "…"] [--seconds n]`, `recover`, `sessions [--last n]`, `db path`,
> `games add --exe`, `killswitch on | off | status`, and `--data-dir <dir>` — **under `--console` only**
> (HANDOFF §P2 decision D6): `--serve` never takes one, so the product's `%LOCALAPPDATA%\FrameLedger` is not
> selectable and an integration test cannot point the product at a profile. `AgentEndToEndTests` runs the
> 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
@@ -96,7 +124,7 @@ Agent flags: `--serve`, `--console`, `--diag`, `--install-task`, `--uninstall-ta
The struck text is kept because the *reason* it was written is still live. What it said next, and what remains true:
> **planned, not present.** `assets/` does not exist, nothing fetches or verifies the binary, and `EtwFrameSource` is unwritten. `20_OPEN_QUESTIONS` §M2 (does the pinned console binary still exist, run unelevated, and emit the 2.x column set?) is unanswered, so this is not merely unpinned — there is nothing to pin yet.
- Vulkan layer manifest, **written** with the installed layer path at install time (Velopack hook) — but **not registered there**. Registration is a separate, later act.
- ~~Vulkan layer manifest, **written** with the installed layer path at install time (Velopack hook) — but **not registered there**.~~ **The install hook writes nothing (P4 PR-5):** the manifest is written by the registrar the first time the ledger asks for the layer (`VkLayerRegistrar.Register`, P4 PR-2), so an install that never enables a Vulkan game has no manifest either. Registration is a separate, later act.
### The Vulkan layer is not registered at install time
@@ -117,15 +145,59 @@ the `--register-vklayer` Agent flag (§Agent flags — a manual repair tool, not
normal path), and the Settings button (`08_UI` §Settings — it reflects and
repairs state, it does not grant machine-wide reach on its own).
> **Enforced 2026-09-14 (P4 PR-2).** "A Vulkan game" is a static fact of the executable — it imports or
> `LoadLibrary`s `vulkan-1.dll` — read by the Agent's detection sweep into `capability_flags` as `vulkan`
> (`17_HOOK_ENGINE` §Vulkan built note). `Application.Vulkan.VkLayerReconciler` registers when the first
> hook-enabled game carries it and unregisters when the last one is disabled, after every consent change and
> after every sweep; the flag and the button run the same rule. The uninstall hook is still the updater's
> (P4, Velopack).
## Version
**One source: the `VERSION` file at the repository root** (`MAJOR.MINOR.PATCH`, nothing else — P4 PR-5,
2026-09-14). Before it, the managed assemblies carried the SDK's default `1.0.0` while CMake said `0.1.0`,
two products claiming to be one.
- `Directory.Build.props` reads it into `<Version>` (assembly, file and informational versions; SourceLink's
`+sha` suffix is off so About, `Hello` and the bug bundle print the version a user can find on the releases
page). The read is conditional on `$(Version)` being empty, so `release.yml` passes `-p:Version=0.1.0-beta.1`
for a pre-release and the assemblies carry the tag's full version.
- `src/native/CMakeLists.txt` reads the same file into `project(VERSION …)`, which the `.rc` template turns
into every VERSIONINFO block. CMake's `project()` accepts numbers only, so the native `FileVersion` is the
numeric core even for a pre-release.
- `tools/versioninfo-check.ps1` compares every built binary's `FileVersion` against the file (`x.y.z.0`), so a
read that silently produced `0.0.0` on either side is red in the gate.
- `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.
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.
## Publish & package
```
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.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -o out/app
vpk pack --packId FrameLedger --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --icon assets/icon.ico
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
```
> **Run by `release.yml` since 2026-09-14 (P4 PR-5)** — `13_CI_CD` §release.yml carries the steps around it
> (the version gate, `{{RELEASE_DATE}}`, the published-tree assertion, checksums, the release). Both publishes
> take `-p:Version=<tag>` (§Version). No `--icon`: `assets/icon.ico` does not exist, and this line named it
> for six weeks. **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`.
>
> **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
> directory when the app is uninstalled; `%LOCALAPPDATA%\FrameLedger` is the data folder (`LedgerPaths`, `07_IPC`,
> `legal/PRIVACY_POLICY.md` §1). With the same id the install would live inside the ledger's folder and the
> uninstaller would take `ledger.db` with it, without the question below. The title users see stays "FrameLedger"
> (`--packTitle`); the installer is `FrameLedger.App-win-Setup.exe`. `UninstallHook.AreSeparate` refuses the data
> delete if the two ever overlap again, so a future id change fails safe rather than silently.
>
> **Exactly two roots, and a gate now says so.** `src/FrameLedger.CaptureHost` — the unshipped
> capture host — is outside the package because neither root references it, and
> `tools/package-closure-check.ps1` is what keeps that true rather than remembered. It matters
@@ -150,16 +222,16 @@ vpk pack --packId FrameLedger --packVersion {ver} --packDir out/app --mainExe Fr
> 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.
- Velopack hooks: installed → offer Agent setup + Vulkan layer registration; uninstalled → unregister the layer, remove the scheduled task, ask about the data folder.
- `SatelliteResourceLanguages=en;vi;ja`. ~~Expected package ≈ 95–130 MB self-contained.~~ **Measured 2026-09-14 (P4 PR-5): the published tree is 250 MB in 362 files** (App + Agent, self-contained, ReadyToRun roughly doubles the IL). `vpk pack` 1.2.0 over that tree, run by hand the same day with the workflow's arguments: `FrameLedger.App-win-Setup.exe` **104 MB**, the full `.nupkg` and the portable zip 100 MB each, plus `releases.win.json` / `RELEASES` / `assets.win.json`; vpk's own pre-process step verified `VelopackApp.Run()` in `FrameLedger.App.Program::Main()`. **From the hosted runner on the first tag (2026-09-16, `v0.1.0-beta.1`):** the tree 252 MB, `Setup.exe` 110 MB, the nupkg and the zip 105 MB — the same shape, a few MB heavier for two more days of code.
- Velopack hooks (**built 2026-09-14, P4 PR-5**: `App/Update/VelopackHooks`, wired in the hand-written `Program.Main` before any window). **Install registers nothing** — the first-run flow is the offer (Agent setup), and the layer follows the ledger (§The Vulkan layer is not registered at install time); this line used to say "offer Agent setup + Vulkan layer registration", and the second half was the thing the section below forbids. Uninstall runs `UninstallHook`: `Shutdown` to a running Agent over the pipe (best effort, it holds the install directory), unregister the layer (HKCU), remove the logon task, then **ask** about the data folder — deleted on Yes only, never when it and the install overlap (`AreSeparate`), and a question unanswered inside Velopack's 30 s callback budget keeps it.
## Release-time token substitution
`{{RELEASE_DATE}}` in `legal/*.md` is the **only** placeholder that survives into
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` — **which
does not exist yet; `13_CI_CD` §release.yml records that** —
substitutes it with the tag date when packaging, and `ci.yml` fails the build if
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~~ 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
@@ -168,24 +240,34 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
## Local quality gate (pre-push)
`./build.ps1 check`:
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`)
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`) — since beta.12 also `FrameLedger.ProcessStats.dll` (the game
process's memory, D43; staged beside the Agent, CaptureHost and Infrastructure.Tests by
`FrameLedger.ProcessStats.targets`), its ctest `fl_process_stats` (GPU_INSTANCE on a machine with a hardware adapter,
NO_GPU_INSTANCE elsewhere) and the instrument `fl-probe-processstats` (`spike-notes` §16)
2. native tests (Catch2)
3. `clang-format --dry-run -Werror` over `src/native`
4. `dotnet restore` + build (warnings as errors)
5. `dotnet format --verify-no-changes`
6. `dotnet test --logger trx` — including `ShmLayoutMirrorTests`; with no switches it also runs the
`Category=Integration` classes, which CI excludes
`Category=Integration` classes, ~~which CI excludes~~ which CI runs too *(corrected 2026-10-04: `ci.yml` and
`release.yml` call `./build.ps1 check` with no switches since 2026-09-06, as the paragraph after this list says;
only `-SkipIntegration`, which nobody passes, leaves them out, loudly)*
7. `tools/coverage-gate.ps1` — reads this run's cobertura reports; self-arming, and armed today for
`FrameLedger.Domain` and `FrameLedger.Application`
8. `tools/rules-validate.ps1` (schema + `anticheat` block sanity — a malformed or empty blocklist is a safety bug)
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees
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)
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
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
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`
15. `tools/resx-audit` — **skipped loudly; it does not exist, and no `.resx` file does either**
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)
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
17. Placeholder guard — fails if any `{{` token other than `{{RELEASE_DATE}}` survives in `README.md` or `legal/*.md`
> **This list was wrong in two ways until 2026-08-06 and both were the same kind of wrong.** Step 6
@@ -196,9 +278,10 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
> list of what `check` does was missing 40% of it, which is worse than having no list: a reader
> plans against it. `13_CI_CD.md` repeats the struct-mirror claim and is corrected with it.
CI runs the identical script (`13_CI_CD`), **with `-SkipIntegration`** — so a green CI is not
evidence for anything touching the managed drain, and `./build.ps1 check` with no switches is what a
developer runs before pushing.
CI runs the identical script (`13_CI_CD`) with no switches since 2026-09-06 — `-SkipIntegration` was
CI's from 2026-08-05 until §S19(b)'s signer half removed the refusal behind it — so a green CI is now
evidence for the managed drain too, and `./build.ps1 check` with no switches is what a developer runs
before pushing.
**Gates skip loudly.** A gate whose tool is not installed (no `cl.exe`) or not
yet written prints `SKIPPED`, is listed again in the summary, and the run ends
+148 -30
View File
@@ -1,28 +1,88 @@
# 13 — CI/CD
FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, and repo-local workflows where they do not. `ci.yml` is repo-local **by necessity, not preference**: the ops repo's `reusable-desktop-csharp.yml` runs `dotnet restore` / `build` / `test` directly and exposes no input for a native pre-step, MSVC setup, or the Vulkan SDK. FrameLedger's build is mixed-toolchain and native-first, and `12_BUILD.md` §Local quality gate commits to CI running *the identical script* as local — a promise a pure-managed template cannot keep. CodeQL and release still call the ops repo.
FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, and repo-local workflows where they do not. `ci.yml` is repo-local **by necessity, not preference**: the ops repo's `reusable-desktop-csharp.yml` runs `dotnet restore` / `build` / `test` directly and exposes no input for a native pre-step, MSVC setup, or the Vulkan SDK. FrameLedger's build is mixed-toolchain and native-first, and `12_BUILD.md` §Local quality gate commits to CI running *the identical script* as local — a promise a pure-managed template cannot keep. CodeQL is repo-local too (its own heading below says why), and so is `release.yml` since 2026-09-14 — the same native pre-step and the identical gate make a caller stub impossible for it as well; this sentence said both "still call the ops repo" until then.
> ⚠ Known gotcha (learned on earlier migrations): caller stubs **must declare explicit `permissions:` blocks** — permissions do not inherit into reusable workflows. Every stub below lists its own.
## Workflows (`.github/workflows/`)
### `ci.yml` — push to `main` + all PRs · **repo-local**
### `ci.yml` — push to `main` + all PRs + `workflow_dispatch` (added 2026-10-04) · **repo-local**
- `runs-on: windows-latest`, .NET SDK pinned by `global.json` via `actions/setup-dotnet`, MSVC via `ilammy/msvc-dev-cmd`, NuGet cached.
- Single step of substance: **`./build.ps1 check -SkipIntegration`** — the same script a developer runs before pushing. The gate list lives in `12_BUILD` §Local quality gate, **once**, rather than being restated here where it goes stale.
- **`-SkipIntegration` is the one place local and CI deliberately differ**, and the reason is a measured property of the hard gate rather than flakiness: §S16 puts the injecting process's ancestors in the scan set, a .NET test host can load `System.Security.Cryptography.ProtectedData.dll`, and the guard's `protect` fragment then refuses our own harness (§S19(b)). So a green CI is **not** evidence for anything touching the managed drain or the capture host's end-to-end behaviour.
- Single step of substance: **`./build.ps1 check`** — the same script, with the same switches (none), a developer runs before pushing. The gate list lives in `12_BUILD` §Local quality gate, **once**, rather than being restated here where it goes stale.
- ~~**`-SkipIntegration` is the one place local and CI deliberately differ**~~ — **gone since 2026-09-06.** From 2026-08-05 CI passed it for a measured reason: §S16 puts the injecting process's ancestors in the scan set, a .NET test host loads `System.Security.Cryptography.ProtectedData.dll`, and the guard's `protect` fragment refused our own harness (§S19(b)). The signer half now verifies that module's embedded signature offline and reads `O=Microsoft Corporation` on the compiled-in bound, so the `Category=Integration` cases run here — **nine** when this was written, **20 across six classes** as of 2026-09-13 (Agent 6, CaptureHost 7, Infrastructure 7); count them with `grep -rl 'Category", "Integration' tests` rather than trusting either number — and a green CI IS evidence for the managed drain and the capture host's end-to-end behaviour. The switch remains in `build.ps1`, loud, for a developer who must.
- **The hosted runner refuses guard scans intermittently — THREE failures in eight gate runs, measured
2026-09-10 while merging P2's stack.** Every one was an `Category=Integration` case, every one passed on
a re-run of the identical commit, and none was caused by the code under review. Two distinct shapes, and
the second is not §S19(b):
- `ShmDrainIntegrationTests.AnUnhookRequestStopsTheCaptureSideAndTheDrainCanSeeIt` at
`GuardedInjectAsync(...).IsAllowed` — the guard refusing our own harness, §S19(b)'s shape.
- `CaptureHostEndToEndTests.WhenTheTargetExitsTheHostStopsAndSaysWhy` with
**`ProcessTreeUnavailable — could not establish the scan set`**: the guard could not walk the
ancestors at all. That is a *different* failure from the fragment/signer one, and §S19(b) does not
cover it. A runner under load whose process enumeration fails is the obvious hypothesis and it is
**untested** — nobody has instrumented it.
So: §S19(b)'s refusal is **reduced, not gone**, and it is not the only way a scan fails here. The
earlier version of this bullet said "one run in the low tens", written after the first failure and
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.
- **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
this flake rate from the run history will measure zero. Read the job logs, or keep the tally as it
happens.
- ~~**The step that would diagnose it runs AFTER the thing it diagnoses, so a gate failure skips it.**
The signer probe below is step 8; the quality gate is step 7, and the job stops there. On the
2026-09-10 failure the probe therefore printed nothing, which is the one run where its output would
have named the refusing module. Moving it before the gate (or giving it `if: always()`) is a one-line
change nobody has made, recorded here rather than done quietly in an unrelated PR.~~ **FALSE when
written, corrected 2026-09-13.** The probe step has carried `if: always()` since #137 (`c5932cc`,
2026-09-06) — four days *before* the failure this bullet describes — so a red gate does not skip it.
Why the probe's output was not read on 2026-09-10 is therefore **unmeasured**: the run was re-run
(`gh run rerun --failed`, next bullet), which replaced its logs, so the original step output is gone.
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.
- **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
> step and there will not be one — the Khronos headers are vendored. `resx-audit` does not exist and
> is skipped loudly, so no artifact of it is uploaded. And the struct-mirror parenthesis — *"that
> step and there will not be one — the Khronos headers are vendored. `resx-audit` ~~does not exist and
> is skipped loudly, so no artifact of it is uploaded~~ (exists since 2026-09-13, P3 PR-2, as a hard step
> of the gate — red on a missing key, never an artifact; `12_BUILD` line 15). And the struct-mirror parenthesis — *"that
> gate does not exist and `build.ps1` skips it loudly"* — has been false since 2026-08-05:
> `build.ps1` implements it as a hard throwing gate that reads the run's `.trx` and fails when
> `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). 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`.
- **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` *(other than `{{RELEASE_DATE}}`, which `release.yml` substitutes — added 2026-10-04)*. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
- ~~`permissions: contents: read`.~~ `permissions: contents: read, pull-requests: read` — the second for the Changelog step's list of a pull request's files, read-only *(corrected 2026-10-04)*.
### `codeql.yml` — push, PR, weekly cron · **repo-local**
@@ -33,20 +93,63 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
- 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.
- `permissions: security-events: write, contents: read`.
### `release.yml` — on tag `v*` · **PLANNED, NOT PRESENT**
### `release.yml` — on tag `v*` · **repo-local, built 2026-09-14 (P4 PR-5)**
> `.github/workflows/` contains `ci.yml`, `codeql.yml` and `rules-publish.yml`. There is no release
> automation at all: the publish commands exist only as a fenced block in `12_BUILD` §Publish &
> package, and **nothing in this repository has ever run `dotnet publish`** — which is why
> `out/app`'s real contents had never been asserted by anything until
> `tools/package-closure-check.ps1` started walking the reference closure statically. Recorded
> 2026-08-06 rather than left describing a workflow that does not exist.
- Build + test (same script, native first) → publish App+Agent self-contained → ~~verify PresentMon SHA-256~~ *(retired 2026-08-27 — the console binary is not bundled; owner decision, `20_OPEN_QUESTIONS` §G)* → **verify VERSIONINFO present on `FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`** (identifiability is a safety requirement, `19_SAFETY`) → `vpk pack` → generate `SHA256SUMS.txt` → create GitHub Release with Velopack assets + checksums, release notes from `CHANGELOG.md` section.
- Optional final step: submit installer hash to VirusTotal and append the report link to release notes (helps unsigned-binary trust).
- `permissions: contents: write`.
> **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~~ (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.
### `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.
- `runs-on: windows-latest`, the same .NET / MSVC / clang-format pins as `ci.yml`, `permissions: contents: write`
(the Release API) and nothing else.
- **Version gate first.** The tag must be `vMAJOR.MINOR.PATCH[-prerelease]`; its numeric core must equal the
`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.
- `{{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~~ 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;
`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 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`~~ 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
@@ -70,7 +173,7 @@ 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`)
@@ -92,13 +195,28 @@ Central package management makes Dependabot PRs single-file diffs.
## Branch & release policy
- `main` protected: CI + CodeQL required, linear history, no direct pushes.
- Release: update `CHANGELOG.md` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest → 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; Velopack stable channel ignores them (explicit beta channel is v2 backlog).
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) *(corrected 2026-10-04: for a pre-release tag `vX.Y.Z-beta.N`, do not bump `VERSION` — it already holds the numeric core the gate compares, and it read `0.1.0` through eleven betas; the section is `## [X.Y.Z-beta.N] - date`, the full version. Bump `VERSION` only when the numeric core moves)* → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
- Pre-releases: `vX.Y.Z-beta.N` tags mark the GitHub release as pre-release; the App's `stable` channel ignores them and its `beta` channel (Settings ▸ Updates, `update.channel`) includes them — built with P4 PR-5, so ~~explicit beta channel is v2 backlog~~ is struck. The managed assemblies carry the full tag version; the native VERSIONINFO blocks carry the numeric core (`12_BUILD` §Version).
## Repo hygiene checklist (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
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly)
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
- [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)
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
+30 -8
View File
@@ -1,26 +1,27 @@
# 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.
## 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.
@@ -29,7 +30,7 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
### Golden metric tests (write first)
- Hand-computed fixtures: time-based avg (not mean-of-FPS), median, p99/p99.9 with **linear interpolation** (include cases where interpolation and nearest-rank differ), min/max, σ, stutter rule, sufficiency guards at 999/1,000 and 9,999/10,000 frames.
- FG ladder: records with API-sourced FG → `fg_source = api`; present-count delta only → `presentdelta`; ETW `FrameType` → `etw`; cadence ≥ 1.5 → `cadence`; ambiguous → `none`. Factor always = Displayed/Native regardless of rung.
- ~~FG ladder: records with API-sourced FG → `fg_source = api`; present-count delta only → `presentdelta`; ETW `FrameType` → `etw`; cadence ≥ 1.5 → `cadence`; ambiguous → `none`. Factor always = Displayed/Native regardless of rung.~~ **Rewritten 2026-09-09 (P2 PR-A), because two of its rungs no longer exist and its last clause was the affirmative negative `03_METRICS` forbids.** `presentdelta` was retired as structurally zero and `etw` with Tier 2 (2026-08-28); "ambiguous → `none`" is exactly what rung 0 exists to prevent. The goldens now are `03_METRICS` §Frame Generation's: `FL_MEASURED_FG_COUNTS` clear → `N/A`, never `none`; a counted ratio ≤ 1.05 over a uniform window → `none` (reachable by COUNTING only); 1.05–1.5 → refused; a saturated count (255) → refused; a non-uniform window → refused rather than averaged; DXGI-counted Displayed may stand in the trio and in `presents/batch` and never in a frame-time distribution. Each refusal is a `FgRefusalKind`, and `FgWindowTests` / `DxgiCountedWindowTests` drive every one.
- Upscaling: exact ratio from render/output pairs; **segment splitting** when resolution changes mid-stream; `settings_changed_midsession` flag; dominant-segment selection.
- RT: AS-builds-only stream (inline RayQuery case) → `rt = Yes` — the specific regression the old design got wrong; dispatch-only → `Yes`; RT-capable device with neither → `No`; D3D11 → `N/A`. PT confidence scoring never yields `Yes`.
- Tri-state precedence: `manual > measured > inherited > N/A`.
@@ -38,7 +39,7 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
### Parsers & infrastructure
- Shm reader against a synthetic mapping: version mismatch → refuse; torn records skipped; dropped counter propagated.
- ~~PresentMon CSV (Tier 2): header-map building with shuffled/unknown/missing columns, malformed lines, invariant decimal. Fixtures recorded from real runs.~~ **Removed 2026-08-27 with the tool.** Whatever Tier 2 ends up parsing needs its own row, written against the format it actually reads — and the lesson from the one parser that did get written is worth carrying: its CSV's first column was named `Application` while the value it counted was also `Application`, so resolving by NAME rather than position was load-bearing (`spike-notes` §11).
- Steam ACF (KeyValues), GOG `.info`, Epic `.item`, itch receipt — real-world fixtures.
- Steam ACF (KeyValues), GOG `.info`, Epic `.item`, itch receipt — real-world fixtures. **Since P4 PR-4 (2026-09-14):** the import's readers are driven by fixtures the tests write themselves (`ValveKeyValuesTests`, `StoreLibrarySourcesTests` — Steam's two-file shape across two library folders, GOG under a test HKCU key, Epic `.item` JSON, an itch receipt gzipped in the test), not by committed real-world files; a real-world corpus is still worth adding the day a launcher's format drifts.
- `RuleEvaluator`: fixture directory trees per engine, including the "Unity markers present but UE structure too" ordering case.
- 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.
@@ -50,12 +51,33 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
- Harness presents 120 s at a controlled cadence → Overlay injected → ring drained → session written → assert every aggregate against expected values.
- Harness simulates: resolution change mid-run (segments), stub upscaler exports (`upscaler` detection), RT PSO + dispatch (RT flags), AS builds without dispatch (inline RayQuery path), PSO compile spikes (stutter attribution), and a fault-triggering hook path (self-disable).
- `.partial` recovery: kill the Agent mid-capture, restart, assert `interrupted` session recovered.
**Built 2026-09-10 (P2 PR-G): `PartialRecoveryEndToEndTests`** — the shipped `FrameLedger.Agent.exe`
captures `hook-harness` with `--partial-flush-seconds 2`, the test polls until a flush has actually
landed (never a sleep), `Process.Kill`s the Agent, and then `--console recover` turns the valid prefix
into an `interrupted` row whose `frame_count` IS the prefix, deletes the file, and finds nothing on a
second pass. `PartialSessionFileTests` already kills at every byte offset; what this adds is that the
Agent wrote a recoverable prefix *on its own* before it died.
- **Test hygiene: the harness's overlay logs leave with the run.** The Overlay logs to the real
`%LOCALAPPDATA%\FrameLedger\logs` by design, so every test binary that starts hook-harness removes the logs it
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`.
- 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)
1. `hook-harness` in a fixed workload, present-rate uncapped: 3 runs hooked vs 3 unhooked → mean present-call cost delta must be ≤ 1 µs (measured with QPC around the call site in an instrumented harness build).
2. Real game, fixed 10-minute scene, capture ON vs OFF, 3 runs each: **game's own Avg FPS delta ≤ 0.5%**, Agent CPU ≤ 1% of a core, Agent RSS ≤ 150 MB, Overlay resident ≤ 8 MB.
> **NOT MEASURED. The runbook exists as of 2026-09-10 (P2 PR-G); the run is the owner's.**
> `tools/fps-impact-runbook.ps1` sequences the six launches, holds consent granted for the ON leg and
> 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 itself, prompts for the number only the operator can see (the game's own
> benchmark average), and prints the block for `spike-notes` §14. **It does not measure FPS and says so
> first:** FrameLedger's frame times exist only in the hooked leg, so they cannot be both sides of this
> comparison. Dev-only, never in `build.ps1 check` — it launches a real game. The harness-level
> per-present cost (item 1's neighbour) is P0's 8.4 ns in `spike-notes` §3, and is not this number.
> Until the run happens, the honest state of this line is *unmeasured*, not *passing*.
3. Results recorded in the release notes ("measured overhead this release: …").
## Tier cross-validation (accuracy regression net) — **GONE, 2026-08-28, and this is the entry to read before planning P5**
@@ -109,7 +131,7 @@ 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) |
| 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)* |
## Release smoke
+45 -13
View File
@@ -22,6 +22,11 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
>
> **Re-read 2026-09-04:** item 7 ✅ (the FG factor is measured, §S31 row P1), item 8's L2 half is written and measured (§M5 row R1), and exit criterion 1 reads **4 of 5** on Cyberpunk 2077 — the quality preset is the one value left, and `HANDOFF` item 7 carries the three things the next session does.
>
> **P0 CLOSED 2026-09-06 (owner).** Criterion 1 met with the quality preset amended to an
> honest `N/A` (`spike-notes` §Exit criteria carries why); criterion 2 met — §S24 counts zero
> S-items against it, with 🚫 S23-2 outside any PR. The measurement path this phase exists to
> prove runs end to end in an unshipped capture host, on nine titles. **P1 starts.**
>
> The 08-06 block below is kept and is now wrong in one specific clause — it says the writer
> *"records `measuredMask = FL_MEASURED_OUTPUT_RES | FL_MEASURED_PRESENT_ARGS` and nothing
> else"*. It records upscaler identity, upscaler params, frame-generation counts and ray
@@ -146,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
@@ -169,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
@@ -181,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
@@ -219,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.
>
@@ -244,8 +257,8 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> **Two things keep this ◐ rather than ✅:**
>
> - **The baseline side cannot be run.** This item's text says *"compare against what the
> item-3 baseline reports"*, and `StaticGameDetector` has **no runnable vehicle** — every
> construction of it is in `tests/`. So the comparison has one arm. `HANDOFF` item 5
> item-3 baseline reports"*, and `StaticGameDetector` ~~has **no runnable vehicle** — every
> construction of it is in `tests/`~~ *(has had one since P4 PR-1, 2026-09-14: the Agent's `DetectionSweep`)*. So the comparison has one arm. `HANDOFF` item 5
> records this as uncosted; this file had never said it at all.
> - **The README sentence does not exist**, and it is the artifact this item is for. It is
> **not a percentage** — item 3 and `spike-notes` §8 already record that the baseline
@@ -259,12 +272,12 @@ 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.)*
**Exit criteria:** a throwaway build records a real session from a real offline game reporting *correct* upscaler, quality preset, render→output resolution, FG factor and RT state — verified against the game's own settings menu.
**Exit criteria:** a throwaway build records a real session from a real offline game reporting *correct* upscaler, quality preset, render→output resolution, FG factor and RT state — verified against the game's own settings menu. *(Met 2026-09-06; the preset is an honest `N/A` by measurement — `spike-notes` §Exit criteria.)*
> **The FPS-impact criterion moves to the end of P1** (`20_OPEN_QUESTIONS` §R4,
> decided 2026-08-02). "Records a real session" with an Agent CPU/RSS budget
@@ -279,6 +292,25 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
## P1 — Native core (1.5 weeks)
`FrameLedger.Overlay` proper: hook installation for D3D11/12/9/OGL, feature hooks, ring writer, fault policy, unhook path, native logging. `FrameLedger.Injector` with launch + attach modes. Struct mirror + Catch2 tests. Vulkan layer to parity — `vkQueuePresentKHR` plus the in-layer supervision check §S2 gates on it.
> **P1 item 1 landed 2026-09-06: the `LoadLibrary` detour** (`kernelbase!LoadLibraryExW`; wake for lazily
> loaded runtimes + §S6's in-process anti-cheat stop, `FL_STATUS_STOPPED_BLOCKLISTED`), measured in
> ctest `fl_guard` `[loader]` / `[S6]`. Order for the rest, as proposed and accepted: **2** the Injector's
> launch mode (§S13(c), §S1's deferred input) — **landed 2026-09-06 as "inject late"**
> (`FlGuardedInjectWhenReady`, the CaptureHost `launch` verb, `dxgiPresentsBeforeHook` as the cost meter;
> `04_CAPTURE` §Launch mode); **3** the Vulkan layer to `vkQueuePresentKHR` with §S2's
> in-layer supervision and a harness Vulkan mode — **landed 2026-09-06** (`layer.cpp` capture side,
> `fl_shm_host.h` shared with the Overlay, `hook-harness --vulkan`, ctest `fl_vklayer*`, launch mode's
> `TargetIsVulkanLayered` branch; §S2 ✅, §S29(d)'s assertion now a ctest that skips on CI); **4** the
> unhook path, native logging, D3D9 / OpenGL — **landed 2026-09-06**: compare-and-restore per inline
> patch (`fl_patch_check.h`, ctest `fl_unhook_inline`), the native event ring flushed to
> `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`~~ (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.
> **The guard already shipped, in P0.** This line used to read "the guard,
> complete and fully tested — it ships before the first real injection, not
> after", which was the correct ordering stated in the wrong phase: P0 items 1
@@ -287,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.**
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)
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.
## 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; store auto-import; capability-vs-measured UI separation; i18n en/vi/ja; Legal Gate; Velopack + updater (with the hooked-session deferral); bug bundle incl. overlay logs; tray + toasts; Settings; DB maintenance; accessibility pass.
~~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; 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 — (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.
@@ -315,7 +347,7 @@ CI/CD with the native build; CodeQL (C# + C++); Dependabot; CHANGELOG; README wi
- Microsoft Store / Game Pass titles (packaged-app injection constraints)
- AFK segmentation via `GetLastInputInfo`
- GPU frame time via timestamp queries (needs care: injecting queries into the game's command lists is more invasive than anything in v1 — needs its own risk review)
- Beta update channel; ARM64
- ~~Beta update channel;~~ ARM64 *(struck 2026-10-04: the beta channel shipped with P4 PR-5 — `update.channel`, Settings ▸ Updates; `13_CI_CD` §Branch & release policy)*
## Permanently out of scope
+57 -10
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) |
@@ -57,10 +57,12 @@ private static readonly IHost _host = Host.CreateDefaultBuilder()
.Build();
```
**As built (P3 PR-2, 2026-09-13), three deviations from the sketch above:** `Host.CreateApplicationBuilder()` rather than `CreateDefaultBuilder`; `MainWindow` is **transient** (a language change rebuilds it in the new culture — `09_I18N` §Mechanics — and `Services.ShellHost` tracks the live one), so `App.xaml` sets `ShutdownMode="OnExplicitShutdown"` and the host's `IHostApplicationLifetime` is what ends the process (the shell host stops it when the live window closes; the old window of a rebuild closing is not an exit); and the run is one `Task` started from a synchronous `OnStartup` (`async void` overrides are VSTHRD100 under this repo's analyzers) that opens the ledger, starts the host, awaits its shutdown, tears down, and only then calls `Shutdown()`.
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.
- Persist the choice in `settings`; re-apply before the main window shows to avoid a flash.
- 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).
## Main window skeleton
@@ -79,7 +81,7 @@ Theme rules:
<RowDefinition Height="*"/> <!-- NavigationView -->
</Grid.RowDefinitions>
<ui:TitleBar Grid.Row="0" Title="FrameLedger" Icon="pack://application:,,,/Assets/icon.ico" />
<ui:TitleBar Grid.Row="0" Title="FrameLedger" /> <!-- no Icon: no icon file exists yet (corrected 2026-10-04) -->
<Menu Grid.Row="1"> <!-- classic menu, Fluent-restyled automatically --> </Menu>
@@ -101,7 +103,7 @@ Theme rules:
</ui:NavigationView>
<ui:SnackbarPresenter x:Name="SnackbarPresenter" Grid.Row="2" VerticalAlignment="Bottom" />
<ContentPresenter x:Name="DialogHost" Grid.Row="2" /> <!-- ContentDialogService host -->
<ui:ContentDialogHost x:Name="DialogHost" Grid.Row="2" /> <!-- §Dialogs; a ContentPresenter stood here until 2026-10-04 -->
</Grid>
</ui:FluentWindow>
```
@@ -142,13 +144,36 @@ 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.
- **`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.
- Exception to the no-hex rule: the chart palette — defined once per theme in ~~`Styles/ChartPalette.xaml` (two dictionaries)~~ `Styles/ChartPalette.Dark.xaml` and `ChartPalette.Light.xaml` (corrected 2026-10-04), never inline.
## FlowDocument (rendered documents, beta.12)
- **WPF UI 4.3.0 styles no `FlowDocument`.** Its own defaults are black Georgia on white, so a document in the dark theme
is unreadable unless the document is themed in code: `Markdown/MarkdownRenderer` sets `TextElement.Foreground` to
`TextFillColorPrimaryBrush` and `TextElement.FontFamily` to `ContentControlThemeFontFamily` **by resource reference**
(`SetResourceReference`, the code form of `DynamicResource`), a transparent background, and resource references for
every other colour (`AccentTextFillColorPrimaryBrush` links, `SubtleFillColorSecondaryBrush` code and table headers,
`ControlStrokeColorDefaultBrush` rules, quote bars and table borders). Never a literal brush.
- Host it in `Controls/MarkdownView` (a `FlowDocumentScrollViewer`, toolbar hidden) — not a `RichTextBox`, which is an
editor. A `Hyperlink` there does not navigate by itself: the view handles `RequestNavigate` and decides
(`Markdown/MarkdownLinks`).
- `AccentTextFillColorPrimaryBrush` is the light accent in the dark theme only after `ApplicationThemeManager.Apply(…,
updateAccent: true)` — measured 2026-10-03 in the test host, which skips it: links drew #003E92 on #202020 there and
#73C2FF once the accent was applied as `WpfThemeApplier` applies it.
## Custom controls (`FpsReadout`, `TriStateChip`, sparklines)
- Derive from `Control` with `ControlTemplate` in `Styles/FrameLedger.xaml`; template uses only theme brushes above → they re-theme for free.
- `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.
## Dialogs & notifications
@@ -166,8 +191,8 @@ 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).
- Rich in-flow dialogs: `IContentDialogService` (host wired in MainWindow).
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` ~~and ban the System one (BannedSymbols/analyzer note)~~ *(corrected 2026-10-04: nothing bans it. Three paths use the Win32 box on purpose — the crash dialog, the startup-failure dialog and the uninstall question — because they run when the shell's dialog host cannot be trusted. Use the WPF UI one everywhere else.)*
- Rich in-flow dialogs: `IContentDialogService` (host wired in MainWindow — a `ui:ContentDialogHost`, since 4.3.0 marks `SetDialogHost(ContentPresenter)` obsolete).
- Transient in-app: `ISnackbarService.Show(title, message, ControlAppearance.Success, new SymbolIcon(SymbolRegular.Checkmark24), TimeSpan.FromSeconds(4))`.
- System/tray notifications: H.NotifyIcon only (08_UI §Notifications policy).
@@ -175,14 +200,36 @@ var result = await box.ShowDialogAsync(); // Wpf.Ui.Controls.MessageBoxResult.Pr
On startup and on `ApplicationThemeManager.Changed`: for every live plot set figure/data background, axis/grid/tick colors, and series palette from the current theme resources (`ChartPalette.xaml`), then `Refresh()`. Centralize in `ChartTheme.Apply(Plot plot)` — pages never color plots ad hoc.
> **Built 2026-09-14 (P3 PR-6).** `Charts/ChartTheme.Apply(Plot)` + `ChartTheme.Attach(WpfPlot)` (weakly held; one
> subscription to `ApplicationThemeManager.Changed` re-applies and refreshes every live plot). The palette is
> **two** dictionaries, `Styles/ChartPalette.Dark.xaml` and `ChartPalette.Light.xaml`, `Color` resources with
> explicit ARGB hex — the one place hex is allowed — read into `Charts/ChartPalette` per theme and cached;
> `ChartPaletteTests` fails when the two files' key sets drift from what the record reads. Series colours come
> from the palette too (native, displayed, stutter, PSO stutter, sensors, segment span, histogram, percentile).
> 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.
## Gotchas checklist
- [ ] Dictionaries order: `ThemesDictionary` → `ControlsDictionary` → app styles. Wrong order = default-looking controls.
- [ ] `SystemThemeWatcher.Watch` after HWND exists (`Loaded`), not in the constructor.
- [ ] `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.
- [ ] Mica is Win 11-only: leave `WindowBackdropType="Mica"`; the library falls back on Win 10 — verify visuals in the Win 10 VM pass (14_TESTING matrix).
- [ ] VS Designer sometimes renders WPF UI controls unstyled at design time — judge by running, not the previewer.
- [ ] `TargetPageType` navigation requires the page registered in DI; a missing registration throws at runtime — smoke-test every nav item.
- [ ] resx localization unchanged: `Content="{x:Static res:Strings.Key}"` works on all WPF UI controls (09_I18N).
- [ ] MIT license copy for WPF UI ships in `legal/licenses/` (THIRD_PARTY_NOTICES checklist).
- [x] MIT license copy for WPF UI ships in `legal/licenses/` (THIRD_PARTY_NOTICES checklist) — ~~`wpfui-MIT.txt`, since 2026-09-14~~ `legal/licenses/nuget/WPF-UI.txt` since 2026-09-15, generated from the package's own LICENSE.md and carried into the published `licenses/`.
- [ ] **`ui:InfoBar` renders no Content in 4.3.0.** It is a `ContentControl`, the docs and the §Control mapping row
above both say "banner with an action button", and the library template has no `ContentPresenter` — so a
`ui:Button` written as the InfoBar's child compiles, binds, and is never drawn. With `IsClosable="False"` that is a
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.
- [ ] **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).
+165 -26
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
@@ -32,6 +32,41 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
1. Open/create shared memory `Local\FrameLedger.Ring.<pid>`; write the handshake header (layout version, build id, pid, api=unknown).
2. `MH_Initialize()`.
3. Resolve which graphics APIs are present (`GetModuleHandleW` on `d3d11.dll`, `d3d12.dll`, `dxgi.dll`, `opengl32.dll`) — and register a `LoadLibrary` hook so APIs loaded **later** still get hooked (many games load D3D12 lazily). **The `LoadLibrary` hook must not install hooks inline:** it runs under the loader lock, and MinHook suspends all threads to patch, which deadlocks against any thread waiting on that lock. It enqueues the request and signals the init thread, which installs outside the lock (`20_OPEN_QUESTIONS` §H2).
> **Built 2026-09-06 (P1 item 1), with two differences from the sentence above.** The detour is on
> `kernelbase.dll!LoadLibraryExW` — the one body every `LoadLibrary*` variant of `kernel32` reaches —
> and it is installed **after** the present hooks, from `InitThread`, outside any loader lock. It
> **enqueues nothing**: the module's real file name (`GetModuleFileNameW` on the handle the original
> returned, into a stack buffer — never the caller's string, which may be relative or an API set) is
> compared against two fixed tables and the detour then does one of two things, both a single store
> plus `SetEvent` on the watchdog's auto-reset wake event. **(a)** A name that is in `FL_HOOK_INVENTORY`
> or `FL_RUNTIME_CENSUS` bumps a saturating 15-bit wake count and wakes the watchdog, whose next
> iteration runs the same lazy installers it always ran — so the install happens on the watchdog
> thread, as before, but **within milliseconds of the module rather than on the next 1 Hz tick**
> (measured in ctest `fl_guard` `[loader]`: 94 ms from the module appearing to the hook family being
> published, against a 500 ms bound that discriminates the wake from the tick). **(b)** A name that
> matches a MODULE family of the compiled anti-cheat floor (`fl_ac_floor.generated.h`, the same table
> the guard carries — prefix, case-insensitive, allocation-free) records the family's 1-based index in
> `earlyStopFamily` and wakes the watchdog; the **present path** stops the Overlay on its next
> `MayObserve` and the **watchdog** stops it on its next iteration, whichever comes first, with the new
> status `FL_STATUS_STOPPED_BLOCKLISTED` (= 4) — `19_SAFETY` §During a session, the in-process half;
> `20_OPEN_QUESTIONS` §S6. The words are `FlWriterState.loaderSignals` @56 (bit 15 = installed, bits
> 0..14 = wake count) and `earlyStopFamily` @58, both carved from `reserved[]` so the layout version did
> not move. The original is always called first and its result returned untouched, and
> `LOAD_LIBRARY_AS_DATAFILE` / `_EXCLUSIVE` / `AS_IMAGE_RESOURCE` loads are skipped — no code runs from
> 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.
@@ -47,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
@@ -77,15 +112,18 @@ Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapCha
> restore-only-if-unchanged rule matters, since another overlay may have
> patched the same shared slot after us.
Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards); use MinHook inline hooks for flat C exports (`wglSwapBuffers`, NGX/FFX/XeSS entry points).
~~Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards);~~ *(corrected 2026-10-04: the Overlay swaps no vtable entry. It reads the slot off a throwaway object and MinHooks the function it points at, so one patch covers every instance (§Ray tracing); §Compare-and-restore explains why the swap is not the cleaner uninstall.)* Use MinHook inline hooks for flat C exports too (`wglSwapBuffers`, the Streamline and FidelityFX entry points ~~, NGX/FFX/XeSS~~ — NGX and XeSS have none).
## Hook inventory
Every hook must be listed here with a purpose. Anything not on this list is not allowed to exist (`19_SAFETY` review checklist).
> **This table is a SPECIFICATION. As of 2026-09-04 the Overlay installs TWELVE DETOURS —
> **This table is a SPECIFICATION. ~~As of 2026-09-04 the Overlay installs TWELVE DETOURS —
> the eight of 2026-09-03 plus four `ffxDispatch` trampolines, one per AMD module a game
> calls — and the FidelityFX row below is the ninth ✅.** The counts differed until 2026-09-03, because a
> calls — and the FidelityFX row below is the ninth ✅.~~** *(Corrected 2026-10-04: as of 2026-09-06 it installs up
> to SIXTEEN — the nine `FL_HOOK_INVENTORY` rows (four Streamline including `slSetTagForFrame`, four `ffxDispatch`,
> `ffxFsr3ContextDispatchUpscale`), the three DXGI slots, the two `ID3D12GraphicsCommandList4` methods,
> `wglSwapBuffers` and `LoadLibraryExW`; four hooks landed without this banner moving.)* The counts differed until 2026-09-03, because a
> row is a *capability* and a detour is a *patch*, and the FG-count row rode on the
> evaluate detour; it has its own now, `sl.interposer.dll!slGetNewFrameToken`. The AMD row
> is the opposite shape — **one row-family, four modules, four patches from one
@@ -108,7 +146,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`,
> ~~`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
@@ -126,6 +164,13 @@ 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~~ 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~~ 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
| Observation | Mechanism | Rule 4 | Why |
@@ -135,13 +180,13 @@ Every hook must be listed here with a purpose. Anything not on this list is not
### Presentation
| Hook | Purpose |
|---|---|
| ✅ `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 |
| ✅ `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 |
| ⏳ `IDXGISwapChain3::SetColorSpace1` | HDR output detection. **`IDXGISwapChain3`, not 4** — 4 adds only `SetHDRMetaData` (`20_OPEN_QUESTIONS` §H9). 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 |
| ~~⏳ `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` | OpenGL titles. Unbuilt, and deliberately not attempted before `hook-harness` has an OpenGL mode: the hook is small (a flat export, no vtable) but shipping an unexercised hook into a game process is not something this project does. Measured 2026-08-05: `opengl32!wglSwapBuffers` is a `jmp` thunk (`E9 <rel32>`) into the vendor ICD, which is already mapped before the first call |
| ⏳ Vulkan `vkQueuePresentKHR` | via layer, not hook (below). Unbuilt — P1, and §S2's in-layer supervision check lands with it. The layer today loads, gates and self-scans, and intercepts nothing |
| ✅ `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 |
| ✅ Vulkan `vkQueuePresentKHR` (2026-09-06, P1 item 3) | via layer, not hook (below). Frame boundary and QPC, one record per present; `vkCreateSwapchainKHR` / `vkDestroySwapchainKHR` intercepted beside it for the output size (`imageExtent`, the API's own argument — rule 4). **No `FL_MEASURED_PRESENT_ARGS`**: `vkQueuePresentKHR` carries no sync interval and no flags, which is why that bit exists. §S2's in-layer supervision check landed with it, on the present path. Measured under the real loader on the harness's `--vulkan` mode: 241 records in 4 s, status READY, `apiMask` = Vulkan (ctest `fl_vklayer_real`) |
### Upscaling / frame generation (the accuracy problem this rewrite exists to solve)
| Hook | Yields |
@@ -152,7 +197,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
| ✅ Streamline: `slSetTag` — **and, since 2026-09-05, every tag's TYPE** (`slTagCensus`; a HUD-less / UI tag marks the present `FL_FG_DLSS_G`, rule 4: the same argument) | The **global** resource tags, where a title states the size of the buffer it is upscaling *from*: `kBufferTypeScalingInputColor`'s extent → `renderW/H` — **or, since 2026-09-05, the size the tagged `sl::Resource` declares when the extent is zero** (`TagSize` in `fl_sl_inputs.h`, shared by all three tag routes; GUID-checked; a Resource declaring no size is still the honest unknown). **Built 2026-08-15** (`FL_HOOK_UPSCALER_PARAMS`), and it is an ALTERNATIVE to the local tags in `slEvaluateFeature`'s `inputs`, not a layer over them — `sl_core_api.h:258` says global and local tags "do NOT interact", so a title using one yields nothing from the other and both are read. Published only on a frame where an evaluation was also seen, because a tag is viewport state that outlives any one frame. This row was MISSING from this table while the hook shipped, which is the gap the banner above now names |
| ✅ Streamline: `slSetTagForFrame` — **and every tag's TYPE, as above** | The same global tags through **Streamline 2.8's frame-based entry point**, which deprecates `slSetTag`: `(const FrameToken&, const ViewportHandle&, const ResourceTag*, uint32_t, CommandBuffer*)` — the token first, then exactly `slSetTag`'s list, handed to the same tag walk. **Built 2026-09-04** (`FL_HOOK_UPSCALER_PARAMS`, its own trampoline; the family is now **published when whole** — once every tag export the loaded interposer has is patched — because publishing on the first row entitled records the second was not yet producing, 38 of 41 on the fixture: the ffx leaves' #110 defect again, fixed the same way). Measured need: Dying Light: The Beast (SL 2.8.0) published `Dlss` identity on every batch and the params bit on none across three captures, because a 2.8 title that tags per frame never calls the deprecated export. The token is not read; the frame count stays with `slGetNewFrameToken`. The installer picks this detour by SYMBOL (`kSymbolSlSetTagForFrame`, bound to the row by `static_assert`), not by family, since the two rows share a family bit and differ in signature |
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither) + one COUNT; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00 |
| XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute` | `outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG |
| ~~XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute`~~ **Closed at the census by licence, 2026-09-04** (`20_OPEN_QUESTIONS` §Scope decisions, `18_GPU_VENDOR_APIS` §Intel XeSS SDK): no hook on any `libxess*.dll` export *(corrected 2026-10-04)* | ~~`outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG~~ |
| ✅ **Application frames per present** (`fgEvaluations`) — **`sl.interposer.dll!slGetNewFrameToken` since 2026-09-03** | Native vs Displayed frame counts at Tier 1 — see `03_METRICS` §Frame Generation. **The producer is the frame-token export**: Streamline hands a title one token per application frame and the title must ask; the detour counts distinct tokens between two presents (pointer changes, nothing dereferenced), `FL_HOOK_FG_EVALUATIONS` is its family, and it installs on every Streamline 2 title including the ones that evaluate nothing through `slEvaluateFeature`. Rule 4: the out-parameter of an API we hooked. Premise and its gate in `03_METRICS`; pre-committed table in `20_OPEN_QUESTIONS` §S31. *The row as it stood before:* ~~NGX/SL/FFX/XeSS FG feature evaluations per present. **Built 2026-08-15 for Streamline, and MEASURED TO YIELD NOTHING ON THAT ROUTE**~~ — `slEvaluateFeature(kFeatureDLSS_G)` is never called by Cyberpunk 2077 (0 across ~14,000 batches, four FG settings), so this row installs, is honest, and counts zero; see `docs/HANDOFF.md` item 3. Built on the detour that was already there: `kFeatureDLSS_G` contributes to a saturating COUNT in the same word the feature bits live in (`fl_sl_seen.h`) rather than to a bit, because a bit collapses several evaluations between two presents into one — and under multi-frame generation that is the common case, not the edge. The row's family is therefore compound (`FL_HOOK_UPSCALER_IDENTITY \| FL_HOOK_FG_EVALUATIONS`), pinned by a `static_assert` because `hookinventory-check` reads that column as an opaque identifier. **Counts EVALUATIONS, not generated frames** — the 2026-08-14 owner ruling; the multiplier lives in `sl::DLSSGOptions`, which is only reachable by the route §2b refused. ~~Non-NVIDIA FG vendors are **deferred with a written rationale**: `amd_fidelityfx_framegeneration_dx12.dll` 3.1.5 exports only the five generic `ffx*` entry points, identical to five sibling modules, so identity is in the arguments and we have no headers~~ — **AMD has a producer since 2026-09-04** (the FidelityFX row above: the PREPARE dispatch's `frameID`, or the UPSCALE count on a title that never prepares, feeds `fgEvaluations` when Streamline has never issued a token); Intel stays at the census (`20_OPEN_QUESTIONS` §Scope decisions, by licence); the FSR 3.0 host DLL's UPSCALE (`ffxFsr3ContextDispatchUpscale`, since 2026-09-05) counts like an ffx-api UPSCALE when neither Streamline nor a PREPARE has spoken |
> `GetFrameStatistics().PresentCount` is **not** in this inventory and must not be
@@ -286,7 +331,7 @@ So:
### Memory / latency
| Hook / call | Yields |
|---|---|
| `IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread) | **Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact |
| ~~`IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread)~~ | ~~**Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact~~ **Never built; superseded 2026-10-03 (D43):** the game's memory is read from OUTSIDE the game by the Agent (`18_GPU_VENDOR_APIS` §The game process's memory), so nothing in the Overlay calls it. Only the budget would need it, and that stays open (`20_OPEN_QUESTIONS` §M11) |
| NVAPI Reflex: hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`; call `NvAPI_D3D_GetLatency` | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
### Explicitly not hooked
@@ -317,7 +362,9 @@ Vulkan gets an **implicit layer** (`FrameLedger.VkLayer`), not injection — it
DLL**, and it compares the variable's **value**, so a stray
`FRAMELEDGER_ENABLE_VK_LAYER=0` does not enable us. **This makes Vulkan
Tier 1 launch-mode-only** — the Agent sets the variable when it starts an
opted-in game, so a Vulkan title launched from Steam or GOG is not hooked.
opted-in game, so a Vulkan title launched from Steam or GOG is not ~~hooked~~ observed by the layer *(corrected
2026-10-04: attach mode has no Vulkan rule, so such a title gets the Overlay injected like a D3D one, and what its
DXGI hooks record there is unverified; `kTargetIsVulkanLayered` applies to launch mode only)*.
It is a *loading* gate, not a security gate: anything running as the user can
set the variable.
@@ -352,10 +399,45 @@ is not something this loader supports.
> admin. Registering under HKCU (below) is the less common choice and the better
> one: no elevation, and per-user scope.
- Intercepts `vkQueuePresentKHR`, `vkCreateSwapchainKHR`, `vkCmdTraceRaysKHR`, `vkCmdBuildAccelerationStructuresKHR`, `vkCreateGraphicsPipelines`.
> **Built 2026-09-06 (P1 item 3): the first two, plus `vkDestroySwapchainKHR`; the three feature entries are still ⏳.** How the capture side works, stated once:
> - **The ring is the same ring.** `fl_shm_host.h` (header-only, in `FrameLedger.Shm`) now holds the user-only DACL, the `Local\FrameLedger.Ring.<pid>` name, the mapping and the handshake for **both** capture sides; the Overlay calls it too. **One ring per process: whichever side creates the mapping first owns it, the other sees `ERROR_ALREADY_EXISTS` and stays inert** — and stays *forwarding*: the layer registers every device's next pointers before it tries the ring, because a hook with nothing to forward to failed the application's present (measured, `VK_ERROR_DEVICE_LOST` on the harness, the first time the Overlay got there first). That is also why the launch-mode guard **does not inject a presenter that mapped `vulkan-1.dll`** (`Reason::kTargetIsVulkanLayered`, `fl_guard.cpp`) — with or without a D3D runtime beside it, because **an NVIDIA Vulkan ICD maps `dxgi.dll` + `d3d12.dll` itself and presents the Vulkan swapchain through a DXGI flip chain** (measured on the harness's `--vulkan` mode: classified as D3D, the injected Overlay recorded 295 DXGI presents of a Vulkan swapchain and the layer forwarded into nothing). The layer is the capture side for anything that maps the Vulkan loader; a D3D title that happens to is the rarer shape and the one this rule gets wrong.
> - **It comes up at the first admitted `vkCreateDevice`**, never at load and never at `vkCreateInstance`, so a process either gate refused never has a mapping with its pid on it. Init is not a hook path; the present hook is, and it follows the Overlay's rules — SEH-guarded, allocation-free, lock-free, three faults → `SELF_DISABLED`.
> - **§S2 part three, the in-layer supervision, runs on the present path**, because the layer may not own a thread (the loader owns its mapping). `guardTicks` not advancing for `FL_GUARD_TICK_DEADLINE_MS` → `FL_STATUS_UNHOOKED`; `unhookRequested` → the same within one present; `pauseRequested` → no record, still forwarded. "Stops" means **passthrough forever with the reason on the mapping** — a layer cannot leave a running game's loader chain. A title that stops presenting is not stopped by the deadline, and has nothing to be observed either. Proven with a test-only flavour of the DLL whose deadline is 1.5 s (`fl_vklayer_shortdeadline`, never shipped; ctest `fl_vklayer_supervision`).
> - **No registry for the operator host.** Loader 1.4.357 honours `VK_ADD_IMPLICIT_LAYER_PATH` (measured 2026-09-06, `spike-notes` §2): the CaptureHost's `launch` writes a manifest under `%LOCALAPPDATA%\FrameLedger\vklayer`, points the launched process at it, sets the enable variable and adds the image name to the enable-list for the session — discoverable by that process alone, gone when it ends. The Agent's HKCU registration (`12_BUILD`) is unchanged and remains P2's.
- The layer respects the same guard, in two steps at init: it checks the enable-list, and it scans **its own process** against the anti-cheat blocklist. Either one saying no means fully passthrough. **A layer is machine-wide by nature — these checks are mandatory, not optional.**
- The self-scan uses the **same matcher and the same rules file as the injection guard** (`fl_ac_rules.h`, compiled into both targets). Not a copy: a layer with its own blocklist would be a second matcher that can disagree with the first. Every uncertainty — rules unreadable, malformed, enumeration failed, a truncated list — resolves to passthrough, which is the opposite polarity from the injection guard and the same principle: leave the host alone.
- Registered only while at least one Vulkan game has hooking enabled; unregistered on uninstall (Velopack hook) and when the last such game is disabled. **Never at install time** — `12_BUILD` §The Vulkan layer is not registered at install time.
> **Built 2026-09-14 (P3 PR-8b), as the repair tools and no more.** `Infrastructure.Vulkan.VkLayerRegistration`
> writes the one DWORD under `HKCU\SOFTWARE\Khronos\Vulkan\ImplicitLayers` named by the manifest's path
> (`%LOCALAPPDATA%\FrameLedger\vklayer\VkLayer_FRAMELEDGER_overlay.json`, written by the same code the launch
> path uses); the Agent's `--register-vklayer` refuses unless a game has hooking enabled, `--unregister-vklayer`
> also removes a stale value naming our manifest elsewhere, and `HelloAck.vulkanLayerRegistered` reads the key
> at the Agent's start. Two things this build does **not** do, stated rather than implied: ~~(1) the automatic
> register-on-first-enable / unregister-on-last-disable needs to know which enabled game is a *Vulkan* title,
> and the ledger does not hold that fact until P4's capability flags — so the check is "any enabled game"~~
> **— closed 2026-09-14 (P4 PR-2).** The fact is static and lives in `capability_flags` under the id `vulkan`:
> `GameFileProbe` reads the executable's import and delay-load tables (`Infrastructure.Detection.PeImports`, bounded,
> read-only) and looks for `vulkan-1.dll` as an ASCII or UTF-16 string in the bounded scan (a `LoadLibraryW`
> loader — the harness's shape and many titles'); null when the file could not be read, never "no". A static
> fact was chosen over the runtime one on purpose: the NVIDIA ICD maps `dxgi.dll` + `d3d12.dll` itself (the
> 2026-09-06 note above), so runtime module presence is the weaker discriminator, and the automation has to act
> at consent time, before the title ever runs. `Application.Vulkan.VkLayerReconciler` computes the desired
> registration from the ledger — hook-enabled games whose flags carry `vulkan` — and moves the HKCU value to it,
> called after every consent change the pipe handler and the console verbs make and after every detection
> sweep (so a guard block, the crash policy's auto-disable, and a Vulkan fact that arrives after the consent all
> converge within one 15 s interval). `--register-vklayer` runs the same reconciler and refuses when it finds no
> such game; the Settings button follows the same rule (`HookedGameViewModel.UsesVulkan`). Not staged = nothing
> to do — and **an Agent off the profile ledger (`--data-dir`) gets an inert registrar**, so the e2e suites'
> consent for `hook-harness` (which `LoadLibraryW`s the loader and therefore reads as Vulkan) never reaches the
> developer's HKCU (D17's shape). `VkLayerReconcilerTests`, `PeImportsTests` (a synthetic PE32+, both directories, the wide
> literal, a malformed file). (2)
> a registration buys nothing today: the layer gates on `FRAMELEDGER_ENABLE_VK_LAYER=1`, which only a launch
> sets, and a launch already reaches the layer through `VK_ADD_IMPLICIT_LAYER_PATH`. Registration becomes
> useful the day background capture sets the variable for a tracked Vulkan title started elsewhere, and not
> before; until then the Settings button and the flag reflect and repair a state nothing needs.
### The enable-list
Referenced everywhere, specified nowhere until now (`20_OPEN_QUESTIONS` §S4).
@@ -410,7 +492,9 @@ struct alignas(64) FlFrameRecord { // 64 bytes exactly, static_assert'd
uint8_t fgEvaluations; // @43 FG feature evaluations observed this frame
uint32_t vramUsedMb; // @44 MiB, matching vramBudgetMb
uint32_t reflexLatencyUs; // @48 0 = unavailable
uint32_t reserved; // @52 must be zero
uint8_t dxgiUnseen; // @52 DXGI-counted presents the hook did not see (2026-09-05; this listing
// showed a uint32 reserved here until 2026-10-04)
uint8_t reserved[3]; // @53..55 must be zero
uint32_t seq; // @56 seqlock counter (see 07_IPC §Protocol rules)
uint32_t swapchainId; // @60 which swapchain this present came through; 0 = unidentified
};
@@ -448,8 +532,9 @@ Field notes — each of these was a defect in an earlier revision:
uncomputable from a pinned counter. `rays_per_pixel` divides this by output
pixels.
- **`maxTraceRecursionDepth`** is the second of the four stated inputs to
`pt_confidence`. It is read at `CreateStateObject` (§Hook inventory) but
previously had no transport to the Agent and no column to land in.
`pt_confidence`. It ~~is~~ would be read at `CreateStateObject` (§Hook inventory) but
previously had no transport to the Agent and no column to land in. *(Corrected 2026-10-04: `CreateStateObject` is
not hooked, so nothing writes it yet.)*
- **`_pad0` and `_pad1` were explicit holes and are now carrying data.** Both were
named only so every offset could be asserted; spending them costs nothing,
because both bytes ranges were already inside the record and already written
@@ -484,14 +569,15 @@ Field notes — each of these was a defect in an earlier revision:
- **SPSC lock-free ring**, capacity a power of two (default 8192 records = 512 KB), overwrite-oldest.
- Writer/reader seqlock protocol, including the rule that the payload write must
**exclude** the `seq` field and that `seq` is never reset: `07_IPC` §Protocol rules.
- Header: three separate 64-byte lines before the ring — `FlShmHandshake` (write-once),
- Header: ~~three~~ **four** separate 64-byte lines before the ring *(corrected 2026-10-04: since layout 4, 2026-09-27,
beta.10, `FlDisplayState` at 0xC0 — Overlay-written at most every 500 ms; the ring starts at 0x100)* — `FlShmHandshake` (write-once),
`FlWriterState` (Overlay-written: `writeIndex`, `status`, `apiMask`, `faultCount`),
and `FlControlBlock` (**Agent**-written: `pauseRequested`, `unhookRequested`,
`overlayEnabled`, `guardTicks`). The control flags are *not* in the Overlay's
header — they are written by the other process, and mixing them into an
Overlay-written line reintroduces exactly the false sharing the split exists to
prevent. Layout is normative in `07_IPC` §A + B.
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present.
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present. *(Added 2026-10-04: the summary leaves out the per-present `IDXGISwapChain::GetLastPresentCount` call (§H5, the `dxgiUnseen` count) and the display sample every 500 ms at most (region 4).)*
- Per-frame mutable state (current upscaler, render res, dispatch counts) lives in a small struct updated by the feature hooks and *read* by the present hook; counters reset at present.
## The watchdog thread — the only thread we add to the game
@@ -500,6 +586,11 @@ One thread, started on the init thread *after* the hooks are installed, sleeping
`1000 ms` at a time. It evaluates `unhookRequested` and the `guardTicks` deadline,
calls `StopObserving` when either fires, and **exits** once stopped.
> **Corrected 2026-10-04 — this describes the thread as it was first written.** Since the lazy installers landed
> (`slEvaluateFeature`, 2026-08-09) the loop also installs feature hooks, runs the runtime census, publishes counters,
> appends the native log, and stops on the loader detour's early-stop family; it waits on that detour's wake event with
> a 1000 ms timeout rather than sleeping. `legal/DISCLAIMER.md` §2 says so to users since beta.12 (Disclaimer 2.10).
**Why it exists.** Both stops used to be evaluated only on the present path, and
`MayObserve` is reachable only from `RecordPresent`, which is reachable only from
the two present hooks. In a process that had stopped presenting — hung,
@@ -523,9 +614,12 @@ we do not own; the re-scan it would have run allocates ~1.15 MB transiently; and
it would have called `NtQuerySystemInformation` and probed the SCM from inside a
game, which is the behavioural signature of anti-analysis code (CLAUDE.md rule 3).
None applies to the Overlay, which is loaded by documented `LoadLibraryW` and is
never `FreeLibrary`'d from a live process. **This thread enumerates nothing,
never `FreeLibrary`'d from a live process. ~~**This thread enumerates nothing,
probes nothing and allocates nothing** — it reads two `uint32`s from our own
mapping and sleeps. That distinction is the whole justification and must survive
mapping and sleeps.~~ *(Corrected 2026-10-04: it enumerates no process, module list or service — the rule-3 line, which
holds — but it asks the loader for fixed module names, allocates through MinHook and, for ray tracing, creates one
command allocator and list on the game's own D3D12 device, and writes the log file. The justification below is
restated for that scope: what it must never start doing is scanning.)* That distinction is the whole justification and must survive
any future change: a watchdog that starts scanning is a different object under
rule 3.
@@ -547,13 +641,28 @@ 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.
## Unhooking
`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.
> **Built 2026-09-06 (P1 item 4) as compare-and-restore PER INLINE PATCH.** The Overlay swaps no vtable
> entries — every hook it installs is a MinHook inline patch on a function's first bytes — so the sentence
> below applies in its inline form: `StopObserving` walks a registry of every patch this DLL made (target,
> detour, name; filled by `PatchTarget` and the two direct sites) and calls `MH_DisableHook` on a target
> **only while the bytes there are still the jump MinHook wrote for us** — `fl_patch_check.h`
> `StillOurs`: `E9 rel32` → a `FF 25 00000000 <addr>` relay whose address is our detour, or the
> hot-patch `EB F9` form of the same. `MH_DisableHook(MH_ALL_HOOKS)`, which this replaced, wrote every
> saved prologue back without looking, and an overlay that patched the same function after us chains
> through our jump — that write would have removed their hook silently (§H7). A patch that is no longer
> ours is left in place, logged `UNHOOK_DECLINED`, and our detour stays in their chain forwarding (every
> body consults `g_observing`). Proven both directions against a real MinHook patch and a simulated
> foreign one in ctest `fl_unhook_inline` (the vtable form stays in `fl_unhook_preserves_foreign`), and
> 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.~~ *(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
@@ -590,9 +699,39 @@ compare-and-restore that never restores is not a fix.
No logging in hook bodies. A small fixed-size in-memory ring of structured events (hook installed, symbol missing, fault, unhook) is flushed to `logs\overlay-<pid>-*.log` by the init thread at session end, on unhook, or on Agent request — never mid-frame.
> **Built 2026-09-06 (P1 item 4), as specified, with the details a bug report needs.** A ring of 256 ×
> 64-byte events (`qpc`, code, two operands, a 40-char name) appended with one `fetch_add` from init and
> watchdog paths and from a hook's **SEH handler** — `NoteFault` records the exception code and the hook's
> `__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
> 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`,
> 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
> (`Consume/OverlayLog.cs`).
> **Tests and the real logs folder (2026-09-15).** The injection tests use the shipped Overlay, so their harness
> logs land in the user's real `logs\` too: measured that day, 2506 overlay logs, **2492 of them hook-harness's**,
> left by test runs since 2026-09-06, beside the owner's 14 from real titles. **The path stays not-a-parameter**: an
> environment variable or any other switch in the injected DLL would reopen the per-launch vector §S21 closed, and a
> test build of the Overlay would stop testing the binary that ships. Instead **each test binary removes what it
> caused** when its run ends: an `overlay-*.log` created after the run started whose first line names a hook-harness
> image that binary owns. Natively a Catch2 listener in `guard_test.cpp` over `src/native/tests/overlay_log_sweep.h` (the image
> must be this build's `FL_HARNESS_EXE`); in managed code `tests/Shared/HarnessOverlayLogSweep.cs`, an xUnit assembly
> fixture that `FrameLedger.DrainFixtures.targets` compiles into every test project staging the harness (the copy
> beside the test binary, plus directories a test registers — `PipeEndToEndTests` runs a renamed copy from its
> scratch directory). Test assemblies run in parallel with their own copies, so none removes a log another is about
> to read; a game's log names the game. **`tools/test-artifacts-check.ps1` makes a missing sweep red**: a harness log
> created during the gate and still there fails it. The logs from before this change are the owner's to delete.
## 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:
@@ -600,8 +739,8 @@ verification a dev-machine-only affair before:
- **WARP** (`D3D_DRIVER_TYPE_WARP`) — a software rasteriser, so no adapter is required.
- **`CreateSwapChainForComposition`** — no `HWND`, so no dependency on a window station or an interactive session.
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**.
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).
+164 -28
View File
@@ -33,25 +33,83 @@ public interface IGpuTelemetrySource : IDisposable
Implementations compose rather than compete:
- `BaselineTelemetrySource` (L1) — always constructed.
- `LhmTelemetrySource` (L2) — constructed when LHM initialises.
- `NvapiTelemetrySource` (L3) — constructed only on NVIDIA hardware.
- `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.
`GpuSample`: `takenAt`, `layer`, `adapterName`, `tempCoreC`, `tempHotspotC`, `tempMemoryC`, `loadPct`, `vramAdapterMB`, `coreClockMhz`, `memClockMhz`, `powerW`, `fanRpm`, `throttleReasons`, `pcieGen/Width`. Every field nullable — `Capabilities` says what to trust, and the UI shows `N/A` rather than zero.
`sessions.telemetry_source` stores the **composite descriptor** (e.g. `l1+lhm+nvapi`), not a single name, so a user can see exactly why a field is missing.
> 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.
> **Written 2026-09-09 (P2 PR-E1): `BaselineTelemetrySource` (L1), `CompositeTelemetrySource`
> and the 1 Hz thread (`TelemetryPoller`, `fl-telemetry`).** Three things this block did not say
> and the code now does. (1) The port gained `IsDisabled`: a layer that has fallen to
> `Capabilities.None` because it was disabled and one that has simply not read yet were
> indistinguishable through the port, and the **descriptor lists the layers still standing**
> — `TelemetryLayerNames.Describe`, lowest first — so a layer disabled mid-session drops out of
> the string the session is stored under. (2) The composite is **not a layer**: its `Layer` is
> `None`, a merged sample's `Layer` is the highest layer that contributed anything, and
> `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.~~ *(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.)* 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.~~
> **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.
- **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.
- **Driver version:** `SetupAPI` / registry adapter properties. Feeds the hardware snapshot and the trend-chart change markers (`06_DATA_MODEL`).
> **Built 2026-09-09 (PR-E1), one counter of the three:** `PdhAdapterMemoryCounter` binds
> `\GPU Adapter Memory(luid_0x<High>_0x<Low>_phys_0)\Dedicated Usage` by the selected
> adapter's LUID — addressed directly, never a wildcard summed — and it is L1's one live field
> (`GpuSample.VramAdapterMb`). Measured on the dev box: **1301 MB** in use on the RTX 5080 at an
> 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.~~ **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.
> **🅓 The two-OS requirement is deferred to Win 11 only — owner decision, 2026-08-05.**
@@ -79,13 +137,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.
@@ -96,16 +172,64 @@ CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, an
Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be absent (no NVIDIA GPU) or older than our headers. `NvAPI_Initialize` failing is a normal condition that must disable L3 cleanly, not throw.
> **Built 2026-09-10 (P2 PR-E2).** NVAPI is a C API behind a static import library, so the managed
> side reaches it through a native DLL of our own: **`FrameLedger.NvapiBridge.dll`**
> (`src/native/FrameLedger.NvapiBridge/`, C ABI in `include/fl_nvapi_bridge.h`) — the **only shipped
> binary that links `nvapi64.lib`**, read-only by construction (every export is a query), loaded by the
> Agent into **its own process** by absolute path and **never into a game**. Its name carries none of
> the words the guard's §S18 heuristic scans a launcher's ancestors for. The ABI is a fixed struct with
> a `present` bitmask per field (`FlNvReadSample`), a refcounted `FlNvInit` / `FlNvShutdown`, the driver
> version, the per-pid NGX words (`FlNvNgxState`), and size / ABI-version / build-id queries so a mirror
> that drifts is refused (`FL_NV_BAD_SIZE`) rather than read. On the managed side, all in
> `Infrastructure.Telemetry`: `NativeNvapiBridge` (the second P/Invoke facade after the guard's — same
> absolute-path rule, through the assembly's one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`,
> because the runtime allows exactly one per assembly and two static constructors setting one is an
> exception in whichever runs second), `NvapiTelemetrySource` (a clear bit is `null`, never 0; an
> `Init` that does not answer 0 disables the layer with **zero faults**, because a machine without the
> driver is a normal condition; two throws disable it for the session), and `NvapiNgxStateProbe`
> (`INgxDriverProbe` in-process — the capture host **no longer spawns `fl-probe-nvapi.exe`**, and the
> probe target is no longer staged beside it). Verified by ctest `fl_nvapi_bridge`
> (`src/native/tests/nvapi_bridge_test.cpp`, `BRANCH: AVAILABLE|DEGRADED` required the way
> `fl_nvapi_probe` requires it) and by `NvapiBridgeMirrorTests`, which compares `Marshal.SizeOf` of both
> mirrors against the DLL's own answers and **fails rather than skips** when the DLL is not staged.
>
> **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 |
|---|---|
| Init / enumerate | `NvAPI_Initialize`, `NvAPI_EnumPhysicalGPUs`, `NvAPI_GPU_GetFullName` |
| Temperatures | `NvAPI_GPU_GetThermalSettings` (+ extended thermal query for hotspot/memory where available) |
| Utilisation | `NvAPI_GPU_GetDynamicPstatesInfoEx` (GPU / FB / VID / BUS domains) |
| Clocks | `NvAPI_GPU_GetAllClockFrequencies` |
| 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 |
| **Throttle reasons** | `NvAPI_GPU_GetPerfDecreaseInfo` — not available from L1 or L2 |
| Driver version | `NvAPI_SYS_GetDriverAndBranchVersion` |
| **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. 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) |
| Temperatures | `NvAPI_GPU_GetThermalSettings` (+ extended thermal query for hotspot/memory where available). **Bridge (2026-09-10):** the public enumeration only — core is the `GPU` target; memory is the `MEMORY` target when the driver lists one, and on the RTX 5080 it does not (bit clear → `null`); hotspot is not read |
| Utilisation | `NvAPI_GPU_GetDynamicPstatesInfoEx` (GPU / FB / VID / BUS domains). **Bridge (2026-09-10):** the GPU domain only, as `loadPct` |
| Clocks | `NvAPI_GPU_GetAllClockFrequencies` — **bridge (2026-09-10):** current graphics and memory clocks |
| 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) |
| **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.
@@ -199,7 +323,11 @@ refused the same day (delegated by the owner, decided 2026-09-04).** It declares
reads no argument, but installing it inline-patches Intel's code inside the game process, and
the same licence forbids *"any modification"*; the census is the answer NGX got and Intel gets
the same one. Reversal condition: Intel publishing the headers under a licence that clears the
checklist, at which point this paragraph is re-run, not argued around.
checklist, at which point this paragraph is re-run, not argued around. **Re-run 2026-09-06 against
<https://raw.githubusercontent.com/intel/xess/main/LICENSE.txt> and `inc/xess/xess.h`: unchanged** —
the same licence, the same three needles, the same header banner. Not fired. Intel's README does
state that XeSS-FG runs on *"non-Intel GPUs with SM 6.4 support"*, so an XeFG session is measurable
on the NVIDIA dev box even though nothing in it may be hooked or declared.
### Checklist before adding any vendor SDK
@@ -212,7 +340,7 @@ checklist, at which point this paragraph is re-run, not argued around.
- 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)
@@ -240,10 +368,10 @@ as the same thing.
| Field | NVIDIA | AMD | Intel |
|---|---|---|---|
| GPU utilisation | ? | untested | untested |
| Adapter VRAM | ? | untested | untested |
| Per-process VRAM | ? (also from Overlay) | untested | untested |
| Driver version | ? | untested | untested |
| 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~~ ✓ **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 |
| Fan | ? (D3DKMT probe) | untested | untested |
@@ -281,19 +409,24 @@ answer; the `untested` cells are exactly as untested as before.
| Field | NVIDIA | AMD | Intel |
|---|---|---|---|
| **Initialises at all** | ✓ **measured 2026-08-05** | `arch` | `arch` |
| **Driver version** | ✓ **measured** — `610.88`, branch `r610_85` | `arch` | `arch` |
| **Driver version** | ✓ **measured** — `610.88`, branch `r610_85`; **through the bridge 2026-09-10:** `616.64`, `r616_41` | `arch` | `arch` |
| **GPU enumeration + name** | ✓ **measured** — 1 GPU, "NVIDIA GeForce RTX 5080" | `arch` | `arch` |
| **Degrades cleanly when absent** | ✓ **measured** — see below | `arch` | `arch` |
| Core / hotspot / memory temp | ? | `arch` | `arch` |
| Per-domain utilisation | ? | `arch` | `arch` |
| Clocks, Power | ? | `arch` | `arch` |
| Throttle reasons | ? | `arch` | `arch` |
| Reflex / PC latency | ? | `arch` | `arch` |
| Core / hotspot / memory temp | **core ✓ measured 2026-09-10** — 35 °C at an idle desktop; **memory: bit clear** on this GPU (no `MEMORY` thermal target enumerated → `null`, not 0); hotspot not read | `arch` | `arch` |
| Per-domain utilisation | **GPU domain ✓ measured 2026-09-10** — 0 % at an idle desktop, present bit set (a measured zero); FB / VID / BUS not read | `arch` | `arch` |
| Clocks, Power | **clocks ✓ measured 2026-09-10** — 2670 MHz graphics, 15001 MHz memory; power not read | `arch` | `arch` |
| Throttle reasons | ✓ **measured 2026-09-10** — mask 0 at an idle desktop, present bit set | `arch` | `arch` |
| Fan | **bit clear at an idle desktop 2026-09-10** — the tach reading is refused while the fans are stopped, and the bridge reports that as absent rather than 0 RPM; a reading under load is the owner's to take | `arch` | `arch` |
| PCIe width | ✓ **measured 2026-09-10** — ×16; generation not read | `arch` | `arch` |
| Reflex / PC latency | not a poller field (§M8) | `arch` | `arch` |
The four measured rows come from `ctest fl_nvapi_probe` (`src/native/tools/fl-probe-nvapi`),
which exists because vendoring added 2.4 MB of headers and an import library that **nothing
else compiles against yet** — an unconsumed vendored dependency is one whose header closure
could be short by a file with every gate still green.
could be short by a file with every gate still green. **The 2026-09-10 rows** come from one
`FlNvReadSample` through `FrameLedger.NvapiBridge.dll` on the dev box (RTX 5080, driver 616.64),
read from the staged DLL by hand after `NvapiBridgeMirrorTests` had passed against it; the
bridge is the second consumer of the vendored material and the first that ships.
**"Degrades cleanly when absent" — what is observed, and what is inferred.** `nvapi64.lib`
is a *static* library of stubs that reach `nvapi64.dll` through `nvapi_QueryInterface` at
@@ -346,6 +479,9 @@ alone could never catch.
> The NVIDIA half is **not** deferred and ~~none of it exists in code yet — no PDH, no
> DXGI telemetry, no LibreHardwareMonitor, no NVAPI~~ — **L2 exists as of 2026-09-03**
> (`LhmTelemetrySource`, `SensorMap`, the port in `FrameLedger.Application.Telemetry`);
> L1 and L3 are still unwritten. §M5 in particular (do LHM GPU
> ~~L1 and L3 are still unwritten~~ **L1 and the composite exist as of 2026-09-09**
> (`BaselineTelemetrySource`, `DxgiAdapters`, `PdhAdapterMemoryCounter`,
> `CompositeTelemetrySource`, `TelemetryPoller`); ~~L3 is P2's PR-E2~~ **L3 exists as of 2026-09-10**
> (`NvapiTelemetrySource` over `FrameLedger.NvapiBridge.dll`, §L3). §M5 in particular (do LHM GPU
> sensors work unelevated, without PawnIO?) decided whether the default unelevated
> Agent has temperatures at all — **it does, on NVIDIA; row R1 above.**
+489 -42
View File
@@ -18,7 +18,7 @@ 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
@@ -50,6 +50,13 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> against a suspended target (§S1). Neither is "no modules found". The read
> handle rights above are confirmed sufficient for every target this call can
> legitimately reach.
>
> **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
> matches nothing against the blocklist, and the injection happens only after check 1 has run in
> full, with the enumeration succeeding, exactly as in attach mode. A launched target that never
> becomes scannable is never injected (`LaunchNoPresentationRuntime`).
> **Which processes get scanned: the game's own subtree.** `04_CAPTURE`
> §The guard writes `Check(pid)` — singular — while `04_CAPTURE` §Process
> watcher says the capture target is a *descendant* elected from a ppid
@@ -210,8 +217,47 @@ 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 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).
> 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
@@ -243,6 +289,23 @@ 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
> **depth 3** — raised from 2 on 2026-08-04 (§S22, `spike-notes.md` §13), because a
@@ -255,7 +318,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.
@@ -264,9 +327,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
@@ -290,7 +355,8 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> **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
@@ -304,7 +370,7 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> 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
@@ -341,7 +407,176 @@ 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).
### 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.)*
**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 — 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
@@ -415,32 +650,109 @@ 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 | `drivers` | exact | `ACE-BASE.sys`, `ACE-ADVT.sys`, `ACE-GAME.sys` — **machine-wide refusal** (check 2) | seed |
| Anti-Cheat Expert | `directories` | name | `AntiCheatExpert`, `AceAntibotClient` | 2026-09-25 |
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service` | seed |
| Anti-Cheat Expert | `files` | name | `PGameProtectDriver_X64.sys`, `SGuard64.exe`, `SGuardSvc64.exe` | seed; `SGuard64.exe`, `SGuardSvc64.exe` 2026-09-25 |
| 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`
@@ -467,7 +779,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
@@ -502,6 +814,23 @@ the entire driver stack read as untrusted, and combined with the `guard` and
theoretical one. A signature that is absent, invalid, or simply could not be
checked stays untrusted and refuses — that direction is deliberate.
> **Wired 2026-09-06, the EMBEDDED half only, under a compiled-in bound** (`20_OPEN_QUESTIONS`
> §S19(b), row G1: the CI leg and the owner's adapters-disabled leg both left every verdict
> unchanged). `Sources::ModuleSignerOrganisation` verifies a fragment-matching module's embedded
> Authenticode signature with `WinVerifyTrust` under `WTD_REVOKE_NONE | WTD_CACHE_ONLY_URL_RETRIEVAL`
> — no CRL or OCSP fetch, measured rather than assumed — and only then reads the subject `O=`. The
> guard trusts it only if the organisation is on the rules file's `trustedSigners` **and** on the list
> compiled into the binary (`IsCompiledTrustedSigner`): the rules file may narrow that list and may
> never widen it, so a rules push cannot widen the hard gate — the boundary of what the gate trusts is
> code, as it is for the launcher list. A trusted module keeps the scan looking; it never stops it, so
> an untrusted module loaded after it is still judged. It applies to the injection target as well as
> to its ancestors — a game that loads a Microsoft-signed key-protection provider is the false refusal
> this half exists to remove. **Fail-closed rows:** no embedded signature (catalog-only system
> binaries such as `mskeyprotect.dll` — the `CryptCATAdmin*` half is deferred with its own rationale),
> an invalid signature, an unreadable `O=`, a null path, a null or failing seam, an organisation on
> one list but not the other — every one is untrusted and refuses. Cost: ~2–4 ms per verified module,
> reached only on a fragment hit, inside the 30 s loop.
### During a session
Re-run **every pre-injection check** every 30 s, for **every Tier-1 session —
@@ -561,12 +890,46 @@ injected or layered**.
**Be honest about the window.** A 30 s poll means anti-cheat can be loaded for up to 30 s before we react — the unhook is immediate *once detected*, not immediate in absolute terms. Consent and disclaimer wording must say "within 30 seconds", never "immediately" (`legal/DISCLAIMER.md` §2). Whether to shrink the window, or to detect the load directly via the `LoadLibrary` hook `17_HOOK_ENGINE` §DLL entry **specifies** for lazily-loaded graphics DLLs, is `20_OPEN_QUESTIONS` §S6.
> **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.
> **The in-process half exists since 2026-09-06 (P1 item 1), and the sentence above stays true because
> of what it does NOT cover.** The Overlay's `LoadLibrary` detour compares every module the loader maps
> mid-session against the **compiled floor's MODULE families — the exact prefix names, and nothing
> else** — and stops the Overlay from inside on a match (`FL_STATUS_STOPPED_BLOCKLISTED`; `17_HOOK_ENGINE`
> §DLL entry step 3), within one present or one watchdog iteration. That is the same set the Agent's
> guard matches by name. **The fragment tier and the signer tier are not in the detour**, on purpose: a
> substring scan is not allocation-free in a hook body under the loader lock, and `WinVerifyTrust` from
> inside a game process is out of the question — so a module the floor knows only by a fragment, or only
> by its signer, is still caught by **this host's 30 s scan and by nothing sooner**. The disclosure
> therefore does not change: "within 30 seconds" remains the promise; the exact-name case is now usually
> much faster, and the report says which happened (`EARLY STOP` naming the family, or the host's own
> 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. *(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:
@@ -601,7 +964,89 @@ Enabling hooking is a **per-game** action, gated by a one-time dialog per game t
Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, never supplied by a client** (`07_IPC` §The pipe is not a trust boundary). Wording lives in `.resx` and is reviewed with the same care as the legal documents.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game.
> **Built 2026-09-13 (P3 PR-4).** The dialog is `FrameLedger.App`'s `ConsentPrompt` over WPF UI's `ContentDialog`,
> its text `FrameLedger.Shared`'s `Safety_Consent_*` family and nothing else: the intro (which says it recommends
> 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
> 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
> language): the Agent's `HelloAck` names the version it stamps against, the App **does not open the dialog**
> when it differs from its own (D14 — it says "restart both"), the App sends the version it showed, and the
> Agent's `SetHookEnabled` handler re-runs the pre-scan, compares the version to its own, and stamps
> `ConsentProvenance.ConsentDialog` from its own clock or answers `Error DisclosureVersionMismatch` with
> nothing written. `HookingConsentTests` (App), `AgentCommandHandlerTests` (Agent side) and
> `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.
> **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
> Agent's own clock — the property a file store could not uphold. It is still **not FR-2.1's dialog**, and its
> text says so first; ~~P3's dialog retires it~~ **P3 PR-4's dialog (2026-09-13, above) is the user path; the verb
> stays as the developer path it always said it was** — its provenance value stays distinguishable in the row.
> **FR-2.4's kill switch is built the same day as the FOURTH input
> of `HookedCaptureGate`** (decision D7): `settings.hooking.kill_switch = 1` refuses every game with
> `KillSwitchEngaged` before consent is read, stops a running session at its next guard-scan boundary by
> publishing `unhookRequested`, and keeps the Vulkan layer off by never setting `FRAMELEDGER_ENABLE_VK_LAYER`
> on a launch.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection). *(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
@@ -619,20 +1064,22 @@ 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).*
- 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
+476 -45
View File
@@ -23,12 +23,42 @@ Rules for this document:
## Scope decisions already taken (recorded, not open)
> **2026-09-21 — the guard gained one override, by owner decision, and it reverses a sentence this project wrote in
> several places.** CLAUDE.md rule 2 said "There is no override switch ... Do not add one"; `19_SAFETY` said "There is no
> override"; `HookingConsentOutcome` said so in a doc comment. The owner asked for a per-game "bypass the guard" mode at
> the user's own risk, behind a warning the user must accept first, and chose the per-game form over a global switch and
> over one that kept kernel anti-cheat refused. It is built as `19_SAFETY` §The user's bypass specifies: per game, off by
> default, its own two-act disclosure, stamped by the Agent, overruling the guard's JUDGEMENT only, never changing HOW
> FrameLedger injects (rule 3), and marking every session it starts. **What stays open, and is the owner's:** whether a
> shipped build should offer it for the kernel-level families at all (the rules file has no severity and may not grow
> one, so that would be a code list); and the ja text, which ships as English until a reviewer signs. **Pre-committed
> withdrawal:** an injection reached under it without the disclosure having been shown, or a session under it that is
> not marked, removes the switch from the App in the next release.
>
> **2026-09-22 — withdrawn by the owner, for a reason the pre-commitment did not list.** Its first real use (ELDEN
> RING under Easy Anti-Cheat) reached `TargetUnreadable`: the switch could not do anything where it was wanted, and
> where it could inject it only exposed the user. The owner asked for the opposite: a finding turns the game's hooking
> off, wherever the guard makes it. `19_SAFETY` §What a finding does to the game is the specification; CLAUDE.md rule 2 is
> unstruck. The two open items above (kernel-level families, the ja text) are moot.
>
> **2026-09-26 — one narrow exception, by owner decision D33, with the 2026-09-22 withdrawal quoted back.** Beta.8's
> library sweep blocked a game FrameLedger had measured hooked (GIRLS' FRONTLINE 2: EXILIUM, NetEase Yidun `NEP2.dll`),
> and the owner chose an evidence-bound, per-game exception for anti-cheat that is user-mode throughout (`19_SAFETY`
> §The user-mode exception; CLAUDE.md rule 2's amendment). The two reasons D22 gave are answered: it is offered only
> where FrameLedger has already measured the game hooked, and its risk is stated in its own disclosure. *(2026-10-03,
> D38: the first of the two no longer holds as written — a game blocked at add time could never be measured, so the
> measurement moved under the grant as a two-session trial whose failure is for good.)* **What stays
> open, and is the owner's:** the `ja` text of `Safety_Exception_*`, which ships as English until a reviewer signs;
> whether a family the rules file makes kernel-level later should end existing exceptions at once (today it does, at
> the sweep's next pass and at every session start); and a real-hardware check that NEP2.dll's load time relative to
> the injection is covered on the owner's machine (the ctest decoy covers the late load).
| # | Decision | Consequence |
|---|---|---|
| — | **D3D9 is not a Tier-1 API in v1.** The Overlay is x64-only; an x64 DLL cannot load into a 32-bit process, and D3D9 titles are almost entirely 32-bit | **The consequence hardened on 2026-08-28 without a word of this row changing**, which is why it is called out: that catalogue used to be "Tier 2", meaning frame times without injection. Tier 2 now measures nothing, so those titles are **unmeasurable in v1**. The VN / JRPG / older-indie catalogue is Tier 2. Reversing this means a second 32-bit Overlay **and** injector, doubling the native build matrix and adding a second struct-mirror surface. Revisit only with evidence that users care more about those titles than about the maintenance cost |
| — | **`ci.yml` is repo-local**, not a caller stub | The ops repo's `reusable-desktop-csharp.yml` runs `dotnet` directly with no native pre-step input, and `12_BUILD` requires CI and local to run the same script |
| — | **No `v1 → v2` migration** | Nothing shipped, so no such database exists. `0001_init.sql` creates the current schema |
| — | ~~**Multi-process titles are refused as `TargetAmbiguous` in v1**~~ — **the Chromium case is RESOLVED the same day (2026-09-03), by the vendor's own label** | Chromium-based runtimes — NW.js, Electron, RPG Maker MV/MZ, a large share of the VN catalogue — run several processes from ONE image path (browser, renderer, GPU), and *Flower in Us* refused as `TargetAmbiguous`. The presenting process is Chromium's GPU process, which owns no window, so "the one with the window" and "the parent" were both wrong picks. **What resolves it:** Chromium marks that process with `--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — **served by the kernel, no `ReadProcessMemory`, no PEB walk, `PROCESS_QUERY_LIMITED_INFORMATION` only**, which is the rule-4 line `HeldProcessHandle` already draws — and resolves only when **exactly one** readable candidate carries the flag as a whole argument. Two GPU processes (two instances), none, or any unreadable candidate still refuse. §S27 is untouched: consent is keyed on the path, every candidate is that path, the guard scans the pid chosen, and `--pid` stays forbidden. **Measured the same evening, and the first rule did not fire:** *Flower in Us* runs **six** processes — browser, `crashpad-handler`, three `utility`, `renderer` — and **no `--type=gpu-process` at all**. NW.js runs the GPU **in-process, in the browser**, which is the one process Chromium leaves untyped. Second rule added: exactly one untyped candidate, every other candidate typed, no GPU process ⇒ the browser is the target; two untyped candidates are two instances and refuse. The refusal line now prints the tree (`browser=1, renderer=1, utility=3, …`) so the next unknown shape is data rather than a bare `TargetAmbiguous`. **Still unmeasured:** whether the Overlay loads and sees presents inside that browser process |
| — | ~~**Multi-process titles are refused as `TargetAmbiguous` in v1**~~ — **the Chromium case is RESOLVED the same day (2026-09-03), by the vendor's own label** | Chromium-based runtimes — NW.js, Electron, RPG Maker MV/MZ, a large share of the VN catalogue — run several processes from ONE image path (browser, renderer, GPU), and *Flower in Us* refused as `TargetAmbiguous`. The presenting process is Chromium's GPU process, which owns no window, so "the one with the window" and "the parent" were both wrong picks. **What resolves it:** Chromium marks that process with `--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — **served by the kernel, no `ReadProcessMemory`, no PEB walk, `PROCESS_QUERY_LIMITED_INFORMATION` only**, which is the rule-4 line `HeldProcessHandle` already draws — and resolves only when **exactly one** readable candidate carries the flag as a whole argument. Two GPU processes (two instances), none, or any unreadable candidate still refuse. §S27 is untouched: consent is keyed on the path, every candidate is that path, the guard scans the pid chosen, and `--pid` stays forbidden. **Measured the same evening, and the first rule did not fire:** *Flower in Us* runs **six** processes — browser, `crashpad-handler`, three `utility`, `renderer` — and **no `--type=gpu-process` at all**. NW.js runs the GPU **in-process, in the browser**, which is the one process Chromium leaves untyped. Second rule added: exactly one untyped candidate, every other candidate typed, no GPU process ⇒ the browser is the target; two untyped candidates are two instances and refuse. The refusal line now prints the tree (`browser=1, renderer=1, utility=3, …`) so the next unknown shape is data rather than a bare `TargetAmbiguous`. ~~**Still unmeasured:**~~ **Measured 2026-09-04** (`spike-notes` §9, run 3): the Overlay loads and sees presents inside that browser process — Flower in Us resolved, injected, captured, 3,587 records over three swap chains *(corrected 2026-10-04)* |
| — | **Intel XeSS / XeFG identity is closed at the census — no hook on any `libxess*.dll` export** (decided 2026-09-04, delegated by the owner) | The XeSS SDK failed `18_GPU_VENDOR_APIS` §Checklist (Intel Simplified Software License: binary-only grant, no reverse engineering, termination; headers forbid copying), so no declaration may be vendored or re-declared. The signature-free counter that seemed to survive that — an assembly thunk on a named export — still inline-patches Intel's code inside the game process, which the same licence forbids as *modification*; it would also be the only entry outside `FL_HOOK_GUARD` and a second build language, for identity alone. An Intel title therefore reports upscaler `NOT_REPORTED` and, with `libxess_fg.dll` in the census, Presented FPS under rule 6's *"MAY include generated frames"* qualifier — honest, and the same answer NGX-direct got. **Reversal condition:** Intel relicenses the headers so the checklist clears; then §H11's AMD route applies to Intel verbatim |
| — | **A title whose upscaler or frame generation is compiled into its executable is Presented FPS + the census's qualifier, in attach mode, and that is the ceiling for IDENTITY** (recorded 2026-09-04; **two such titles found the same night — Rune Factory, and Black Myth: Wukong for its upscaling, which ships and loads the 1.1.x monolith and never dispatches to it**) | No module for the census, no export for the inventory: nothing by name. What survives static linking is behaviour on interfaces we hook — the FSR3 frame-generation proxy swapchain at *creation* (launch mode only, §S1 deferred) and queue-side cadence with no vendor name on it. ~~**No installed title has this shape**~~ — **Rune Factory: Guardians of Azuma has it**: `amd_fidelityfx_dx12.dll` ships beside the executable and is never loaded (the census has no AMD module), FSR frame generation is on, and the report read `59.99 → 119.95 (×2 FG)`, *technology not identified* — because on a UE5 title **Streamline's frame token is requested whether or not NVIDIA's features are the ones running**, so the application-frame COUNT survives static linking even though the identity cannot. The ceiling is therefore lower than this row first said: the trio with an unidentified technology, not Presented FPS alone (§H11's run table). Identity for such a title stays out of reach by name |
| — | ~~**Tier 2 requires an elevated Agent**~~ | **CLOSED 2026-08-28 by the two-rung ladder.** The requirement came from Windows restricting ETW trace sessions; there is no ETW rung, so **no capture tier needs elevation**. Elevation is optional everywhere and buys exactly two things (CPU temperatures via PawnIO, attaching to elevated targets — ADR-9). An unelevated Agent whose Tier-1 attempt fails lands on Tier 2, which is what every unhooked session lands on regardless of privilege |
@@ -71,27 +101,27 @@ or it becomes the next stale status claim this file exists to record.
| S3, S5, S7, S8, S9, S10, S11, S15, S16, S17, S18, S21, S22 | ✅ **resolved** | Thirteen. Reasoning kept in place rather than deleted |
| **S25, S26** | ✅ **resolved 2026-08-05** | The two runtime stops unreachable in a non-presenting process; occlusion probes recorded as frames |
| **S28** | ✅ **resolved 2026-08-05** | The guard's entry points share process-wide statics; a concurrent call cleared the blocklist mid-match and every check fell through to `Allow`. Reproduced by CI, not argued |
| **S27** | ✅ **resolved, and restated 2026-08-06** | The chokepoint is the anti-cheat gate, not the consent gate. It was closed by *not building* a capture host; item 1 built one, and the ✅ survives on the clause that was always load-bearing — **no injecting entry point on any SHIPPED binary**. `FrameLedger.CaptureHost` is unpublished, and `tools/package-closure-check.ps1` makes that a gate rather than a fact about today's csproj. `HookRequest` is get-only behind one factory, so this entry's own rejected synthesis no longer compiles |
| **S27** | ✅ **resolved, and restated 2026-08-06** | The chokepoint is the anti-cheat gate, not the consent gate. It was closed by *not building* a capture host; item 1 built one, and ~~the ✅ survives on the clause that was always load-bearing — **no injecting entry point on any SHIPPED binary**. `FrameLedger.CaptureHost` is unpublished, and `tools/package-closure-check.ps1` makes that a gate rather than a fact about today's csproj.~~ *(Corrected 2026-10-04: ✅ restated 2026-09-10 in the entry below — the shipped Agent injects by design, and the four properties in the entry hold rule 1; `package-closure-check` keeps its meaning for the CaptureHost only.)* `HookRequest` is get-only behind one factory, so this entry's own rejected synthesis no longer compiles |
| S12 | 🅓 **deferred, rationale written** | Cautious mode → v1.1; it disabled nothing in v1. *(Marked ✅ until 2026-08-27 — same disposition, different glyph.)* |
| **S1** | 🅓 **deferred, rationale written** | Owner decision 2026-08-05. Deciding input — a title loading a presentation runtime lazily — is not on this machine |
| **S13(c)** | 🅓 **deferred, rationale written** | Same decision as S1; (a) and (b) were already settled |
| **S1** | ◐ **launch mode built as "inject late" 2026-09-06 (P1 item 2); the cost is now measured per title** | `FlGuardedInjectWhenReady` polls until a presentation runtime is mapped, then runs the full guard; `dxgiPresentsBeforeHook` and the reported wait are the input the 2026-08-05 deferral lacked. The ruling "inject late vs. no launch mode" is answered by construction — inject late exists — and whether it is *preferred* per title is what the numbers decide |
| **S13(c)** | ✅ **salvageable, and salvaged 2026-09-06** | The externally observable proxy the entry proposed is what was built; the missing input is produced by every launched session |
| **S19(b)** | 🅓 **deferred, rationale written — and MEASURED** | CI 2026-08-05: the fragment fires on `System.Security.Cryptography.ProtectedData.dll` loaded by a .NET **test host**, i.e. inside a real scan set in the launch-mode arrangement — refusing our own injection. The entry's "plausible and unmeasured" is superseded; the deferral rationale (a `CryptCATAdmin*` PR doing network I/O inside the hard gate, NFR-10) still stands. *(Marked 🔴 until 2026-08-27. The measurement belongs in this cell, not in the marker — a glyph that means "deferred" and a glyph that means "open defect" cannot be the same one in a table audited by counting.)* |
| **S14** | ◐ **exe half wired 2026-08-05** | Owner decision 2026-08-05: wire it, empty list, unresolvable identity refuses. The **store-id half is blocked** on the platform metadata extractors and cannot be reached through the guard ABI by design |
| **S14** | ✅ **both halves wired and seeded 2026-09-25** (exe half 2026-08-05) | ~~The store-id half's only in-policy route is P4's platform metadata extractors feeding a guard-side resolver~~ — built as a guard-side seam that reads Steam's `appmanifest_*.acf` and GOG's `goggame-<id>.info` itself; an install no store names is not refused, unreadable store metadata is. 30 Steam ids and 33 executables listed (rules 2026.09.4), floored; 33 Steam ids since 2026-10-03 (rules 2026.10.1: three CrackProof titles, `19_SAFETY` check 3). Epic has no reader |
| **S23-1** | ✅ **resolved 2026-08-05** | `FlGuardBuildId` gives the Agent a build id of its own, and `ShmHandshakeValidator` performs the comparison `07_IPC` and `04_CAPTURE` both specify. Every refusal path is driven, including **both ids empty** — the shape the feature shipped in, where `"" == ""` reported `Ok` for every process on the machine |
| **S23-4** | ✅ **resolved 2026-08-05** | `19_SAFETY` §During a session said "the module scan and the driver scan"; `EvaluateImpl` runs four. Reworded to "every pre-injection check" so it cannot go stale when a check is added, with the two omissions named — `services` is the only tier measured firing on real anti-cheat, and the pre-scan is the only one touching the filesystem |
| **S2 part three** | ⏳ **open, sequenced** | In-layer supervision lands with `vkQueuePresentKHR` (P1). Building it sooner would be a predicate whose wrong answer changes nothing observable |
| **S4 signing** | ⏳ **open, residual accepted** | HTTPS authenticates the host, not the content. Recorded rather than closed — needs a rationale written or a decision |
| **S6** | ❓ **open, disposition undecided** | Owner: work, or deferral-with-rationale? See the correction block under §S6 for what #40–#44 changed and what it does not |
| **S2 part three** | ✅ **built 2026-09-06 (P1 item 3)** | In-layer supervision on the present path, landed with `vkQueuePresentKHR`; `unhookRequested` and the tick deadline both stop the layer (passthrough with the reason on the mapping), proven by a fake loader chain and a 1.5 s test-only flavour of the DLL |
| **S4 signing** | 🅓 **deferred ~~to P4~~, unscheduled — P4 closed without it (corrected 2026-10-04); rationale written 2026-09-06** | Signing is a property of the feed and there is no feed (§S20); every rules file today shipped inside a release whose checksum attests it. The P4 decision (compiled-in key, detached signature, fail-closed) is written in the entry |
| **S6** | ✅ **built 2026-09-06 (P1 item 1)** | The detour on `kernelbase!LoadLibraryExW` stops the Overlay from inside on an exact-floor MODULE match, within one present or one watchdog iteration, and wakes the lazy installers within milliseconds for an inventoried module; measured against the real Overlay in ctest `fl_guard` `[loader]`/`[S6]`. Exact names only — fragment and signer stay the host's 30 s scan, so the disclosure does not change |
| **S19(a)** | ✅ **resolved 2026-08-05** | `gameguard` could never fire — `guard` subsumed it. Removed; `rules-validate` now fails when any fragment contains another, so the class cannot return. Zero coverage lost: nProtect has its own named module family |
| **S19(c)** | ❓ **open, disposition undecided** | `signerField` and `action` are schema-`required` and parsed by nobody. Costing `action` honestly means first deciding `warn`/`allow` may exist, and CLAUDE.md rule 2 says they may not |
| **S19(c)** | ✅ **resolved 2026-09-06** | The fields are constants the schema pins and the guard never reads, because the policy is code by CLAUDE.md rule 2 and `19_SAFETY`; `rules-validate` now proves the schema rejects `action: "allow"` and `signerField: "CN"` (canary 3), so the data cannot say otherwise |
| **S19(d) residual** | ✅ **resolved 2026-08-05** | A second canary, **derived from the shipped document** rather than hand-written, carries `nameFragments: []` and must be rejected. The entry's stated consequence was overstated and is corrected in place: the generated floor would not have disappeared, `gen-ac-floor.ps1` hard-errors and the native build fails — what was unguarded is the *schema* half |
| **S20 feed half** | ❓ **open, disposition undecided** | **FR-7.3 is unmet**: a rules edit reaches no installed machine until a release |
| **S23-3** | ⏳ **open, sequenced** | `08_UI`'s refusal notice is wrong in the commonest case; needs to reach `08_UI` and the `Safety_*` keys before any UI exists (P3) |
| **S20 feed half** | 🅓 **deferred ~~to P4~~, unscheduled — P4 closed without it (corrected 2026-10-04); rationale written 2026-09-06** | **FR-7.3 stays unmet and written as unmet**: the fetch needs a shipped Agent, §S4's signing and the privacy policy's rows, all P4; until then a rules edit ships with the next release, checksum-attested |
| **S23-3** | ~~🅓 **deferred to P3, rationale written 2026-09-06**~~ 🔴 **open: P3 shipped the refusal UI without it** *(corrected 2026-10-04: a machine-wide `BlockedService` / `BlockedDriver` notice still reads "… was detected in this game", `SafetyNotices.RefusalText`)* | `08_UI`'s refusal notice is wrong in the commonest case; the requirement reaches `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI — a string with no view would read as done |
| **S23-5** | ✅ **resolved 2026-08-05** | Closed the way §S23-4 closed the same class — by **removing** the restatement, not correcting it — and `rules-validate` now fails when any `$comment` enumerates checks again. The rule's own first version was scoped to the wrong object and could not fire; it now walks every `$comment` and fails if it finds none |
| **S23-6** | ◐ **partly closed** | `license-check` now binds `THIRD_PARTY_NOTICES` bidirectionally — the first real gate over anything in `legal/`. The **accuracy blocks remain hand-maintained prose that nothing verifies**, and `DISCLAIMER.md`'s went stale a second time on 2026-08-05 |
| **S23-6** | ✅ **closed 2026-09-06** | `license-check` binds `THIRD_PARTY_NOTICES` bidirectionally, and the accuracy blocks are now ONE text — `legal/ACCURACY.md`, embedded verbatim in `README.md` and `DISCLAIMER.md` §4, gated by `tools/accuracy-check.ps1` (self-tested both directions). Truth stays a human's job; drift between copies no longer is |
| **S23-2** | 🚫 **owner only — no PR can close it** | `Rules / validate` is **not** a required status check on `main`. **Re-verified against the live branch protection 2026-08-05**, not repeated from the entry: `required_status_checks.contexts` is exactly `["check", "analyze (csharp, none)", "analyze (cpp, manual)"]` (`strict: true`, `enforce_admins: true`, `required_linear_history: true`). The `validate` job is path-filtered and `pull_request`-only, so a red removal check does not block the merge button. **The gate that exists to make the anti-cheat blocklist un-removable is advisory.** This is a branch-protection setting |
| **S29** | 🔴 **open, new 2026-08-05 — five ✅ and two ◐, counted off the glyphs below on 2026-08-20** | (a) ◐ **CORRECTED**: the honesty assertion *is* in the merge gate, natively (`fl_guard`, 20.58 s on CI); only the **managed** drain is ungated, and §S19(b) is **not** a prerequisite of the feature hooks — the original claim was wrong and had been used to re-order the work. **Sharpened 2026-08-06:** fixing §S19(b) alone would still gate nothing, because `build.ps1`'s `-SkipIntegration` applies `--filter 'Category!=Integration'` and excludes the class *before* the guard is ever asked. Two independent mechanisms produce one absence, and `ci.yml` must drop the switch too; (b) ✅ `fl_vtable_indices` now pins the Overlay's indices through a shared header; (c) ✅ **closed 2026-08-06 by deleting `ShouldUnhookAsync`** — zero production callers, strictly weaker than `ScanOnceAsync`, and inverted in polarity; the gate's public instance surface is now pinned to `{StartAsync}`; (d) ◐ `vklayer-blastradius` case 3 is now an assertion, but the script still runs only by hand; (e) ✅ **closed 2026-08-06 host-side**, with a held process handle and a classifier that takes no elapsed-time parameter, so a frozen `writeIndex` can never end a session; (f) ✅ **closed 2026-08-20**: the normative contradiction between CLAUDE.md rule 7 and `03_METRICS` about inline RayQuery is settled the way the entry proposed — AS-build activity proves ray tracing is happening, *naming the technique* is what needs a DXIL scan — and rule 7 is amended in the PR that wrote the hooks. Its second half closes with it: `FL_MEASURED_RT` now has a producer (both command-list detours, installed off the game's own device), so all three conjuncts of the `No` branch are live and **`Yes` and `No` are both reachable for the first time**, proved by injection in both directions; (g) ✅ the present-only writer claimed `FL_MEASURED_OUTPUT_RES` unconditionally, including on records with no size |
| **S29** | 🅓 **six ✅ and one 🅓 on 2026-09-06 — nothing 🔴 remains** | (a) ✅ **closed 2026-09-06**: the managed drain is in the merge gate — §S19(b)'s signer half removed the refusal and `ci.yml` dropped `-SkipIntegration` in the same PR, both mechanisms at once, as the sharpening below said they had to be. *(History: ◐ CORRECTED — the honesty assertion *was* in the merge gate natively (`fl_guard`, 20.58 s on CI); only the **managed** drain was ungated, and §S19(b) was **not** a prerequisite of the feature hooks. Sharpened 2026-08-06: fixing §S19(b) alone would still have gated nothing, because `build.ps1`'s `-SkipIntegration` applied `--filter 'Category!=Integration'` before the guard was ever asked.)* (b) ✅ `fl_vtable_indices` now pins the Overlay's indices through a shared header; (c) ✅ **closed 2026-08-06 by deleting `ShouldUnhookAsync`** — zero production callers, strictly weaker than `ScanOnceAsync`, and inverted in polarity; the gate's public instance surface is now pinned to `{StartAsync}`; (d) 🅓 **deferred 2026-09-06 on a measurement** — `ci.yml` now prints a Vulkan runtime census, and the script runs as a CI step the day a runner has a loader; until then it stays hand-run before any layer PR, with the P1 Vulkan entry as the reminder (the pre-commitment in the entry covers both rows); (e) ✅ **closed 2026-08-06 host-side**, with a held process handle and a classifier that takes no elapsed-time parameter, so a frozen `writeIndex` can never end a session; (f) ✅ **closed 2026-08-20**: the normative contradiction between CLAUDE.md rule 7 and `03_METRICS` about inline RayQuery is settled the way the entry proposed — AS-build activity proves ray tracing is happening, *naming the technique* is what needs a DXIL scan — and rule 7 is amended in the PR that wrote the hooks. Its second half closes with it: `FL_MEASURED_RT` now has a producer (both command-list detours, installed off the game's own device), so all three conjuncts of the `No` branch are live and **`Yes` and `No` are both reachable for the first time**, proved by injection in both directions; (g) ✅ the present-only writer claimed `FL_MEASURED_OUTPUT_RES` unconditionally, including on records with no size |
| **S30** | ✅ **closed 2026-08-15** | Answered on the title that raised it: with Ray Reconstruction on, Cyberpunk 2077 evaluates `kFeatureDLSS_RR` on every application frame and `kFeatureDLSS` **not once**, so RR was doing the upscaling and the decode had no arm for it. Evidence rather than inference: `renderW/H` are published only on a frame that drained an evaluation and read 1485×835 = 0.58 × 2560×1440, so the scaling-input tag arrives ON the RR evaluation. Two further defects fell out — the pre-committed decision table had two holes, and the fix contaminated the census that found it (it derived the id from the decoded byte) |
| **S31** | ✅ **resolved 2026-09-04 — row P1, and `tokens/batch = 1.00`** | Is a drained Streamline batch an application frame? **Yes.** The `slGetNewFrameToken` count (#103, #105) reads 1.00 / 2.99 / 3.99 against Cyberpunk's own off / ×3 / ×4 and 4.00 on Hell Is Us, and on every leg with batches the two counts agree to the frame. Two independent per-frame API counts are the oracle four instruments could not be. `fg_factor` is published; `none` is reachable by counting. *(The row as it stood while open:)* ◐ **row P2, 2026-08-27 — the ORACLE is retired, the QUESTION is not** | Is a drained Streamline batch an application frame? The PresentMon 2.x `FrameType` test, with its decision table pre-committed BEFORE the run and `tools/frametype-oracle.ps1` producing the input as two dimensionless ratios. **Two obstacles measured before it could be run**: the console binary will not start a trace session unelevated on the dev box (exit 6; the account is in neither Administrators nor Performance Log Users, and the running shared service does not help), and `--track_frame_type` is a **beta** option whose own help says it needs application or driver instrumentation of the Intel-PresentMon provider — so it may be as unavailable as `fl-baseline-probe` proved to be. Two of the table's six rows retire it outright. Blocks HANDOFF item 3's producer decision |
| **H11** | ◐ **AMD ffx-api BUILT and RUN 2026-09-04 (A1–A3 accepted; the loader row added the same evening after three loader titles read silent); Intel closed at the census by licence; FSR 3.0 host route deferred to its own PR** | XeFG and FSR3-FG identity. The AMD half is measured on nine titles: the three ffx-api leaves AND the SDK 2.x loader are hooked (the loader turned out to be the game's entry on loader-shipping titles, with the leaves silent behind it), the vendored MIT headers (tag v2.3.0) decode the dispatch descriptor, and rows A1–A3 landed as pre-committed and **R6 closed on Dying Light: The Beast and KCD2 the same night** (`FSR (3.1 or 4 …)` / `FsrFg` / ×2 / 1.01 and `none` / 1.00 through the loader row). Wukong's FSR upscaling is compiled in (Rune Factory's shape; the title has no FSR frame generation), so nothing more is owed on the AMD half; the FSR 3.0 host route is the one deferred piece Intel's SDK failed the licence checklist, so XeSS/XeFG stay at the census (§Scope decisions). `ffx_fsr3_x64.dll` (FSR 3.0, Cyberpunk only here) ~~needs ten host headers from tag v1.1.4 and is deferred with that costing written~~ **built 2026-09-05** from tag `fsr3-v3.0.4` (the docs' `v1.1.4` was the wrong tag: twelve exports match 3.0.4, not 1.1.4's fifteen, and 1.1.4's descriptor appends fields after `renderSize`); one row, the host's UPSCALE; **rows B1–B4 owed** (below) |
@@ -134,6 +164,29 @@ the recount becomes the next thing that needs recounting.
> the question* rather than by a decision to stop asking it, since S30. ❓ three, ⏳ three,
> ◐ two, 🔴 one, plus 🚫 S23-2. The list above moved in the same edit as this count.
>
> **ZERO on 2026-09-06 — exit criterion 2 reads as met, with one item outside any PR.** The
> owner's closing sweep ("theo bảng"): S19(c) and S23-6 resolved by a gate each, S29 down to
> one 🅓 on a pre-committed measurement, and six items deferred with their rationale written
> in the entry and their phase named in this table — S6 and S2 part three to P1, S23-3 to P3,
> S4 signing, S20 feed half and S14's store-id half to P4. ❓ zero, ⏳ zero, ◐ zero, 🔴 zero.
> **What remains is 🚫 S23-2**, a branch-protection setting only the owner can change; it is
> not resolved and not deferred, it is outside what a PR can do, and the criterion's own
> wording does not reach it. The bullet list above is history as of 2026-09-04 and is left as
> it stood; this paragraph is the current count.
>
> **Corrected 2026-09-09: ◐ is TWO, not zero.** S1 and H11 carry ◐ in their own headings and in
> the rows above — both *built, with a residue that is an owner measurement* (S1: the first
> real-title launch and the descendant election, now P2's; H11: rows B2–B4 unfired). The count
> *against exit criterion 2* is unchanged — neither is a safety gap and P0 stays closed — but the
> glyph column said ◐ while the sentence above said ◐ zero, which is exactly the failure this
> table records about itself (*"a count that is correct while its own list is wrong"*). Kept
> as ◐ two here rather than re-glyphing the rows: the rows were right and the paragraph was
> wrong, and the residue of each is a run, not a rationale. P2's sequencing is `HANDOFF` §P2.
>
> **2026-09-25: S14 ✅.** The store-id half, one of the six deferrals of 2026-09-06 (to P4), is built and seeded
> in the beta.8 train: a guard-side seam reads the store's own metadata, and the lists carry 30 Steam ids and 33
> executables. The deferred set is five; ◐ stays two (S1, H11); nothing else in this count moved.
>
> **STILL TEN on 2026-08-27, for the third consecutive movement.** S31 moved from ❓ to ◐,
> so ❓ goes four to three and ◐ goes two to three. **The number has now stayed at ten across
> three different changes**, and that is worth saying out loud precisely because a reader
@@ -161,6 +214,13 @@ the recount becomes the next thing that needs recounting.
> whether accepting the Legal Gate (FR-11) is a precondition of stamping consent; and
> whether §S18 blocker 3's "the Agent is the sole host of the guard" is re-ratified now
> that a third project imports `FrameLedger.Guard.targets`.
>
> **Three of these were decided 2026-09-09 and built 2026-09-10 (P2 PR-F):** the kill switch IS an
> input to `HookedCaptureGate` — the fourth, checked first (decision D7); what an operator is shown
> before a console record is written is `OperatorDisclosure`, one text for the unshipped host and the
> Agent's console, still not a reviewed `Safety_*` string and saying so first (decision D4); FR-11 is NOT
> a precondition of stamping consent in P2 (decision D8). The `hook_blocked_reason` clearing and the
> §S18 blocker-3 re-ratification stay the owner's.
> **2026-08-09, and the count does not move: still nine.** The upscaler identity hook
> landed (`HANDOFF` item 2) and closed nothing in this table, which is worth stating so
@@ -291,7 +351,13 @@ refuter told to default to *refuted*. The ledger drift it found is fixed in the
that records this. What follows is the residue: things that need code, recorded so
the next session finds them by reading.
**(a) ◐ The honesty contract is in the merge gate — natively. The MANAGED half is not.**
**(a) ✅ The honesty contract is in the merge gate — natively, and since 2026-09-06 the MANAGED half too.**
> **Closed 2026-09-06 by §S19(b)'s signer half and the same PR's `ci.yml` change.** The .NET
> test host still loads `System.Security.Cryptography.ProtectedData.dll`; the guard now verifies
> its embedded signature offline, reads `O=Microsoft Corporation` on the compiled-in bound, and
> keeps looking. `ShmDrainIntegrationTests`, `CaptureHostEndToEndTests` and the LHM hardware case
> run in CI under `./build.ps1 check` with no switches. The entry below is the history.
> **This entry was WRONG when it was written on 2026-08-05, and the correction
> matters because the wrong version was used to re-order the work.** It claimed the
@@ -401,6 +467,38 @@ layers) and needs `vulkaninfo` on `PATH`. So the assertion only fires when someo
runs it by hand. Nothing reminds them, and a loader upgrade is exactly when it
would matter.
> #### Disposition 2026-09-06, pre-committed on a measurement the same PR takes
>
> The "wrong place" argument inverts on a hosted runner: it is disposable, so an implicit
> layer registered under its `HKCU` harms nothing, and it IS the place a loader upgrade
> would be noticed. What decides is whether the runner has a Vulkan loader and
> `vulkaninfo.exe` at all — they ship with a GPU driver's runtime, not with Windows.
> `ci.yml` now prints a **Vulkan runtime census** (`vulkan-1.dll`, `vulkaninfo.exe`, the
> ICD registry key) as a measurement step. **Rows:** present → the next PR runs
> `vklayer-blastradius.ps1` as a CI step and (d) closes ✅; absent → (d) is 🅓 **deferred on
> that measurement**: the script stays hand-run before any layer PR (`HANDOFF` §Traps), and
> the reminder is the P1 Vulkan entry that cannot land without running it. Either row ends
> S29 as an S-item; the count below is written for the absent row and corrected if the
> census says otherwise.
>
> **2026-09-06 (P1 item 3): the assertion now lives in a ctest, and it no longer needs the registry.**
> `fl_vklayer_real` starts the harness's `--vulkan` mode with `VK_ADD_IMPLICIT_LAYER_PATH` pointed at the
> build tree's manifest and the enable variable set, and asserts the loader mapped the layer and the layer
> recorded the presents — on every dev-box build, with no HKCU write and nothing left behind. It SKIPS
> where there is no loader or no presentable device, which is CI's row; the census still decides (d)'s
> CI leg. `vklayer-blastradius.ps1` remains the hand-run check of the *unset-variable* case (it was run
> before this PR, green), and the loader-upgrade reminder is now the ctest rather than a HANDOFF trap.
>
> **Read 2026-09-06 off the sweep PR's run (`windows-latest`): `vulkan-1.dll` PRESENT in
> System32, `vulkaninfo.exe` absent (not in System32, not on PATH), no ICD registry key.** The
> absent row: **🅓 deferred on that measurement.** The loader is there but nothing to drive it
> with and nothing for it to drive — `vulkaninfo.exe` ships with a GPU driver's runtime, and
> without an ICD `vkCreateInstance` fails before the layer question is fully asked. The script
> stays hand-run before any layer PR. **Reopen condition, written now:** a Vulkan mode of
> `hook-harness` (unwritten, `12_BUILD` §Targets) could replace `vulkaninfo.exe` as the driver,
> and whether the loader's layer discovery and `enable_environment` behaviour is observable
> with no ICD is one measurement away — the P1 Vulkan entry is where it is taken.
**(e) ✅ The reader cannot tell a dead target from a quiet one — closed 2026-08-06,
host-side, with no ABI change.**
@@ -1143,6 +1241,47 @@ rather than a missing feature.~~
> the App as a stdout capability report while `12_BUILD` and `Program.cs` list it
> as an Agent flag. Whatever the eventual capture flag is called, it is not that.
> **Restated 2026-09-09 (P2 PR-B), because the basis moved.** The 2026-08-06 restatement held the ✅
> on *"no injecting entry point on any SHIPPED binary"* and on the consent adapter living in the
> unshipped host. Neither is true now: `Infrastructure.Persistence.SqliteGameConsentStore` — the
> adapter `04_CAPTURE` said P2 would write — SHIPS in both publish roots, and `GameConsentRecord.Stored`'s
> `InternalsVisibleTo` list names `FrameLedger.Infrastructure` (the "deliberate, reviewable act"
> `Domain.csproj` asked for). PR-C/PR-F then make the Agent the injecting entry point by design, which
> `01_ARCHITECTURE` always said it was. **What holds rule 1 from here is not packaging.** It is that
> the only producers of an acknowledgement are a disclosure shown to a human — the unshipped host's
> verb today, the Agent's console verb (HANDOFF §P2 decision D4), the UI's dialog (P3) — that the
> provenance is recorded by NAME and an unknown one reads as `NotRecorded`, that `HookRequest.FromConsent`
> stays the gate's only producer, and that every anti-cheat check still runs afterwards.
> `package-closure-check` keeps its meaning for the CaptureHost only. **The owner re-ratifies this
> and §S18 blocker 3 together** (HANDOFF §Owner-only item 5); until then the ✅ stands on the four
> properties above, stated, rather than on the one that no longer holds.
> **Restated again 2026-09-09 (P2 PR-C): the loop ships too.** `CaptureLoop` — the code that has
> reached `FlGuardedInject` on every hooked session since 2026-08-06 — is now
> `Application.Capture.CaptureSession`, in both publish closures, with `Infrastructure.Capture`
> holding the adapters (`ShmRingAttacher`, `HeldProcessLivenessSource`, `TargetResolver`,
> `ProcessLauncher`). Nothing in the Agent calls it yet (PR-F), so today's shipped binaries still
> carry no injecting *entry point*; what they carry is the injecting *code path*, and that is by
> design (`01_ARCHITECTURE`). The four properties above are what hold, and PR-C adds two pins:
> `HookRequestSoleProducerTests` (reflection: no public constructor, no setter, exactly one factory)
> and `NoSecondRingReaderTests` (nothing but `ShmRingReader` opens the ring). The resolver still has
> no pid parameter — `TargetResolver.Resolve(normalisedExePath)` is the only way to a pid, and the
> gate is the only way from a pid to the guard.
> **Restated 2026-09-10 (P2 PR-F): the Agent is the injecting entry point now, by design.**
> `FrameLedger.Agent --serve` watches the `games` table and records a session per tracked process;
> `--console capture | launch` do it on an operator's verb; both reach `FlGuardedInject` through
> `SessionRecorder → CaptureSession → HookedCaptureGate` and nothing else. What holds rule 1 is what the
> 2026-09-09 restatement said it would be: the only producers of an acknowledgement are a disclosure shown
> to a human — now including the Agent's own console (`ConsentProvenance.AgentConsoleOperator`, decision D4,
> stamped by the Agent's clock, refusing redirected stdin), the provenance is recorded by NAME and travels
> with the acknowledgement (a nameless one is refused by the store), `HookRequest.FromConsent` stays the
> gate's only producer — with a FOURTH input, FR-2.4's kill switch (decision D7), which can only refuse —
> and every anti-cheat check still runs afterwards. The command line is pinned
> (`AgentCommandLineSurfaceTests`: no pid, no payload, no override; `--data-dir` only under `--console`).
> `package-closure-check` keeps its meaning for the CaptureHost only. **The owner's re-ratification of this
> and §S18 blocker 3 is still HANDOFF §Owner-only item 5**; the ✅ stands on the properties above.
### S25 ✅ · Both runtime stops were unreachable in a non-presenting process, and pause was unreachable on a ticking one — **closed 2026-08-05**
Found by tracing call paths while planning the next phase, in code merged the
@@ -1206,7 +1345,32 @@ is still no fault-policy test at all**, so the fix has no regression net. The
vehicle is the blocker, not the assertions; `src/native/tests/CMakeLists.txt`
records both rejected approaches and why.
### S1 · The guard is structurally blind in launch mode
### S1 ◐ · The guard is structurally blind in launch mode — **launch mode built as "inject late", 2026-09-06 (P1 item 2)**
> **Built, and the deferral's missing input is now something every launched session produces.**
> The guard gained `GuardedInjectWhenReady(pid, dll, timeoutMs)` (ABI `FlGuardedInjectWhenReady`): it
> polls the target every 50 ms through the module seam — a `Collected::kFailed` (the suspended /
> still-in-loader `ERROR_PARTIAL_COPY`) is "not yet", never a pass — until `dxgi.dll` with
> `d3d11.dll`/`d3d12.dll`, or `opengl32.dll`, or `vulkan-1.dll` is mapped, then runs `GuardedInjectImpl`
> in full. The poll matches nothing against the blocklist; it chooses WHEN the guard runs and nothing
> about whether it passes. Two new reasons end the poll with nothing injected: `LaunchTargetExited`
> (24) and `LaunchNoPresentationRuntime` (25). The CaptureHost's `launch` verb starts the consented
> executable itself (`ProcessLauncher`, `FRAMELEDGER_ENABLE_VK_LAYER=1`, handle held from birth) and
> routes the same gate through `HookRequest.WaitForPresentationRuntimeMs`; it never terminates what it
> launched. Measured, ctest `fl_guard` `[launch]`: the fake-driven poll injects on the first
> enumeration that shows the runtime and not one before (7 polls, ~300 ms), a target that exits first
> and a budget that runs out each answer their own reason, anti-cheat mapped beside the runtime is the
> full scan's refusal, and the real-seam case against `hook-harness` injects within one poll (15 ms).
>
> **The number nobody had:** `FlWriterState.dxgiPresentsBeforeHook` @60 — DXGI's `GetLastPresentCount`
> at the first hooked present on the first hooked chain, i.e. presents that ran before the hook was in
> (0xFFFFFFFF = the hook never saw a present). With the reported wait (`launch: the guard injected N ms
> after the process was started`) that is the early-init cost §S13(c) said needed a lazily loading title:
> it now comes from every title, on every launched session. **What the numbers decide is whether launch
> mode is *preferred* for a given title, not whether it exists.** The 2026-08-05 rationale stands as
> written below; what it deferred is now measurable rather than argued. Owed: the first real-title launch
> (the owner's next captures), which will also be the first look at a launcher-first title landing on
> `LaunchTargetExited` and needing the Agent's descendant election (P2).
> **§S1 does not gate the Vulkan path.** Added 2026-08-03, because "launch mode
> is blocked by §S1 anyway" was being used as a reason to deprioritise §S18 and
@@ -1275,7 +1439,7 @@ still lacks.
> `opengl32` or `vulkan-1` lazily rather than at startup. The owner supplies real
> fixtures on request; this one has not been found on this machine.
### S2 ◐ · The Vulkan layer has no guard — **both halves done; mid-session unhook still open**
### S2 ✅ · The Vulkan layer has no guard — **both halves done; part three built 2026-09-06 (P1 item 3)**
An implicit layer is machine-wide and loads **before** anything of ours runs, so
the injection guard cannot cover it: no module scan, no driver scan, no
@@ -1331,7 +1495,30 @@ there is no way to point the layer at a different rules file (§S3), so without
it the test silently skipped on any machine that had not run the product — and a
ctest that always skips is a gate that cannot fail.
### ◐ Part three: mid-session guard inside a layered process — decided, half built
### ~~◐~~ ✅ Part three: mid-session guard inside a layered process — decided, ~~half built~~ built 2026-09-06 (heading corrected 2026-10-04)
> #### ✅ Built 2026-09-06 (P1 item 3), in the PR that added the present hook — as the deferral below said it would be
>
> The layer intercepts `vkQueuePresentKHR` (+ `vkCreateSwapchainKHR` / `vkDestroySwapchainKHR`), owns the
> same ring the Overlay would (`fl_shm_host.h`, one per process) and runs the in-layer check **on the
> present path**: `unhookRequested` → `UNHOOKED` within one present; `guardTicks` not advancing for the
> 07_IPC deadline → `UNHOOKED`; `pauseRequested` → no record, still forwarded. "Stops" is passthrough forever
> with the reason on the mapping. Driven end to end by a fake loader chain (ctest `fl_vklayer`), the deadline
> proven with a 1.5 s test-only flavour of the DLL (`fl_vklayer_supervision`: ticks every 600 ms keep it
> alive past the deadline, 1.8 s without one stops it), and the real loader + the harness's `--vulkan` mode
> on the dev box (`fl_vklayer_real`, 241 records in 4 s; skips on CI, which has no loader). `17_HOOK_ENGINE`
> §Vulkan carries the shape. **The residual below is unchanged** and the Disclaimer's wording with it.
>
> #### 🅓 Deferred to P1, rationale written 2026-09-06
>
> The decision is taken (below: supervision is the Agent's job; a layer that cannot confirm
> supervision goes inert) and half of it is built. The other half is the in-layer check that
> reads `guardTicks` — and it has nothing to run on until `vkQueuePresentKHR` is intercepted,
> which is P1 (`15_ROADMAP` §P1: *"Vulkan layer to parity — `vkQueuePresentKHR` plus the
> in-layer supervision check §S2 gates on it"*). Building the predicate now would be one
> whose wrong answer changes nothing observable, the defect class this file records. Cost of
> waiting: none a user can see — the layer intercepts nothing, so there is no Vulkan capture
> to stop.
**The mechanism is decided.** The layer does NOT re-scan on its own after init.
Four options were pressure-tested (2026-08-02); the reasons the other three lost
@@ -1370,7 +1557,8 @@ the layer already has — every uncertainty resolves to inert.
> file and exits. What is built and tested is the *counting discipline*: the tick
> counts evaluations rather than seconds. What is not built is the supervision.
> A reader ticking this off as delivered would then find `07_IPC` §Supervision
> loss unimplementable, which is exactly what happened.
> loss unimplementable, which is exactly what happened. *(Overtaken in P2: `ShmRingReader` publishes the tick from
> `GuardSupervisor`, which `CaptureSession` runs on every Tier-1 session. Marked 2026-10-04.)*
**✅ The Agent half's counting discipline is built and proven.** `GuardSupervisor`
(`FrameLedger.Application`) computes what will become `guardTicks`, and the load-bearing property
@@ -1383,12 +1571,13 @@ process in the §S16 scan set — and the capture side would then keep observing
"the Overlay keeps writing (harmless)" on heartbeat loss described an
unsupervised hooked process as harmless.
**◐ The in-layer half is deliberately NOT built yet, and this stays open.**
**~~◐ The in-layer half is deliberately NOT built yet, and this stays open.~~ ✅ Built 2026-09-06, see the top of this part.**
The layer intercepts nothing — `vkQueuePresentKHR` is P1 — so a `ShouldObserve()`
today would be a predicate whose wrong answer *in either direction* changes
nothing observable. That is a gate on something that does not exist, which is the
defect class this file keeps recording. It lands in the PR that adds the present
hook, where a fake loader chain can drive it end to end.
hook, where a fake loader chain can drive it end to end. *(It did: `MayObserve()` in
`layer.cpp`, ctest `fl_vklayer` / `fl_vklayer_supervision`.)*
**Residual, to state rather than discover:** even once built, the mid-session
*driver* case is invisible from inside a layered process, and a layer cannot
@@ -1434,6 +1623,16 @@ override with a timer on it.
host, not the content. The rules above let a compromised feed be *rejected* but
not a genuine one *proven*. Residual risk, recorded rather than closed.
> #### 🅓 Deferred to P4, rationale written 2026-09-06
>
> Signing is a property of the feed, and there is no feed (§S20's feed half, deferred to
> P4 in the same sweep): every rules file on every machine today shipped inside a build
> whose SHA-256 is published, so the content IS attested, by the release. The decision that
> belongs to P4 — a compiled-in public key and a detached signature over the rules file,
> verified before validate-then-replace, with the same fail-closed polarity as the rest of
> the feed rules — is written here so the feed cannot ship without it. Residual until then:
> none beyond the release checksum, because nothing fetches.
### S5 ✅ · `detection-rules.json` schema — **closed**
`rules/detection-rules.schema.json` (JSON Schema 2020-12) now fixes the shape,
@@ -1455,7 +1654,9 @@ a system DLL.
**Two families remain unrepresented in the data** — Activision Ricochet (driver
and service names unconfirmed) and Valve VAC (needs `blockedStoreIds`). Recorded
in the seed's own `$comment`. The `heuristic.trustedSigners` list is a guess and
in the seed's own `$comment`. ~~Ricochet~~ **has data since 2026-09-25** (`randgrid.sys`,
`atvi-randgrid_sr`/`_msstore`, from Activision's support pages — documented, unmeasured; `19_SAFETY`
§Blocklist seed). VAC still has none. The `heuristic.trustedSigners` list is a guess and
is marked UNVERIFIED.
### S13(c) · Is launch-mode injection salvageable?
@@ -1501,6 +1702,10 @@ prologue) cannot produce a figure that generalises.
> entry proposes (resume, then poll until the target has mapped a presentation
> runtime *and* the scan passes *and* the blocklist is clean) remains the only
> candidate design for "inject late". It is unbuilt, not rejected.
>
> > **✅ Built 2026-09-06 (P1 item 2), exactly that proxy** — `FlGuardedInjectWhenReady`, §S1 carries
> > the mechanism and the measurements. "Salvageable" is answered yes; the cost of injecting late is
> > reported by the session itself (`dxgiPresentsBeforeHook`, and the wait).
### S15 ✅ · The four consequences of putting the guard in C++ (§S13(a)) — **closed**
@@ -2181,6 +2386,80 @@ admits it has no data for (Ricochet, VAC). Three refuters agreed.
> **Nothing under `FrameLedger.Injector` changed with the probe**, deliberately. This
> is a measurement, and reading a row off the table is a separate PR — including the
> row that says build nothing.
>
> **THE CI LEG WAS NEVER READABLE, found 2026-09-06 when it was finally looked for.**
> `ctest fl_signer_probe` passes on `BLOCKER: (FOUND|NOT PRESENT)` and ctest prints nothing
> for a passing test, so eleven days of green CI carried none of the probe's answers — the
> leg rows G3/G4/G5 are written for was "run" in the sense that a binary exited 0. And the
> native tests run BEFORE `dotnet restore` in `build.ps1`, so on a cold runner the NuGet
> copy the probe searches first may not exist yet at ctest time. `ci.yml` now runs the probe
> as its own step AFTER the gate (`continue-on-error`, a measurement and not a gate), and the
> answers are read off that step's log. **Owner-only, still unrun:** the adapters-disabled
> leg (rows G1/G2 — a network setting, not a PR), and the allow-widening bound that no row
> can lift (below). The recommendation for the bound, so the owner decides between two
> written options rather than one: **bound `trustedSigners` by a compiled-in allowlist the
> data file can only intersect** — the boundary of what the gate trusts stays code, exactly
> as `19_SAFETY` ruled for the launcher list, and it needs no branch-protection change; the
> alternative, making `Rules / validate` a required check, is §S23-2 and is the owner's
> GitHub setting, not a file in this repository.
>
> **THE CI LEG, READ 2026-09-06 off the new step (run on `ci/signer-probe-leg`, `windows-latest`,
> the probe reporting `elevated: yes` — the runner is an administrator; the dev-box leg was
> unelevated).** The blocker at the runner's NuGet cache (`system.security.cryptography.protecteddata`
> 6.0.0, `lib/net6.0`): embedded/offline **`ERROR_SUCCESS`, 3.47 ms, `O= Microsoft Corporation`**,
> no catalog; `mskeyprotect.dll` `TRUST_E_NOSIGNATURE` / catalog `ERROR_SUCCESS`; `kernel32.dll` both;
> cold 3.45 ms, warm 3.53 ms; `cryptnet.dll` newly loaded under the offline flags, as on the dev box;
> the canary `TRUST_E_NOSIGNATURE`; the probe's own verdict *"G1 is a CANDIDATE"*. **So G3 does not
> fire (the `O=` premise holds on CI's copy), G4 does not fire (CI's copy is embedded-signed), G5 does
> not fire (3.5 ms).** What is left before G1 can be read is exactly the two owner-only legs above:
> adapters disabled (G1 against G2), and the bound.
>
> **THE ADAPTERS-DISABLED LEG, the owner's run, 2026-09-06 (dev box, elevated; reported in answer
> to the request to run it with every adapter off — if it was not, this paragraph is withdrawn
> and the leg is unrun).** Every verdict UNCHANGED against `spike-notes` §1: `kernel32.dll`
> embedded `ERROR_SUCCESS` / catalog `ERROR_SUCCESS`; `mskeyprotect.dll` embedded
> `TRUST_E_NOSIGNATURE` / catalog `ERROR_SUCCESS`; the blocker embedded `ERROR_SUCCESS`, no
> catalog, **`O= Microsoft Corporation`**; canary `TRUST_E_NOSIGNATURE`; `cryptnet.dll` still
> mapped under the offline flags and still not evidence of a request. Faster than the online run
> (2.14 ms cold, 2.15 ms warm; 2.97 / 2.13 ms on the system binaries), which is what an offline
> cache-only path should look like. **One detail worth its line:** the blocker's subject now reads
> `CN=.NET` where the August copy read `CN=Microsoft Windows` — the NuGet copy was re-staged with a
> different certificate — and `O=` is the same on both, which is the `signerField: "O"` decision
> confirmed on a subject class it was never measured against. **Row G1 reads.** The embedded half
> alone, offline, clears the CI refusal; the `CryptCATAdmin*` catalog half is deferred with its own
> rationale (it reaches `mskeyprotect.dll`, which is not on the path to the merge gate, and it is
> the `CatRoot` walk §S19(b) priced). **What still stops the build is the bound**, above — the
> owner's, and asked for beside this reading.
>
> #### ✅ BUILT 2026-09-06 — the embedded half, on row G1, under the compiled-in bound (owner: option 1)
>
> **The owner chose the bound the same afternoon: a compiled-in allowlist the rules file may only
> intersect.** `IsCompiledTrustedSigner` in `fl_ac_rules.cpp` names the five organisations the shipped
> rules name, and `IsTrustedSigner` now requires BOTH lists — a rules push that adds `"Evil Corp"`
> widens nothing, which is one assertion in `fl_guard`. `Sources` gained
> `ModuleSignerOrganisation`: `WinVerifyTrust(WTD_CHOICE_FILE)` under `WTD_REVOKE_NONE |
> WTD_CACHE_ONLY_URL_RETRIEVAL | WTD_SAFER_FLAG`, and only after `ERROR_SUCCESS` the signing
> certificate's subject `O=` through `CryptQueryObject` — the probe's shape with fixed buffers, in
> `fl_guard_sources.cpp` (never `fl_ac_rules.cpp`, which the Vulkan layer compiles: wintrust and
> crypt32 stay out of every Vulkan process). `ModuleSinkFn` asks it after the ours exemption and
> BEFORE latching: a trusted module returns *keep looking*, exactly as the exemption does, so the
> load-order fail-open this entry predicted is closed by the same structure — and it applies to the
> TARGET too, because a game loading a Microsoft-signed key-protection provider is the false refusal
> the half exists to remove. **The fail-closed row, added:** no embedded signature (every catalog-only
> system binary — `mskeyprotect.dll` by design), an invalid one, an unreadable `O=`, a null path, a null
> seam, a seam that fails, an organisation on one list but not the other — all untrusted, all refuse.
> The catalog half stays deferred: it reaches only modules that are not on the path to the merge gate,
> and it is the `CatRoot` walk this entry priced.
>
> **Proved in both directions, against the real seams:** `hook-harness --load <dll>` puts a named module
> into the target before the guard looks. The NuGet copy of the CI blocker → **Allowed**, Overlay
> injected (skipped loudly on a machine with no NuGet cache; the managed integration cases are the gate
> that cannot skip it). Our own unsigned Overlay copied under a `protect`-bearing name outside the
> guard's directory → **SuspiciousUnsigned**, naming it, nothing injected. Nine fake-seam cases pin the
> decision (both lists, the target, kFailed, missing seam, pathless, load order, exact-hit precedence).
> **And `-SkipIntegration` is gone from `ci.yml` in the same PR**: the nine `Category=Integration`
> cases are in the merge gate for the first time since 2026-08-05, and CI runs the same
> `./build.ps1 check` a developer does. The switch stays in `build.ps1`, loud, for whoever must.
**(c) `signerField` and `action` are required by the schema and parsed by
nobody.** Both are `required` in `detection-rules.schema.json`, both carry
@@ -2203,6 +2482,17 @@ configurable and never was; the field that would express it has no consumer.
> `warn_and_refuse` — a predicate whose answer changes nothing observable, which
> is the defect class this file exists to record. Wiring it means first deciding
> that `warn` or `allow` may exist, and CLAUDE.md rule 2 says they may not.
>
> #### ✅ Resolved 2026-09-06 — the consumer is the validator, and the policy is code by rule
>
> Decided the way the paragraph above costs it: `warn` and `allow` do not exist (CLAUDE.md
> rule 2), and the signer field is `O=` by measurement (`19_SAFETY`), so neither field is
> for the guard to read — they exist so that the DATA cannot claim otherwise. What was
> missing was the thing that makes that true: `rules-validate` now carries a third canary
> that mutates the shipped document to `action: "allow"` and to `signerField: "CN"` and
> requires the schema to reject both. Delete either `const` and the gate goes red. The
> guard's hardcoded refusal is the specification, and `IsCompiledTrustedSigner` (§S19(b))
> made the other half of the heuristic code-bounded the same day.
**(d) ◐ The fragment list has unreconciled copies — more than three. The runtime
hole is CLOSED.** `rules/detection-rules.json`, `guard_test.cpp` (the inline
@@ -2363,6 +2653,15 @@ disproved:
with validate-then-replace; none of it exists. So **FR-7.3 is unmet**: anti-cheat
entries cannot reach a machine on their own schedule, only with a release. A
rules edit still changes nothing on any installed machine until the next build.
> **🅓 Deferred to P4, rationale written 2026-09-06.** The feed is the product's one
> permitted outbound request after the release check (CLAUDE.md rule 8), and it needs
> three things P0 does not have: a shipped Agent to run it in, the signing §S4 defers to
> the same phase, and the privacy policy's rows that describe it (~~`legal/PRIVACY_POLICY.md`
> already flags them as describing a request the software does not make~~ — **removed in version 2.2, 2026-09-16**:
> the feed lands as a new policy version the Legal Gate shows again, not as rows kept in advance). Until then a
> rules edit reaches a machine with the next release, whose checksum attests it — a slower
> delivery, not a weaker gate. FR-7.3 stays unmet and stays written as unmet.
- **No binary/data handshake inside the guard.** `ParseRules` still walks only the
`anticheat` subtree and never reads `schemaVersion` or `rulesVersion`. Teaching
it to refuse an unknown version would be a second machine-wide refusal lever
@@ -2370,19 +2669,21 @@ disproved:
which used to claim a bump check that does not exist.
- **`trustedSigners` is the one allow-widening field a foreign file still
controls.** Deliberately not floored, because flooring an allowlist has the
wrong polarity. Inert today — `IsTrustedSigner` has no production call site
while §S19(b) is deferred — and **live the moment the signer half is wired**,
wrong polarity. ~~Inert today — `IsTrustedSigner` has no production call site
while §S19(b) is deferred — and~~ **live the moment the signer half is wired** *(corrected 2026-10-04: wired since
§S19(b), 2026-09-06, and bounded by `IsCompiledTrustedSigner`)*,
which makes gating it a prerequisite of §S19(b) rather than of this item.
- **This is what arms the Vulkan layer's self-scan for the first time.** `layer.cpp`
§S2's second half could only ever answer "inert" while the file never existed.
It is now reachable, on a machine where the file is present. The layer still
It is now reachable, on a machine where the file is present. ~~The layer still
intercepts nothing (`vkQueuePresentKHR` is P1), so nothing observable changes
yet — recorded here so it is not discovered as a surprise when the present hook
lands.
lands.~~ *(Corrected 2026-10-04: `vkQueuePresentKHR` is intercepted since 2026-09-06, §S2 part three.)*
- **A seed replacement is a rules update in FR-2.3's sense**, and the obligation
attached to that event — re-run the pre-scan, force-disable a game that has
started matching — is unimplemented. There is no `games` table yet, so there is
nothing to write; named here so whoever builds persistence has an anchor.
started matching — ~~is unimplemented. There is no `games` table yet, so there is
nothing to write; named here so whoever builds persistence has an anchor.~~ *(corrected 2026-10-04: built —
`UpdateRules` wakes `AntiCheatPreScanSweep`, beta.8, keyed per rules version by schema 0010.)*
### S21 ✅ · The hard gate's data source was caller-nameable, and its completeness floor never read the values — **closed**
@@ -2782,7 +3083,7 @@ required contexts are exactly `check`, `analyze (csharp, none)` and
the gate that exists to make the anti-cheat blocklist un-removable is advisory.
Fixing it is a branch-protection change, i.e. the owner's, not a code change.
**3. `08_UI` describes a refusal notice that is wrong in the commonest case.** It
**3. ~~🅓 Deferred to P3, rationale written 2026-09-06~~ 🔴 Open — P3 built the refusal UI without it (corrected 2026-10-04: `SafetyNotices.RefusalText` formats every named refusal as "… was detected in this game", so the measured case below still reads wrong) — `08_UI` describes a refusal notice that is wrong in the commonest case.** *(The requirement below must reach `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI, and not before: there is no UI to be wrong in yet, and a `.resx` string with no view is the kind of fix that reads as done. The spike log carries the measurement; this line is the reminder.)* It
promises "the specific signal named in plain language". Measured (`spike-notes`
§13): while any Easy Anti-Cheat title is running, **every** target — including a
freshly spawned, unrelated process — refuses with `BlockedService` naming
@@ -2868,8 +3169,24 @@ gate.
> four-going-on-five unimplemented promises, and now this file's bundling audit —
> remain hand-maintained prose that nothing verifies. A gate over one table is not
> a gate over `legal/`.
>
> **✅ Closed 2026-09-06, by making there be one block.** `legal/ACCURACY.md` is the single
> statement of what the software measures, dated; `README.md` and `legal/DISCLAIMER.md` §4
> embed it verbatim between markers, and `tools/accuracy-check.ps1` — a `build.ps1` gate with
> a four-case self-test, both directions — fails when any copy differs from the source, when
> a copy has no markers, or when the source is empty. What the gate does NOT do is decide
> whether the block is true; that stays with whoever changes the Overlay or the capture host,
> and the block's own comment says so. The block was rewritten to 2026-09-06 truth in the same
> PR (the previous §4 note still said frame generation and ray tracing had no hook).
### S14 ◐ · Pre-injection check 3 is **unwired**, and has no "cannot determine" state
### S14 ✅ · Pre-injection check 3 ~~is **unwired**, and has no "cannot determine" state~~ — both halves wired and seeded 2026-09-25
> **Closed 2026-09-25 (beta.8, owner decision: title lists yes, the AreWeAntiCheatYet bulk list no).** The store
> half reads the store's own metadata through `Sources::StoreIdentity`, from the install root the guard derives
> from the pid — the ABI is unchanged, which was reason (2). Reason (3) is answered by the matrix in `19_SAFETY`
> check 3: listed refuses, no store identity is not applicable, unreadable store metadata refuses. Both lists are
> seeded (30 Steam ids, 33 executables) and floored. What stays open is Epic, which has no reader and so carries no
> identity to this check. The body below is the history.
Found 2026-08-02 while hardening the rules toolchain. `19_SAFETY` §Pre-injection
checks lists a per-title blocklist as check 3, but `anticheat.blockedExecutables`
@@ -2925,6 +3242,13 @@ nothing.
> "fix" (2) by widening the ABI.** The route is the metadata extractors plus a
> guard-side resolver, which is its own PR and its own fail-closed matrix row.
>
> **🅓 The store-id half is deferred to P4, rationale written 2026-09-06.** Its only
> in-policy route is the platform metadata extractors (Steam/GOG/Epic/itch — P4's library
> import) feeding a guard-side resolver, and a resolver with no extractor behind it would
> refuse every title (an unresolved id refuses, by the matrix). The executable half is
> wired and proven red; the data for both halves is empty by decision. Cost of waiting:
> none — no title is blocked by store id today because none is listed.
>
> Proven red: disarming the matcher makes the guard **allow** a blocked
> executable, and the test asserts `kBlockedExecutable` specifically rather than
> "it refused" — which is indistinguishable from the four refusals the guard
@@ -2967,9 +3291,32 @@ Two decisions, both the owner's:
Until both are answered the inertness is recorded in the data's own `$comment`
and beside check 3, rather than being inferable only from two empty arrays.
### S6 · The 30 s scan window is the weakest part of the most important behavior
### S6 ✅ · The 30 s scan window is the weakest part of the most important behavior — **the in-process half built 2026-09-06 (P1 item 1)**
Now disclosed honestly in the Disclaimer and README. The open question is whether
> **Built, as the deferral below said it would be: one detour, both jobs.** `kernelbase.dll!LoadLibraryExW`
> is patched from `InitThread` after the present hooks; the body calls the original first, skips
> data-file / resource mappings, reads the mapped module's own file name into a stack buffer and compares
> its base name (a) against `FL_HOOK_INVENTORY` + `FL_RUNTIME_CENSUS` — a match bumps a 15-bit wake count
> and signals the watchdog's auto-reset event, so the lazy installers run **within milliseconds** rather
> than on the next 1 Hz tick — and (b) against the compiled floor's MODULE families (prefix, case-
> insensitive, the generated table the guard itself carries; zero allocation) — a match CASes the family's
> 1-based index into `earlyStopFamily`, and the present path (`MayObserve`) or the watchdog, whichever is
> first, calls `StopObserving(FL_STATUS_STOPPED_BLOCKLISTED)`. It supplements the poll and replaces
> nothing; it installs nothing inline (§H2). **Measured**, real Overlay in a real target (ctest `fl_guard`):
> a late `sl.interposer.dll` hooked **94 ms** after it appeared (bound 500 ms, which the tick alone cannot
> meet more than half the time); a decoy copied to `EasyAntiCheat_fl_fixture.dll` and loaded 2.5 s in
> stopped the Overlay with `earlyStopFamily` equal to the index the test computed from the same generated
> table, `unhookRequested` still 0, and `writeIndex` frozen thereafter. The CaptureHost reads both words
> (`Consume/EarlyStop.cs`), ends the session as `WriterStoppedBlocklisted` (exit 5, the safety-stop code)
> and names the family from the staged rules file.
>
> **What it does not do, stated so the disclosure stays honest:** the fragment tier and the signer tier
> are not in the detour, so a module the floor knows only that way waits for the host's 30 s scan; the
> Disclaimer's "within 30 seconds" is unchanged. **Owed:** the real-game leg of §H2 — a title that loads
> D3D12 or Streamline lazily, hooked through the wake rather than the tick — which the next captures
> report via the `loader detour:` line (`woke the watchdog N time(s)`).
Now disclosed honestly in the Disclaimer and README. The open question ~~is~~ was whether
to shrink it.
> **"Already installs" was false, and it changed how this item read.** Corrected
@@ -3010,6 +3357,17 @@ acceptable in that hook under the no-allocation rule (it should be), and a
decision on whether it supplements or replaces the poll. Supplements — the poll
also catches modules loaded before we hooked.
> #### 🅓 Deferred to P1, rationale written 2026-09-06 (owner: "theo bảng")
>
> The mechanism is a `LoadLibrary` hook inside the Overlay raising the control-block flag
> the moment a blocklisted module name loads, supplementing the 30 s poll. It is specified
> (`17_HOOK_ENGINE` §DLL entry, deferred install per §H2) and it needs the P1 hook layer's
> `LoadLibrary` detour to hang on — the same detour lazily loaded graphics DLLs need — so
> building it in P0 would mean building that detour twice. The cost of waiting is the one
> the Disclaimer already discloses: up to 30 s between a mid-session load and the stop.
> Not closed: the name comparison in that hook must be against the compiled floor
> families and allocation-free, and it supplements the poll rather than replacing it.
### S7 ✅ · Guard handle rights and WOW64 — **closed**
Measured unelevated 2026-08-02 by `src/native/tools/fl-probe-guard` (ctest
@@ -3127,6 +3485,14 @@ lazily, which is the case the hook exists for. Until then, keep the rule and do
not let anyone "simplify" it back to an inline install on the grounds that the
probe never showed a deadlock.
> **The deferred path is built and exercised in a fixture (2026-09-06, P1 item 1 — §S6).** The detour
> signals an auto-reset event the watchdog waits on with its 1 s timeout; it never calls MinHook.
> ctest `fl_guard` `[loader]` loads `sl.interposer.dll` into a presenting harness 2.3 s after start and
> sees the hook family within 94 ms, wake count ≥ 1, no fault, no stop. **Still owed, unchanged:** the
> real-game leg — a title that pulls Streamline or D3D12 in lazily, hooked through the wake — which the
> `loader detour:` report line will show as a non-zero wake count with the family present from the first
> bucket.
### H5 ✅ · Proxy swapchains defeat the dummy-vtable assumption — **the DLSS / DLSS-G question closed 2026-09-06 (owner)**
> **CLOSED 2026-09-06, 12:17, on Cronos: The New Dawn demo with frame generation ON (`spike-notes` §9).**
@@ -3291,6 +3657,12 @@ probe never showed a deadlock.
> beside each module snapshot (out of process, no consent needed) or, if it goes in-process, through
> `Infrastructure` only (CLAUDE.md: no P/Invoke elsewhere).
>
> **In-process since 2026-09-10 (P2 PR-E2):** the same words through `FrameLedger.NvapiBridge.dll`
> (`Infrastructure.Telemetry.NvapiNgxStateProbe`, the `INgxDriverProbe` the Agent will take from DI);
> the spawn below is retired and `fl-probe-nvapi.exe` is no longer staged beside the host. The readings,
> the merge and the printed block are unchanged, and `NvapiNgxStateProbeTests` maps the bridge's three
> answers to the three outcomes the machine line used to carry.
>
> **BUILT 2026-09-06, on the owner's decision ("nối probe để bắt đầu").** The capture host spawns
> `fl-probe-nvapi --ngx-state <pid>` beside every module snapshot (the probe prints one machine line,
> `NGXSTATE status=… sr=0x… …`, and is staged beside the host by the project file), merges the readings
@@ -3599,7 +3971,7 @@ make us miss the present.
Needs a real Streamline/DLSS-G title, ideally with RTSS and the Steam overlay
also active (`spike-notes.md` §Environment — that machine already has both).
### H6 · D3D12 command-list hooks count recorded, not executed, work
### H6 ✅ · D3D12 command-list hooks count recorded, not executed, work — **answered 2026-08-20 with the RT hooks** *(marked 2026-10-04: per-present atomics drained once per present; the unit is "recorded between two presents", `03_METRICS` §RT)*
`DispatchRays`, `BuildRaytracingAccelerationStructure` and pipeline creation are
recorded into command lists, possibly on many threads, possibly re-executed or
@@ -3642,7 +4014,57 @@ turns a would-be STL throw into `__fastfail`, which SEH cannot intercept
(`spike-notes.md` §H3). The "no throwing STL in hook paths" rule is therefore
load-bearing rather than stylistic.
### H11 ◐ · XeFG and FSR3-FG identity — **AMD built 2026-09-04 through the ffx-api leaves; Intel closed by licence; FSR 3.0 host route deferred**
### H11 ◐ · XeFG and FSR3-FG identity — **AMD built 2026-09-04 through the ffx-api leaves, complete 2026-09-06; Intel closed by licence; FSR 3.0 host route built 2026-09-05**
> **2026-09-06: the AMD half is complete on its oracle** — Lies of P at FSR 3.1 + FSR FG on the #129 build
> prints `Fsr3` / `FsrFg` / `59.77 → 119.55 (×2 FG)` / `2560x1440 -> 2560x1440` with `presents/frame=2.00`,
> `frames/upscale-drained=1.00`, `unseen=0` and the NVIDIA driver's word saying nothing was created
> (`spike-notes` §9); the owner called it done. **Intel, re-checked the same day: the licence has not
> changed** (`18_GPU_VENDOR_APIS` §Intel), so nothing in `libxess*.dll` may be hooked or declared, and the
> signature-free thunk stays refused. **What is left in policy for an XeFG session, proposed and not yet
> built — identity BY ELIMINATION, labelled as such:** frame generation is COUNTED by the Streamline token
> (UE titles request it whatever the FG vendor — measured on Rune Factory's compiled-in FSR) or by DXGI's
> counter; DLSS-G is EXCLUDED by the NVIDIA driver's FG word (no feature created) and by the absence of the
> HUD-less / UI tags; FSR-FG through a shipped DLL is EXCLUDED by the ffx census (no FRAMEGENERATION dispatch
> at any hooked module); the frame-generation runtime the census names is `libxess_fg.dll`. The line would
> read `Active (technology not identified) — by elimination among the runtimes loaded: not DLSS-G (the
> NVIDIA driver reports no NGX frame-generation feature), no FSR dispatch reached a hooked module, and the
> frame-generation runtime present is libxess_fg.dll; a frame generator compiled into the executable would
> read the same`. Never `XeFg` as a measured identity; never a render extent. Intel's README says XeSS-FG
> runs on non-Intel GPUs with SM 6.4, so DL:TB / Hell Is Us / Cronos / Expedition 33 with XeSS FG on are
> the sessions that measure it, and the pre-commitment is the last clause: the wording must survive the
> one static title (Rune Factory at FSR FG) reading the same way.
>
> **BUILT 2026-09-06 (owner: "build cả hai"), with the executable-file scan beside it.** `FgModePrinted`
> carries the elimination sentence on every rung-3 line; `ExecutableMarkerScan` reads the exe on disk once
> after the session and the clear-census qualifier says MAY when a frame-generation-capable SDK string is in
> the file. Expected on an XeFG session (DL:TB / Hell Is Us / Cronos / Expedition 33 with XeSS FG on):
> the trio or a Presented line from the token or DXGI count, and `frame generation: Active (technology not
> identified) — by elimination …: not DLSS-G (…), no FSR frame-generation dispatch …; the frame-generation
> runtime(s) loaded: libxess_fg.dll …`. Expected on Rune Factory at FSR FG: the same shape with *"no
> frame-generation runtime module is loaded at all; the executable itself carries ffxFsr3, …"*. Neither
> prints a vendor as measured.
>
> **LANDED 2026-09-06, 13:45–14:02 (`spike-notes` §9).** **Rune Factory at FSR + FSR FG** reads exactly the
> pre-committed line: `30.05 → 60.05 (×2 FG)` from the Streamline token, `unseen=0` (the compiled-in FSR 3
> presents through the patched body), `frame generation: Active (technology not identified) — by elimination
> …: not DLSS-G (…); no FSR frame-generation dispatch …; the frame-generation runtime(s) loaded:
> nvngx_dlssg.dll; the executable itself carries ffxFsr3, ffxFrameInterpolation — …` — 7b at its ceiling, the
> Steam overlay showing FG where the report shows the count. **Hell Is Us at XeSS + XeSS-FG** (the owner:
> the Steam overlay could not show FG there): `Presented FPS: 186.47`, **`tokens=0`** — this plugin version
> requests no Streamline token at XeSS, where it did at DLSS — so no count and no factor; `unseen=0`, so
> XeFG presents its generated frames through the patched body and the 186 IS the Displayed rate; the driver's
> words clear; the file carries `xefgSwapChain ×13`. The FG line read the bare *"N/A (a hook ran …)"* and the
> upscaler N/A named "a vendor this build does not decode" — both now carry their witnesses: the N/A prints
> the same exclusion clauses (*the frame-generation runtime(s) loaded: nvngx_dlssg.dll, libxess_fg.dll, …;
> the executable itself carries xefgSwapChain*), and the upscaler line says *libxess.dll is loaded, and XeSS
> cannot be hooked or declared under Intel's licence … N/A here by policy, not by ignorance* (7c item 4's
> string change, done). **Cronos at XeSS** (no FG option): `FPS: 110.02`, `none` by count with DXGI agreeing
> — this plugin requests the token at XeSS. **The ceiling for XeFG on a title that requests no token:**
> Displayed measured, Native unknown, vendor by elimination — there is no in-policy application-frame
> producer for XeFG (the token is the plugin's choice; the XeFG API cannot be hooked; the ffx census is
> silent by construction), and the report says so rather than inventing one.
>
> **BUILT, 2026-09-04, the AMD half — and the deferral's own rule was kept: header first, decode
> second, never from observation.** `HANDOFF` item 7c. The FidelityFX headers cleared the
@@ -3858,6 +4280,11 @@ this item defers, and whether generated presents reach our vtable is what §H5 t
### H10 · Per-process VRAM thread inside the game process
🅓 **The usage half is answered from outside the game — 2026-10-03 (beta.12, owner decision D43); the budget half is
deferred with §M11.** The game's dedicated and shared GPU memory are read by the Agent from the `GPU Process Memory`
counters (`18_GPU_VENDOR_APIS` §The game process's memory), so no thread and no DXGI call is added inside the game for
them. What only an in-process call could give is the budget, and nothing reads it. *(The question as it stood:)*
`17_HOOK_ENGINE` §Memory calls `QueryVideoMemoryInfo` "once per second from our
own thread". Spawning a thread inside a host process we do not own is a heavier
footprint than the rest of the design's posture, and DXGI calls off the render
@@ -3881,10 +4308,12 @@ instead, which needs no thread at all.
| M2 ✅ | ~~Does the pinned console binary still exist, run unelevated, and emit the 2.x column set?~~ | **Answered, then closed 2026-08-27.** It exists (2.5.1, 956,768 bytes, SHA256 `9BEC…A191`, **no VERSIONINFO at all**); it does **not** run unelevated (exit 6 — the account is in neither Administrators nor Performance Log Users, and the running `PresentMonSharedService` does not help because the console starts its own session); and the 2.x column set **is measured** — 24 columns, `spike-notes` §11. The parser ate three real CSVs and resolved `FrameType` correctly against a first column literally named `Application`. Closed because the binary is dropped, and kept in full because every one of those facts cost a measurement |
| M5 ✅ | **Do LHM GPU sensors work unelevated, without PawnIO?** **YES — measured 2026-09-03, row R1 of the pre-committed table below**, NVIDIA RTX 5080 / 616.56 / LHM 0.9.6: eight fields unelevated (core and memory temperature, load, VRAM used, core and memory clock, package power, fan), the identical eight in the elevated control, PawnIO never opened. The three user-facing sentences stand. Numbers in `spike-notes` §10. *(The row as it stood while open follows, unchanged.)* This decides whether the default unelevated Agent has temperatures at all, and therefore how ADR-9 reads to users. **SEVERITY PROMOTED 2026-08-28, and the promotion is the point.** It used to decide how a design note read. It now decides whether a **user-facing claim is true**: the two-rung ladder says a Tier-2 session records duration and hardware telemetry, and that sentence is heading for `README`, the consent dialog and `legal/EULA.md`. If LHM needs elevation for GPU sensors, then the DEFAULT Agent's Tier-2 session is **duration only** and every one of those documents is wrong. Until it is measured, all three are worded *"whatever hardware telemetry this machine can provide"* — honest under either outcome, at the cost of vagueness. `18_GPU_VENDOR_APIS` §P0(b) already specifies the test and the dev box can run it |
| M6 ✅ | ~~Elevation-free Tier 2~~ | **Closed by decision 2026-08-27.** Half was answered on 2026-08-20 in the direction nobody expected: `PresentMonSharedService` is installed and `Running` as LocalSystem and the console **still** fails, because it starts its own trace session. The other half — whether `Performance Log Users` suffices without admin — stays unmeasured and now has no subject. **The elevation question does not disappear with the tool**: ETW trace sessions are restricted by Windows, not by PresentMon, so whatever §G chooses inherits it. Re-ask it there |
| M7 | `18_GPU_VENDOR_APIS` §Runtime policy says telemetry is never read from the game process, but `17_HOOK_ENGINE` reads per-process VRAM and Reflex latency there. Reconcile the wording — the rule means "no vendor SDK polling loops in the game", not "no measurement in the game" |
| M8 | The `GpuSample` type has no latency field, yet L3 is credited with Reflex/PC latency. Latency is per-frame and arrives via the ring, not the 1 Hz sample. Fix the layering description |
| M7 ✅ | ~~`18_GPU_VENDOR_APIS` §Runtime policy says telemetry is never read from the game process, but `17_HOOK_ENGINE` reads per-process VRAM and Reflex latency there. Reconcile the wording — the rule means "no vendor SDK polling loops in the game", not "no measurement in the game"~~ **Closed 2026-09-09 (PR-E1) by the code taking exactly that shape.** The rule is *no telemetry polling loop in the game*: the one 1 Hz loop is `TelemetryPoller` on the Agent's `fl-telemetry` thread, and it reads L1/L2/L3 only. Per-process VRAM stays an in-process read on the present path (`vram_proc`, `17_HOOK_ENGINE`), and PR-E1 measured why that must be so: `IDXGIAdapter3::QueryVideoMemoryInfo`'s `CurrentUsage` is the *calling process's* figure — 0 bytes from the Agent — so it is a measurement only where the game is. **Corrected 2026-10-03 (beta.12, D43): "only where the game is" holds for `QueryVideoMemoryInfo` and not in general** — the `GPU Process Memory` performance counters give any process's dedicated and shared GPU memory from outside it, with no handle, and the Agent reads them since that day (`18_GPU_VENDOR_APIS` §The game process's memory; `spike-notes` §16). The in-process read was never built. Adapter-wide usage is L1's PDH counter. §Runtime policy's sentence stands as written; this row is the reconciliation |
| M8 ✅ | ~~The `GpuSample` type has no latency field, yet L3 is credited with Reflex/PC latency. Latency is per-frame and arrives via the ring, not the 1 Hz sample. Fix the layering description~~ **Closed 2026-09-09 (PR-E1): the description now matches the type.** `GpuSample` has no latency field by design (its own remarks said so since 2026-09-03), `TelemetrySample` carries a 1 Hz reading stamped with QPC, and per-frame latency is `FlFrameRecord.reflexLatencyUs` in the ring. The §L3 table row "Reflex / PC latency" is an *in-process hook fact* the Overlay records (`SetSleepMode` / `SetLatencyMarker`, `17_HOOK_ENGINE`), never a poller field; `NvapiTelemetrySource` (PR-E2) will not call `NvAPI_D3D_GetLatency` |
| M9 ✅ | **Closed 2026-08-02 by a decision.** The old file/module detection does not exist in this repository and the owner confirmed there is no copy elsewhere, so **"build a minimal static-hint detector as the measurement baseline" is now P0 item 3** (`15_ROADMAP`). It needs no guard and no injection. Until it exists, ADR-7's headline claim stays out of the README rather than being asserted unmeasured |
| M10 | PDH `\GPU Engine(*)\Utilization Percentage` summed across engines does not reproduce the Task Manager figure the doc invokes. Decide what we actually report and label it accordingly |
| M10 ❓ | **§CPU — is the CPU temperature this build reads the right sensor, and does it read at all on the owner's machine?** `LhmCpuTemperatureReader` (2026-09-21) opens a CPU-only LibreHardwareMonitor `Computer` when the Agent is elevated AND `PawnIo.IsInstalled`, takes the package sensor (`CPU Package` / `Core (Tctl/Tdie)`) and falls back to the hottest core. It was written against LHM's sensor names and a fake `ILhmComputer`; **no elevated run with PawnIO has been taken.** | **The measurement is one session:** Agent elevated, PawnIO installed, a five-minute capture with HWiNFO or Ryzen Master open beside it. Pre-committed: `max_cpu_temp` within 3 °C of the reference's package peak → keep; a core sensor picked where a package sensor exists, or a reading tens of degrees off (a distance-to-TjMax sensor mistaken for a temperature) → fix `Pick` and re-run; nothing read at all → `cpu_temp` stays N/A and `legal/ACCURACY.md` says processor temperature is not measured. CPU **load** and memory are not in question: `TheRealCountersAnswerOnThisMachine` reads them on every gate run. |
| M11 🅓 | **The game's VRAM budget and `budget_exceeded_pct` (FR-4.5's second half), 2026-10-03.** D43 reads the game's usage from outside (the `GPU Process Memory` counters); the budget the OS grants the process is what DXGI's `QueryVideoMemoryInfo` returns to the *calling* process (§M7), so only an in-process call — the Overlay's background thread, which today only checks for a stop — or `D3DKMTQueryStatistics`' `PROCESS_SEGMENT_GROUP` query (documented "Reserved for system use") could read it. **Deferred by decision:** neither is built; `vram_budget_exceeded_pct` stays NULL and the budget N/A, and the in-process route would change what the Disclaimer says the Overlay's thread does. Reopening it needs that decision, not a measurement. | — |
| M10 ✅ | ~~PDH `\GPU Engine(*)\Utilization Percentage` summed across engines does not reproduce the Task Manager figure the doc invokes. Decide what we actually report and label it accordingly~~ **Decided 2026-09-09 (PR-E1): L1 does not read the engine counters at all.** `LoadPct` is L2's vendor-reported `GPU Core` load (measured ✓ on NVIDIA, §M5 row R1) and is labelled *GPU load (vendor)* wherever it is shown; on a machine without L2 the field is N/A, never a sum that is not the number the user expects. What L1 does read from PDH is one counter, `\GPU Adapter Memory(luid_…_phys_0)\Dedicated Usage`, bound by LUID — the figure Task Manager labels "Dedicated GPU memory", measured 1301 MB at an idle desktop on the RTX 5080. Reopening this needs a measurement of `max(engine)` against Task Manager's own number, not a decision |
#### §M5 — the decision table, pre-committed 2026-09-03 BEFORE the first run
@@ -3930,13 +4359,13 @@ Each of these is referenced by an existing doc but specified nowhere.
| Area | What is missing | Referenced by |
|---|---|---|
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
| **Session identity** | `sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`. Also: the `.partial` file format is undefined, and it is the crash-recovery artifact | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
| **Settings registry** | The `settings` table is key/value with no key list, defaults, types, or validation — and no message for the UI to push a changed setting to the Agent | `06_DATA_MODEL`, FR-10 |
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open *(corrected 2026-10-04: built in P3 PR-8b — `LogonTask` behind both flags, and start-with-Windows as the HKCU Run value)*. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) ~~elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator~~ **closed 2026-09-27 (beta.10, owner decision D34): chosen** — `capture.run_elevated`, a UAC prompt at every Agent start, the logon task's Agent asking through its own prompt, and with the option off an administrator's App starts the Agent with the shell's token (`01_ARCHITECTURE` ADR-9). "How elevation is requested and persisted" is that: requested by the prompt, persisted as one settings row and never as a task's run level | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
| **Session identity** | ~~`sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`.~~ **`sessions.session_guid` (UNIQUE) exists since 2026-09-09 (P2 PR-B), with `qpc_epoch` / `qpc_frequency` beside it.** ~~Still open: the `.partial` file format is undefined, and it is the crash-recovery artifact — PR-D's, pre-committed in HANDOFF §P2 (CRC-framed append-only chunks, the valid prefix wins)~~ **Built 2026-09-10 (P2 PR-D): `06_DATA_MODEL` §The `.partial` file, `PartialSessionFile` + `PartialRecovery`, killed at every byte in the merge gate.** ~~What stays open here is the pipe's use of the guid (P3)~~ *(built in P3 PR-1/1b: the session events and `StopSession` carry `SessionGuid` — corrected 2026-10-04)* | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
| ~~**Settings registry**~~ | ~~The `settings` table is key/value with no key list, defaults, types, or validation — and no message for the UI to push a changed setting to the Agent.~~ **Decided 2026-09-13 (HANDOFF §P3 decision D16)**: the key list with defaults and ranges, and *no* push message — the Agent re-reads its keys at each session start. **Built the same day (P3 PR-3):** `06_DATA_MODEL` §Settings registry (12 keys), `Application.Settings.SettingsRegistry` + `RegisteredSettings` (validating writes, tolerant reads), `SettingsRecorderPolicy` resolving `capture.min_session_s` / `telemetry.interval_ms` / `retention.raw_sessions_per_game` at each session start. **Row closed** | `06_DATA_MODEL`, FR-10 |
| **Error taxonomy** | `07_IPC` lists `CaptureError` codes; no canonical mapping to resx keys and user-facing text, though `09_I18N` requires safety strings to be reviewed as legal text | `07_IPC`, `09_I18N` |
| **Threading model** | Which component owns which thread, UI-thread rules, and how the 1 Hz telemetry poller, 10 Hz drain and pipe reader interact | `04_CAPTURE`, `18_GPU_VENDOR_APIS` |
| **Pipe/shm security** | Stated as policy ("DACL granting the current user's SID") but not as implementable SDDL, nor who creates the objects with what rights | `07_IPC` |
| **Legal doc versioning** | FR-11 re-shows documents "when a document version increments". Nothing says where the current version lives, who writes `legal_acceptance.version`, or how the markdown is rendered in-app | FR-11, `06_DATA_MODEL` |
| ~~**Threading model**~~ | ~~Which component owns which thread, UI-thread rules, and how the 1 Hz telemetry poller, 10 Hz drain and pipe reader interact~~ **Answered 2026-09-09 (P2 PR-C): `04_CAPTURE` §Threading model** — four threads, one owner per shared object, the pipe reader named as one more producer. This row was not struck when the section was written; struck 2026-09-13. What is still unspecified is the UI thread's own rules, which is `08_UI`'s in P3 | `04_CAPTURE`, `18_GPU_VENDOR_APIS` |
| **Pipe/shm security** | Stated as policy ("DACL granting the current user's SID") but not as implementable SDDL, nor who creates the objects with what rights. The shm half is built (`fl_shm_host.h`, the Overlay creates the section under the current user's SID); the pipe half is **built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D11)**: `D:P(A;;GA;;;<user>)(A;;GA;;;BA)` (with the owner `O:<user>` stated since 2026-09-17, `07_IPC` §C) handed to `CreateNamedPipe` with `PIPE_REJECT_REMOTE_CLIENTS`, and the client's token user compared by impersonation on its first frame (`Infrastructure.Ipc.PipeAccessControl`, pinned by `PipeServerClientTests` including the refused stranger). **Row closed** | `07_IPC` |
| ~~**Legal doc versioning**~~ | ~~FR-11 re-shows documents "when a document version increments". Nothing says where the current version lives, who writes `legal_acceptance.version`, or how the markdown is rendered in-app~~ **Answered 2026-09-14 (P3 PR-9):** the version is the document's own `**Version:**` line, read from the copy embedded in the App at build (`App.Services.LegalDocuments`); the App writes `legal_acceptance.version` on the one Accept and re-shows any document whose embedded version differs from its row; ~~the markdown is shown as text with authoring comments stripped, not rendered~~ the markdown is shown with authoring comments stripped and, since beta.12, rendered (`08_UI` §Menu, *Documents are rendered*; §First-run flow built note) | FR-11, `06_DATA_MODEL` |
| **Accessibility / DPI** | NFR-9 states requirements; no design anywhere | NFR-9, `08_UI` |
| **Uninstall / data deletion** | One Velopack clause. No in-app "delete all my data", despite the privacy position | `12_BUILD`, `legal/PRIVACY_POLICY.md` |
| **Cover art** | Appears in the schema, the data directory and the UI; nothing says where it comes from or the licence position on downloaded store art | `06_DATA_MODEL`, `05_DETECTION` |
@@ -3951,7 +4380,9 @@ the guard is **item 0**, the Vulkan passthrough test is **item 1**, the two
licence checks were run first and came back clear (`spike-notes.md` §0), and
P0's exit criteria no longer import P2 work — the FPS-impact measurement moves
to the end of P1, while the harness-level per-present cost (no game, no Agent,
no drain) stays in P0. Items 5–9 below are still open.
no drain) stays in P0. ~~Items 5–9 below are still open.~~ *(Corrected 2026-10-04: 5 and 6 are deferred, 🅓 below; 7
is moot — `ci.yml` has gated every PR since bootstrap; 8 is history, P1 having closed; 9 stays open — no `ja` string has
been reviewed, an owner-only item.)*
5. **P0 item 5 asks for an AFMF decision on an RTX 5080.** AFMF is AMD driver
-side. Reword to "validate on NVIDIA; record AFMF as untested", per the
precedent `14_TESTING` already sets for absent hardware.
@@ -4003,9 +4434,9 @@ no drain) stays in P0. Items 5–9 below are still open.
| Named where | Artifact | State |
|---|---|---|
| `12_BUILD:139`, `13_CI_CD:11`, `09_I18N:28`, `CLAUDE.md:66` | `tools/resx-audit` | Absent. **Honestly handled** — `build.ps1:309` skips it loudly with a reason, and no `.resx` files exist yet |
| `12_BUILD:139`, `13_CI_CD:11`, `09_I18N:28`, `CLAUDE.md:66` | `tools/resx-audit` | ~~Absent. **Honestly handled** — `build.ps1:309` skips it loudly with a reason, and no `.resx` files exist yet~~ **✅ Built 2026-09-13 (P3 PR-2)**, a `build.ps1` step (marked 2026-10-04) |
| `12_BUILD:136`, `13_CI_CD:11` | the managed **struct-mirror** test | ~~Absent. Nothing under `tests/` references `FlFrameRecord`.~~ **✅ Built in #47** — `ShmLayout.cs` + `ShmLayoutMirrorTests`, driven by `fl-layout-dump`'s JSON rather than a transcribed table, asserting blittability as well as offsets, and walking the field list in both directions. `build.ps1`'s gate now reads the run's `.trx` and fails when the class did not execute, so **deleting the test is red too** — it used to `Test-Path` a source file |
| `13_CI_CD:21`, `12_BUILD:121`, `CHANGELOG:9` | `.github/workflows/release.yml` | Absent. `CHANGELOG`'s header instructs an author to write for a consumer that does not exist |
| `13_CI_CD:21`, `12_BUILD:121`, `CHANGELOG:9` | `.github/workflows/release.yml` | ~~Absent. `CHANGELOG`'s header instructs an author to write for a consumer that does not exist~~ **✅ Built 2026-09-14 (P4 PR-5)**; it published beta.1 through beta.11 (marked 2026-10-04) |
| `12_BUILD` §Local quality gate | gates omitted from the list | ~~**Three documents give three different counts, which is the finding.** `build.ps1` has **15** `Write-Step` calls as of 2026-08-05 (14 before this PR's `changelog-check`); `12_BUILD` lists 10; this row said 13.~~ **Corrected 2026-08-06: `build.ps1` has 17 `Write-Step` calls** (`package-closure` added two), and `12_BUILD`'s list is rewritten to 16 numbered entries — the difference is that `Invoke-Native`'s three steps run under one heading there. `13_CI_CD` no longer restates the list at all; it points at `12_BUILD`, because restating it in two places is what let one of them rot. **Nothing still derives the list from the script**, so the drift is slowed rather than stopped, and this row remains open for that reason. **And it drifted again, exactly as predicted — re-counted 2026-08-28.** `hookinventory-check` had reached `build.ps1` and never reached the list; `frametype-oracle` had reached both and then been deleted with PresentMon, so the two errors happened to cancel and the *totals* matched while the *membership* did not — the same coincidence §S24's own recount was caught by. The list is rebuilt to **17 entries against 17 `Write-Step` calls, in script order** (re-deriving the order caught a second defect: two adjacent entries had been transposed relative to the script). **The row still does not close.** Aligning by hand is what was done in 2026-08-06 and again here; it lasts until the next gate lands. The fix is a gate that reads the `Write-Step` names out of `build.ps1` and fails when the list disagrees — until it exists, re-count rather than trusting the number |
The struct-mirror row is the one that matters. `CLAUDE.md` §Struct mirroring
+907 -16
View File
File diff suppressed because it is too large. Load diff
+74
View File
@@ -0,0 +1,74 @@
# Games FrameLedger has been run with
*As of 2026-09-27 (0.1.0-beta.10). 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.)*
**The machine.** Every row below was run on one PC: an NVIDIA GeForce RTX 5080 (the only graphics card), an Intel Core
i7-14700KF, 32 GB of DDR5, Windows 11 (Insider builds 26300 → 29648) and a 2560×1440, 240 Hz monitor. **No AMD or Intel
graphics card and no second machine has been tested**, and **no real Vulkan or OpenGL game has been measured** — every
measurement below is Direct3D 11 or 12. What the tiers mean and what FrameLedger cannot do: [LIMITATIONS.md](../LIMITATIONS.md).
**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 — earlier ones went
with the 2026-09-16 recovery and with library entries removed since.
## 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 | 2026-08-15 → 09-05, about 25 runs | [spike-notes §8, §9, §11](spike-notes.md) |
| 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* | 2026-09-04 → 09-06 | [spike-notes §9](spike-notes.md) |
| 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* | 2026-08-03 → 09-16 | [spike-notes §7, §9, §14](spike-notes.md) |
| 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); DLSS *driver-reported*; ray tracing *Yes* | 2026-09-25 | database |
| DARK SOULS III | FromSoftware | D3D11 | Presented 59.8 FPS; no upscaler, frame generation or ray tracing loaded | 2026-09-03 | [spike-notes §9](spike-notes.md) |
| Sekiro: Shadows Die Twice | FromSoftware | D3D11 | Presented 60 FPS (the game's cap), two sessions of 15 min and 2 h 18 min | 2026-09-26 | 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 | 2026-09-21 → 09-27 | 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 |
## Recorded without measurement (Tier 2)
| Game | Why nothing was measured | When | Evidence |
|---|---|---|---|
| HELLO, HELLO WORLD! | A 32-bit game (RPG Maker MV): refused by the guard once, and two sessions with hooking switched off — each recorded with its duration and sensors | 2026-09-23 | database |
| Umamusume: Pretty Derby | Three sessions played with hooking switched off for the game | 2026-09-27 | database |
| Sekiro: Shadows Die Twice | One session played with hooking switched off | 2026-09-25 | database |
| GIRLS' FRONTLINE 2: EXILIUM | One session whose process Windows would not let FrameLedger open, and two recovered after the agent itself stopped mid-session (*interrupted*) | 2026-09-22 → 09-23 | database |
## 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) |
| 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))
+84
View File
@@ -0,0 +1,84 @@
# 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) and the traps that each cost a cycle. It carries no status on purpose |
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE) |
**Status lives in four places, and nowhere else** — check a status claim against the code before you plan on it:
| Question | File |
|---|---|
| What is unresolved, and what does it block? | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) |
| What was measured, on what machine? | [`spike-notes.md`](spike-notes.md) |
| Which phase is where? | [`15_ROADMAP.md`](15_ROADMAP.md) |
| What landed, in which release? | [`../CHANGELOG.md`](../CHANGELOG.md) |
What the software promises users is the accuracy block in [`../legal/ACCURACY.md`](../legal/ACCURACY.md), copied
verbatim into the README and the Disclaimer and bound to its source by `tools/accuracy-check.ps1`.
## Reading order
1. [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) — the guard, the refusal list, what will not be built. It
constrains everything else.
2. [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) — processes, the injection flow, lifecycles, the ADRs.
3. [`02_SPEC.md`](02_SPEC.md) — the FR / NFR ids used everywhere.
4. [`03_METRICS.md`](03_METRICS.md) — the metric math; the source of truth for every number shown.
5. [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) — the C++ hook layer inside the game.
6. [`04_CAPTURE.md`](04_CAPTURE.md) — capture orchestration on the Agent's side.
7. [`05_DETECTION.md`](05_DETECTION.md) — engine, upscaler, frame-generation and ray-tracing facts.
8. [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) — layered telemetry, the game process's memory, vendor-SDK licence rules.
9. [`06_DATA_MODEL.md`](06_DATA_MODEL.md) · [`07_IPC.md`](07_IPC.md) · [`08_UI.md`](08_UI.md) ·
[`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md)
10. The rest: [`09_I18N.md`](09_I18N.md), [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md),
[`11_UPDATER.md`](11_UPDATER.md), [`12_BUILD.md`](12_BUILD.md), [`13_CI_CD.md`](13_CI_CD.md),
[`14_TESTING.md`](14_TESTING.md), [`15_ROADMAP.md`](15_ROADMAP.md).
**Before you write native or capture code, read [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md):** its S-series items
are safety items, and something listed there as unresolved should not be built the way an older document describes it.
## Every document, in one line
| Document | What it is for |
|---|---|
| [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) | The processes (App, Agent, Overlay, Vulkan layer), how injection flows, the architecture decisions |
| [`02_SPEC.md`](02_SPEC.md) | Functional and non-functional requirements, by id |
| [`03_METRICS.md`](03_METRICS.md) | How every number is computed: frame times, lows, stutter, frame generation, display mode, the game's memory, sensor statistics, the export schema |
| [`04_CAPTURE.md`](04_CAPTURE.md) | The Agent's capture loop, the tiers, finalizing and recovery, the threading model |
| [`05_DETECTION.md`](05_DETECTION.md) | Detecting engines, platforms and capabilities; the detection rules |
| [`06_DATA_MODEL.md`](06_DATA_MODEL.md) | The SQLite schema, every migration, who writes what, retention |
| [`07_IPC.md`](07_IPC.md) | The shared-memory ring between the game and the Agent, and the named pipe between the Agent and the App |
| [`08_UI.md`](08_UI.md) | Every screen of the App, as specified and as built |
| [`09_I18N.md`](09_I18N.md) | English / Vietnamese / Japanese strings, the glossary, the safety-string review rule |
| [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md) | Logs in every process, the bug-report bundle, redaction |
| [`11_UPDATER.md`](11_UPDATER.md) | Velopack updates from GitHub Releases, and when an update may apply |
| [`12_BUILD.md`](12_BUILD.md) | The toolchain, the build, the quality gate step by step, publishing and packaging |
| [`13_CI_CD.md`](13_CI_CD.md) | The CI and release workflows |
| [`14_TESTING.md`](14_TESTING.md) | The test strategy, hook overhead, the hardware matrix |
| [`15_ROADMAP.md`](15_ROADMAP.md) | The phases and where each stands |
| [`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md) | WPF UI (lepoco) rules, theming, rendered documents, gotchas |
| [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) | The hooks inside the game: inventory, fault policy, the ring writer, Vulkan |
| [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) | Telemetry layers (DXGI/PDH, LibreHardwareMonitor, NVAPI), the game process's memory, licences |
| [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) | The anti-cheat guard, what a finding does, the user-mode exception, what will never be built |
| [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) | Every unresolved question, defect and measurement, with its status marker |
| [`HANDOFF.md`](HANDOFF.md) | Sequencing, the owner's decisions, traps |
| [`spike-notes.md`](spike-notes.md) | What was measured, how, on which machine, and what each result decided |
| [`LIST_GAME_TESTED.md`](LIST_GAME_TESTED.md) | The real games FrameLedger has been run with, and what each session measured (changes need the owner's review) |
| [`legal-drift-history.md`](legal-drift-history.md) | How the legal documents once drifted from the software, and the maintainers' notes moved out of them |
| [`vendor-exports.json`](vendor-exports.json) | The vendor DLL exports the hooks are allowed to bind, checked by `tools/vendor-exports` |
## Beside this folder
- [`../guide/`](../guide/README.md) — the user guide (players, English).
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
texts, the trademark note.
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
- [`../rules/detection-rules.json`](../rules/detection-rules.json) — engine, platform and capability signatures and the
anti-cheat blocklist, validated by `tools/rules-validate.ps1`.
+70
View File
@@ -0,0 +1,70 @@
# How `legal/` drifted from the software, 2026-08-04 → 2026-09-15
The block below lived at the top of `legal/DISCLAIMER.md` — inside the text a user accepts at first run — from
2026-08-04 until 2026-09-16, when it moved here unchanged. It is the record of six re-counts of that document's
promises against the code, in both directions, and of the mechanism that ended the drift: one accuracy statement
(`legal/ACCURACY.md`) embedded in `README.md` and `DISCLAIMER.md` §4 and bound to its source by
`tools/accuracy-check.ps1` (`docs/20_OPEN_QUESTIONS.md` §S23-6). It is kept because the pattern it records —
half a mechanism reading as a whole one, an under-claim going unnoticed because everyone was watching for
over-claims — is the pattern the next reviewer of `legal/` will meet. Nothing here is normative; the current
statement is `legal/ACCURACY.md`, dated.
> ⚠ **Accuracy audit — re-checked 2026-08-14, a FOURTH time, after PR #64. SIX statements below describe behaviour the software does not yet fully have**, and they are flagged here rather than quietly reworded because a document the user accepts must not over-promise.
>
> **A FIFTH time, 2026-09-06, and the mechanism changed rather than the count.** Every drift this block records came from the same cause: the sentence about what the software measures lived in three places and was re-read in none of them. It now lives in **one** — `legal/ACCURACY.md`, embedded verbatim in §4 below and in `README.md`, and `tools/accuracy-check.ps1` fails the build when a copy differs from the source (`20_OPEN_QUESTIONS` §S23-6). The bullets below are the history of the four drifts and are kept as history; the block in §4 is the current statement, dated.
>
> **A SIXTH time, 2026-09-15, and the drift ran the safe way again.** The block in §4 is re-dated and rewritten against the code: OpenGL is measured, the shipped Agent runs the in-session re-scan, the whole-card video memory is recorded, and the Vulkan, preset, FSR-version and frame-generation sentences say exactly what the code does. Two bullets below became false because the software caught up with them, and they are struck where they sit. Version 2.1-draft, so the first-run gate shows this document again.
>
> **The fourth drift is the first one that ran the other way, and that is the finding.** Every previous re-count found this document claiming *more* than the software did. #64 landed the upscaler identity hook and this block went on saying "there is no upscaler hook anywhere in the software" — an under-claim, in the one file whose failure mode everybody was watching for in the opposite direction. It went unnoticed for five days for exactly that reason: a reviewer checking whether `legal/` over-promises reads a sentence like that and moves on. **Re-reading this block means checking both directions.**
>
> **The re-count was overdue and this block's own rule is what says so.** The last line of this block requires whoever changes what `FrameLedger.Overlay` does to re-read it. #48 changed exactly that — the Overlay now drops `DXGI_PRESENT_TEST` presents without recording them — and this block was not re-read. That is the second time the rule has been broken since it was written, and both breaches were invisible from inside the PR that caused them.
>
> **Two additions this round, both about what the software claims to *measure*** — the class the project has already had to retract twice:
>
> **Two bullets changed substance and neither could be struck.** The capture side that *receives* a stop now exists and now runs whether or not the game is presenting; the side that would *send* one still does not. That is the pattern to watch for when re-counting: half a mechanism reads as a whole one, and the half that is missing is usually the one nobody was looking at.
>
> - ~~§1's *"what it observes: … presentation, upscaling, ray tracing, pipeline creation"* and §4's *"upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs"* — **only the presentation path is intercepted.** There is no upscaler hook, no frame-generation hook, no ray-tracing hook and no pipeline hook anywhere in the software.~~ **FALSE SINCE #64, corrected 2026-08-14 — the fourth drift, and this one is the block's own subject.** An **upscaler hook exists**: one detour on `sl.interposer.dll!slEvaluateFeature`, module-scoped, reading one argument. It measures **which upscaler is running** (DLSS, NIS, or `unknown` — never "none") and, for Streamline titles, **whether Ray Reconstruction is active**, which is a `Yes`/`No` the software now publishes. What still does not exist: quality preset, render resolution, frame generation, ray tracing, pipeline. The capture side states all of that in its own data on every frame rather than defaulting to "none", so nothing false is *recorded*; what over-promised was this document, in the direction of under-claiming rather than over-claiming — which is the safer direction and is still wrong. Both sentences are qualified where they sit.
> - ~~§2's *"and every 30 seconds afterwards … it stops at the next scan"* — the pre-injection guard is real and refuses. The **receiving half is implemented**: an injected D3D title removes its hooks within one frame of the stop flag being set. The **sending half is still missing, and the missing part is narrower than this block used to say.** Both the write path (`ShmRingReader.PublishGuardResult`, which maps the shared memory and advances the field) and the read path exist in shipped code and are tested; what does not exist is a production caller that runs the loop between them. A missing loop, not a missing subsystem — and the user-facing consequence is identical: **no re-scan runs and no stop is ever sent.**~~ **FALSE SINCE 2026-09-10 (P2 PR-F), struck 2026-09-15:** the shipped Agent drives the loop — during every capture it re-runs the checks every 30 s and sends the stop on a refusal (`legal/ACCURACY.md`, embedded in §4).
> - §2's *"waits **65 seconds** before concluding that contact is lost"* — **the deadline now has a reader, and since 2026-08-05 it runs whether or not the game is presenting.** For one day it was evaluated only on a present, so a title that had hung or been alt-tabbed never reached it — the exact case the mechanism was specified for. A watchdog inside the injected component now checks once a second regardless. Two qualifications remain: for **Vulkan titles the check runs on each present rather than once a second** — the layer may not own a thread, so a Vulkan title that has stopped presenting is not stopped by the deadline (and presents nothing to be observed) — and **the 65-second value itself is not covered by a test** — the stop is proven to fire, but a suite that runs on every build cannot wait 65 seconds, so what is verified is the mechanism, not the number.
> - ~~§3's *"automatically stops injecting into a game that crashes shortly after injection twice"* — the only trace of this anywhere is a `hook_crash_count` column in a schema for which no `.sql` file exists. There is no design for it.~~ **BUILT 2026-09-10 (P2 PR-D), struck 2026-09-15:** two crashes of the same game within 60 s of injection disable hooking for that game, with the reason on its row (`CrashAutoDisablePolicy`).
> - §1's *"Only FrameLedger's own component is ever loaded"* — **narrower than it sounds, and the qualification is now in §1 itself.** The check is a directory test: the payload must resolve into FrameLedger's own install directory. It does not compare a filename, a version or any content, deliberately — a name check would be defeated by any DLL that borrowed the name. A published self-contained build puts several hundred files in that directory.
>
> **None of this may ship as-is.** Either the behaviour exists at first release or these sentences change. Tracked in `docs/20_OPEN_QUESTIONS.md`.
>
> **This block is maintained by hand and nothing verifies it.** Every other document here is bound to the code by something — `rules-validate` cross-checks the blocklist, `static_assert`s bind `fl_shm.h` to `07_IPC`, `versioninfo-check` and `chokepoint-check` bind claims to binaries. `legal/` is bound by nothing, and it has now gone stale **three times**: first within hours of being written, when the 65-second sentence was added directly beneath a header that said "Three"; then again when five PRs (#40–#44) changed the Overlay from a stub into a hooking, shared-memory-mapping, control-block-reading component and touched **no documentation at all**, leaving the second bullet above asserting four things about that binary that were each false. and a third time when #46–#52 landed — seven PRs, including one (#48) that changed what the Overlay does *inside a game* — with no edit here at all. None of the three drifts was visible from inside the PR that caused it. **Whoever edits any promise in this file must re-count — and whoever changes what `FrameLedger.Overlay` does must re-read this block, because nothing will remind them.**
>
> **That sentence has now failed twice, so it is being replaced by something that is not a sentence.** `ci.yml` fails a pull request that touches `src/` without touching `CHANGELOG.md`. That is a weaker gate than the ones binding every other document — it forces a *ledger* entry, not a re-read of *this* file — and it is written down as weaker rather than described as a fix. A gate over the claims in `legal/` would have to assert things about behaviour rather than about files, and nobody has designed one (`docs/20_OPEN_QUESTIONS.md` §S23-6).
---
## Moved out of the accepted documents on 2026-10-03 (beta.12: Disclaimer 2.10, Privacy Policy 2.6)
The three blocks below were notes for the documents' maintainers inside texts a user accepts. They moved here unchanged
when the user guide (`guide/`) and a rendered Legal Gate made those documents read as what they are — terms — and they
are kept because they record what each version changed and why (owner decision D45).
### The Disclaimer's preface (versions 2.3–2.9)
> **How this document is kept true.** The statement of what FrameLedger measures (§4) is `legal/ACCURACY.md`,
> embedded here and in `README.md` and bound to its source by `tools/accuracy-check.ps1`, which fails the build when a
> copy differs. Earlier versions of this document carried a hand-maintained audit of how its own promises drifted from
> the software — six re-counts between 2026-08-04 and 2026-09-15; that history is `docs/legal-drift-history.md`,
> moved out of the text you accept on 2026-09-16 and kept in full.
### The Privacy Policy's §2 history note (versions 2.2–2.5)
> **History.** Versions 2.0 and 2.1 of this document listed three further rows — a weekly safety-list update, a weekly detection-rules update, and an opt-in Steam store lookup — describing requests the software did not make; from 2026-08-04 they carried an audit note saying so. Version 2.2 (2026-09-16) removes them. A privacy policy that lists a transmission which never happens is as wrong as one that omits a transmission which does.
### The Privacy Policy's §4 history note (versions 2.3–2.5)
> **History.** Version 2.3 (2026-09-23) adds the per-entry recording switch. Before it, every program in your library was recorded whenever it ran, which recorded a utility that starts with Windows at every boot.
>
> Version 2.4 (2026-09-25, 0.1.0-beta.8) names what the software reads to check every game in your library for anti-cheat — until then it checked only a game you asked to hook — and to name the versions of its files, and the NVIDIA driver's settings for your games. The files of a library game's folder were already read to detect its engine and features; this version is the first to say so.
>
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
### What version 2.6 of the Privacy Policy changed
It names the game's own memory use (since beta.12, read from outside the game in every session) where version 2.5
named "video-memory usage reported by the graphics runtime" — an in-game figure the software never read — and adds
§3A: what an export or a bug report can carry about you before you share it.
+254 -6
View File
@@ -312,8 +312,20 @@ offline retires the route, and §S19(b)'s row G2 says so before the run.
yields no organisation — so a green result discriminates rather than merely running.
`fl-baseline-probe` was retired by exactly this class of test.
**Not measured here:** the CI leg (a different machine stages a different copy), and
the adapters-disabled leg. Both have pre-committed rows. An unrun leg is unrun.
~~**Not measured here:** the CI leg (a different machine stages a different copy), and
the adapters-disabled leg. Both have pre-committed rows. An unrun leg is unrun.~~
**The CI leg, 2026-09-06** (the ctest printed nothing for eleven days; `ci.yml` now runs the
probe as a step): `windows-latest`, elevated. Blocker copy from the runner's NuGet cache,
6.0.0, embedded/offline `ERROR_SUCCESS` 3.47 ms, `O= Microsoft Corporation`, no catalog;
`mskeyprotect.dll` embedded `TRUST_E_NOSIGNATURE`, catalog `ERROR_SUCCESS`; `kernel32.dll`
both; cold 3.45 / warm 3.53 ms; `cryptnet.dll` newly loaded under the offline flags; canary
`TRUST_E_NOSIGNATURE`; *"G1 is a CANDIDATE"*. Rows G3, G4, G5 do not fire.
**The adapters-disabled leg, the owner's run, 2026-09-06** (dev box, elevated): every verdict
unchanged — `kernel32.dll` both `ERROR_SUCCESS`; `mskeyprotect.dll` embedded `TRUST_E_NOSIGNATURE`,
catalog `ERROR_SUCCESS`; the blocker embedded `ERROR_SUCCESS`, `O= Microsoft Corporation`, subject
now `CN=.NET` (the August copy read `CN=Microsoft Windows`; same `O=`); cold 2.14 / warm 2.15 ms;
`cryptnet.dll` mapped; canary `TRUST_E_NOSIGNATURE`. **Row G1 reads**; the bound decision is the
owner's before anything is built.
### Still open
@@ -323,6 +335,9 @@ the adapters-disabled leg. Both have pre-committed rows. An unrun leg is unrun.
loads a presentation runtime lazily, and the only local fixtures are
`hook-harness` (creates D3D at startup) and a 2D GOG prologue. A number from
those would not generalise, which is worse than recording it as unmeasured.
*(2026-09-06: built as "inject late" — P1 item 2 — and the number now comes
from every launched session, as `dxgiPresentsBeforeHook` plus the reported
wait. `20_OPEN_QUESTIONS` §S1.)*
### ✅ Signer field for the unknown-but-suspicious heuristic — **`O=`, not `CN=`**
@@ -428,6 +443,31 @@ the same shape as defects found elsewhere in this project:
The unambiguous signal is the loader printing `Insert instance layer` /
`Inserted device layer` with our name and DLL path.
### ✅ `VK_ADD_IMPLICIT_LAYER_PATH` is honoured, and it needs no registry (2026-09-06, P1 item 3)
Measured against the same loader 1.4.357 with `vulkaninfo --summary` and `VK_LOADER_DEBUG=layer`: with
`VK_ADD_IMPLICIT_LAYER_PATH` pointed at the build tree's `FrameLedger.VkLayer` directory and
`FRAMELEDGER_ENABLE_VK_LAYER=1`, the loader prints `Insert instance layer "VK_LAYER_FRAMELEDGER_overlay"
(…\FrameLedger.VkLayer.dll)` and `Inserted device layer …` — the unambiguous signal above — with nothing
under `HKCU` or `HKLM`, and `vulkaninfo` exits 0 with the layer inert (no enable-list entry for it). The
first run's `grep … | head` cut the log before the `Insert` lines and read as "found, not inserted"; the
lines are at the instance-creation point, ~850 lines in. So the operator host launches Vulkan titles with
no registration at all, and the real-loader ctest (`fl_vklayer_real`) does the same: the harness's
`--vulkan` mode presented 241 frames in 4 s on a hidden 240-wide window and the layer recorded every one.
### ✅ On NVIDIA a Vulkan swapchain presents through DXGI — and the DXGI hook sees it (2026-09-06)
Found by the first end-to-end run of `launch` on the harness's `--vulkan` mode: the guard's poll saw
`dxgi.dll` + `d3d12.dll` (the fixture imports d3d11/dxgi; but the NVIDIA Vulkan ICD `nvoglv64` maps them
too) and injected the Overlay, whose `Present` hook then recorded **295 DXGI presents in 5 s with
`apiMask = D3D12` and DXGI's counter agreeing (248 samples, 0 unseen)** — the Vulkan swapchain's own
presents, made by the driver on an internal DXGI flip-model chain. So on this driver the injected Overlay
*can* measure a Vulkan title's presents; that is a driver property, not a portable one (AMD's and Intel's
WSI need not do it), which is why the layer stays the capture side. Two consequences landed: the
launch-mode guard now classifies **any** process that mapped `vulkan-1.dll` as the layer's, and the
harness's `--vulkan` mode maps the loader before anything else so the fixture looks like a real Vulkan
title to the first poll.
### ✅ The in-layer blocklist scan — §S2's second half
The layer scans its own process at init and goes fully passthrough on any hit,
@@ -1913,6 +1953,32 @@ one launch per capture, consent granted after launch. Exit codes and full report
patches cover; the bypass measured on Dying Light: The Beast is that title's integration. With this row
every measured NVIDIA title prints the rule-6 trio or a counted `none`, and the owner closed the item.
- **2026-09-06, 12:46, Lies of P at FSR 3.1 + FSR frame generation, on the #129 build — §H11 row A1 again,
now with every witness on the page.** `upscaler: Fsr3`, `render -> output: 2560x1440 -> 2560x1440 = 1x` on
3,538 records, `frame generation: FsrFg`, `Native FPS: 59.77 -> Displayed FPS: 119.55 (x2 FG)` over 7,042
presents; the ffx census `upscale-drained=3518 fg-dispatch-drained=3518 frames=3520`, `presents/frame=2.00`,
`frames/upscale-drained=1.00`; `DXGI present counter: unseen=0 over samples=7096` (the FSR 3.1 pacer presents
through the patched body); the NVIDIA driver's word `SR 0x5` / `FG 0x90001` — nothing created, so the
driver-reported rung correctly says nothing beside an AMD identity. The census names only
`amd_fidelityfx_dx12.dll` (the 3.1 monolith Lies of P calls) — the AMD half of 7c is complete on its oracle.
Same run, Rune Factory at DLSS + FG ×4: `125.45 → 498.51 (×3.97)`, `Dlss (driver-reported)`, `DlssG` with the
driver agreeing — the 7b title on its NVIDIA path.
- **2026-09-06, 13:45–14:02, the owner's run on #132 (rung 3 by elimination + the executable scan): Cronos at
XeSS (no FG option), Hell Is Us at XeSS + XeSS-FG, Rune Factory at FSR + FSR FG.**
| Title / setting | Line | `frame generation:` | `executable markers:` |
|---|---|---|---|
| **Cronos**, XeSS, no FG | `FPS: 110.02`, `none` by count, DXGI agrees | `None` | ffxFrameInterpolation ×1, NVSDK_NGX ×112, xefgSwapChain ×13 |
| **Hell Is Us**, XeSS + **XeSS-FG** | `Presented FPS: 186.47`, **`tokens=0`**, `unseen=0` | N/A — no token on this plugin at XeSS; witnesses: not DLSS-G, no FSR dispatch, runtimes nvngx_dlssg + libxess_fg + amd FG, file carries xefgSwapChain | same set |
| **Rune Factory**, FSR + **FSR FG** (compiled in) | `30.05 → 60.05 (×2 FG)` from the token, `unseen=0` | `Active (technology not identified) — by elimination …; the executable itself carries ffxFsr3, ffxFrameInterpolation` | ffxFsr3 ×13, ffxFrameInterpolation ×9, NVSDK_NGX ×112 |
Three readings. Rune Factory is the pre-committed 7b line, verbatim. XeFG presents through the patched
body (0 unseen) so its Displayed rate is measured; its Native is not, because Hell Is Us's plugin requests
no Streamline token at XeSS (it does at DLSS, and Cronos's does at XeSS) — the count producer is the
plugin's choice, and nothing in policy replaces it. The Steam overlay could not show FG on that session
either. The upscaler N/A on both XeSS titles now names Intel's licence as the reason (7c item 4).
## 10 · Telemetry layering
- L1 baseline vendor-neutral:
@@ -2365,16 +2431,25 @@ produced no false refusal on any real install.
`15_ROADMAP` §P0. Nothing in P1 starts until all are met.
- [ ] A throwaway build records a real session from a real offline game
- [x] A throwaway build records a real session from a real offline game
reporting **correct** upscaler, quality preset, render → output
resolution, FG factor and RT state — verified against the game's own
settings menu.
settings menu. **Met 2026-09-06 with one amendment, the owner's:** the
quality preset reads `N/A` on every title, by measurement — Streamline's tags
carry no size or preset on Direct3D 12, NVIDIA's override fields are the
override's, XeSS is closed by licence — and an honest `N/A` where measurement
is impossible is the *correct* value CLAUDE.md rule 7 asks for. Upscaler,
render → output (where the vendor's call carries it), FG factor and RT state
are verified against the menus of nine titles (§9). The owner closed 7a on
this reading and closed P0 on it here.
- [x] **Moved to the end of P1** (§R4, decided 2026-08-02) — ~~measured game FPS
impact under 0.5%~~. As written it imported P2's drain, aggregate and
recorder paths; the harness-level per-present cost stayed in P0 and is
measured in §3 (8.4 ns).
- [ ] Every S-series item in `20_OPEN_QUESTIONS.md` resolved, or explicitly
deferred with a written rationale.
- [x] Every S-series item in `20_OPEN_QUESTIONS.md` resolved, or explicitly
deferred with a written rationale. **Met 2026-09-06** (§S24: zero counted
against it). 🚫 S23-2 is a branch-protection setting outside any PR and is
recorded as such, not as met.
- [x] M3 and M4 answered **before** any NVAPI or LHM code is written — both
CLEAR, §0 above.
@@ -2382,3 +2457,176 @@ produced no false refusal on any real install.
> 2026-08-02** — the FPS-impact criterion moved to the end of P1, and the
> harness-level per-present cost stayed in P0 as item 2. This file went on asking
> for a decision that two other documents had already recorded.
---
## 14 · The P2 milestone and the FPS-impact run *(slots — the owner's runs)*
**Nothing below has been run** *(written 2026-09-10; §14.1's row half is read 2026-09-16 — see there — and §14.2–14.4 are
still unrun)*. The section exists because P2's code is finished and its two
remaining obligations are measurements a script cannot take: a real title, read against its own
settings menu, and a benchmark whose number only the operator can see. Written as empty slots with
the exact commands rather than left absent, so the next session cannot mistake "not measured" for
"not required" — the failure mode this file's own rules name first.
### 14.1 · The milestone session — Tier 1, a real title, against its menus
`15_ROADMAP` §P2: *"first real hooked session persisted with measured upscaler/RT data."*
**The technical half is met and is in the merge gate (2026-09-10, P2 PR-F):**
`AgentEndToEndTests` runs the shipped `FrameLedger.Agent.exe --console capture --exe hook-harness.exe`
and reads back one `sessions` row — tier 1, `d3d11`, > 100 frames, `guard_ticks_published ≥ 1`, the
blobs beside it, no `.partial` left. What the harness cannot supply is a *game*: it has no upscaler,
no frame generation and no ray tracing, so `upscaler`, `fg_mode` and `rt_flag` are honestly `N/A`
there. The milestone is the row where they are not.
**The run, when the owner takes it** (candidates from §9: Cyberpunk 2077, Lies of P, Cronos):
```
FrameLedger.Agent --console consent grant --exe "<title>.exe" # type the phrase
FrameLedger.Agent --console launch --exe "<title>.exe" --seconds 600
FrameLedger.Agent --console sessions --last 1
```
**The row half is read — 2026-09-16, the shipped Agent, not the console.** The owner ran the App with its `--serve`
Agent for an afternoon (18 hooked sessions — **count note, 2026-09-27:** `CHANGELOG` 2026-09-17 says *all nine hooked
sessions of 2026-09-16*; neither count was re-made when the other was written, and the ledger as it stands today holds no
session from that day, so the discrepancy is recorded rather than resolved — attach mode, `late_attach = 1`, every one watcher-driven from a Steam
launch rather than the `launch` verb above — a Steam title started from its Shipping executable relaunches through
Steam, so the console recipe is the wrong vehicle for a Steam library and the product's own path is the right one).
`sessions.id = 10`, **Lies of P**, 16:11, 147 s, `d3d12`, 16,221 frames, `guard_ticks_published = 5`, Overlay
`dcf5796bf2a6-dirty`, read from the ledger (rebuilt that evening from its WAL — `06_DATA_MODEL` §Migrations carries
that incident; the row is the row):
| Field | Read from the row | The game's own menu | Agree? |
|---|---|---|---|
| `upscaler` | `fsr3` (`fg_source = api`) | *owner to read* | |
| `upscaler_quality` | `NULL` (0xFF → not stored, #183) | | *(`N/A` is the measured answer on every title so far — §9, P0 exit criterion 1; FSR 3 carries no Streamline `DLSSOptions` to chain, so it is the expected answer here too)* |
| `render_w` × `render_h` → `output_w` × `output_h` | **1506 × 848 → 2560 × 1440** (`upscale_ratio` 1.70 — FSR "Balanced" is 1.7×; "Quality" would be 1.5×, "Performance" 2.0×) | *owner to read* | |
| `fg_mode` / `fg_factor` | `fsrfg` / **2.04** (`native_fps` 57.1 → `displayed_fps` 116.4, `displayed_counted_by = hook`, no refusal) | *owner to read* | |
| `rt_flag` | `no` (`rt_source = measured`, `rt_frame_pct` 0.0) | *owner to read* | |
| `telemetry_source` | `l1+lhm+nvapi` | *(expect `l1+lhm+nvapi` on this box since PR-E2)* | ✅ |
**What this row does and does not settle.** It is the first hooked session the *shipped* Agent persisted with a
measured upscaler, a counted frame-generation factor and a measured RT state — the milestone's row half. The
"against its menus" column is empty because only the owner can read the game's settings screen, and the row is
kept here with that column blank rather than filled from memory. The same afternoon's DLSS-G rows (Onimusha ×2,
Hell Is Us, Black Myth: Wukong) are the *refused* shape — identity `dlssg` from the tags, `fg_factor` NULL,
`fg_refusal` = `multiple_streams` (RE Engine's second swapchain) or `non_uniform` (a bucket that departed: menus,
loading, alt-tab in a whole play session) — which is the guard working on real play rather than on a 40-second leg,
and the reason `fg_refusal_detail` (schema 0005) now stores the bucket's numbers. Onimusha's `rt_flag = yes` with
`rt_frame_pct` 25.0 / 17.8 and Wukong's `yes` at 16.2 are measured against nothing yet either.
**One launch per capture** (HANDOFF §Traps): a title measured off / ×2 / ×4 is three launches.
### 14.2 · §S1's launcher-fronted title — launch mode and the descendant election
The election is built (P2 PR-F, `DescendantElection`) and unit-tested against fabricated snapshots;
what has never happened is a real launcher spawning a real game under it. An Epic- or
Ubisoft-fronted title is the case: the consented executable exits or never presents, the guard
answers `LaunchTargetExited` / `LaunchNoPresentationRuntime` with nothing injected, and the Agent
then elects the newest tracked descendant and attaches.
**The elected image needs its own consent record** — a launcher's consent does not extend to what it
spawns — so the run is: `consent grant` the launcher, `launch` it, read the `election:` line, then
`consent grant` the game the election named and `launch` again.
| | |
|---|---|
| Title / launcher | |
| Guard's answer for the launcher | |
| `election:` line | |
| Session row for the elected image | |
### 14.3 · FPS impact ≤ 0.5 % — `14_TESTING` §Hook overhead item 2
The last thing P1 owes (§R4 moved it here because it needs P2's drain and recorder). Run
`tools/fps-impact-runbook.ps1`; it prints the block that replaces this one.
```
./tools/fps-impact-runbook.ps1 -Exe "<title>.exe" -GameArgs "-benchmark" -Seconds 600
```
| Run | Leg | Game avg FPS | Agent CPU (% of a core) | Agent RSS (MB) |
|---|---|---|---|---|
| 1 | ON | | | |
| 2 | ON | | | |
| 3 | ON | | | |
| 1 | OFF | | | |
| 2 | OFF | | | |
| 3 | OFF | | | |
Gates: FPS delta ≤ 0.5 %, Agent CPU ≤ 1 % of a core, Agent RSS ≤ 150 MB. **Overlay resident ≤ 8 MB is
not measured by the runbook** and is left blank rather than guessed: it is a module inside the game
process, and reading the target's memory is what CLAUDE.md rule 4 forbids — an external tool that
inspects module sizes is the way to fill it.
### 14.4 · §H7's six overlays — still owner-only
Unchanged by P2 and repeated here because it is the other measurement no PR can close: the
compare-and-restore path is proven against a fixture (`ctest fl_unhook_inline`), and §H7 still asks
for one capture with each of the six overlays actually resident on the dev machine.
## 15 · Unreal Engine versions in shipping executables *(2026-09-27, beta.10)*
Measured read-only on the owner's machine (i7-14700KF, RTX 5080, Windows 11 29648): every `*-Win64-Shipping.exe`
under `D:\SteamLibrary\steamapps\common` (a USB drive), before the extractor was written, then again through the
shipped `UnrealBuildReader` once it was. Nothing was copied or written; the numbers are in `05_DETECTION` §Engine version
(the table is not repeated here).
- **Numeric file version** (`VS_FIXEDFILEINFO`): the engine's MAJOR.MINOR.PATCH in seven of ten; a studio's own in three
(Cronos 1.2.0.0, Rune Factory 1.0.3.0, SILENT HILL 2 1.0.0.5). The version *strings* are empty in six of ten.
- **Branch name** (UTF-16 `++UE4+Release-M.m` / `++UE5+Release-M.m`): present in five — in `.rdata` in four (15–30 MB
sections), and 290 MB into `.code` in Black Myth: Wukong, whose protected executable has an 8 KB `.rdata`; in UMIGARI
also in the version strings. Absent in five (Hell Is Us carries `UE5-CL-0`: a renamed branch).
- **The shipped reader, same ten files:** every version as tabled — 8 read, 2 honestly none — in 16 ms to 1.1 s each and
7.5 s for Black Myth (the whole-file fallback, stopping at the first chunk that names a release line). A first pass
that scanned only a PE's `.rdata` read Black Myth as `5.0.0` from the file version alone; the 1 MiB `.rdata` floor
(`UnrealBuildReader.MinRdataBytes`) is what moved it to the stronger rung.
- No UE3 title is installed; the rule does not detect UE3 at all.
## 16 · A game process's own memory, read from outside it *(2026-10-03, beta.12, owner decision D43)*
**Why this was measured.** Per-process VRAM had storage since 0001 and no producer: `17_HOOK_ENGINE` §Memory planned
`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game, `20_OPEN_QUESTIONS` §M7 (2026-09-09) recorded that its
`CurrentUsage` is the calling process's own (0 bytes from the Agent) and concluded the figure could only be read in the
game, and §H10 left open where in the game. The owner chose the other road (D43): the documented performance counters
`\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated Usage` / `Shared Usage` — the numbers Task Manager's Details tab
shows — need no handle to the game at all, and `GetProcessMemoryInfo` needs only `PROCESS_QUERY_LIMITED_INFORMATION`.
§M7's conclusion holds for `QueryVideoMemoryInfo` and not in general.
**Already seen before this section was written**, stated so the table below is not read as having preceded them:
(1) the counter set exists on the dev box, 37 instances at an idle desktop (`Get-Counter`, 2026-10-03); (2) `Dedicated
Usage` is not `Local Usage` — dwm.exe 858 MB against 310 MB — so "dedicated" is defined as Task Manager's column and never
compared with a DXGI budget; (3) `ctest fl_process_stats` on the RTX 5080 while the reader was being written: a 256 MiB
DEFAULT buffer moved this process's dedicated figure 12.9 → 269.0 MiB (+256.1), and `PROCESS_MEMORY_COUNTERS_EX2` answered
(private working set 5.2 MiB) on Windows 11 29648.
**The decision table, written before the runs below** (instrument: `fl-probe-processstats`, `--hold-vram` in one
process and `--read` against it in another):
| # | Measurement | Outcome → what it means |
|---|---|---|
| M1 | Cost of one collect + read, 60 samples at 1 s | median ≤ 5 ms → 1 Hz with the sensors; 5–20 ms → still 1 Hz, noted in `18_GPU_VENDOR_APIS`; > 20 ms → every 5 s, and said so |
| M2 | Δ dedicated of a second process holding 512 MiB | within ±2 % → "Dedicated GPU memory, as Task Manager shows it" may be written; off by > 10 % → stop, the video half does not ship |
| M3 | dedicated against that process's own `QueryVideoMemoryInfo(LOCAL).CurrentUsage` | recorded in `03_METRICS`, whichever way it falls — the source does not change |
| M4 | `PrivateWorkingSetSize` (EX2) against `\Process V2(<name>:<pid>)\Working Set - Private` | equal → "the same as Task Manager's Memory column"; EX2 refused → the EX fallback, and Windows 10 stays unmeasured |
| M5 | How soon a new process's counter instance appears | recorded; the first seconds of a session reading N/A is then expected, not a fault |
| M6 | The probe's own private bytes after 600 collections | Δ < 1 MiB → keep one query per session; more → open and close per collection, then measure again |
**Results (2026-10-03, the same evening; RTX 5080, driver 617.14, Windows 11 29648.1000, `fl-probe-processstats`
from this PR's build):**
| # | Measured | Row taken |
|---|---|---|
| M1 | 60 samples at 1 s: collect + read **median 0.098 ms, max 0.217 ms**; 600 back to back: median 0.028 ms, max 0.190 ms | ≤ 5 ms → 1 Hz with the sensors |
| M2 | holder at 8 MiB: dedicated **21.0 MiB**; holder at 512 MiB: **525.0 MiB** → Δ **512.0 MiB** for 512 MiB allocated (0.0 %); the in-process ctest earlier: +256.1 MiB for 256 | within ±2 % → "Dedicated GPU memory, as Task Manager shows it" |
| M3 | the holder's own `CurrentUsage(LOCAL)`: 16.5 MiB (8 MiB holder) and 520.5 MiB (512 MiB holder) against dedicated 21.0 and 525.0 — **dedicated reads 4.5 MiB more, the same 4.5 MiB at both sizes** | recorded in `03_METRICS`: the counter includes a constant per-device amount the DXGI budget group does not; the difference does not grow with what the game allocates |
| M4 | private working set (EX2) **9.1 MiB** = `\Process V2(fl-probe-processstats:<pid>)\Working Set - Private` **9.1 MiB**, in all 60 samples | equal → "the same as Task Manager's Memory column" |
| M5 | the holder's instance was present at the reader's first poll, ~50 ms after the holder started (its device and buffer had already been created) | an instance exists from the process's first GPU allocation; a game that has made none reads N/A, as specified |
| M6 | 600 collections: the probe's private bytes moved by **0 bytes** (−44 KB over the 60 slow ones) | < 1 MiB → one query per session |
**What stays unmeasured:** Windows 10 22H2 (no machine; the reader falls back to `PROCESS_MEMORY_COUNTERS_EX` where EX2 is
refused, and the private working set then reads N/A), AMD and Intel GPUs, a laptop with two adapters (the reader sums
every adapter's instances for the pid), and a real game — the owner's beta.12 check (HANDOFF owner-only item 9) compares
a session's figures with Task Manager's Details tab at the same moment.
+45
View File
@@ -0,0 +1,45 @@
# Install and first start
## What you need
- **Windows 10 (22H2) or Windows 11, 64-bit.**
- Games FrameLedger can measure: **64-bit DirectX 11, DirectX 12 and OpenGL games.** Other games — 32-bit games,
DirectX 9 games, and Vulkan games you start yourself — are still recorded (how long you played, your PC's sensors,
the game's memory use), but not measured. [Limitations](../LIMITATIONS.md) has the full list.
## Download and install
1. Download `FrameLedger.App-win-Setup.exe` from the project's
[Releases page](https://github.com/poli0981/frameledger/releases) on GitHub.
2. **Check the file.** Each release publishes SHA-256 checksums in `SHA256SUMS.txt`. In PowerShell:
`Get-FileHash .\FrameLedger.App-win-Setup.exe` — the result must match the line for that file.
3. Run it. FrameLedger is free software and is **not code-signed**, so Windows SmartScreen may warn about an unknown
publisher. Once the checksum matches, choose **More info ▸ Run anyway**.
FrameLedger installs into `%LOCALAPPDATA%\FrameLedger.App` and needs no administrator rights. Your recordings are kept
separately, in `%LOCALAPPDATA%\FrameLedger`.
## The first start
The first window walks you through four short steps:
1. **Before you start** — the documents. You accept three: the End User License Agreement, the Disclaimer and the
Privacy Policy. The GNU GPL v3 is shown too: it is your licence to FrameLedger and needs no acceptance. A short
summary sits above them, and [The terms, in plain words](terms-in-plain-words.md) explains them, but the documents
are the terms. Declining closes FrameLedger.
2. **The capture agent** — the background program that notices when one of your games starts and records it. It runs
as you, without administrator rights.
3. **What hooking means** — the difference between a game that is recorded and a game that is measured. Read
[Anti-cheat and safety](04-anti-cheat-and-safety.md) before you switch hooking on for any game.
4. **Your game library** — where to import it from. Nothing is measured until you choose to.
## Updates
A few seconds after it starts, FrameLedger asks GitHub whether a newer version exists. A new version downloads in the
background and is installed only when you restart FrameLedger — never while a game is being measured. You can switch
the check off in **Settings ▸ Updates ▸ Check for updates at startup**, and check by hand with Help ▸ Check for
updates.
## Uninstall
Uninstall FrameLedger from Windows Settings ▸ Apps. It asks before it deletes your recordings folder.
+47
View File
@@ -0,0 +1,47 @@
# Record a game
## 1. Add the game
- **File ▸ Add game…** — pick the game's `.exe` file.
- **File ▸ Import library…** — FrameLedger lists the games installed through Steam, GOG, Epic and itch.io, and you
tick the ones to add.
Every game is added with **hooking off**.
## 2. Play
When a game in your library starts, the capture agent records a session by itself. While it runs, the **Dashboard**
shows it live. When the game closes, the session is saved and you get a notice. A session shorter than 30 seconds is
not kept.
## Recorded, or measured
A game in your library is always **recorded**: how long you played, your PC's sensors (GPU temperature, load and power;
CPU load; memory in use) and how much memory the game itself used — its video memory and its RAM, read from Windows
from outside the game.
To **measure** a game — frame rate and frame times, the real render resolution, the upscaler, frame generation, ray
tracing — FrameLedger has to load a small component into it. That is called **hooking**, and it is a choice you make
**one game at a time**: open the game's page (Games ▸ the game) and switch **Hooking** on. A warning explains the risk
first. **Read [Anti-cheat and safety](04-anti-cheat-and-safety.md) before you do.**
In the session list, **T1** marks a measured session and **T2** one that was only recorded; a recorded session says
why it was not measured.
## When FrameLedger will not measure a game
- **It found anti-cheat.** FrameLedger then turns hooking off for that game and says why on the game's page.
- **The game is 32-bit or uses DirectX 9.**
- **It is a Vulkan game** you started yourself.
- **The game runs as administrator.** Settings ▸ Capture agent ▸ *Run the agent as administrator* can help (off by
default; Windows asks every time the agent starts). Read its risk in [Limitations](../LIMITATIONS.md) first.
- **The game was already running when FrameLedger was updated** — restart the game once.
## Programs that are not games
Open the entry's page and switch **Recording** off: it is then ignored and nothing is recorded.
## Turning all hooking off
**Settings ▸ Capture ▸ Disable all hooking** stops every game from being hooked, whatever each game's own switch says. A
session that is running stops measuring within 30 seconds.
+50
View File
@@ -0,0 +1,50 @@
# Read your results
Open **Games ▸ a game ▸ Sessions**: one row per session. Double-click a row (or press **Open**) for the session's
summary. The Dashboard lists your most recent sessions too.
## N/A means "not measured"
A value FrameLedger could not measure reads **N/A** — never 0, and never an estimate. A session that was only recorded
(**T2**) has N/A for everything that needs hooking, and says why.
## Frame rate
- **When frame generation was measured**, the game's own frames and the frames you saw are shown together:
`62 → 118 FPS (×1.9 FG)`. If frame generation changed during the session (menus, loading screens, a settings change),
the figures are for the state that lasted longest, with the share of the session it covers: `(×1.9 FG · 75%)`.
- **When it could not be measured**, you see **Presented FPS** with a sentence saying whether generated frames could be
included in it. FrameLedger never shows a single number that may count generated frames as the game's own.
- **1% low** and **0.1% low** are the frame rate of the slowest 1% and 0.1% of frames: the further they fall below the
average, the less smooth the game felt. **Stutter** counts frames that took much longer than the frames around them,
and the share of time they took.
## Memory
- **VRAM (this game)** is the game's own video memory — what Task Manager's Details tab calls *Dedicated GPU memory* for
the game's process. **RAM (this game)** is its *Memory (private working set)*. Both are read from Windows once a
second, from outside the game, whether or not the game was hooked.
- The **median** is the typical level during the session; the **peak** is the highest it reached.
- *VRAM, whole graphics card* and *RAM in use, whole PC* count everything else running too, so they are usually much higher.
- **Statistics per series**, at the bottom of the summary, lists the mean, median, minimum and peak of every sensor.
## Ray tracing
**Ray tracing**, **path tracing** and **ray reconstruction** read *Yes*, *No* or *N/A*. Ray tracing is measured on
DirectX 12 games; path tracing is never stated as a fact, because nothing in a game's calls says so. Click a chip to
correct it by hand — your correction is labelled as yours.
## Charts
- **Frametime** — how long each frame took. Spikes are stutters.
- **Distribution** — how often each frame rate occurred.
- **Sensors** — temperatures, load and power; video memory; memory. The game's own line and the whole card's or the
whole PC's are drawn separately.
- **Trend** (on the game's page) — one point per session over time, for example before and after a driver update.
Changes to your hardware or driver are marked on it.
- **Compare** (in the navigation on the left) — pick sessions, even of different games, and see them side by side.
## Export
The summary's **Export CSV**, **Export JSON** and **Export PNG** buttons — or File ▸ Export — save a session to a file.
Read [Your data](05-your-data.md) before you share one.
+45
View File
@@ -0,0 +1,45 @@
# Anti-cheat and safety
## The risk
To measure a game, FrameLedger loads a small component into it ("hooking"). **Anti-cheat systems can detect that and
may warn you, block you, or permanently ban your account** — and a ban can arrive days after the session. The developer
cannot reverse a ban, recover progress, or speak to a game's publisher for you.
**Use hooking for offline and single-player games.** Switching it on for a game with online or competitive play is
your decision and your risk.
## What FrameLedger does to keep the risk small
- **Hooking is off for every game** until you switch it on for that game, after a warning.
- **It looks for anti-cheat** before it hooks a game and every 30 seconds while it is hooked. If it finds any, it
refuses — or stops measuring at the next check — and turns hooking off for that game. **There is no switch that
overrides this**, apart from the one narrow exception below.
- **It never hides.** It keeps its real name and does nothing to avoid being seen by security software.
- **It never reads or changes the game's memory**, its saves or your input. It only observes the graphics calls the
game makes.
## What it cannot promise
- Its list of anti-cheat systems is its own and **can be incomplete**, and a game can add anti-cheat in an update.
- Anti-cheat that starts in the middle of a session can be there for **up to 30 seconds** — in the worst case 65 —
before FrameLedger stops.
- Some anti-tamper software (Denuvo, for example) can make a game **crash** when it is hooked, even offline.
## The one exception you can make
**Settings ▸ Capture ▸ User-mode exceptions** (off by default). For a game whose only finding is one anti-cheat that runs
entirely inside the game — no driver, nothing else found — you may allow hooking for that game after a separate warning.
Its first two hooked sessions are a trial: one that does not go well ends the exception for good. FrameLedger still runs
every check under it, and **a ban is still possible.** Kernel anti-cheat is never allowed.
## Turning everything off
**Settings ▸ Capture ▸ Disable all hooking** stops all hooking at once, whatever each game's own switch says.
## If FrameLedger missed a game's anti-cheat
Please open an issue with the **Safety gap** form on the project's GitHub page. That is treated as a safety bug, with
the same priority as a security report. A fix reaches you with the next version you install.
The full statement of the risk is the [Disclaimer](../legal/DISCLAIMER.md), §2 and §2A.
+49
View File
@@ -0,0 +1,49 @@
# Your data
## Where it is
Everything FrameLedger records stays on your PC, in `%LOCALAPPDATA%\FrameLedger` (Tools ▸ Open data folder): the
database with your library and sessions, the logs, and crash reports of FrameLedger itself. There is no account and
nothing is uploaded. The only network requests are the update check and the update download, both to GitHub
([Install and first start](01-install.md#updates)).
## What is in it
Your game library; your sessions — frame times when a game was measured, the statistics, your PC's sensors, the game's
own memory use, how the game's window was shown; a short description of your hardware for each session; your tags and
notes; your settings. The [Privacy Policy](../legal/PRIVACY_POLICY.md) lists all of it.
## How much is kept
The per-frame data of the newest **20 sessions of each game** is kept; older sessions keep their statistics. Change it
in **Settings ▸ Recording ▸ Raw series kept per game** (0 keeps everything).
## Back it up
**Tools ▸ Database maintenance… ▸ Back up…** writes a consistent copy of the database to a file you choose, even while
a game is being recorded. Backing up is up to you — FrameLedger does not do it by itself.
## Delete it
- **A game's sessions:** Games ▸ the game ▸ Sessions ▸ **Delete all sessions…**
- **A game:** its page ▸ **Remove…**
- **Every session of every game:** Settings ▸ Data ▸ **Delete all sessions…**
- **Everything:** uninstall FrameLedger and let it delete the data folder, or delete the folder yourself.
## Share it — carefully
An exported **CSV** or **JSON** file, and a bug report, can contain:
- your games' names and **the paths to their files**, which include your **Windows user name** when a game is installed
in your user folder;
- your PC's processor, graphics card, driver and Windows version;
- your tags and notes.
Look at a file before you share it. **Help ▸ Report a bug…** builds the report on your PC, shows you every file in it,
and removes your user folder's path from the logs; you decide whether to attach it to an issue on GitHub. An export is
written as it is. Once you share a file, whoever receives it — and the site you post it to — can read it.
## Updating and going back
A new version upgrades the database in place. **An older version cannot open it afterwards** — there is no downgrade,
so keep a backup if you might want to go back.
+49
View File
@@ -0,0 +1,49 @@
# Questions and answers
## Why does my session say N/A everywhere?
The game was recorded, not measured (**T2**): hooking is off for it, FrameLedger found anti-cheat, or the game is one
FrameLedger cannot measure. The session's summary says which. See [Record a game](02-record-a-game.md).
## I switched hooking on, and the game is still not measured.
FrameLedger refuses a game where it finds anti-cheat, and cannot measure 32-bit games, DirectX 9 games, Vulkan games you
start yourself, or a game that runs as administrator (unless the agent does too). A game that was already running when
FrameLedger updated needs one restart. The game's page and the session's summary say what happened.
## Why "Presented FPS" and not the game's own frame rate?
Because frame generation could not be measured in that session. Presented FPS counts every frame the game handed to
Windows, and the sentence beside it says whether generated frames could be among them. FrameLedger never labels a
number that may include generated frames as the game's own.
## Why is the video memory different from my in-game overlay?
FrameLedger shows what Task Manager shows for the game's process: its *Dedicated GPU memory*. Overlays often show the
whole graphics card's use, which includes every other program, or the amount the game is allowed to use. FrameLedger
shows the whole card's figure too, separately.
## Why is the CPU temperature N/A?
Reading it needs *Run the agent as administrator* (Settings ▸ Capture agent) and the separately installed PawnIO
driver — and that reading has not been checked on real hardware yet. CPU load needs neither.
## Windows warned me when I installed FrameLedger.
FrameLedger is not code-signed, so SmartScreen does not know its publisher. Check the download against the published
SHA-256 checksum before you run it ([Install and first start](01-install.md)).
## Can I use FrameLedger with online games?
Recording works with any game. **Hooking** an online or competitive game risks your account — see
[Anti-cheat and safety](04-anti-cheat-and-safety.md).
## Something is wrong. How do I report it?
**Help ▸ Report a bug…** builds a report on your PC and opens the issue form on GitHub; you decide what to attach. If
FrameLedger missed a game's anti-cheat, use the **Safety gap** form instead.
## Where are the full documents?
**Help ▸ About ▸ Legal documents**, or Settings ▸ Legal ▸ Reopen the legal documents. What FrameLedger cannot do is in
[Limitations](../LIMITATIONS.md).
+24
View File
@@ -0,0 +1,24 @@
# FrameLedger user guide
FrameLedger records how your games run on this PC — frame rate, frame times, the settings a game is really rendering
with, temperatures, and how much memory the game uses — and keeps every session so you can compare them later.
Everything stays on your PC.
Each page below takes a minute or two to read.
1. [Install and first start](01-install.md)
2. [Record a game](02-record-a-game.md)
3. [Read your results](03-read-your-results.md)
4. [Anti-cheat and safety](04-anti-cheat-and-safety.md) — read this before you switch hooking on for any game
5. [Your data](05-your-data.md)
6. [Questions and answers](06-faq.md)
7. [The terms, in plain words](terms-in-plain-words.md)
What FrameLedger cannot do is listed on its own page: [Limitations](../LIMITATIONS.md) (in the app: Help ▸
Limitations).
**FrameLedger is beta software.** It certainly still has bugs. If something goes wrong, Help ▸ Report a bug… builds a
report on your PC that you can look at before you decide to share it.
This guide is part of FrameLedger and describes the version it came with. It is also in the project's repository on
GitHub, in the `guide` folder.
+43
View File
@@ -0,0 +1,43 @@
# The terms, in plain words
This page sums up the documents FrameLedger shows you. **It is a summary, not the terms:** the documents themselves
are the terms, and where this page and a document differ, the document is right. They are all under **Help ▸ About ▸
Legal documents**.
## End User License Agreement — you accept it
- FrameLedger is **free software** under the GNU GPL v3 (below), and nothing in the agreement takes any of that away.
- It records performance data **on your PC**.
- It hooks a game **only if you switch that on for that game**, after a warning. If anti-cheat bans your account for
it, **that risk is yours**, and the developer cannot undo a ban.
- It is **beta** software, provided **without warranty**, and the developer is not liable for damage it causes — as
far as the law allows. Rights the law gives you as a consumer, which no agreement can take away, stay yours.
- Read it: [EULA](../legal/EULA.md).
## Disclaimer — you accept it
How FrameLedger measures, why that can be detected by anti-cheat, what its safety checks can and cannot catch, how
accurate its measurements are, that your PC must meet each game's own requirements, and what *Run the agent as
administrator* changes. Read it: [Disclaimer](../legal/DISCLAIMER.md).
## Privacy Policy — you accept it
Everything stays on your PC: no account, no telemetry, no analytics. The only network requests are the update check
and the update download, to GitHub, and the check can be switched off. It lists what FrameLedger can observe, and says
that sharing an export or a bug report is your decision. Read it: [Privacy Policy](../legal/PRIVACY_POLICY.md).
## GNU General Public License v3 — your licence, shown for information
It gives you the right to **use, study, share and change** FrameLedger. You do not have to accept it to use the
program. If you **give copies to others** — changed or not — you must pass on the same freedoms and offer the source
code. Read it: [GPL v3](../LICENSE).
## NOTICE — the copyright line and three extra terms
The copyright line, and three terms of the kinds the GPL's section 7 allows: keep the copyright line and the
attribution; a changed version must say it is changed and must not be called just "FrameLedger"; and the terms give no
rights to the FrameLedger name or logo. Read it: [NOTICE](../NOTICE).
## When the documents change
A new version of a document you accepted is shown to you again before FrameLedger continues.
+98
View File
@@ -0,0 +1,98 @@
<!--
THE ONE ACCURACY BLOCK. Embedded verbatim in README.md and legal/DISCLAIMER.md
between the two HTML-comment markers named `accuracy-block:begin` and
`accuracy-block:end` (spelled out in tools/accuracy-check.ps1 — not here, because a
literal marker inside this comment would end the comment early), and that gate
fails the build when any copy differs from this file
(20_OPEN_QUESTIONS §S23-6: the accuracy blocks were hand-maintained prose that
nothing verified, and DISCLAIMER's went stale four times in one direction and once
in the other). Whether the sentences below are TRUE is still a human's job — the
gate only makes there be one place to get them wrong. Re-read this file in the PR
that changes what FrameLedger.Overlay or the capture host does; date the change.
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-10-04.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.12`** (2026-10-04), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> 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
> 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 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.
> - **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
> and OpenGL titles.
> - **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. 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. 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. 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:** 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.
> - **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.** 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
> yours. The software never substitutes an estimate.
+186 -30
View File
@@ -1,30 +1,24 @@
# FrameLedger — Disclaimer
**Version:** 2.0-draft · **Effective:** {{RELEASE_DATE}}
**Version:** 2.10 · **Effective:** {{RELEASE_DATE}}
> ⚠ Draft for review. Not legal advice. Review before first public release — this version covers code injection and should be read carefully.
## 0. This is pre-release (beta) software
> ⚠ **Accuracy audit — re-checked 2026-08-14, a FOURTH time, after PR #64. SIX statements below describe behaviour the software does not yet fully have**, and they are flagged here rather than quietly reworded because a document the user accepts must not over-promise.
>
> **The fourth drift is the first one that ran the other way, and that is the finding.** Every previous re-count found this document claiming *more* than the software did. #64 landed the upscaler identity hook and this block went on saying "there is no upscaler hook anywhere in the software" — an under-claim, in the one file whose failure mode everybody was watching for in the opposite direction. It went unnoticed for five days for exactly that reason: a reviewer checking whether `legal/` over-promises reads a sentence like that and moves on. **Re-reading this block means checking both directions.**
>
> **The re-count was overdue and this block's own rule is what says so.** The last line of this block requires whoever changes what `FrameLedger.Overlay` does to re-read it. #48 changed exactly that — the Overlay now drops `DXGI_PRESENT_TEST` presents without recording them — and this block was not re-read. That is the second time the rule has been broken since it was written, and both breaches were invisible from inside the PR that caused them.
>
> **Two additions this round, both about what the software claims to *measure*** — the class the project has already had to retract twice:
>
> **Two bullets changed substance and neither could be struck.** The capture side that *receives* a stop now exists and now runs whether or not the game is presenting; the side that would *send* one still does not. That is the pattern to watch for when re-counting: half a mechanism reads as a whole one, and the half that is missing is usually the one nobody was looking at.
>
> - ~~§1's *"what it observes: … presentation, upscaling, ray tracing, pipeline creation"* and §4's *"upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs"* — **only the presentation path is intercepted.** There is no upscaler hook, no frame-generation hook, no ray-tracing hook and no pipeline hook anywhere in the software.~~ **FALSE SINCE #64, corrected 2026-08-14 — the fourth drift, and this one is the block's own subject.** An **upscaler hook exists**: one detour on `sl.interposer.dll!slEvaluateFeature`, module-scoped, reading one argument. It measures **which upscaler is running** (DLSS, NIS, or `unknown` — never "none") and, for Streamline titles, **whether Ray Reconstruction is active**, which is a `Yes`/`No` the software now publishes. What still does not exist: quality preset, render resolution, frame generation, ray tracing, pipeline. The capture side states all of that in its own data on every frame rather than defaulting to "none", so nothing false is *recorded*; what over-promised was this document, in the direction of under-claiming rather than over-claiming — which is the safer direction and is still wrong. Both sentences are qualified where they sit.
> - §2's *"and every 30 seconds afterwards … it stops at the next scan"* — the pre-injection guard is real and refuses. The **receiving half is implemented**: an injected D3D title removes its hooks within one frame of the stop flag being set. The **sending half is still missing, and the missing part is narrower than this block used to say.** Both the write path (`ShmRingReader.PublishGuardResult`, which maps the shared memory and advances the field) and the read path exist in shipped code and are tested; what does not exist is a production caller that runs the loop between them. A missing loop, not a missing subsystem — and the user-facing consequence is identical: **no re-scan runs and no stop is ever sent.**
> - §2's *"waits **65 seconds** before concluding that contact is lost"* — **the deadline now has a reader, and since 2026-08-05 it runs whether or not the game is presenting.** For one day it was evaluated only on a present, so a title that had hung or been alt-tabbed never reached it — the exact case the mechanism was specified for. A watchdog inside the injected component now checks once a second regardless. Two qualifications remain: it covers **injected Direct3D titles only**, because the Vulkan layer intercepts nothing yet, and **the 65-second value itself is not covered by a test** — the stop is proven to fire, but a suite that runs on every build cannot wait 65 seconds, so what is verified is the mechanism, not the number.
> - §3's *"automatically stops injecting into a game that crashes shortly after injection twice"* — the only trace of this anywhere is a `hook_crash_count` column in a schema for which no `.sql` file exists. There is no design for it.
> - §1's *"Only FrameLedger's own component is ever loaded"* — **narrower than it sounds, and the qualification is now in §1 itself.** The check is a directory test: the payload must resolve into FrameLedger's own install directory. It does not compare a filename, a version or any content, deliberately — a name check would be defeated by any DLL that borrowed the name. A published self-contained build puts several hundred files in that directory.
>
> **None of this may ship as-is.** Either the behaviour exists at first release or these sentences change. Tracked in `docs/20_OPEN_QUESTIONS.md`.
>
> **This block is maintained by hand and nothing verifies it.** Every other document here is bound to the code by something — `rules-validate` cross-checks the blocklist, `static_assert`s bind `fl_shm.h` to `07_IPC`, `versioninfo-check` and `chokepoint-check` bind claims to binaries. `legal/` is bound by nothing, and it has now gone stale **three times**: first within hours of being written, when the 65-second sentence was added directly beneath a header that said "Three"; then again when five PRs (#40–#44) changed the Overlay from a stub into a hooking, shared-memory-mapping, control-block-reading component and touched **no documentation at all**, leaving the second bullet above asserting four things about that binary that were each false. and a third time when #46–#52 landed — seven PRs, including one (#48) that changed what the Overlay does *inside a game* — with no edit here at all. None of the three drifts was visible from inside the PR that caused it. **Whoever edits any promise in this file must re-count — and whoever changes what `FrameLedger.Overlay` does must re-read this block, because nothing will remind them.**
>
> **That sentence has now failed twice, so it is being replaced by something that is not a sentence.** `ci.yml` fails a pull request that touches `src/` without touching `CHANGELOG.md`. That is a weaker gate than the ones binding every other document — it forces a *ledger* entry, not a re-read of *this* file — and it is written down as weaker rather than described as a fix. A gate over the claims in `legal/` would have to assert things about behaviour rather than about files, and nobody has designed one (`docs/20_OPEN_QUESTIONS.md` §S23-6).
**FrameLedger is a beta.** Every build published so far is a pre-release. It has been tested on a small number of
machines and games — the games are listed in `docs/LIST_GAME_TESTED.md` in the project's repository, and what the software
cannot do is listed in `LIMITATIONS.md` there and in the app under Help ▸ Limitations — and **it certainly still contains
bugs — some of them not yet known to anyone.** Features can
change or disappear between builds, recorded data can turn out to be wrong, and an update can require your data to be
migrated.
By installing or running a pre-release build you accept that:
- it may crash, hang, fail to record, or record wrongly, and may cause the game you are measuring to do the same;
- **the developer is not responsible for any incident, loss or damage that results**, including lost progress, corrupted
saves, lost recordings, wasted time, or anything else described in this document;
- no support, fix, or response time is promised. Reports are welcome and are read; nothing is owed in return.
If that is not acceptable to you, do not use a pre-release build.
## 1. How FrameLedger measures (read this first)
@@ -42,9 +36,11 @@ Be precise about what that does and does not promise, because the shorter versio
Install it somewhere only you can write to, and verify the published SHA-256 checksums.
**What it observes:** arguments the game passes to graphics APIs we intercept (presentation, upscaling, ray tracing, pipeline creation) and video-memory usage reported by the graphics runtime.
**What it observes inside the game:** arguments the game passes to graphics APIs we intercept (presentation, upscaling, ray tracing, pipeline creation).
> **Today that list is two items long: presentation and upscaling** — and the upscaling half is *identity only*. The software can say which upscaler is executing, and whether Ray Reconstruction is active alongside it; it cannot yet say at what quality preset or at what render resolution. No ray-tracing or pipeline hook exists yet, and video-memory usage is not read. The list describes what the software is designed to observe, and the boundary — API arguments and nothing else — holds for all of it. See the accuracy audit at the top.
**What it reads about the game from outside it, in every session:** the game process's own memory use — its dedicated and shared video memory and its working sets, the figures Windows' Task Manager shows — from Windows' performance counters and process-memory information. For a game it does not inject into, FrameLedger opens the game's process for this with the least access Windows offers, once a second, and closes it again; it reads nothing inside the process.
> **What of that list is observed today is stated once, in §4 below** (the block `legal/ACCURACY.md` carries, dated). The list here describes what the software is designed to observe, and the boundary — API arguments and nothing else — holds for all of it.
**What it never does:** read or write the game's memory outside those API arguments; read save files, input, chat, or network traffic; modify game behavior; hide itself from any security software; or install a kernel driver of its own.
@@ -55,7 +51,7 @@ Install it somewhere only you can write to, and verify the published SHA-256 che
FrameLedger is designed to reduce that risk substantially:
- Injection is **off by default** and must be enabled by you **per game**.
- Before injecting, and every 30 seconds afterwards, FrameLedger scans for known anti-cheat and anti-tamper components. **If it finds one, it refuses to inject; if a session is already running, it stops at the next scan.** There is no setting to override this. Because the scan runs every 30 seconds rather than continuously, anti-cheat that loads mid-session may be present for **up to 30 seconds** before FrameLedger detects it and stops.
- Before injecting, and every 30 seconds afterwards, FrameLedger scans for known anti-cheat and anti-tamper components. **If it finds one, it refuses to inject; if a session is already running, it stops at the next scan.** No setting turns this off, globally or per game; the one exception you can make yourself, per game, still runs every check and is described in §2A. Because the scan runs every 30 seconds rather than continuously, anti-cheat that loads mid-session may be present for **up to 30 seconds** before FrameLedger detects it and stops.
**And there is a second, longer window you should know about.** The part of FrameLedger running inside the game also stops on its own if it loses contact with the part doing the scanning — because a scanner that has stopped cannot protect you. It waits **65 seconds** before concluding that contact is lost, so that one delayed scan on a busy machine does not end your session. In the worst case those windows combine: if the scanner stops at the moment anti-cheat appears, the component inside the game may keep running for up to **65 seconds** afterwards. That number is 65 and not 30, and this document says so rather than leaving the 30 above to imply it.
@@ -69,8 +65,8 @@ FrameLedger is designed to reduce that risk substantially:
the game exits.
- FrameLedger contains **no evasion techniques of any kind** — it does not hide, rename, obfuscate, or disguise itself. It is intended to be plainly identifiable to any security software that looks.
For completeness about what it *does* run inside the game: besides the intercepted calls themselves, the component starts **one background thread** that sleeps for a second at a time and checks whether it has been told to stop. It reads only FrameLedger's own shared memory. It does not scan the game, enumerate what the system has loaded, or query Windows services — deliberately, because software that does those things from inside a game process looks like the thing this tool is trying not to be mistaken for.
- FrameLedger injects into a game only after you enable that game individually. For every other game — and for any game where the safety checks refuse — it records the session's start, end and duration together with whatever hardware sensor readings your machine provides, and reports every other measurement as not available. **There is no measurement mode that works without injecting**; an earlier version of this document described one, and it was never built. FrameLedger never estimates a value it could not measure, and it always shows which of the two modes produced a session. Neither mode requires administrator rights.
For completeness about what it *does* run inside the game: besides the intercepted calls themselves, the component starts **one background thread**. It wakes once a second, or when the game loads a library, and then: checks FrameLedger's own shared memory for a request to stop and for the heartbeat of the safety scan described above; asks Windows, by name, whether the graphics, upscaling and frame-generation libraries it knows about are loaded, and puts its interception into the ones that are (for ray tracing it creates one command list on the game's own Direct3D 12 device, to find the functions to intercept); writes its counters to FrameLedger's shared memory; and writes FrameLedger's own log file. It does not scan the game's memory, list the modules or processes on the system, or query Windows services — deliberately, because software that does those things from inside a game process looks like the thing this tool is trying not to be mistaken for.
- FrameLedger injects into a game only after you enable that game individually. For every other game — and for any game where the safety checks refuse — it records the session's start, end and duration together with whatever hardware sensor readings your machine provides and the game's own memory use as Windows reports it (§1), and reports every other measurement as not available. **There is no measurement mode that works without injecting**; an earlier version of this document described one, and it was never built. FrameLedger never estimates a value it could not measure, and it always shows which of the two modes produced a session. Neither mode requires administrator rights.
**However, these protections cannot be complete:**
@@ -81,6 +77,33 @@ FrameLedger is designed to reduce that risk substantially:
**FrameLedger is intended for offline and single-player play. If you enable injection for a game with any online or competitive component, you do so entirely at your own risk and are solely responsible for the consequences, including compliance with that game's terms of service.**
## 2A. There is no way past the guard — and one narrow exception you can make yourself
Versions 0.1.0-beta.3 and 0.1.0-beta.4 offered a per-game switch to overrule the guard. **It has been removed.** If
FrameLedger finds anti-cheat or anti-tamper software in a game — before it injects, when a session starts, or during a
session — it refuses, turns hooking off for that game, and says so on the game's page. There is no setting, per game or
global, that overrules that. Sessions recorded under the earlier switch stay in your database, marked as such in their
notes.
**Since 0.1.0-beta.9 there is one exception, and it is not a way past the guard.** A Settings option, off unless you
turn it on, lets you make an exception — one game at a time, after a disclosure you must accept — for a game whose only
finding is a single anti-cheat that works entirely in user mode (no kernel driver, no service, and no driver file
anywhere in the game's folder) and that is on no list of titles FrameLedger refuses. Since 0.1.0-beta.11 the game does
not need to have been measured before: **the first two sessions under the exception are a trial**, and if one of them
does not go well — it crashes, records nothing, does not end normally, is stopped for safety, or something new is found
— the exception ends and can never be made again for that game. Under it the guard still runs every check, before
injecting and every 30 seconds, and still refuses anything else it finds; after the trial the exception ends by itself
when something new is found, when a session under it crashes or is stopped for safety, or when the game is updated, and
turning the option off suspends it. Sessions recorded under it are marked with the anti-cheat they ran beside. **Two
good sessions are not evidence that the anti-cheat did not notice** — a ban may still come later.
**It exists because users asked for it, and it carries exactly the risk this document describes.** That anti-cheat
may still detect FrameLedger in the game and warn, block or permanently ban your account — possibly days later — and
FrameLedger cannot know whether it did. Earlier sessions that went well are no promise about the next one. **Do not
use it with a game you play online or competitively unless you accept losing that account;** the developer cannot
reverse a ban.
## 3. Stability
Software running inside another process can, in principle, destabilize it. FrameLedger guards every intercepted call, disables itself automatically after repeated internal faults, and automatically stops injecting into a game that crashes shortly after injection twice. Despite this, the developer is not responsible for crashes, lost progress, corrupted saves, or any other loss arising from use of the software. **Save your game before benchmarking.**
@@ -89,19 +112,134 @@ Software running inside another process can, in principle, destabilize it. Frame
Frame timing is derived from high-resolution timestamps taken at the moment the game presents each frame; upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs. This is substantially more accurate than inferring settings from files on disk, but **no measurement is guaranteed to be exact**:
> **Frame timing is measured today, and so are two of the settings.** Which upscaler is executing, and whether Ray Reconstruction is running with it, are read from the arguments the game passes — for titles that go through Streamline. **The rest are not measured at all yet**: quality preset, render resolution, frame generation and ray tracing have no hook behind them. Where a value has not been measured the software marks it as unmeasured rather than reporting a zero, so it will read `N/A` and never a confident wrong answer — including for a title whose upscaler runs by a route this hook cannot see, which reports `unknown` rather than "none". See the accuracy audit at the top.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-10-04.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.12`** (2026-10-04), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> 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
> 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 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.
> - **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
> and OpenGL titles.
> - **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. 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. 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. 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:** 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.
> - **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.** 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
> yours. The software never substitutes an estimate.
<!-- accuracy-block:end -->
- Frame timing: typically better than 0.05% error; hardware sensors carry their own accuracy limits (±1–2 °C is normal).
- 1% Low and 0.1% Low are statistical and are hidden when the sample size is insufficient.
- Path tracing has no reliable technical signature; FrameLedger reports it as a confidence-scored suggestion only and never asserts it.
- Path tracing has no reliable technical signature; FrameLedger reports it as `N/A` and never asserts it. *(This line promised a confidence-scored suggestion; none is computed. Corrected 2026-09-15.)*
- When measurement is unavailable (no-injection mode, unsupported API, missing vendor support), fields read `N/A`. FrameLedger does not substitute estimates for measurements.
Do not use FrameLedger's output as the sole basis for purchasing, warranty, overclocking, or safety decisions.
## 4A. Your PC must meet the game's own requirements
FrameLedger measures a game; it does not make one run. **Make sure your PC meets at least the minimum system
requirements published by the game's developer or publisher before you measure it** — read them first.
If you run FrameLedger with a game on a machine below that game's minimum requirements, low frame rates, stutter,
crashes, overheating, failures to start, and readings that look wrong are consequences of that choice. **They are your
responsibility, not the developer's**, and they are not defects of FrameLedger. The same applies to unstable overclocks
or undervolts, overheating or failing hardware, out-of-date or beta graphics drivers, a Windows installation that is
missing updates, and other overlays, injectors or "optimizer" tools running at the same time.
FrameLedger adds a small cost of its own while it records. On a machine that is already at its limit, that cost can
be the difference between a game that runs and one that does not. Turn hooking off for that game if so.
## 5. Hardware and drivers
FrameLedger reads GPU telemetry through vendor libraries that ship with your graphics driver. It **only reads** — it never changes clocks, fan curves, power limits, or any other hardware setting. Optional CPU-temperature support relies on the separate third-party **PawnIO** driver, which you install at your own discretion under its own license; some anti-cheat systems object to third-party kernel drivers regardless of what they are used for.
## 5A. Running the capture agent as administrator — optional, and your decision
Since 0.1.0-beta.10 a Settings option, off unless you turn it on, starts FrameLedger's capture agent as administrator.
**Windows asks you every time the agent starts** — also when you sign in — and the prompt names an unknown publisher,
because FrameLedger is not code-signed. It lets FrameLedger open and measure a game that itself runs as administrator,
and read the CPU temperature where PawnIO is installed. It changes nothing in the anti-cheat guard (§2, §2A), opens no
process that Windows or an anti-cheat driver protects, and never starts a game as administrator: games you start from
FrameLedger run with your standard rights.
**The risk is yours.** FrameLedger is installed in your user folder, which any program running under your Windows
account can change (§1). If such a program replaced FrameLedger's files, it would run with administrator rights the next
time you accept the prompt. Accept it only for a copy you installed from the project's GitHub Releases, and turn the
option on only if you trust everything that runs under your account. The developer is not responsible for what runs
under an administrator prompt you accept.
## 6. Third-party names
Windows and DirectX are trademarks of Microsoft Corporation. NVIDIA, DLSS, Reflex, NVAPI, AMD, FSR, Intel, XeSS, Vulkan, Steam, GOG, Epic Games, itch.io, Unity, Unreal Engine, and all other product names are trademarks of their respective owners. FrameLedger is an independent project and is **not affiliated with, endorsed by, or sponsored by** any of them, including any game publisher or anti-cheat vendor.
@@ -110,6 +248,24 @@ Windows and DirectX are trademarks of Microsoft Corporation. NVIDIA, DLSS, Refle
If you publish benchmarks or videos using FrameLedger data, you are responsible for how you present the numbers. The software deliberately shows native frame rate alongside frame-generation-boosted output, and labels which measurement tier produced each session; keeping both visible in published material is strongly encouraged.
## 7A. Your data, unsigned builds, and third parties
- **Your recordings are yours to back up.** They live in one folder on your PC (`%LOCALAPPDATA%\FrameLedger`). A bug, an
update, a disk problem or an uninstall can damage or remove them. The developer cannot recover them.
- **Builds are not code-signed.** Windows SmartScreen and antivirus products may warn about or block the installer or
the component loaded into a game. Verify the download against the published `SHA256SUMS.txt`; only download from the
project's own GitHub Releases page. A build obtained anywhere else is not the developer's and is not covered by
anything here.
- **FrameLedger is not affiliated with any game, publisher, platform, GPU vendor or anti-cheat vendor** (§6). None of
them supports it. If a game's or a platform's terms forbid third-party software that loads into the game, using
FrameLedger with it is your decision and your responsibility.
- **Numbers are for your own information.** Do not rely on them for a purchase, a warranty claim, a refund dispute, a
review you are paid for, or any decision where being wrong costs money, without checking them another way (§4).
## 8. No professional advice
Nothing in the software or its documentation constitutes professional, legal, or engineering advice.
---
Contact: <contact@poli0981.dev> · Developer: <https://poli0981.dev/> · Project: <https://github.com/poli0981/frameledger>
+21 -8
View File
@@ -1,8 +1,6 @@
# FrameLedger — End User License Agreement (EULA)
**Version:** 1.0-draft · **Effective:** {{RELEASE_DATE}}
> ⚠ Draft for review. Not legal advice. The developer should review before first public release.
**Version:** 1.5 · **Effective:** {{RELEASE_DATE}}
This End User License Agreement ("Agreement") applies to **FrameLedger** ("the Software"), developed and published by **poli0981** ("the Developer"), contactable at <contact@poli0981.dev> — see <https://poli0981.dev/> for other contact channels.
@@ -12,11 +10,11 @@ The Software is free and open-source software licensed to you under the **GNU Ge
## 2. What the Software does
The Software records game performance data, hardware telemetry (temperatures, load, memory usage), and game metadata, and stores this data **locally on your device**. Details are described in the Privacy Policy and Disclaimer accompanying the Software.
The Software records game performance data, hardware telemetry (temperatures, load, memory usage), each game's own memory use as Windows reports it, and game metadata, and stores this data **locally on your device**. Details are described in the Privacy Policy and Disclaimer accompanying the Software.
## 2A. Code injection — your responsibility
To measure rendering settings accurately, the Software can load a component into a game process, **but only for games you have individually enabled**, after a consent prompt that explains the risk. The Software refuses to do so when it detects anti-cheat or anti-tamper software, and provides no means to override that refusal.
To measure rendering settings accurately, the Software can load a component into a game process, **but only for games you have individually enabled**, after a consent prompt that explains the risk. The Software refuses to do so when it detects anti-cheat or anti-tamper software, turns hooking off for that game, and provides no means to override that refusal — except a narrow, per-game exception for anti-cheat that works entirely in user mode, which you may make yourself, after a separate disclosure, whose first two sessions are a trial that ends it for good if one of them does not go well, and under which the Software still runs every check (Disclaimer §2A). By making such an exception you accept, for that game, the risk described in (b) below.
By enabling this feature for a game, you confirm that:
@@ -30,15 +28,26 @@ By enabling this feature for a game, you confirm that:
(e) the Developer has no ability to reverse a ban, recover lost progress, or intervene with any game publisher on your behalf, and accepts no liability for such outcomes.
The Software records without injecting unless you enable injection for a specific game. In that mode it records only the session's duration and whatever hardware sensor data is available, indicates that mode on the session, and reports unavailable measurements as such rather than estimating them. Neither mode requires the Software's agent to run with administrator rights.
The Software records without injecting unless you enable injection for a specific game. In that mode it records only the session's duration, whatever hardware sensor data is available, and the game's own memory use as Windows reports it — read from outside the game, never from the game's memory — indicates that mode on the session, and reports unavailable measurements as such rather than estimating them. Neither mode requires the Software's agent to run with administrator rights.
## 2B. Pre-release software, and your PC
The Software is currently distributed only as **pre-release (beta) builds**, which certainly still contain defects
(Disclaimer §0). You use a pre-release build at your own risk, and the Developer is not responsible for any incident
that results.
You are responsible for making sure your PC meets at least the minimum system requirements published by the developer
or publisher of each game you measure. Problems that arise from running a game below its minimum requirements, or on
unstable, overheating, overclocked or faulty hardware, are your responsibility and not the Developer's (Disclaimer
§4A).
## 3. Acceptance
By clicking "Accept" in the first-run dialog or by using the Software, you confirm that you have read this Agreement, the Disclaimer, and the Privacy Policy.
By clicking "Accept" in the first-run dialog or by using the Software, you confirm that you have read this Agreement, the Disclaimer, and the Privacy Policy. The GPL-3.0 is shown in the same dialog for your information: it is your licence to the Software, and you need not accept it to run the Software (GPL-3.0 §9).
## 4. Third-party components
The Software includes and interoperates with third-party components listed in `legal/THIRD_PARTY_NOTICES.md`, each under its own license. The optional **PawnIO** kernel driver is a separate third-party product installed by you at your discretion and governed by its own license and terms.
The Software includes and interoperates with third-party components listed in `legal/THIRD_PARTY_NOTICES.md` — in an installed copy, `licenses\THIRD_PARTY_NOTICES.md` beside the Software, and Help ▸ About — each under its own license. The optional **PawnIO** kernel driver is a separate third-party product installed by you at your discretion and governed by its own license and terms.
## 5. No warranty
@@ -60,6 +69,10 @@ The Software can check for updates via GitHub. Installing updates is always your
Your rights under the GPL-3.0 continue as described in that license. You may stop using the Software at any time by uninstalling it; local data removal options are offered during uninstall.
## 10. Your rights as a consumer, and the rest of this Agreement
Nothing in this Agreement limits any right you have under consumer protection law that cannot be limited or waived by agreement; where such a law applies, the warranty and liability terms above apply only as far as that law allows. If a court finds any provision of this Agreement unenforceable, that provision is enforced to the extent permitted, and the rest of the Agreement remains in effect.
---
Contact: <contact@poli0981.dev> · Developer: <https://poli0981.dev/> · Project: <https://github.com/poli0981/frameledger>
+15 -14
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.0-draft · **Effective:** {{RELEASE_DATE}}
**Version:** 2.6 · **Effective:** {{RELEASE_DATE}}
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
@@ -8,39 +8,40 @@
Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
- Your game library entries (names, executable paths, cover art, metadata you or the app filled in).
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, memory usage), session duration, crash flags, tags and notes you write.
- Your game library entries (names, executable paths, metadata you or the app filled in, and whether each one is recorded).
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, memory usage), the game's own memory use (its dedicated and shared video memory, private working set, working set and commit, once a second), session duration, crash flags, the graphics driver's settings the game ran under (NVIDIA only), how the game's window was shown (full-screen, borderless or windowed, for how long, its size and the monitor's), tags and notes you write.
- A hardware snapshot per session (CPU/GPU model, driver version, RAM size, OS build, display mode) used for the "what changed between sessions" feature.
- App settings, logs (7-day rotation, including logs written by the component loaded into games), and, after a crash of the app itself, crash dump files.
- App settings, logs (rotated daily — the app keeps 7 days, the capture agent 14 — including the logs written by the component loaded into games), and, after a crash of the app itself, crash dump files.
- Which games you enabled code injection for, and when you consented.
This data never leaves your device unless **you** export it or attach it to a bug report yourself. Deleting the app offers deletion of this folder; you can also delete it manually at any time.
## 2. Network connections the app can make
FrameLedger makes **no network connections except the following**, each visible in settings:
FrameLedger makes **no network connections except the following two**, both from an installed copy only, and the first can be switched off in Settings ▸ Updates:
| Purpose | Endpoint | When | Data sent |
|---|---|---|---|
| Update check | GitHub Releases API for `poli0981/frameledger` | At startup (can be disabled) and on manual check | Standard HTTP request metadata only (no identifiers beyond your IP as seen by GitHub) |
| Safety list update | Raw file on the project repository | Weekly, and **regardless of your other rules-update settings** | Same as above — this list is what stops FrameLedger injecting into newly-protected games, so it is not optional |
| Update download | GitHub release assets | Only after an update is found | Same as above |
| Detection-rules update | Raw file on the project repository | Weekly check (can be disabled) and manual | Same as above |
| Store metadata lookup | Steam public store API | **Off by default — opt-in** | The Steam AppID of a game you added |
| Update check | GitHub Releases API for `poli0981/frameledger` | A few seconds after startup (can be disabled) and when you choose Help ▸ Check for updates | Standard HTTP request metadata only — the request carries `User-Agent: FrameLedger/<version>` and nothing else of ours; no identifiers beyond your IP as seen by GitHub |
| Update download | GitHub release assets | Only after an update is found, and applied only after you restart (never while a game is being measured) | Same as above |
> ⚠ **Accuracy audit, 2026-08-04: the "Safety list update" and "Detection-rules update" rows describe outbound requests the software does not make.** There is no HTTP client anywhere in the product; the anti-cheat blocklist currently ships with the build and is installed locally on first run (`docs/20_OPEN_QUESTIONS.md` §S20 — the seed half is done, the feed half is not). **Over-disclosure is a defect in this document too**: a privacy policy that lists a transmission which never happens is as wrong as one that omits a transmission which does. Either the fetch exists at first release or these rows change.
There is no other request. In particular, the anti-cheat safety list and the detection rules ship **with the build** and are installed locally on first run; the software fetches no rules from anywhere, and it looks nothing up on any store. When a rules feed exists it will be a new version of this document, which the app shows you again before continuing (§6).
GitHub's own privacy practices apply to requests it receives: <https://docs.github.com/privacy>. The Steam lookup, if enabled, is governed by Valve's policies.
GitHub's own privacy practices apply to requests it receives: <https://docs.github.com/privacy>.
## 3. Bug reports — always manual
The "Report a bug" feature builds a zip file **on your device**, shows you exactly which files it contains, and lets you inspect them. Nothing is transmitted by the app; **you** decide whether to attach the file to a GitHub issue in your browser. Logs are redacted (user directory paths removed) before bundling. Optional items (crash dumps, last-session metadata) are included only when you tick their checkboxes.
## 3A. Sharing an export or a bug report
An exported session (CSV or JSON) and a bug report can contain your games' names and **the paths to their files** — which include your **Windows user name** when a game is installed under your user folder — your hardware model, graphics driver and Windows build, the times you played, and your tags and notes. A bug report removes user directory paths from its logs; an export is written as it is. Look at a file before you share it. Once you share it, it is outside FrameLedger: whoever receives it, and the site you post it to, can read it under their own terms.
## 4. What the app can technically observe
To do its job, FrameLedger observes: which of *your tracked* executables are running and their process trees; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); video-memory usage reported by the graphics runtime; loaded module names of a game being captured (for detection and for the anti-cheat safety check); and hardware sensor values from your graphics driver's own libraries.
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), and the store files that name it (Steam's and GOG's, on your disk) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and how busy the processor is and how much memory is in use, from Windows' own counters.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for games you added to your library, and injects only into games you individually enabled.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
All of this stays on your device. None of it is transmitted anywhere.
+17 -10
View File
@@ -1,6 +1,6 @@
# FrameLedger — Third-Party Notices
FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the third-party components below, each under its own license. All listed licenses are compatible with distribution alongside/within a GPL-3.0 application. Full license texts must be shipped in `legal/licenses/` in release packages. Populating that directory is a P4 task, driven by a license-gathering script and enforced at build time by `tools/license-check` (`docs/12_BUILD.md` §Local quality gate).
FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the third-party components below, each under its own license. All listed licenses are compatible with distribution alongside/within a GPL-3.0 application. Full license texts must be shipped in `legal/licenses/` in release packages. Populating that directory was a P4 task, driven by a license-gathering script and enforced at build time by `tools/license-check` (`docs/12_BUILD.md` §Local quality gate) — **built 2026-09-15 (P4 PR-6):** `tools/license-gather.ps1` writes one text per NuGet package the App and the Agent ship into `legal/licenses/nuget/` (the list, `INDEX.md`, is read from the build's restore output, not from this table), the gate fails when that directory is not what the script writes, and a release carries the directory plus the .NET runtime's own licence and notices (`release.yml`).
> ⚠ **Bundling audit — last checked 2026-08-05.** Two rows below claimed material
> this repository does not contain, and the licence gate could not have caught
@@ -29,21 +29,28 @@ FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the th
| Component | Use | License | Notes |
|---|---|---|---|
| **MinHook** | Inline function hooking in `FrameLedger.Overlay` | BSD-2-Clause | Vendored and built from source, pinned by commit. Copyright notice must ship in `legal/licenses/` |
*(The **Intel PresentMon** row was removed on 2026-08-27. It is not bundled, not fetched, not redistributed and no longer used at all — §S31 retired it as a measurement oracle and the owner then dropped it outright — so a notice for it would be over-disclosure, which this document treats as a defect in the same way an omission is. `tools/license-check.ps1`'s matching claim was removed in the same commit, because a bidirectional check whose subject no longer exists cannot go green honestly: it would be asserting agreement about nothing.)*
| Vulkan headers / loader interfaces | `FrameLedger.VkLayer` implicit layer | Apache-2.0 | Khronos headers; layer implemented against the documented loader–layer interface |
| LibreHardwareMonitorLib | GPU sensors (all vendors) + CPU/motherboard sensors (optional, elevated) | MPL-2.0 | See §GPU telemetry below. Consumed unmodified |
| WPF UI (`Wpf.Ui`, lepoco) | Fluent UI theme/controls/navigation | MIT | © lepo.co, Leszek Pomianowski and contributors. License copy must ship with the app (MIT requirement) |
| WPF UI (`Wpf.Ui`, lepoco) | Fluent UI theme/controls/navigation | MIT | © lepo.co, Leszek Pomianowski and contributors. License copy must ship with the app (MIT requirement) — `legal/licenses/nuget/WPF-UI.txt`, the package's own LICENSE.md |
| Fluent UI System Icons | Icon font bundled inside WPF UI | MIT | © Microsoft. Segoe Fluent Icons is **not** bundled (its EULA forbids redistribution) and must not be used |
| CommunityToolkit.Mvvm | MVVM framework | MIT | |
| ScottPlot 5 | Charts | MIT | |
| Serilog (+ file sink) | Logging | Apache-2.0 | |
| Velopack | Installer/updater | MIT | |
| Velopack | Installer/updater | MIT | © Velopack Ltd. (the package's copyright field). Referenced by the App since 2026-09-14 (P4 PR-5); the package ships no licence file, so the text is `legal/licenses/nuget/Velopack.txt` |
| Microsoft.Data.Sqlite / SQLitePCLraw | Database | MIT / Apache-2.0 | SQLite itself: public domain |
| Dapper | Data access | Apache-2.0 | |
| CsWin32 (build-time) | Win32 interop source generator | MIT | Build-time only |
| NVIDIA NVAPI SDK | NVIDIA GPU telemetry + Reflex latency | MIT | **Vendored 2026-08-05** — nine headers + `amd64/nvapi64.lib`, at `src/native/third_party/nvapi/`. See §GPU telemetry below |
| H.NotifyIcon.Wpf | Tray icon | MIT | |
| Markdig | Markdown rendering in the App (since beta.12): the Legal Gate, Help, About, the update notes | BSD-2-Clause | © Alexandre Mutel. The package ships no licence file; its text is the project's own `license.txt` at the packaged commit, a reviewed override (`tools/license-overrides/Markdig.txt`) → `legal/licenses/nuget/Markdig.txt`. Consumed unmodified; HTML in a document is shown as text, never interpreted, and no image is fetched |
| **Transitive, under LibreHardwareMonitorLib** — BlackSharp.Core, DiskInfoToolkit, RAMSPDToolkit-NDD | Hardware access helpers LHM 0.9.6 depends on | MPL-2.0 | Not named by this table until 2026-09-15. **Exhibit B clear:** authenticated code search of each upstream repository (Blacktempel/BlackSharp, /DiskInfoToolkit, /RAMSPDToolkit) finds the sentence once, in `LICENSE` — the template — and no source file carries an MPL notice at all, so the repository licence governs and §3.3 Secondary Licenses applies. Default branch as searched; the nuspecs pin commits `c70b735c`, `25319eae`, `3b47b960`. Source Code Form links are in each package's text |
| **Transitive, under LibreHardwareMonitorLib** — HidSharp; Mono.Posix.NETStandard; System.IO.Ports, System.Management, System.CodeDom, System.IO.FileSystem.AccessControl | USB HID, POSIX helpers, serial ports, WMI | Apache-2.0 (HidSharp's LICENSE.txt); MIT (Mono's LICENSE, reviewed override); MIT (Microsoft) | Mono.Posix.NETStandard declares only a URL; its text is the Mono LICENSE file that URL resolves to, fetched 2026-09-15 and committed as `tools/license-overrides/Mono.Posix.NETStandard.txt` |
| **Transitive, under ScottPlot.WPF** — SkiaSharp, HarfBuzzSharp and their Win32 native assets; OpenTK 4.x; OpenTK.GLWpfControl; OpenTK.redist.glfw | 2-D rendering, text shaping, OpenGL host | MIT; GLFW is zlib (its COPYING.md) | The native Skia and HarfBuzz builds carry their own third-party notices, shipped once each in `legal/licenses/nuget/notices-*.txt`. OpenTK.GLWpfControl declares only a URL (reviewed override, like Mono.Posix) |
| **Transitive** — Microsoft.Extensions.* (Hosting, DependencyInjection, Logging, Configuration, Options, …), Serilog.Extensions.*, Serilog.Sinks.Console, SQLite (SourceGear's native build), SQLitePCLRaw.* | Host, DI, logging plumbing; the SQLite engine | MIT; Apache-2.0; SQLite is public domain | The complete, versioned list is `legal/licenses/nuget/INDEX.md` — 77 packages on 2026-09-15 |
| Roslynator, Meziantou.Analyzer, VS Threading Analyzers (build-time) | Static analysis | Apache-2.0 / MIT | Build-time only |
| **Test-time only, never shipped** — xUnit.net v3 4.x (`xunit.v3.mtp-off`, `xunit.runner.visualstudio`), Microsoft.NET.Test.Sdk, coverlet.collector, FluentAssertions 7.x, NSubstitute; Catch2 (native) | Unit and integration tests, coverage | Apache-2.0 (xUnit.net, <https://github.com/xunit/xunit>; FluentAssertions **7.x only**) · MIT (Test.Sdk, coverlet) · BSD-3-Clause (NSubstitute) · BSL-1.0 (Catch2) | Not named by this table until 2026-09-21. None of them is in a published package: `12_BUILD` publishes App and Agent only, `tools/package-closure-check.ps1` keeps the test projects out of that closure, and `legal/licenses/nuget/` therefore lists none of them. xUnit.net moved 3.2.2 → 4.0.1 on 2026-09-21, same licence. **FluentAssertions is pinned to `[7.2.2]` on purpose**: 8.x is Xceed's Community Licence, not an OSI licence (`Directory.Packages.props`, `20_OPEN_QUESTIONS` §G). Catch2's text is `legal/licenses/catch2-BSL-1.0.txt` |
*(The **Intel PresentMon** row was removed on 2026-08-27. It is not bundled, not fetched, not redistributed and no longer used at all — §S31 retired it as a measurement oracle and the owner then dropped it outright — so a notice for it would be over-disclosure, which this document treats as a defect in the same way an omission is. `tools/license-check.ps1`'s matching claim was removed in the same commit, because a bidirectional check whose subject no longer exists cannot go green honestly: it would be asserting agreement about nothing.)* *(Moved out of the table on 2026-10-03: a line without cells inside a table ended it for Markdig, so the App drew the whole table as text; GitHub draws it either way.)*
## GPU telemetry — what is bundled and what is not
@@ -51,7 +58,7 @@ Telemetry is layered so no proprietary vendor licence is ever required (`docs/18
| Component | How we use it | Licence | Bundled? |
|---|---|---|---|
| **NVIDIA NVAPI SDK** (headers, interface definitions, `nvapi64.lib`) | Planned: NVIDIA-only telemetry, throttle reasons, Reflex/PC latency. **No code links it yet** — the `fl_nvapi` target exists and nothing consumes it | **MIT** — <https://github.com/NVIDIA/nvapi> @ `cd6918f6` (2026-06-24) | **Vendored 2026-08-05** at `src/native/third_party/nvapi/`: nine headers (`nvapi.h` and its include closure, plus `nvapi_interface.h`), `License.txt`, and `amd64/nvapi64.lib` — **x64 only**, `x86/nvapi.lib` deliberately not taken. **Verified 2026-08-02 and re-verified on the vendored copy:** `License.txt` opens "nvapi.lib and nvapi64.lib are licensed under the following terms" + `SPDX-License-Identifier: MIT`, so the grant names the import libraries explicitly and the binary is covered rather than only the headers. Every vendored header retains its own SPDX MIT block, which `license-check.ps1` asserts file by file |
| **NVIDIA NVAPI SDK** (headers, interface definitions, `nvapi64.lib`) | NVIDIA-only telemetry — temperatures, GPU-domain utilisation, clocks, fan, throttle reasons, PCIe width, driver version, and the driver's per-process NGX words. ~~**No code links it yet** — the `fl_nvapi` target exists and nothing consumes it~~ **Linked by `FrameLedger.NvapiBridge.dll` since 2026-09-10** (P2 PR-E2): the only shipped binary that links `nvapi64.lib`, loaded by the Agent into its own process and never into a game; the unshipped `fl-probe-nvapi` links it too. Reflex/PC latency is a hook fact, not an NVAPI query (`docs/20_OPEN_QUESTIONS` §M8) | **MIT** — <https://github.com/NVIDIA/nvapi> @ `cd6918f6` (2026-06-24) | **Vendored 2026-08-05** at `src/native/third_party/nvapi/`: nine headers (`nvapi.h` and its include closure, plus `nvapi_interface.h`), `License.txt`, and `amd64/nvapi64.lib` — **x64 only**, `x86/nvapi.lib` deliberately not taken. **Verified 2026-08-02 and re-verified on the vendored copy:** `License.txt` opens "nvapi.lib and nvapi64.lib are licensed under the following terms" + `SPDX-License-Identifier: MIT`, so the grant names the import libraries explicitly and the binary is covered rather than only the headers. Every vendored header retains its own SPDX MIT block, which `license-check.ps1` asserts file by file |
| `nvapi64.dll` (runtime implementation) | Loaded at runtime from the user's system | Part of the NVIDIA graphics driver | No — never redistributed by us |
| **LibreHardwareMonitorLib** | GPU sensors for **all vendors** (AMD, Intel, NVIDIA) + CPU/board sensors when elevated | **MPL-2.0** | Yes, as an unmodified NuGet package |
| **DXGI + Windows performance counters (PDH)** | Vendor-neutral baseline: utilisation, VRAM, adapter identity | Windows OS APIs | n/a |
@@ -89,16 +96,16 @@ Any proposal to add a vendor SDK must first pass the checklist in `docs/18_GPU_V
## Trademarks
All product names, logos, and brands are property of their respective owners and are used for identification purposes only (see `DISCLAIMER.md` §4).
All product names, logos, and brands are property of their respective owners and are used for identification purposes only (see `DISCLAIMER.md` §6).
## Attribution requirements checklist (release gate)
- [ ] `legal/licenses/` contains full texts: MIT (per-project copies, **including `nvapi-MIT.txt`**), BSD-2-Clause (MinHook), MPL-2.0, Apache-2.0
- [ ] About → Third-party tab lists this table with versions filled from `Directory.Packages.props`
- [x] `legal/licenses/` contains full texts: MIT (per-project copies, **including `nvapi-MIT.txt`**), BSD-2-Clause (MinHook), MPL-2.0, Apache-2.0 — **2026-09-15 (P4 PR-6):** the vendored natives' copies as before, plus one generated text per shipped NuGet package in `legal/licenses/nuget/` (77), gated by `license-check` §3; the .NET runtime's licence and notices are added to the package by `release.yml`. The copies ship: the App's publish carries `legal/licenses/` as `licenses/`
- [x] About → Third-party tab lists this table with versions ~~filled from `Directory.Packages.props`~~ — **built beta.12 (2026-10-03)**: Help ▸ About ▸ *Third-party licences* renders this file and `licenses/nuget/INDEX.md` — every shipped package with its version and licence, generated from what the build restores rather than from `Directory.Packages.props` — with a button that opens the published `licenses\` folder. ~~not built as of 2026-09-16 and not a gate for the first pre-release: the texts ship as files (`licenses/` beside the App, `licenses/nuget/INDEX.md` lists every package with its version), and Help ▸ Documentation opens this file; the tab is an open UI item~~
- ~~PresentMon license + copyright shipped beside the bundled binary~~ — **removed 2026-08-27 with the dependency.** Nothing Intel-authored is distributed by this project
- [ ] MPL-2.0 source-availability note points to upstream LibreHardwareMonitor repository
- [x] MPL-2.0 source-availability note points to upstream LibreHardwareMonitor repository — every MPL-2.0 package text in `legal/licenses/nuget/` names its Source Code Form (MPL-2.0 §3.2), LHM's `https://github.com/LibreHardwareMonitor/LibreHardwareMonitor` included (2026-09-15)
- [x] LHM checked for MPL-2.0 Exhibit B on any depended-upon file — clear as of 0.9.6 / commit `3d331e33`, 2026-08-02
- [x] **AMD FidelityFX headers are vendored** (2026-09-04) — five headers, MIT **by exception**: `license-check.ps1` §2d asserts each vendored path against the exception list inside the vendored `license.md` and each header's own banner, file by file. No binary, no source
- [x] **AMD FidelityFX SDK 3.0 host headers are vendored** (2026-09-05) — ten headers at tag `fsr3-v3.0.4`, MIT at the root **and** inline: `license-check.ps1` §2e asserts the root grant and every header's banner, file by file, in a directory of its own because the licence shape differs from the row above. No binary, no source, no shaders
- [x] **NVAPI is vendored** (2026-08-05) and all nine headers carry their `SPDX-License-Identifier: MIT` blocks unmodified — asserted file by file, not sampled. `license-check.ps1` enforces that this line and the table agree with the filesystem, **in both directions**: vendoring the material while the table still said "Not yet" failed the build, which is how this row came to be flipped
- [ ] No Intel IGCL or AMD ADLX material anywhere in the tree (CI grep, see `docs/13_CI_CD.md`)
- [x] No Intel IGCL or AMD ADLX material anywhere in the tree — `tools/license-check.ps1` §1 greps for both SDKs' identifiers on every `build.ps1 check` and therefore in CI (`docs/13_CI_CD.md` §Licence guard); ticked 2026-09-16, the check had existed since P0
+47
View File
@@ -0,0 +1,47 @@
# Names and trademarks
FrameLedger measures games on hardware, drivers and platforms made by other companies, so its software and its
documents name their products constantly. This page says how those names are used, and how the name *FrameLedger*
itself may be used. It is information for readers of the repository and of the documentation; it is not one of the
documents the app asks you to accept.
## Other companies' names
Microsoft, Windows, DirectX, Direct3D and DXGI are trademarks of Microsoft Corporation. NVIDIA, GeForce, RTX, DLSS,
Reflex, NVAPI and Streamline are trademarks of NVIDIA Corporation. AMD, Radeon, FSR and FidelityFX are trademarks of
Advanced Micro Devices, Inc. Intel, Arc and XeSS are trademarks of Intel Corporation. Vulkan is a registered trademark
of the Khronos Group Inc.; OpenGL is a registered trademark of Hewlett Packard Enterprise, used under licence by the
Khronos Group. Steam and Valve are trademarks of Valve Corporation; Epic Games, the Epic Games Store and Unreal Engine of
Epic Games, Inc.; Unity of Unity Technologies. GOG, GOG Galaxy and itch.io are trademarks of their respective owners. The
names of anti-cheat and anti-tamper products, and the names and store identifiers of games, belong to their respective
owners. All other product names are trademarks of their respective owners.
They are used **only to say what FrameLedger works with or measures** — for example, which upscaler a game used, or
which anti-cheat product made FrameLedger refuse to load into a game. Such a mention is a statement of fact about
compatibility or detection; it is not a claim about the quality of anyone's product.
**FrameLedger is an independent project.** It is not affiliated with, endorsed by or sponsored by any of these
companies, by any game's developer or publisher, or by any anti-cheat vendor, and none of them supports it.
- The anti-cheat products named in `rules/detection-rules.json` are listed so that FrameLedger can **refuse** to load
into a game protected by them; the list says nothing else about them.
- The games named in `docs/LIST_GAME_TESTED.md` are games the developer ran FrameLedger with, on one machine; the list is
not a benchmark claim and not a recommendation.
## The name FrameLedger
*FrameLedger* is the name of this project. The licence (`LICENSE`, `NOTICE`) gives you broad rights in the software
but, by its additional term (e), **no rights in the name**, the project's logo or its icon, beyond describing truthfully
where a work comes from:
- **fine:** "based on FrameLedger", "a fork of FrameLedger", "compatible with FrameLedger's export format", a link to
the project, an article or video about FrameLedger;
- **not fine:** naming a modified version "FrameLedger", using the icon or name for a build the project did not make,
or suggesting the developer made or endorses something they did not (NOTICE (c)).
`FORKING.md` says what a fork that ships builds should rename.
## Questions
If you represent one of the companies above and believe a mention here is wrong, or you want to ask about using the
FrameLedger name, write to contact@poli0981.dev.
+23 -23
View File
@@ -1,29 +1,29 @@
# Third-party licence texts
Full licence texts for everything FrameLedger bundles or links. Populated at P4
by a licence-gathering script; `tools/license-check.ps1` fails the build if a
vendored component is present here without its licence copy.
Full licence texts for everything FrameLedger bundles or links. The App's publish carries this directory as
`licenses/` beside the executables; `release.yml` adds `licenses/dotnet/` (the .NET runtime's licence and
third-party notices, from the runtime packs that publish used).
Required before the first release
(`legal/THIRD_PARTY_NOTICES.md` §Attribution requirements checklist):
| Path | What it is | Who writes it |
|---|---|---|
| `nuget/` | One text per NuGet package the App and the Agent ship (77 on 2026-09-15), the distinct third-party notice files those packages carry (`notices-*.txt`), and `INDEX.md` | **Generated** by `tools/license-gather.ps1` from the build's restore output — never edited by hand; `tools/license-check.ps1` §3 fails when it differs |
| `apache-2.0.txt` | The Apache-2.0 text: the Vulkan headers, and every Apache-2.0 package in `nuget/` that ships no licence file of its own | Hand-committed |
| `mpl-2.0.txt` | The MPL-2.0 text: LibreHardwareMonitorLib and its three MPL-2.0 dependencies (their packages ship no licence file, so distributing it is our obligation, §3.1) | Hand-committed; `license-check` §2b requires it |
| `minhook-BSD-2-Clause.txt` | MinHook — vendored and built from source | Hand-committed; §2 |
| `nvapi-MIT.txt` | NVIDIA NVAPI SDK — headers + import library vendored | Hand-committed; §2 |
| `streamline-MIT.txt`, `fidelityfx-MIT.txt` | NVIDIA Streamline headers; AMD FidelityFX headers (2.x and 3.0 host) | Hand-committed; §2b, §2d, §2e |
| `jsmn-MIT.txt`, `catch2-BSL-1.0.txt` | jsmn (built into the Overlay); Catch2 (tests only) | Hand-committed; §2 |
| File | Component |
|---|---|
| `minhook-BSD-2-Clause.txt` | MinHook — vendored and built from source |
| `nvapi-MIT.txt` | NVIDIA NVAPI SDK — headers + import library vendored |
| `wpfui-MIT.txt` | WPF UI (lepoco) — MIT requires the notice to ship |
| `librehardwaremonitor-MPL-2.0.txt` | LibreHardwareMonitorLib, consumed unmodified |
| `apache-2.0.txt` | Serilog, Dapper, the analyzers, Vulkan headers |
| `mit.txt` | Shared text for the MIT-licensed NuGet packages |
`wpfui-MIT.txt` (2026-09-14) and `velopack-MIT.txt` (2026-09-14) were hand copies of texts the generator now
writes as `nuget/WPF-UI.txt` and `nuget/Velopack.txt`; they were removed with P4 PR-6 so each package has one
source. ~~`librehardwaremonitor-MPL-2.0.txt`~~ and ~~`mit.txt`~~ were planned names in this file that never
existed: the MPL text is `mpl-2.0.txt`, and MIT is written per package because its notice names the holder.
Two of these are release-blocking questions, not paperwork
(`docs/20_OPEN_QUESTIONS.md` §M3, §M4):
~~Two of these are release-blocking questions, not paperwork~~ — **both came back clean on 2026-08-02**
(`docs/spike-notes.md` §M3, §M4; `docs/20_OPEN_QUESTIONS.md` records them resolved):
- **NVAPI** — confirm the exact vendored artifact is MIT, *including*
`nvapi64.lib`. The import library may not be covered by the same grant as the
headers. If it is not, Reflex / PC latency has no alternative source.
- **LibreHardwareMonitor** — confirm no depended-upon file carries MPL-2.0
**Exhibit B** ("Incompatible With Secondary Licenses"), which would remove the
GPL-compatibility route and leave no sensor layer for any vendor.
Answer both before writing NVAPI or LHM code, not after.
- **NVAPI** — the vendored artifact, `nvapi64.lib` included, is MIT.
- **LibreHardwareMonitor** — no depended-upon file applies MPL-2.0 **Exhibit B**, so the GPL-compatibility route
holds. The three MPL-2.0 packages LHM 0.9.6 pulls in (BlackSharp.Core, DiskInfoToolkit, RAMSPDToolkit-NDD) were
not part of that search; they were checked the same way on 2026-09-15 and are recorded in
`legal/THIRD_PARTY_NOTICES.md`. A version bump of any of them is a new search, not an inherited answer.
+17
View File
@@ -0,0 +1,17 @@
BlackSharp.Core 1.0.7
Licence declared: MPL-2.0
Text below: the shared MPL-2.0 text; the package ships no licence file
Copyright: Florian K.
Authors: BlackSharp.Core
Project: https://github.com/Blacktempel/BlackSharp
Ships in: Agent, App
MPL-2.0 Exhibit B: not found in the package's 2 text file(s); the package ships no source, so the upstream repository is where it would have to be ruled out
-------------------------------------------------------------------------------
Subject to the terms of the Mozilla Public License, Version 2.0. The full text is mpl-2.0.txt in the directory above this one.
Source Code Form (MPL-2.0 section 3.2): https://github.com/Blacktempel/BlackSharp
Copyright: Florian K.
@@ -0,0 +1,25 @@
CommunityToolkit.Mvvm 8.4.2
Licence declared: MIT
Text below: License.md, verbatim from the package
Copyright: (c) .NET Foundation and Contributors. All rights reserved.
Authors: Microsoft
Project: https://github.com/CommunityToolkit/dotnet
Ships in: App
Third-party notices: notices-79498b27081b.txt (ThirdPartyNotices.txt)
-------------------------------------------------------------------------------
# .NET Community Toolkit
Copyright © .NET Foundation and Contributors
All rights reserved.
## MIT License (MIT)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+14
View File
@@ -0,0 +1,14 @@
Dapper 2.1.86
Licence declared: Apache-2.0
Text below: the shared Apache-2.0 text; the package ships no licence file
Copyright: 2019 Stack Exchange, Inc.
Authors: Sam Saffron,Marc Gravell,Nick Craver
Project: https://dapperlib.dev/
Ships in: Agent, App
-------------------------------------------------------------------------------
Licensed under the Apache License, Version 2.0. The full text is apache-2.0.txt in the directory above this one.
Copyright: 2019 Stack Exchange, Inc.
+17
View File
@@ -0,0 +1,17 @@
DiskInfoToolkit 1.1.2
Licence declared: MPL-2.0
Text below: the shared MPL-2.0 text; the package ships no licence file
Copyright: Florian K.
Authors: DiskInfoToolkit
Project: https://github.com/Blacktempel/DiskInfoToolkit
Ships in: Agent, App
MPL-2.0 Exhibit B: not found in the package's 2 text file(s); the package ships no source, so the upstream repository is where it would have to be ruled out
-------------------------------------------------------------------------------
Subject to the terms of the Mozilla Public License, Version 2.0. The full text is mpl-2.0.txt in the directory above this one.
Source Code Form (MPL-2.0 section 3.2): https://github.com/Blacktempel/DiskInfoToolkit
Copyright: Florian K.
@@ -0,0 +1,32 @@
H.GeneratedIcons.System.Drawing 2.4.1
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: not stated by the package
Authors: havendv
Project: https://github.com/HavenDV/H.NotifyIcon
Ships in: App
-------------------------------------------------------------------------------
MIT License
Copyright: not stated by the package (authors: havendv)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+32
View File
@@ -0,0 +1,32 @@
H.NotifyIcon.Wpf 2.4.1
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: not stated by the package
Authors: havendv
Project: https://github.com/HavenDV/H.NotifyIcon
Ships in: App
-------------------------------------------------------------------------------
MIT License
Copyright: not stated by the package (authors: havendv)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+32
View File
@@ -0,0 +1,32 @@
H.NotifyIcon 2.4.1
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: not stated by the package
Authors: havendv
Project: https://github.com/HavenDV/H.NotifyIcon
Ships in: App
-------------------------------------------------------------------------------
MIT License
Copyright: not stated by the package (authors: havendv)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,31 @@
HarfBuzzSharp.NativeAssets.Win32 8.3.1.1
Licence declared: MIT
Text below: LICENSE.txt, verbatim from the package
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://go.microsoft.com/fwlink/?linkid=868515
Ships in: App
Third-party notices: notices-78954f26302a.txt (THIRD-PARTY-NOTICES.txt)
-------------------------------------------------------------------------------
Copyright (c) 2015-2016 Xamarin, Inc.
Copyright (c) 2017-2018 Microsoft Corporation.
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+30
View File
@@ -0,0 +1,30 @@
HarfBuzzSharp 8.3.1.1
Licence declared: MIT
Text below: LICENSE.txt, verbatim from the package
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://go.microsoft.com/fwlink/?linkid=868515
Ships in: App
-------------------------------------------------------------------------------
Copyright (c) 2015-2016 Xamarin, Inc.
Copyright (c) 2017-2018 Microsoft Corporation.
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+203
View File
@@ -0,0 +1,203 @@
HidSharp 2.6.4
Licence declared: the file LICENSE.txt in the package
Text below: LICENSE.txt, verbatim from the package
Copyright: Copyright 2010-2025 James Bellinger
Authors: James F. Bellinger
Project: https://software.seekye.com/hidsharp
Ships in: Agent, App
-------------------------------------------------------------------------------
HIDSharp
Copyright 2010-2025 James F. Bellinger <http://software.seekye.com/hidsharp>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
+87
View File
@@ -0,0 +1,87 @@
# Packages the App and the Agent ship
Generated by `tools/license-gather.ps1` from the restore output of the two publish roots. Do not edit a
file here by hand: `tools/license-check.ps1` fails when this directory differs from what the script writes.
The .NET runtime a self-contained package carries is not listed; `release.yml` copies its licence and notices
from the runtime packs the publish used.
| Package | Version | Licence | Ships in | Text |
|---|---|---|---|---|
| BlackSharp.Core | 1.0.7 | MPL-2.0 | Agent, App | [BlackSharp.Core.txt](BlackSharp.Core.txt) |
| CommunityToolkit.Mvvm | 8.4.2 | MIT | App | [CommunityToolkit.Mvvm.txt](CommunityToolkit.Mvvm.txt) |
| Dapper | 2.1.86 | Apache-2.0 | Agent, App | [Dapper.txt](Dapper.txt) |
| DiskInfoToolkit | 1.1.2 | MPL-2.0 | Agent, App | [DiskInfoToolkit.txt](DiskInfoToolkit.txt) |
| H.GeneratedIcons.System.Drawing | 2.4.1 | MIT | App | [H.GeneratedIcons.System.Drawing.txt](H.GeneratedIcons.System.Drawing.txt) |
| H.NotifyIcon | 2.4.1 | MIT | App | [H.NotifyIcon.txt](H.NotifyIcon.txt) |
| H.NotifyIcon.Wpf | 2.4.1 | MIT | App | [H.NotifyIcon.Wpf.txt](H.NotifyIcon.Wpf.txt) |
| HarfBuzzSharp | 8.3.1.1 | MIT | App | [HarfBuzzSharp.txt](HarfBuzzSharp.txt) |
| HarfBuzzSharp.NativeAssets.Win32 | 8.3.1.1 | MIT | App | [HarfBuzzSharp.NativeAssets.Win32.txt](HarfBuzzSharp.NativeAssets.Win32.txt) |
| HidSharp | 2.6.4 | the file LICENSE.txt in the package | Agent, App | [HidSharp.txt](HidSharp.txt) |
| LibreHardwareMonitorLib | 0.9.6 | MPL-2.0 | Agent, App | [LibreHardwareMonitorLib.txt](LibreHardwareMonitorLib.txt) |
| Markdig | 1.4.0 | BSD-2-Clause | App | [Markdig.txt](Markdig.txt) |
| Microsoft.Data.Sqlite.Core | 10.0.12 | MIT | Agent, App | [Microsoft.Data.Sqlite.Core.txt](Microsoft.Data.Sqlite.Core.txt) |
| Microsoft.Extensions.Configuration | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.txt](Microsoft.Extensions.Configuration.txt) |
| Microsoft.Extensions.Configuration.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Abstractions.txt](Microsoft.Extensions.Configuration.Abstractions.txt) |
| Microsoft.Extensions.Configuration.Binder | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Binder.txt](Microsoft.Extensions.Configuration.Binder.txt) |
| Microsoft.Extensions.Configuration.CommandLine | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.CommandLine.txt](Microsoft.Extensions.Configuration.CommandLine.txt) |
| Microsoft.Extensions.Configuration.EnvironmentVariables | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.EnvironmentVariables.txt](Microsoft.Extensions.Configuration.EnvironmentVariables.txt) |
| Microsoft.Extensions.Configuration.FileExtensions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.FileExtensions.txt](Microsoft.Extensions.Configuration.FileExtensions.txt) |
| Microsoft.Extensions.Configuration.Json | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Json.txt](Microsoft.Extensions.Configuration.Json.txt) |
| Microsoft.Extensions.Configuration.UserSecrets | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.UserSecrets.txt](Microsoft.Extensions.Configuration.UserSecrets.txt) |
| Microsoft.Extensions.DependencyInjection | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.DependencyInjection.txt](Microsoft.Extensions.DependencyInjection.txt) |
| Microsoft.Extensions.DependencyInjection.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.DependencyInjection.Abstractions.txt](Microsoft.Extensions.DependencyInjection.Abstractions.txt) |
| Microsoft.Extensions.Diagnostics | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Diagnostics.txt](Microsoft.Extensions.Diagnostics.txt) |
| Microsoft.Extensions.Diagnostics.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Diagnostics.Abstractions.txt](Microsoft.Extensions.Diagnostics.Abstractions.txt) |
| Microsoft.Extensions.FileProviders.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.FileProviders.Abstractions.txt](Microsoft.Extensions.FileProviders.Abstractions.txt) |
| Microsoft.Extensions.FileProviders.Physical | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.FileProviders.Physical.txt](Microsoft.Extensions.FileProviders.Physical.txt) |
| Microsoft.Extensions.FileSystemGlobbing | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.FileSystemGlobbing.txt](Microsoft.Extensions.FileSystemGlobbing.txt) |
| Microsoft.Extensions.Hosting | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Hosting.txt](Microsoft.Extensions.Hosting.txt) |
| Microsoft.Extensions.Hosting.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Hosting.Abstractions.txt](Microsoft.Extensions.Hosting.Abstractions.txt) |
| Microsoft.Extensions.Logging | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.txt](Microsoft.Extensions.Logging.txt) |
| Microsoft.Extensions.Logging.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.Abstractions.txt](Microsoft.Extensions.Logging.Abstractions.txt) |
| Microsoft.Extensions.Logging.Configuration | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.Configuration.txt](Microsoft.Extensions.Logging.Configuration.txt) |
| Microsoft.Extensions.Logging.Console | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.Console.txt](Microsoft.Extensions.Logging.Console.txt) |
| Microsoft.Extensions.Logging.Debug | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.Debug.txt](Microsoft.Extensions.Logging.Debug.txt) |
| Microsoft.Extensions.Logging.EventLog | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.EventLog.txt](Microsoft.Extensions.Logging.EventLog.txt) |
| Microsoft.Extensions.Logging.EventSource | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Logging.EventSource.txt](Microsoft.Extensions.Logging.EventSource.txt) |
| Microsoft.Extensions.Options | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Options.txt](Microsoft.Extensions.Options.txt) |
| Microsoft.Extensions.Options.ConfigurationExtensions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Options.ConfigurationExtensions.txt](Microsoft.Extensions.Options.ConfigurationExtensions.txt) |
| Microsoft.Extensions.Primitives | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Primitives.txt](Microsoft.Extensions.Primitives.txt) |
| Mono.Posix.NETStandard | 1.0.0 | a URL only: https://go.microsoft.com/fwlink/?linkid=869050 | Agent, App | [Mono.Posix.NETStandard.txt](Mono.Posix.NETStandard.txt) |
| OpenTK.Audio.OpenAL | 4.9.4 | MIT | App | [OpenTK.Audio.OpenAL.txt](OpenTK.Audio.OpenAL.txt) |
| OpenTK.Compute | 4.9.4 | MIT | App | [OpenTK.Compute.txt](OpenTK.Compute.txt) |
| OpenTK.Core | 4.9.4 | MIT | App | [OpenTK.Core.txt](OpenTK.Core.txt) |
| OpenTK.GLWpfControl | 4.3.3 | a URL only: https://github.com/varon/GLWpfControl/blob/master/LICENSE.md | App | [OpenTK.GLWpfControl.txt](OpenTK.GLWpfControl.txt) |
| OpenTK.Graphics | 4.9.4 | MIT | App | [OpenTK.Graphics.txt](OpenTK.Graphics.txt) |
| OpenTK.Input | 4.9.4 | MIT | App | [OpenTK.Input.txt](OpenTK.Input.txt) |
| OpenTK.Mathematics | 4.9.4 | MIT | App | [OpenTK.Mathematics.txt](OpenTK.Mathematics.txt) |
| OpenTK.redist.glfw | 3.4.0.44 | the file COPYING.md in the package | App | [OpenTK.redist.glfw.txt](OpenTK.redist.glfw.txt) |
| OpenTK.Windowing.Common | 4.9.4 | MIT | App | [OpenTK.Windowing.Common.txt](OpenTK.Windowing.Common.txt) |
| OpenTK.Windowing.Desktop | 4.9.4 | MIT | App | [OpenTK.Windowing.Desktop.txt](OpenTK.Windowing.Desktop.txt) |
| OpenTK.Windowing.GraphicsLibraryFramework | 4.9.4 | MIT | App | [OpenTK.Windowing.GraphicsLibraryFramework.txt](OpenTK.Windowing.GraphicsLibraryFramework.txt) |
| RAMSPDToolkit-NDD | 1.4.2 | MPL-2.0 | Agent, App | [RAMSPDToolkit-NDD.txt](RAMSPDToolkit-NDD.txt) |
| ScottPlot | 5.1.59 | MIT | App | [ScottPlot.txt](ScottPlot.txt) |
| ScottPlot.WPF | 5.1.59 | MIT | App | [ScottPlot.WPF.txt](ScottPlot.WPF.txt) |
| Serilog | 4.4.0 | Apache-2.0 | Agent, App | [Serilog.txt](Serilog.txt) |
| Serilog.Extensions.Hosting | 10.0.0 | Apache-2.0 | Agent, App | [Serilog.Extensions.Hosting.txt](Serilog.Extensions.Hosting.txt) |
| Serilog.Extensions.Logging | 10.0.0 | Apache-2.0 | Agent, App | [Serilog.Extensions.Logging.txt](Serilog.Extensions.Logging.txt) |
| Serilog.Sinks.Console | 6.1.1 | Apache-2.0 | Agent | [Serilog.Sinks.Console.txt](Serilog.Sinks.Console.txt) |
| Serilog.Sinks.File | 7.0.0 | Apache-2.0 | Agent, App | [Serilog.Sinks.File.txt](Serilog.Sinks.File.txt) |
| SkiaSharp | 3.119.0 | MIT | App | [SkiaSharp.txt](SkiaSharp.txt) |
| SkiaSharp.HarfBuzz | 3.119.0 | MIT | App | [SkiaSharp.HarfBuzz.txt](SkiaSharp.HarfBuzz.txt) |
| SkiaSharp.NativeAssets.Win32 | 3.119.0 | MIT | App | [SkiaSharp.NativeAssets.Win32.txt](SkiaSharp.NativeAssets.Win32.txt) |
| SkiaSharp.Views.Desktop.Common | 3.119.0 | MIT | App | [SkiaSharp.Views.Desktop.Common.txt](SkiaSharp.Views.Desktop.Common.txt) |
| SkiaSharp.Views.WPF | 3.119.0 | MIT | App | [SkiaSharp.Views.WPF.txt](SkiaSharp.Views.WPF.txt) |
| SQLite | 3.53.4 | the file LICENSE.txt in the package | Agent, App | [SQLite.txt](SQLite.txt) |
| SQLitePCLRaw.config.e_sqlite3 | 3.0.5 | Apache-2.0 | Agent, App | [SQLitePCLRaw.config.e_sqlite3.txt](SQLitePCLRaw.config.e_sqlite3.txt) |
| SQLitePCLRaw.core | 3.0.5 | Apache-2.0 | Agent, App | [SQLitePCLRaw.core.txt](SQLitePCLRaw.core.txt) |
| SQLitePCLRaw.provider.e_sqlite3 | 3.0.5 | Apache-2.0 | Agent, App | [SQLitePCLRaw.provider.e_sqlite3.txt](SQLitePCLRaw.provider.e_sqlite3.txt) |
| System.CodeDom | 10.0.2 | MIT | Agent | [System.CodeDom.txt](System.CodeDom.txt) |
| System.Diagnostics.EventLog | 10.0.12 | MIT | Agent | [System.Diagnostics.EventLog.txt](System.Diagnostics.EventLog.txt) |
| System.IO.FileSystem.AccessControl | 5.0.0 | MIT | Agent, App | [System.IO.FileSystem.AccessControl.txt](System.IO.FileSystem.AccessControl.txt) |
| System.IO.Ports | 10.0.3 | MIT | Agent, App | [System.IO.Ports.txt](System.IO.Ports.txt) |
| System.Management | 10.0.2 | MIT | Agent, App | [System.Management.txt](System.Management.txt) |
| Velopack | 1.2.0 | MIT | App | [Velopack.txt](Velopack.txt) |
| WPF-UI | 4.3.0 | MIT | App | [WPF-UI.txt](WPF-UI.txt) |
| WPF-UI.Abstractions | 4.3.0 | MIT | App | [WPF-UI.Abstractions.txt](WPF-UI.Abstractions.txt) |
| WPF-UI.DependencyInjection | 4.3.0 | MIT | App | [WPF-UI.DependencyInjection.txt](WPF-UI.DependencyInjection.txt) |
@@ -0,0 +1,17 @@
LibreHardwareMonitorLib 0.9.6
Licence declared: MPL-2.0
Text below: the shared MPL-2.0 text; the package ships no licence file
Copyright: LibreHardwareMonitor
Authors: LibreHardwareMonitorLib
Project: https://github.com/LibreHardwareMonitor/LibreHardwareMonitor
Ships in: Agent, App
MPL-2.0 Exhibit B: not found in the package's 1 text file(s); the package ships no source, so the upstream repository is where it would have to be ruled out
-------------------------------------------------------------------------------
Subject to the terms of the Mozilla Public License, Version 2.0. The full text is mpl-2.0.txt in the directory above this one.
Source Code Form (MPL-2.0 section 3.2): https://github.com/LibreHardwareMonitor/LibreHardwareMonitor
Copyright: LibreHardwareMonitor
+47
View File
@@ -0,0 +1,47 @@
Markdig 1.4.0
Licence declared: BSD-2-Clause
Text below: tools/license-overrides/Markdig.txt, a reviewed copy of the project's own licence file; the package ships none
Copyright: Alexandre Mutel
Authors: Alexandre Mutel
Project: https://xoofx.github.io/markdig
Ships in: App
-------------------------------------------------------------------------------
Reviewed override for Markdig 1.4.0 (tools/license-gather.ps1).
The package declares <license type="expression">BSD-2-Clause</license> and ships no licence file. The text
below is the project's own license.txt at the commit the package names (<repository commit=
"56e9c238584a44a169f174c881855c049768634c">), fetched on 2026-10-03 from
https://raw.githubusercontent.com/xoofx/markdig/56e9c238584a44a169f174c881855c049768634c/license.txt,
verbatim. The package's <copyright> field is "Alexandre Mutel"; the file names the same holder.
Used by the App since beta.12 to render the documents it shows (the Legal Gate, Help, About, the user guide);
consumed unmodified.
-------------------------------------------------------------------------------
Copyright (c) 2016-2026, Alexandre Mutel
All rights reserved.
Redistribution and use in source and binary forms, with or without modification
, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,32 @@
Microsoft.Data.Sqlite.Core 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://docs.microsoft.com/dotnet/standard/data/sqlite/
Ships in: Agent, App
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.Binder 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.CommandLine 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.EnvironmentVariables 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.FileExtensions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.Json 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration.UserSecrets 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Configuration 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.DependencyInjection.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.DependencyInjection 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Diagnostics.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Diagnostics 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.FileProviders.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.FileProviders.Physical 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.FileSystemGlobbing 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Hosting.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Hosting 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging.Configuration 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging.Console 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging.Debug 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging.EventLog 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging.EventSource 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Logging 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,33 @@
Microsoft.Extensions.Options.ConfigurationExtensions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
Copyright: © Microsoft Corporation. All rights reserved.
Authors: Microsoft
Project: https://dot.net/
Ships in: Agent, App
Third-party notices: notices-b7d456965950.txt (THIRD-PARTY-NOTICES.TXT)
-------------------------------------------------------------------------------
MIT License
Copyright: © Microsoft Corporation. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Loaded 100 of 1351 files, more files were not shown because too many files have changed in this diff. Show more