Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 8727c99123 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
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 23:53:36 +07: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
472 changed files with 24365 additions and 1506 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.
+33 -4
View File
@@ -21,12 +21,28 @@
# 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:
@@ -71,9 +87,13 @@ jobs:
- name: Version gate (tag vs VERSION, CHANGELOG section)
id: version
shell: pwsh
env:
DRY_RUN: ${{ github.event_name == 'workflow_dispatch' }}
DISPATCHED_VERSION: ${{ inputs.version }}
run: |
$ErrorActionPreference = 'Stop'
$tag = $env:GITHUB_REF_NAME
$dry = $env:DRY_RUN -eq 'true'
$tag = if ($dry) { 'v' + $env:DISPATCHED_VERSION.TrimStart('v') } else { $env:GITHUB_REF_NAME }
$m = [regex]::Match($tag, '^v(\d+\.\d+\.\d+)(-[0-9A-Za-z.]+)?$')
if (-not $m.Success) { throw "tag '$tag' is not vMAJOR.MINOR.PATCH[-prerelease]" }
$full = $tag.Substring(1)
@@ -83,10 +103,18 @@ jobs:
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) { throw 'release notes' }
if ($LASTEXITCODE -ne 0) {
if (-not $dry) { throw 'release notes' }
Write-Host "::warning::CHANGELOG.md has no '## [$full]' section yet - a dry run continues with placeholder notes; a real tag stops here"
[System.IO.File]::WriteAllText('out/notes.md', "DRY RUN of $full - CHANGELOG.md has no ``## [$full]`` section yet.`n", [System.Text.UTF8Encoding]::new($false))
# The runner's pwsh wrapper ends the step with `exit $LASTEXITCODE`, so a handled failure must clear it
# (measured 2026-09-16: the first rehearsal printed the warning and then failed with the script's exit 1).
$global:LASTEXITCODE = 0
}
"version=$full" >> $env:GITHUB_OUTPUT
"prerelease=$pre" >> $env:GITHUB_OUTPUT
Write-Host "releasing $full (pre-release: $pre)"
"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
@@ -205,6 +233,7 @@ jobs:
Get-Content out/release/SHA256SUMS.txt
- name: Create the GitHub Release
if: steps.version.outputs.dry_run != 'true'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
@@ -221,7 +250,7 @@ jobs:
if: always()
uses: actions/upload-artifact@v7
with:
name: release-${{ github.ref_name }}
name: release-${{ steps.version.outputs.version || github.ref_name }}${{ steps.version.outputs.dry_run == 'true' && '-dry-run' || '' }}
path: |
out/release/**
out/notes.md
+913 -2
View File
@@ -14,13 +14,815 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
> **Built 2026-09-14 (P4 PR-5).** From 2026-08-06 until then this paragraph said the workflow
> "will" exist and that a missing section "will mean an empty release note"; the second half
> was the wrong design and is replaced rather than implemented. This file still has no
> `## [x.y.z]` heading: the first one is the owner's, in the commit that cuts the first tag.
> was the wrong design and is replaced rather than implemented. ~~This file still has no
> `## [x.y.z]` heading: the first one is the owner's, in the commit that cuts the first tag.~~
>
> **The first heading is `## [0.1.0-beta.1]` (2026-09-16), and it is a summary rather than the moved
> entries.** The instruction above says "move the `[Unreleased]` entries under the heading"; by the first
> tag those entries were 370 KB — every PR since 2026-08-04 — and a GitHub release body holds 125,000
> characters. So the versioned section is a written summary of what the pre-release is and is not, and
> the entries it summarises stay below it, verbatim, under a heading that is not a version
> (`## Ledger before 0.1.0-beta.1`), where `release-notes.ps1` stops reading. From the second tag on,
> the entries under `[Unreleased]` are short enough to move as written.
## [Unreleased]
_Nothing yet — entries continue here after `0.1.0-beta.8`._
## [0.1.0-beta.8] - 2026-09-25
**The eighth pre-release: anti-cheat is found before you ask, a session says what the game and the driver were, and
a frame-generation session's numbers and charts are the application's.** The same unsigned installer: verify its
hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
- **Anti-cheat is looked for harder, and before you ask.** Twenty-two families (74 entries), any kernel driver in a
game's folder, and per-title lists by Steam app id and executable name. The Agent checks every game in your library
on its own, turns hooking off for those with anti-cheat, and their pages show what was found instead of the hooking
switch. Their sessions are still recorded, with play time and sensors.
- **A game's page says what its files say** — 64-bit or 32-bit, the file and store versions, the DLSS / FSR / XeSS
libraries it ships — and a 32-bit game's hooking cannot be turned on.
- **NVIDIA App overrides are shown**: each session records the driver profile the game ran under (DLSS preset and
mode, frame generation, Smooth Motion), read from the driver and never changed.
- **Reasons read as what they are**: End task is not a crash, a refusal says what happened, a launch that could not
start says why, a missing executable says whether its drive is disconnected.
- **Trend works on first open**, with Native and Presented FPS as two metrics, and FPS can show two decimals
(Settings ▸ Window).
- **A frame-generation session's lows, median and stutter are over application frames**, a pause no longer counts as
one long frame, and the charts draw what they say — including the sensors of a session that was not hooked.
- **The Privacy Policy (2.4) is updated**, so the Legal Gate opens once after the update: it now names what the
software reads to check every library game for anti-cheat, the version information of the game's files, and the
NVIDIA driver's settings for your games — all on your PC, none of it sent anywhere.
**Updating from `0.1.0-beta.7`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schemas 0010–0013 add columns; the database opens in place.
- Shortly after the Agent starts it checks every game in your library for anti-cheat, once; a game where it finds
some has its hooking turned off for good, with a notice if hooking was on.
- Sessions recorded before keep the numbers they were stored with; the corrected lows and the in-step sensor overlay
apply to sessions recorded from now on.
### Added
- **FrameLedger finds the anti-cheat games in your library on its own, and hides their hooking switch** (owner decision
2026-09-25). The Agent now scans every game in the library for anti-cheat — once, and again whenever the rules or the
game's executable change — where until now it scanned only a game someone asked to hook, so most games had never
been scanned at all. A game it finds anti-cheat in has its hooking turned off for good, as any finding does, and a
notice says so when hooking had been on. The library card says **Anti-cheat**; the game's page says what was found —
"BattlEye — its module BEClient_x64.dll was loaded in the game", "Easy Anti-Cheat — its folder EasyAntiCheat ships
with the game", in your language — in place of the Hooking switch, which could only be refused. Settings ▸ Capture ▸
*Hide hooking on anti-cheat games* (on by default) brings the disabled switch back beside the finding. Sessions of
such a game are still recorded, with play time and sensors. The scan reads the game's files only: it opens no process
and decides nothing on its own — every session start still runs the full check. Schema 0010 adds three columns; the
database opens in place, and the first scan of the library runs when the Agent starts.
- **The game page has a Details card: what the game's files say about it.** Whether the executable is 64-bit (x64),
32-bit (x86), ARM or .NET "any CPU"; its file and product versions; the store's build ("Steam build 20374416" — the
subtitle labels it that way too, instead of a bare number); the engine; and the upscaler and frame-generation files
it ships with their versions — "DLSS: nvngx_dlss.dll 3.7.10.0", Streamline, FSR, XeSS. FSR is named by its file: its
DLL's version is the SDK's, and FrameLedger does not guess which FSR that is. The capture agent reads every game in
the library once after the update. Schema 0011 adds four columns; the database opens in place.
- **A session's summary lists the libraries the game had loaded** — recorded since the first beta and shown nowhere
until now — and says when one differs from the copy the game ships ("nvngx_dlss.dll 310.2.1.0 (the game ships
3.7.10.0: another copy was loaded, for example by the driver or the NVIDIA App)").
- **FPS with two decimals** (Settings ▸ Window ▸ *Show FPS with two decimals*, off by default): every FPS figure reads
"62.40" instead of "62". Whole numbers now round half up (62.5 is 63); they rounded half to even.
- **FrameLedger says when the NVIDIA App overrides a game's DLSS.** Each session now records the NVIDIA driver profile
the game ran under — read from the driver's own settings, never from the game — and its summary says what that
profile overrides: "NVIDIA profile “…”: DLSS override (preset K, Quality) · Frame Generation override (×4)", Ray
Reconstruction, Streamline's override, a forced frame-generation mode, Smooth Motion. It also says what the driver
reported applying inside the game ("DLSS DLL chosen by the driver · preset K · Quality"), and the game page's Details
card names the overrides from the newest session. These are the driver's settings, not measurements: what FrameLedger
measured is shown as before. FrameLedger only reads these settings; it never changes them. Schema 0012 adds one
column; the database opens in place.
- **A 32-bit game's hooking switch cannot be turned on, and the page says why**: FrameLedger's hook runs in 64-bit
games only. Until now the switch turned on and every launch was refused by the guard. A 32-bit game whose hooking
was already on has it turned off the first time the capture agent reads it; its sessions are still recorded, with
play time and sensors.
### Changed
- **The anti-cheat blocklist names twenty-two families, twice as many, most through more than one signal.** New:
EA AntiCheat, Activision Ricochet (`randgrid.sys` and its `atvi-randgrid_*` services — the family 19_SAFETY carried
as "no data yet" since August), NetEase Anti-Cheat, NetEase Yidun, Nexon Game Security (BlackCipher), TenProtect,
AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion. Existing families gained the groups they
lacked: BattlEye's driver `BEDaisy.sys` and its services, FACEIT's and ESEA's drivers and services, HoYoverse's
`HoYoKProtect.sys` (which the `mhyprot` prefix never matched), Xigncode3's driver and service, Denuvo Anti-Cheat's
driver, GameGuard's folder, files and service, EAC's `start_protected_game.exe` launcher and setup files. 19 entries
became 74 (rules `2026.09.3`). Every new name is documented — SteamDB's file-detection rules (MIT), the vendors'
support pages, LOLDrivers, DRML — and none is measured on a real title yet; each entry's `note` says which. Three
services are deliberately left out because they run outside play and would refuse every session on the machine:
`EAAntiCheatService`, PunkBuster's `PnkBstrA`, and Denuvo's update service.
- **Check 3 is live in both halves, and the per-title lists are seeded** (rules `2026.09.4`, owner decision
2026-09-25). The store half reads the store's own files through a seam the guard owns — `appmanifest_*.acf` in the
Steam library that holds the game, `goggame-<id>.info` for GOG — so nothing is handed in by a caller and nothing is
read from the game. 30 Steam app ids and 33 executable names across nine families are listed: Valve's VAC titles
(CS2, Dota 2, TF2, Deadlock and the older ones), VALORANT and League of Legends, Roblox, Blizzard's online titles,
Call of Duty, Marvel Rivals, NARAKA, FragPunk, Once Human, Delta Force, Arena Breakout: Infinite, HoYoverse's games,
Battlefield 2042/6 and EA SPORTS FC 25/26 — the titles whose anti-cheat leaves nothing of the game's own for the
other checks to find. A game no store names is not refused by this half; a Steam library whose manifests cannot be
read is. Both lists are floored like the families, so a rules file can add a title and never take one off, and the
validator refuses names engines share (`Game.exe`, `Client-Win64-Shipping.exe`…). The AreWeAntiCheatYet bulk list was
considered and declined: community data that outlives a game's anti-cheat would turn hooking off for good.
- **Any kernel driver in a game's folder counts as anti-cheat** (owner decision 2026-09-25). A `*.sys` file in the
install tree that no rule names is reported as "Kernel driver in the game folder" and turns that game's hooking off,
like any finding. Every driver found in a game so far was an anti-cheat's; this catches the next one before anyone
names it. It is code, so no rules file can remove it — and a game that ships a driver for another reason loses
hooking with no way back, which is the trade the owner took.
- **FSR 3's and XeSS's DX11 libraries count as "Supports FSR" / "Supports XeSS"** (rules `2026.09.5`):
`ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` and `libxess_dx11.dll` matched no rule before.
- **The guard holds 256 blocklist entries instead of 64** (2 × 74 no longer fitted the worst case of the compiled-in
floor plus a drifted file). The parsed rules are ~530 KB, so they are now reset in place instead of being copied from
a temporary: the Vulkan layer parses them on whichever of a game's threads creates its Vulkan instance, and a
temporary that size on a small thread stack would crash the game. The native tests hold them on the heap.
### Fixed
- **A frame-generation session's lows, median, min / max, σ and stutter count are over application frames**, as
`03_METRICS` always said they were: they were computed over every present, generated ones included, so a ×2
session's 1% low could sit above its native average, and a game that submits its generated frames in a burst —
the owner's Onimusha demo capture, DLSS frame generation ×3 — read a median of 2,073 FPS at a native 60. Sessions
recorded before this release keep the numbers they were stored with; their charts use the corrected rule.
- **Pausing capture no longer puts a pause-long frame and the paused minutes into the session.** The first frame
after a resume was measured from the last one before the pause; it follows a gap now, and every average is over
the time that was measured. Records lost when the capture agent fell behind are left out of that time the same way,
so an average reads the rate the game ran at rather than the survivors spread over the lost time.
- **The charts are honest about what they draw.** The frametime chart's default line is application frame to
application frame (it was each frame's interval to the generated frame before it), of the one swapchain the
statistics are over (two swapchains' intervals were drawn interleaved); the every-present line no longer draws
0 ms frames after gaps and says that presents are timed at submission; segments are labelled with their settings;
the sensor overlay is in step with the frames (it was drawn from the session's start, tens of seconds early —
schema 0013 records where the first frame sits, so sessions recorded before keep the overlay off). The histogram
is binned over the 0.5th–99.5th percentile with its bars centred on their bins; the percentile curve and its
1% / 0.1% low markers are drawn only where the session has the frames for them, the rule the stat cards follow.
The Sensors charts put power on a watt axis, call the memory plot *Memory*, leave out VRAM readings of 0, give
every line its own colour in the light theme too, and chart **sessions that were not hooked** — their sensors
were recorded and shown nowhere.
- **A game's page updates when one of its sessions finishes** — its sessions, trend and header kept what the page
opened with until it was left and reopened.
- **The Trend tab was blank the first time a game's page opened.** It is drawn at once, on a date axis that keeps its
label and the theme's colours. "Average" is two metrics now — Native FPS and Presented FPS — so a line never mixes
the two, and never shows a presented rate that includes generated frames. Temperatures, loads, power and memory
include sessions recorded without hooking; points that describe only part of their session are drawn hollow; several
hardware changes on one day are one marker.
- **A steady-state frame-generation factor always shows the share of the session it covers** — the average card,
Compare and the Sessions grid's FG× column dropped it. The game header's "Lifetime average" was the last measured
session and is labelled so.
- **Compare**: the best value is highlighted in the accent colour (it was only bold), two values that read the same are
both best, CPU and GPU load are not ranked, the percentile chart spans 0–100 again, and exported PNGs have a solid
background.
- **Ending a game with End task is no longer a "crash".** Every non-zero exit code was one, and Task Manager leaves 1.
A crash is now an exception's exit code or Windows' own crash record, and the session summary says how each session
ended: "crashed (0xC0000005 access violation)", "ended with exit code 1 — what End task and taskkill leave". The
crash safety still counts an early abnormal exit of either kind, so hooking still turns itself off after two in a row.
- **Reasons read as what they are.** Every way a session can end has its own sentence, a refusal that names no
anti-cheat says what happened ("the game is 32-bit…", "the game's process could not be opened") instead of calling
its detail "detected in this game", a launch that could not start says why (for example "the game requires
administrator rights"), and a missing executable says whether its drive is disconnected or the file is gone. A
refusal's details were stored so that a detail could be read as an anti-cheat's name; they are stored in three fixed
places now, and older sessions are read correctly.
- **The NVIDIA bridge's native test could not fail on a machine with an NVIDIA GPU.** It was registered to pass on
its "which branch" line alone, which makes ctest ignore the exit code; its reference-counting check had been failing
on every GPU machine unseen. The check is corrected and a failed assertion now fails the test.
- **Turning hooking on for an Unreal game now sees its `EasyAntiCheat` folder.** The scan that runs when hooking is
enabled was given the executable's own folder — `<game>\<Project>\Binaries\Win64\` for Unreal titles — and scanned
exactly that, while `EasyAntiCheat\` sits at the game's root. The session-time scan always looked at the root, so no
injection was ever allowed by the gap, but the toggle could be switched on and the refusal came only at launch. The
guard now takes the executable and finds the root itself, and also checks the executable's name and its store id.
- **A game blocked for anti-cheat no longer offers "Turn hooking back on" after a crash auto-disable.** The button
could only be refused.
- **19_SAFETY's fixture rule is enforced for every family, not eleven.** A generated test walks every value of the
shipped seed and requires it to match its own family in its own group — which also catches a later row that an
earlier prefix shadows. The rules file's note that called XIGNCODE3's `x3.xem` "not a loadable module" is corrected:
XIGNCODE3 loads it as its loader, so the modules group names it too.
## [0.1.0-beta.7] - 2026-09-23
**The seventh pre-release: a program in the library can be left unrecorded, and Steam's own tools already are.** The
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
user:
- **The game page has a Recording switch.** Off, FrameLedger does not watch for that program at all — no session, no
measurement, no injection — and a session of it that is running stops; sessions already recorded stay. The library
card says **Not recorded**. Use it for a utility that starts with Windows: until now every program in the library was
recorded whenever it ran, at every boot.
- **Steam's own tools already in your library start with it off** — Borderless Gaming, Wallpaper Engine, SteamVR,
Blender, the Steam runtimes and Proton — so a tool imported before 0.1.0-beta.5 stops being recorded without you
doing anything.
- **The Privacy Policy (2.3) and the Disclaimer (2.6) are updated**, so the Legal Gate opens once after the update.
**Updating from `0.1.0-beta.6`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schema 0009 adds one column; the database opens in place, and the Steam tools above are switched off once.
- Sessions a tool recorded before stay in its history; to remove them, remove the entry with *Delete sessions too* —
the import will not add it again.
### Added
- **A library entry can be left unrecorded.** Borderless Gaming starts with Windows, and every program in the library
was recorded whenever it ran — so each boot added a session of it, for as long as it ran, to the playtime totals. The
game page now has a **Recording** switch: off, FrameLedger does not watch for that program at all — no session, no
measurement, no injection — and a session of it that is running stops (sessions already recorded stay). The library
card says **Not recorded**. Entries an earlier import made for Steam's own tools (Borderless Gaming, Wallpaper Engine,
SteamVR, Blender, the Steam runtimes and Proton) start with it off; the import has skipped them since 0.1.0-beta.5.
The Privacy Policy (2.3) says so — a program whose recording is off is not watched — and the Disclaimer (2.6) carries
the updated accuracy statement, including the correction made in 0.1.0-beta.6; the Legal Gate shows both once after
the update. Schema 0009 adds one column; the database opens in place.
## [0.1.0-beta.6] - 2026-09-23
**The sixth pre-release: a game is recorded under its own entry, one entry per game after a drive changes its
letter, a game that is not measured is shown while it runs, and RE Engine and FromSoftware games are detected.** The
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
user:
- **Another game's `Game.exe` is no longer recorded under your entry.** A process that matches an entry by file name
only starts nothing — unless it is that entry's own executable on a drive that changed its letter — so an RPG Maker
game can no longer be recorded under another RPG Maker game's name, twice, as *HELLO, HELLO WORLD!* was under
*Flower in Us*.
- **A game that is not measured is shown while it runs.** Hooking off, refused by the guard, or a process Windows
would not open: the Dashboard shows the game, the time and the temperatures, says why nothing is measured, and the
tray turns to recording-only — until now it said "Nothing is being captured." for as long as the game ran.
- **One entry per game when a drive changes its letter.** Two entries for the same executable under two letters
merge on their own (the older one stays, with both histories); a game updated while its drive had another letter is
followed with hooking off; the library import no longer adds a game again under the new letter.
- **A game removed while it runs keeps its session** (under the entry that holds its executable), and a session file
left behind can no longer stop the Agent at every start.
- **RE Engine and FromSoftware games are detected**, engines are shown by name, and a game added by hand whose
executable is `Game.exe` is named after the game.
**Updating from `0.1.0-beta.5`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- No schema change; the database opens in place. Every game is re-detected once (rules `2026.09.2`).
- Session files in `%LOCALAPPDATA%\FrameLedger\tmp` that beta.5 could not store are stored at the Agent's first start —
under the entry that holds their executable — or dropped with a line in `agent-*.log`; the Agent keeps running either
way.
- An entry that a beta.5 file-name match created for another game keeps its wrong name until you rename it (*Edit…*)
or remove it; its executable path says which game it is.
- A game whose **folder** moved — not only its drive letter — now records nothing until *Change executable* points its
entry at the new file.
### Added
- **RE Engine and FromSoftware games are detected.** Capcom's RE Engine titles (RESIDENT EVIL 2/3/4/7/Village, Devil
May Cry 5, Monster Hunter Rise/Wilds, Street Fighter 6, Dragon's Dogma 2, Onimusha…) by their `re_chunk_000.pak`
archive; FromSoftware's (DARK SOULS II/III, ELDEN RING, Sekiro…) by their `.bhd` + `.bdt` archive pairs. Both are
relative signals — a file layout, not a proof — like every engine rule. Every game in the library is re-detected on
the next sweep. Engines are now shown by name ("RPG Maker MV/MZ", "Unreal Engine") instead of the rule's id
(`rpgmaker_mv`). A game added by hand whose executable says nothing (`Game.exe`) is named after the game — RPG
Maker's own title when the folder carries one, else its folder — instead of "Game".
### Fixed
- **Another game's `Game.exe` no longer runs under a library entry — no wrong name, no second session.** On
2026-09-23 00:16 *HELLO, HELLO WORLD!* (itch) started its RPG Maker runtime, `swiftshader\Game.exe`, and the Agent
matched it by FILE NAME to the only entry named `Game.exe`, *Flower in Us*: it recorded the session under that name,
which created a new "Flower in Us" entry at HHW's path, and an NW.js child process then matched the new entry and
started a second session beside the first (57 s and 56 s). A process that matches an entry by file name only now
starts nothing — unless it is that entry's own executable on a drive that changed its letter, in which case the entry
follows it as before — and the log says once that it is not in the library. The same match can no longer move an
entry onto another game whose `Game.exe` has identical bytes (every RPG Maker MV game ships the same one). One session
per executable, whatever id its entry has; a session that could not be hooked is timed by its own executable instead
of any process with its file name; the resolver says in the Agent's log why a process could not be read; an
unreadable entry is logged once instead of every 15 s. **Changed:** a game whose folder moved records nothing until
*Change executable* points its entry at the new file. The "Flower in Us" entry the old match created stays until you
rename it (it points at HHW's `swiftshader\Game.exe`, the file to measure HHW by) or remove it.
- **One entry per game after a drive letter changes — the two side by side become one.** When the owner's USB drive
came back as `H:` for a morning, a second entry was made for each game played from it, and once the letter was back
neither entry could move onto the other's path: two of each game, and "could not be moved" in the log every 15 s.
Now the Agent merges two entries for the same executable (same path on two letters, same size and modification
time): the entry made first stays, the other's sessions join it, a block on either is kept, and no consent moves
between them — it waits while either game runs. A game whose executable changed on the new letter (it was updated
meanwhile) is followed with hooking off, as *Change executable* does; turn hooking on again to measure it. The
library import no longer adds a game again when it is already in the library under another drive letter. And a
database error during the Agent's 15 s library pass no longer stops the Agent.
- **A game removed from the library while it runs no longer loses its session — or stops the Agent at the next
start.** On 2026-09-22 23:26 and 2026-09-23 00:25 a GIRLS' FRONTLINE 2 session ended `FAULTED` on the database's
foreign key: its entry had been removed (and re-imported) while the game ran, and the session was written under the
id it started with. Each left a `.partial` file, and the recovery that runs at every start would have failed on it
the same way — with no guard, so the Agent's host would have stopped at every start and nothing would have been
captured. Now the session is stored under the entry that holds its executable when the one it started with is gone
(the re-imported entry); when no entry does — the game was removed with its sessions — it is dropped with a log line
that says so. Recovery never throws: a file it cannot finalize is set aside as `<guid>.partial.failed`, kept for a bug
report, and the next file is recovered. The `FAULTED` and end-of-session log lines now name the session, the game and
its executable, and the Agent's host logs its own warnings and errors into `agent-*.log`.
- **A game that is recorded without measuring is shown while it runs.** A game with hooking off, one the guard
refused, or one whose process could not be read is recorded (duration, sensors, the reason) since beta.5 — but the
Agent announced only hooked sessions, so for as long as such a game ran the Dashboard said "Nothing is being
captured." and the tray stayed idle. Now the live card shows it with the T2 badge, the elapsed time, the
temperatures, "Recording duration and sensors only — nothing is measured." and why, in the sentence its summary will
use (no FPS readout: nothing is measured, so nothing is shown); the tray turns to recording-only; the refusal notice
appears when the game starts rather than when it exits. A Dashboard opened after a game started shows it at once
(it used to wait for the next start), a session running when the App connects is in the tray, the notice after a
session names that session's game (it could name the previous one), a session that fails is let go of instead of
staying on the card, and an update downloaded after a session ends is ready to install instead of waiting for the
App to reconnect. A game whose executable changed since hooking was turned on — after a store update, usually — now
says so in its summary instead of `RefusedConsentMissing`.
## [0.1.0-beta.5] - 2026-09-22
**The fifth pre-release: the guard override is gone, Tier 2 exists, and a drive that changes its letter is followed.**
The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for
a user:
- **The "Bypass the anti-cheat guard" switch is removed.** Where FrameLedger finds anti-cheat in a game — before it
injects, when a session starts, or during one — it refuses and **turns hooking off for that game**, says so in the
notice and on the game's page, and offers no way to turn it back on for that executable. The terms say so
(Disclaimer 2.5, EULA 1.2), so the Legal Gate opens once after the update.
- **Sessions that could not be hooked are recorded now.** A refused or hooking-off game gets a T2 row with its
duration, hardware telemetry and the reason — the summary says why ("the guard refused — …", "hooking was off for
this game", "Windows would not let FrameLedger open the process"). Until now every such session was thrown away
within a second.
- **A hooking-off entry that runs as administrator (Borderless Gaming, imported from Steam) no longer gets the
"anti-cheat driver" notice**, and Steam's tools are no longer imported as games. An entry you already have for one
stays until you remove it.
- **A drive that changes its letter no longer loses your games.** The Agent finds the same file under the new letter
and moves the entry to it with its consent kept — within about 15 s in the background, at once when you launch the
game, and when you click the hooking switch. The game's page says when its executable is not where the entry points.
**Updating from `0.1.0-beta.4`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schema 0008 drops the five columns of the removed switch; the database opens in place, nothing else changes.
- Entries whose switch was on lose it; if the guard blocked such a game, its hooking is off and its page says why.
### Removed
- **The per-game guard override ("Bypass the anti-cheat guard") is gone** — owner decision 2026-09-22, two pre-releases
after it arrived. Its first real use could not reach a process an anti-cheat driver protects, and where it could
inject it only exposed the user to the risk its own warning described. Removed entirely: the native entries
(`FlGuardedInjectAcknowledged`, its WhenReady twin, `FlGuardIsJudgement`, reason 28), the `SetGuardBypass` message, the
App's card and dialog, the session mark and its export line, the `Safety_Bypass_*` strings, and schema 0007's five
columns (schema 0008 drops them — the first `DROP COLUMN` in the migration set). Sessions that ran under it keep
`guard-bypass=` in their notes. CLAUDE.md rule 2 reads "there is no override" again; Disclaimer 2.5 and EULA 1.2 say
so, so the Legal Gate opens once.
### Added
- **Tier 2 exists now: a session that could not be hooked is recorded — duration, hardware telemetry and the
reason — instead of being thrown away.** Until 2026-09-22 every refusal returned within a second and the 30 s
minimum discarded it (`Discarded (tier 2, exit=Normal, frames=0)` for every one in the owner's log), so "the session
is still recorded" in the notice was false. The loop now holds a refused session open, ticking the telemetry poller,
until the game exits; the row lands as T2 with N/A everywhere a measurement would be, and its summary says why
("Why: the guard refused — Easy Anti-Cheat (…)", "Why: hooking was off for this game", "Why: Windows would not let
FrameLedger open the process"). The unshipped operator host keeps returning at the refusal.
- **A drive that changes its letter no longer loses your games.** When the drive holding a library comes back as
another letter (the owner's external drive: `D:` one evening, `H:` the next morning), every game on it read
"executable unreadable" and a game launched from the new letter ran as a stranger with no consent. The Agent now
finds the same file — same size, same modified time, under exactly one other drive letter — and moves the entry to
it with consent, block and detection kept: within about 15 s in the background sweep, at once when such a game is
launched, and when you click the hooking switch. The game's page says when its executable is not where the entry
points. *Change executable* is still the way to point an entry at a different file.
- **Steam's tools are no longer imported as games**: Steamworks Common Redistributables, Borderless Gaming, Wallpaper
Engine, SteamVR, the Proton and Steam Linux Runtime entries and Blender are skipped by app id. A row you already have
for one of them stays until you remove it.
### Fixed
- **A hooking-off entry that runs as administrator no longer gets the "anti-cheat driver" notice.** Borderless Gaming,
imported from Steam with hooking off, produced a red "hooking refused" notice on every launch: the Agent tried to
open its process before it looked at whether hooking was on. Hooking-off is decided first now — no process is
opened, no resolver, no gate — and the row gets a quiet Tier-2 session like any other hooking-off game.
### Changed
- **A finding turns the game's hooking off, wherever the guard makes it** (`19_SAFETY` §What a finding does to the game). The
pre-scan always did this; now a finding at a session's start or at the 30 s re-scan writes the same block — hooking
off, the reason on the row, the toggle disabled on the game's page — when it names an anti-cheat *in the game* (its
process, its folder, its title lists). A machine-wide driver or service refuses that session only. The notice says
"Hooking has been turned off for this game", the session's notes carry `hooking-turned-off=`, and `CaptureRefused` /
`SafetyUnhook` carry `hookingTurnedOff`.
- **`0.1.0-beta.4`'s notes named a cause they had no evidence for, and are corrected in place** (see its *Updating*
section). The owner reported afterwards that the external USB drive holding the Steam library had a loose cable that
evening. Windows' System and Application logs for 2026-09-21 agree and re-date the day's symptoms: disk resets and
paging errors on that drive from 20:42; `start_protected_game.exe` (20:56) and `GF2_Exilium.exe` (21:45) both
ended with `0xc0000006`, an in-page I/O error — the drive, not FrameLedger, and **FrameLedger had injected nothing
into ELDEN RING in any run**; the Agent's "executable unreadable" for all 46 titles and the two pipe timeouts at
21:12–21:13 sit inside a burst of 30 disk errors. **What the drive does NOT explain, and beta.4's fixes stand on:**
Easy Anti-Cheat's own log says "successfully loaded in-game" for ELDEN RING at 21:29:28, the second the resolver
found a process it could not open (`TargetUnreadable`); the two App instances started 360 ms apart at 21:07; the
English safety texts and the contradictory line are in the screenshot itself.
## [0.1.0-beta.4] - 2026-09-21
**The fourth pre-release: four faults found in the first day of `0.1.0-beta.3`.** The same unsigned installer: verify
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
- **Only one FrameLedger window now.** Starting the App while it is already running (a double-click, or the shortcut
while it sits in the tray) brings the running one forward instead of opening a second one with a second tray icon.
- **The safety texts follow your language.** In a Vietnamese UI the consent dialog, the refusal notices and the
guard-bypass card were English.
- **The guard bypass is honest about what it cannot do.** A game whose anti-cheat protects its process (ELDEN RING
under Easy Anti-Cheat is one) cannot be opened by any other program, so FrameLedger cannot measure it with or without
the bypass, and it will not try to get around that protection. beta.3 showed nothing at all in that case; this build
shows a notice that says so, the bypass warning says it before you accept, and the game page no longer says
"Hooking is disabled" beside a hooking switch that is on.
**Updating from `0.1.0-beta.3`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
> **Corrected the same evening.** This bullet went on to say that on 2026-09-21 "an install over a running Agent left
> a half-replaced folder and the App failed to start three times". **That cause was a guess and the logs do not
> support it**: nothing was installed between the three failed starts (20:59–21:01, `Could not load …
> Microsoft.Data.Sqlite`) and the start that worked at 21:02. What Windows' own event log shows for that hour is a
> failing external USB drive (the owner's report: a loose cable) and two restarts of the PC at 20:57 and 21:02. The
> three failed starts are **unexplained**; the advice to stop the Agent before installing stands on its own.
- The Disclaimer moved to 2.4 (one paragraph about the bypass), so the Legal Gate opens once.
- No schema change. A bypass you already accepted stays on; the new warning text is shown the next time you turn one on.
### Fixed
- **A second App could be started beside the first.** Nothing enforced one instance: the owner's log of 2026-09-21
shows two started 360 ms apart from one double-click — two windows, two tray icons, a second log file, both writing
one ledger — and with "minimize to tray" on, every click on the shortcut made another. The App now claims its data
folder at start (`Services.SingleInstance`, a named mutex and event keyed on the folder); a later start hands over to
the running one, which brings its window forward, and exits. `--diag` still runs beside a running App.
- **A Vietnamese (or Japanese) UI showed the safety texts in English** — the consent dialog, the refusal notices, and
the whole guard-bypass card in beta.3's screenshot. `FrameLedger.Shared`'s string family was never given the UI
culture and fell back to the thread's, which the App's async start does not pass to later dispatcher work.
`App.ApplyCulture` sets both families now. (Japanese safety text is still the English by design, until reviewed.)
- **Under the guard bypass the game page said "Hooking is disabled for this game: …" beside a hooking switch that was
on.** The finding stays on the page and now reads "The guard found: … You chose to bypass it for this game".
- **With the bypass on, a game protected by a kernel anti-cheat produced nothing at all** — no session, and a toast
reading `InjectFailed: TargetAmbiguous`. Measured on the owner's ELDEN RING (Easy Anti-Cheat): the anti-cheat's
driver closes the game's process to other programs, the resolver could read no candidate, and it called that
"ambiguous". It is `TargetUnreadable` now, and it reaches the user as a persistent notice that says what happened,
that nothing was injected or measured, and that **the bypass does not change this and FrameLedger will not work
around another product's protection** (rule 3). The bypass disclosure says the same before it is accepted (its
version is `guard-bypass-dialog/2`), and so does `legal/DISCLAIMER.md` §2A (2.3 -> **2.4**, so the Legal Gate opens
once). The same reason covers a game running as administrator while the Agent does not.
- The refusal notices said "there is no way to override this"; they name the per-game bypass switch and whose risk it is.
### Changed
- The Agent's session log line names what the guard said when it was not a plain allow
(`…; guard=BlockedService/Easy Anti-Cheat/EasyAntiCheat_EOS`), and `started-under-bypass=` for a bypassed start. A
`SafetyUnhook` on the owner's machine left no trace of WHICH finding fired; the pipe event carried it and the log,
which is what survives, did not.
## [0.1.0-beta.3] - 2026-09-21
**The third pre-release.** The same unsigned installer as before: verify its hash against `SHA256SUMS.txt`, then
*More info → Run anyway*. What changed for a user:
- **The terms changed, so the Legal Gate opens once after the update.** They now say plainly that this is beta
software with bugs, that your PC must meet each game's own minimum requirements, and what the new guard bypass means.
- **CPU load, system memory and (when the Agent runs as administrator with PawnIO) CPU temperature are recorded**, and a
game's Trend tab can chart them, the GPU's load and power, VRAM and the ×FG factor across that game's sessions.
Settings ▸ System shows this PC as FrameLedger records it.
- **DLSS is named.** Titles that call DLSS directly read "Unknown upscaler"; they now read "DLSS (driver-reported)"
where the NVIDIA driver reports it — including sessions you already recorded.
- **A game imported from Steam could never hook** when the import picked a helper executable instead of the game
(GIRLS' FRONTLINE 2 was one). The import picks the game now, and the game page shows the executable and can change it.
- **The platform and engine tags were blank white boxes in the light theme.** Fixed.
- **New, off by default, per game: "Bypass the anti-cheat guard (at your own risk)".** Read its warning. Your account
can be permanently banned, and the developers accept no responsibility if you turn it on.
**Updating from `0.1.0-beta.2`:**
- Quit the App (tray icon → Exit) before installing, as before.
- On its first start the ledger migrates to schema 7 (the guard-bypass columns; nothing existing is rewritten).
- **A game an earlier Steam import created for the wrong executable is not rewritten.** Open it, check the path under
its name, and use *Change executable…* (hooking is turned off for it and must be enabled again), or remove it.
- Sessions recorded before this version keep N/A for CPU load, memory and CPU temperature: nothing measured them.
### Fixed
- **DLSS read "Unknown upscaler" on most titles while FSR was named.** Most DLSS titles call NGX directly, and no NGX
hook may exist (the SDK's licence; `20_OPEN_QUESTIONS`), so the hook runs and sees nothing. The NVIDIA driver does
report the feature per process, the Agent has stored that on every session since P2
(`sessions.upscaler_driver_reported`) and the capture host has printed it since 2026-09-06 — **the App never read
it.** It does now: where no hook named an upscaler and the driver reports NGX super resolution created and
evaluated, the library, the session summary, the game page and the live card say **DLSS (driver-reported)** —
attributed, identity only, never a quality. A hook's name still outranks it. Sessions already recorded show it too,
because the column was always written. `unknown` itself now reads "Upscaler not identified". Nothing native changed.
- **A measured DLSS preset is its name, not its number**: `DLSS Balanced`, not `DLSS 2` (`Domain.Metrics.UpscalerNames`,
which `03_METRICS` had promised from the start). Only the Streamline route produces the byte; a value with no name
is shown as stored. A preset derived from the render scale is still not shown — that is an open owner decision.
- **The Games card's platform and engine tags were empty white boxes in the light theme.** They were
`ui:Badge Appearance="Secondary"`, whose WPF UI 4.3.0 trigger repaints the background only and keeps the default
badge's on-accent foreground: near-white text on a near-white fill. They, and the edit dialog's "Detected" marker,
are the App's own `TagPill` now, with the theme's secondary text; `ContrastTests` refuses a Secondary badge in App
XAML beside the four palette appearances it already refused (`08_UI` §Contrast).
- **A game imported from Steam could be a game that never hooks.** Steam names no executable, so the import guessed
"the largest non-helper", and on GIRLS' FRONTLINE 2: EXILIUM that was the embedded browser
`GF2_Exilium_Data\Plugins\ZFGameBrowser.exe`, not the 675 KB Unity player `GF2_Exilium.exe`. Everything downstream is
keyed on the executable path, so hooking enabled on that row could never match the running game, while the same
game added by its exe worked. The locator now ranks by the engines' own layouts (Unity `X.exe` beside `X_Data`,
Unreal `*-Win64-Shipping.exe`), then by a name matching the install folder, then by size; it skips `X_Data\Plugins`
and redistributables folders, knows `browser`/`webview`/`subprocess`/`analyzer`/`vconsole` as helpers, and walks four
levels instead of three. Verified read-only over the owner's Steam library: GF2, Red Dead Redemption 2 (was the
Rockstar launcher installer), Counter-Strike 2 (was `vconsole2.exe`), Rune Factory, Dying Light: The Beast (was
nothing at all). **A row an earlier import created for the wrong executable is not rewritten**: remove it, or use
the new button below.
### Added
- **A per-game "bypass the anti-cheat guard" switch, at your own risk (owner decision 2026-09-21).** Off by default,
never global: there is no setting, no command-line switch and no rules-file field for it. Turning it on opens its
own disclosure, which says what the guard found for that game, that anti-cheat treats a loaded DLL as tampering
whatever it does, that **your account can be permanently banned without warning or appeal**, that FrameLedger does
not hide and never will, and that **by turning it on you accept the entire risk yourself and the developers accept
no responsibility or liability**. It is accepted only by ticking the acknowledgement AND typing `BYPASS`; Enter keeps
the guard on. The Agent stamps it (the App writes nothing), keyed on the executable like consent; turning hooking
off or the executable changing turns it off again. **It overrules the guard's judgement and nothing else**: the kill
switch, a game that was merely added, a missing consent, a foreign payload, a 32-bit target, a failed injection and
a Vulkan title the guard refuses all still refuse. The guard still runs every check and still reports what it
found; the verdict is `AllowedUnderUserBypass`, never `Allow`. **How FrameLedger injects is unchanged** — the same
documented `LoadLibraryW`, the DLL's real name and version info, one chokepoint file (CLAUDE.md rule 3). Every
session started under it is marked, permanently, with what the guard found: in the sessions list, the session
summary, the CSV and JSON exports (schema 0007: `games.guard_bypass_*`, `sessions.guard_bypassed` /
`guard_bypass_family` / `guard_bypass_signal`). A session recovered after an Agent crash does not carry the mark.
CLAUDE.md rule 2, `19_SAFETY`, `02_SPEC` FR-2.7, `SECURITY.md` and `tools/chokepoint-check.ps1`'s own description
are amended with it. Japanese shows this dialog in English until a reviewer signs the translation.
- **CPU load, memory in use and (elevated) CPU temperature are measured.** `sessions.avg_cpu_load`, `avg_cpu_temp`,
`max_cpu_temp` and `avg_ram_mb`, and the `cpu_load` / `cpu_temp` / `ram_mb` sensor series, were in the schema from
0001 with no producer. The telemetry poller now reads the machine beside the GPU on the same 1 Hz tick: CPU time
busy across every logical processor (`GetSystemTimes` — not Task Manager's frequency-scaled "utility") and physical
memory in use, both unprivileged and opening no process. **CPU temperature is read only when the Agent runs as
administrator with PawnIO installed, and has not been checked on real hardware yet**; everywhere else it is N/A,
never 0. Sessions recorded before this keep their nulls; no migration. The live card carries CPU load and
temperature (`SessionProgress.cpuLoadPct`, optional).
- **One game's sessions over time, beyond the frame rate.** The game page's Trend tab gains average GPU load, average
GPU power, max VRAM (game), average CPU load, max CPU temperature, average memory in use, and the **×FG factor**. A
factor that is its session's steady state (rule 6) covers part of the session, so it is left out by default and
drawn marked when "include mid-session changes" is on — never as the session's. The Sensors chart draws CPU
temperature, CPU load and system memory; Compare gains average GPU load, average CPU load and max CPU temperature;
the session summary gains GPU and CPU cards (average load · peak temperature).
- **Settings ▸ System shows this PC** — processor, graphics card and driver, memory, Windows build, primary display —
as FrameLedger records it with every session, with a Copy button; nothing is sent anywhere. The session summary
shows that session's snapshot under its header, and `--diag` prints the machine's. The bug bundle is unchanged.
- **Game page: the row's executable is shown, and "Change executable…" re-points it.** The remedy for a wrong import
guess used to be remove-and-add. The row comes back exactly as a new game would — hooking off, no consent, pre-scan
not run — with consent revoked over the pipe first, as removal does; a block is never cleared by it, and a path
another row owns (in the library, or removed with its sessions kept) is refused.
### Changed
- **The terms say what an end user needs to hear, and must be accepted again.** `legal/DISCLAIMER.md` 2.2 -> **2.3**:
a new §0 (**this is pre-release software — it certainly still has bugs, and the developer is not responsible for
incidents that result**), §2A (the guard bypass, entirely at your own risk, no liability), §4A (**your PC must meet
at least the minimum requirements the game's developer or publisher states — read them first; problems on a machine
below them, or on unstable, overclocked or overheating hardware, are yours and not the developer's**) and §7A (back
up your own data; builds are unsigned, download only from the project's Releases page and verify the hash; no
affiliation with any game, platform or vendor; numbers are for your own information). `legal/EULA.md` 1.0 -> **1.1**
says the same in §2A/§2B. The first-run Legal step shows a short plain-language summary of those points in en/vi/ja
above the documents, which remain the terms. Because both versions moved, the Legal Gate opens once after the update.
The accuracy block's Safety bullet no longer says "There is no override anywhere".
- **Docs that had gone stale.** `legal/THIRD_PARTY_NOTICES.md` gains the test-time row it never had (xUnit.net v3 4.x
under Apache-2.0, FluentAssertions 7.x and why it is pinned, NSubstitute, coverlet, Test.Sdk, Catch2);
`16_WPFUI_SYNTAX` named a TFM this repository never built; `14_TESTING` still called Catch2 and the blocked toggle
future work; README's status line said "pre-alpha" beside three pre-releases; `build.ps1` "skipped" the coverage and
rules gates when their tools were missing, which its own header calls worse than no gate — a missing tool fails now.
- **Two flaky tests, seen on CI the same day.** The native-log test slept a fixed 1500 ms and read the Overlay's log
between two lines (it polls for the last one now); `ParentDumpTests` dumped a child process microseconds after starting
it and got `ERROR_PARTIAL_COPY` (it waits for the child to finish loading). Neither was a product defect.
- **A local native build no longer fails on an uncommitted change.** After the first tag `git describe --dirty`
produces `v0.1.0-beta.2-2-g<12 hex>-dirty`, 35 characters against `FlShmHandshake::buildId`'s 31, so every CMake
configure of a dirty tree was fatal and the workaround was "commit before you build". The id now falls back to an
8-digit abbreviation with `+` for dirty when the long form does not fit; a release is a clean checkout at a tag and
never takes the fallback. Still too long after that is still fatal.
- **Dependencies, 2026-09-21.** The test framework moves from xUnit.net v3 3.2.2 to **4.0.1**, referenced as
`xunit.v3.mtp-off` with `xunit.runner.visualstudio` 4.0.0: 4.0 makes Microsoft Testing Platform v2 the default of the
plain `xunit.v3` package, and `build.ps1`'s gates are VSTest-shaped on purpose (the `XPlat Code Coverage` collector,
the `results.trx` the struct-mirror gate and the 25-minute wall clock read), so the projects take the same 4.x
framework through the variant xunit publishes for that. The tree carried no v2-era API; the one test change is a
race 4.0.1's scheduler found on its first gate run: eight `App.Tests` classes write the process-wide `Strings.Culture`
and ran in parallel, so `StringsTests` read "Settings" where it had just written `vi`. They share one collection now.
Also: Dapper 2.1.86, Microsoft.Data.Sqlite / Microsoft.Extensions.Hosting / System.Diagnostics.EventLog 10.0.12,
CsWin32 0.3.333, Roslynator 5.0.0, Meziantou.Analyzer 3.0.266, Microsoft.NET.Test.Sdk 18.10.1, NSubstitute 6.2.0.
**Deliberately not moved:** `WPF-UI [4.3.0]` and `FluentAssertions [7.2.2]` (8.x is not an OSI licence), both pinned
with their reasons in `Directory.Packages.props`. `legal/licenses/nuget/` is regenerated for the shipped packages
that moved.
## [0.1.0-beta.2] - 2026-09-17
**The second pre-release.** The same unsigned installer as `0.1.0-beta.1`: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user: a finished session whose frame generation
did not stay in one state — a menu, a loading screen — now shows the factor of its steady state with the share of
the session it covers, where `0.1.0-beta.1` showed "factor not counted" for most real sessions; and three faults from
the first day of use are fixed: an App started as administrator started another Agent every few seconds, and each of
them recorded every game; closing the App ended in an error; and a crash dump could hang the process it described.
**Updating from `0.1.0-beta.1`:**
- **Quit the App (tray icon → Exit), then end every `FrameLedger.Agent.exe` in Task Manager before installing.** If the
App was ever started as administrator, some Agents run elevated, and Task Manager can end those only when it runs
as administrator itself.
- On its first start the ledger migrates to schema 6. Sessions recorded before keep the frame-generation result they
were stored with; the steady state applies to sessions recorded from this version on.
- Sessions recorded while more than one Agent was running appear once per Agent. Nothing removes them automatically.
### Fixed
- **Closing the App no longer ends in a Fatal error and exit code 1 (2026-09-17).** Measured on the installed
0.1.0-beta.1: `ui-*.log` recorded `ui: the run ended in an exception` — "the calling thread cannot access this object
because a different thread owns it" — from `TrayHost.Dispose` on every close after an update check. The App waited
with `WaitForShutdownAsync`, which resumes on the thread pool and stops the hosted services there, so the tray icon (a
WPF object whose disposal unsubscribes `Application.Exit`) was removed off its thread; `TearDownAsync` then stopped every
service a second time. The App now waits for the stop request on the dispatcher and stops the host once, from the UI
thread, and `TrayHost.Dispose` marshals to the icon's own dispatcher from any thread (bounded at 5 s; skipped when the
dispatcher has already shut down). Test: `TrayHostTests` disposes a real tray icon from a pool thread while the UI
thread pumps — red on the old code with that exception, green now; skipped where the session has no notification area.
- **A crash dump can no longer hang the process it describes, and the test suite no longer freezes (2026-09-17).**
`FrameLedger.Infrastructure.Tests` hung about one run in eight — it cancelled the first tag's release run after 58
minutes — and the verbose reporter of a hung run showed thirteen tests started and none finished, one of them
`CrashDumpWriterTests.WritesAMinidumpOfThisProcess…`. That test, and the product's crash path in the App and the Agent,
called `MiniDumpWriteDump` on the calling process, which suspends every other thread of it; one holding the heap or
loader lock deadlocks the dumper, and the whole process freezes with it. Forty runs without the test: no hang. The dump
is written by a child now: `CrashDumpWriter.TryWrite` starts `FrameLedger.Agent.exe --write-crash-dump <file>` and waits
up to 30 s, and the helper (`Infrastructure.Diagnostics.ParentDump`) dumps its parent with the same flags — it takes no
pid and refuses unless the parent is still running, started before it and sits in the helper's own directory, so it can
only ever read the App or the Agent (CLAUDE.md rule 4). Forty runs of the suite with the new tests: no hang.
`--blame-hang` (#196) did not stop the hung xUnit v3 executable, so `build.ps1` runs `dotnet test` under a 25-minute
wall-clock limit, kills the tree on expiry and names the test projects that wrote no `results.trx`. Tests:
`ParentDumpTests` (a real minidump of another process; which parent is ours), `CrashDumpWriterTests` (a failing and a
missing dumper), `CrashDumpHelperTests` (the shipped Agent dumps the test process from outside; it refuses a parent
from System32; the flag's surface). Docs: `10_LOGGING` §Crash handling, `12_BUILD` Agent flags, `13_CI_CD` tally.
**A hang in one test process no longer fails the others.** The migration mutex was one name for every ledger
(`Local\FrameLedger.Ledger.Migrate`), so a suite frozen mid-migration held every other process's scratch ledger: on
#199's run `Infrastructure.Tests` hung and seven App and Agent tests failed after 30 s with "another process has been
migrating the ledger". It is the file's now (`MigrationRunner.LockNameFor`; `MigrationLockTests`; `06_DATA_MODEL`
§Migrations). And a failed dump names dbghelp's error instead of 0: CsWin32 declares `MiniDumpWriteDump` without
`SetLastError`, so the code is read with `GetLastSystemError` (`ParentDumpTests`: an exited process).
- **One Agent per data folder: an App started as administrator no longer starts an Agent per connect round
(2026-09-17).** On the owner's machine the installed 0.1.0-beta.1 ran four `FrameLedger.Agent.exe --serve`: the App
opened at 10:04 was elevated, the pipe of the Agent already serving refused it, and it took the refusal for an absent
Agent and started three more, elevated like itself, 17 seconds apart. Nothing in the Agent noticed the first — the
single instance `01_ARCHITECTURE` §Lifecycle specified was never built — so every game launched in the next hour was
injected, read and recorded by all four (four copies of each session, equal frame counts), and the three extras
logged "accept failed" every 260 ms for four hours. The cause of the refusal: `PipeOptions.CurrentUserOnly` compares
the pipe's owner with the client token's default *owner*, which an elevated token sets to Administrators (the elevated
Agents' log files are owned by Administrators, measured), not with its *user*.
- `Infrastructure.Startup.AgentInstanceLock`: a named mutex per data folder, claimed by `--serve` and the console's
`capture` / `launch` / `recover` before logging, rules and the ledger; a second process exits **10** with one line.
- The App starts an Agent only when no process holds the folder and the one it started last has exited; it logs why a
connect failed, once per reason, and the exit code of the Agent it started.
- The pipe states its owner (`O:<user>` in the SDDL) and the client checks the owner against its token user
(`PipeAccessControl.RequireOwnedByCurrentUser`), so an elevated App and an unelevated Agent reach each other in both
directions.
- A pipe instance that cannot be created backs off 250 ms → 10 s and is logged with its Win32 error, once per streak
(CsWin32 declares `CreateNamedPipeW` without `SetLastError`; the error is read with `GetLastSystemError`).
- Tests: `AgentInstanceLockTests`, `OneAgentPerDataFolderTests` (the shipped binary against a claimed scratch folder),
`AgentConnectionTests` (an Agent that is up and does not answer is never started again; the real launcher sees the
claim), `PipeServerClientTests` (the owner; an Administrators-owning token trusts its user's pipe and refuses an
Administrators one — on CI's elevated runner; the backoff logs once with error 231). Docs: `01_ARCHITECTURE`
§Lifecycle, `07_IPC` §C and §Client behavior, `08_UI`, `12_BUILD`, `20_OPEN_QUESTIONS` §G.
### Added
- **A session whose frame-generation state changed publishes its steady state, with its share (2026-09-17, owner
decision — `03_METRICS` §The steady state).** The owner saw the live card show the FG factor all session and the
finished session show "factor not counted" most of the time, and suspected the path from the hook to the UI. The
path is whole: the stored per-frame counts of all nine hooked sessions of 2026-09-16 read 2.00 / 3.00 / 4.00 inside
gameplay. The live card looks at five seconds; the stored row looked at the whole session, split it in eight and
refused it when one bucket departed — and every real session opens with a splash, a menu or a loading screen, so
one session in nine published. The refusal is right (Wukong's session averages to 2.22; its gameplay ran ×4.1) and
stays; what changes is that the gameplay's number is no longer thrown away with the average.
`Domain.Metrics.FgSteadyState`: five-second windows (the live card's own), the ACTIVE windows agreeing within 10 %
that hold the most time, published at ≥ 10 s and ≥ 10 % of the presenting time — `fg_factor` / `native_fps` /
`displayed_fps` from that state's own windows, `fg_factor_scope = 'steady'`, `fg_steady_share` (schema **0006**),
the refusal and its detail kept beside it. The readout is the generated shape with the chip **`×2.0 FG · 75%`** —
the share is never omitted — and a tooltip saying why there is no session-wide factor. Replayed over the nine
sessions through the real `FgWindow`: eight publish (Onimusha ×4.00 60 → 240, Lies of P ×2.00, Hell Is Us ×3.03,
Cronos ×2.00 225 → 451, Wukong ×4.11); the ninth had nine seconds of gameplay. **Two constants moved with it:**
`BucketTolerance` 25 % → 10 % (at 25 % a ×3-then-×4 session published 3.69, and the one published session read
×2.04 for a gameplay of 2.00), and `MultipleStreams` refuses only when the chains' samples interleave — Onimusha
recreates its swapchain on entering gameplay, one stream at a time, and had been refused as two on every session.
CLAUDE.md rule 6 amended. Two strings (en/vi/ja). Tests: `FgSteadyStateTests`, `FgWindowTests` (interleaved vs
sequential), `SessionAggregatorTests`, `FpsPresentationTests`, `LedgerDatabaseTests` (script six), the repository
round trip. Existing rows are not re-aggregated.
### Changed
- **The first tag ran (2026-09-16).** `v0.1.0-beta.1` on `becc208`; `release.yml` run 35111939019. The first attempt
passed the version gate and the substitution and then sat in `Infrastructure.Tests` for 58 minutes — every other
suite green, the same suite 42 s in the rehearsal — until the job's 60-minute limit cancelled it with no test named;
`gh run rerun --failed` on the same tag went green in 11 minutes and created the pre-release with the section's notes
and the checksums appended. `build.ps1` now runs `dotnet test` with `--blame-hang --blame-hang-timeout 15m` (#196) so
the next hang is a named failure; the capture-host suite's `Kill` waits for exit (#194) and the layer-registration
test deletes only its own registry subtree (#188), the two harness races the same evening's merge train kept hitting.
Docs: `13_CI_CD` §release.yml and §ci.yml's tally, `12_BUILD` §Publish & package (the runner's sizes),
`15_ROADMAP` §P5.
## [0.1.0-beta.1] - 2026-09-16
**The first pre-release.** An unsigned installer, `FrameLedger.App-win-Setup.exe`, built by `release.yml` from
this tag; `SHA256SUMS.txt` is published beside it and printed below. SmartScreen will warn (no code signing —
`docs/11_UPDATER.md`); verify the hash, then *More info → Run anyway*. It installs into `%LOCALAPPDATA%\FrameLedger.App`
and keeps its data in `%LOCALAPPDATA%\FrameLedger`; uninstalling asks before touching the data. Windows 10 22H2 is
the supported floor and is **unmeasured** — every measurement below was taken on one Windows 11 machine with an NVIDIA
GPU (`docs/spike-notes.md`).
### What it is
- **A desktop app and a background Agent.** The App (WPF) holds the library, imports it from Steam, GOG, Epic and
itch.io, shows the Dashboard, session summaries, charts, trends and comparisons, Settings, Logs, the tray, the
first-run Legal Gate and the bug report. The Agent watches the library at 1 Hz, records a session whenever a
library game runs, and stores it in a local SQLite ledger. Nothing leaves the machine except the update check
(`legal/PRIVACY_POLICY.md` 2.2).
- **Measurement by hooking, opt-in per game, behind a hard anti-cheat gate.** For a game you enabled — and only
after the consent dialog — the Agent loads `FrameLedger.Overlay.dll` into the game and reads what the game passes
to the graphics APIs: frame times and output resolution from the present call (Direct3D 11/12, OpenGL; Vulkan
through an implicit layer, today only when the Agent itself launches the title); upscaler identity and
render→output resolution from Streamline and FidelityFX calls; the frame-generation factor from Streamline's frame
token and FidelityFX's dispatches, **counted, never assumed**; ray tracing from DXR dispatch and
acceleration-structure hooks. Before injecting, and every 30 s during a session, the guard scans the process
tree for anti-cheat and anti-tamper modules, services and drivers and **refuses** — there is no override — and a
refusal mid-session unhooks within a frame. A game that is not enabled, or is refused, is recorded as duration
and hardware sensors with the reason, and every measured field reads N/A.
- **Honest numbers by rule.** Where frame generation is active the readout is *Native → Displayed (×N FG)*;
where it was identified but the count refused — a session whose frame-generation state changed (menus,
loading screens, alt-tab), or a title with two swapchains — the chip says "factor not counted" and its tooltip
says which bucket and by how much. Ray tracing, path tracing and Ray Reconstruction are Yes / No / N/A, measured
or not at all. The one number that stands alone carries a qualifier saying whether a frame-generation runtime
was loaded.
- **Telemetry** from DXGI and PDH (every vendor), LibreHardwareMonitor (GPU sensors unelevated), and NVAPI on
NVIDIA. CPU and board sensors need PawnIO and elevation and are off by default.
- **Safety and legal surface:** the consent dialog with the disclosure text in en/vi/ja (ja machine-drafted,
marked for review), the kill switch, a crash within 60 s of injection twice auto-disabling hooking for that game,
the Legal Gate (EULA 1.0, Disclaimer 2.2, Privacy Policy 2.2), the bug bundle built locally and redacted,
crash dumps offered only when ticked.
### What it is not, yet
- **No rules feed.** The anti-cheat blocklist and the detection rules ship with the build and update only with the
next release (`docs/20_OPEN_QUESTIONS.md` §S20). A missed anti-cheat is a safety report (`SECURITY.md`).
- **Vulkan in attach mode is unmeasured**, and the layer is registered only when you ask (Settings).
- **The DLSS quality preset reads N/A** on every title measured: no title chains the structure that carries it.
- **AMD and Intel GPUs are unmeasured** for telemetry and for their frame-generation runtimes; XeSS and the newer
FidelityFX frame generation are identified by module, not counted.
- **The frame-generation factor is refused rather than guessed** on whole play sessions that changed state; a
steady-state figure over the uniform part of a session is a decision not yet taken.
- **The ≤ 0.5 % FPS-impact run and the "against the game's own menu" readings** in `docs/spike-notes.md` §14 are
still the owner's to take.
### The record
Everything that landed before this tag — every PR from 2026-08-04 to 2026-09-16, with its reasoning — is the
section *Ledger before 0.1.0-beta.1* below, kept verbatim.
## Ledger before 0.1.0-beta.1 (2026-08-04 → 2026-09-16)
_The `[Unreleased]` entries as they stood when the first tag was cut; `release-notes.ps1` stops before this
heading. Newest first._
### Added
- **P5 prep: a release rehearsal, `SECURITY.md`, and an honest hygiene checklist (2026-09-16).** `release.yml` gains
`workflow_dispatch` with a `version` input: the identical job — the gate, publish, runtime licences, the
published-tree assertion, `vpk pack`, checksums, the artifact — with no tag and no Release, so the steps that had
only ever run by hand on one machine run on the hosted runner before the first tag; a missing `## [x.y.z]` section
is a warning with placeholder notes in a rehearsal and stays a stop on a tag. `SECURITY.md`: the private route for
a vulnerability (GitHub's private reporting when enabled, else e-mail), the public *Safety gap* form for an
undetected anti-cheat, what not to include, and the response *intent* stated as an intent; `ISSUE_TEMPLATE/config.yml`
points a vulnerability at the private route; README's safety-gap paragraph links both. `13_CI_CD` §Repo hygiene
checklist rewritten: the in-tree items were done and unticked, the first box asked for caller stubs the file's own
opening paragraph rejects, and the rest are GitHub settings only the owner can set — listed as such. `14_TESTING`'s
Velopack-delta row says it is reachable from the second release.
- **The "factor not counted" tooltip says which bucket, and by how much — `sessions.fg_refusal_detail`, schema
0005 (2026-09-16).** The owner's Dashboard showed "DLSS-G active — factor not counted" on Hell Is Us, Black Myth:
Wukong, Cronos and Onimusha; three refused `non_uniform` (one of eight equal-sample buckets departed more than
25 % from the whole, or held no tokens — a menu, a loading screen, an alt-tab inside a whole play session) and
one `multiple_streams` (a second swapchain), and the tooltip could only repeat the kind. `FgWindow` had computed
the bucket, its ratio and the window's all along; `SessionAggregator` kept only the kind. Now
`Application.Recording.FgRefusalDetail` — kind, subject, count, bucket index/count, the bucket's ratio (null when it
held no tokens) and the window's — is stored as JSON beside `fg_refusal`, and `FpsPresentation.IdentifiedTooltip`
appends its sentence: "Bucket 3 of 8 measured 2.25 against 3.65 for the whole session, over 53 samples." /
"2 swapchains presented during the session." / "40 samples; at least 64 are needed to check." A kind with no
numbers worth a sentence adds nothing; an unparsable column is the old tooltip. The producer is unchanged and
no number is decided by it (owner's decision 2026-09-16: store and show the reason; no steady-state factor, no
change to `multiple_streams`). Six strings (en/vi/ja). Tests: `SessionAggregatorTests`, `LedgerDatabaseTests`
(script five), `FpsPresentationTests`. Docs: `06_DATA_MODEL` §Migrations, `03_METRICS` §FG factor, `08_UI` §FPS
display rule.
- **RPG Maker is detected — MV/MZ and XP/VX/VX Ace — and `rulesVersion` is `2026.09.1` (2026-09-16).** Two engine
rows `05_DETECTION` marked ⛔ "cannot be expressed in schemaVersion 2": the MV/MZ reasoning wanted a nested group
for `nw.dll` **and** (`www/` **or** `package.json`), but MV and MZ both ship `package.json` beside `nw.dll`
unconditionally, so `all: [nw.dll, package.json]` is the signal — measured on the owner's *Flower in Us* and a
hand-extracted MV title, both `engine=none` until now. The RGSS family is one rule over the three DLL prefixes and
the three archive extensions, no version (which DLL matched is not a value any extractor produces). Both sit
after `unity`/`unreal` and before `godot`. Fixtures `engines/rpgmaker_mv`, `engines/rpgmaker_rgss`; the
`every_engine_marker` canary carries both engines' markers and still expects `unity`. The version bump changes the
sweep's cache key, so every game is re-detected on the Agent's next pass. Docs: `05_DETECTION` §Engine signatures.
- **The bug report's last optional item: the last session's summary, when ticked (2026-09-15).** `10_LOGGING` §Bug
report flow step 2 listed "last session metadata + aggregates JSON (never raw blobs by default)" beside the crash
dump, and `legal/PRIVACY_POLICY.md` §3 promises both only when ticked. The Optional items dialog PR-9 added now shows
a box for each item that exists: the crash dump, and the newest session in the ledger (`LastSessionSummary`) labelled
with its game and start time. Ticked, the zip gains `session.json`, File ▸ Export's own JSON (metadata, aggregates,
segments, hardware) without the user's notes and tags, passed through `LogRedactor` because it names the executable;
no frame or sensor series. With neither item there is no question. `CrashDumpChoice` became `BugBundleOptions`, and
`IBugReportPreview.AskCrashDumpAsync` became `AskOptionsAsync(BugBundleOffer)`. Two strings (en/vi/ja). Tests:
`LastSessionSummaryTests`, `BugReportFlowTests`, `BugBundleOptionsViewModelTests`, `PagesLoadTests`. Docs:
`10_LOGGING` §Bug report flow step 2.
- **P4 PR-9 — the crash dialog, the minidump in both processes, and the crash dump as the bug report's opt-in
(2026-09-15).** `10_LOGGING` §Crash handling specified Fatal → `MiniDumpWriteDump` → a dialog offering the bug report
→ exit code 1; only the Fatal line existed, and `Crash_Title` / `Crash_Body` were translated for a dialog nothing
@@ -241,6 +1043,98 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
### Fixed
- **The legal documents say what the software does, in release form (2026-09-16).** EULA 1.0, Disclaimer 2.2,
Privacy Policy 2.2 — the `-draft` suffix (which `legal_acceptance.version` recorded) and the "Draft for review"
banners are gone, so the Legal Gate shows all three again. **Privacy Policy §2** listed three requests the software
has never made — a weekly safety-list update, a weekly detection-rules update, an opt-in Steam store lookup —
under an audit note saying so since 2026-08-04; version 2.2 keeps the two real rows (Velopack's update check and
download) and says there is no other request, with the removal recorded as history in the document itself. §1 no
longer mentions cover art (no such feature) and states the log retention the code has (7 days App, 14 Agent).
**Disclaimer:** the 25-line accuracy-audit block that sat inside the accepted text moved, unchanged, to
`docs/legal-drift-history.md`; a five-line pointer explains how §4 is kept true (`legal/ACCURACY.md` +
`accuracy-check`); the contact footer the other two documents carry is added. **Third-party notices:** the IGCL/ADLX
box is ticked with its check named (`license-check` §1, in the gate since P0); the About-tab box says it is not
built and not a gate for the first pre-release; the trademarks pointer reads §6. **README** §Privacy collapsed to
one accurate paragraph. **Settings:** the `privacy.online_metadata` toggle is no longer shown — a switch for a request
that has no code is the same over-disclosure — and the setting stays reserved (`06_DATA_MODEL` §Settings registry,
`08_UI`). `20_OPEN_QUESTIONS` §S20: the feed lands as a new policy version, not as rows kept in advance. The
accuracy block's "unreleased" sentence is deliberately untouched: it becomes false with the tag and is rewritten in
the tag commit.
- **itch.io import reads butler's database, so an install location outside `%APPDATA%` is found (2026-09-16).**
`ItchLibrarySource` scanned `%APPDATA%\itch\apps\*\.itch\receipt.json.gz` and nothing else; on the owner's machine
the itch app's one install location is `D:\another\it`, `apps\` is empty, and the import logged `itch — 0 title(s)`
with no reason — every itch title had to be added by hand. The app records its installs in
`%APPDATA%\itch\db\butler.db`: `install_locations` (the folders the user chose), `caves` (one per install, with the
folder name or a custom folder) and its own `verdict` JSON naming the executable butler launches. The adapter now
copies that database to a temporary directory (the running app holds it in WAL mode), opens the copy read-only,
joins the three tables, takes the first Windows candidate of the verdict as the executable (an HTML or Love2D game
leaves the locator's guess), and still scans `apps\` receipts for anything the database does not list; an install
found both ways is one row, the database's. It logs one line per run — what was consulted and what each source
yielded — through the importer's sink, so `0 title(s)` has a reason beside it. `ItchLibrarySource`'s constructor
now takes the itch directory (`%APPDATA%\itch`), not `apps\`. Tests: `StoreLibrarySourcesTests` (a butler.db built
in the test with a location elsewhere, a custom folder, a verdict path with forward slashes, an HTML-only verdict,
a verdict that will not parse, a receipt beside a cave and a receipt-only install; no database and a garbage
database both fall back to receipts and say so). Docs: `05_DETECTION` §Platform signatures.
- **The Games card's hooking chip reads at 2.6:1 no more, and the Dashboard's FG qualifier no longer clips
(2026-09-16).** "Hooking on/off" was `ui:Badge Appearance="Info"`: WPF UI paints that with `PaletteLightBlueBrush`,
a fixed Material colour outside both theme dictionaries, under the theme's white text — `#03A9F4` in dark, below
AA-large — and no `#` in our XAML for `NoXamlHardCodesAColour` to catch. It is a `Border` in the new `HookStatePill`
style now (ON: the accent pair the ×FG chip uses; OFF: the Pill's muted fill with secondary text), the edit
dialog's "Detected" badge is `Secondary`, and `ContrastTests` holds it: no App XAML uses the four palette
appearances, and every pill's (text, fill) pair composited over the card and window backgrounds is ≥ 4.5:1 in both
theme dictionaries, with the old pair asserted below it so the check is known to bite. The FG qualifier chip on the
Dashboard's recent-sessions row was reported with it and had a different defect — a sentence-length qualifier in a
star column with no trimming overflowed the row — so the qualifier text trims with an ellipsis at 260 px (the
readout's tooltip carries the full sentence) and the row's readout column is sized to content with the game's name
trimming first. Docs: `08_UI` §Contrast, `16_WPFUI_SYNTAX` §Theming.
- **A print verb no longer migrates the ledger it prints, and a close checkpoints the WAL it wrote (2026-09-16).**
`FrameLedger.Agent --console sessions`, run against the owner's own ledger while its on-disk file was at schema 2,
applied scripts 0003 and 0004 to it: every verb opened through the one migrating `LedgerDatabase.OpenAsync`. Found
while investigating a ledger whose day of rows lived only in a 4 MB WAL whose 1006 frames carried a salt one
generation older than the WAL header, over a main file no checkpoint had reached — a fresh connection (the console,
a next launch) saw the 14 September state, while the running App and Agent saw the day through the shared WAL
index. The mechanism is unrecorded (`06_DATA_MODEL` §Migrations carries what was observed and what is not known);
the data was rebuilt from the old-salt chain by hand. What changed: `LedgerDatabase.OpenReadOnlyAsync` — an
existing file, `query_only`, no pragma that writes, no `MigrationRunner`; a schema newer OR older than the build is
refused with the reason, and `WriteAsync`/`MaintainAsync` throw. The Agent's `sessions`, `consent list`,
`killswitch status` use it (`Program.PrintsOnly`), `db path` opens nothing at all, and a refusal is a console line
with exit 7, never a crash dump; the App's `--diag` uses it too. `OpenAsync` now runs a passive checkpoint after
migrating and reports it (`LedgerDatabase.OpenDiagnostics`, one `ledger: wal at open` log line), and
`DisposeAsync` runs `wal_checkpoint(TRUNCATE)` and reports that, so a clean close leaves the main file complete
whether or not SQLite's own close-time checkpoint runs. Tests: `LedgerDatabaseTests` (an older schema is refused
byte-for-byte unchanged; a read-only open reads and refuses to write; a missing file creates nothing; a close leaves
the row readable through `immutable=1`), `AgentReadOnlyVerbsTests` (the print-verb set, the refusal's exit code and
the untouched file, `db path` without a ledger). Docs: `06_DATA_MODEL` §Migrations, `12_BUILD` §Debugging,
`10_LOGGING` §Diagnostics, HANDOFF §Traps.
- **A start that fails says so on screen (2026-09-15).** When `App.RunAsync` caught its own exception — a ledger
that would not open (a newer schema, a locked file), a host that would not start — FrameLedger wrote a Fatal line to
`ui-*.log` and exited with code 1 with nothing on screen, so a user saw a click do nothing. It now shows
`StartupFailureDialog`, a Win32 message box like the crash dialog (the shell is what failed): the exception's message,
the log folder, and Yes to open that folder; the exit code is still 1, and a crash the dispatcher already reported
shows no second dialog. Two strings (en/vi/ja). Tests: `StartupFailureDialogTests`. Docs: `10_LOGGING` §Crash
handling.
- **Bug bundles no longer carry the user's name in log paths, which the privacy policy already promised
(2026-09-15).** `legal/PRIVACY_POLICY.md` §3 says "logs are redacted (user directory paths removed) before
bundling" and `10_LOGGING` named a `RedactingEnricher`; neither existed, and `BugBundleBuilder` copied `ui-*.log`,
`agent-*.log` and `overlay-*.log` verbatim on the stated ground that they carry no paths beyond the data directory,
which is itself under the user's profile. On the dev box the profile path appeared 8 times in the UI log, 7 in the
Agent's and in 175 overlay headers. `App/Services/LogRedactor` now rewrites every log copy in the zip: the name in
each `X:\Users\<name>` path becomes `<user>`, and so does a profile directory's last segment elsewhere, in
backslash, doubled-backslash (Serilog's JSON), forward-slash, any-case and ANSI-`?` spellings, byte for byte
otherwise (Latin-1 round trip, so UTF-8 and ANSI logs both survive). The files on disk keep their paths; the policy's
sentence is now true without a word of it changing. Tests: `LogRedactorTests`, `BugBundleBuilderTests`. Docs:
`10_LOGGING` §Serilog configuration (the enricher claim struck, with where the rule is enforced) and §Bug report
flow step 2.
- **Two unmeasured facts were stored as values (2026-09-15).** The quality byte's `0xFF`, the Overlay's "a hook ran
and could not tell" (`fl_shm.h` `upscalerQuality`), was aggregated as a number, so a session and the live card
carried the text `255`, which the game page and the Dashboard append to the upscaler's name: every AMD dispatch
carries `0xFF`, so an FSR title would read "FSR 255". `SessionAggregator` (row and segments) and
`SessionProgressCalculator` now leave those frames out, and a quality nobody told is null (`FrameSample.QualityNotTold`).
And `reflex_active` was written `false` on every hooked row with no latency sample, although nothing measures Reflex
today; it is null there now, so an export no longer says "off" for a thing never measured. Tests:
`SessionAggregatorTests` (not told is null, told frames still count; Reflex null), `SessionProgressCalculatorTests`.
Found while checking `legal/ACCURACY.md` against the code. Not done: naming a preset the hook did read, which
`03_METRICS` assigns to a `Domain.UpscalerNames` that does not exist; no measured title has produced one.
- **Test runs stop filling the real data folder with hook-harness logs (2026-09-15).** The injection tests inject the
shipped Overlay, whose log goes to `%LOCALAPPDATA%\FrameLedger\logs` by design (§S21: not the environment, and no
switch in the injected DLL), so the owner's folder held 2506 overlay logs, 2492 of them hook-harness's from test
@@ -255,6 +1149,23 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
created during the gate and still there, which is red on the unswept tree. Tests: `[sweep]` in `fl_guard_test`,
`HarnessOverlayLogSweepTests`. The logs from before this change are left for the owner. Docs: `17_HOOK_ENGINE`
§Native logging, `12_BUILD` gate list, `14_TESTING`, HANDOFF §Traps. No Overlay change, so no hook-path overhead.
- **The accuracy block says what the code measures on 2026-09-15 (`legal/ACCURACY.md`, embedded in `README.md` and
`legal/DISCLAIMER.md`).** Dated 2026-09-06, it still said there was no Agent loop, storage, charts, library import
or UI, that OpenGL intercepted nothing, that no shipped component drove the 30 s re-scan and that video memory was
not measured — all false since. Every sentence was re-checked against the code: OpenGL is measured; Vulkan only
when FrameLedger starts the game (a running Vulkan title gets the Direct3D component, unverified); FSR is named FSR 3
or unversioned, never FSR 2 or 4; the preset is not reported anywhere; frame generation is Direct3D-only and falls
back to a qualified Presented FPS; whole-card video memory is recorded while per-game VRAM, shader-stutter
attribution, Reflex, HDR and CPU temperature are not; the shipped Agent runs the re-scan and the kill switch can
only refuse. Nothing has been released. `README.md` outside the block: the safety row's "re-scan does not run at
all", the XeSS and "always shown" promises, the Vulkan requirement, CPU temperature, NVAPI's Reflex, and a note that
no release exists. `legal/DISCLAIMER.md` is 2.1-draft (the first-run gate shows it again): two history bullets the
software caught up with are struck, and the path-tracing "confidence-scored suggestion" it never computes is
corrected. Docs that contradicted the code: `04_CAPTURE` (attach mode on a running Vulkan title is not Tier 2 — an
open decision for the owner), `05_DETECTION` (four runtime facts have no writer), `17_HOOK_ENGINE` (`wglSwapBuffers`
is built), `15_ROADMAP` and HANDOFF (`StaticGameDetector` runs in `DetectionSweep`). Stale comments in `dllmain.cpp`
(OpenGL "NOT HERE"), `layer.cpp` (`vkQueuePresentKHR` "NOT hooked") and `fl_guard.cpp` (the signer lookup "not wired
yet") now say what the code does; comments only, no behaviour change.
- **The native log test read another process's log, and was filed as a flake four times (2026-09-14).**
`guard_test.cpp`'s `FindOverlayLog` took the first `overlay-<pid>-*.log` by name in the real
`%LOCALAPPDATA%\FrameLedger\logs`, which keeps every run's log — 2130 on the dev box. A harness that drew a
+6
View File
@@ -12,6 +12,10 @@ 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.
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).
@@ -22,6 +26,8 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
> **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*).
+19 -12
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>
@@ -28,7 +28,7 @@
</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 +37,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,7 +56,7 @@
</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
@@ -64,19 +64,26 @@
<PackageVersion Include="LibreHardwareMonitorLib" Version="0.9.6" />
<!-- The crash witness (04_CAPTURE §Crash & exit classification): Application log events 1000/1001. In-box
for WPF apps, a package for a class library on the Windows TFM. Microsoft, MIT. -->
<PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.10" />
<PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.12" />
</ItemGroup>
<ItemGroup Label="Analyzers (build-time only)">
<PackageVersion Include="Roslynator.Analyzers" Version="4.16.1" />
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.257" />
<PackageVersion Include="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.
@@ -94,7 +101,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>
+79 -43
View File
@@ -5,38 +5,74 @@
> No telemetry. No accounts. All data stays on your machine.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-06.** The software is pre-alpha: the
> measurement path exists as an injected Direct3D 11/12 component and an **unshipped** capture
> host that drives the guard loop and prints a report; there is no Agent loop, no storage, no
> charts, no library import, no UI and no installer yet.
> ⚠ **What FrameLedger actually measures today — 2026-09-25.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.8`** (2026-09-25), 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 hook, for injected D3D11/12
> titles, and for Vulkan titles **launched through FrameLedger** (the layer intercepts
> `vkQueuePresentKHR` since 2026-09-06; a Vulkan title already running when FrameLedger attaches is
> not observed). OpenGL/D3D9 intercept nothing yet.
> - **Which upscaler is running:** measured from the API the game calls — DLSS (with Ray
> Reconstruction Yes/No) through NVIDIA Streamline; FSR 2/3.x/4 through AMD's shipped DLLs; DLSS on
> titles that bypass Streamline is reported from the NVIDIA driver's own per-process record,
> labelled *driver-reported*. Intel XeSS is **not** read (its SDK licence forbids it) and reads
> `N/A` by policy; an upscaler compiled into the game executable reads `N/A`.
> - **Quality preset:** `N/A` everywhere. No route this software may use exposes it.
> - **Render → output resolution:** measured where the vendor's own call carries the size (AMD
> dispatches, some Streamline titles); `N/A` where it does not (NVIDIA-direct titles, most
> Direct3D 12 Streamline titles).
> - **Frame generation:** the Displayed rate is counted from presents — including, on one title,
> presents DXGI counted that the hook could not — and the Native rate from the vendor's own
> per-frame calls where the title makes them. Identity: DLSS-G and FSR-FG named from the calls
> the game makes; anything else (XeSS-FG, a generator compiled into the game) is reported *by
> elimination* and never named. Where no per-frame call exists the Native rate is `N/A`.
> - **Ray tracing:** Yes/No measured from DXR dispatches and acceleration-structure builds on
> Direct3D 12; the technique and path tracing are `N/A`.
> - **Not measured at all:** video memory, shader-compilation stutter, PC latency (Reflex), HDR.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-
> vendor half of the suspicious-module rule (since 2026-09-06), and the unshipped capture host
> re-runs them every 30 s and stops the capture on refusal. No shipped component drives that loop
> yet. There is no override anywhere.
> - **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.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), 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 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.
>
> Where a value is not measured it reads `N/A`; the software never substitutes an estimate.
> 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
@@ -48,8 +84,8 @@
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).
- **Shader-compilation stutter attribution** — which frame spikes were pipeline compiles.
@@ -59,7 +95,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.**
@@ -68,7 +104,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. For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>✅ **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 |
@@ -95,31 +131,31 @@ The tier is recorded on every session and shown in the UI. Metrics unavailable a
| `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.
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (not read yet — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on.
## Requirements
- Windows 10 (22H2) or Windows 11, 64-bit
- A 64-bit DirectX 11/12, 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
## Install
> **The latest pre-release is `v0.1.0-beta.8` (2026-09-25); before it `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 one of them: the update check** — at startup, a few seconds after launch, unless you turn it off in Settings ▸ Updates, and when you choose Help ▸ Check for updates — plus the download of an update you accepted; both go to GitHub Releases, from an installed copy only, and nothing is applied until you restart (never while a game is hooked). The rules feed does not exist — the blocklist ships with the build and updates only when you install a new one (`docs/20_OPEN_QUESTIONS.md` §S20). Listing a fetch that has no code is over-disclosure, and this document was already corrected once for describing a weekly outbound request the software never made.
Everything lives locally in `%LOCALAPPDATA%\FrameLedger`. The only network calls FrameLedger makes are **the update check** — a few seconds after launch unless you turn it off in Settings ▸ Updates, and when you choose Help ▸ Check for updates — and **the download of an update you accepted**; both go to GitHub Releases, from an installed copy only, and nothing is applied until you restart (never while a game is hooked). There is no other request: the anti-cheat blocklist and the detection rules ship with the build and update only when you install a new one (`docs/20_OPEN_QUESTIONS.md` §S20), and nothing is looked up on any store. Bug reports are always built locally, shown to you, and submitted by you. Full policy: [`legal/PRIVACY_POLICY.md`](legal/PRIVACY_POLICY.md) — version 2.2 removed the three rows (a rules feed twice over, a Steam lookup) that earlier versions listed for requests the software never made.
## License
GPL-3.0-only. See `LICENSE`. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras 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.
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
## Documentation
@@ -127,10 +163,10 @@ Developer/AI-facing docs in [`docs/`](docs/). Start with `CLAUDE.md`, then `docs
## 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.
---
**Status:** pre-alpha, under active development. Roadmap: [`docs/15_ROADMAP.md`](docs/15_ROADMAP.md).
**Status:** pre-release (beta). Eight 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.
+49
View File
@@ -0,0 +1,49 @@
# 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.
## 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.
+39 -20
View File
@@ -68,6 +68,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 +272,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 +299,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 +311,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
+10
View File
@@ -93,6 +93,16 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
- UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.
- 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 |
+3 -1
View File
@@ -10,12 +10,14 @@ 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.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.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.**
- 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.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.
+85 -2
View File
@@ -27,7 +27,7 @@ Let `D` = session duration (first → last present), `F_app` = frames the *game*
| **Native FPS (avg)** | `count(F_app) / D` | 1 |
| **Displayed FPS (avg)** | `count(F_disp) / D` | 1 |
| **Presented FPS (avg)** | `presents / D` — **numerically Displayed FPS; the name for the one number that stands alone.** "Native" and "Displayed" are printed only *together* (rule 6); when frame generation is not measured, this is the headline, with a mandatory qualifier (§Frame Generation, rung 0's qualifier) | 1 |
| **FG factor** | `DisplayedFPS / NativeFPS`, shown `×N.N`; `—` when FG inactive; **`N/A` when FG is not measured** — and **`N/A` when FG was *identified* but the count refused** (`fg_mode` a technology, `fg_factor` NULL, `fg_refusal` the reason — schema 0003, 2026-09-14): the one number is then Presented FPS with a warning chip naming the technology, exactly rung 0's third row, because the identity says generated frames may be in the presents and the count cannot say how many. Never `×0.0`, never "Native" | 1 |
| **FG factor** | `DisplayedFPS / NativeFPS`, shown `×N.N`; `—` when FG inactive; **`N/A` when FG is not measured** — and **`N/A` when FG was *identified* but the count refused** (`fg_mode` a technology, `fg_factor` NULL, `fg_refusal` the reason — schema 0003, 2026-09-14 — and `fg_refusal_detail` its numbers: the bucket that departed, its ratio and the window's — schema 0005, 2026-09-16): the one number is then Presented FPS with a warning chip naming the technology, exactly rung 0's third row, because the identity says generated frames may be in the presents and the count cannot say how many. Never `×0.0`, never "Native". **Since 2026-09-17 a session refused as `non_uniform` publishes its STEADY STATE instead** — `fg_factor_scope = steady`, the share beside it (§The steady state, below) | 1 |
| **Avg FPS** (headline) | = Native FPS when `fg_mode` is measured (`api` rung) or `none`; **= Presented FPS, labelled, when `fg_mode` is `N/A`**. Time-based, **not** the mean of instantaneous FPS values | 1 |
| **Median FPS** | `1000 / p50(ft_app)` | 1 |
| **1% Low** | `1000 / p99(ft_app)` | 1 |
@@ -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,6 +393,36 @@ 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
@@ -447,6 +501,15 @@ 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.
@@ -460,6 +523,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
@@ -515,6 +584,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
@@ -620,7 +701,9 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline
| Per-process VRAM | exact | not available |
| PC latency | as reported by Reflex | not available |
| 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.
+100 -6
View File
@@ -74,6 +74,28 @@ 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. **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
> first, and a row whose hooking is off — merely added, blocked by a finding, auto-disabled — goes straight to
> the hold with `RefusedHookNotEnabled` (its verdict is the row's block when it has one, `PreviouslyBlocked`).
> The resolver used to run first, and a hooking-off utility that runs elevated (Borderless Gaming, imported from
> Steam) was reported as a process an anti-cheat driver protects, with the notice that sentence deserves.
> `TargetNotRunning` alone returns at once — there is nothing to hold. Launch mode's two guard refusals
> (`LaunchTargetExited`, `LaunchNoPresentationRuntime`) return at once too, because the descendant election
> is waiting on them. The unshipped operator host sets `HoldUnhooked = false`: to an operator a refusal is the
> answer and the exit code. The discard rule is unchanged: a Tier-2 row under 30 s is still dropped, which is
> now a game that ran under 30 s rather than every refusal. `PartialRecovery` no longer reads a tick as proof of
> a hooked session — a held session flushes ticks with no records and no `attached` note.
**The reason is the payload of Tier 2**, not a consolation attached to it. A session
that records duration and sensors while saying nothing about *why* it measured
nothing is indistinguishable from a broken capture. `sessions.capture_notes` and the
@@ -103,7 +125,7 @@ which makes the notification more important than it was, not less.
## Process watcher
- 1 Hz snapshot via `CreateToolhelp32Snapshot` (CsWin32): pid, ppid, exe path (`QueryFullProcessImageName`).
- Watchlist match on normalized full path (`GetFinalPathNameByHandle` — junctions/symlinks), filename fallback with a stale-path warning badge.
- Watchlist match on normalized full path (`GetFinalPathNameByHandle` — junctions/symlinks), ~~filename fallback with a stale-path warning badge~~ **and a file name alone never starts a session (2026-09-23, HANDOFF D25): it can only be the entry's own executable on a drive that changed its letter (the relocator's rule), or it is not in the library.**
- Process tree assembled from ppid chains; the **capture target** is the descendant that actually presents. In launch mode we know it; in attach mode we wait for the first ring handshake. ~~or (Tier 2) elect the PID with the most presents in the first 10 s~~ — there is no Tier-2 present stream to elect from. Re-elect if the presenting PID dies while the tree lives (level-transition relaunches).
> **Built 2026-09-10 (P2 PR-F), in `Application.Watch` with one adapter.** `ToolhelpProcessSnapshotSource`
@@ -113,7 +135,20 @@ which makes the notification more important than it was, not less.
> both null so it can match nothing. `ProcessWatcher` diffs it against the watchlist — the `games` rows — on the
> normalised full path first and on the file name only when exactly ONE row carries it (`StalePath`, the
> "stale-path warning badge"; the session is keyed on the path the process actually runs from, so consent for the
> old path does not follow the binary). `ProcessTree` reads ppid chains with the one rule that defeats pid
> old path does not follow the binary — **unless it IS the same binary on a drive that changed its letter**, 2026-09-22:
> `CaptureOrchestrator.AdoptIfMovedAsync` asks `ExecutableRelocator` first, and when the row's file is gone and the
> running one has the row's size and mtime, the row is moved and the session is the row's, consent and all;
> `19_SAFETY` §A moved drive is the same executable). **Narrowed 2026-09-23 (D25): a `StalePath` match that is not
> adopted records NOTHING.** The stranger session was keyed on the real path and named after the matched row, and
> `SessionRecorder`'s `EnsureAsync` turned that into a new library entry with the other game's name: *HELLO, HELLO
> WORLD!*'s `swiftshader\Game.exe` became a second "Flower in Us" (the only entry named `Game.exe`), and its NW.js
> children, matching the new entry exactly, started a second session beside the first. Now the process is said once
> in the log ("not in the library, so nothing is recorded") and its exit is silent; the adopt itself accepts only the
> row's path with its drive letter changed (an RPG Maker `Game.exe` has the same bytes in every game); and the
> running-session table is keyed by the executable's path, so a re-imported or merged entry's new id cannot start a
> second session for the same executable. The launch election registers its session there too, and skips a child the
> watcher already records. **Behaviour change:** a game whose folder moved (not its drive letter) records nothing until
> *Change executable* points its entry at the new file. `ProcessTree` reads ppid chains with the one rule that defeats pid
> reuse: a child that started before its parent is not its child. `DescendantElection` picks the newest-started
> descendant whose image is tracked — a launcher's consent does not extend to what it spawns, so the elected image
> needs its own record. `CaptureOrchestrator` is the `--serve` loop: one snapshot per second, ONE session per game
@@ -125,6 +160,16 @@ which makes the notification more important than it was, not less.
> (`05_DETECTION` §Caching) on its own task, because `GameFileProbe` blocks on file I/O and the 1 Hz poll must
> not wait on it. It reads game files and writes the detected columns of `games`; it never touches a process,
> a hook, or a consent column.**
>
> **The watchlist is the entries whose recording is on (2026-09-23, FR-1.6, D29).** Borderless Gaming starts with
> Windows on the owner's machine, and since Tier 2 exists every library entry that runs gets a session — one per boot,
> for as long as the utility ran, in the playtime totals. `games.record_sessions = 0` (schema 0009, the user's switch on
> the game page) takes an entry out of the watchlist `PollOnceAsync` hands the watcher, and out of the launch election's
> tracked set: its process appearing is no event, no session and no log line. Switched off while a session of it runs,
> the orchestrator cancels that session's stop token at its next poll — the loop ends as a user stop and saves what it
> had — and `LaunchGame` answers `RecordingOff`. Switched back on, a process that is still running is picked up by
> the next poll (a pid the watcher never matched is new to it). Detection and the drive-letter relocator still follow
> the entry; they read files, not processes.
## Launch mode vs attach mode
@@ -270,6 +315,12 @@ than a tuning knob. ~~There is no UI thread in P2; the pipe reader (P3) joins as
the pipe's tasks touches the ring or the recorder, and the session loop never waits on a client. The command half (PR-1b) is the
`Channel` producer this sentence anticipated.
> **The pause is a gap (beta.8).** FR-3.9's pause stops the Overlay recording; the loop reads the QPC as it tells the ring
> to resume (`ApplyPause`, before `SetPaused(false)`, on the Overlay's own clock — `Stopwatch` is `QueryPerformanceCounter`)
> and marks a gap before the first drained record stamped at or after it (`MarkResume`). A record drained after the
> resume but stamped before it is a straggler the pause had not reached. `03_METRICS` §Data gaps says what a gap then
> does to the statistics and to `D`.
## Telemetry poller
1 Hz on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) + optional CPU sample when the Agent is elevated and PawnIO is present. Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
@@ -301,8 +352,13 @@ Vulkan loader when the Agent launches an opted-in game, so the path is
> 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: only a launch can set the loader's environment. This is
> 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
@@ -312,6 +368,22 @@ because a layer cannot leave a running game's loader chain.
**Discard rule:** duration < min session length (default 30 s) → discard silently (log only).
> **A session whose entry was removed while it ran (2026-09-23).** Step 5 wrote under the id the session *started*
> with, and the owner's GIRLS' FRONTLINE 2 entry was removed — and re-imported — twice while the game ran: both
> sessions died on the foreign key (`session: FAULTED SqliteException: … FOREIGN KEY constraint failed`, 2026-09-22
> 23:26 and 2026-09-23 00:25), and each left a `.partial` whose recovery would have died the same way at the next
> start — stopping the host, because recovery ran before the watcher with no guard. As built:
> - **The owner is looked up, not assumed** (`ISessionRepository.ResolveOwnerAsync`, `FinalizeInput.ExePath`): the id
> the session started under when that row predates the session or holds its executable (an id SQLite reused for a
> later game is neither — `games.id` has no AUTOINCREMENT), else the row that holds the executable's path now (the
> re-imported entry), else **`GameRemoved`**: the user removed the game with its sessions and this was one of them.
> Nothing is written, the `.partial` is deleted, and the log says which. The write transaction re-checks the row, so a
> removal between the lookup and the insert is the same answer rather than the foreign key's exception.
> - **Recovery never throws.** A file it cannot finalize is set aside as `<guid>.partial.failed` (never retried, kept for
> a bug report) and reported `Failed`; the next file is recovered, and the watcher starts either way.
> - The Agent's host logs through Serilog since the same day: a background service that stops the host is now in
> `agent-*.log`, where before it was in no file at all.
> **Built 2026-09-10 (P2 PR-D): `Application.Recording`.** The state machine above is the intent; what
> runs is one class per box. `SessionRecorder` owns a session end to end — the row's identity and time
> base (`session_guid`, `qpc_epoch`/`qpc_frequency` from `TimeProvider.GetTimestamp`, which is QPC), the
@@ -337,8 +409,8 @@ because a layer cannot leave a running game's loader chain.
## Crash & exit classification
- Normal: presenting PID exit code 0.
- `crashed`: nonzero exit code, **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
- 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.
@@ -356,6 +428,21 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
> exit code and the witness (`end=TargetExited; exit_code=-1073741819; crash_event=application_log`).
> `CrashAutoDisablePolicy` counts only crashes inside the 60 s window after the attach — `hook_crash_count`
> is that count and nothing else — and disables on the second; it never re-enables.
>
> **Corrected 2026-09-25 (beta.8, owner item 5): End task is not a crash.** The owner's sessions ended by Task Manager
> read *Crashed* — every non-zero code was one, and `TerminateProcess` leaves 1. A crash is now an exception's code or
> the event log's witness; any other code is `normal` with the code in the notes, and the session summary says it
> ("ended with exit code 1 — what End task and taskkill leave…", "crashed (0xC0000005 access violation)", "0xC0000006
> in-page I/O error: a disk or drive failed…"). **The safety policy did not get looser:** it takes the exit code beside
> the status and still counts every non-zero exit inside its window — a game the hook hung that the user then ended is
> the shape it exists for — and its row reason says "ended abnormally", not "crashed" (`19_SAFETY` §Crash & stability).
>
> **The notes' guard slot has three positions since the same day:** `guard=Reason|Family|Signal`, every slot present
> and `;` never inside one (`CaptureNotes.GuardSlot`). It was `Reason/Family/Signal` with an empty family dropped, so
> a refusal no family names put its signal where the family goes — and the notice read "Access is denied was detected
> in this game" — and a signal with a `;` was cut there. Old rows are read by the one rule that separates them: findings
> and the gate's own refusals carry a family, every other reason's second part was its signal. A launch that cannot
> start keeps Windows' reason (`launch_error=740`; `IProcessLauncher.Start(…, out win32Error)`).
## Live progress
@@ -368,6 +455,13 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
> stands alone with the census qualifier (`FgLadder.PresentedQualifier`, the row's). CPU temperature is null until the Agent composes a
> CPU sensor, and every other unmeasured field is null, never 0. Rate-limited to 1 Hz inside the observer's `Tick`, computed only while
> a client is connected, and a fault in the computation is counted rather than allowed to end the session.
>
> **A held session is live too (2026-09-23).** The hold's ticks carry the refusal (`CaptureProgress.Held`, with the pid the loop
> holds, 0 for a hooking-off hold that never opened the process). The publisher's first held tick announces the session —
> `SessionStarted` at tier 2 with its `hold`, and the refusal's own event at once rather than when the game exits — and every tick
> after feeds `SessionHeld` (elapsed and sensors, nothing measured) at the same 1 Hz while a client listens. It is never run through
> `SessionProgressCalculator`, whose window over no records would still emit a qualifier. A session whose task faults now also
> completes on the pipe (`finalize: faulted`, `07_IPC`), so nothing is left shown as running.
## Overhead rules (NFR-1)
+106 -15
View File
@@ -27,6 +27,11 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
| Per-process VRAM | `QueryVideoMemoryInfo` |
| PSO compilation events | pipeline-creation hooks |
> **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.
> **"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
> 2026-08-05: `IDXGISwapChain::GetFrameStatistics().PresentCount` counts presents *the
@@ -130,8 +135,10 @@ Recorded as a residual risk, not as a solved problem.
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)` |
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
| 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 |
| 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 |
| CryEngine | `CrySystem.dll` | FileVersion |
| Source | `gameinfo.txt` + `bin/engine.dll` | `N/A` |
@@ -141,10 +148,43 @@ 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.
@@ -155,19 +195,36 @@ Everything else in the table is in the data and has a fixture; `rules-validate.p
| 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 |
| 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.
> **Built 2026-09-14 (P4 PR-4).** `Application.Import.LibraryImporter` over four `IStoreLibrarySource` adapters in
> `Infrastructure.Import` — `SteamLibrarySource` (`libraryfolders.vdf` + `appmanifest_*.acf` through
> `ValveKeyValues`, the Steam root from `HKCU\Software\Valve\Steam\SteamPath`), `GogLibrarySource` (the HKLM
> keys, read-only, the first HKLM read in the tree), `EpicLibrarySource` (`*.item` JSON: `DisplayName`,
> `InstallLocation`, `LaunchExecutable`, `AppName`, `AppVersionString`), `ItchLibrarySource`
> (`%APPDATA%\itch\apps\*\.itch\receipt.json.gz`). **Two stores do not name the game's executable** (Steam,
> itch): `ExecutableLocator` walks the install three levels deep, drops the helpers by name fragment and takes
> the largest — a *guess the review list marks as such*; GOG's `exe` and Epic's `LaunchExecutable` are the store's
> (~~`%APPDATA%\itch\apps\*\.itch\receipt.json.gz`~~ — **since 2026-09-16 butler's database first**: the itch app
> records the install locations the user chose in `%APPDATA%\itch\db\butler.db`, and they need not be under
> `%APPDATA%` at all — on the owner's machine the one location was `D:\another\it` and `apps\` was empty, so the
> receipt scan returned nothing, silently; `install_locations` + `caves` give every install, butler's own `verdict`
> names the executable it launches, and `apps\` receipts are still scanned for what the database does not list. The
> database is copied to a temporary directory and the copy opened read-only, because the running app holds it in
> WAL mode. One log line says what was consulted: `import: itch — butler.db read: 1 location(s), 2 cave(s), …`).
> **Two stores do not name the game's executable** (Steam,
> itch-by-receipt): `ExecutableLocator` walks the install ~~three~~ **four** levels deep, drops the helpers by name
> fragment, everything under a Unity `X_Data\Plugins` folder and every redistributables/prerequisites folder, and then
> **ranks** what is left — ~~takes the largest~~ an executable the engine's own layout names as the game (Unity: `X.exe`
> beside `X_Data`; Unreal: `*-Win64-Shipping.exe`) beats one named after the install folder, which beats a stranger, and
> size decides only between equals. "The largest wins" was measured wrong 2026-09-21 on GIRLS' FRONTLINE 2: EXILIUM:
> the import chose `GF2_Exilium_Data\Plugins\ZFGameBrowser.exe` (1,082,944 bytes) over the 675,392-byte Unity player, and
> because the watcher, consent and the gate are keyed on the executable path, hooking enabled on that row could never
> match the game. The same pass fixed Red Dead Redemption 2 (the 140 MB launcher installer under `Redistributables`),
> Counter-Strike 2 (`vconsole2.exe`), Rune Factory (root bootstrapper vs the shipping binary) and Dying Light: The
> Beast (the game sits four levels down). Still a *guess the review list marks as such*, and since the same date the
> game page shows the row's executable and **Change executable…** re-points it (hooking off and unconsented afterwards,
> exactly as a new game; a block is never cleared by it). GOG's `exe` and Epic's `LaunchExecutable` are the store's
> own. The review (`ImportReviewPrompt`) ticks only what can be imported: a row already in the library or with no
> executable on disk cannot be. Every added row lands exactly as File ▸ Add game… lands it — hooking off — and
> the store's platform, id and version go through `IGameRepository.ApplyStoreMetadataAsync` under the same
@@ -178,7 +235,7 @@ Everything else in the table is in the data and has a fixture; `rules-validate.p
> is fetched (CLAUDE.md rule 8's "opt-in store metadata" is the online lookup, which does not exist). First-run
> step 4 now points at File ▸ Import library… rather than saying "later build".
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days.
**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)
@@ -186,8 +243,8 @@ Files shipped with a game tell us what it *supports*. These populate a **"Suppor
- DLSS SR `nvngx_dlss.dll` · DLSS-G `nvngx_dlssg.dll` · **Ray Reconstruction `nvngx_dlssd.dll`**
- Streamline `sl.interposer.dll`, `sl.dlss_g.dll`, `sl.reflex.dll`
- FSR `ffx_fsr2_*.dll`, `ffx_frameinterpolation_*.dll`, `amd_fidelityfx_*.dll`, `ffx_api*.dll` — a hint still, even though `amd_fidelityfx_dx12.dll` / `_upscaler_dx12.dll` / `_framegeneration_dx12.dll` are *hooked* since 2026-09-04: the measured chip comes from the dispatch, never from the file
- XeSS `libxess.dll`, XeFG `libxess_fg.dll`
- FSR `ffx_fsr2_*.dll`, `ffx_fsr3*.dll` (since rules 2026.09.5 — FSR 3's `ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` matched nothing before), `ffx_frameinterpolation_*.dll`, `amd_fidelityfx_*.dll`, `ffx_api*.dll` — a hint still, even though `amd_fidelityfx_dx12.dll` / `_upscaler_dx12.dll` / `_framegeneration_dx12.dll` are *hooked* since 2026-09-04: the measured chip comes from the dispatch, never from the file
- XeSS `libxess.dll`, `libxess_dx11.dll` (since rules 2026.09.5), XeFG `libxess_fg.dll`
- DXR-capable: `d3d12.dll` usage + RT-capable GPU (capability only — says nothing about the game)
- **Vulkan (since P4 PR-2, 2026-09-14) — a code-level fact, not a rule.** The rules can only ask about files
beside the executable, and the Vulkan loader is not one of them (`vulkan-1.dll` lives in System32). So
@@ -200,11 +257,42 @@ Files shipped with a game tell us what it *supports*. These populate a **"Suppor
The UI wording is deliberate: **"Supports DLSS-G"** (capability, from files) versus **"Frame Generation: DLSS-G ×1.9"** (measured, from this session). Users conflating these is exactly the confusion the old design created.
### What the files say about themselves (beta.8, 2026-09-25, schema 0011)
The owner asked for the game's version, the DLSS / FSR versions and whether a game is 32- or 64-bit. The sweep read
most of it already and kept none of it; since beta.8 it keeps four more facts per game, written whole with each
detection (`DetectionWrite`, `games.exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`):
- **What the executable runs as** — `PeImports.ReadArchitecture`, from the same bounded header read as the imports:
the COFF machine and, for a .NET executable, the CLR header's flags (`Domain.Detection.ExecutableArchitecture`:
`x64 | x86 | arm64 | arm | anycpu | anycpu32 | other | unknown`). An "AnyCPU" assembly carries an I386 machine and
runs as a 64-bit process unless it prefers or requires 32-bit, which is why the machine alone is not the answer.
`x86`, `anycpu32`, `arm64` and `arm` are **known not hookable** — the hook is an x64 DLL loaded with `LoadLibraryW`
(CLAUDE.md rule 3) — so enabling hooking on one is refused before anything is scanned or stamped
(`Refused { reason: "ExecutableNotX64", signal: <id> }`, `07_IPC`), and a row enabled before this build read the file
has its hooking turned off by the sweep (`hook_autodisabled_reason` = `executable is x86: the hook runs in x64
processes only`). `unknown` and `other` are not: the guard's `TargetIsWow64` at a session's start stays the check.
A row whose `exe_machine` is NULL is stale once, so every library entry is read under this build.
- **The executable's own versions** — the PE `FileVersion` and `ProductVersion` strings. The file's word, kept apart
from `game_version`, which is the store's (a Steam build id, a GOG or Epic version string) or the user's. For an
Unreal title the file version is often the *engine's*; the page labels both and does not pick one.
- **What it ships, with versions** — every file a capability rule names among those the walk listed, with the
numeric version of its `VS_FIXEDFILEINFO` (the version *string* may carry text, and Streamline stamps `2,8,0,0`):
`nvngx_dlss.dll 3.7.10.0`, `sl.interposer.dll 2.8.0.0`, `ffx_fsr2_api_x64.dll …`. Bounded at 48 files. A file with
no version resource is listed with none — it is shipped either way. FSR is named by its file, never mapped to an
"FSR 2.2" number: the DLL's version is the SDK's, and no table of that mapping has been measured.
**Shipped is not loaded.** `library_versions` is what the game folder holds. What the process loaded is
`sessions.runtime_modules` (Tier 1), and the two differ exactly when something else supplied the DLL — the NVIDIA
App's DLSS override loads the driver's `nvngx_dlss.dll` from the driver store under the same name. 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:
@@ -220,7 +308,10 @@ Three things this section previously implied that are not true, and are worth st
> `DetectionHostedService` (`--serve` only) sweeps the library on its own task — every 15 s, and at once
> when `UpdateRules` re-seeds the rules file — through `Application.Detection.DetectionSweep`, which runs
> `StaticGameDetector` over the real `GameFileProbe` for every game whose key is stale and persists through
> `IGameRepository.ApplyDetectionAsync`. A game the App adds is scanned on the next tick (the App writes the
> `IGameRepository.ApplyDetectionAsync`. *A missing executable is asked one more question before it is skipped
> (2026-09-22): is the same file — same size, same mtime — under exactly one other drive letter? When it is, the row
> follows it (`ExecutableRelocator`, `19_SAFETY` §A moved drive is the same executable) and this very pass scans
> it there; `DetectionSweepReport.Relocated` counts them.* A game the App adds is scanned on the next tick (the App writes the
> row, the Agent reads the table); no Agent running means no scan, and the game page says "not scanned yet".
> *The key's exe half is NOT `exe_size_bytes` / `exe_mtime_ms`:* those are the consent fingerprint the gate
> reads (`SqliteGameConsentStore` refuses a mismatch while a block stands), so schema 0004 gave the key its own
+123 -6
View File
@@ -2,7 +2,7 @@
`%LOCALAPPDATA%\FrameLedger\ledger.db`. Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=5000`. `Microsoft.Data.Sqlite` + Dapper; all writes in explicit transactions.
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms` — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; never a `hook_*` column), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It 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. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; never a `hook_*` column), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
## Schema (v2 — hook architecture)
@@ -40,7 +40,9 @@ CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER
CREATE TABLE games (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
exe_path TEXT NOT NULL UNIQUE,
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,
@@ -53,7 +55,14 @@ CREATE TABLE games (
-- hooking state (19_SAFETY)
hook_enabled INTEGER NOT NULL DEFAULT 0, -- 0 = Tier 2, i.e. nothing measured; default for every new game
hook_consent_at INTEGER, -- per-game informed consent timestamp
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI.
-- 'Reason|Family|Signal' since 2026-09-25 (SqliteGameConsentStore.
-- BlockText), so the App can say it in the user's language; older
-- rows keep "Reason: Family Signal" and are shown as stored
hook_prescan_rules_version TEXT, -- schema 0010 (2026-09-25): the key the Agent's pre-scan of the
hook_prescan_exe_size_bytes INTEGER, -- library last scanned the row under — the rules version and the
hook_prescan_exe_mtime_ms INTEGER, -- executable's size and mtime; NULL = never scanned by the sweep.
-- Change executable clears them with hook_prescan_state
hook_autodisabled_reason TEXT, -- set after repeated crashes
hook_crash_count INTEGER NOT NULL DEFAULT 0,
capability_flags TEXT, -- JSON: what the game SHIPS — never a measurement. Since P4 PR-1 (2026-09-14) a JSON
@@ -67,6 +76,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
@@ -276,12 +293,22 @@ CREATE TABLE frame_blobs (
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
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
-- 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)
);
@@ -325,6 +352,8 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `ui.theme` | choice | `system` | `system` · `light` · `dark` | UI |
| `ui.start_with_windows` | bool | `0` | | UI (P4) |
| `ui.minimize_to_tray` | bool | `0` | | UI (PR-8) |
| `ui.hide_anticheat_hooking` | bool | `1` | | UI (beta.8, 2026-09-25): the game page of an entry the guard found anti-cheat in shows the finding in place of its Hooking card (`08_UI` §Game detail) |
| `ui.fps_decimals` | bool | `0` | | UI (beta.8, 2026-09-25): every FPS figure with two decimals ("62.40") instead of a whole number |
| `capture.background` | bool | `1` | | Agent |
| `hooking.kill_switch` | bool | `0` | | Agent (FR-2.4, since P2 PR-F) |
| `capture.min_session_s` | int | `30` | 5–600 | Agent, per session (FR-3.6) |
@@ -332,7 +361,7 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `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` | | UI (P4; CLAUDE.md rule 8) |
| `privacy.online_metadata` | bool | `0` | | *reserved* — no consumer and, since 2026-09-16, no toggle on Settings either: the store request it would enable has no code (CLAUDE.md rule 8), and PRIVACY_POLICY 2.2 removed the row that described it |
| `log.debug` | bool | `0` | | UI |
An operator's bounded capture (`--console … --seconds N`, which lowers the discard threshold to N) keeps
@@ -350,6 +379,9 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> record ON THE SAME SWAPCHAIN; the first record of a stream, and any record after a torn slot or an
> overwrite skip, carries 0 with the `frame_flags` gap bit set, so the statistics exclude it and the export
> still reconstructs `qpc_ms`. `swapchain_ids` is present only when the session held more than one stream.
> **Schema 0013 (beta.8)** adds `frame_blobs.first_present_ms`: the charts draw the dominant stream from its first present
> and the sensors from `qpc_epoch`, and nothing said how far apart the two zeros were. Gaps stay closed up on the frame
> axis (a gap's interval is stored as 0), so a series still drifts ahead of its sensors past each gap.
> Sensor series are aligned to `t_ms` (milliseconds from `qpc_epoch`) and a tick with no reading is stored as
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.s (NaN forbidden — assert).
@@ -380,6 +412,16 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> column computed from the prefix exactly as a live finalize would. **Rejected:** a `sessions_in_progress`
> table — a blob churn every minute, a lock fight with the UI in P3, and `04_CAPTURE` had already named a
> file under `tmp\`.
>
> **The header's `game_id` is where the session started, not necessarily where it lands (2026-09-23).** A live
> finalize and a recovery both ask `ISessionRepository.ResolveOwnerAsync`: that id when the row predates the session
> or holds the header's exe path; else the row that holds the exe path now (an entry removed and re-imported while
> the game ran); else nothing — `FinalizeStatus.GameRemoved` / `RecoveryStatus.GameRemoved`, file deleted, nothing
> written. `games.id` is `INTEGER PRIMARY KEY` without AUTOINCREMENT, so a deleted id can be handed to the next row
> added; `added_at` after the session's start and another path is how that row is told apart. A file recovery cannot
> finalize for any other reason is renamed `<guid>.partial.failed` (`IPartialSessionStore.Quarantine`) — not listed
> again, not retried, kept for a bug report — and recovery goes on to the next file: it runs before the watcher on
> every start, and one file used to be able to stop them all.
## Retention
@@ -422,11 +464,86 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
> which are the consent fingerprint the gate reads and which a background scan must never refresh.
> `LatestVersion` is 4; `LedgerDatabaseTests` asserts the columns.
> **`0005_fg_refusal_detail.sql` (2026-09-16) — `sessions.fg_refusal_detail`.** 0003 recorded WHICH refusal took the
> factor; the owner's Dashboard then showed "DLSS-G active — factor not counted" on four titles with a tooltip that
> could only say "the frame-generation state changed mid-session", while `FgWindow` had computed which of the eight
> buckets departed, its ratio and the window's, and `SessionAggregator` kept only the kind. The column is
> `Application.Recording.FgRefusalDetail` as JSON (`RecordingJsonContext`): kind, subject, count, bucket index/count,
> the bucket's ratio (null when it held no tokens — infinity is not JSON) and the window's. Written by the Agent
> beside `fg_refusal`, read by the UI's tooltip (`FpsPresentation.RefusalDetailText`), never an input to a number.
> Existing rows keep NULL. `LatestVersion` is 5; `LedgerDatabaseTests` asserts the column.
> **`0006_fg_steady_state.sql` (2026-09-17) — `sessions.fg_factor_scope` / `fg_steady_share`.** `fg_factor` was
> session-wide or NULL, and on real play it was almost always NULL (`03_METRICS` §The steady state). `session` = one
> state for the whole claimed span; `steady` = `fg_factor` / `native_fps` / `displayed_fps` describe the state the
> session spent most of its generating time in, `fg_steady_share` of the presenting time, with `fg_refusal` and its
> detail still set beside it. A reader that ignores the scope reads a steady factor as a session one, which is why
> every surface prints the share. Existing rows keep NULL. `LatestVersion` is 6.
> **`0007_guard_bypass.sql` (2026-09-21) and `0008_withdraw_guard_bypass.sql` (2026-09-22) — the first DROP.** 0007
> added five columns for the per-game guard override; the owner withdrew the feature a day later and 0008 drops them
> (`ALTER TABLE … DROP COLUMN`, SQLite ≥ 3.35 — `LedgerDatabaseTests` asserts the engine's version beside the columns'
> absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The
> data dropped is the override acknowledgements themselves, which is the decision. `LatestVersion` is 8.
> **`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`.
> **Every open used to migrate, and one that should not have did — 2026-09-16.** The Agent's `--console sessions`,
> a verb that prints, was run against the owner's ledger while the file on disk was at schema 2 and applied 0003 and
> 0004 to it. `LedgerDatabase.OpenReadOnlyAsync` exists since that day: an existing file, `PRAGMA query_only`, no
> `MigrationRunner`, and a refusal (`LedgerSchemaException`) for a schema **older** than the build as well as newer —
> the older file needs the App or `--serve` to bring it forward, not a verb whose name says it reads. The Agent's
> `sessions`, `consent list` and `killswitch status` open that way (`Program.PrintsOnly` is the list, pinned by
> `AgentReadOnlyVerbsTests`), `db path` opens nothing, and the App's `--diag` does the same.
>
> **What that run found, recorded because the mechanism is not known.** The on-disk `ledger.db` was 94 KB, 23 pages,
> dated 14 September, at schema 2 with three test games and no sessions; the day's 41 imported games and 18 sessions
> were in `ledger.db-wal` — 4 MB, 1006 frames — and every one of those frames carried salt-1 one **lower** than the
> WAL header's, with a checkpoint sequence of 1 and a single frame under the new salt. That is the shape SQLite leaves
> after a checkpoint has moved every frame into the main file and the next writer restarts the log; but no checkpoint
> had reached this main file (645 pages of data, 23 on disk, and the file's own time stamp two days old). A fresh
> connection therefore recovered one frame and saw the 14 September state, while the App and Agent that were running
> saw the whole day through the wal-index they shared. Neither process closed cleanly enough to fix it: the Agent's
> stop at 17:57 and the console's exit at 17:58 both left the WAL in place, and `-wal`/`-shm` then vanished between
> 18:00 and 18:04 with no FrameLedger process alive. The data was rebuilt by applying the old-salt chain to the main
> file (176 commits, `integrity_check` ok) and the broken set kept beside it. **Nothing in this repository writes the
> main file behind SQLite's back, replaces it, or restarts the WAL by hand**; what the code can do about an unknown
> mechanism is make the next occurrence visible, and it does: `OpenAsync` runs `wal_checkpoint(PASSIVE)` after
> migrating and logs the frame count it found and moved (`LedgerDatabase.OpenDiagnostics`), and `DisposeAsync` runs
> `wal_checkpoint(TRUNCATE)` and logs that, so a clean close leaves the main file complete and a WAL that will not
> checkpoint is a logged number rather than a silent one. A WAL at open holding frames a passive checkpoint cannot
> move, with no other FrameLedger process running, is the signature to look for.
> **Built 2026-09-09 (P2 PR-B):** `Infrastructure.Persistence.MigrationRunner` over scripts embedded in
> the assembly (so the schema a build applies is the one it was tested against), one transaction per
> script, under `Local\FrameLedger.Ledger.Migrate` — session-local rather than `Global\`, because the
> Agent and the UI share a session and the global namespace asks for a privilege a standard user need
> not hold. **A ledger at a version newer than the build's scripts is refused, not read**
> not hold. *(One name per ledger FILE since 2026-09-17 — `Migrate.<hash of the path>`,
> `MigrationRunner.LockNameFor`: with one name for every ledger, a test process frozen mid-migration held
> every other process's scratch ledger, and seven App and Agent tests failed after 30 s on #199's run.)* **A ledger at a version newer than the build's scripts is refused, not read**
> (`LedgerSchemaException`): guessing at a schema we do not understand is the one option that could
> turn a newer file into wrong answers. `LedgerDatabase` opens with the four pragmas above, one
> connection per process behind a gate, and every write in an explicit transaction — a failing blob
+45 -11
View File
@@ -291,7 +291,24 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
SDDL `D:P(A;;GA;;;<user SID>)(A;;GA;;;BA)` on the instance — `PipeAccessControl.Sddl`, what `20_OPEN_QUESTIONS`
§G asked for — and the token check by impersonation on the client's FIRST frame, because the kernel refuses
`ImpersonateNamedPipeClient` before the client has written; a stranger is disconnected without an answer and
counted. The client side uses `PipeOptions.CurrentUserOnly`, the mirror check on the server's owner.)*
counted. ~~The client side uses `PipeOptions.CurrentUserOnly`, the mirror check on the server's owner.~~)*
> **Amended 2026-09-17: the owner is stated, and the client compares it with its token USER.** The SDDL is now
> `O:<user SID>D:P(A;;GA;;;<user SID>)(A;;GA;;;BA)`. Left to default, a pipe's owner is its creator token's default
> owner, and an elevated token's is `BUILTIN\Administrators` — measured on the owner's machine that morning: the log
> files the elevated Agents created are owned by Administrators, the unelevated ones' by the user.
> `PipeOptions.CurrentUserOnly` compares the pipe's owner with the client token's default OWNER
> (`NamedPipeClientStream.ValidateRemotePipeUser` in dotnet/runtime), so an App started as administrator refused the
> user's own unelevated Agent, silently, as though none were there, and started another on every connect round
> (`01_ARCHITECTURE` §Lifecycle). The client connects without that option and calls
> `PipeAccessControl.RequireOwnedByCurrentUser` before it writes a byte; `PipeServerClientTests` pins the owner and
> drives both directions on a token that owns as Administrators (CI's elevated runner — an unelevated run skips it).
>
> **Accept failures back off.** An instance that cannot be created is retried 250 ms doubling to 10 s and logged on
> the first failure, on a change of error and at 10, 100, 1000… in a row, with the Win32 error. The three extra
> Agents of that morning logged the bare "accept failed" every 260 ms for four hours, 2 MB each. The error is read
> with `GetLastSystemError`: CsWin32 0.3.298 declares `CreateNamedPipeW` without `SetLastError`, so
> `GetLastPInvokeError` read 0.
- Framing: 4-byte LE length + UTF-8 JSON, max 1 MB. `System.Text.Json` source-generated contexts in `FrameLedger.Shared`.
*(Header and body go out in one write, so on the message-mode pipe one frame is one message; the reader
reassembles by length alone. Over the cap, or a stream ending inside a frame, is `IpcFramingException`.)*
@@ -307,22 +324,24 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
| Type | Dir | Payload / notes |
|---|---|---|
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. `vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered) and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` — and `activeSessions[]`, one `{ sessionGuid, gameId, gameName?, pid, tier, startedAt, hold? }` per running session. **`hold` added 2026-09-23, optional:** present on a session held unhooked (Tier 2), with the same words `SessionStarted.hold` carries; a session listed at tier 2 WITHOUT a `hold` has not attached yet — it is starting, not held. The App reads this list on every (re)connect (§Client behavior) |
| `SetWatchlist` | UI→A | `{ entries: [{ gameId?, exePath }] }` — ~~full replace~~ **ensure, never remove** (built 2026-09-13, PR-1b): each entry's path is normalised by the Agent, its row ensured with hooking OFF when new, and the ack is `WatchlistAck { games: [{ gameId, exePath, name }], unreadable: [exePath] }`; `gameId` in a request is a hint and never trusted over the path. UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary). *Since the App writes `games` rows itself under `06_DATA_MODEL` §Writer ownership (HANDOFF §P3 D15), this is the pipe's way of adding a row, not the only one; the watcher reads the table at 1 Hz either way.* |
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable`. *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* |
| `LaunchGame` | UI→A | `{ 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). |
| `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`.)* |
| `SweepRetention` | UI→A | **no payload** — a trigger, like `UpdateRules`: the Agent applies `06_DATA_MODEL` §Retention to every game with the `retention.raw_sessions_per_game` it reads itself → `SweepRetentionAck { keep, games, sessions }` (`keep` 0 = unlimited, and then nothing was swept). *(Built 2026-09-15, P4 PR-7, for Tools ▸ Database maintenance: `Application.Recording.RetentionSweep` over `ISessionRepository.SweepRetentionAllAsync`, composed into `AgentCommandHandler` under `--serve`. The client names no number because the rows are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the dialog reads as "restart the Agent". Carries no safety fact.)* |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt }` — **published at the attach**, i.e. when the session becomes Tier 1 and the live card has something to show; a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2) and, when a refusal or error caused that, the event below that names it |
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus? }` — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason` |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal? }` — **guard fired**; UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt, hold? }` — **published once per session**: at the attach (tier 1, `startedAt` the attach), or — **since 2026-09-23** — at the first tick of a session held unhooked (tier 2, `startedAt` the session's start, `pid` 0 when the loop never opened the process, as a hooking-off hold never does). ~~a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2)~~ — that was the beta.5 wire, and every hooking-off, refused or unreadable game read "Nothing is being captured." for as long as it ran. **`hold` (optional, tier 2 only)** is why nothing is measured: `{ reason, guardReason?, family?, signal?, hookingTurnedOff }` — the loop's `SessionEndReason` and, when the guard said anything but allow, its reason, family and signal: the same words the row's `capture_notes` will carry, so the live card and the summary read one sentence (`Formats.Tier2HoldReason` / `Tier2Reason`). The refusal's own event (`CaptureRefused` and the rest, below) goes out with this start rather than when the game exits, and is not repeated at the end |
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct? }` — how long it has run and the machine's sensors. **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus? }` — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal? }` — anti-cheat appeared mid-session; prominent UI notice. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
| `CaptureError` | A→UI | `{ sessionGuid?, code, message }` — `InjectFailed`, `RingVersionMismatch`, `AttachRefused`, ~~`EtwAccessDenied`~~ (struck 2026-09-13 with the tier), ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed`, `SessionFaulted` (the session's task threw before finalize; the `.partial` stays for recovery, and no `SessionCompleted` follows). *(Built: `RingVersionMismatch` for a layout / record-size / build-id refusal — the "restart the game after an update" case — `AttachRefused` for the rest of the ring's refusals, `InjectFailed` for a target that could not be started, pinned, read or singled out.)* |
| `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
@@ -363,10 +382,25 @@ message, and that message always re-scans.
## Client behavior (UI)
- **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.
> **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.
- 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
+194 -4
View File
@@ -55,6 +55,7 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
> 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`,
@@ -92,7 +93,12 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
> 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. `CaptureError` (non-fatal) goes to the 4 s strip. The safety
> 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).
@@ -105,6 +111,14 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
> `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):
@@ -113,7 +127,8 @@ 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".
- **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"; 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.
- **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).
@@ -140,6 +155,19 @@ All screens are `Page`s registered with the navigation page provider and navigat
> 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.
>
> **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.
@@ -158,7 +186,10 @@ All screens are `Page`s registered with the navigation page provider and navigat
> 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), **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
> 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
@@ -168,6 +199,44 @@ All screens are `Page`s registered with the navigation page provider and navigat
> 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`.
>
> **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.
2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
@@ -188,6 +257,33 @@ All screens are `Page`s registered with the navigation page provider and navigat
> per-present `vram_proc` (a held 1 Hz sample) and the adapter-wide `vram_adapter` sensor as two
> differently-labelled series. **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.
@@ -207,6 +303,41 @@ Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutte
> 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, 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 `#`
@@ -215,6 +346,32 @@ Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutte
> 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.
@@ -247,6 +404,8 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
### Settings
Sections per FR-10 using the WPF UI settings idiom: `ui:CardControl`/`ui:CardExpander` rows with `ToggleSwitch`, `ComboBox`, `ui:NumberBox` (numeric inputs — min session length, sensor interval, retention). Language switch applies immediately (09_I18N). Theme selector (Light/Dark/System) drives `ApplicationThemeManager` (16 §Theming). **Capture section (top, most important):** the global **hooking kill switch** (`ToggleSwitch`, prominent) with a one-line summary of what it does; a list of games currently hook-enabled with a per-game revoke; Vulkan layer registration state + Register/Unregister; a link to the safety documentation. Turning the global switch off must take effect immediately, including for the Vulkan layer.
**System (2026-09-21, FR "show the user's hardware"):** a card above Legal stating this PC as a session's hardware snapshot would record it right now — processor, graphics card, graphics driver, memory, Windows build, primary display — through the same `IHardwareSnapshotSource` the Agent stamps sessions with, read on the thread pool when the page opens, a field that could not be read as N/A, with **Copy** (the same lines as text) and a note that nothing is sent anywhere and what CPU temperature needs. Its own `SystemInfoViewModel`, not `SettingsViewModel`'s. The same snapshot is one tertiary line under the session summary's header (it was loaded for the export and shown nowhere), and `--diag` prints it; the bug bundle's `sysinfo.json` is deliberately NOT given it — its keys are the issue link's prefill.
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", background capture toggle. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
> **Built 2026-09-14 (P3 PR-8a), with three rows deferred to PR-8b and one to PR-9.** `SettingsViewModel` over
@@ -269,7 +428,7 @@ Agent section: elevation state with a plain explanation of what elevation *optio
> 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.
> 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
@@ -286,6 +445,10 @@ Agent section: elevation state with a plain explanation of what elevation *optio
> 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.
### First-run flow
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept.
@@ -367,6 +530,33 @@ meet it — and cannot be broken locally: `AccessibilityTests.NoXamlHardCodesACo
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`).
+7
View File
@@ -2,6 +2,13 @@
Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as the rest of the poli0981 portfolio.
> **Both string families are given the UI culture explicitly (2026-09-21).** `App.ApplyCulture` sets `Strings.Culture`
> AND `FrameLedger.Shared.Strings.Culture`. The second was missing: the safety family fell back to the thread's
> `CurrentUICulture`, and a culture set inside the App's async start flows with that async context, not to the
> dispatcher's later operations — so on an English Windows a Vietnamese UI showed the consent dialog, the refusal
> notices in English (and, for one day, a guard-override card). A resource accessor that depends on which thread asks is the defect;
> `StringsTests.ApplyingTheUiLanguageSetsTheSafetyFamilyToo` holds it with the thread deliberately left English.
## Mechanics
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` for error codes). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
+52 -9
View File
@@ -6,7 +6,7 @@
- Minimum level `Information` (`Debug` toggle in Settings → applies live via `LoggingLevelSwitch`).
- Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).
- Template: `[{Timestamp:HH:mm:ss.fff} {Level:u3}] {SourceContext} {Message:lj} {Properties:j}{NewLine}{Exception}`.
- **Never log:** full user paths outside `%LOCALAPPDATA%\FrameLedger` (redact to `<user>`), machine name, any exe arguments of games. A `RedactingEnricher` enforces the path rule.
- **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,6 +15,17 @@
- On fatal: Serilog `Fatal` with full exception → write minidump via `MiniDumpWriteDump` (CsWin32, `MiniDumpWithIndirectlyReferencedMemory | WithThreadInfo`) to `crashdumps/` (keep last 5) → UI shows crash dialog offering the bug-report flow → exit code 1.
- Agent crash mid-session → `.partial` recovery path (04_CAPTURE) on next start finalizes an `interrupted` session.
> **Written by a child process since 2026-09-17.** `MiniDumpWriteDump` on the calling process suspends every other
> thread of it, and a suspended thread holding the process heap or loader lock deadlocks the dumper — Microsoft's
> documentation says to dump "from a separate process if at all possible". The in-process writer below froze the
> Infrastructure test suite one run in eight, and a crashing App or Agent is the unstable process the warning is about.
> `CrashDumpWriter.TryWrite` now starts `FrameLedger.Agent.exe --write-crash-dump <file>` (the Agent beside the App;
> the Agent's own binary for the Agent) and waits up to 30 s; the helper (`ParentDump`) dumps **its parent** with the
> same two flags, and nothing else: it takes no pid, and refuses unless the parent is still running, started before it,
> and has its image in the helper's own directory — the App or the Agent, never a game (CLAUDE.md rule 4). A missing,
> failed or slow helper is a null path and one Warning line, as before. The runtime's `createdump.exe` would have done
> the job, but a self-contained install does not ship it (measured on 0.1.0-beta.1).
>
> **Built 2026-09-15 (P4 PR-9).** `Infrastructure/Diagnostics/CrashDumpWriter` writes
> `crashdumps\<ui|agent>-<yyyyMMdd-HHmmss, UTC>-<pid>.dmp` through CsWin32's `MiniDumpWriteDump` with exactly the two
> flags above, keeps the five newest `*.dmp` of either process after each write, and never throws: a failure is a null
@@ -33,7 +44,10 @@
> `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.
> 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
@@ -67,8 +81,9 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
> **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; `overlay/` = the five newest
> 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
@@ -90,7 +105,20 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
> 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; the session-metadata checkbox is open.
> 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
@@ -100,10 +128,21 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
> 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. 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`.
> 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=…`
@@ -116,6 +155,10 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
- **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
+5 -2
View File
@@ -58,10 +58,13 @@ flow, and the tests run the flow over a fake client because nothing here may tou
- **FR-12 is the shape of the flow, not a check at the end.** A downloaded package is `Ready` only while the Agent
reports no session (its `StatusAck` at connect, then `SessionStarted` / `SessionCompleted` on the pipe);
otherwise it is `Deferred`, the button is disabled and the body says why, and it becomes `Ready` when the last
session ends. The apply is refused again inside if a session started meanwhile. A recording-only (Tier 2)
session ends. The apply is refused again inside if a session started meanwhile. ~~A recording-only (Tier 2)
session that began before the App connected is covered by the status; one that begins afterwards raises no
`SessionStarted` (that event is the ring's) and is not — a known gap, recorded rather than hidden: the Overlay
is not on disk under such a session, so the rule's reason does not apply to it.
is not on disk under such a session, so the rule's reason does not apply to it.~~ **Closed 2026-09-23:** a held
(Tier 2) session raises its own `SessionStarted`, so it defers an update like any other; and the status read at
connect SEEDS the running set rather than being OR-ed with it forever — before, a session running when the App
connected held every download at `Deferred` until the next reconnect, hours after it ended.
- **Apply:** `Shutdown` to the Agent over the pipe, the connection's relaunch held (`IAgentLink.SetLaunchHold`),
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so),
then `WaitExitThenApplyUpdates(asset, silent: false, restart: true)` and the host ends. The restarted App
+13 -2
View File
@@ -88,7 +88,7 @@ Launch profiles:
Native debugging notes: use **`hook-harness`, never a real game**, for step-through debugging — a breakpoint inside a present hook of a real game freezes it in ways anti-cheat and drivers both dislike. Enable the Vulkan validation layers when touching `FrameLedger.VkLayer`. Application Verifier + PageHeap on the harness catches ring-buffer bugs early.
Agent flags: `--serve`, `--console`, ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
Agent flags: `--serve`, `--console`, `--write-crash-dump <file>` (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — `10_LOGGING` §Crash handling), ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
> **Built 2026-09-10 (P2 PR-F): `--serve` and `--console`; the other five answer "not implemented in P2"
> with exit 2** rather than being silently accepted (`--diag` is the App's anyway, `10_LOGGING`). The console
@@ -100,6 +100,17 @@ Agent flags: `--serve`, `--console`, ~~`--diag`~~ (the App's — `FrameLedger.ex
> shipped `FrameLedger.Agent.exe` against `hook-harness` with a scratch `--data-dir` and reads the one
> `sessions` row back — the milestone's technical half, in the merge gate.
> **The print verbs open the ledger read-only (2026-09-16).** `sessions`, `consent list` and `killswitch status`
> migrate nothing and refuse — exit 7, the reason on stderr — a ledger at a schema older or newer than the build;
> `db path` opens no file at all. Until then every verb went through the migrating open, and `sessions` run against
> the owner's ledger applied two scripts to it (`06_DATA_MODEL` §Migrations). `AgentReadOnlyVerbsTests` pins the set.
> **One capturing process per data folder (2026-09-17).** `--serve`, `capture`, `launch` and `recover` claim the data
> folder (`AgentInstanceLock`) before logging, rules or the ledger, and exit **10** — one line on stderr, nothing
> written — when another process holds it; the other verbs run beside a serving Agent, as the App's `--install-task`
> does. `OneAgentPerDataFolderTests` runs the shipped binary against a claimed scratch folder
> (`01_ARCHITECTURE` §Lifecycle).
## Bundled assets
- ~~`assets/native/PresentMon.exe` (pinned, SHA-256 verified at build) for the Tier-2 fallback~~ — **DROPPED 2026-08-27, and there are no bundled native assets at all.** §S31 measured PresentMon classifying every frame of a ×4 capture as an application frame (row P2); the owner then dropped it outright. It is not bundled, not fetched, not used, and `tools/frametype-oracle.ps1` — the parser that consumed its output — is deleted with it. `assets/` does not exist and now has no reason to. **And since 2026-08-28 Tier 2 is not a measurement at all**: the ladder is two rungs, `EtwFrameSource` is deleted from the design, and whether a shipped build ever regains a no-injection measurement is `20_OPEN_QUESTIONS` §G.
@@ -203,7 +214,7 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
> prevent.
- No trimming (WPF + reflection), no NativeAOT (WPF unsupported), **no obfuscation** (GPLv3 policy, and `19_SAFETY` forbids making our binaries harder to identify).
- `SatelliteResourceLanguages=en;vi;ja`. ~~Expected package ≈ 95–130 MB self-contained.~~ **Measured 2026-09-14 (P4 PR-5): the published tree is 250 MB in 362 files** (App + Agent, self-contained, ReadyToRun roughly doubles the IL). `vpk pack` 1.2.0 over that tree, run by hand the same day with the workflow's arguments: `FrameLedger.App-win-Setup.exe` **104 MB**, the full `.nupkg` and the portable zip 100 MB each, plus `releases.win.json` / `RELEASES` / `assets.win.json`; vpk's own pre-process step verified `VelopackApp.Run()` in `FrameLedger.App.Program::Main()`.
- `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
+68 -8
View File
@@ -26,6 +26,32 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
wrong by the end of the same evening; it is corrected rather than quietly deleted, because a frequency
claim made from one observation is exactly the shape this file keeps catching.
**Re-run before investigating**; if it reproduces, read the module list and the scan-set reason, not the test.
- **A hang, not a refusal — the first tag run (2026-09-16, run 35111939019).** Every suite green except
`Infrastructure.Tests`, which printed its "test run for …" line and nothing else for 58 minutes until the job's
60-minute limit cancelled the run; the same suite took 42 s in the rehearsal an hour earlier. The log named no
test. ~~`build.ps1` now passes `--blame-hang --blame-hang-timeout 15m --blame-hang-dump-type mini` to `dotnet test`,
so the next hang fails the run in 15 minutes with the test's name in `TestResults\…\Sequence.xml` and a mini
dump beside it — the diagnostic this run lacked. Which test hung is **unmeasured**; the re-run is the measurement.~~
**Found and fixed 2026-09-17.** Reproduced locally one run in eight; the xUnit verbose reporter of a hung run showed
thirteen tests started and none finished, one of them `CrashDumpWriterTests.WritesAMinidumpOfThisProcess…` — which
called `MiniDumpWriteDump` on its OWN process. That call suspends every other thread of the caller, and one holding
the heap or loader lock deadlocks the dumper: the whole test process froze, including xUnit's long-running-test
timer, which is why nothing was ever named. 40 runs without that test: no hang. **The same call was the product's
crash path**, in the App and the Agent — a real crash could have hung instead of dumping. Dumps are written by a
child process now (`Infrastructure.Diagnostics.ParentDump`, `FrameLedger.Agent.exe --write-crash-dump`; `10_LOGGING`
§Crash handling). And **`--blame-hang` did not stop the hung xUnit v3 executable** — still alive four minutes after
a 60 s hang timeout — so `build.ps1` runs `dotnet test` under a 25-minute wall-clock limit instead, kills the tree on
expiry, and names the test projects that wrote no `results.trx`. *(Measured on xUnit v3 3.2.2. The suites moved to
4.0.1 on 2026-09-21 as `xunit.v3.mtp-off`, still under VSTest; whether `--blame-hang` stops a hung 4.x executable is
unmeasured, and the wall clock stays either way.)*
- **Two more shapes had one cause, found and fixed 2026-09-16** after four failures in one evening's merge train:
`AKilledHostLeavesAPartialThatRecoverTurnsIntoAnInterruptedSession` ("the process cannot access the file …
`.partial`") and `WithNoConsentRecordTheHostRefusesAndNothingIsEverInjected` (a leftover consent record). The
suite's `Kill` helper returned before the killed host had released its files, so the next line read a `.partial`
the dead process still held, and the ledger delete in `Dispose` silently failed and left the record for the next
case. `Kill` now waits for exit (bounded, asserted) and the delete retries. Not §S19(b) either — a test-harness
race, and the third flake shape of the day (the registry-subtree race between `VkLayerRegistrationTests` and the
GOG reader's test, fixed in #188) was the same kind.
- **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
@@ -69,11 +95,31 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
### `release.yml` — on tag `v*` · **repo-local, built 2026-09-14 (P4 PR-5)**
> **Exercised by a tag on 2026-09-16 — `v0.1.0-beta.1`, run 35111939019 — and the first attempt did not finish.**
> The version gate, the substitution and the quality gate ran; the quality gate then sat in `Infrastructure.Tests` for
> 58 minutes (every other suite green; the same suite 42 s in the rehearsal an hour before) until the job's 60-minute
> limit cancelled it, with no test named. `gh run rerun --failed` on the same tag: the gate in 11 minutes
> (Infrastructure 305 in 17 s), publish (252 MB tree), licences, the tree assertion, `vpk pack` (`Setup.exe` 110 MB,
> portable zip and full nupkg 105 MB), `SHA256SUMS.txt`, and the pre-release created with the section's notes and the
> checksums appended — <https://github.com/poli0981/frameledger/releases/tag/v0.1.0-beta.1>. Two things the tag taught:
> a tag run can be re-run in place after a flake (the Release step is idempotent up to the release existing — it did
> not, so nothing had to be deleted), and a hang eats the whole job budget silently, which is why #196 added
> `--blame-hang` to the gate. The paragraph below is the history as it stood.
>
> This heading said **PLANNED, NOT PRESENT** from 2026-08-06 until the workflow existed, with the note that
> "nothing in this repository has ever run `dotnet publish`". Still true of the *repository's history*: the
> workflow has not been exercised by a tag yet — its publish, tree assertion and `vpk pack` steps were run by hand on
> "nothing in this repository has ever run `dotnet publish`". ~~Still true of the *repository's history*: the
> workflow has not been exercised by a tag yet~~ (struck 2026-09-16, above) — its publish, tree assertion and `vpk pack` steps were run by hand on
> 2026-09-14 (`12_BUILD` §Publish & package has the sizes), the release upload was not. The first tag is the rest of the measurement; until then every other claim below is
> what the file says, not what a run showed.
>
> **A dry run exists since 2026-09-16 (P5 prep).** `workflow_dispatch` with a `version` input runs the identical
> job — gate, publish, runtime licences, tree assertion, `vpk pack`, checksums, the artifact upload — and skips only
> `gh release create`; no tag is made. Two things differ from a tag run, both deliberate: the version comes from the
> input (its numeric core must still equal `VERSION`), and a missing `## [x.y.z]` section is a printed warning with
> placeholder notes rather than a stop, because that section is written in the tag commit and a rehearsal precedes
> it. The artifact is `release-<version>-dry-run`. Run it with `gh workflow run release.yml -f version=0.1.0-beta.1`
> (on the branch that carries the file, `--ref <branch>`); the result is what the first tag will do, minus the
> upload. The rehearsal's outcome is recorded in `CHANGELOG.md` when it has run.
- `runs-on: windows-latest`, the same .NET / MSVC / clang-format pins as `ci.yml`, `permissions: contents: write`
(the Release API) and nothing else.
@@ -152,10 +198,24 @@ Central package management makes Dependabot PRs single-file diffs.
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
- 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):**
- [ ] Branch protection as §Branch & release policy states; `Rules / validate` as a required check (§S23-2, after its skip-shim)
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
- [ ] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
+6 -5
View File
@@ -1,19 +1,20 @@
# 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 native suites on every gate (`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. **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)
@@ -130,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* |
## Release smoke
+4 -4
View File
@@ -249,8 +249,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
@@ -311,7 +311,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> re-scan wired to a real Overlay.
## P2 — Capture pipeline (1 week)
Agent: watcher, tier selection, injection orchestration, shm drain, telemetry poller (NVAPI first), session recorder, segments, `.partial` recovery, ~~Tier-2 `EtwFrameSource` retained as fallback.~~ **There is nothing to retain: Tier 2 has no mechanism as of 2026-08-27** (§G). `EtwFrameSource` is a port with no adapter, and P2 should not be planned as though writing one were scoped. SQLite v2 schema + migrations. Domain metric calculators + golden tests. **Milestone: first real hooked session persisted with measured upscaler/RT data.** *Technical half reached 2026-09-10 (P2 PR-F): the shipped `FrameLedger.Agent.exe --console capture` against `hook-harness` ends as one hooked `sessions` row, in the merge gate (`AgentEndToEndTests`). **P2's code is complete as of PR-G (2026-09-10)** — kill-and-recover is in the gate too (`PartialRecoveryEndToEndTests`) and `tools/fps-impact-runbook.ps1` exists. What P2 still owes is two MEASUREMENTS, not code: the real-title milestone read against the game's own menus, and the ≤ 0.5 % FPS-impact run. Both are the owner's; `spike-notes` §14 holds their slots and the exact commands.*
Agent: watcher, tier selection, injection orchestration, shm drain, telemetry poller (NVAPI first), session recorder, segments, `.partial` recovery, ~~Tier-2 `EtwFrameSource` retained as fallback.~~ **There is nothing to retain: Tier 2 has no mechanism as of 2026-08-27** (§G). `EtwFrameSource` is a port with no adapter, and P2 should not be planned as though writing one were scoped. SQLite v2 schema + migrations. Domain metric calculators + golden tests. **Milestone: first real hooked session persisted with measured upscaler/RT data.** *Technical half reached 2026-09-10 (P2 PR-F): the shipped `FrameLedger.Agent.exe --console capture` against `hook-harness` ends as one hooked `sessions` row, in the merge gate (`AgentEndToEndTests`). **P2's code is complete as of PR-G (2026-09-10)** — kill-and-recover is in the gate too (`PartialRecoveryEndToEndTests`) and `tools/fps-impact-runbook.ps1` exists. What P2 still owes is two MEASUREMENTS, not code: the real-title milestone read against the game's own menus, and the ≤ 0.5 % FPS-impact run. Both are the owner's; `spike-notes` §14 holds their slots and the exact commands. **The milestone's row half exists as of 2026-09-16** — the shipped Agent's Lies of P session with `fsr3`, 1506×848 → 2560×1440, FG ×2.04 and `rt = no` (`spike-notes` §14.1); the menu column is still the owner's, as is the FPS-impact run.*
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; the owner's merges of the stack are the remaining act)**
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). *Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*
@@ -320,7 +320,7 @@ WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashbo
~~Static rules engine + `detection-rules.json` (engines, platforms, capabilities, **anticheat blocklist**) + validator + fixtures~~ **landed 2026-09-14 (P4 PR-1: the engine existed since P0; the Agent's `DetectionSweep` is its first caller, `ApplyDetectionAsync` its first writer — HANDOFF §P4)**; ~~store auto-import~~ **landed 2026-09-14 (P4 PR-4)**; ~~capability-vs-measured UI separation~~ **(PR-1: the Supports row reads the sweep's flags)**; ~~i18n en/vi/ja; Legal Gate;~~ ~~Velopack + updater (with the hooked-session deferral)~~ **landed 2026-09-14 (P4 PR-5 — the deferral is `UpdateService`'s shape, not a flag)**; ~~bug bundle incl. overlay logs~~ **landed (overlay logs since P3 PR-8a; 2026-09-15, P4 PR-9: the crash dialog, the minidump in both processes and the dump as the bundle's opt-in — `10_LOGGING` built notes)**; ~~tray + toasts; Settings;~~ ~~DB maintenance~~ **landed 2026-09-15 (P4 PR-7: the sweep is the Agent's over `SweepRetention`; integrity, backup and compaction in the App)**; ~~accessibility pass~~ **landed 2026-09-15 (P4 PR-8: `08_UI` §Accessibility written first — Ctrl+1…5, Esc on every dialog, an automation name on every textless input, theme colours only — each held by `AccessibilityTests`)**; ~~the scheduled task (`--install-task`)~~ (P3 PR-8b) and ~~the Velopack install hooks~~ **(PR-5: the uninstall hook; install registers nothing, by design — `12_BUILD` §The Vulkan layer is not registered at install time)**. *(The struck items moved to P3 on 2026-09-13 — see §P3.)*
## P5 — Ship (3–4 days)
CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 — untested by a tag yet); 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** (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.
+8 -1
View File
@@ -6,7 +6,7 @@ Mandatory conventions for all XAML/C# in `FrameLedger.App`. WPF UI = lepoco's Fl
| Package (NuGet id) | Pin | Notes |
|---|---|---|
| `WPF-UI` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net10.0-windows10.0.19041.0` TFM (`12_BUILD` §Managed build) |
| `WPF-UI` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net10.0-windows10.0.22621.0` TFM (`12_BUILD` §Managed build; this row said `19041` until 2026-09-21, which is no TFM this repository ever built — `Directory.Build.props` has been `22621` with a 19045 floor throughout) |
| `WPF-UI.Abstractions` | transitive | Navigation abstractions (`INavigationViewPageProvider`) |
| `WPF-UI.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) |
@@ -144,6 +144,13 @@ 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.
+1 -1
View File
@@ -133,7 +133,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`, `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
+39 -1
View File
@@ -112,6 +112,21 @@ L1 gives no temperatures on its own (unless the D3DKMT probe pans out). That is
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 — 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. `HelloAck.cpuTempAvailable` reports those same two conditions (it was a constant
> `false`). A tick only the machine answered is still queued, under a placeholder `GpuSample` with
> `TelemetryLayer.None` and no field. The `.partial` sensor chunk carries the three values in bits 12–14 of the
> existing 16-bit presence mask, so an older file reads back with an empty reading.
## L3 — NVAPI (MIT, NVIDIA only)
**Integration: vendored headers + import library, linked normally. ✅ Vendored 2026-08-05** at `src/native/third_party/nvapi/` — nine headers (`nvapi.h`'s include closure plus `nvapi_interface.h`), `License.txt`, and `amd64/nvapi64.lib`; **x64 only**, `x86/nvapi.lib` deliberately not taken. Consumed through the `fl_nvapi` INTERFACE target. NVIDIA publishes the NVAPI SDK — headers, interface definitions, and `nvapi64.lib` — under the **MIT licence** (verified 2026-08-02 and re-verified on the vendored copy: `amd64/nvapi64.lib` is a tracked file in the MIT repo and `License.txt` names the import libraries as the subject of the grant, so the binary is covered and not only the headers), so the SDK material can live in our GPL-3.0 repository with only the usual MIT attribution obligation. The runtime implementation lives in `nvapi64.dll`, which ships with the installed NVIDIA driver.
@@ -146,6 +161,29 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
> **Not in this build, stated so nobody infers it from the table below:** VRAM (`FlNvSample.vram` is
> reserved and its bit is never set — see the Memory row), power, hotspot temperature, per-domain
> utilisation beyond the GPU domain, and anything Reflex (§M8: a hook fact, not a poller field).
>
> **ABI 2 (2026-09-25, beta.8): the driver profile, read-only.** The owner asked whether the NVIDIA App overrides a
> game's DLSS (frame generation, ray reconstruction, the model preset). The NVIDIA App writes those overrides into the
> driver's own settings store (DRS), so `FlNvDriverProfile(exePath, ids, count, out)` reads them there: a DRS session
> is created, the settings loaded, the profile the driver applies to that path found (`NvAPI_DRS_FindApplicationByName`
> — a fully qualified path returns the profile the driver will apply on launch; none named → the current global
> profile), each id read with `NvAPI_DRS_GetSetting` (value, where it comes from, whether someone set it), and the
> session destroyed. **No DRS setter exists in the bridge** — not `SetSetting`, not `SaveSettings`, not
> `RestoreProfileDefault`, not `NvAPI_NGX_SetNGXOverrideState`: the overrides are the user's, and this only reports
> them. A path longer than NVAPI's string is refused, never truncated (a truncated path names another program).
> The ids and their values' meanings are NVIDIA's `NvApiDriverSettings.h` (github.com/NVIDIA/nvapi, MIT), written into
> `Application.Capture.NvidiaDriverSettings` as eighteen constants rather than vendored as a header; Smooth Motion
> (`0xB0D384C0`) is not in NVIDIA's header and is documented by community profile tools only, which every surface
> that shows it says. Managed: `NvapiDriverProfileSource` (`IDriverProfileSource`) — the Agent's recorder reads the
> profile beside every session, both tiers, and stores it in `sessions.driver_profile` (schema 0012). Verified by
> ctest `fl_nvapi_bridge` (argument refusals, DEGRADED before init, the global profile of the test's own executable on
> a GPU machine) and `NvapiBridgeMirrorTests` (`FlNvDriverProfileSize`, ABI 2).
>
> **The ctest could not fail on a GPU machine until the same day.** `fl_nvapi_bridge` was registered with
> `PASS_REGULAR_EXPRESSION` alone, which makes ctest ignore the exit code: the AVAILABLE branch's reference-counting
> check (two references, two releases, then a read expected to work) failed on every machine with an NVIDIA GPU while
> ctest reported Passed, and CI — no driver — never takes that branch. The check is corrected and the registration now
> carries a `FAIL_REGULAR_EXPRESSION` on Catch2's failure lines.
| Purpose | Function |
|---|---|
@@ -267,7 +305,7 @@ on the NVIDIA dev box even though nothing in it may be hooked or declared.
- Poll at 1 Hz on a dedicated Agent thread. Never from the game process, never from the Overlay.
- Any layer that throws or hangs twice is disabled for the session and its fields report `N/A`, rather than being retried in a loop.
- **Read-only, always.** These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile.
- **Read-only, always.** These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile. *(Since beta.8 the same holds for the driver's settings store: the bridge reads DRS profiles and has no entry point that writes, saves or restores one — §L3, ABI 2.)*
## Capability matrix (fill during P0 on real hardware)
+268 -28
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.)*
- Reading or writing game memory outside the arguments of APIs we hooked
- Kernel drivers of our own
@@ -220,6 +220,35 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> 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).
> **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:** 30 Steam app ids and 33 executable names across nine 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).
> 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.
> 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
> module scan and the pre-scan, and an unresolvable identity refuses with
@@ -250,6 +279,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
@@ -348,7 +394,78 @@ 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.
### 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.
**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 floor data cannot remove
@@ -422,32 +539,107 @@ 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 |
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); VAC's stays until its per-title route exists.
> **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`
@@ -668,7 +860,55 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
> publishing `unhookRequested`, and keeps the Vulkan layer off by never setting `FRAMELEDGER_ENABLE_VK_LAYER`
> on a launch.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection).
### 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
@@ -697,7 +937,7 @@ rules feed can switch injection on for a game without anyone looking.
## 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.
+40 -7
View File
@@ -23,6 +23,24 @@ 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.
| # | 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 |
@@ -76,7 +94,7 @@ or it becomes the next stale status claim this file exists to record.
| **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; store-id half deferred to P4, rationale written 2026-09-06** | The store-id half's only in-policy route is P4's platform metadata extractors feeding a guard-side resolver; a resolver with no extractor would refuse every title. No title is blocked by store id today because none is listed |
| **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. 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** | ✅ **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 |
@@ -153,6 +171,10 @@ the recount becomes the next thing that needs recounting.
> 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
@@ -1619,7 +1641,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?
@@ -2620,8 +2644,9 @@ disproved:
> **🅓 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). Until then a
> 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
@@ -3139,7 +3164,14 @@ gate.
> 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`
@@ -4259,6 +4291,7 @@ instead, which needs no thread at all.
| M7 ✅ | ~~`18_GPU_VENDOR_APIS` §Runtime policy says telemetry is never read from the game process, but `17_HOOK_ENGINE` reads per-process VRAM and Reflex latency there. Reconcile the wording — the rule means "no vendor SDK polling loops in the game", not "no measurement in the game"~~ **Closed 2026-09-09 (PR-E1) by the code taking exactly that shape.** The rule is *no telemetry polling loop in the game*: the one 1 Hz loop is `TelemetryPoller` on the Agent's `fl-telemetry` thread, and it reads L1/L2/L3 only. Per-process VRAM stays an in-process read on the present path (`vram_proc`, `17_HOOK_ENGINE`), and PR-E1 measured why that must be so: `IDXGIAdapter3::QueryVideoMemoryInfo`'s `CurrentUsage` is the *calling process's* figure — 0 bytes from the Agent — so it is a measurement only where the game is. Adapter-wide usage is L1's PDH counter. §Runtime policy's sentence stands as written; this row is the reconciliation |
| M8 ✅ | ~~The `GpuSample` type has no latency field, yet L3 is credited with Reflex/PC latency. Latency is per-frame and arrives via the ring, not the 1 Hz sample. Fix the layering description~~ **Closed 2026-09-09 (PR-E1): the description now matches the type.** `GpuSample` has no latency field by design (its own remarks said so since 2026-09-03), `TelemetrySample` carries a 1 Hz reading stamped with QPC, and per-frame latency is `FlFrameRecord.reflexLatencyUs` in the ring. The §L3 table row "Reflex / PC latency" is an *in-process hook fact* the Overlay records (`SetSleepMode` / `SetLatencyMarker`, `17_HOOK_ENGINE`), never a poller field; `NvapiTelemetrySource` (PR-E2) will not call `NvAPI_D3D_GetLatency` |
| M9 ✅ | **Closed 2026-08-02 by a decision.** The old file/module detection does not exist in this repository and the owner confirmed there is no copy elsewhere, so **"build a minimal static-hint detector as the measurement baseline" is now P0 item 3** (`15_ROADMAP`). It needs no guard and no injection. Until it exists, ADR-7's headline claim stays out of the README rather than being asserted unmeasured |
| M10 ❓ | **§CPU — is the CPU temperature this build reads the right sensor, and does it read at all on the owner's machine?** `LhmCpuTemperatureReader` (2026-09-21) opens a CPU-only LibreHardwareMonitor `Computer` when the Agent is elevated AND `PawnIo.IsInstalled`, takes the package sensor (`CPU Package` / `Core (Tctl/Tdie)`) and falls back to the hottest core. It was written against LHM's sensor names and a fake `ILhmComputer`; **no elevated run with PawnIO has been taken.** | **The measurement is one session:** Agent elevated, PawnIO installed, a five-minute capture with HWiNFO or Ryzen Master open beside it. Pre-committed: `max_cpu_temp` within 3 °C of the reference's package peak → keep; a core sensor picked where a package sensor exists, or a reading tens of degrees off (a distance-to-TjMax sensor mistaken for a temperature) → fix `Pick` and re-run; nothing read at all → `cpu_temp` stays N/A and `legal/ACCURACY.md` says processor temperature is not measured. CPU **load** and memory are not in question: `TheRealCountersAnswerOnThisMachine` reads them on every gate run. |
| 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
@@ -4305,12 +4338,12 @@ Each of these is referenced by an existing doc but specified nowhere.
| Area | What is missing | Referenced by |
|---|---|---|
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
| **Session identity** | ~~`sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`.~~ **`sessions.session_guid` (UNIQUE) exists since 2026-09-09 (P2 PR-B), with `qpc_epoch` / `qpc_frequency` beside it.** ~~Still open: the `.partial` file format is undefined, and it is the crash-recovery artifact — PR-D's, pre-committed in HANDOFF §P2 (CRC-framed append-only chunks, the valid prefix wins)~~ **Built 2026-09-10 (P2 PR-D): `06_DATA_MODEL` §The `.partial` file, `PartialSessionFile` + `PartialRecovery`, killed at every byte in the merge gate.** What stays open here is the pipe's use of the guid (P3) | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
| ~~**Settings registry**~~ | ~~The `settings` table is key/value with no key list, defaults, types, or validation — and no message for the UI to push a changed setting to the Agent.~~ **Decided 2026-09-13 (HANDOFF §P3 decision D16)**: the key list with defaults and ranges, and *no* push message — the Agent re-reads its keys at each session start. **Built the same day (P3 PR-3):** `06_DATA_MODEL` §Settings registry (12 keys), `Application.Settings.SettingsRegistry` + `RegisteredSettings` (validating writes, tolerant reads), `SettingsRecorderPolicy` resolving `capture.min_session_s` / `telemetry.interval_ms` / `retention.raw_sessions_per_game` at each session start. **Row closed** | `06_DATA_MODEL`, FR-10 |
| **Error taxonomy** | `07_IPC` lists `CaptureError` codes; no canonical mapping to resx keys and user-facing text, though `09_I18N` requires safety strings to be reviewed as legal text | `07_IPC`, `09_I18N` |
| ~~**Threading model**~~ | ~~Which component owns which thread, UI-thread rules, and how the 1 Hz telemetry poller, 10 Hz drain and pipe reader interact~~ **Answered 2026-09-09 (P2 PR-C): `04_CAPTURE` §Threading model** — four threads, one owner per shared object, the pipe reader named as one more producer. This row was not struck when the section was written; struck 2026-09-13. What is still unspecified is the UI thread's own rules, which is `08_UI`'s in P3 | `04_CAPTURE`, `18_GPU_VENDOR_APIS` |
| **Pipe/shm security** | Stated as policy ("DACL granting the current user's SID") but not as implementable SDDL, nor who creates the objects with what rights. The shm half is built (`fl_shm_host.h`, the Overlay creates the section under the current user's SID); the pipe half is **built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D11)**: `D:P(A;;GA;;;<user>)(A;;GA;;;BA)` 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` |
| **Pipe/shm security** | Stated as policy ("DACL granting the current user's SID") but not as implementable SDDL, nor who creates the objects with what rights. The shm half is built (`fl_shm_host.h`, the Overlay creates the section under the current user's SID); the pipe half is **built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D11)**: `D:P(A;;GA;;;<user>)(A;;GA;;;BA)` (with the owner `O:<user>` stated since 2026-09-17, `07_IPC` §C) handed to `CreateNamedPipe` with `PIPE_REJECT_REMOTE_CLIENTS`, and the client's token user compared by impersonation on its first frame (`Infrastructure.Ipc.PipeAccessControl`, pinned by `PipeServerClientTests` including the refused stranger). **Row closed** | `07_IPC` |
| ~~**Legal doc versioning**~~ | ~~FR-11 re-shows documents "when a document version increments". Nothing says where the current version lives, who writes `legal_acceptance.version`, or how the markdown is rendered in-app~~ **Answered 2026-09-14 (P3 PR-9):** the version is the document's own `**Version:**` line, read from the copy embedded in the App at build (`App.Services.LegalDocuments`); the App writes `legal_acceptance.version` on the one Accept and re-shows any document whose embedded version differs from its row; the markdown is shown as text with authoring comments stripped, not rendered (`08_UI` §First-run flow built note) | FR-11, `06_DATA_MODEL` |
| **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` |
+296 -3
View File
@@ -690,7 +690,7 @@ The README sentence is **not a percentage** — the recorded decision is that th
cannot answer four of the five questions at all.
**Two things nobody has costed** (found by the completeness critic, 2026-08-05):
`StaticGameDetector` has **no runnable vehicle** — every construction is in tests — so
`StaticGameDetector` ~~has **no runnable vehicle** — every construction is in tests~~ *(runs in the Agent's `DetectionSweep` since P4 PR-1, 2026-09-14)* — so
item 4's mandated comparison cannot be re-run on the *baseline* side either; and the
only candidate title exercising all five required values is a **Streamline** title,
i.e. the one class where the hook premise is recorded INCONCLUSIVE.
@@ -1356,6 +1356,290 @@ charts (6) after Games (5) because the summary opens from the Sessions tab; Sett
- **D17 — `FL_MOCK`, if the owner wants it, is `--serve --mock` under `--data-dir` only** (D6's shape), so a
synthetic session can never land in the profile's ledger.
## 0.1.0-beta.3 (2026-09-21) — what it decided, and the traps it paid for
*PRs #204-#210. Status is where status lives (`CHANGELOG.md` `[0.1.0-beta.3]`); this is only what no other file carries.*
**Decisions (owner, 2026-09-21).**
- ~~**D18 — the guard has one override, and its shape is fixed.**~~ **Withdrawn 2026-09-22 (D22, below).** Per game, off by default, never global, a two-act
disclosure stamped by the Agent, overruling the guard's JUDGEMENT only, never changing HOW FrameLedger injects.
`19_SAFETY` §The user's bypass is the specification and CLAUDE.md rule 2 carries it as a rule. The owner chose this
over a global switch and over a variant that kept kernel-level families refused. **Do not widen it**: no settings key,
no CLI verb (`--console` has none on purpose), no rules-file field. A Vulkan title the guard refuses stays refused.
- **D19 — the DLSS preset derived from the render scale is STILL not shown.** `Domain.Metrics.UpscalerNames` names the
measured byte only; §7a's decision stands open. The driver-reported rung reached the App, identity only.
- **D20 — the bug bundle does not get the machine's hardware.** `sysinfo.json`'s keys are the issue link's prefill;
`--diag` and Settings ▸ System (with Copy) carry it instead.
**Owed by the owner after this release.** `20_OPEN_QUESTIONS` M10 (one elevated session with PawnIO beside a reference
tool decides whether `cpu_temp` stays); a look at the light theme's pills ~~, the bypass dialog~~ and Settings ▸ System in the
running App — no FrameLedger binary was run against the owner's data folder in the session that built them ~~; the ja
review of `Safety_Bypass_*`, which ships as English until signed~~ (moot since 2026-09-22: the strings are gone).
**Traps.**
- **xUnit.net v3 4.x defaults to Microsoft Testing Platform v2.** `build.ps1` is VSTest-shaped (collector, `results.trx`);
the projects reference `xunit.v3.mtp-off`. Moving to MTP is a `build.ps1` change, never a version bump.
- **4.0.1's scheduler found a race 3.2.2 never did**: test classes that WRITE the static `Strings.Culture` must share
`StringsCultureCollection`. A new App test that sets the culture and is not in it will fail one run in N.
- **A bash heredoc mangles apostrophes and `\\`, even quoted.** Every patch script in this session that carried C#
verbatim strings, `\n` escapes or prose with `'` was written with the Write tool and run by path.
- **A WPF page property named `System` does not compile** — the generated `.g.cs` resolves `System.` against it.
- **NSubstitute: never build a substitute inside another's `Returns(...)`** (`CouldNotSetReturnDueToNoLastCall`).
- **Branch protection requires an up-to-date branch.** A small PR merged in the middle of a train puts every open PR
`BEHIND`; `gh pr update-branch N` and a second CI cycle is the price. Merge the train in order and keep side PRs out.
- **`guard_test.cpp`'s native-log test slept a fixed 1500 ms** and was read between two lines on a loaded runner; it
polls now. Record a flake on the PR BEFORE `gh run rerun --failed` erases it.
## 0.1.0-beta.4 (2026-09-21) — four faults from beta.3's first day
*Status is `CHANGELOG.md` `[0.1.0-beta.4]`; this is what no other file carries.*
**Decision (D21).** A process an anti-cheat driver protects is `TargetUnreadable`, and nothing FrameLedger offers changes
that: it is not, and may not become, a way past another product's protection (rule 3, not rule 2). ~~"the bypass
stops there"~~ — the override itself is gone since 2026-09-22 (D22).
**Found and NOT fixed — each needs its own PR.**
- ~~**A refused session is not recorded, though the notice says it is.**~~ **Fixed 2026-09-22 (D23):** the loop holds a
refused session open until the target exits, so Tier 2 has a producer and the sentence is true for every refusal.
- **A released Overlay logs its build as `v0.1.0-beta.3-dirty`**: the CI checkout is dirty by the time CMake runs
`git describe`. Both sides of the handshake compile the same string, so nothing breaks; it is a release that calls
itself dirty.
- ~~**An install over a running Agent half-replaces the folder** (three failed starts, `Microsoft.Data.Sqlite` not
found).~~ **A GUESS, WITHDRAWN the same evening, and it had already been published in beta.4's notes.** Nothing was
installed between the failures (20:59–21:01) and the start that worked (21:02); the PC had been restarted at 20:57
and was again at 21:02 (System log 1074), and the owner's external USB drive was failing all evening. The three
failed starts are UNEXPLAINED. What is still true and still unbuilt: `Setup.exe` run by hand does not stop the Agent,
and only the CHANGELOG says to.
- **A GF2 session ended `SafetyUnhook` 35 s in (2026-09-21 21:45) and nothing recorded which finding fired.** ~~read it
the next time it happens before guessing~~ **Mostly explained by the owner's report:** the game is on the failing
drive, `GF2_Exilium.exe` crashed at 21:45:50 with `0xc0000006` (in-page I/O error, Application log 1000/1005, eleven
Ntfs errors in that minute), and the Agent saved the session at 21:45:52. The 30 s re-scan reads the game's directory
(check 4) and the process; either failing is a refusal by design, so a dying drive reads as a safety unhook. **Open:**
that row says `UnhookedSafety` about a game Windows says crashed — whether a crash witness should outrank the unhook
in `ExitStatusMapper` is a decision, not a bug fix. The log line's new `guard=` detail will say which check it was.
- **Read Windows' event logs before attributing a symptom** (`Get-WinEvent` System: disk 51/153, UASPStor 129, Ntfs;
Application: 1000/1005). On 2026-09-21 the first pass published one cause that was wrong and left one 'unknown' that
those two logs answered in a minute.
**Traps.**
- **`CultureInfo.CurrentUICulture` set inside an `async` start does not reach later dispatcher operations.** A resource
accessor with no explicit `Culture` follows whichever thread asks. Give every string family its culture explicitly.
- **`TargetResolver` counts a process it cannot read, and zero readable + some unreadable is not "ambiguous".** A test
against a real protected process exists (`csrss.exe`); it needs no fixture and runs elevated or not.
- **`Mutex` is thread-affine**: `SingleInstance` is claimed and disposed on `Main`'s thread; its tests are synchronous
on purpose.
## 2026-09-22 — the override withdrawn; a finding turns hooking off; Tier 2 exists; a moved drive is followed
*Status is `CHANGELOG.md` `[0.1.0-beta.5]`; this is what no other file carries.*
**Decision (D23, owner: "Tier 2 does not work — what does it record, and show it").** Tier 2 is now a held session
(`04_CAPTURE` §Tier selection): duration, telemetry and the reason, saved under the same 30 s rule as Tier 1. **Two
choices inside it that a later session may want to revisit:** (a) *every* library row is still watched, so a
hooking-off game accumulates play-time rows — the documented behaviour (`06_DATA_MODEL` "0 = Tier 2"), kept; the
alternative, watching only rows the user enabled or FrameLedger itself disabled, is one predicate in
`CaptureOrchestrator` and a doc change; (b) a hooking-off row is decided BEFORE the process is opened, so an
elevated utility in the library (the owner's Borderless Gaming) is a quiet Tier-2 row rather than a red notice — and
`SteamLibrarySource.KnownTools` keeps the next import from adding one. The owner's existing Borderless Gaming row is
theirs to remove.
**Decision (D24, owner: "handle the drive changing its letter while the data does not").** A row may follow its
executable to another drive-letter root when the file is gone from the row's path and exactly one other root holds a
file with the same size and mtime — with consent, block and detection kept (`19_SAFETY` §A moved drive is the same
executable). Three callers: the 15 s sweep, the watcher's file-name match, the enable-hooking command. The owner's
log of the same morning is the case: 46 rows unreadable on `D:` while the drive sat on `H:`, GF2 and ELDEN RING
running from `H:` "BY FILE NAME ONLY". ~~**Not done, on purpose:** re-import does not merge a duplicate row an earlier
re-scan created at the new path (`LibraryImporter` still dedupes on path); the relocator refuses to move onto a path
another row owns and says so in the log.~~ **Done 2026-09-23 (D26/D27, the beta.6 section below):** twins with the
same bytes merge, a changed file is followed with hooking off, and the import no longer adds a twin.
**Trap.** `FakeIdentity` in three test classes answers the same fingerprint for ANY path; a relocation test needs one
that answers per path, or the "exactly one candidate" rule reads every root as a match.
**Decision (D22, owner).** The per-game guard override (D18) is withdrawn entirely — the owner's words: a switch that
can be turned on and still does nothing is meaningless. In its place a finding about the game turns that game's hooking
off, at the pre-scan (as before), at a session's start and at the 30 s re-scan (new): `19_SAFETY` §What a finding does to the game.
Machine-wide drivers and services refuse the session only. D18 and D21's "the bypass stops there" are history; D21's
fact stands.
**Traps.**
- **Removing an enum value that is LAST on both sides of the ABI renumbers nothing**, and `GuardMirrorTests` fails until
the native DLL in the test output is rebuilt (`./build.ps1 native`) — it looks like a managed defect and is not.
- **The first `DROP COLUMN` migration.** SQLite ≥ 3.35 is asserted in `LedgerDatabaseTests`. The test helper
`RewindSchemaAsync` deletes `schema_migrations` rows and leaves columns in place; a rewind to below 8 followed by a
re-migration would run 0008 against columns that are gone. Today it rewinds to 2 and never re-migrates.
- **Meziantou MA0004 fires on the SECOND await of a test method** once a lambda inside it used `ConfigureAwait(false)`.
- **A patch script must not carry `\r\n` inside a bash heredoc**; the helper module is written with the Write tool.
## 2026-09-23 — the beta.6 train: a file name is not an identity, one entry per executable, Tier 2 shown live
*Status is `CHANGELOG.md` `[0.1.0-beta.6]`; this is what no other file carries. The owner's list and the
evidence behind each item are in the approved plan the PRs cite; the decisions it took are D25–D28.*
**Decision (D25, owner: "HELLO, HELLO WORLD! was recorded as Flower in Us, twice").** A file name is not an identity:
a process that matches an entry by file name only starts nothing unless the relocator moves that entry to it, and the
relocator accepts only the entry's own path with its drive letter changed. The stranger session is gone (it created a
wrongly-named entry through `SessionRecorder`'s `EnsureAsync`); the running table is keyed by executable path; the
launch election registers its session and defers to the watcher's. **What it costs:** a game whose FOLDER moved records
nothing until *Change executable* — accepted, because the alternative is exactly what put HHW's sessions under Flower
in Us. **D28 (owner, same day):** HHW itself is measured by pointing an entry at `swiftshader\Game.exe` (the NW.js
runtime its .NET launcher starts); no launcher-following in beta.6.
**Decision (D26, owner: "the library still shows two entries side by side after the drive letter changed, with the
data unchanged").** The Agent merges two entries for one executable under two drive letters by itself: the stale
entry's file is gone, the other entry holds the same path on another letter, and the file there has the bytes the
stale entry recorded. The entry made first stays; the other's sessions join it; a block or a crash auto-disable in
force is kept; no consent moves between them; it waits while a session of either runs or waits to be recovered
(`CaptureOrchestrator.IsRecording`, `IPartialSessionStore.PendingGameIds`). `19_SAFETY` §A moved drive has the rules,
`06_DATA_MODEL` the writer. The import no longer adds a twin: a store's executable that is a library entry's path on
another letter, with that entry's file gone, is shown "in the library under another drive letter" and skipped.
**D27 (owner, same day):** when the only file at the entry's path on another letter has other bytes, the entry follows
it with hooking off (`ChangeExecutableAsync`, the *Change executable* write). Other bytes under a twin are NOT merged
— the log says once which entry to remove.
**Traps.**
- **`IGameMerge` is a second writer that can delete a `games` row.** Only the relocator calls it; a test that removes
rows under a running session must expect the merge to wait (busy), not to race it.
- **Python patch scripts: `\"` inside a normal triple-quoted string is an escaped quote**, so `@"C:\"` silently loses
its backslash and the replace finds nothing (or worse, writes the wrong text). Use raw strings (`r"""…"""`) for C#.
- **`FakeIdentity` in `CaptureOrchestratorTests` answers every path with the same bytes — which is exactly the hazard
D25 closed**, so it is the right fake for "identical bytes in another folder are another game" and the wrong one for
any test that needs a relocation to succeed (use `ExecutableRelocatorTests.DiskByPath`).
- **A background service that throws stops the Agent's host, and until 2026-09-23 it said so nowhere.** The Generic
Host's default `BackgroundServiceExceptionBehavior` is `StopHost`, and `ServeAsync` never routed
Microsoft.Extensions.Logging into Serilog, so the reason reached no file. `WatcherHostedService` runs recovery before
the watcher: one `.partial` whose finalize threw would have stopped every start, and the App would have started a new
Agent into the same failure each time. `PartialRecovery` never throws now, and the host logs through `AddSerilog`.
- **Removing an entry while its game runs used to lose the session.** Both of the owner's GIRLS' FRONTLINE 2 faults
were a removal (to clean up an `H:` twin) under a running session. The finalize now resolves the owner; a test that
deletes a row mid-session must expect `GameRemoved` or a re-keyed row, never an exception.
**Tier 2 on the wire (item 4a, owner: "capture still does not show when some titles are launched").** `SessionStarted`
is published ONCE per session — at the attach, or at a held session's first tick carrying `hold` — so the card never
flickers between tiers; a held session's 1 Hz is `SessionHeld`, never `SessionProgress` (its required fields would put
zeros that look measured on the wire); the refusal's event goes out when the hold begins and is not repeated at the
end; a faulted session completes with `finalize: faulted`. Every list of running sessions the App keeps is seeded from
the status at each connect (`07_IPC` §Client behavior). All fields are additive: `IpcProtocol.Version` stays 2.
**Traps.**
- **Only `hold` means held.** The status lists every session that has not attached yet at tier 2 (beta.5's shape,
kept), so a tier-2 `ActiveSession` without `hold` is a session STARTING. The card shows its name and badge and
nothing else; "nothing is measured" and "Attached — waiting for the first frames…" would both be false there.
- **`sed -i` in this machine's Git Bash writes a CRLF file back as LF.** Twice on 2026-09-23 a one-line `sed -i` turned
a test file into `w/lf` (`git ls-files --eol`), which `dotnet format` then fails on for no visible reason. Check
`git ls-files --eol -m -o --exclude-standard | grep -v w/crlf` after any shell edit; `unix2dos` repairs it.
- **Heredocs that carry C# with nested quotes can fail to parse in the Bash tool** ("unexpected EOF while looking for
matching `'`") even when quoted `<<'EOF'` — write the script with the Write tool and run it by path, as the traps
above already say for patches.
## 2026-09-23 (after 0.1.0-beta.6) — the recording switch
*Status is `CHANGELOG.md` `[0.1.0-beta.7]`; this is what no other file carries.*
**Decision (D29, owner: "the Agent records Borderless Gaming although hooking is off, and it starts with Windows —
propose an ignore list, a disable, or something suitable").** Both, as one mechanism: a per-entry **Recording**
switch (`games.record_sessions`, schema 0009, FR-1.6) the user owns, and the import's known-tools list
(`SteamLibrarySource.KnownTools`) applied once to the entries an earlier import made, which start with it off. Off
means the program is not watched at all (the watchlist is the entries whose recording is on), a running session of it
stops at the next poll, and `LaunchGame` answers `RecordingOff`. Not chosen: a hard-coded list the watcher consults
(no user control, and a list is never complete), and D23's recorded alternative of recording Tier 2 only for entries
hooking was once enabled for (it would take back the Tier-2 sessions the owner asked for). The Privacy Policy (2.3) and
the Disclaimer (2.6, whose accuracy block also carries #224's correction) were bumped with the owner's leave ("sửa docs
và legal"), so the Legal Gate shows both once.
**Traps.**
- **A pid the watcher matched stays matched.** Switching recording off stops the session but leaves the process in
`ProcessWatcher`'s table, so switching it back on while the same process still runs starts nothing until it restarts.
A process the watcher never matched (off from the start) is picked up by the next poll.
- **A migration that changes data needs its own rewind in a test.** `RewindSchemaAsync` leaves columns in place, so
`ScriptNineAddsTheRecordingSwitchOffForSteamToolsOnly` drops the column itself before re-applying 0009.
- **`SqliteGameRepository._columns` is read by ordinal** (`ReadMore`): a new column goes at the end of the list, and the
twin merge reads its own columns — both had to learn `record_sessions`.
## 2026-09-25 — the beta.8 train
*Status is `CHANGELOG.md` `[0.1.0-beta.8]`; this is what no other file carries. The owner's list
(eight items: the anti-cheat set as large and strict as possible, hiding the hook part for anti-cheat games, more
metadata, NVIDIA App overrides, clearer reasons, a working Trend, FPS decimals, chart fixes) is planned as nine PRs in
one approved plan; each PR cites it.*
**Decision (D30, owner, asked before any code: "which strict rules, beyond named tokens?").** Two of three: **any
kernel driver (`*.sys`) inside a game's install tree** is a finding (code, not data — `kKernelDriverInTreeFamily`),
and **per-title lists** (30 Steam ids, 33 executables across nine families, floored like the families). **Not** the
AreWeAntiCheatYet bulk import (~250 Steam ids): community data that keeps listing a game after it drops its anti-cheat
would turn hooking off for good, since nothing clears a block. Recorded because the next person to "expand the list"
will find that import one search away.
**Decision (D31, owner): the store half's matrix.** Listed → refuse; no store identity (a loose folder, an Epic
install, a Steam folder no manifest names) → not applicable, recorded as nothing; a store layout whose metadata cannot
be read → refuse (`PreScanFailed`). §S14's "unknown must never read clean" is kept by the third row; the second is not
an unknown — it is the answer "this is not a store title", and refusing it would be the gate that cannot pass.
**Decision (D32, owner, item 2: "an option to hide the hook part for games with anti-cheat").** Hide **and** scan:
the Agent pre-scans every library entry itself (`AntiCheatPreScanSweep`, checks 3 and 4, once per rules version and
executable — schema 0010's key), a finding is the same block every other moment writes, and the game's page shows
the finding in place of the Hooking card while `ui.hide_anticheat_hooking` is on (default on). Tier 2 is still
recorded. **Why not the setting alone:** most entries sat at `hook_prescan_state = 'not_run'` — the pre-scan ran only
when someone asked for hooking — so a hide keyed on a finding would have hidden nothing on most libraries. **What it
must never become:** a gate. The chokepoint runs checks 1–4 at every session start whatever the sweep wrote; the sweep
only answers early, writes through the consent store's block-preserving `UPDATE`, and hides a control that could
only be refused, never the finding (FR-2.2).
**Traps.**
- **`Rules` is ~650 KB now** (256 families, 128 per-title rules). `x = Rules{}` builds that on the stack before
copying — use `ResetRules`. The Vulkan layer parses on a game's own `vkCreateInstance` thread, and native tests hold
it on the heap (two in one test function overflowed the 1 MB default).
- **New `anticheat.modules` rows go at the END.** The Overlay's early stop reports a 1-based index into that order, and
`sessions.early_stop_family` stores it.
- **`sed -i` and the Bash tool's heredocs strike again**: a heredoc halved `\\` in a Python patch (a C# verbatim path
still matched by luck), and a one-line `sed -i` turned `layer.cpp` into LF. Scripts go through the Write tool and run
by path; `git ls-files --eol -m` after any shell edit.
- **`'clean'` is not new.** `AgentCommandHandler` has stamped it on every consented enable since P3; the sweep adds it
for entries nobody enabled. Nothing gates on it — a reader that treats `'clean'` as "may hook" is a second gate.
- **The sweep's notice is not a refusal.** `HookingTurnedOff` is `SafetyNoticeKind.HookingOff` with Dismiss: a
`Refused` kind would offer "record this session without measuring it" with no session running.
- **Analyzers on tests:** CA2000 flags a disposable passed into a record's constructor (construct it inside a class
that disposes it), MA0023 a regex with numbered groups (name them), CA1062 a `[Theory]` string parameter
dereferenced without a check.
- **`exe_machine` NULL is stale (schema 0011).** The detection sweep re-reads any row whose executable facts this build
has not written — so a test double of `IGameRepository.ApplyDetectionAsync` that drops the new fields makes every
sweep test re-scan forever. `unknown` is the stored "looked, could not tell".
- **`FileVersionInfo` on a System32 file reads its `.mui`.** `version.dll` read in place said 6.2.x, its copy in a temp
folder 10.0.x: compare a version against the file that was read, never against its source.
- **`PASS_REGULAR_EXPRESSION` alone makes ctest ignore the exit code.** `fl_nvapi_bridge` passed for weeks with a failing
assertion on every GPU machine (CI has no driver, so never took the branch). Any test that must print a line AND
pass needs a `FAIL_REGULAR_EXPRESSION` beside it; running the test binary directly is the check.
- **A C ABI cannot give a function and a struct one name** (`FlNvDriverProfile` the export, `FlNvDriverProfileRead` the
struct): C puts typedefs and functions in one namespace, and MSVC's error names neither clearly.
- **The driver profile is a configuration.** `sessions.driver_profile` says what the NVIDIA App set; it never feeds
the upscaler ladder or the factor. The bridge has no DRS writer, and a PR that adds one is a different product.
- **Present-to-present is not a frame time on a frame-generation title.** DLSS FG submits its generated frames in a
burst (measured: half a millisecond apart on the owner's Onimusha capture); anything over `ft_app` — lows, median,
σ, stutter, the charts' default line — is application frame to application frame (`FrameTimeSeries.ApplicationFrames`,
`SessionSeriesLoader.ApplicationFrames`).
- **A gap is neither a frame time nor time** (beta.8): `FrameTimeSeries.MeasuredSeconds` and `FgWindow.Seconds` leave
out every interval a gap sat in. A pause is a gap (`CaptureSession.MarkResume`); do not mark one any other way.
- **Reading the owner's ledger for evidence: copy it (`ledger.db` + `-wal`) to the scratchpad and read the copy** with
plain SQLite — never a FrameLedger binary against the data folder. `capture_tier` is an integer (1 = hooked); the
frame flags are Generated = 1, Gap = 4.
- **A view model that loads in its constructor raises its events to nobody** until the page subscribes; a page must
draw what the view model already holds when it is made (the Trend tab was blank on every first open).
- **`Axes.DateTimeTicksBottom()` replaces the bottom axis**: call it before the theme and the label, or both are lost.
- **A local property value outranks a style trigger** (Compare's best cell was never accent-coloured): defaults a
trigger may change go in the Style as Setters.
- **`ui.fps_decimals` is process-wide state** (`FpsDecimals`): a test that moves it belongs to `StringsCultureCollection`
with every test that reads FPS text, and restores it.
- **A status is not a policy input.** Splitting End task (exit 1) out of `crashed` would have loosened the crash
auto-disable had the policy kept reading the status alone; it takes the exit code too. Check every reader of a value
whose meaning you narrow.
- **The gate's own refusals carry a label in the family slot** (`not enabled`, `no consent`, `kill switch`, `previously
blocked`, `HookedCaptureGate`), so "has a family" does not mean "is a finding" — `IsFindingAboutTheGame` is the test.
- **`add_strings.py` replaced an existing key in place** (`Exit_Normal`, the Sessions grid's word) — it now refuses
without `--replace`; diff the resx for `-.*<value>` before committing new strings.
- **A 32-bit refusal is not a block.** `ExecutableNotX64` writes nothing — no `hook_blocked_reason`, no stamp — so a
64-bit build of the same game under *Change executable* can be hooked; the sweep's turn-off uses
`hook_autodisabled_reason`, which the page does not offer to undo while the file is still 32-bit.
## Owner-only — no PR can close these
1. **§S23-2 — branch protection.** `Rules / validate` is not a required status check on
@@ -1371,8 +1655,9 @@ charts (6) after Games (5) because the summary opens from the Sessions tab; Sett
2026-09-03 (P4) and 2026-09-04 (P1); done.** What is still owed here is the **quality
preset** on a title that chains `sl::DLSSOptions` — Alan Wake 2 is the candidate — and
the DLSS-G identity on a title where `kFeatureDLSS_G` is evaluated, if one exists.
3. **Which titles** go in `blockedExecutables` — a product decision with false-refusal
consequences. The list ships empty until it is taken.
3. ~~**Which titles** go in `blockedExecutables` — a product decision with false-refusal
consequences. The list ships empty until it is taken.~~ **Taken 2026-09-25 (D30):** per-title
lists by Steam id and executable name, seeded and floored (§2026-09-25 — the beta.8 train).
4. **§H7's confirmation against the overlays actually resident on the dev machine.** The
compare-and-restore path is proven against a fixture (ctest `fl_unhook_inline`); §H7 still
says the six real overlays are *"worth doing once the Overlay has real hooks"*, and it has
@@ -1410,6 +1695,14 @@ deferred with a written rationale.
The mechanical ones live in the toolchain notes; these are the ones that cost a *wrong
diagnosis*.
- **A VERB THAT PRINTS WAS A WRITER UNTIL 2026-09-16, AND THE OWNER'S LEDGER IS NOT A FIXTURE.** `--console
sessions` against `%LOCALAPPDATA%\FrameLedger\ledger.db` applied two migration scripts, because every verb opened
through the one migrating path. The print verbs open read-only now (`Program.PrintsOnly`; a schema older than the
build is refused, exit 7) — but the rule that outlives the fix is: **nothing from a session is run against the
owner's data directory unless the owner asks for exactly that**; `--data-dir` exists for everything else. The same
day's ledger held a whole day of rows only in a WAL a fresh connection discarded (`06_DATA_MODEL` §Migrations
carries the shape); if `ledger: wal at open` in `agent-*.log` or `ui-*.log` reports frames that a passive checkpoint
did not move while no other FrameLedger process is running, stop and read that note before touching the file.
- **THE TESTS WRITE INTO THE REAL DATA FOLDER, AND THAT IS NOT A SWITCH TO ADD.** The Overlay's log path is
`SHGetKnownFolderPath`, never the environment (§S21), and the tests inject the shipped DLL, so 2492 hook-harness
logs had piled up in the owner's `%LOCALAPPDATA%\FrameLedger\logs` by 2026-09-15. Each test binary now sweeps the
+36
View File
@@ -0,0 +1,36 @@
# 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).
+26 -7
View File
@@ -2462,7 +2462,8 @@ produced no false refusal on any real install.
## 14 · The P2 milestone and the FPS-impact run *(slots — the owner's runs)*
**Nothing below has been run.** The section exists because P2's code is finished and its two
**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
@@ -2487,14 +2488,32 @@ 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, 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` | | | |
| `upscaler_quality` | | | *(`N/A` is the measured answer on every title so far — §9, P0 exit criterion 1)* |
| `render_w` × `render_h` → `output_w` × `output_h` | | | |
| `fg_mode` / `fg_factor` | | | |
| `rt_flag` | | | |
| `telemetry_source` | | *(expect `l1+lhm+nvapi` on this box since PR-E2)* | |
| `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.
+66 -30
View File
@@ -11,35 +11,71 @@
that changes what FrameLedger.Overlay or the capture host does; date the change.
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-09-06.** The software is pre-alpha: the
> measurement path exists as an injected Direct3D 11/12 component and an **unshipped** capture
> host that drives the guard loop and prints a report; there is no Agent loop, no storage, no
> charts, no library import, no UI and no installer yet.
> ⚠ **What FrameLedger actually measures today — 2026-09-25.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.8`** (2026-09-25), 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 hook, for injected D3D11/12
> titles, and for Vulkan titles **launched through FrameLedger** (the layer intercepts
> `vkQueuePresentKHR` since 2026-09-06; a Vulkan title already running when FrameLedger attaches is
> not observed). OpenGL/D3D9 intercept nothing yet.
> - **Which upscaler is running:** measured from the API the game calls — DLSS (with Ray
> Reconstruction Yes/No) through NVIDIA Streamline; FSR 2/3.x/4 through AMD's shipped DLLs; DLSS on
> titles that bypass Streamline is reported from the NVIDIA driver's own per-process record,
> labelled *driver-reported*. Intel XeSS is **not** read (its SDK licence forbids it) and reads
> `N/A` by policy; an upscaler compiled into the game executable reads `N/A`.
> - **Quality preset:** `N/A` everywhere. No route this software may use exposes it.
> - **Render → output resolution:** measured where the vendor's own call carries the size (AMD
> dispatches, some Streamline titles); `N/A` where it does not (NVIDIA-direct titles, most
> Direct3D 12 Streamline titles).
> - **Frame generation:** the Displayed rate is counted from presents — including, on one title,
> presents DXGI counted that the hook could not — and the Native rate from the vendor's own
> per-frame calls where the title makes them. Identity: DLSS-G and FSR-FG named from the calls
> the game makes; anything else (XeSS-FG, a generator compiled into the game) is reported *by
> elimination* and never named. Where no per-frame call exists the Native rate is `N/A`.
> - **Ray tracing:** Yes/No measured from DXR dispatches and acceleration-structure builds on
> Direct3D 12; the technique and path tracing are `N/A`.
> - **Not measured at all:** video memory, shader-compilation stutter, PC latency (Reflex), HDR.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-
> vendor half of the suspicious-module rule (since 2026-09-06), and the unshipped capture host
> re-runs them every 30 s and stops the capture on refusal. No shipped component drives that loop
> yet. There is no override anywhere.
> - **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.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), 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 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.
>
> Where a value is not measured it reads `N/A`; the software never substitutes an estimate.
> 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.
+130 -57
View File
@@ -1,32 +1,28 @@
# FrameLedger — Disclaimer
**Version:** 2.0-draft · **Effective:** {{RELEASE_DATE}}
**Version:** 2.6 · **Effective:** {{RELEASE_DATE}}
> ⚠ Draft for review. Not legal advice. Review before first public release — this version covers code injection and should be read carefully.
> **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.
> ⚠ **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.
>
> **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: 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.
> - §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).
## 0. This is pre-release (beta) software
**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, 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)
@@ -57,7 +53,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 (§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.
@@ -83,6 +79,15 @@ 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
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 turns that back on for that executable. Sessions recorded under the earlier switch stay in your database,
marked as such in their notes.
## 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.**
@@ -92,47 +97,97 @@ Software running inside another process can, in principle, destabilize it. Frame
Frame timing is derived from high-resolution timestamps taken at the moment the game presents each frame; upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs. This is substantially more accurate than inferring settings from files on disk, but **no measurement is guaranteed to be exact**:
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-06.** The software is pre-alpha: the
> measurement path exists as an injected Direct3D 11/12 component and an **unshipped** capture
> host that drives the guard loop and prints a report; there is no Agent loop, no storage, no
> charts, no library import, no UI and no installer yet.
> ⚠ **What FrameLedger actually measures today — 2026-09-25.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.8`** (2026-09-25), 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 hook, for injected D3D11/12
> titles, and for Vulkan titles **launched through FrameLedger** (the layer intercepts
> `vkQueuePresentKHR` since 2026-09-06; a Vulkan title already running when FrameLedger attaches is
> not observed). OpenGL/D3D9 intercept nothing yet.
> - **Which upscaler is running:** measured from the API the game calls — DLSS (with Ray
> Reconstruction Yes/No) through NVIDIA Streamline; FSR 2/3.x/4 through AMD's shipped DLLs; DLSS on
> titles that bypass Streamline is reported from the NVIDIA driver's own per-process record,
> labelled *driver-reported*. Intel XeSS is **not** read (its SDK licence forbids it) and reads
> `N/A` by policy; an upscaler compiled into the game executable reads `N/A`.
> - **Quality preset:** `N/A` everywhere. No route this software may use exposes it.
> - **Render → output resolution:** measured where the vendor's own call carries the size (AMD
> dispatches, some Streamline titles); `N/A` where it does not (NVIDIA-direct titles, most
> Direct3D 12 Streamline titles).
> - **Frame generation:** the Displayed rate is counted from presents — including, on one title,
> presents DXGI counted that the hook could not — and the Native rate from the vendor's own
> per-frame calls where the title makes them. Identity: DLSS-G and FSR-FG named from the calls
> the game makes; anything else (XeSS-FG, a generator compiled into the game) is reported *by
> elimination* and never named. Where no per-frame call exists the Native rate is `N/A`.
> - **Ray tracing:** Yes/No measured from DXR dispatches and acceleration-structure builds on
> Direct3D 12; the technique and path tracing are `N/A`.
> - **Not measured at all:** video memory, shader-compilation stutter, PC latency (Reflex), HDR.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-
> vendor half of the suspicious-module rule (since 2026-09-06), and the unshipped capture host
> re-runs them every 30 s and stops the capture on refusal. No shipped component drives that loop
> yet. There is no override anywhere.
> - **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.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), 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 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.
>
> Where a value is not measured it reads `N/A`; the software never substitutes an estimate.
> 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.
@@ -145,6 +200,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>
+13 -4
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.2 · **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.
@@ -16,7 +14,7 @@ The Software records game performance data, hardware telemetry (temperatures, lo
## 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 (Disclaimer §2A).
By enabling this feature for a game, you confirm that:
@@ -32,6 +30,17 @@ By enabling this feature for a game, you confirm that:
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.
## 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.
+17 -14
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.1-draft · **Effective:** {{RELEASE_DATE}}
**Version:** 2.4 · **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,29 +8,28 @@
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), session duration, crash flags, the graphics driver's settings the game ran under (NVIDIA only), 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, amended 2026-09-14: the "Safety list update" and "Detection-rules update" rows describe outbound requests the software does not make.** The "Update check" and "Update download" rows are real since 2026-09-14 (version 2.1 of this document — a new outbound request is a material change): Velopack, against GitHub's release API and release assets, from an installed copy only, the startup check off with one switch in Settings ▸ Updates, and the request carries `User-Agent: FrameLedger/<version>` and nothing else of ours. The rules rows are not real: there is no rules 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.
> **History.** Versions 2.0 and 2.1 of this document listed three further rows — a weekly safety-list update, a weekly detection-rules update, and an opt-in Steam store lookup — describing requests the software did not make; from 2026-08-04 they carried an audit note saying so. Version 2.2 (2026-09-16) removes them. A privacy policy that lists a transmission which never happens is as wrong as one that omits a transmission which does.
GitHub's own privacy practices apply to requests it receives: <https://docs.github.com/privacy>.
## 3. Bug reports — always manual
@@ -38,9 +37,13 @@ The "Report a bug" feature builds a zip file **on your device**, shows you exact
## 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); video-memory usage reported by the graphics runtime; loaded module names of a game being captured (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling libraries it ships, and the store files that name it (Steam's and GOG's, on your disk) — to detect its engine and features and to check it for anti-cheat before any injection is possible; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); and hardware sensor values from your graphics driver's own libraries.
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.
> **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.
All of this stays on your device. None of it is transmitted anywhere.
+4 -3
View File
@@ -48,6 +48,7 @@ FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the th
| **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` |
## GPU telemetry — what is bundled and what is not
@@ -93,16 +94,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)
- [x] `legal/licenses/` contains full texts: MIT (per-project copies, **including `nvapi-MIT.txt`**), BSD-2-Clause (MinHook), MPL-2.0, Apache-2.0 — **2026-09-15 (P4 PR-6):** the vendored natives' copies as before, plus one generated text per shipped NuGet package in `legal/licenses/nuget/` (77), gated by `license-check` §3; the .NET runtime's licence and notices are added to the package by `release.yml`. The copies ship: the App's publish carries `legal/licenses/` as `licenses/`
- [ ] About → Third-party tab lists this table with versions filled from `Directory.Packages.props`
- [ ] About → Third-party tab lists this table with versions filled from `Directory.Packages.props` — **not built as of 2026-09-16 and not a gate for the first pre-release**: the texts ship as files (`licenses/` beside the App, `licenses/nuget/INDEX.md` lists every package with its version), and Help ▸ Documentation opens this file; the tab is an open UI item
- ~~PresentMon license + copyright shipped beside the bundled binary~~ — **removed 2026-08-27 with the dependency.** Nothing Intel-authored is distributed by this project
- [x] MPL-2.0 source-availability note points to upstream LibreHardwareMonitor repository — every MPL-2.0 package text in `legal/licenses/nuget/` names its Source Code Form (MPL-2.0 §3.2), LHM's `https://github.com/LibreHardwareMonitor/LibreHardwareMonitor` included (2026-09-15)
- [x] LHM checked for MPL-2.0 Exhibit B on any depended-upon file — clear as of 0.9.6 / commit `3d331e33`, 2026-08-02
- [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
+2 -2
View File
@@ -1,10 +1,10 @@
Dapper 2.1.79
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://github.com/DapperLib/Dapper
Project: https://dapperlib.dev/
Ships in: Agent, App
-------------------------------------------------------------------------------
+30 -30
View File
@@ -9,7 +9,7 @@ from the runtime packs the publish used.
|---|---|---|---|---|
| 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.79 | Apache-2.0 | Agent, App | [Dapper.txt](Dapper.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) |
@@ -18,34 +18,34 @@ from the runtime packs the publish used.
| HarfBuzzSharp.NativeAssets.Win32 | 8.3.1.1 | MIT | App | [HarfBuzzSharp.NativeAssets.Win32.txt](HarfBuzzSharp.NativeAssets.Win32.txt) |
| HidSharp | 2.6.4 | the file LICENSE.txt in the package | Agent, App | [HidSharp.txt](HidSharp.txt) |
| LibreHardwareMonitorLib | 0.9.6 | MPL-2.0 | Agent, App | [LibreHardwareMonitorLib.txt](LibreHardwareMonitorLib.txt) |
| Microsoft.Data.Sqlite.Core | 10.0.10 | MIT | Agent, App | [Microsoft.Data.Sqlite.Core.txt](Microsoft.Data.Sqlite.Core.txt) |
| Microsoft.Extensions.Configuration | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.txt](Microsoft.Extensions.Configuration.txt) |
| Microsoft.Extensions.Configuration.Abstractions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Abstractions.txt](Microsoft.Extensions.Configuration.Abstractions.txt) |
| Microsoft.Extensions.Configuration.Binder | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Binder.txt](Microsoft.Extensions.Configuration.Binder.txt) |
| Microsoft.Extensions.Configuration.CommandLine | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.CommandLine.txt](Microsoft.Extensions.Configuration.CommandLine.txt) |
| Microsoft.Extensions.Configuration.EnvironmentVariables | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.EnvironmentVariables.txt](Microsoft.Extensions.Configuration.EnvironmentVariables.txt) |
| Microsoft.Extensions.Configuration.FileExtensions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.FileExtensions.txt](Microsoft.Extensions.Configuration.FileExtensions.txt) |
| Microsoft.Extensions.Configuration.Json | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Json.txt](Microsoft.Extensions.Configuration.Json.txt) |
| Microsoft.Extensions.Configuration.UserSecrets | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Configuration.UserSecrets.txt](Microsoft.Extensions.Configuration.UserSecrets.txt) |
| Microsoft.Extensions.DependencyInjection | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.DependencyInjection.txt](Microsoft.Extensions.DependencyInjection.txt) |
| Microsoft.Extensions.DependencyInjection.Abstractions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.DependencyInjection.Abstractions.txt](Microsoft.Extensions.DependencyInjection.Abstractions.txt) |
| Microsoft.Extensions.Diagnostics | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Diagnostics.txt](Microsoft.Extensions.Diagnostics.txt) |
| Microsoft.Extensions.Diagnostics.Abstractions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Diagnostics.Abstractions.txt](Microsoft.Extensions.Diagnostics.Abstractions.txt) |
| Microsoft.Extensions.FileProviders.Abstractions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.FileProviders.Abstractions.txt](Microsoft.Extensions.FileProviders.Abstractions.txt) |
| Microsoft.Extensions.FileProviders.Physical | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.FileProviders.Physical.txt](Microsoft.Extensions.FileProviders.Physical.txt) |
| Microsoft.Extensions.FileSystemGlobbing | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.FileSystemGlobbing.txt](Microsoft.Extensions.FileSystemGlobbing.txt) |
| Microsoft.Extensions.Hosting | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Hosting.txt](Microsoft.Extensions.Hosting.txt) |
| Microsoft.Extensions.Hosting.Abstractions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Hosting.Abstractions.txt](Microsoft.Extensions.Hosting.Abstractions.txt) |
| Microsoft.Extensions.Logging | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.txt](Microsoft.Extensions.Logging.txt) |
| Microsoft.Extensions.Logging.Abstractions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.Abstractions.txt](Microsoft.Extensions.Logging.Abstractions.txt) |
| Microsoft.Extensions.Logging.Configuration | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.Configuration.txt](Microsoft.Extensions.Logging.Configuration.txt) |
| Microsoft.Extensions.Logging.Console | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.Console.txt](Microsoft.Extensions.Logging.Console.txt) |
| Microsoft.Extensions.Logging.Debug | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.Debug.txt](Microsoft.Extensions.Logging.Debug.txt) |
| Microsoft.Extensions.Logging.EventLog | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.EventLog.txt](Microsoft.Extensions.Logging.EventLog.txt) |
| Microsoft.Extensions.Logging.EventSource | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Logging.EventSource.txt](Microsoft.Extensions.Logging.EventSource.txt) |
| Microsoft.Extensions.Options | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Options.txt](Microsoft.Extensions.Options.txt) |
| Microsoft.Extensions.Options.ConfigurationExtensions | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Options.ConfigurationExtensions.txt](Microsoft.Extensions.Options.ConfigurationExtensions.txt) |
| Microsoft.Extensions.Primitives | 10.0.10 | MIT | Agent, App | [Microsoft.Extensions.Primitives.txt](Microsoft.Extensions.Primitives.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) |
@@ -76,7 +76,7 @@ from the runtime packs the publish used.
| 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.10 | MIT | Agent | [System.Diagnostics.EventLog.txt](System.Diagnostics.EventLog.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) |
@@ -1,4 +1,4 @@
Microsoft.Data.Sqlite.Core 10.0.10
Microsoft.Data.Sqlite.Core 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.Abstractions 10.0.10
Microsoft.Extensions.Configuration.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.Binder 10.0.10
Microsoft.Extensions.Configuration.Binder 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.CommandLine 10.0.10
Microsoft.Extensions.Configuration.CommandLine 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.EnvironmentVariables 10.0.10
Microsoft.Extensions.Configuration.EnvironmentVariables 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.FileExtensions 10.0.10
Microsoft.Extensions.Configuration.FileExtensions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.Json 10.0.10
Microsoft.Extensions.Configuration.Json 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration.UserSecrets 10.0.10
Microsoft.Extensions.Configuration.UserSecrets 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Configuration 10.0.10
Microsoft.Extensions.Configuration 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.DependencyInjection.Abstractions 10.0.10
Microsoft.Extensions.DependencyInjection.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.DependencyInjection 10.0.10
Microsoft.Extensions.DependencyInjection 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Diagnostics.Abstractions 10.0.10
Microsoft.Extensions.Diagnostics.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Diagnostics 10.0.10
Microsoft.Extensions.Diagnostics 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.FileProviders.Abstractions 10.0.10
Microsoft.Extensions.FileProviders.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.FileProviders.Physical 10.0.10
Microsoft.Extensions.FileProviders.Physical 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.FileSystemGlobbing 10.0.10
Microsoft.Extensions.FileSystemGlobbing 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Hosting.Abstractions 10.0.10
Microsoft.Extensions.Hosting.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Hosting 10.0.10
Microsoft.Extensions.Hosting 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging.Abstractions 10.0.10
Microsoft.Extensions.Logging.Abstractions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging.Configuration 10.0.10
Microsoft.Extensions.Logging.Configuration 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging.Console 10.0.10
Microsoft.Extensions.Logging.Console 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging.Debug 10.0.10
Microsoft.Extensions.Logging.Debug 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging.EventLog 10.0.10
Microsoft.Extensions.Logging.EventLog 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging.EventSource 10.0.10
Microsoft.Extensions.Logging.EventSource 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Logging 10.0.10
Microsoft.Extensions.Logging 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Options.ConfigurationExtensions 10.0.10
Microsoft.Extensions.Options.ConfigurationExtensions 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Options 10.0.10
Microsoft.Extensions.Options 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Microsoft.Extensions.Primitives 10.0.10
Microsoft.Extensions.Primitives 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
System.Diagnostics.EventLog 10.0.10
System.Diagnostics.EventLog 10.0.12
Licence declared: MIT
Text below: the standard MIT text; the package ships no licence file
@@ -1,4 +1,4 @@
Third-party notices first found in Microsoft.Extensions.Configuration 10.0.10 THIRD-PARTY-NOTICES.TXT
Third-party notices first found in Microsoft.Extensions.Configuration 10.0.12 THIRD-PARTY-NOTICES.TXT
.NET Runtime uses third-party libraries or other resources that may be
distributed under licenses different than the .NET Runtime software.
+211 -24
View File
@@ -15,16 +15,15 @@
"compilability, case-insensitive duplicate values — stay imperative in",
"tools/rules-validate.ps1.",
"",
"STILL INCOMPLETE AS DATA: docs/19_SAFETY §Blocklist seed names two families",
"with no representation here at all — Activision Ricochet (driver/service",
"names not yet confirmed) and Valve VAC (needs blockedStoreIds entries).",
"STILL INCOMPLETE AS DATA: docs/19_SAFETY §Blocklist seed names one family",
"with no representation here at all — Valve VAC (needs blockedStoreIds",
"entries). Activision Ricochet was the other until 2026-09-25, when its",
"driver and services arrived from Activision's own support pages.",
"",
"PRE-INJECTION CHECK 3 MATCHES NOTHING, because `blockedExecutables` and",
"`blockedStoreIds` are both empty. That is a fact about THIS DATA, which is",
"why it is stated here; seeding the lists is a product decision (which",
"titles, and what an unresolvable store id means) tracked as",
"docs/20_OPEN_QUESTIONS.md §S14. Recorded rather than left to be inferred",
"from two empty arrays.",
"PRE-INJECTION CHECK 3 MATCHED NOTHING until 2026-09-25, because",
"`blockedExecutables` and `blockedStoreIds` were both empty. The owner seeded",
"them that day (rules 2026.09.4); what an unresolvable store id means is",
"the matrix in docs/19_SAFETY check 3 (docs/20_OPEN_QUESTIONS.md §S14).",
"",
"WHICH CHECKS RUN IS DELIBERATELY NOT STATED HERE ANY MORE. This comment used",
"to list them — a FOURTH restatement of the gate's composition, in the one",
@@ -41,7 +40,7 @@
"level, which made it a check that could not fire."
],
"schemaVersion": 2,
"rulesVersion": "2026.08.2",
"rulesVersion": "2026.09.5",
"engines": [
{
@@ -62,6 +61,45 @@
] },
"version": { "type": "pe_product_version_regex", "value": "\\+\\+UE(4|5)\\+Release-(\\d+\\.\\d+)" }
},
{
"id": "rpgmaker_mv",
"name": "RPG Maker MV/MZ",
"signals": { "all": [
{ "type": "sibling_glob", "value": "nw.dll" },
{ "type": "sibling_glob", "value": "package.json" }
] },
"version": null
},
{
"id": "rpgmaker_rgss",
"name": "RPG Maker XP/VX/VX Ace",
"signals": { "any": [
{ "type": "sibling_glob", "value": "RGSS1*.dll" },
{ "type": "sibling_glob", "value": "RGSS2*.dll" },
{ "type": "sibling_glob", "value": "RGSS3*.dll" },
{ "type": "sibling_glob", "value": "*.rgssad" },
{ "type": "sibling_glob", "value": "*.rgss2a" },
{ "type": "sibling_glob", "value": "*.rgss3a" }
] },
"version": null
},
{
"id": "re_engine",
"name": "RE Engine",
"signals": { "any": [
{ "type": "sibling_glob", "value": "re_chunk_000.pak" }
] },
"version": null
},
{
"id": "fromsoftware",
"name": "FromSoftware",
"signals": { "all": [
{ "type": "sibling_glob", "value": "*.bhd" },
{ "type": "sibling_glob", "value": "*.bdt" }
] },
"version": null
},
{
"id": "godot",
"name": "Godot",
@@ -144,8 +182,8 @@
{ "id": "dlss_g", "name": "DLSS Frame Gen", "signals": [ "nvngx_dlssg.dll", "sl.dlss_g.dll" ] },
{ "id": "dlss_rr", "name": "Ray Reconstruction","signals": [ "nvngx_dlssd.dll" ] },
{ "id": "streamline", "name": "Streamline", "signals": [ "sl.interposer.dll", "sl.reflex.dll" ] },
{ "id": "fsr", "name": "FSR", "signals": [ "ffx_fsr2_*.dll", "ffx_frameinterpolation_*.dll", "amd_fidelityfx_*.dll", "ffx_api*.dll" ] },
{ "id": "xess", "name": "XeSS", "signals": [ "libxess.dll" ] },
{ "id": "fsr", "name": "FSR", "signals": [ "ffx_fsr2_*.dll", "ffx_fsr3*.dll", "ffx_frameinterpolation_*.dll", "amd_fidelityfx_*.dll", "ffx_api*.dll" ] },
{ "id": "xess", "name": "XeSS", "signals": [ "libxess.dll", "libxess_dx11.dll" ] },
{ "id": "xefg", "name": "XeSS Frame Gen", "signals": [ "libxess_fg.dll" ] }
],
@@ -159,30 +197,129 @@
{ "family": "Xigncode3", "match": "prefix", "values": [ "xhunter" ] },
{ "family": "PunkBuster", "match": "prefix", "values": [ "PnkBstr", "pbcl", "pbsv" ] },
{ "family": "FACEIT", "match": "prefix", "values": [ "faceit" ] },
{ "family": "ESEA", "match": "prefix", "values": [ "esea" ] }
{ "family": "ESEA", "match": "prefix", "values": [ "esea" ] },
{ "family": "Anti-Cheat Expert", "match": "prefix", "values": [ "SGuard", "AntiCheatExpert" ],
"note": "APPENDED 2026-09-25, as every row below: the Overlay reports a 1-based index into this array (sessions.early_stop_family), so a row inserted above shifts what stored indexes mean. SGuard64/SGuardSvc64 are ACE's guard processes (documented, file.net; unmeasured)." },
{ "family": "EA AntiCheat", "match": "prefix", "values": [ "EAAntiCheat" ],
"note": "EA Javelin: EAAntiCheat.GameServiceLauncher.dll / EAAntiCheat.GameService.exe (documented, EA forums). Unmeasured." },
{ "family": "NetEase Anti-Cheat", "match": "prefix", "values": [ "NeacSafe", "NeacClient" ],
"note": "NEAC (Naraka, Marvel Rivals, FragPunk). NeacSafe64 is documented (LOLDrivers, SteamDB NetEase_AntiCheatExperts); NeacClient unmeasured." },
{ "family": "NetEase Yidun", "match": "exact", "values": [ "NEP2.dll" ],
"note": "Documented (SteamDB FileDetectionRuleSets, NetEase_Yidun). Unmeasured." },
{ "family": "Nexon Game Security", "match": "prefix", "values": [ "BlackCipher", "BlackCall", "BlackXchg" ],
"note": "BlackCipher64.aes runs as its own process in the game's tree (The First Descendant, MapleStory). Documented (SteamDB BlackCipher). Unmeasured." },
{ "family": "mihoyo protect", "match": "prefix", "values": [ "mhypbase" ],
"note": "mhypbase.dll is the user-mode half HoYoverse titles load. Documented; unmeasured." },
{ "family": "TenProtect", "match": "prefix", "values": [ "TP3Helper", "TenSafe" ],
"note": "Tencent TenProtect. TP3Helper documented (SteamDB); TenSafe unmeasured." },
{ "family": "AhnLab HackShield", "match": "prefix", "values": [ "EhSvc", "HShield", "HSInst" ],
"note": "Documented (SteamDB HackShield: HShield/HSInst.dll). Unmeasured." },
{ "family": "Anybrain", "match": "exact", "values": [ "anybrainSDK.dll", "Cerebro.dll" ],
"note": "Behavioural, user-mode. Documented (SteamDB AnyBrain). Unmeasured." },
{ "family": "Roblox Hyperion", "match": "exact", "values": [ "RobloxPlayerBeta.dll" ],
"note": "Hyperion (Byfron) protects this module inside the Roblox player. Documented; unmeasured." },
{ "family": "EQU8", "match": "prefix", "values": [ "equ8" ],
"note": "Splitgate. Documented (SteamDB EQU8); module names unmeasured." },
{ "family": "Xigncode3", "match": "exact", "values": [ "x3.xem" ],
"note": "x3.xem is XIGNCODE3's loader, LoadLibrary'd as an ordinary module (documented). The files row names the same token in the install tree." }
],
"drivers": [
{ "family": "Riot Vanguard", "match": "exact", "values": [ "vgk.sys" ], "scope": "machine" },
{ "family": "mihoyo protect", "match": "prefix", "values": [ "mhyprot" ], "scope": "machine" },
{ "family": "mihoyo protect", "match": "prefix", "values": [ "mhyprot", "HoYoKProtect" ], "scope": "machine",
"note": "HoYoKProtect.sys (Genshin Impact's overseas client, 2025) is NOT matched by the mhyprot prefix, so it is named here (documented; unmeasured)." },
{ "family": "Easy Anti-Cheat", "match": "prefix", "values": [ "EasyAntiCheat" ], "scope": "machine",
"note": "MEASURED 2026-08-04: EasyAntiCheat_EOSSys was Running as a kernel driver while a real EAC title played, and matched NOTHING in this group — the refusal came from the service check instead. A family caught through only one of five groups is one rename away from being missed." },
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "ACE-BASE.sys", "ACE-ADVT.sys", "ACE-GAME.sys" ], "scope": "machine",
"note": "ACE-BASE.sys and ACE-ADVT.sys MEASURED under System32\\drivers on the dev machine 2026-08-04. ACE-GAME.sys is a documented sibling and is UNMEASURED: a blocklist may over-cover, never under-cover. Exact not prefix — 'ACE-' is four characters over a namespace we do not own." }
"note": "ACE-BASE.sys and ACE-ADVT.sys MEASURED under System32\\drivers on the dev machine 2026-08-04. ACE-GAME.sys is a documented sibling and is UNMEASURED: a blocklist may over-cover, never under-cover. Exact not prefix — 'ACE-' is four characters over a namespace we do not own." },
{ "family": "BattlEye", "match": "exact", "values": [ "BEDaisy.sys" ], "scope": "machine",
"note": "BattlEye's kernel driver, loaded by BEService while a protected game runs and unloaded after (documented, BattlEye FAQ). Unmeasured." },
{ "family": "FACEIT", "match": "exact", "values": [ "FACEIT.sys" ], "scope": "machine",
"note": "Loaded while the FACEIT AC client runs (documented, FACEIT support). Unmeasured." },
{ "family": "ESEA", "match": "prefix", "values": [ "ESEADriver" ], "scope": "machine",
"note": "ESEADriver2.sys (documented). Unmeasured." },
{ "family": "EA AntiCheat", "match": "exact", "values": [ "EAAntiCheat.sys" ], "scope": "machine",
"note": "EA Javelin's kernel driver, loaded with the game (documented, EA forums). Unmeasured. Its user-mode EAAntiCheatService is deliberately NOT listed: it can be set to start automatically, and a service that is always running would refuse every session on the machine." },
{ "family": "Activision Ricochet", "match": "exact", "values": [ "randgrid.sys", "brynhildr.sys", "atvi-brynhildr.sys" ], "scope": "machine",
"note": "RICOCHET's kernel driver randgrid.sys (documented, Activision support; a kernel service pointing at the file in the game folder); brynhildr is its 2021 predecessor (Microsoft Q&A). Unmeasured." },
{ "family": "NetEase Anti-Cheat", "match": "prefix", "values": [ "NeacSafe" ], "scope": "machine",
"note": "NeacSafe64.sys, a minifilter loaded during play (documented, LOLDrivers). Unmeasured." },
{ "family": "Xigncode3", "match": "prefix", "values": [ "xhunter" ], "scope": "machine",
"note": "xhunter1.sys, XIGNCODE3's kernel driver (documented, LOLDrivers / Wellbia FAQ). Unmeasured." },
{ "family": "Denuvo Anti-Cheat", "match": "exact", "values": [ "denuvo-anti-cheat.sys" ], "scope": "machine",
"note": "Loaded only while a protected game runs (documented, Irdeto Q&A; file name from DRML). Unmeasured." },
{ "family": "EQU8", "match": "prefix", "values": [ "EQU8_HELPER" ], "scope": "machine",
"note": "EQU8_HELPER_<n>.sys (documented). Unmeasured." },
{ "family": "PunkBuster", "match": "prefix", "values": [ "PnkBstrK" ], "scope": "machine",
"note": "PnkBstrK.sys, PunkBuster's kernel component. Unmeasured." },
{ "family": "TenProtect", "match": "exact", "values": [ "TesSafe.sys" ], "scope": "machine",
"note": "Tencent game-protection driver (documented). Unmeasured." },
{ "family": "Nexon Game Security", "match": "exact", "values": [ "BlackCat64.sys" ], "scope": "machine",
"note": "Documented (SteamDB BlackCipher). Unmeasured." }
],
"directories": [
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat" ] },
{ "family": "BattlEye", "values": [ "BattlEye" ] }
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat", "EasyAntiCheat_EOS" ] },
{ "family": "BattlEye", "values": [ "BattlEye" ] },
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert", "AceAntibotClient" ],
"note": "Documented (SteamDB FileDetectionRuleSets, AntiCheatExpert). Unmeasured." },
{ "family": "nProtect GameGuard", "values": [ "GameGuard" ] },
{ "family": "Xigncode3", "values": [ "XIGNCODE", "XIGNCODE3" ] },
{ "family": "AhnLab HackShield", "values": [ "HShield" ],
"note": "Documented (SteamDB HackShield). Unmeasured." },
{ "family": "Nexon Game Security", "values": [ "BlackCipher" ],
"note": "Measured by others at M1/Binaries/Win64/BlackCipher/ (The First Descendant, Steam community); unmeasured here." },
{ "family": "PunkBuster", "values": [ "PunkBuster" ],
"note": "Documented (SteamDB PunkBuster). The two-letter pb/ folder some titles use is deliberately NOT a token: too short to be a signal." },
{ "family": "FredaikisAntiCheat", "values": [ "FredaikisAntiCheat" ],
"note": "Documented (SteamDB FileDetectionRuleSets). Unmeasured." }
],
"services": [
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat", "EasyAntiCheat_EOS", "EasyAntiCheat_EOSSys" ] },
{ "family": "Riot Vanguard", "values": [ "vgc" ] },
{ "family": "Riot Vanguard", "values": [ "vgc", "vgk" ],
"note": "vgk is the kernel driver's service, started at boot like vgk.sys itself." },
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert Protection", "AntiCheatExpert Service" ],
"note": "'AntiCheatExpert Protection' MEASURED registered on the dev machine 2026-08-04 by Neverness To Everness. The sibling name is unmeasured." }
"note": "'AntiCheatExpert Protection' MEASURED registered on the dev machine 2026-08-04 by Neverness To Everness. The sibling name is unmeasured." },
{ "family": "BattlEye", "values": [ "BEService", "BEDaisy" ],
"note": "BEService is started by a protected game and stops after it; BEDaisy is the driver's service. A stopped service is absent (19_SAFETY). Unmeasured." },
{ "family": "FACEIT", "values": [ "FACEIT", "FACEITService" ],
"note": "Running while the FACEIT AC client runs (documented, FACEIT support). Unmeasured." },
{ "family": "ESEA", "values": [ "ESEADriver2" ] },
{ "family": "Activision Ricochet", "values": [ "atvi-randgrid_sr", "atvi-randgrid_msstore" ],
"note": "Kernel services pointing at randgrid.sys; running only while Call of Duty runs (documented, Activision support). Unmeasured." },
{ "family": "mihoyo protect", "values": [ "mhyprot2", "mhyprot3", "HoYoKProtect" ] },
{ "family": "Xigncode3", "values": [ "xhunter1" ] },
{ "family": "Denuvo Anti-Cheat", "values": [ "denuvo-anti-cheat" ],
"note": "The driver's service. The separate update service runs outside play and is deliberately NOT listed." },
{ "family": "nProtect GameGuard", "values": [ "npggsvc" ] }
],
"files": [
{ "family": "Xigncode3", "values": [ "x3.xem" ], "note": "Data file shipped beside the game, not a loadable module." },
{ "family": "Anti-Cheat Expert", "values": [ "PGameProtectDriver_X64.sys" ],
"note": "A KERNEL DRIVER shipped inside the game install. MEASURED at 'Neverness To Everness/NTEGlobal/driver/' 2026-08-04, where check 4 returned Allow: no group named it, and the fuzzy tier is modules-only — so a name containing 'protect' sat in the game's tree and the static scan walked past." }
{ "family": "Xigncode3", "values": [ "x3.xem", "xhunter1.sys" ],
"note": "Shipped beside the game. This note said 'not a loadable module' until 2026-09-25: XIGNCODE3 LoadLibrary's x3.xem as its loader (documented), which is why the modules group names it too." },
{ "family": "Anti-Cheat Expert", "values": [ "PGameProtectDriver_X64.sys", "SGuard64.exe", "SGuardSvc64.exe" ],
"note": "A KERNEL DRIVER shipped inside the game install. MEASURED at 'Neverness To Everness/NTEGlobal/driver/' 2026-08-04, where check 4 returned Allow: no group named it, and the fuzzy tier is modules-only — so a name containing 'protect' sat in the game's tree and the static scan walked past." },
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat_EOS_Setup.exe", "EasyAntiCheat_Setup.exe", "EasyAntiCheat_x64.dll", "EasyAntiCheat_x86.dll", "EasyAntiCheat_EOS.sys", "start_protected_game.exe", "eac_server64.dll" ],
"note": "For a layout where the EasyAntiCheat folder sits deeper than the scan reaches. start_protected_game.exe is the EAC launcher FromSoftware titles ship (ELDEN RING's appeared in the owner's Windows Application log on 2026-09-21)." },
{ "family": "BattlEye", "values": [ "BEService.exe", "BEService_x64.exe", "BEClient.dll", "BEClient_x64.dll", "BEDaisy.sys" ],
"note": "Documented (SteamDB BattlEye). Unmeasured." },
{ "family": "EA AntiCheat", "values": [ "EAAntiCheat.Installer.exe", "EAAntiCheat.GameServiceLauncher.exe", "EAAntiCheat.GameServiceLauncher.dll" ],
"note": "Documented (SteamDB EA_AntiCheat; EA forums). Unmeasured." },
{ "family": "Activision Ricochet", "values": [ "randgrid.sys" ],
"note": "The driver ships inside the game folder (documented, Activision support). Unmeasured." },
{ "family": "mihoyo protect", "values": [ "mhypbase.dll", "mhyprot2.sys", "mhyprot3.sys", "HoYoKProtect.sys" ] },
{ "family": "NetEase Anti-Cheat", "values": [ "NeacSafe64.sys", "NeacSafe64_ex.sys" ],
"note": "Documented (SteamDB NetEase_AntiCheatExperts). Unmeasured." },
{ "family": "NetEase Yidun", "values": [ "NEP2.dll" ] },
{ "family": "Nexon Game Security", "values": [ "BlackCipher.aes", "BlackCipher64.aes", "BlackCall.aes", "BlackCall64.aes", "BlackCat64.sys" ] },
{ "family": "TenProtect", "values": [ "TP3Helper.exe" ] },
{ "family": "EQU8", "values": [ "equ8_conf.json" ] },
{ "family": "AhnLab HackShield", "values": [ "HSInst.dll", "EhSvc.dll" ] },
{ "family": "nProtect GameGuard", "values": [ "GameGuard.des", "GameMon.des", "GameMon64.des", "npggNT.des", "npggNT64.des", "npsc.des" ],
"note": "GameGuard's engine files (documented, file.net / SteamDB). Unmeasured." },
{ "family": "PunkBuster", "values": [ "pbsvc.exe", "PnkBstrA.exe", "PnkBstrB.exe", "pbsv.dll", "pbcl.dll", "pbag.dll" ],
"note": "Files in the install tree, not services: PnkBstrA runs at every boot once installed, so as a service it would refuse every session on the machine." },
{ "family": "Anybrain", "values": [ "anybrainSDK.dll", "Cerebro.dll" ] },
{ "family": "Denuvo Anti-Cheat", "values": [ "denuvo-anti-cheat.sys", "denuvo-anti-cheat-runtime.dll", "denuvo-anti-cheat-update-service.exe" ],
"note": "Documented (DRML). Unmeasured." },
{ "family": "Roblox Hyperion", "values": [ "RobloxPlayerBeta.dll" ] }
],
"heuristic": {
"$comment": [
@@ -232,7 +369,57 @@
],
"action": "warn_and_refuse"
},
"blockedExecutables": [],
"blockedStoreIds": []
"blockedExecutables": [
{ "family": "Valve VAC", "match": "exact", "values": [ "cs2.exe", "csgo.exe", "dota2.exe", "tf_win64.exe", "deadlock.exe", "project8.exe", "left4dead2.exe", "gmod.exe" ],
"reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "family": "Riot Vanguard", "match": "exact", "values": [ "VALORANT-Win64-Shipping.exe", "League of Legends.exe" ],
"reason": "Protected by Riot Vanguard, a kernel anti-cheat that loads at boot." },
{ "family": "Roblox Hyperion", "match": "exact", "values": [ "RobloxPlayerBeta.exe" ],
"reason": "The Roblox player is protected by Hyperion anti-tamper." },
{ "family": "Blizzard Warden", "match": "exact", "values": [ "Overwatch.exe", "Diablo IV.exe", "Diablo III64.exe", "Wow.exe", "WowClassic.exe", "SC2_x64.exe", "HeroesOfTheStorm_x64.exe" ],
"reason": "An online Blizzard title: its anti-cheat is built into the game and ships no file of its own." },
{ "family": "Activision Ricochet", "match": "exact", "values": [ "cod.exe", "ModernWarfare.exe", "BlackOpsColdWar.exe" ],
"reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "family": "NetEase Anti-Cheat", "match": "exact", "values": [ "Marvel-Win64-Shipping.exe", "NarakaBladepoint.exe" ],
"reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "DeltaForceClient-Win64-Shipping.exe" ],
"reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
{ "family": "mihoyo protect", "match": "exact", "values": [ "GenshinImpact.exe", "YuanShen.exe", "StarRail.exe", "ZenlessZoneZero.exe", "BH3.exe" ],
"reason": "A HoYoverse title, protected by its kernel anti-cheat driver." },
{ "family": "EA AntiCheat", "match": "exact", "values": [ "bf2042.exe", "bf6.exe", "FC25.exe", "FC26.exe" ],
"reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." }
],
"blockedStoreIds": [
{ "store": "steam", "id": "730", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "570", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "440", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "1422450", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "240", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "10", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "80", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "550", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "500", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "4000", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "320", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "300", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "20", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "1938090", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "1962663", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "3595270", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "4384550", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "2519060", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "2357570", "family": "Blizzard Warden", "reason": "An online Blizzard title: its anti-cheat is built into the game and ships no file of its own." },
{ "store": "steam", "id": "2344520", "family": "Blizzard Warden", "reason": "An online Blizzard title: its anti-cheat is built into the game and ships no file of its own." },
{ "store": "steam", "id": "2767030", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "1203220", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "2943650", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "2139460", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "2507950", "family": "Anti-Cheat Expert", "reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
{ "store": "steam", "id": "2073620", "family": "Anti-Cheat Expert", "reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
{ "store": "steam", "id": "1517290", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
{ "store": "steam", "id": "2807960", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
{ "store": "steam", "id": "2669320", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
{ "store": "steam", "id": "3405690", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." }
]
}
}
+9 -9
View File
@@ -404,7 +404,7 @@
"$comment": "maxItems is fl::guard::kMaxFamilies, and it bounds the SUM of all five groups, not this one array - the parser fills a single families[kMaxFamilies] from all of them. A schema cannot express a cross-array total, so the per-array cap is set to the total (no single array can breach it alone) and tools/rules-validate.ps1 checks the sum imperatively. Exceeding it is ParseResult::kTooLarge for the whole file, i.e. the guard refuses every title.",
"type": "array",
"minItems": 1,
"maxItems": 64,
"maxItems": 256,
"items": { "$ref": "#/$defs/acMatchGroup" },
"allOf": [
{
@@ -420,7 +420,7 @@
"drivers": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"maxItems": 256,
"items": { "$ref": "#/$defs/acDriverGroup" },
"allOf": [
{
@@ -429,29 +429,29 @@
]
},
"directories": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/$defs/acNameGroup" } },
"services": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/$defs/acNameGroup" } },
"directories": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "$ref": "#/$defs/acNameGroup" } },
"services": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "$ref": "#/$defs/acNameGroup" } },
"files": {
"$comment": "NEW in this schema. 19_SAFETY lists Xigncode3's `x3.xem`, which is a data file shipped beside the game rather than a loadable module - the previous seed had nowhere to put it. Also the home for the anti-cheat SDK payloads that 19_SAFETY check 4 (multiplayer heuristic) looks for during the static pre-scan.",
"$comment": "NEW in this schema. 19_SAFETY lists Xigncode3's `x3.xem`, which is a data file shipped beside the game rather than a loadable module - the previous seed had nowhere to put it (2026-09-25: XIGNCODE3 also LoadLibrary's it as its loader, so modules names it too). Also the home for the anti-cheat SDK payloads that 19_SAFETY check 4 (multiplayer heuristic) looks for during the static pre-scan.",
"type": "array",
"minItems": 1,
"maxItems": 64,
"maxItems": 256,
"items": { "$ref": "#/$defs/acNameGroup" }
},
"heuristic": { "$ref": "#/$defs/heuristic" },
"blockedExecutables": {
"$comment": "May legitimately be empty - a per-title list, not the family blocklist. minItems is deliberately absent here and deliberately present on modules/drivers. maxItems is fl::guard::kMaxTitleRules; at kMaxValuesPerTitleRule values each that is 512 blockable names, more than the 4096 this used to claim could ever have survived the parser.",
"$comment": "May legitimately be empty - a per-title list, not the family blocklist. minItems is deliberately absent here and deliberately present on modules/drivers. maxItems is fl::guard::kMaxTitleRules (128 since 2026-09-25); at kMaxValuesPerTitleRule values each that is 1024 blockable names, more than the 4096 this used to claim could ever have survived the parser.",
"type": "array",
"maxItems": 64,
"maxItems": 128,
"items": { "$ref": "#/$defs/acBlockedExecutable" }
},
"blockedStoreIds": {
"type": "array",
"maxItems": 64,
"maxItems": 128,
"items": { "$ref": "#/$defs/acBlockedStoreId" }
}
}
@@ -31,6 +31,7 @@ internal sealed record AgentCommandLine
private const string _usage =
"usage: FrameLedger.Agent --serve\n"
+ " FrameLedger.Agent --register-vklayer | --unregister-vklayer | --install-task | --uninstall-task\n"
+ " FrameLedger.Agent --write-crash-dump <file> (started by a crashing App or Agent; dumps that parent)\n"
+ " FrameLedger.Agent --console [--data-dir <dir>] consent list | consent grant --exe <path> | consent revoke --exe <path>\n"
+ " | capture --exe <path> [--seconds <n>] | launch --exe <path> [--args \"<string>\"] [--seconds <n>]\n"
+ " | recover | sessions [--last <n>] | db path | games add --exe <path>\n"
@@ -58,6 +59,9 @@ internal sealed record AgentCommandLine
public string? DataDirectory { get; init; }
/// <summary>The file <see cref="AgentVerb.WriteCrashDump"/> writes — a path, never a pid.</summary>
public string? CrashDumpFile { get; init; }
/// <summary>The flag behind <see cref="AgentVerb.NotImplemented"/>.</summary>
public string? Flag { get; init; }
@@ -84,6 +88,13 @@ internal sealed record AgentCommandLine
: new AgentCommandLine { Error = $"{args[0]} takes no options" };
}
if (string.Equals(args[0], "--write-crash-dump", StringComparison.Ordinal))
{
return args.Length == 2 && !string.IsNullOrWhiteSpace(args[1])
? new AgentCommandLine { Verb = AgentVerb.WriteCrashDump, CrashDumpFile = args[1] }
: new AgentCommandLine { Error = "--write-crash-dump takes exactly one argument, the dump's file" };
}
if (string.Equals(args[0], "--serve", StringComparison.Ordinal))
{
return args.Length == 1
+7
View File
@@ -35,4 +35,11 @@ internal enum AgentVerb
/// <summary><c>--uninstall-task</c>.</summary>
UninstallTask,
/// <summary>
/// <c>--write-crash-dump &lt;file&gt;</c> (2026-09-17): the crash-dump helper. Dumps this process's PARENT — the App or
/// Agent that crashed and started it — when that parent's image is in this binary's directory; takes no pid
/// (<c>Infrastructure.Diagnostics.ParentDump</c>).
/// </summary>
WriteCrashDump,
}
+1 -1
View File
@@ -276,7 +276,7 @@ internal sealed class ConsoleVerbs(IServiceProvider services, AgentPaths paths)
return result.Reason switch
{
SessionEndReason.TargetExited or SessionEndReason.Running => _exitOk,
SessionEndReason.TargetNotRunning or SessionEndReason.TargetAmbiguous
SessionEndReason.TargetNotRunning or SessionEndReason.TargetAmbiguous or SessionEndReason.TargetUnreadable
or SessionEndReason.TargetCannotBePinned or SessionEndReason.LaunchCannotStart => _exitTargetNotResolved,
SessionEndReason.AttachRefused => _exitAttachRefused,
SessionEndReason.SafetyUnhook or SessionEndReason.SupervisionLost or SessionEndReason.KillSwitchEngaged
@@ -21,8 +21,9 @@ internal static class AgentIdentityFactory
// The layer reaches a launched process through VK_ADD_IMPLICIT_LAYER_PATH; the HKCU registration is the
// repair tool --register-vklayer writes (P3 PR-8b), read here as it stands at this process's start.
VulkanLayerRegistered: new VkLayerRegistration().IsRegistered(Path.Combine(vkLayerDirectory, VkLayerLaunchEnvironment.ManifestFileName)),
// AgentRecording.Poller composes LhmComputerAdapter(enableCpuAndMemory: false): no CPU sensor unelevated.
CpuTempAvailable: false,
// The same two conditions SystemTelemetrySource.Create opens the CPU reader under (2026-09-21): elevated AND
// PawnIO installed. It was a constant false while nothing read a CPU sensor at all.
CpuTempAvailable: Infrastructure.Telemetry.LhmEnvironment.IsElevated && Infrastructure.Telemetry.LhmEnvironment.IsPawnIoInstalled == true,
// D14: the FR-2.1 text this build stamps against; the App compares it with its own before showing the dialog.
DisclosureVersion: SafetyDisclosure.Version);
}
@@ -34,6 +34,7 @@ internal sealed class AgentRecording
private readonly ISessionObserver _observer;
private readonly CapturePause _pause;
private readonly IRecorderPolicy _policy;
private readonly IDriverProfileSource _profiles;
public AgentRecording(
IGameConsentStore store,
@@ -53,8 +54,10 @@ internal sealed class AgentRecording
ICrashEventSource crashes,
ISessionObserver observer,
CapturePause pause,
IRecorderPolicy policy)
IRecorderPolicy policy,
IDriverProfileSource profiles)
{
_profiles = profiles;
_store = store;
_gate = gate;
_guard = guard;
@@ -104,7 +107,8 @@ internal sealed class AgentRecording
TimeProvider.System,
new RecorderOptions { MinimumSessionLength = minimum, PartialFlushInterval = flush },
_observer,
_policy);
_policy,
_profiles);
}
/// <summary>L1 + L2 + L3 under the composite, one poller per session; the poller owns and disposes the layers. The interval is the session's (<c>telemetry.interval_ms</c>, D16).</summary>
@@ -117,6 +121,7 @@ internal sealed class AgentRecording
LhmTelemetrySource? l2 = null;
NvapiTelemetrySource? l3 = null;
CompositeTelemetrySource? composite = null;
SystemTelemetrySource? system = null;
try
{
pdh = new PdhAdapterMemoryCounter();
@@ -131,8 +136,12 @@ internal sealed class AgentRecording
l1 = null;
l2 = null;
l3 = null;
var poller = new TelemetryPoller(composite, new TelemetryPollerOptions { Interval = interval }, TimeProvider.System, ownsSource: true);
// The machine beside the GPU (2026-09-21): CPU busy time and memory unprivileged, the CPU temperature only
// where this process is elevated and PawnIO is installed. The poller owns it with the layers.
system = SystemTelemetrySource.Create();
var poller = new TelemetryPoller(composite, new TelemetryPollerOptions { Interval = interval }, TimeProvider.System, ownsSource: true, system);
composite = null;
system = null;
return poller;
}
finally
@@ -142,6 +151,7 @@ internal sealed class AgentRecording
l2?.Dispose();
l3?.Dispose();
composite?.Dispose();
system?.Dispose();
}
}
@@ -75,13 +75,20 @@ internal static class AgentServices
services.AddSingleton<IAntiCheatGuard, NativeAntiCheatGuard>();
services.AddSingleton<HookedCaptureGate>();
// The capture path's adapters (PR-C).
services.AddSingleton<ITargetResolver>(static _ => new TargetResolver(AgentConsole.Line));
// The capture path's adapters (PR-C). The resolver's notes reach the Agent's log too (2026-09-23: there were none in
// it), and its Tier-2 liveness reads the watcher's snapshot by image path, never a process of its own.
services.AddSingleton<LatestProcessSnapshot>();
services.AddSingleton<ITargetResolver>(static sp => new TargetResolver(
static line =>
{
AgentConsole.Line(line);
Serilog.Log.Information("{Line}", line);
},
sp.GetRequiredService<LatestProcessSnapshot>()));
services.AddSingleton<ITargetLivenessSource, HeldProcessLivenessSource>();
services.AddSingleton<IRingAttacher>(static _ => new ShmRingAttacher(NativeAntiCheatGuard.BuildId()));
services.AddSingleton<IRuntimeModuleSnapshot>(static _ => new RuntimeModuleSnapshot(CensusNames.ModuleFileNames));
services.AddSingleton<NvapiNgxStateProbe>();
services.AddSingleton<INgxDriverProbe>(static sp => sp.GetRequiredService<NvapiNgxStateProbe>());
AddNvidia(services);
// The recorder's adapters (PR-D).
services.AddSingleton<IPartialSessionStore>(_ => new PartialSessionStore(paths.Tmp));
@@ -104,6 +111,19 @@ internal static class AgentServices
return services;
}
/// <summary>
/// What the NVIDIA driver says about a session, through the bridge (never into a game): the per-process NGX words (P2
/// PR-E2), and since beta.8 the driver profile each session's executable runs under — the NVIDIA App's DLSS and
/// frame-generation overrides — read from the driver's settings store through the bridge's read-only DRS entry point.
/// </summary>
private static void AddNvidia(IServiceCollection services)
{
services.AddSingleton<NvapiNgxStateProbe>();
services.AddSingleton<INgxDriverProbe>(static sp => sp.GetRequiredService<NvapiNgxStateProbe>());
services.AddSingleton<NvapiDriverProfileSource>();
services.AddSingleton<IDriverProfileSource>(static sp => sp.GetRequiredService<NvapiDriverProfileSource>());
}
/// <summary>The static detection sweep (P4 PR-1, <c>05_DETECTION</c> §Caching): hosted under <c>--serve</c> only, composed and inert under <c>--console</c>.</summary>
private static void AddDetection(IServiceCollection services, AgentPaths paths)
{
@@ -112,12 +132,40 @@ internal static class AgentServices
// --serve only (DetectionHostedService); composed and inert under --console.
services.AddSingleton<IDetectionRulesSource>(static _ => new DetectionRulesFile());
services.AddSingleton<IGameFileProbe, GameFileProbe>();
// A drive that changed its letter (2026-09-22): one relocator, asked by the sweep, the watcher and the enable-hooking
// command, over the BCL's drive list. Since 2026-09-23 it also merges two entries for one executable (D26), and waits
// while a session of either runs — the orchestrator's table, read when asked (it holds the relocator itself) — or
// waits in a .partial to be recovered.
services.AddSingleton<IGameMerge>(static sp => new SqliteGameMerge(sp.GetRequiredService<LedgerDatabase>()));
services.AddSingleton(static sp => new ExecutableRelocator(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
VolumeRoots.Ready,
static line => Serilog.Log.Information("{Line}", line),
merge: sp.GetRequiredService<IGameMerge>(),
busy: id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)
|| sp.GetRequiredService<IPartialSessionStore>().PendingGameIds().Contains(id)));
services.AddSingleton(static sp => new DetectionSweep(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IDetectionRulesSource>(),
sp.GetRequiredService<IGameFileProbe>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
static line => Serilog.Log.Information("{Line}", line)));
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<ExecutableRelocator>()));
// The anti-cheat pre-scan of the library (beta.8, 19_SAFETY §What a finding does to the game): every entry through
// the guard's advisory checks 3 and 4, again whenever the rules or the executable change. It waits while a session
// of the entry runs (the session's own checks are running then), and tells the App only when it turned hooking off
// for an entry the user had turned on. Hosted under --serve only, beside the detection sweep.
services.AddSingleton(static sp => new AntiCheatPreScanSweep(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IGameConsentStore>(),
sp.GetRequiredService<IAntiCheatGuard>(),
sp.GetRequiredService<IDetectionRulesSource>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<IIpcEventPublisher>(),
id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)));
// The layer's registration follows the ledger (P4 PR-2, 12_BUILD §The Vulkan layer is not registered at
// install time): the same manifest and key --register-vklayer writes, reconciled after every consent change
@@ -163,6 +211,8 @@ internal static class AgentServices
{
RulesSeedOutcome outcome = await new RulesSeeder(new FileSystemRulesStore()).EnsureSeededAsync(ct).ConfigureAwait(false);
sp.GetRequiredService<DetectionSweep>().RequestNow();
// And the anti-cheat pre-scan: new rules may name a game the library already holds (2026-09-25).
sp.GetRequiredService<AntiCheatPreScanSweep>().RequestNow();
return outcome.ToString();
},
// P3 PR-4 (D14): the reviewed disclosure this Agent stamps against, and its own clock for the stamp.
@@ -170,7 +220,10 @@ internal static class AgentServices
TimeProvider.System,
sp.GetRequiredService<VkLayerReconciler>(),
// P4 PR-7: the on-demand retention sweep, over the Agent's own settings read and its own blob tables.
ct => new RetentionSweep(sp.GetRequiredService<ISessionRepository>(), sp.GetRequiredService<RegisteredSettings>()).RunAsync(ct)));
ct => new RetentionSweep(sp.GetRequiredService<ISessionRepository>(), sp.GetRequiredService<RegisteredSettings>()).RunAsync(ct),
sp.GetRequiredService<ExecutableRelocator>(),
// beta.8: an executable that cannot run as x64 is refused before anything is scanned or stamped.
new PeArchitectureSource()));
services.AddSingleton<IIpcRequestHandler>(static sp => new AgentRequestHandler(
AgentIdentityFactory.OfThisProcess(sp.GetRequiredService<AgentPaths>().VkLayerDirectory),
TelemetryDescriptor(),
@@ -190,7 +243,9 @@ internal static class AgentServices
sp.GetRequiredService<IExecutableIdentitySource>(),
new OrchestratorOptions { PayloadPath = AgentPaths.Payload },
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<ILaunchRecorderFactory>()));
sp.GetRequiredService<ILaunchRecorderFactory>(),
sp.GetRequiredService<ExecutableRelocator>(),
sp.GetRequiredService<LatestProcessSnapshot>()));
services.AddSingleton<ILaunchRecorderFactory, AgentLaunches>();
}
@@ -0,0 +1,61 @@
using System.Data.Common;
using FrameLedger.Application.AntiCheat;
using Microsoft.Extensions.Hosting;
using Serilog;
namespace FrameLedger.Agent.Hosting;
/// <summary>
/// <c>--serve</c> (beta.8, 2026-09-25): the anti-cheat pre-scan of the library on its own background task. One pass at
/// start, then one every <see cref="Interval"/>, and one as soon as <c>UpdateRules</c> re-seeds the rules file
/// (<see cref="AntiCheatPreScanSweep.RequestNow"/>). It reads executables' paths, install folders and the stores' own
/// files, and writes the pre-scan's hook-state columns of <c>games</c>; it never opens a game's process
/// (<c>19_SAFETY</c> §What a finding does to the game, CLAUDE.md rule 4).
/// </summary>
/// <remarks>
/// Its own task, like <see cref="DetectionHostedService"/>'s, because the guard's directory walk blocks on file I/O.
/// A pass that throws is logged and retried on the next tick rather than ending the service: a game's folder going away
/// mid-walk is ordinary, a busy ledger is a retry, and a service that throws stops the Agent's host.
/// </remarks>
internal sealed class AntiCheatPreScanHostedService(AntiCheatPreScanSweep sweep) : BackgroundService
{
/// <summary>The idle cadence, the detection sweep's: a game the App just added is scanned within it.</summary>
public static readonly TimeSpan Interval = TimeSpan.FromSeconds(15);
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
Log.Information("prescan: scanning the library for anti-cheat every {Seconds} s, and on every rules update", Interval.TotalSeconds);
while (!stoppingToken.IsCancellationRequested)
{
try
{
AntiCheatPreScanReport r = await sweep.SweepOnceAsync(stoppingToken).ConfigureAwait(false);
// Said when something happened: a pass over an unchanged library scans nothing and says nothing.
if (r.Scanned > 0 || r.RulesUnusable)
{
Log.Information("prescan: scanned {Scanned} — anti-cheat {Found}, clean {Clean}, could not verify {Unverified}; blocked {Blocked}, current {Current}{Rules}",
r.Scanned, r.Found, r.Clean, r.Unverified, r.Blocked, r.Current, r.RulesUnusable ? ", rules unusable" : string.Empty);
}
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
break;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidOperationException or DbException)
{
Log.Warning(ex, "prescan: pass did not complete; retrying on the next tick");
}
try
{
await sweep.WaitAsync(Interval, stoppingToken).ConfigureAwait(false);
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
break;
}
}
Log.Information("prescan: stopped");
}
}
@@ -1,3 +1,4 @@
using System.Data.Common;
using FrameLedger.Application.Detection;
using FrameLedger.Application.Vulkan;
using Microsoft.Extensions.Hosting;
@@ -15,7 +16,9 @@ namespace FrameLedger.Agent.Hosting;
/// Its own task because <c>GameFileProbe</c> blocks on file I/O (a bounded directory walk, an 8 MB strings pass):
/// the orchestrator's 1 Hz poll must not wait on it, and a session's drain must never share a thread with it.
/// A sweep that throws is logged and retried on the next tick rather than ending the service — a game's
/// directory going away mid-walk is ordinary, and one bad game must not stop the scan of the rest.
/// directory going away mid-walk is ordinary, and one bad game must not stop the scan of the rest. A database error
/// is one of those since 2026-09-23: the sweep writes rows (a relocation, a merge), a service that throws stops the
/// Agent's host (the Generic Host's default), and a busy or locked ledger is a retry, not a reason to stop capturing.
/// </remarks>
internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconciler layer) : BackgroundService
{
@@ -25,17 +28,22 @@ internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconc
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
Log.Information("detect: sweeping the library every {Seconds} s, and on every rules update", Interval.TotalSeconds);
DetectionSweepReport? previous = null;
while (!stoppingToken.IsCancellationRequested)
{
try
{
DetectionSweepReport r = await sweep.SweepOnceAsync(stoppingToken).ConfigureAwait(false);
if (r.Scanned > 0 || r.Unreadable > 0 || r.RulesUnusable)
// Said when something happened or changed (2026-09-23): an unreadable entry used to repeat this line every
// 15 s — 5,760 a day — with nothing new in it.
if (r.Scanned > 0 || r.Relocated > 0 || r.RulesUnusable || (r.Unreadable > 0 && r.Unreadable != previous?.Unreadable))
{
Log.Information("detect: sweep scanned {Scanned}, current {Current}, unreadable {Unreadable}{Rules}",
r.Scanned, r.Current, r.Unreadable, r.RulesUnusable ? ", rules unusable" : string.Empty);
}
previous = r;
// The layer follows the ledger after every sweep (P4 PR-2): a Vulkan fact that arrived after the
// consent, and the crash policy's auto-disable, both converge here within one interval.
_ = await layer.ReconcileAsync(stoppingToken).ConfigureAwait(false);
@@ -44,7 +52,7 @@ internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconc
{
break;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidOperationException)
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidOperationException or DbException)
{
Log.Warning(ex, "detect: sweep did not complete; retrying on the next tick");
}
@@ -14,19 +14,30 @@ namespace FrameLedger.Agent.Hosting;
/// a session somebody lost, and it becomes an <c>interrupted</c> row before any new session can write beside
/// it. Then the orchestrator polls until the host stops; its sessions finalize inside the host's shutdown
/// grace, and one that does not make it leaves its <c>.partial</c> for the next start — the same rule.
/// <b>Nothing recovery does can keep the watcher from starting (2026-09-23)</b>: the host's default for a background
/// service that throws is to stop the whole Agent, so a file recovery could not finalize would have stopped every start
/// after it. <see cref="PartialRecovery"/> no longer throws; the guard here is for what it cannot foresee.
/// </remarks>
internal sealed class WatcherHostedService(PartialRecovery recovery, CaptureOrchestrator orchestrator) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
IReadOnlyList<RecoveryOutcome> recovered = await recovery.RecoverAsync(stoppingToken).ConfigureAwait(false);
Log.Information("recover: {Count} pending .partial file(s)", recovered.Count);
foreach (RecoveryOutcome o in recovered)
try
{
Log.Information("recover: {Guid} {Status} {Detail}", o.SessionGuid.ToString("N"), o.Status, o.Detail);
IReadOnlyList<RecoveryOutcome> recovered = await recovery.RecoverAsync(stoppingToken).ConfigureAwait(false);
Log.Information("recover: {Count} pending .partial file(s)", recovered.Count);
foreach (RecoveryOutcome o in recovered)
{
Log.Information("recover: {Guid} {Status} {Detail}", o.SessionGuid.ToString("N"), o.Status, o.Detail);
}
}
catch (Exception ex) when (ex is not OperationCanceledException and not OutOfMemoryException)
{
Log.Warning(ex, "recover: did not complete; the watcher starts anyway and the files stay for the next start");
}
Log.Information("serve: watching the games table at 1 Hz; hooking only where a game is enabled and consented");
Log.Information("serve: watching the games table at 1 Hz; hooking only where a game is enabled and consented ({Elevation}, pid {Pid})",
Environment.IsPrivilegedProcess ? "elevated" : "not elevated", Environment.ProcessId);
await orchestrator.RunAsync(stoppingToken).ConfigureAwait(false);
Log.Information("serve: stopped");
}
+119 -12
View File
@@ -9,6 +9,9 @@
// The Agent is the sole owner of %LOCALAPPDATA%\FrameLedger (§S18 blocker 3, ratified) and the only
// thing that may write there; `--data-dir` exists only under `--console` (HANDOFF §P2 decision D6).
//
// One process per data folder runs the capturing verbs (--serve, capture, launch, recover): Infrastructure.Startup's
// AgentInstanceLock, claimed before logging, and a second exits 10 (2026-09-17 — beta.1 ran four Agents at once).
//
// The maintenance flags (P3 PR-8b) — --register-vklayer, --unregister-vklayer, --install-task, --uninstall-task —
// run over the product directory and exit; --diag is the App's (10_LOGGING) and answers "not implemented", exit 2.
@@ -20,6 +23,7 @@ using FrameLedger.Application.Rules;
using FrameLedger.Infrastructure.Diagnostics;
using FrameLedger.Infrastructure.Persistence;
using FrameLedger.Infrastructure.Rules;
using FrameLedger.Infrastructure.Startup;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Serilog;
@@ -32,6 +36,7 @@ internal static class Program
private const int _exitUsage = 1;
private const int _exitNotImplemented = 2;
private const int _exitRulesFailed = 3;
private const int _exitLedgerRefused = 7;
private static int _crashReported;
@@ -40,19 +45,18 @@ internal static class Program
ArgumentNullException.ThrowIfNull(args);
AgentCommandLine cmd = AgentCommandLine.Parse(args);
if (cmd.Error is not null)
if (AnswerWithoutLogging(cmd) is { } answered)
{
AgentConsole.Problem(cmd.Error);
return _exitUsage;
}
if (cmd.Verb == AgentVerb.NotImplemented)
{
AgentConsole.Problem($"{cmd.Flag}: not this binary's — FrameLedger.exe --diag writes the report (10_LOGGING §Diagnostics extras)");
return _exitNotImplemented;
return answered;
}
AgentPaths paths = cmd.DataDirectory is { } dir ? new AgentPaths(Path.GetFullPath(dir)) : AgentPaths.Default;
using AgentInstanceLock? claim = ClaimDataDirectory(cmd.Verb, paths, out bool heldElsewhere);
if (heldElsewhere)
{
return AgentInstanceLock.ExitHeldElsewhere;
}
ConfigureLogging(paths);
HookCrashHandlers(paths);
@@ -69,10 +73,14 @@ internal static class Program
return _exitRulesFailed;
}
LedgerDatabase db = await LedgerDatabase.OpenAsync(paths.Database).ConfigureAwait(false);
LedgerDatabase? db = await OpenLedgerOrSayWhyAsync(cmd.Verb, paths).ConfigureAwait(false);
if (db is null)
{
return cmd.Verb == AgentVerb.DbPath ? _exitOk : _exitLedgerRefused;
}
await using (db.ConfigureAwait(false))
{
Log.Information("ledger: {Path} (schema {Schema}, migration {Migration})", db.Path, db.SchemaVersion, db.Migration);
return cmd.Verb switch
{
AgentVerb.Serve => await ServeAsync(db, paths).ConfigureAwait(false),
@@ -95,11 +103,106 @@ internal static class Program
}
}
/// <summary>A usage error or a flag this binary does not implement is answered before any file is touched.</summary>
private static int? AnswerWithoutLogging(AgentCommandLine cmd)
{
if (cmd.Verb == AgentVerb.WriteCrashDump)
{
// Before logging, rules and the ledger: the crashed parent still holds the day's log file, and a helper that
// waited on anything the parent holds would be the deadlock it exists to avoid.
return ParentDump.Run(cmd.CrashDumpFile!, AgentConsole.Problem);
}
if (cmd.Error is not null)
{
AgentConsole.Problem(cmd.Error);
return _exitUsage;
}
if (cmd.Verb == AgentVerb.NotImplemented)
{
AgentConsole.Problem($"{cmd.Flag}: not this binary's — FrameLedger.exe --diag writes the report (10_LOGGING §Diagnostics extras)");
return _exitNotImplemented;
}
return null;
}
/// <summary>
/// The verbs that only print open the ledger read-only — no migration, no write — so that running one against a
/// ledger at another schema changes nothing on disk (2026-09-16: <c>sessions</c> against the owner's own ledger
/// applied two scripts to it). Every other verb is a writer and opens read-write, migrating as before.
/// </summary>
internal static bool PrintsOnly(AgentVerb verb) =>
verb is AgentVerb.Sessions or AgentVerb.ConsentList or AgentVerb.KillSwitchStatus or AgentVerb.DbPath;
/// <summary>
/// The verbs that inject, read a ring or finalize sessions: one process per data folder may run them (2026-09-17). The
/// others (consent, games, the kill switch, the maintenance flags, the read-only verbs) run beside a serving Agent, as
/// the App's own <c>--install-task</c> does.
/// </summary>
internal static bool Captures(AgentVerb verb) =>
verb is AgentVerb.Serve or AgentVerb.Capture or AgentVerb.Launch or AgentVerb.Recover;
private static AgentInstanceLock? ClaimDataDirectory(AgentVerb verb, AgentPaths paths, out bool heldElsewhere)
{
heldElsewhere = false;
if (!Captures(verb))
{
return null;
}
AgentInstanceLock? claim = AgentInstanceLock.TryAcquire(paths.DataDirectory);
if (claim is null)
{
// Before logging, rules and the ledger: the Agent holding the folder holds the day's log file too, so a second one
// leaves nothing behind but this line and its exit code, which the App's log records when the App started it.
heldElsewhere = true;
AgentConsole.Problem($"another FrameLedger Agent is already capturing for {paths.DataDirectory}; this one exits (exit {AgentInstanceLock.ExitHeldElsewhere})");
}
return claim;
}
/// <summary>
/// Null when a print verb refuses the ledger — at another schema, or not there — said on the console and in the log
/// rather than as a crash: nothing about this machine is broken.
/// </summary>
private static async Task<LedgerDatabase?> OpenLedgerOrSayWhyAsync(AgentVerb verb, AgentPaths paths)
{
if (verb == AgentVerb.DbPath)
{
// Prints a path; opens nothing. A machine with no ledger yet still has an answer, and the verb never reaches
// ConsoleVerbs because the answer is complete here.
AgentConsole.Line(paths.Database);
return null;
}
try
{
LedgerDatabase db = PrintsOnly(verb)
? await LedgerDatabase.OpenReadOnlyAsync(paths.Database).ConfigureAwait(false)
: await LedgerDatabase.OpenAsync(paths.Database, diagnostics: static line => Log.Information("{Line}", line)).ConfigureAwait(false);
Log.Information("ledger: {Path} (schema {Schema}, migration {Migration}{ReadOnly})", db.Path, db.SchemaVersion, db.Migration,
db.IsReadOnly ? ", read-only" : string.Empty);
return db;
}
catch (Exception ex) when (ex is LedgerSchemaException or FileNotFoundException)
{
AgentConsole.Problem(ex.Message);
Log.Warning("ledger: {Message}", ex.Message);
return null;
}
}
private static void ConfigureLogging(AgentPaths paths)
{
Directory.CreateDirectory(paths.Logs);
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Information()
// The host's own lines reach this file since 2026-09-23 (ServeAsync's AddSerilog): its warnings and errors —
// a background service that stopped the host — not its start/stop chatter.
.MinimumLevel.Override("Microsoft", Serilog.Events.LogEventLevel.Warning)
.WriteTo.File(Path.Combine(paths.Logs, "agent-.log"), formatProvider: System.Globalization.CultureInfo.InvariantCulture,
rollingInterval: RollingInterval.Day, retainedFileCountLimit: 14)
.CreateLogger();
@@ -128,7 +231,7 @@ internal static class Program
}
Log.Fatal(exception, "agent: unhandled exception ({Source}); the Agent exits", source);
string? dump = CrashDumpWriter.TryWrite(paths.CrashDumps, "agent", DateTimeOffset.UtcNow, static line => Log.Warning("{Line}", line));
string? dump = CrashDumpWriter.TryWrite(paths.CrashDumps, "agent", DateTimeOffset.UtcNow, Environment.ProcessPath, static line => Log.Warning("{Line}", line));
Log.Information("agent: crash dump {Dump}", dump ?? "not written");
}
@@ -136,12 +239,16 @@ internal static class Program
private static async Task<int> ServeAsync(LedgerDatabase db, AgentPaths paths)
{
HostApplicationBuilder builder = Host.CreateApplicationBuilder();
// The host's log into agent-*.log (2026-09-23). A background service that threw stopped the host with nothing in
// the file: the Generic Host logs that through Microsoft.Extensions.Logging, which was never routed here.
builder.Services.AddSerilog();
// Before the composition, so its TryAdd keeps this one: Shutdown over the pipe stops the host (PR-1b).
builder.Services.AddSingleton<IAgentLifetime, HostAgentLifetime>();
builder.Services.AddFrameLedgerAgent(db, paths);
builder.Services.AddHostedService<WatcherHostedService>();
// The static detection sweep (P4 PR-1, 05_DETECTION §Caching): its own task, because the probe blocks on file I/O.
builder.Services.AddHostedService<DetectionHostedService>();
builder.Services.AddHostedService<AntiCheatPreScanHostedService>();
// The pipe (07_IPC §C), the product's UI channel: --serve only, never under --console (P3 PR-1).
builder.Services.AddHostedService<PipeServerHostedService>();
// Finalize's grace on shutdown (04_CAPTURE §Threading model): a session that does not make it leaves
+90 -18
View File
@@ -38,7 +38,7 @@ public partial class App : System.Windows.Application
{
/// <summary><c>10_LOGGING</c> §Crash handling (P4 PR-9): Fatal, the minidump, the crash dialog offering the bug report.</summary>
private readonly CrashReporter _crashes = new(
static () => CrashDumpWriter.TryWrite(UiPaths.CrashDumps, "ui", DateTimeOffset.UtcNow, static line => Log.Warning("{Line}", line)),
static () => CrashDumpWriter.TryWrite(UiPaths.CrashDumps, "ui", DateTimeOffset.UtcNow, CrashDumper, static line => Log.Warning("{Line}", line)),
CrashDialog.AskToReport,
static () =>
{
@@ -47,7 +47,13 @@ public partial class App : System.Windows.Application
return Services.GetRequiredService<BugReportFlow>().RunAsync();
});
/// <summary>The crash-dump helper: the Agent binary beside the App dumps this process from outside (<c>10_LOGGING</c> §Crash handling).</summary>
private static string CrashDumper => Path.Combine(AppContext.BaseDirectory, "FrameLedger.Agent.exe");
private IHost? _host;
/// <summary>This process's claim on the data folder (<see cref="SingleInstance"/>); null under <c>--diag</c> and in tests.</summary>
internal SingleInstance? Instance { get; init; }
private LedgerDatabase? _db;
private Task? _run;
@@ -85,24 +91,45 @@ public partial class App : System.Windows.Application
int exitCode = 0;
try
{
_db = await LedgerDatabase.OpenAsync(UiPaths.Database).ConfigureAwait(true);
_db = await LedgerDatabase.OpenAsync(UiPaths.Database, diagnostics: static line => Log.Information("{Line}", line)).ConfigureAwait(true);
var store = new SqliteSettingsStore(_db);
var appearance = new AppearanceSettings(store);
await appearance.LoadAsync().ConfigureAwait(true);
ApplyCulture(appearance.Language);
var registered = new RegisteredSettings(store);
LoggingLevel.SetDebug(await registered.GetBooleanAsync(SettingsRegistry.LogDebug).ConfigureAwait(true));
FpsDecimals.Two = await registered.GetBooleanAsync(SettingsRegistry.UiFpsDecimals).ConfigureAwait(true);
var closePolicy = new WindowClosePolicy { MinimizeToTray = await registered.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true) };
_host = BuildHost(_db, appearance, registered, closePolicy);
await _host.StartAsync().ConfigureAwait(true);
Log.Information("ui: started ({Version}), ledger {Ledger}", UiIdentity.Version, UiPaths.Database);
await _host.WaitForShutdownAsync().ConfigureAwait(true);
// A second start of the App hands over to this one: bring the window forward, from the tray too.
if (Instance is not null)
{
// Captured HERE, on the dispatcher: the event arrives on a thread-pool thread and is posted back.
IHost host = _host;
var ui = new UiThread();
Instance.RevealRequested += (_, _) => ui.Post(() =>
{
Log.Information("ui: another start handed over to this instance; revealing the window");
host.Services.GetRequiredService<ShellHost>().Reveal();
});
}
await WaitForStopRequestAsync(_host).ConfigureAwait(true);
}
catch (Exception ex) when (ex is not OutOfMemoryException)
{
Log.Fatal(ex, "ui: the run ended in an exception");
exitCode = 1;
// 10_LOGGING §Crash handling: a start that fails is said on screen, not only in the log. A crash the dispatcher
// already reported has had its dialog.
if (!_crashes.Crashed)
{
StartupFailureDialog.Show(ex, UiPaths.Logs);
}
}
finally
{
@@ -128,7 +155,8 @@ public partial class App : System.Windows.Application
var values = new Dictionary<string, string>(StringComparer.Ordinal);
try
{
LedgerDatabase db = await LedgerDatabase.OpenAsync(UiPaths.Database).ConfigureAwait(true);
// Read-only: a diagnostic run against a ledger at another schema must report it, not migrate it (2026-09-16).
LedgerDatabase db = await LedgerDatabase.OpenReadOnlyAsync(UiPaths.Database).ConfigureAwait(true);
await using (db.ConfigureAwait(true))
{
schema = db.SchemaVersion;
@@ -144,7 +172,17 @@ public partial class App : System.Windows.Application
Log.Warning(ex, "diag: the ledger could not be opened; settings are reported at their defaults");
}
string report = DiagReport.Build(UiIdentity.Version, UiPaths.DataDirectory, UiPaths.Logs, schema, values, new AgentLauncher().CanLaunch, now);
Application.Persistence.HardwareSnapshot? hardware = null;
try
{
hardware = new Infrastructure.Recording.HardwareSnapshotSource(new Infrastructure.Telemetry.DxgiAdapters()).Take();
}
catch (Exception ex) when (ex is not OutOfMemoryException)
{
Log.Warning(ex, "diag: the hardware could not be read; its lines are n/a");
}
string report = DiagReport.Build(UiIdentity.Version, UiPaths.DataDirectory, UiPaths.Logs, schema, values, new AgentLauncher().CanLaunch, now, hardware);
string path = DiagReport.Write(UiPaths.Logs, report, now);
await Console.Out.WriteLineAsync(string.Format(CultureInfo.CurrentCulture, Strings.Diag_Written_Format, path)).ConfigureAwait(true);
Log.Information("ui: --diag written to {Path}", path);
@@ -158,6 +196,22 @@ public partial class App : System.Windows.Application
Shutdown(exitCode);
}
/// <summary>
/// Waits for a stop request ON the dispatcher, and stops nothing: <see cref="TearDownAsync"/> stops the host once,
/// from the UI thread. <c>WaitForShutdownAsync</c> resumed on the thread pool (it awaits with
/// <c>ConfigureAwait(false)</c>) and stopped the hosted services there, which is how the tray was disposed off its
/// thread on 0.1.0-beta.1 — and TearDownAsync then stopped every service a second time.
/// </summary>
private static async Task WaitForStopRequestAsync(IHost host)
{
IHostApplicationLifetime lifetime = host.Services.GetRequiredService<IHostApplicationLifetime>();
using var stopping = new SemaphoreSlim(0, 1);
using (lifetime.ApplicationStopping.Register(static state => ((SemaphoreSlim)state!).Release(), stopping))
{
await stopping.WaitAsync().ConfigureAwait(true);
}
}
private async Task TearDownAsync()
{
try
@@ -188,6 +242,12 @@ public partial class App : System.Windows.Application
CultureInfo.DefaultThreadCurrentUICulture = culture;
CultureInfo.CurrentUICulture = culture;
Strings.Culture = culture;
// THE SAFETY FAMILY TOO (2026-09-21). FrameLedger.Shared's Strings had no culture of its own and fell back to the
// thread's - and CurrentUICulture set inside this async start does not reach the dispatcher's later operations,
// so on an English Windows a Vietnamese UI showed the consent dialog and the refusal notices in English (the
// owner's screenshot, beta.3). An explicit culture does not depend on which thread asks.
Shared.Strings.Culture = culture;
}
private static IHost BuildHost(LedgerDatabase db, AppearanceSettings appearance, RegisteredSettings registered, WindowClosePolicy closePolicy)
@@ -209,16 +269,7 @@ public partial class App : System.Windows.Application
builder.Services.AddSingleton(closePolicy);
builder.Services.AddSingleton<IThemeApplier, WpfThemeApplier>();
// The Agent over the pipe (07_IPC §Client behavior): connect, start it when it is not there, tell the shell.
builder.Services.AddSingleton<IAgentLauncher, AgentLauncher>();
builder.Services.AddSingleton(static sp => new AgentConnection(
sp.GetRequiredService<IAgentLauncher>(),
static () => new PipeClient(),
new AgentConnectionOptions(),
UiIdentity.Version));
builder.Services.AddHostedService<AgentConnectionHostedService>();
builder.Services.AddSingleton<IAgentRequests>(static sp => sp.GetRequiredService<AgentConnection>());
builder.Services.AddSingleton<IAgentLink>(static sp => sp.GetRequiredService<AgentConnection>());
AddAgentLink(builder.Services);
// FR-2.1 (P3 PR-4): the consent dialog and the request it ends in; the toggle that opens it is the game page's (PR-5).
builder.Services.AddSingleton<IConsentPrompt, ConsentPrompt>();
@@ -250,6 +301,23 @@ public partial class App : System.Windows.Application
return builder.Build();
}
/// <summary>The Agent over the pipe (07_IPC §Client behavior): connect, start it when it is not there, tell the shell.</summary>
private static void AddAgentLink(IServiceCollection services)
{
services.AddSingleton<IAgentLauncher, AgentLauncher>();
services.AddSingleton(static sp => new AgentConnection(
sp.GetRequiredService<IAgentLauncher>(),
static () => new PipeClient(),
new AgentConnectionOptions(),
UiIdentity.Version));
services.AddHostedService<AgentConnectionHostedService>();
services.AddSingleton<IAgentRequests>(static sp => sp.GetRequiredService<AgentConnection>());
services.AddSingleton<IAgentLink>(static sp => sp.GetRequiredService<AgentConnection>());
// What the Agent runs right now (2026-09-23), for the pages rebuilt on every visit; built before the connection's
// first round by AgentConnectionHostedService, so it never misses a session.
services.AddSingleton(static sp => new LiveSessions(sp.GetRequiredService<IAgentLink>()));
}
/// <summary>
/// The library (P3 PR-5): the ports the pages read and write, the selection that travels between pages, and the
/// pickers, prompts and confirmations behind interfaces so the view models are testable without a window.
@@ -270,6 +338,9 @@ public partial class App : System.Windows.Application
// The session summary (P3 PR-6): the series loader over the ports, the exports' file picker, the window opener.
services.AddSingleton<IHardwareSnapshotRepository, SqliteHardwareSnapshotRepository>();
// Settings > System (2026-09-21): the same source the Agent stamps every session with, read for this PC now.
services.AddSingleton<Application.Recording.IHardwareSnapshotSource>(static _ => new Infrastructure.Recording.HardwareSnapshotSource(new Infrastructure.Telemetry.DxgiAdapters()));
services.AddTransient<SystemInfoViewModel>();
services.AddSingleton<Charts.SessionSeriesLoader>();
services.AddSingleton<IFileSaver, FileSaver>();
services.AddSingleton<ISessionSummaryOpener, SessionSummaryOpener>();
@@ -280,13 +351,14 @@ public partial class App : System.Windows.Application
services.AddSingleton<IRunAtLogon, RunAtLogonRegistry>();
services.AddSingleton<SafetyNotices>();
services.AddSingleton(static _ => new LogTail(UiPaths.Logs));
services.AddSingleton(static sp => new BugBundleBuilder(UiPaths.Logs, sp.GetRequiredService<RegisteredSettings>(), crashDumpDirectory: UiPaths.CrashDumps));
services.AddSingleton(static sp => new BugBundleBuilder(UiPaths.Logs, sp.GetRequiredService<RegisteredSettings>(), crashDumpDirectory: UiPaths.CrashDumps, redactor: LogRedactor.ForCurrentUser()));
// The bug report's steps 3-4 and the shell's Export (P4 PR-3): the preview dialog, the browser, the clipboard,
// the flow over them, the session the shell exports, and the CSV/JSON service the summary window's writers serve.
services.AddSingleton<IUrlOpener, ShellUrlOpener>();
services.AddSingleton<IClipboard, WpfClipboard>();
services.AddSingleton<IBugReportPreview, BugReportPreviewPrompt>();
services.AddSingleton<LastSessionSummary>();
services.AddSingleton<BugReportFlow>();
services.AddSingleton<SessionSelection>();
services.AddSingleton<SessionExportService>();
@@ -328,7 +400,7 @@ public partial class App : System.Windows.Application
services.AddSingleton<IStoreLibrarySource>(static _ => new SteamLibrarySource());
services.AddSingleton<IStoreLibrarySource>(static _ => new GogLibrarySource());
services.AddSingleton<IStoreLibrarySource>(static _ => new EpicLibrarySource());
services.AddSingleton<IStoreLibrarySource>(static _ => new ItchLibrarySource());
services.AddSingleton<IStoreLibrarySource>(static _ => new ItchLibrarySource(log: static line => Serilog.Log.Information("{Line}", line)));
services.AddSingleton<IExecutableLocator, ExecutableLocator>();
services.AddSingleton<IExecutableIdentitySource, ExecutableIdentitySource>();
services.AddSingleton(static sp => new LibraryImporter(
@@ -369,7 +441,7 @@ public partial class App : System.Windows.Application
AppDomain.CurrentDomain.UnhandledException += static (_, args) =>
{
Log.Fatal(args.ExceptionObject as Exception, "ui: unhandled exception (AppDomain, terminating {Terminating})", args.IsTerminating);
string? dump = CrashDumpWriter.TryWrite(UiPaths.CrashDumps, "ui", DateTimeOffset.UtcNow, static line => Log.Warning("{Line}", line));
string? dump = CrashDumpWriter.TryWrite(UiPaths.CrashDumps, "ui", DateTimeOffset.UtcNow, CrashDumper, static line => Log.Warning("{Line}", line));
Log.Information("ui: crash dump {Dump}", dump ?? "not written");
Log.CloseAndFlush();
};
@@ -57,6 +57,25 @@ public sealed record ChartPalette(
return new ChartPalette(c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7], c[8], c[9], c[10], c[11], c[12]);
}
/// <summary>The colour a key names — how a chart that assigns palette entries to series by name reads them (<c>SensorsChart</c>).</summary>
public Color ByKey(string key) => key switch
{
"Chart_Figure" => Figure,
"Chart_Data" => Data,
"Chart_Axis" => Axis,
"Chart_Grid" => Grid,
"Chart_Native" => Native,
"Chart_Displayed" => Displayed,
"Chart_Stutter" => Stutter,
"Chart_StutterPso" => StutterPso,
"Chart_Sensor" => Sensor,
"Chart_SensorSecondary" => SensorSecondary,
"Chart_Segment" => Segment,
"Chart_Histogram" => Histogram,
"Chart_Percentile" => Percentile,
_ => throw new ArgumentOutOfRangeException(nameof(key), key, "not a chart palette key"),
};
private static ChartPalette Load(ApplicationTheme theme)
{
string file = theme == ApplicationTheme.Light ? "ChartPalette.Light.xaml" : "ChartPalette.Dark.xaml";
+35
View File
@@ -32,6 +32,41 @@ public static class ChartTheme
plot.Legend.FontColor = p.Axis;
}
/// <summary>
/// Save the plot as a PNG with an OPAQUE background (beta.8): on screen the figure is transparent over its card, but an
/// exported image has no card behind it, and a viewer painted its own colour under the theme's text — white axis labels
/// on a white page. The window's colour is painted for the file and the plot restored.
/// </summary>
public static void SavePng(Plot plot, string path, int width, int height)
{
ArgumentNullException.ThrowIfNull(plot);
ArgumentException.ThrowIfNullOrWhiteSpace(path);
Color figure = plot.FigureBackground.Color;
Color data = plot.DataBackground.Color;
Color window = ApplicationThemeManager.GetAppTheme() == ApplicationTheme.Light ? Color.FromHex("#F3F3F3") : Color.FromHex("#202020");
try
{
plot.FigureBackground.Color = Over(figure, window);
plot.DataBackground.Color = Over(data, Over(figure, window));
plot.SavePng(path, width, height);
}
finally
{
plot.FigureBackground.Color = figure;
plot.DataBackground.Color = data;
}
}
/// <summary>Source-over: <paramref name="top"/> composited on an opaque <paramref name="under"/>.</summary>
internal static Color Over(Color top, Color under)
{
double a = top.A / 255.0;
return new Color(
(byte)Math.Round((top.R * a) + (under.R * (1 - a))),
(byte)Math.Round((top.G * a) + (under.G * (1 - a))),
(byte)Math.Round((top.B * a) + (under.B * (1 - a))));
}
/// <summary>Registers a control so a theme change re-applies and refreshes it (weakly held; a closed window is forgotten).</summary>
public static void Attach(WpfPlot control)
{
@@ -44,8 +44,10 @@ public partial class CompareChart : UserControl
if (DrawnCurves > 0)
{
plot.Axes.SetLimitsX(0, 100);
// The percentile axis is 0–100 whatever the data: AutoScale first, then the X limits (beta.8 — the other way
// round, AutoScale undid them).
plot.Axes.AutoScale();
plot.Axes.SetLimitsX(0, 100);
plot.ShowLegend(Alignment.UpperRight);
}
@@ -1,10 +1,15 @@
<UserControl x:Class="FrameLedger.App.Charts.DistributionChart"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:sp="clr-namespace:ScottPlot.WPF;assembly=ScottPlot.WPF"
MinHeight="240">
<!-- FR-5.1: the FPS histogram and the percentile curve, side by side. -->
<!-- FR-5.1: the FPS histogram and the percentile curve, side by side; the note says what the histogram's range left out (beta.8). -->
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="*" />
<RowDefinition Height="Auto" />
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="12" />
@@ -12,5 +17,6 @@
</Grid.ColumnDefinitions>
<sp:WpfPlot x:Name="Histogram" Grid.Column="0" />
<sp:WpfPlot x:Name="Percentiles" Grid.Column="2" />
<ui:TextBlock x:Name="Note" Grid.Row="1" Grid.ColumnSpan="3" Margin="0,4,0,0" Appearance="Tertiary" TextWrapping="Wrap" Visibility="Collapsed" />
</Grid>
</UserControl>
@@ -1,3 +1,5 @@
using System.Globalization;
using System.Windows;
using System.Windows.Controls;
using ScottPlot;
using ScottPlot.Plottables;
@@ -7,8 +9,10 @@ namespace FrameLedger.App.Charts;
/// <summary>
/// FR-5.1's distribution: a histogram of instantaneous FPS over application frames, and the percentile curve —
/// FPS at each percentile of frametime under <c>03_METRICS</c>' linear method (<c>Domain.Metrics.Percentile</c>),
/// so the 1% and 0.1% lows on the stat cards are two points on this curve.
/// so the 1% and 0.1% lows on the stat cards are two points on this curve, marked where the session has the frames for
/// them (<see cref="PercentileCurve"/>).
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public partial class DistributionChart : UserControl
{
private const int _bins = 60;
@@ -22,38 +26,46 @@ public partial class DistributionChart : UserControl
public ScottPlot.Plot HistogramPlot => Histogram.Plot;
/// <summary>The percentile plot, for a test's look at its axis.</summary>
public ScottPlot.Plot PercentilePlot => Percentiles.Plot;
public void Show(SessionSeries? series)
{
DrawHistogram(series);
int outside = DrawHistogram(series);
DrawPercentiles(series);
Note.Text = outside > 0 ? string.Format(CultureInfo.CurrentCulture, Strings.Chart_Note_OutsideRange_Format, outside) : string.Empty;
Note.Visibility = outside > 0 ? Visibility.Visible : Visibility.Collapsed;
}
private void DrawHistogram(SessionSeries? series)
/// <summary>Draws the histogram; the frames its range left out.</summary>
private int DrawHistogram(SessionSeries? series)
{
ScottPlot.Plot plot = Histogram.Plot;
plot.Clear();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Fps);
plot.YLabel(Strings.Chart_Axis_Count);
int outside = 0;
if (series is { AppFrameTimesMs.Length: > 1 })
{
double[] fps = [.. series.AppFrameTimesMs.Where(static f => f > 0).Select(static f => 1000.0 / f)];
if (fps.Length > 1)
FpsHistogram histogram = FpsHistogram.Of(series.AppFrameTimesMs, _bins);
if (histogram.Centers.Length > 0)
{
var histogram = ScottPlot.Statistics.Histogram.WithBinCount(_bins, fps);
BarPlot bars = plot.Add.Bars(histogram.Bins, histogram.Counts.Select(static c => (double)c));
BarPlot bars = plot.Add.Bars(histogram.Centers, histogram.Counts);
bars.Color = ChartTheme.Current.Histogram;
foreach (Bar bar in bars.Bars)
{
bar.Size = histogram.FirstBinSize;
bar.Size = histogram.BinWidth;
bar.LineWidth = 0;
}
outside = histogram.Outside;
plot.Axes.AutoScale();
}
}
Histogram.Refresh();
return outside;
}
private void DrawPercentiles(SessionSeries? series)
@@ -66,11 +78,24 @@ public partial class DistributionChart : UserControl
if (series is { AppFrameTimesMs.Length: > 1 })
{
(double[] xs, double[] ys) = PercentileCurve.Of(series.AppFrameTimesMs);
Scatter line = plot.Add.ScatterLine(xs, ys, ChartTheme.Current.Percentile);
line.LineWidth = 2;
line.LegendText = Strings.Chart_Series_Percentile;
plot.Axes.SetLimitsX(0, 100);
if (xs.Length > 0)
{
Scatter line = plot.Add.ScatterLine(xs, ys, ChartTheme.Current.Percentile);
line.LineWidth = 2;
line.LegendText = Strings.Chart_Series_Percentile;
}
foreach ((double x, double fps, bool pointOne) in PercentileCurve.Lows(series.AppFrameTimesMs))
{
Scatter low = plot.Add.ScatterPoints(new[] { x }, new[] { fps }, ChartTheme.Current.Stutter);
low.MarkerSize = 7;
low.LegendText = pointOne ? Strings.Summary_Stat_P01Low : Strings.Summary_Stat_P1Low;
}
// The axis is 0–100 whatever the curve covers: AutoScale first, then the X limits (AutoScale afterwards undid them).
plot.Axes.AutoScale();
plot.Axes.SetLimitsX(0, 100);
plot.ShowLegend(Alignment.LowerLeft);
}
Percentiles.Refresh();
@@ -0,0 +1,54 @@
using FrameLedger.Domain.Metrics;
namespace FrameLedger.App.Charts;
/// <summary>
/// The distribution tab's histogram of instantaneous FPS over application frames (FR-5.1), binned over the 0.5th to the
/// 99.5th percentile and drawn at each bin's CENTRE (beta.8). Binned over min to max, one frame of a fraction of a
/// millisecond — a present that followed another by nothing — stretched the axis to thousands of FPS and squeezed every
/// real frame into two bars; and a bar is drawn centred on its position, where ScottPlot's bins are lower edges, so every
/// bar sat half a bin to the left of what it counted.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1819:Properties should not return arrays", Justification = "a data carrier for ScottPlot, which draws double[]")]
public sealed record FpsHistogram(double[] Centers, double[] Counts, double BinWidth, int Outside)
{
/// <summary>The share cut from each end before binning.</summary>
public const double TailFraction = 0.005;
public static FpsHistogram Of(IReadOnlyList<double> appFrameTimesMs, int bins = 60)
{
ArgumentNullException.ThrowIfNull(appFrameTimesMs);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(bins);
double[] fps = [.. appFrameTimesMs.Where(static f => f > 0).Select(static f => 1000.0 / f)];
if (fps.Length == 0)
{
return new FpsHistogram([], [], 0, 0);
}
IReadOnlyList<double> sorted = Percentile.Sorted(fps);
double lo = Percentile.Linear(sorted, TailFraction) ?? sorted[0];
double hi = Percentile.Linear(sorted, 1 - TailFraction) ?? sorted[^1];
if (hi - lo < 1e-9)
{
// Every frame at one rate: one bar, a frame per second wide, centred on it.
return new FpsHistogram([lo], [fps.Length], 1, 0);
}
double width = (hi - lo) / bins;
var counts = new double[bins];
int outside = 0;
foreach (double v in fps)
{
if (v < lo || v > hi)
{
outside++;
continue;
}
counts[Math.Min(bins - 1, (int)((v - lo) / width))]++;
}
double[] centers = [.. Enumerable.Range(0, bins).Select(b => lo + ((b + 0.5) * width))];
return new FpsHistogram(centers, counts, width, outside);
}
}
+11 -2
View File
@@ -1,8 +1,17 @@
<UserControl x:Class="FrameLedger.App.Charts.FrametimeChart"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:sp="clr-namespace:ScottPlot.WPF;assembly=ScottPlot.WPF"
MinHeight="260">
<!-- 08_UI §Session summary / FR-5.1: the frametime timeline, min/max decimated (FR-5.3); zoom and pan are ScottPlot's. -->
<sp:WpfPlot x:Name="Plot" />
<!-- 08_UI §Session summary / FR-5.1: the frametime timeline, min/max decimated (FR-5.3); zoom and pan are ScottPlot's.
The note above it says what the lines are not, when that is not obvious (beta.8). -->
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="*" />
</Grid.RowDefinitions>
<ui:TextBlock x:Name="Note" Grid.Row="0" Margin="0,0,0,4" Appearance="Tertiary" TextWrapping="Wrap" Visibility="Collapsed" />
<sp:WpfPlot x:Name="Plot" Grid.Row="1" />
</Grid>
</UserControl>
+107 -11
View File
@@ -1,3 +1,5 @@
using System.Globalization;
using System.Windows;
using System.Windows.Controls;
using ScottPlot;
using ScottPlot.Plottables;
@@ -5,13 +7,17 @@ using ScottPlot.Plottables;
namespace FrameLedger.App.Charts;
/// <summary>
/// The frametime timeline (FR-5.1, FR-5.3, FR-5.4, FR-5.5): the application-frame series by default, the
/// displayed (every present) series on request, stutter markers coloured by cause where the PSO count says so,
/// the segment ribbon as translucent spans, and the sensor overlay on the right axis. Series are min/max
/// decimated per draw; the raw arrays stay in the <see cref="SessionSeries"/>.
/// The frametime timeline (FR-5.1, FR-5.3, FR-5.4, FR-5.5): the application-frame series by default, every present on
/// request, stutter markers coloured by cause where the PSO count says so, the segment ribbon as translucent spans with
/// their settings named, and the sensor overlay on the right axis. Series are min/max decimated per draw; the raw arrays
/// stay in the <see cref="SessionSeries"/>.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public partial class FrametimeChart : UserControl
{
/// <summary>A segment narrower than this share of the axis keeps its shading and loses its label (the labels would overlap).</summary>
private const double _labelledSegmentShare = 0.12;
private SessionSeries? _series;
private bool _displayed;
private bool _sensors;
@@ -28,6 +34,9 @@ public partial class FrametimeChart : UserControl
/// <summary>How many points the last draw put on the axes (a test's window into the decimation).</summary>
public int DrawnPoints { get; private set; }
/// <summary>The note the last draw showed above the plot; empty when it had nothing to say.</summary>
public string NoteText => Note.Text;
public void Show(SessionSeries? series, bool displayed, bool sensors)
{
_series = series;
@@ -48,6 +57,37 @@ public partial class FrametimeChart : UserControl
Redraw();
}
/// <summary>
/// What the lines are not, when that is not obvious (beta.8): a session whose presents were all generated is charted as
/// presents; every present is timed at submission, which is not the display's cadence; and the overlay's sensors run ahead
/// of the frames past every gap the time axis closes up.
/// </summary>
internal static string NoteFor(SessionSeries? series, bool displayed, bool sensors)
{
if (series is null || series.Presents == 0)
{
return string.Empty;
}
var lines = new List<string>(2);
if (series.NoApplicationFrames)
{
lines.Add(Strings.Chart_Note_NoApplicationFrames);
}
else if (displayed && series.HasGenerated)
{
lines.Add(Strings.Chart_Note_PresentsTiming);
}
int gaps = series.Gap.Skip(1).Count(static g => g);
if (sensors && series.SensorsAligned && gaps > 0)
{
lines.Add(string.Format(CultureInfo.CurrentCulture, Strings.Chart_Note_GapsClosed_Format, gaps));
}
return string.Join(Environment.NewLine, lines);
}
private void Redraw()
{
ScottPlot.Plot plot = Plot.Plot;
@@ -56,6 +96,8 @@ public partial class FrametimeChart : UserControl
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Time);
plot.YLabel(Strings.Chart_Axis_Frametime);
Note.Text = NoteFor(_series, _displayed, _sensors);
Note.Visibility = Note.Text.Length > 0 ? Visibility.Visible : Visibility.Collapsed;
if (_series is null || _series.Presents == 0)
{
Plot.Refresh();
@@ -63,26 +105,33 @@ public partial class FrametimeChart : UserControl
}
ChartPalette p = ChartTheme.Current;
bool generating = _series.HasGenerated && !_series.NoApplicationFrames;
DrawSegments(plot, p);
if (_displayed && _series.HasGenerated)
if (_displayed && generating)
{
DrawSeries(plot, _series.TimesS, [.. _series.FrameTimesMs.Select(static f => (double)f)], p.Displayed, Strings.Chart_Series_Displayed);
DrawPresents(plot, p);
}
DrawSeries(plot, _series.AppTimesS, _series.AppFrameTimesMs, p.Native, Strings.Chart_Series_Native);
DrawSeries(plot, _series.AppTimesS, _series.AppFrameTimesMs, p.Native, generating ? Strings.Chart_Series_AppFrames : Strings.Chart_Series_Presents);
DrawStutter(plot, p);
if (_sensors)
if (_sensors && _series.SensorsAligned)
{
DrawSensors(plot, p);
}
plot.Axes.AutoScale();
LabelSegments(plot, p);
plot.ShowLegend(Alignment.UpperRight);
Plot.Refresh();
}
private void DrawSeries(ScottPlot.Plot plot, double[] xs, double[] ys, Color color, string label)
private void DrawSeries(ScottPlot.Plot plot, IReadOnlyList<double> xs, IReadOnlyList<double> ys, Color color, string label)
{
if (xs.Count == 0)
{
return;
}
(double[] dx, double[] dy) = Decimator.MinMax(xs, ys);
DrawnPoints += dx.Length;
SignalXY line = plot.Add.SignalXY(dx, dy, color);
@@ -90,6 +139,23 @@ public partial class FrametimeChart : UserControl
line.LegendText = label;
}
/// <summary>Every present but those after a gap, whose stored interval is 0 — not a frame, and it was drawn as a 0 ms one.</summary>
private void DrawPresents(ScottPlot.Plot plot, ChartPalette p)
{
var xs = new List<double>(_series!.Presents);
var ys = new List<double>(_series.Presents);
for (int i = 0; i < _series.Presents; i++)
{
if (!_series.Gap[i])
{
xs.Add(_series.TimesS[i]);
ys.Add(_series.FrameTimesMs[i]);
}
}
DrawSeries(plot, xs, ys, p.Displayed, Strings.Chart_Series_Displayed);
}
private void DrawStutter(ScottPlot.Plot plot, ChartPalette p)
{
if (_series?.Stutter is null)
@@ -152,6 +218,34 @@ public partial class FrametimeChart : UserControl
}
}
/// <summary>
/// Each segment's settings at its top-left corner (beta.8: the label was computed for every segment and drawn for none),
/// where the segment is wide enough to hold it. Placed after the axes are scaled, at their top.
/// </summary>
private void LabelSegments(ScottPlot.Plot plot, ChartPalette p)
{
if (_series is null || _series.Segments.Count < 2)
{
return;
}
AxisLimits limits = plot.Axes.GetLimits();
double width = limits.Right - limits.Left;
foreach (SegmentSpan segment in _series.Segments.Where(s => s.Label.Length > 0 && s.EndS - s.StartS >= width * _labelledSegmentShare))
{
Text label = plot.Add.Text(segment.Label, segment.StartS, limits.Top);
label.LabelFontSize = 11;
label.LabelFontColor = p.Axis;
label.LabelAlignment = Alignment.UpperLeft;
label.LabelOffsetX = 4;
label.LabelOffsetY = 4;
}
}
/// <summary>
/// GPU temperature and load on the right axis, over the frames' span only: the sensors sit on the frames' axis when the
/// blob said where the first present is (schema 0013), and ticks before it are the launch and the loading screen.
/// </summary>
private void DrawSensors(ScottPlot.Plot plot, ChartPalette p)
{
if (_series is null)
@@ -162,14 +256,16 @@ public partial class FrametimeChart : UserControl
IYAxis right = plot.Axes.Right;
right.Label.Text = Strings.Chart_Axis_Sensor;
int n = 0;
double end = _series.DurationS;
foreach (SensorSeries sensor in _series.Sensors.Where(static s => s.Name is "gpu_temp" or "gpu_load"))
{
if (sensor.TimesS.Length == 0)
int[] inside = [.. Enumerable.Range(0, sensor.TimesS.Length).Where(i => sensor.TimesS[i] >= 0 && sensor.TimesS[i] <= end)];
if (inside.Length == 0)
{
continue;
}
(double[] dx, double[] dy) = Decimator.MinMax(sensor.TimesS, sensor.Values, 1000);
(double[] dx, double[] dy) = Decimator.MinMax([.. inside.Select(i => sensor.TimesS[i])], [.. inside.Select(i => sensor.Values[i])], 1000);
DrawnPoints += dx.Length;
Scatter line = plot.Add.ScatterLine(dx, dy, n++ == 0 ? p.Sensor : p.SensorSecondary);
line.LineWidth = 1;
+63 -8
View File
@@ -2,9 +2,22 @@ using FrameLedger.Domain.Metrics;
namespace FrameLedger.App.Charts;
/// <summary>FPS at each percentile (0…100) of frametime, under <c>03_METRICS</c>' linear method — the distribution tab's curve and Compare's overlay.</summary>
/// <summary>
/// FPS at each percentile of frametime, under <c>03_METRICS</c>' linear method — the distribution tab's curve and Compare's
/// overlay — drawn only where the session has the frames to say it (beta.8).
/// </summary>
/// <remarks>
/// <b>A percentile is drawn when at least <see cref="FramesBeyond"/> frames lie beyond it on each side</b> — FR-4.8's rule
/// generalised: the 1% low (the 99th percentile) needs 1,000 frames and the 0.1% low (the 99.9th) 10,000, which is exactly
/// ten frames beyond each. The curve drew 0 to 100 whatever the count: its 100th point was the single worst frame, its 0th
/// the single shortest interval — thousands of FPS that set the axis for every other point — and its 99th was a 1% low the
/// stat card beside it refused to publish.
/// </remarks>
public static class PercentileCurve
{
/// <summary>Frames that must lie beyond a percentile, on each side, for it to be drawn.</summary>
public const int FramesBeyond = 10;
public static (double[] Xs, double[] Ys) Of(IReadOnlyList<double> appFrameTimesMs)
{
ArgumentNullException.ThrowIfNull(appFrameTimesMs);
@@ -14,15 +27,57 @@ public static class PercentileCurve
}
IReadOnlyList<double> sorted = Percentile.Sorted(appFrameTimesMs);
var xs = new double[101];
var ys = new double[101];
for (int i = 0; i <= 100; i++)
var xs = new List<double>(103);
var ys = new List<double>(103);
foreach (double p in Percents())
{
xs[i] = i;
double? ft = Percentile.Linear(sorted, i / 100.0);
ys[i] = ft is > 0 ? 1000.0 / ft.Value : 0;
if (Supported(sorted.Count, p) && Fps(sorted, p) is double fps)
{
xs.Add(p);
ys.Add(fps);
}
}
return (xs, ys);
return ([.. xs], [.. ys]);
}
/// <summary>The 1% and 0.1% lows as points on the curve (x 99 and 99.9), each only where the session has the frames for it.</summary>
public static IReadOnlyList<(double X, double Fps, bool PointOne)> Lows(IReadOnlyList<double> appFrameTimesMs)
{
ArgumentNullException.ThrowIfNull(appFrameTimesMs);
IReadOnlyList<double> sorted = Percentile.Sorted(appFrameTimesMs);
var lows = new List<(double, double, bool)>(2);
if (Supported(sorted.Count, 99) && Fps(sorted, 99) is double p1)
{
lows.Add((99, p1, false));
}
if (Supported(sorted.Count, 99.9) && Fps(sorted, 99.9) is double p01)
{
lows.Add((99.9, p01, true));
}
return lows;
}
/// <summary>At least <see cref="FramesBeyond"/> of <paramref name="frames"/> lie beyond <paramref name="percent"/> on each side.</summary>
public static bool Supported(int frames, double percent) =>
frames * Math.Min(percent, 100 - percent) / 100.0 >= FramesBeyond - 1e-9;
/// <summary>0, 0.1, 1 … 99, 99.9, 100 — in order, because the curve is drawn as a line through them.</summary>
private static IEnumerable<double> Percents()
{
yield return 0;
yield return 0.1;
for (int i = 1; i <= 99; i++)
{
yield return i;
}
yield return 99.9;
yield return 100;
}
private static double? Fps(IReadOnlyList<double> sorted, double percent) =>
Percentile.Linear(sorted, percent / 100.0) is > 0 and double ft ? 1000.0 / ft : null;
}
+85 -24
View File
@@ -5,12 +5,32 @@ using ScottPlot.Plottables;
namespace FrameLedger.App.Charts;
/// <summary>
/// The Sensors tab: GPU core / hotspot temperature and load / power on one plot (°C and % left, W right),
/// and VRAM on another — the game's own usage (the per-present <c>vram_proc</c> blob, a held 1 Hz sample)
/// and the adapter-wide figure (the <c>vram_adapter</c> sensor) as two differently-labelled series.
/// The Sensors tab: GPU core / hotspot temperature, load, CPU temperature and load on one plot (°C and % left) with the GPU's
/// power on a watt axis at the right, and memory on another — the game's own VRAM (the per-present <c>vram_proc</c> blob, a
/// held 1 Hz sample), the adapter-wide VRAM (the <c>vram_adapter</c> sensor) and the system's RAM as differently-labelled
/// series. Since beta.8 it draws a session that was not hooked too: its sensors are all it has.
/// </summary>
public partial class SensorsChart : UserControl
{
/// <summary>The temperatures-and-load plot's series, each with the palette key it is drawn in and whether it is on the watt axis.</summary>
internal static readonly IReadOnlyList<(string Series, string PaletteKey, bool Watts)> TempsPlot =
[
("gpu_temp", "Chart_Sensor", false),
("gpu_hotspot", "Chart_Stutter", false),
("gpu_load", "Chart_Native", false),
("gpu_power", "Chart_SensorSecondary", true),
("cpu_temp", "Chart_Percentile", false),
("cpu_load", "Chart_Displayed", false),
];
/// <summary>The memory plot's series and their palette keys; <c>vram_proc</c> is the per-present blob, the others sensors.</summary>
internal static readonly IReadOnlyList<(string Series, string PaletteKey)> MemoryPlot =
[
("vram_proc", "Chart_Displayed"),
("vram_adapter", "Chart_SensorSecondary"),
("ram_mb", "Chart_Percentile"),
];
public SensorsChart()
{
InitializeComponent();
@@ -20,27 +40,38 @@ public partial class SensorsChart : UserControl
public int DrawnSeries { get; private set; }
/// <summary>The temperatures plot, for a test's look at its axes.</summary>
public ScottPlot.Plot TempsPlotView => Temps.Plot;
public void Show(SessionSeries? series)
{
DrawnSeries = 0;
DrawTemps(series);
DrawVram(series);
DrawMemory(series);
}
/// <summary>The time axis says where its zero is: the first frame when the sensors sit on the frames' axis, the session's start otherwise.</summary>
internal static string TimeAxisLabel(SessionSeries? series) =>
series is { SensorsAligned: true, Presents: > 0 } ? Strings.Chart_Axis_TimeFromFirstFrame : Strings.Chart_Axis_TimeFromStart;
private void DrawTemps(SessionSeries? series)
{
ScottPlot.Plot plot = Temps.Plot;
plot.Clear();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Time);
plot.XLabel(TimeAxisLabel(series));
plot.YLabel(Strings.Chart_Axis_Sensor);
if (series is not null)
{
ChartPalette p = ChartTheme.Current;
Line(plot, series, "gpu_temp", Strings.Sensors_Series_GpuTemp, p.Sensor, null);
Line(plot, series, "gpu_hotspot", Strings.Sensors_Series_GpuHotspot, p.Stutter, null);
Line(plot, series, "gpu_load", Strings.Sensors_Series_GpuLoad, p.Native, null);
Line(plot, series, "gpu_power", Strings.Sensors_Series_GpuPower, p.SensorSecondary, plot.Axes.Right);
foreach ((string name, string key, bool watts) in TempsPlot)
{
if (Line(plot, series, name, Label(name), p.ByKey(key), watts ? plot.Axes.Right : null) && watts)
{
plot.Axes.Right.Label.Text = Strings.Sensors_Axis_Watts;
}
}
plot.Axes.AutoScale();
plot.ShowLegend(Alignment.UpperRight);
}
@@ -48,27 +79,19 @@ public partial class SensorsChart : UserControl
Temps.Refresh();
}
private void DrawVram(SessionSeries? series)
private void DrawMemory(SessionSeries? series)
{
ScottPlot.Plot plot = Vram.Plot;
plot.Clear();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Time);
plot.XLabel(TimeAxisLabel(series));
plot.YLabel(Strings.Sensors_Axis_Mb);
if (series is not null)
{
ChartPalette p = ChartTheme.Current;
if (series.VramProcMb is { Length: > 0 } proc)
{
int n = Math.Min(proc.Length, series.TimesS.Length);
(double[] xs, double[] ys) = Decimator.MinMax(series.TimesS[..n], [.. proc.Take(n).Select(static v => (double)v)], 1000);
Scatter line = plot.Add.ScatterLine(xs, ys, p.Displayed);
line.LineWidth = 1;
line.LegendText = Strings.Sensors_Series_VramProcess;
DrawnSeries++;
}
Line(plot, series, "vram_adapter", Strings.Sensors_Series_VramAdapter, p.SensorSecondary, null);
DrawProcessVram(plot, series, p.ByKey(MemoryPlot[0].PaletteKey));
Line(plot, series, "vram_adapter", Strings.Sensors_Series_VramAdapter, p.ByKey(MemoryPlot[1].PaletteKey), null);
Line(plot, series, "ram_mb", Strings.Sensors_Series_Ram, p.ByKey(MemoryPlot[2].PaletteKey), null);
plot.Axes.AutoScale();
plot.ShowLegend(Alignment.UpperRight);
}
@@ -76,12 +99,49 @@ public partial class SensorsChart : UserControl
Vram.Refresh();
}
private void Line(ScottPlot.Plot plot, SessionSeries series, string name, string label, Color color, IYAxis? axis)
/// <summary>
/// The game's own VRAM, per present on the frames' axis — a 0 is a present the sample did not reach (the record's zero,
/// SessionFinalizer.Series), never a reading, and is left out (beta.8).
/// </summary>
private void DrawProcessVram(ScottPlot.Plot plot, SessionSeries series, Color color)
{
if (series.VramProcMb is not { Length: > 0 } proc)
{
return;
}
int n = Math.Min(proc.Length, series.TimesS.Length);
int[] read = [.. Enumerable.Range(0, n).Where(i => proc[i] > 0)];
if (read.Length == 0)
{
return;
}
(double[] xs, double[] ys) = Decimator.MinMax([.. read.Select(i => series.TimesS[i])], [.. read.Select(i => (double)proc[i])], 1000);
Scatter line = plot.Add.ScatterLine(xs, ys, color);
line.LineWidth = 1;
line.LegendText = Strings.Sensors_Series_VramProcess;
DrawnSeries++;
}
private static string Label(string series) => series switch
{
"gpu_temp" => Strings.Sensors_Series_GpuTemp,
"gpu_hotspot" => Strings.Sensors_Series_GpuHotspot,
"gpu_load" => Strings.Sensors_Series_GpuLoad,
"gpu_power" => Strings.Sensors_Series_GpuPower,
"cpu_temp" => Strings.Sensors_Series_CpuTemp,
"cpu_load" => Strings.Sensors_Series_CpuLoad,
_ => series,
};
/// <summary>Draws one sensor series if the session has it; whether it did.</summary>
private bool Line(ScottPlot.Plot plot, SessionSeries series, string name, string label, Color color, IYAxis? axis)
{
SensorSeries? sensor = series.Sensors.FirstOrDefault(s => string.Equals(s.Name, name, StringComparison.Ordinal));
if (sensor is null || sensor.TimesS.Length == 0)
{
return;
return false;
}
(double[] xs, double[] ys) = Decimator.MinMax(sensor.TimesS, sensor.Values, 1000);
@@ -94,5 +154,6 @@ public partial class SensorsChart : UserControl
}
DrawnSeries++;
return true;
}
}
+46 -5
View File
@@ -1,15 +1,20 @@
namespace FrameLedger.App.Charts;
/// <summary>
/// A session's per-present series decoded for the charts and the export: every present in drained order with its
/// time from the session start, its interval, whether it was generated, whether a gap sat before it; the
/// application-frame view (non-generated, non-gap) with the stutter flags over it; the segments on the time
/// axis; the sensor series. Decoded once per window, decimated per draw.
/// A session's per-present series decoded for the charts and the export: every present of the charted stream in drained
/// order with its time from the stream's first present, its interval, whether it was generated, whether a gap sat before
/// it; the application-frame view with the stutter flags over it; the segments on the time axis; the sensor series.
/// Decoded once per window, decimated per draw.
/// </summary>
/// <remarks>
/// <b>One stream (beta.8).</b> A session that presented to more than one swapchain is charted on the one its statistics are
/// over (<c>SegmentBuilder.DominantStream</c>: identified first, then the most presents) — the stored intervals are per
/// swapchain, and interleaving two streams' intervals on one time axis drew neither.
/// </remarks>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1819:Properties should not return arrays", Justification = "a data carrier for the charts: ScottPlot draws double[] and a 500k-frame session is decimated per draw, not copied per read")]
public sealed record SessionSeries
{
/// <summary>Seconds from the first present, per present (a cumulative sum of the intervals).</summary>
/// <summary>Seconds from the stream's first present, per present (a cumulative sum of the intervals; a gap adds none).</summary>
public required double[] TimesS { get; init; }
/// <summary>The stored interval per present, ms; 0 on the first present and after a gap.</summary>
@@ -37,23 +42,59 @@ public sealed record SessionSeries
public ushort[]? RenderRes { get; init; }
// the application-frame view
/// <summary>The time of each application frame's present, seconds.</summary>
public required double[] AppTimesS { get; init; }
/// <summary>
/// Each application frame's time, ms: from the previous application frame's present to its own (beta.8) — the generated
/// presents between them add no interval, and a gap breaks the chain. Every present's interval where nothing was generated.
/// </summary>
public required double[] AppFrameTimesMs { get; init; }
/// <summary>Index into the per-present arrays for each application frame.</summary>
public required int[] AppPresentIndex { get; init; }
/// <summary>
/// Every present was generated — frame generation counted and no application frame's token arrived (the <c>no_evaluations</c>
/// refusal) — so the application-frame view is every present instead, and the chart says so.
/// </summary>
public bool NoApplicationFrames { get; init; }
/// <summary>Per application frame, from <c>Domain.Metrics.StutterDetector</c>; null when the session is too short for the window.</summary>
public bool[]? Stutter { get; init; }
public required IReadOnlyList<SegmentSpan> Segments { get; init; }
/// <summary>
/// The sensor series. On the frames' axis — seconds from the first present, negative before it — when
/// <see cref="SensorsAligned"/>; from the session's start otherwise.
/// </summary>
public required IReadOnlyList<SensorSeries> Sensors { get; init; }
/// <summary>
/// The sensors are placed on the frames' time axis: the blob said where the first present sits on the sensors' clock
/// (schema 0013). A session recorded before cannot draw them over its frames.
/// </summary>
public bool SensorsAligned { get; init; }
public int Presents => TimesS.Length;
public bool HasGenerated => Generated.Any(static g => g);
public double DurationS => TimesS.Length == 0 ? 0 : TimesS[^1];
/// <summary>A series with no frames: a session that was not hooked still has its sensors (beta.8).</summary>
public static SessionSeries SensorsOnly(IReadOnlyList<SensorSeries> sensors) => new()
{
TimesS = [],
FrameTimesMs = [],
Generated = [],
Gap = [],
AppTimesS = [],
AppFrameTimesMs = [],
AppPresentIndex = [],
Segments = [],
Sensors = sensors,
};
}
+141 -35
View File
@@ -6,10 +6,11 @@ using FrameLedger.Infrastructure.Blobs;
namespace FrameLedger.App.Charts;
/// <summary>
/// Decodes one session's blobs into a <see cref="SessionSeries"/>: the frametime series with the gap and
/// generated bits, the application-frame view with <c>StutterDetector</c> over it (the same rule the stored
/// <c>stutter_count</c> came from), the segments mapped from frame index to seconds, and the sensors aligned to
/// their <c>t_ms</c>. Null when the session has no frame blob (Tier 2, or swept by retention).
/// Decodes one session's blobs into a <see cref="SessionSeries"/>: the charted stream's frametime series with the gap
/// and generated bits, the application-frame view with <c>StutterDetector</c> over it (the rule the stored
/// <c>stutter_count</c> came from), the segments mapped from frame index to seconds, and the sensors. Null when the
/// session has no frame blob (Tier 2, or swept by retention); <see cref="LoadSensorsAsync"/> reads a Tier-2 session's
/// sensors on their own.
/// </summary>
public sealed class SessionSeriesLoader
{
@@ -30,61 +31,165 @@ public sealed class SessionSeriesLoader
return Decode(frames, segments, sensors);
}
/// <summary>
/// The sensor series alone, timed from the session's start — what a session that was not hooked has to chart (beta.8: the
/// Tier-2 row has kept its sensors since 2026-09-22, and no chart read them). Empty when none were recorded.
/// </summary>
public async Task<IReadOnlyList<SensorSeries>> LoadSensorsAsync(long sessionId, CancellationToken ct = default) =>
DecodeSensors(await _sessions.FindSensorsAsync(sessionId, ct).ConfigureAwait(false), offsetS: 0);
public static SessionSeries Decode(FrameBlobs frames, IReadOnlyList<SegmentRow> segments, IReadOnlyList<SensorBlob> sensors)
{
ArgumentNullException.ThrowIfNull(frames);
ArgumentNullException.ThrowIfNull(segments);
ArgumentNullException.ThrowIfNull(sensors);
float[] frametimes = SeriesCodec.DecodeFloat32(frames.FrameTimes.ToArray());
byte[] flags = SeriesCodec.DecodeBytes(frames.FrameFlags.ToArray());
int n = Math.Min(frametimes.Length, flags.Length);
float[] allFrametimes = SeriesCodec.DecodeFloat32(frames.FrameTimes.ToArray());
byte[] allFlags = SeriesCodec.DecodeBytes(frames.FrameFlags.ToArray());
int total = Math.Min(allFrametimes.Length, allFlags.Length);
uint[]? swapchains = frames.SwapchainIds is { } ids ? SeriesCodec.DecodeUInt32(ids.ToArray()) : null;
(int[] keep, uint? swapchain) = ChartedStream(total, swapchains);
float[] frametimes = Pick(allFrametimes, keep);
byte[] flags = Pick(allFlags, keep);
int n = keep.Length;
var times = new double[n];
var generated = new bool[n];
var gap = new bool[n];
double t = 0;
var appTimes = new List<double>(n);
var appFrametimes = new List<double>(n);
var appIndex = new List<int>(n);
for (int i = 0; i < n; i++)
{
t += frametimes[i] / 1000.0;
times[i] = t;
generated[i] = (flags[i] & (byte)FrameFlagBits.Generated) != 0;
gap[i] = (flags[i] & (byte)FrameFlagBits.Gap) != 0;
if (i > 0 && !generated[i] && !gap[i] && frametimes[i] > 0)
{
appTimes.Add(t);
appFrametimes.Add(frametimes[i]);
appIndex.Add(i);
}
}
(List<int> appIndex, List<double> appFrametimes, bool noApplicationFrames) = ApplicationFrames(frametimes, generated, gap);
StutterResult? stutter = StutterDetector.Detect(appFrametimes);
uint[]? frameIndex = frames.FrameIndex is { } fi ? SeriesCodec.DecodeUInt32(fi.ToArray()) : null;
uint[]? frameIndex = frames.FrameIndex is { } fi ? PickOptional(SeriesCodec.DecodeUInt32(fi.ToArray()), keep) : null;
double? offsetS = frames.FirstPresentMs / 1000.0;
return new SessionSeries
{
TimesS = times,
FrameTimesMs = frametimes.Length == n ? frametimes : frametimes[..n],
FrameTimesMs = frametimes,
Generated = generated,
Gap = gap,
FrameIndex = frameIndex,
RtFlags = frames.RtFlags is { } rt ? SeriesCodec.DecodeBytes(rt.ToArray()) : null,
DispatchRays = frames.DispatchRays is { } dr ? SeriesCodec.DecodeUInt32(dr.ToArray()) : null,
PsoCreated = frames.PsoCreated is { } pso ? SeriesCodec.DecodeUInt16(pso.ToArray()) : null,
VramProcMb = frames.VramProc is { } vram ? SeriesCodec.DecodeUInt32(vram.ToArray()) : null,
LatencyUs = frames.LatencyUs is { } lat ? SeriesCodec.DecodeUInt32(lat.ToArray()) : null,
RenderRes = frames.RenderRes is { } rr ? SeriesCodec.DecodeUInt16(rr.ToArray()) : null,
AppTimesS = [.. appTimes],
RtFlags = frames.RtFlags is { } rt ? PickOptional(SeriesCodec.DecodeBytes(rt.ToArray()), keep) : null,
DispatchRays = frames.DispatchRays is { } dr ? PickOptional(SeriesCodec.DecodeUInt32(dr.ToArray()), keep) : null,
PsoCreated = frames.PsoCreated is { } pso ? PickOptional(SeriesCodec.DecodeUInt16(pso.ToArray()), keep) : null,
VramProcMb = frames.VramProc is { } vram ? PickOptional(SeriesCodec.DecodeUInt32(vram.ToArray()), keep) : null,
LatencyUs = frames.LatencyUs is { } lat ? PickOptional(SeriesCodec.DecodeUInt32(lat.ToArray()), keep) : null,
RenderRes = frames.RenderRes is { } rr ? PickQuads(SeriesCodec.DecodeUInt16(rr.ToArray()), keep) : null,
AppTimesS = [.. appIndex.Select(i => times[i])],
AppFrameTimesMs = [.. appFrametimes],
AppPresentIndex = [.. appIndex],
NoApplicationFrames = noApplicationFrames,
Stutter = stutter is null ? null : [.. stutter.IsStutter],
Segments = MapSegments(segments, times, frameIndex),
Sensors = DecodeSensors(sensors),
Segments = MapSegments([.. segments.Where(s => swapchain is null || s.SwapchainId == swapchain.Value)], times, frameIndex),
Sensors = DecodeSensors(sensors, offsetS ?? 0),
SensorsAligned = offsetS is not null,
};
}
/// <summary>
/// The presents of the stream the charts draw — the one the session's statistics are over (<c>SegmentBuilder.DominantStream</c>:
/// identified first, then the most presents) — as indices into the blob, and that stream's id; every present, and no id,
/// when the blob held one stream.
/// </summary>
internal static (int[] Keep, uint? Swapchain) ChartedStream(int count, uint[]? swapchains)
{
if (swapchains is null || swapchains.Length < count)
{
return ([.. Enumerable.Range(0, count)], null);
}
IReadOnlyList<int> keep = SegmentBuilder.DominantStream([.. Enumerable.Range(0, count)], i => swapchains[i]);
return ([.. keep], keep.Count > 0 ? swapchains[keep[0]] : null);
}
/// <summary>
/// The application-frame view: each application frame's time is from the previous application frame's present to its own —
/// the generated presents between them add their intervals to it, never an interval of their own — and a gap breaks the
/// chain. Where every present was generated, every present's interval, and the flag that says so.
/// </summary>
internal static (List<int> Index, List<double> FrametimesMs, bool NoApplicationFrames) ApplicationFrames(float[] frametimes, bool[] generated, bool[] gap)
{
ArgumentNullException.ThrowIfNull(frametimes);
ArgumentNullException.ThrowIfNull(generated);
ArgumentNullException.ThrowIfNull(gap);
bool noApplicationFrames = generated.Length > 0 && generated.All(static g => g);
var index = new List<int>(frametimes.Length);
var ms = new List<double>(frametimes.Length);
bool chain = false;
double sinceApplicationFrame = 0;
for (int i = 0; i < frametimes.Length; i++)
{
if (gap[i])
{
chain = false;
sinceApplicationFrame = 0;
}
else
{
sinceApplicationFrame += frametimes[i];
}
if (generated[i] && !noApplicationFrames)
{
continue;
}
if (chain && sinceApplicationFrame > 0)
{
index.Add(i);
ms.Add(sinceApplicationFrame);
}
chain = true;
sinceApplicationFrame = 0;
}
return (index, ms, noApplicationFrames);
}
private static T[] Pick<T>(T[] values, int[] keep)
{
if (keep.Length == values.Length)
{
return values;
}
var picked = new T[keep.Length];
for (int i = 0; i < keep.Length; i++)
{
picked[i] = values[keep[i]];
}
return picked;
}
/// <summary>A per-present series the blob may have written shorter than the frames: only the kept presents it covers.</summary>
private static T[] PickOptional<T>(T[] values, int[] keep) => keep.Length == values.Length ? values : [.. keep.Where(i => i < values.Length).Select(i => values[i])];
private static ushort[] PickQuads(ushort[] values, int[] keep)
{
if (keep.Length * 4 == values.Length)
{
return values;
}
var picked = new List<ushort>(keep.Length * 4);
foreach (int i in keep.Where(i => (i * 4) + 3 < values.Length))
{
picked.AddRange(values.AsSpan(i * 4, 4).ToArray());
}
return [.. picked];
}
/// <summary>A segment's <c>start_frame</c>/<c>end_frame</c> are frame indices; the present at that index (or the nearest) gives the seconds.</summary>
private static IReadOnlyList<SegmentSpan> MapSegments(IReadOnlyList<SegmentRow> segments, double[] times, uint[]? frameIndex)
private static List<SegmentSpan> MapSegments(IReadOnlyList<SegmentRow> segments, double[] times, uint[]? frameIndex)
{
if (times.Length == 0)
{
@@ -117,18 +222,19 @@ public sealed class SessionSeriesLoader
private static string SegmentLabel(SegmentRow s)
{
string upscaler = Services.Formats.Upscaler(s.Upscaler);
if (s.UpscalerQuality is { Length: > 0 } q)
{
upscaler += " " + q;
}
// A segment carries no driver word: the driver's bookkeeping is per process, not per settings change.
string upscaler = Services.Formats.Upscaler(s.Upscaler, s.UpscalerQuality, driverReported: null);
string resolution = Services.Formats.Resolution(s.RenderW, s.RenderH, s.OutputW, s.OutputH);
string fg = Services.Formats.FrameGeneration(s.FgMode);
return string.Join(" · ", new[] { upscaler, resolution, fg }.Where(static x => x.Length > 0));
}
private static List<SensorSeries> DecodeSensors(IReadOnlyList<SensorBlob> sensors)
/// <summary>
/// Every sensor series against <c>t_ms</c> less <paramref name="offsetS"/> — the first present's place on the sensors'
/// clock, so they share the frames' axis (schema 0013) — and −1 dropped: a tick with no reading, never a zero.
/// </summary>
private static List<SensorSeries> DecodeSensors(IReadOnlyList<SensorBlob> sensors, double offsetS)
{
SensorBlob? clock = sensors.FirstOrDefault(static s => string.Equals(s.Series, "t_ms", StringComparison.Ordinal));
float[]? tMs = clock is null ? null : SeriesCodec.DecodeFloat32(clock.Data.ToArray());
@@ -150,7 +256,7 @@ public sealed class SessionSeriesLoader
continue; // SessionFinalizer.SensorMissing: a tick with no reading, never a zero
}
xs.Add(tMs is not null && i < tMs.Length ? tMs[i] / 1000.0 : i / Math.Max(blob.Hz, 0.001));
xs.Add((tMs is not null && i < tMs.Length ? tMs[i] / 1000.0 : i / Math.Max(blob.Hz, 0.001)) - offsetS);
ys.Add(values[i]);
}
+21 -2
View File
@@ -17,17 +17,23 @@ public partial class TrendChart : UserControl
public int DrawnPoints { get; private set; }
/// <summary>How many of <see cref="DrawnPoints"/> were drawn hollow (a part of their session).</summary>
public int HollowPoints { get; private set; }
public void Show(IReadOnlyList<TrendPoint> points, IReadOnlyList<HardwareChange> changes, string metricLabel)
{
ArgumentNullException.ThrowIfNull(points);
ArgumentNullException.ThrowIfNull(changes);
ScottPlot.Plot plot = Plot.Plot;
plot.Clear();
// The date axis REPLACES the bottom axis, so it goes first (beta.8): made after the theme and the label, it dropped
// both — an unlabelled axis in the default colours, unreadable in the dark theme.
plot.Axes.DateTimeTicksBottom();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Trend_Axis_Date);
plot.YLabel(metricLabel);
plot.Axes.DateTimeTicksBottom();
DrawnPoints = points.Count;
HollowPoints = points.Count(static t => t.SettingsChangedMidSession);
if (points.Count > 0)
{
ChartPalette p = ChartTheme.Current;
@@ -37,7 +43,20 @@ public partial class TrendChart : UserControl
line.LineWidth = 2;
line.MarkerSize = 7;
line.LegendText = metricLabel;
foreach (HardwareChange change in changes)
// A point that describes part of its session (settings changed, or a steady state) is drawn hollow over its
// filled one: the line still passes through it, and it cannot be read as the session's own number.
TrendPoint[] partial = [.. points.Where(static t => t.SettingsChangedMidSession)];
if (partial.Length > 0)
{
double[] hx = [.. partial.Select(static t => t.At.LocalDateTime.ToOADate())];
double[] hy = [.. partial.Select(static t => t.Value)];
Scatter hollow = plot.Add.ScatterPoints(hx, hy, p.Data);
hollow.MarkerSize = 6;
hollow.MarkerShape = MarkerShape.FilledCircle;
}
foreach (HardwareChange change in TrendSeriesBuilder.MergedByDay(changes))
{
VerticalLine marker = plot.Add.VerticalLine(change.At.LocalDateTime.ToOADate(), 1, p.StutterPso, LinePattern.Dashed);
marker.LabelText = change.Text;
+28 -2
View File
@@ -3,8 +3,15 @@ namespace FrameLedger.App.Charts;
/// <summary>The Trend tab's selector (<c>08_UI</c> §Games › Trend).</summary>
public enum TrendMetric
{
/// <summary>Native FPS where frame generation was measured; Presented FPS where it was not (the row's headline, per <c>03_METRICS</c> Avg FPS).</summary>
Average,
/// <summary>
/// Presented FPS — every frame presented — on the sessions where no generated frame was counted (beta.8: "Average" mixed
/// it with Native in one line). A session that counted generated frames has none here: its presented rate includes them,
/// the single inflated number CLAUDE.md rule 6 forbids; it is on <see cref="NativeFps"/> and <see cref="Displayed"/>.
/// </summary>
PresentedFps,
/// <summary>Native FPS — the game's own frames — only where frame generation was measured (counted, or measured none).</summary>
NativeFps,
/// <summary>Displayed FPS — only sessions that measured frame generation have one.</summary>
Displayed,
@@ -14,4 +21,23 @@ public enum TrendMetric
P01Low,
MaxGpuTemp,
/// <summary>The seven below are 2026-09-21's: one game's sessions over time, beyond the frame rate.</summary>
AvgGpuLoad,
AvgGpuPower,
MaxVramProcess,
AvgCpuLoad,
MaxCpuTemp,
AvgRam,
/// <summary>
/// The counted ×FG factor. A session whose factor is its STEADY STATE's (CLAUDE.md rule 6, 2026-09-17) describes part
/// of the session, so it is treated as a mid-session change: left out by default, drawn marked when those are included.
/// </summary>
FgFactor,
}
@@ -7,10 +7,15 @@ using FrameLedger.Domain.Sessions;
namespace FrameLedger.App.Charts;
/// <summary>
/// The Trend tab's data (FR-6.3, FR-6.4): one point per hooked session that has the metric, oldest first, with
/// the sessions that changed settings mid-session excluded unless asked for; and a marker wherever two
/// consecutive sessions' hardware snapshots differ in what a reader would want to know about.
/// The Trend tab's data (FR-6.3, FR-6.4): one point per session that has the metric, oldest first, with the points that
/// describe only part of their session excluded unless asked for; and a marker wherever two consecutive sessions'
/// hardware snapshots differ in what a reader would want to know about.
/// </summary>
/// <remarks>
/// <b>Which sessions (beta.8).</b> A frame-rate metric is the hooks' and comes from hooked sessions only; a machine metric
/// — temperatures, loads, power, memory — is the telemetry every session records, Tier 2 included, which the trend left
/// out until 2026-09-25 (a game never hooked had no trend at all).
/// </remarks>
[SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format string is a resource that follows the UI culture, which changes at runtime")]
public static class TrendSeriesBuilder
{
@@ -18,9 +23,10 @@ public static class TrendSeriesBuilder
{
ArgumentNullException.ThrowIfNull(rows);
var points = new List<TrendPoint>();
foreach (SessionRow row in rows.Where(static r => r.Tier == CaptureTier.Hooked).OrderBy(static r => r.StartedAt))
foreach (SessionRow row in rows.Where(r => Counts(r, metric)).OrderBy(static r => r.StartedAt))
{
if (row.SettingsChangedMidSession && !includeMidSessionChanges)
bool partial = IsPartial(row, metric);
if (partial && !includeMidSessionChanges)
{
continue;
}
@@ -28,7 +34,7 @@ public static class TrendSeriesBuilder
double? value = ValueOf(row, metric);
if (value is double v)
{
points.Add(new TrendPoint(row.StartedAt, v, row.Id, row.SettingsChangedMidSession));
points.Add(new TrendPoint(row.StartedAt, v, row.Id, partial));
}
}
@@ -36,10 +42,37 @@ public static class TrendSeriesBuilder
}
/// <summary>How many sessions FR-6.4 leaves out at the default setting.</summary>
public static int ExcludedCount(IReadOnlyList<SessionRow> rows)
public static int ExcludedCount(IReadOnlyList<SessionRow> rows) => ExcludedCount(rows, TrendMetric.PresentedFps);
/// <summary>Whether a session can have a point for <paramref name="metric"/>: a frame rate needs the hooks; the machine is every session's.</summary>
public static bool Counts(SessionRow row, TrendMetric metric)
{
ArgumentNullException.ThrowIfNull(row);
return row.Tier == CaptureTier.Hooked || IsMachineMetric(metric);
}
/// <summary>The metrics that are telemetry, recorded by every session whatever its tier.</summary>
public static bool IsMachineMetric(TrendMetric metric) => metric is TrendMetric.MaxGpuTemp or TrendMetric.AvgGpuLoad or TrendMetric.AvgGpuPower
or TrendMetric.AvgCpuLoad or TrendMetric.MaxCpuTemp or TrendMetric.AvgRam;
public static int ExcludedCount(IReadOnlyList<SessionRow> rows, TrendMetric metric)
{
ArgumentNullException.ThrowIfNull(rows);
return rows.Count(static r => r.Tier == CaptureTier.Hooked && r.SettingsChangedMidSession);
return rows.Count(r => Counts(r, metric) && IsPartial(r, metric) && ValueOf(r, metric) is not null);
}
/// <summary>
/// A point that describes only part of its session: the settings changed mid-session (FR-6.4), or — for the factor
/// — the number is the steady state's and covers a share of the session (rule 6: never shown as the session's).
/// </summary>
public static bool IsPartial(SessionRow row, TrendMetric metric)
{
ArgumentNullException.ThrowIfNull(row);
// A steady state (CLAUDE.md rule 6, 2026-09-17) is the factor's AND the Native / Displayed rates beside it: all three
// describe the state the session spent most of its generating time in, never the whole session (beta.8).
return row.SettingsChangedMidSession
|| (metric is TrendMetric.FgFactor or TrendMetric.NativeFps or TrendMetric.Displayed
&& string.Equals(row.FgFactorScope, "steady", StringComparison.Ordinal));
}
/// <summary>The metric's value on a row, or null when that row cannot have it (FR-4.9: never an estimate).</summary>
@@ -49,9 +82,11 @@ public static class TrendSeriesBuilder
FpsReadoutModel readout = FpsPresentation.FromRow(row);
return metric switch
{
TrendMetric.Average => readout.Kind switch
TrendMetric.NativeFps => readout.Kind is FpsReadoutKind.Generated or FpsReadoutKind.None ? readout.Native : null,
TrendMetric.PresentedFps => readout.Kind switch
{
FpsReadoutKind.Generated or FpsReadoutKind.None => readout.Native,
// A measured none: the presents are the application's frames, so the rate is both.
FpsReadoutKind.None => readout.Native,
FpsReadoutKind.Presented or FpsReadoutKind.IdentifiedUncounted => readout.Presented,
_ => null,
},
@@ -59,10 +94,28 @@ public static class TrendSeriesBuilder
TrendMetric.P1Low => row.P1LowFps,
TrendMetric.P01Low => row.P01LowFps,
TrendMetric.MaxGpuTemp => row.MaxGpuTemp,
TrendMetric.AvgGpuLoad => row.AvgGpuLoad,
TrendMetric.AvgGpuPower => row.AvgGpuPowerW,
TrendMetric.MaxVramProcess => row.VramProcMaxMb,
TrendMetric.AvgCpuLoad => row.AvgCpuLoad,
TrendMetric.MaxCpuTemp => row.MaxCpuTemp,
TrendMetric.AvgRam => row.AvgRamMb,
TrendMetric.FgFactor => readout.Kind == FpsReadoutKind.Generated ? readout.Factor : null,
_ => null,
};
}
/// <summary>
/// One marker per day that changed (beta.8): every difference found on that day in one label, line after line — two
/// labels at one position were drawn over each other.
/// </summary>
public static IReadOnlyList<HardwareChange> MergedByDay(IReadOnlyList<HardwareChange> changes)
{
ArgumentNullException.ThrowIfNull(changes);
return [.. changes.GroupBy(static c => c.At.LocalDateTime.Date)
.Select(static g => new HardwareChange(g.First().At, string.Join(Environment.NewLine, g.Select(static c => c.Text).Distinct(StringComparer.Ordinal))))];
}
/// <summary>Markers between consecutive sessions (oldest first) whose snapshots differ; <paramref name="snapshotOf"/> resolves a row's snapshot id.</summary>
public static IReadOnlyList<HardwareChange> Changes(IReadOnlyList<SessionRow> rows, Func<long, HardwareSnapshot?> snapshotOf)
{
@@ -24,7 +24,13 @@
<RowDefinition Height="Auto" />
<RowDefinition Height="*" />
</Grid.RowDefinitions>
<ui:TextBlock Grid.Row="0" Grid.ColumnSpan="2" Margin="0,0,0,12" Appearance="Secondary" Text="{x:Static vm:FirstRunViewModel.LegalBody}" TextWrapping="Wrap" />
<StackPanel Grid.Row="0" Grid.ColumnSpan="2" Margin="0,0,0,12">
<!-- The short version, in the user's language (2026-09-21). It summarises; the documents below are the terms. -->
<Border Padding="12" CornerRadius="6" Background="{DynamicResource SystemFillColorCautionBackgroundBrush}">
<ui:TextBlock Foreground="{DynamicResource TextFillColorPrimaryBrush}" Text="{x:Static vm:FirstRunViewModel.LegalSummary}" TextWrapping="Wrap" />
</Border>
<ui:TextBlock Margin="0,10,0,0" Appearance="Secondary" Text="{x:Static vm:FirstRunViewModel.LegalBody}" TextWrapping="Wrap" />
</StackPanel>
<ListBox Grid.Row="1"
Grid.Column="0"
Margin="0,0,12,0"
@@ -9,13 +9,19 @@
mc:Ignorable="d"
MinWidth="480">
<!--
10_LOGGING §Bug report flow step 2's optional item (P4 PR-9): the crash dump goes in only when it is ticked
(legal/PRIVACY_POLICY.md §3). The box starts clear, and its label and the line under it say how large the dump is
and what it can hold before anyone ticks it.
10_LOGGING §Bug report flow step 2's optional items: the crash dump (P4 PR-9) and the last session's summary each go
in only when ticked (legal/PRIVACY_POLICY.md §3). Only the items there are get a box; every box starts clear, and
the line under it says what the item holds before anyone ticks it.
-->
<StackPanel>
<ui:TextBlock TextWrapping="Wrap" Text="{x:Static vm:BugBundleOptionsViewModel.Intro}" />
<CheckBox Margin="0,12,0,0" IsChecked="{Binding IncludeCrashDump}" Content="{Binding DumpLabel}" />
<ui:TextBlock Margin="28,4,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:BugBundleOptionsViewModel.DumpDetail}" />
<StackPanel Visibility="{Binding HasCrashDump, Converter={StaticResource BoolToVis}}">
<CheckBox Margin="0,12,0,0" IsChecked="{Binding IncludeCrashDump}" Content="{Binding DumpLabel}" />
<ui:TextBlock Margin="28,4,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:BugBundleOptionsViewModel.DumpDetail}" />
</StackPanel>
<StackPanel Visibility="{Binding HasLastSession, Converter={StaticResource BoolToVis}}">
<CheckBox Margin="0,12,0,0" IsChecked="{Binding IncludeLastSession}" Content="{Binding SessionLabel}" />
<ui:TextBlock Margin="28,4,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:BugBundleOptionsViewModel.SessionDetail}" />
</StackPanel>
</StackPanel>
</UserControl>
@@ -8,25 +8,35 @@
d:DataContext="{d:DesignInstance Type=vm:EditGameViewModel}"
mc:Ignorable="d"
MinWidth="420">
<!-- FR-1.3: a detected field is badged (05_DETECTION §Caching), and saving marks what changed as the user's. -->
<!--
FR-1.3: a detected field is badged (05_DETECTION §Caching), and saving marks what changed as the user's.
A TagPill, not ui:Badge: Info's background is a fixed Material colour outside the theme dictionaries, and Secondary keeps the
default badge's on-accent foreground over a near-white fill in the light theme (08_UI §Contrast, 2026-09-21).
-->
<StackPanel>
<DockPanel>
<ui:Badge DockPanel.Dock="Right" Margin="8,0,0,0" Appearance="Info" Content="{x:Static vm:EditGameViewModel.DetectedBadge}"
Visibility="{Binding NameDetected, Converter={StaticResource BoolToVis}}" />
<Border DockPanel.Dock="Right" Style="{StaticResource TagPill}"
Visibility="{Binding NameDetected, Converter={StaticResource BoolToVis}}">
<TextBlock Style="{StaticResource TagPillText}" Text="{x:Static vm:EditGameViewModel.DetectedBadge}" />
</Border>
<ui:TextBlock Appearance="Secondary" Text="{x:Static vm:EditGameViewModel.NameLabel}" />
</DockPanel>
<ui:TextBox Margin="0,4,0,12" AutomationProperties.Name="{x:Static vm:EditGameViewModel.NameLabel}" Text="{Binding Name, UpdateSourceTrigger=PropertyChanged}" />
<DockPanel>
<ui:Badge DockPanel.Dock="Right" Margin="8,0,0,0" Appearance="Info" Content="{x:Static vm:EditGameViewModel.DetectedBadge}"
Visibility="{Binding PublisherDetected, Converter={StaticResource BoolToVis}}" />
<Border DockPanel.Dock="Right" Style="{StaticResource TagPill}"
Visibility="{Binding PublisherDetected, Converter={StaticResource BoolToVis}}">
<TextBlock Style="{StaticResource TagPillText}" Text="{x:Static vm:EditGameViewModel.DetectedBadge}" />
</Border>
<ui:TextBlock Appearance="Secondary" Text="{x:Static vm:EditGameViewModel.PublisherLabel}" />
</DockPanel>
<ui:TextBox Margin="0,4,0,12" AutomationProperties.Name="{x:Static vm:EditGameViewModel.PublisherLabel}" Text="{Binding Publisher, UpdateSourceTrigger=PropertyChanged}" />
<DockPanel>
<ui:Badge DockPanel.Dock="Right" Margin="8,0,0,0" Appearance="Info" Content="{x:Static vm:EditGameViewModel.DetectedBadge}"
Visibility="{Binding VersionDetected, Converter={StaticResource BoolToVis}}" />
<Border DockPanel.Dock="Right" Style="{StaticResource TagPill}"
Visibility="{Binding VersionDetected, Converter={StaticResource BoolToVis}}">
<TextBlock Style="{StaticResource TagPillText}" Text="{x:Static vm:EditGameViewModel.DetectedBadge}" />
</Border>
<ui:TextBlock Appearance="Secondary" Text="{x:Static vm:EditGameViewModel.VersionLabel}" />
</DockPanel>
<ui:TextBox Margin="0,4,0,12" AutomationProperties.Name="{x:Static vm:EditGameViewModel.VersionLabel}" Text="{Binding Version, UpdateSourceTrigger=PropertyChanged}" />
+4 -1
View File
@@ -88,9 +88,12 @@
</ItemsControl.ItemsPanel>
<ItemsControl.ItemTemplate>
<DataTemplate DataType="{x:Type vm:CompareCell}">
<TextBlock Margin="4,0" Text="{Binding Text}" Foreground="{DynamicResource TextFillColorPrimaryBrush}">
<!-- The default foreground is the Style's, not a local value (beta.8): a local value outranks every
trigger, and the best cell was bold but never in the accent colour. -->
<TextBlock Margin="4,0" Text="{Binding Text}">
<TextBlock.Style>
<Style TargetType="TextBlock">
<Setter Property="Foreground" Value="{DynamicResource TextFillColorPrimaryBrush}" />
<Style.Triggers>
<DataTrigger Binding="{Binding IsBest}" Value="True">
<Setter Property="FontWeight" Value="Bold" />
Loaded 100 of 472 files, more files were not shown because too many files have changed in this diff. Show more