Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 6fdb2f7282 feat(app): the user-mode anti-cheat exception in Settings and on the game page - its option, its list, its versioned disclosure, and the legal text that says it (D33)
Owner decision D33 (2026-09-26), beta.9 PR-3 of 4, on the guard (#236) and the Agent (#237).
This is the part a user sees; every state it shows is the Agent's, read from its columns,
and every grant is the Agent's to make.

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

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

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

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

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

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

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

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

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

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

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

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

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

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 17:06:15 +00:00
135 changed files with 5905 additions and 307 deletions

No files matched your search

+75
View File
@@ -29,6 +29,81 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
### Added
- **A user-mode anti-cheat exception you can make yourself, per game** (owner decision D33). Settings ▸ Capture ▸
*Allow hooking in games with user-mode anti-cheat that were measured before* — off by default. On, it lists the games
FrameLedger found eligible: the only anti-cheat in the game runs entirely in user mode (no driver or service, no
driver file anywhere in the game's folder), the game is on no title list, and FrameLedger has measured it hooked
successfully at least twice. **Make exception…** shows a disclosure — the ban risk, possibly days later and invisible
to FrameLedger; what is still refused; how the exception ends — and asks you to accept the risk for that game. The
exception turns nothing on: you then turn hooking on for the game on its page, through the usual consent dialog, and
the guard still runs every check and refuses anything else it finds. The game's page shows the exception's state
(eligible; not eligible and why; in force; suspended; ended and why), the library card says **Exception**, and a
session hooked under it is marked in the Sessions tab and its summary. It ends by itself on a new finding, a crash or
safety stop under it, FrameLedger stopping because another anti-cheat loaded, or a game update; turning the option
off suspends every exception. Aniimo stays blocked: it ships a kernel driver (`NEPKernel.sys`).
- **Groundwork for the user-mode anti-cheat exception** (owner decision D33, 2026-09-26; the option, the list and the
disclosure arrive later in this train). The guard can now be asked to let ONE named anti-cheat family through, and
grants it only for a family whose every signal — in the built-in floor and in the rules file — is user-mode: no
driver, no service, no `.sys` (on today's rules NetEase Yidun, AhnLab HackShield, Anybrain and FredaikisAntiCheat).
It still runs every check and keeps scanning past what it let through, so a second anti-cheat, a kernel driver in
the game's folder, a title list, a driver or service on the machine, or a scan that could not finish still refuses;
a pass that let something through says so and names it. The injected Overlay learns the same family before it
starts watching the game's module loads, so a late-loading module of that family does not stop it and any other
anti-cheat still does. Nothing asks for any of this yet: every game is judged exactly as in beta.8.
- **The Agent can grant, keep and end a user-mode anti-cheat exception** (D33; the Settings option, the list and the
disclosure arrive in the next PR, so nothing in the App asks for one yet). With the option on
(`hooking.usermode_ac_exceptions`, off by default), the Agent's library scan asks each blocked game one question —
would the guard let exactly its blocking family through, with no kernel driver and nothing else found — and counts
its successful hooked sessions; a game with both and at least two sessions is eligible. A grant rests on facts the
Agent gathers itself when asked, is bound to the executable's bytes and turns nothing on: hooking is the usual
consent dialog afterwards. Under it the Agent tells the Overlay the family before injecting, names it to the guard at
the start and at every 30 s re-scan, and marks the session with it. It ends — hooking off, the block standing, the
reason kept — on a new finding, a safety unhook, the Overlay stopping for another anti-cheat, a crash while hooked, a
game update, or when the user withdraws it; turning the option off suspends every exception without deleting any.
Schema 0014 adds the columns; the database opens in place.
### Changed
- **Legal: Disclaimer 2.7 and EULA 1.3.** Disclaimer §2A describes the user-mode exception and its risk; the EULA's
code-injection clause names it and what making one means. The accuracy block and SECURITY.md say it too. The Legal
Gate shows the two changed documents once more; the Privacy Policy is unchanged (2.4).
## [0.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
+1
View File
@@ -16,6 +16,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
> **Amended 2026-09-22 (owner decision): the override of 2026-09-21 is withdrawn, and the sentence above is the rule again.** For one day (releases `0.1.0-beta.3` and `beta.4`) a per-game override existed. The owner withdrew it: no entry point, no message, no column (schema 0008 drops 0007's five), no string. Do not add one in any form.
>
> **A finding turns the game's hooking off** (`19_SAFETY` §What a finding does to the game). An anti-cheat named in the game itself — its process, its title lists, its folder — is written to the row exactly as the pre-scan always wrote it (`hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`), and since 2026-09-22 also when the guard finds it at a session's start or at the 30 s re-scan (`AntiCheatVerdict.IsFindingAboutTheGame`). A machine-wide driver or service refuses that session only. The notice, the game's page, the session's notes and the Agent's log all say it happened. Nothing clears the block, as before.
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
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).
+17 -10
View File
@@ -5,8 +5,8 @@
> No telemetry. No accounts. All data stays on your machine.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-23.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.7`** (2026-09-23), an unsigned installer built from that tag with its
> ⚠ **What FrameLedger actually measures today — 2026-09-26.** 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
@@ -24,7 +24,9 @@
> 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)*. Intel XeSS is **not** read (its SDK licence
> 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
@@ -45,7 +47,8 @@
> 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.
> **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
@@ -62,9 +65,13 @@
> 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, in its folder or on its title lists — turns hooking off for that game, whether found
> 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.
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
> runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
@@ -100,7 +107,7 @@ FrameLedger is built to keep that risk small and to be honest about it:
| Safeguard | |
|---|---|
| **Off by default** | Injection is disabled for every game until you enable it individually, after a consent prompt |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>**One narrow exception since beta.9 (owner decision D33):** per game, after its own disclosure and only while a Settings option (off by default) is on, a game whose only finding is one anti-cheat that runs entirely in user mode — no driver file in its folder, on no title list — and that FrameLedger has measured successfully at least twice may be hooked under a user-mode exception. The guard still runs every check under it, refuses anything else it finds, and ends it on anything new; a ban remains possible (`legal/DISCLAIMER.md` §2A).<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **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 |
@@ -137,7 +144,7 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
## Install
> **The latest pre-release is `v0.1.0-beta.7` (2026-09-23); before it `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
> **The latest pre-release is `v0.1.0-beta.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**.
@@ -165,4 +172,4 @@ If you find a game with anti-cheat that FrameLedger fails to detect, please open
---
**Status:** pre-release (beta). Seven tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
**Status:** pre-release (beta). 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.
+9
View File
@@ -31,6 +31,15 @@ now turns the game's hooking off. What IS a security report: any way to reach an
setting, a crafted rules file, a pipe message, a database edit the Agent honours — or a finding about a game that
does not turn its hooking off.
Since 0.1.0-beta.9 one narrow exception exists (owner decision D33, `docs/19_SAFETY_AND_ANTICHEAT.md` §The user-mode
exception): per game, only for one anti-cheat family that is user-mode throughout, with the guard still running every
check. The grant is a record in your own database, like the consent stamp; what keeps it narrow is the guard, which
decides itself which family it may let through. So these are security reports too: the guard letting through a family
that has a driver, a service or a `.sys` in the floor or the rules; an exception applying to a game with a kernel
driver in its folder, on a title list, or with a second anti-cheat; the Agent writing a grant on a pipe message
without its own tolerant pre-scan and session count; an exception that survives a new finding, a crash or safety stop
under it, or a changed executable; and the Overlay tolerating a family the guard did not.
## 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
+2 -1
View File
@@ -15,9 +15,10 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
### 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. 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.3 The runtime guard refuses injection and refuses to continue a session when anti-cheat is detected. **No override exists anywhere in the UI, config, or CLI.** *(Since 2026-09-26 one narrow, evidence-bound exception exists — FR-2.8. It is not an override: the guard still runs every check and decides itself which anti-cheat family it may let through.)*
- FR-2.4 Global "disable all hooking" kill switch in Settings; also honored by the Vulkan layer.
- FR-2.7 (owner decision 2026-09-22; it was a per-game override for one day, withdrawn) A finding about a game — anti-cheat named in its process, on its title lists or in its folder — turns hooking off for that game wherever the guard makes it: at the pre-scan, at a session's start, at the 30 s re-scan, or (since 2026-09-25) at the Agent's pre-scan of the library. The row carries the reason, the game's page and the notice say so, and nothing overrides it (`19_SAFETY` §What a finding does to the game).
- FR-2.8 (owner decision D33, 2026-09-26) **The user-mode anti-cheat exception.** A Settings option, off by default, lets the user grant a per-game exception to a game whose only anti-cheat findings are ONE family that is user-mode throughout (no driver, service or `.sys` in the floor or the rules), whose install tree holds no `.sys`, which is on no title list, and which FrameLedger has measured hooked at least twice (successful Tier-1 sessions). The Agent computes that eligibility itself; the user grants each game through a versioned disclosure that states the ban risk; hooking is then turned on through FR-2.1's dialog as ever. Machine-wide drivers and services, title lists, kernel drivers in the game folder, the fuzzy tier, a scan that could not finish, an unreadable process, a 32-bit game, the kill switch and Vulkan are never excepted. A new finding, a crash / safety unhook / Overlay stop under it, or a changed executable ends it; the option off suspends it; the block itself is never cleared and stays shown (FR-2.2). Sessions under it are marked with the family (`19_SAFETY` §The user-mode exception).
- FR-2.5 Repeated crashes shortly after injection auto-disable hooking for that game, with an explanation and a manual re-enable path.
- FR-2.6 Users can always see, per session, which tier produced the data.
+12
View File
@@ -227,6 +227,18 @@ Its result is authoritative: no code path may inject without a passing check, an
What the Agent checks **before** asking the guard is the thing the native side structurally cannot see: **per-game consent** (CLAUDE.md rule 1). Consent is a record of something a human did, so `HookedCaptureGate` refuses an unconsented or un-enabled game without the guard ever being called.
> **The user-mode exception (D33, 2026-09-26) — one branch, and it only narrows.** A blocked game is refused
> `PreviouslyBlocked` before the guard is asked, as ever, UNLESS `HookRequest.FromConsent` found its exception in
> force: `hooking.usermode_ac_exceptions` on, a grant on the row made on the executable on disk, the block naming that
> family (`UserModeExceptionRules.CoveredFamily`) — and the session could publish the Overlay's channel
> (`IOverlayToleranceChannel`, `07_IPC` §D) BEFORE building the request. Then the gate hands the guard the family's
> NAME through the same entry (`GuardedInjectAsync` / `…WhenReadyAsync`), the guard decides whether to honour it and
> runs every check, and every 30 s re-scan names it again (`GuardSupervisor(guard, toleratedFamily)`). A blocked row
> whose exception does not apply is hooking-off before the process is opened, like any other. A hooked session under
> it is marked (`sessions.ac_exception_family`, `; ac-exception=<family>` in the notes), and a finding about the game,
> a safety unhook, the Overlay's own stop or a crash while hooked ends the exception (`UserModeExceptionLapsePolicy`,
> after the row is stored). `19_SAFETY` §The user-mode exception is the rule; this is where the loop applies it.
> **Where it lives, corrected 2026-08-06.** This sentence said "lives in SQLite", and was the
> only line in the tree that said where consent lives — while no database, no `games` table
> and no consent writer existed in any `.cs` file (§S27). The port is
+29 -1
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`, 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).
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It is the one Agent write that deletes a `games` row; it never touches a consent column. **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; never a `hook_*` column), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
## Schema (v2 — hook architecture)
@@ -63,6 +63,22 @@ CREATE TABLE games (
hook_prescan_exe_size_bytes INTEGER, -- library last scanned the row under — the rules version and the
hook_prescan_exe_mtime_ms INTEGER, -- executable's size and mtime; NULL = never scanned by the sweep.
-- Change executable clears them with hook_prescan_state
-- schema 0014 (2026-09-26, D33): the user-mode anti-cheat exception, a layer OVER hook_blocked_reason, never its clearing
ac_exception_eligible INTEGER NOT NULL DEFAULT 0, -- the Agent's sweep: the exception may be granted now
ac_exception_verdict TEXT, -- its tolerant pre-scan, Reason|Family|Signal; NULL = nothing asked
ac_exception_sessions INTEGER NOT NULL DEFAULT 0, -- successful Tier-1 sessions counted
ac_exception_checked_rules_version TEXT, -- the key the verdict was reached under: rules, executable size and
ac_exception_checked_exe_size_bytes INTEGER, -- mtime, and the block text itself
ac_exception_checked_exe_mtime_ms INTEGER,
ac_exception_checked_block TEXT,
ac_exception_at INTEGER, -- the user's grant; NULL = no exception in force
ac_exception_family TEXT, -- the family it covers (kept as history once it ends)
ac_exception_disclosure_version TEXT, -- AntiCheatExceptionDisclosure.Version the user accepted
ac_exception_exe_size_bytes INTEGER, -- the executable the grant was made on; other bytes end it
ac_exception_exe_mtime_ms INTEGER,
ac_exception_lapsed_at INTEGER, -- when and why the last grant ended (UserModeExceptionLapse:
ac_exception_lapsed_reason TEXT, -- Withdrawn|ExecutableChanged|NoLongerEligible|NewFinding|
-- SafetyUnhook|OverlayStopped|SessionCrashed)
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
@@ -356,6 +372,7 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `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) |
| `hooking.usermode_ac_exceptions` | bool | `0` | | Agent, at every session start and command (FR-2.8, D33, 2026-09-26): off suspends every user-mode exception without deleting any; on, the user still grants each eligible game |
| `capture.min_session_s` | int | `30` | 5–600 | Agent, per session (FR-3.6) |
| `telemetry.interval_ms` | int | `1000` | 500–2000 | Agent, per session (FR-3.5) |
| `retention.raw_sessions_per_game` | int | `20` | 0–10000; **0 = unlimited** | Agent, per session (§Retention) |
@@ -511,6 +528,17 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
> `FgPreset`, `FgMode` beside its masks (additive JSON fields; older rows lack them). `LatestVersion` is 12;
> `LedgerDatabaseTests.ScriptTwelveAddsTheDriverProfileColumn`.
> **`0014_usermode_ac_exception.sql` (beta.9, 2026-09-26, owner decision D33) — the user-mode anti-cheat exception.**
> Fourteen `games.ac_exception_*` columns in three groups — the Agent's eligibility answer about a blocked row and its
> key, the user's grant, and how the last grant ended — and `sessions.ac_exception_family`, the family a HOOKED session
> ran under the exception with. `ADD COLUMN` only; no row changes, so a blocked row stays blocked, not eligible, with
> no grant, until the Agent and the user say otherwise (`19_SAFETY` §The user-mode exception). Written through
> `IGameConsentStore` only — `RecordExceptionEligibilityAsync` (the sweep), `GrantAntiCheatExceptionAsync` (the
> `SetAntiCheatException` command; the store applies `UserModeExceptionRules.IsEligible` itself), `RevokeAntiCheatExceptionAsync`
> (every end) — plus one downgrade in `ChangeExecutableAsync`, which ends a grant (`ExecutableChanged`) and forgets
> the eligibility. The grant and the eligibility are each bound in SQL to the block they were reached about. `LatestVersion`
> is 14; `LedgerDatabaseTests.ScriptFourteenAddsTheExceptionColumnsAndChangesNoRow`.
> **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
+25 -2
View File
@@ -260,6 +260,28 @@ same class of bug as record drift.
Agent is inert from the beginning rather than enjoying a grace window.
- If `unhookRequested` is set, the Overlay disables hooks within one frame and sets `status = unhooked`. This path must be the fastest, most-tested code in the DLL: it is the safety stop.
## D — the tolerance mapping (`Local\FrameLedger.Tolerate.<pid>`), D33 (2026-09-26)
Agent → Overlay, once, BEFORE the injection it concerns: the anti-cheat family NAMES a game's user-mode exception
covers (`19_SAFETY` §The user-mode exception). It cannot live in A + B: the Overlay creates that mapping on init and the
Agent opens it afterwards, while the Overlay's loader detour must know the tolerance from the moment it exists.
```cpp
struct FlTolerance { // fl_tolerance.h; 16 + 8 x 64 = 528 B, no padding
uint32_t magic; // @0 FL_TOLERANCE_MAGIC ("FLTL")
uint32_t version; // @4 FL_TOLERANCE_VERSION (1)
uint32_t count; // @8 names used, <= 8
uint32_t reserved; // @12 zero
char families[8][64]; // @16 NUL-terminated ASCII family names
};
```
Created by the Agent for the game's pid, current user only, held for the session; read once by the Overlay's
`InitThread` before `InstallLoaderHook`, which resolves every name against its own compiled floor and honours only a
user-mode family. Absent, malformed or naming anything else: nothing is tolerated. Mirrored as `FlTolerance` /
`ToleranceLayout` in `FrameLedger.Shared` and held to the native layout by `ShmLayoutMirrorTests` through
`fl-layout-dump`. *(Built in beta.9: PR-1, the Overlay reads it; PR-2, the Agent writes it — `Infrastructure.Capture.OverlayToleranceChannel`, security descriptor `O:<user>D:P(A;;GR;;;<user>)` stated rather than defaulted (an elevated Agent's default DACL omits the user, and the Overlay in an unelevated game could not open it), a name that already exists refused as not ours, and a channel that cannot be published is no exception: the session then names no family and the blocked game is refused as before.)*
## C — command pipe (`\\.\pipe\FrameLedger.v2`)
Unchanged in spirit from v1, bumped to `v2` for the new message set.
@@ -323,11 +345,12 @@ 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` |
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, exceptionDisclosureVersion /* D33, 2026-09-26: the user-mode exception's disclosure this Agent grants against */, ~~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? }` — and `activeSessions[]`, one `{ sessionGuid, gameId, gameName?, pid, tier, startedAt, hold? }` per running session. **`hold` added 2026-09-23, optional:** present on a session held unhooked (Tier 2), with the same words `SessionStarted.hold` carries; a session listed at tier 2 WITHOUT a `hold` has not attached yet — it is starting, not held. The App reads this list on every (re)connect (§Client behavior) |
| `SetWatchlist` | UI→A | `{ entries: [{ gameId?, exePath }] }` — ~~full replace~~ **ensure, never remove** (built 2026-09-13, PR-1b): each entry's path is normalised by the Agent, its row ensured with hooking OFF when new, and the ack is `WatchlistAck { games: [{ gameId, exePath, name }], unreadable: [exePath] }`; `gameId` in a request is a hint and never trusted over the path. UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary). *Since the App writes `games` rows itself under `06_DATA_MODEL` §Writer ownership (HANDOFF §P3 D15), this is the pipe's way of adding a row, not the only one; the watcher reads the table at 1 Hz either way.* |
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable` · `RecordingOff` (2026-09-23: the entry's recording switch is off, FR-1.6 — FrameLedger does not start what it will not record). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). **Since D33 (2026-09-26):** for a blocked game whose user-mode exception is in force for the executable on disk (the option on, a grant made on these bytes, the block naming that family) the pre-scan NAMES the family, and a pass under it is stamped as ever and answered `prescan: "exception"`; a finding about the game under it also ends the exception. |
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — a tolerant pre-scan of the executable on disk naming the block's family (`Refused { reason, family, signal }` unless the guard let exactly that family through) and the successful Tier-1 sessions (`Refused { reason: "TooFewSessions", signal: <count> }` under two) — and the store writes the grant only over facts that make the game eligible → `AntiCheatExceptionAck { granted, outcome, family }`. **A grant turns nothing on**: hooking is FR-2.1's `SetHookEnabled`, afterwards. Not answered (`UnknownType`) by an Agent composed without the exception. |
| `PauseCapture` / `ResumeCapture` | UI→A | global → `PauseAck { paused }`; `StatusAck.paused` reports it. *(Built 2026-09-13, PR-1b: one in-memory flag, `CapturePause`, read by every session loop at its tick and told to the ring once per transition; supervision — the guard scan, the kill switch, the safety stop — never pauses. Not persisted: an Agent that restarts resumes.)* |
| `StopSession` | UI→A | `{ sessionGuid }` — graceful ~~unhook~~ stop + finalize → `StopAck { sessionGuid, accepted, reason? }`. *(Built 2026-09-13, PR-1b: the orchestrator names every session it starts and cancels THAT session's stop token; the loop reads it at its next tick, drains once more, and ends as `SessionEndReason.StoppedByUser` — `exit_status = normal`, the row stored like any other, the target left running. A guid nobody runs is `accepted: false`. Distinct from the host's cancellation, which leaves a `.partial`.)* |
| `UpdateRules` | UI→A | **no payload** — a trigger, not a source. The Agent re-reads only its own `%LOCALAPPDATA%\FrameLedger\rules\` copy → `UpdateRulesAck { outcome }`. *(Built 2026-09-13, PR-1b: the seeder's `EnsureSeededAsync` outcome; a payload naming a path is ignored, and a test sends one to prove it.)* |
+25
View File
@@ -224,6 +224,23 @@ All screens are `Page`s registered with the navigation page provider and navigat
> blocked row: its one action could only be refused. Tests: `GameDetailViewModelTests` (hidden, shown, the card
> pill), `BlockedReasonTextTests`, `PagesLoadTests.AnAntiCheatGamesPageRendersTheFindingInPlaceOfTheHookingCard`.
>
> **The user-mode exception (2026-09-26, beta.9, owner decision D33).** While Settings' option is on, a blocked
> game's page shows a **User-mode exception** card with the Agent's answer about it (`Services.ExceptionView` over
> `GameRow.AcException` — the App reads those columns and writes none): *Eligible — no exception made* with **Make
> exception…**; *Checking…* until the Agent has looked at this block; *Not eligible: N successful hooked session(s), two
> are needed*; *Not eligible: the guard also found {family} ({signal})* — Aniimo's *Kernel driver in the game folder
> (NEPKernel.sys)*; *Not eligible: {family} is not user-mode throughout*; and how the last exception ended. **Make
> exception…** opens the exception's disclosure (`AntiCheatExceptionPrompt`, text `Safety_Exception_*` versioned by
> `AntiCheatExceptionDisclosure.Version`, the primary button bound to the ticked *I accept the risk of a ban for this
> game*, Enter = *Keep it blocked*) and then `SetAntiCheatException`; the Agent gathers the facts and grants or
> refuses, and the page says which. An exception in force brings the Hooking card back — even while anti-cheat cards
> are hidden — with its switch usable through FR-2.1's dialog as ever, the finding still under it; **Withdraw
> exception** ends it and turns hooking off. With the option off a kept exception is shown *suspended* and the switch
> is disabled again. The library card says **Exception** for a game carrying one; a hooked session under it is
> *Hooked · exception* in the Sessions tab (the tooltip names the family) and its summary has one line saying so.
> Tests: `GameDetailViewModelTests.AnEligibleGameOffersTheExceptionAndOneInForceMakesTheSwitchUsable`,
> `…WhyAGameIsNotEligibleIsSaidOnItsPage`, `AntiCheatExceptionsTests`.
>
> **Details (2026-09-25, beta.8, schema 0011).** A `ui:CardExpander` **Details** under the two rows, expanded, says
> what the game's files and its store say (`05_DETECTION` §What the files say about themselves): *Runs as* (64-bit
> (x64) · 32-bit (x86) · ARM64 · .NET, any CPU (runs as 64-bit) · …), *File version* and *Product version* (the
@@ -449,6 +466,14 @@ Agent section: elevation state with a plain explanation of what elevation *optio
> **2026-09-25 (beta.8):** Capture gained *Hide hooking on anti-cheat games* (`ui.hide_anticheat_hooking`, on by
> default) between the kill switch and the Vulkan layer row — §Games says what it hides; the game's page reads it at
> each load. It hides a control that could only be refused, never the finding.
>
> **2026-09-26 (beta.9, D33):** Capture gained *Allow hooking in games with user-mode anti-cheat that were measured
> before* (`hooking.usermode_ac_exceptions`, off by default), below the hide switch, and under it the **User-mode
> exceptions** list — the games the Agent found eligible (**Make exception…**), held back only by the session count,
> or carrying an exception (**Withdraw**), each with its finding, its successful hooked sessions and its state; with
> the option off only kept exceptions are listed, *suspended*. *Checking…* shows until the Agent has answered about
> every blocked game, and **Refresh** re-reads the list (the Agent's sweep runs every 15 s). The option is an
> Agent-read key and takes effect at the next session start and command.
### First-run flow
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept.
+3
View File
@@ -62,6 +62,9 @@ Consent, refusal, and safety-unhook text (FR-2.1, `19_SAFETY`) is **reviewed lik
- No machine-drafted `ja` in this category — a mistranslated ban warning is a real harm. These keys are marked `<comment>safety: human review required</comment>` and ~~the `ja` build fails the resx audit until a human reviewer signs off; until then the `en` string is shown as fallback rather than an unreviewed translation~~ **as built (2026-09-13): the audit is red on a `Safety_*` key in `ja` that carries neither `safety: human review required` nor `safety: reviewed by <name>`, and red on one marked review-required whose value is anything but the `en` string verbatim** — the key-set rule forbids leaving it out, so "shown as `en` until signed" is true by construction (the value IS the English), not by a runtime fallback. Signing = replacing the comment with `safety: reviewed by <name>` beside the reviewed text.
- Never soften the wording per locale. "May result in a permanent ban of your account" must survive translation with the same force in all three languages.
- Key prefix `Safety_*` so they are easy to audit as a group.
- **`Safety_Exception_*` (2026-09-26, D33)** is the user-mode exception's disclosure: the same rules — `ja` ships the
English verbatim marked for review — and its own version, `AntiCheatExceptionDisclosure.Version`, bumped when any of
those strings changes meaning, exactly as `SafetyDisclosure.Version` is for `Safety_Consent_*`.
> **What is in scope, stated 2026-08-06 because a binary now exists that is not.** These rules
> govern the **shipped** application's user-visible strings — what `12_BUILD` §Publish & package
+10
View File
@@ -57,6 +57,16 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
> them and the loader does not list them. Body under `FL_HOOK_GUARD`, no allocation, no lock, no
> logging (rule 5). Exercised by `hook-harness --load-after-ms N PATH` (up to four), against the real
> Overlay in a real target, both jobs.
>
> **D33 (2026-09-26): one family may be tolerated.** Before `InstallLoaderHook`, `InitThread` reads
> `Local\FrameLedger.Tolerate.<pid>` once (`fl_tolerance.h`; absent = nothing tolerated, the ordinary case),
> resolves each name against its OWN compiled floor, honours only a family whose whole footprint there is
> user-mode (`fl::guard::FamilyIsUserModeOnly`) and keeps a 64-bit mask over the floor's module families. The
> detour's only change is one bit test before (b): a tolerated family's module loading late is not an early stop.
> **Overhead:** one relaxed-acquire `uint64` load, a shift and a compare, on the floor-match branch alone — a branch
> that fires approximately never — and nothing on the present path; the tolerance is read on the init thread, not in
> a hook body (and logged there as `TOLERANCE`). ctest `fl_guard` `[D33]` loads a decoy `NEP2.dll` 2.5 s in: the
> Overlay keeps recording when the mapping names NetEase Yidun, and stops when it names Easy Anti-Cheat.
4. Install present hooks for what exists (below).
5. Install feature hooks (upscaler / RT / PSO) lazily — the first time their module appears.
6. Publish `status = ready` in the handshake block.
+68 -3
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 "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.)*
- Any "bypass" setting, "stealth mode", or documentation explaining how to defeat the guard below. *(The first two words left this line on 2026-09-21 and returned on 2026-09-22 — §What a finding does to the game. The one exception the owner has granted since, D33 on 2026-09-26, is not a bypass: the guard still runs every check and decides itself which family is user-mode — §The user-mode exception.)*
- Reading or writing game memory outside the arguments of APIs we hooked
- Kernel drivers of our own
@@ -394,7 +394,7 @@ 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.** ~~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.
> **There is no override.** ~~There is one, since 2026-09-21, and it is none of the things this paragraph named~~ *(one day; withdrawn 2026-09-22)*: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below — and since 2026-09-26 (D33), one narrow, evidence-bound exception for anti-cheat that is user-mode throughout, which lets a named family through while every check still runs (§The user-mode exception).
### What a finding does to the game — owner decision 2026-09-22
@@ -455,7 +455,8 @@ card is back with the finding under its disabled switch. The finding itself is o
**What clears it.** Nothing, as before: the block outlives *Change executable* and a re-import (§A game already enabled
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
switch.
switch. *(Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
exception.)*
**D21 stands as a fact.** A process an anti-cheat driver protects is `SessionEndReason.TargetUnreadable` (2026-09-21:
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
@@ -467,6 +468,70 @@ still finds the injection primitives in exactly that file and the evasion primit
to four methods (`NoSecondMatcherTests`). `FloorFamilies` is untouched.
### The user-mode exception — owner decision 2026-09-26 (D33)
**Why it exists.** The beta.8 library sweep turned hooking off for *GIRLS' FRONTLINE 2: EXILIUM* on a documented,
unmeasured rule — NetEase Yidun, `AntiCheatFile NEP2.dll` — after FrameLedger had measured that game hooked (three
normal Tier-1 sessions in the owner's ledger, 474,143 frames). The owner asked for a way to keep measuring a game like
that, and chose, against the rule this document had kept since 2026-09-22 and with that rule quoted back to them, **an
exception the user grants per game, bound to evidence, and only for anti-cheat that is user-mode throughout.** The
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — an exception is only
offered where FrameLedger has already measured the game hooked; it "only exposed the user to the risk its own disclosure
described" — that risk stands, and the disclosure says so, including that a ban can arrive days later and that FrameLedger
cannot know.
**What may be excepted — all of it must hold:**
- every finding about the game is `BlockedModule`, `AntiCheatFile` or `AntiCheatDirectory` of **one** family;
- that family's whole footprint is user-mode — no `drivers` entry, no `services` entry and no `*.sys` among its `files`, in
the compiled floor or the rules file (`fl::guard::FamilyIsUserModeOnly`). The floor cannot be shrunk, so data can make a
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain and
FredaikisAntiCheat; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
other family carry a driver or a service and are never excepted;
- no `*.sys` anywhere in the install tree — the kernel-driver rule (D30) is never excepted, whichever family a driver
belongs to (so *Aniimo*, which unpacks `NEPKernel.sys` beside `NEP2.dll` on its first run, stays blocked);
- the game is on no title list (`BlockedExecutable`, `BlockedStoreId` — the notorious titles are there by design);
- the ledger holds **at least two successful Tier-1 sessions** of the game: hooked, frames recorded, `exit_status = normal`
(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.
**Never excepted, whatever the user ticked:** a machine-wide `BlockedDriver` or `BlockedService`, the fuzzy tier
(`SuspiciousUnsigned`), a scan that could not look or finish, unusable rules, `TargetUnreadable` (D21), a 32-bit target,
the kill switch, and a Vulkan target (the implicit layer's own self-scan stays strict).
**How the guard takes it.** The four evaluating ABI entries carry `toleratedFamilies` — a NAME, never evidence
(`fl_guard_abi.h`). The guard resolves it against its own rules (`ResolveTolerance`), keeps only a user-mode family,
runs every check, lets that family's modules, files and folders through **and keeps scanning past them**, so a second
family, a suspicious module or a `.sys` further in still refuses. A pass that let something through is
`kAllowedUserModeException` (reason 28, the slot the withdrawn bypass left) with the family and the signal; the session it
starts is marked with them.
**How the Overlay takes it.** The Overlay stops observing when a floor module loads after injection, so the Agent
publishes the exception's family names in `Local\FrameLedger.Tolerate.<pid>` (`fl_tolerance.h`) before it asks the guard
to inject, and the Overlay's init thread reads them once, before its loader detour exists — resolving each against its
own compiled floor and honouring only a user-mode family. A mapping that names anything else tolerates nothing, and the
Agent's 30 s re-scan keeps judging every other signal.
**What ends it.** A new finding outside the excepted family at any of the four moments above writes the block as before
and revokes the exception; a session under it that crashes, is unhooked for safety or is stopped by the Overlay's
in-process floor stop revokes it; an executable change ends it with the consent it shared a fingerprint with; turning
the option off suspends every exception. **The block itself is never cleared** — the exception is a separate layer over
it, and the finding stays on the game's page (FR-2.2).
**What it is not.** Not a bypass of a live refusal, not a global switch (a Settings option off by default enables the list,
and the user ticks each game), not reachable from the command line, and not evasion: the DLL stays `LoadLibraryW`-loaded,
named and visible (rule 3). `InjectViaLoadLibrary` still has internal linkage in `fl_guard.cpp`; `tools/chokepoint-check.ps1`
is unchanged.
*Built in beta.9. PR-1: the guard's tolerance and the Overlay's channel. PR-2: the Agent — the option
(`hooking.usermode_ac_exceptions`, off), the sweep's eligibility pass (a tolerant pre-scan keyed on the rules, the
executable and the block; the session count every pass), the `SetAntiCheatException` command (the Agent gathers the
facts itself; the store applies the rule), the gate's one branch with the channel published before the request, the
re-scans naming the family, the session's mark, and every end (`UserModeExceptionLapse`) — schema 0014. PR-3: the
option and the list in Settings, the versioned disclosure (`Safety_Exception_*`, `AntiCheatExceptionDisclosure`), the
game page's exception card and its usable switch under an exception in force, the marks, and the legal text
(Disclaimer §2A 2.7, EULA 1.3, the accuracy block, SECURITY.md) — `08_UI` §Games.*
### The floor data cannot remove
**There was a local bypass, and this paragraph is the reason it no longer works
+10
View File
@@ -40,6 +40,16 @@ Rules for this document:
> where it could inject it only exposed the user. The owner asked for the opposite: a finding turns the game's hooking
> off, wherever the guard makes it. `19_SAFETY` §What a finding does to the game is the specification; CLAUDE.md rule 2 is
> unstruck. The two open items above (kernel-level families, the ja text) are moot.
>
> **2026-09-26 — one narrow exception, by owner decision D33, with the 2026-09-22 withdrawal quoted back.** Beta.8's
> library sweep blocked a game FrameLedger had measured hooked (GIRLS' FRONTLINE 2: EXILIUM, NetEase Yidun `NEP2.dll`),
> and the owner chose an evidence-bound, per-game exception for anti-cheat that is user-mode throughout (`19_SAFETY`
> §The user-mode exception; CLAUDE.md rule 2's amendment). The two reasons D22 gave are answered: it is offered only
> where FrameLedger has already measured the game hooked, and its risk is stated in its own disclosure. **What stays
> open, and is the owner's:** the `ja` text of `Safety_Exception_*`, which ships as English until a reviewer signs;
> whether a family the rules file makes kernel-level later should end existing exceptions at once (today it does, at
> the sweep's next pass and at every session start); and a real-hardware check that NEP2.dll's load time relative to
> the injection is covered on the owner's machine (the ctest decoy covers the late load).
| # | Decision | Consequence |
|---|---|---|
+48 -1
View File
@@ -1558,7 +1558,7 @@ và legal"), so the Legal Gate shows both once.
## 2026-09-25 — the beta.8 train
*Status is `CHANGELOG.md` `[Unreleased]` (then `[0.1.0-beta.8]`); this is what no other file carries. The owner's list
*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.*
@@ -1640,6 +1640,53 @@ only be refused, never the finding (FR-2.2).
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.
## 2026-09-26 — the beta.9 train: the user-mode exception (D33)
*Status is `CHANGELOG.md` `[Unreleased]` (then `[0.1.0-beta.9]`); this is what no other file carries. The approved plan
is four PRs: PR-1 the guard's tolerance and the Overlay's channel, PR-2 the Agent (eligibility, gate, records, schema
0014, IPC), PR-3 the App, strings, docs and legal text, PR-4 the release.*
**Decision (D33, owner, 2026-09-26, asked with rule 2 and D22 quoted back).** The beta.8 sweep turned hooking off for
GIRLS' FRONTLINE 2: EXILIUM (NetEase Yidun, `AntiCheatFile NEP2.dll`, a documented and unmeasured rule) after it had
been measured hooked; the owner asked for an exception list for user-mode anti-cheat games measured at Tier 1 before.
Chosen, all four options as recommended: **evidence-bound, per game** (a Settings option off by default, then the user
ticks each eligible game); **≥ 2 successful Tier-1 sessions**; **Aniimo stays blocked** (it unpacks `NEPKernel.sys` beside
`NEP2.dll` — the D30 `.sys` rule is never excepted); **the legal text changes** (Disclaimer §2A 2.7, EULA 1.3, the
accuracy block, SECURITY.md, FR-2.3; Privacy stays 2.4). Eligibility, what is never excepted and every lapse are in
`19_SAFETY` §The user-mode exception; the rule-2 amendment is in CLAUDE.md.
**Evidence it rests on (read from a COPY of the owner's ledger and their logs, 2026-09-26).** GF2: three normal Tier-1
sessions under the current entry (474,143 frames; three more from 2026-09-21 went with a removed entry), no `.sys` in
its tree. Aniimo: one Tier-1 session stored `crashed` (End task before beta.8, no exit code kept). A randomly named
kernel driver (`lyoxztfx.sys`) was installed on 2026-09-21 at 15:38 and is gone now, service and file, by something
the logs cannot name — the residual the disclosure states: a driver outside the game folder that no rule names is
invisible to every check.
**Traps met on the way:**
- **The ring cannot carry anything the Overlay needs before its detour is armed** — the Overlay creates it. Hence the
separate `Local\FrameLedger.Tolerate.<pid>` mapping the Agent creates BEFORE the injection (`fl_tolerance.h`).
- **A tolerant scan must keep scanning.** Every sink that used to stop at the first hit returns `true` on a tolerated
one, or a second family / a `.sys` further in would pass: the same load-order fail-open §S22(b) closed for the
exemption.
- **A prefix value of a user-mode family can match a `.sys`**; the tolerant file sink refuses any `.sys` itself.
- **CA2101 rejects `[MarshalAs(LPUTF8Str)] string`** on a P/Invoke; the tolerance crosses as NUL-terminated UTF-8
`byte[]`, the shape `FlGuardCheckRules` already used.
- **The Vulkan branch evaluates strictly**: the layer's self-scan goes inert on any anti-cheat module, so an exception
there could only buy a session that measures nothing.
- **An elevated Agent's default DACL omits the user** (`PipeAccessControl`'s remarks): a tolerance mapping created with
it could not be opened by the Overlay in an unelevated game, and the exception would fail as the Overlay's own stop.
`OverlayToleranceChannel` states `O:<user>D:P(A;;GR;;;<user>)`; a test proves the user can read it and nobody can
open it to write.
- **`hook_enabled` can be 1 on a blocked row now** — only because an exception once applied. `CaptureSession.RunAsync`
therefore treats a blocked row whose exception does not apply right now as hooking-off BEFORE the resolver opens
anything, or the option off would reopen the Borderless-Gaming problem of 2026-09-22.
- **The store applies the eligibility rule itself** (`GrantAntiCheatExceptionAsync` answers `NotEligible`), and the
grant and the eligibility are bound in SQL to the block text they were reached about: a block rewritten between the
read and the write leaves the row alone. SQLite evaluates every `SET` from the old row, which is what lets
`ChangeExecutableAsync`'s `CASE WHEN ac_exception_at IS NOT NULL` record the end of the grant it clears.
- **CA1711 rejects a type whose name ends in `Exception`**: the rules class is `UserModeExceptionRules`, the reasons
`UserModeExceptionLapse`.
## Owner-only — no PR can close these
1. **§S23-2 — branch protection.** `Rules / validate` is not a required status check on
+14 -7
View File
@@ -11,8 +11,8 @@
that changes what FrameLedger.Overlay or the capture host does; date the change.
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-09-23.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.7`** (2026-09-23), an unsigned installer built from that tag with its
> ⚠ **What FrameLedger actually measures today — 2026-09-26.** 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
@@ -30,7 +30,9 @@
> 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)*. Intel XeSS is **not** read (its SDK licence
> 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
@@ -51,7 +53,8 @@
> 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.
> **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
@@ -68,9 +71,13 @@
> 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, in its folder or on its title lists — turns hooking off for that game, whether found
> 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.
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
> runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
+34 -12
View File
@@ -1,6 +1,6 @@
# FrameLedger — Disclaimer
**Version:** 2.6 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.7 · **Effective:** {{RELEASE_DATE}}
> **How this document is kept true.** The statement of what FrameLedger measures (§4) is `legal/ACCURACY.md`,
> embedded here and in `README.md` and bound to its source by `tools/accuracy-check.ps1`, which fails the build when a
@@ -53,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.** 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.
- Before injecting, and every 30 seconds afterwards, FrameLedger scans for known anti-cheat and anti-tamper components. **If it finds one, it refuses to inject; if a session is already running, it stops at the next scan.** No setting turns this off, globally or per game; the one exception you can make yourself, per game, still runs every check and is described in §2A. Because the scan runs every 30 seconds rather than continuously, anti-cheat that loads mid-session may be present for **up to 30 seconds** before FrameLedger detects it and stops.
**And there is a second, longer window you should know about.** The part of FrameLedger running inside the game also stops on its own if it loses contact with the part doing the scanning — because a scanner that has stopped cannot protect you. It waits **65 seconds** before concluding that contact is lost, so that one delayed scan on a busy machine does not end your session. In the worst case those windows combine: if the scanner stops at the moment anti-cheat appears, the component inside the game may keep running for up to **65 seconds** afterwards. That number is 65 and not 30, and this document says so rather than leaving the 30 above to imply it.
@@ -79,13 +79,28 @@ 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
## 2A. There is no way past the guard — and one narrow exception you can make yourself
Versions 0.1.0-beta.3 and 0.1.0-beta.4 offered a per-game switch to overrule the guard. **It has been removed.** If
FrameLedger finds anti-cheat or anti-tamper software in a game — before it injects, when a session starts, or during a
session — it refuses, turns hooking off for that game, and says so on the game's page. There is no setting, per game or
global, that turns that back on for that executable. Sessions recorded under the earlier switch stay in your database,
marked as such in their notes.
global, that overrules that. Sessions recorded under the earlier switch stay in your database, marked as such in their
notes.
**Since 0.1.0-beta.9 there is one exception, and it is not a way past the guard.** A Settings option, off unless you
turn it on, lets you make an exception — one game at a time, after a disclosure you must accept — for a game whose only
finding is a single anti-cheat that works entirely in user mode (no kernel driver, no service, and no driver file
anywhere in the game's folder), that is on no list of titles FrameLedger refuses, and that FrameLedger has already
measured successfully at least twice. Under it the guard still runs every check, before injecting and every 30
seconds, and still refuses anything else it finds; the exception ends by itself when something new is found, when a
session under it crashes or is stopped for safety, or when the game is updated, and turning the option off suspends
it. Sessions recorded under it are marked with the anti-cheat they ran beside.
**It exists because users asked for it, and it carries exactly the risk this document describes.** That anti-cheat
may still detect FrameLedger in the game and warn, block or permanently ban your account — possibly days later — and
FrameLedger cannot know whether it did. Earlier sessions that went well are no promise about the next one. **Do not
use it with a game you play online or competitively unless you accept losing that account;** the developer cannot
reverse a ban.
## 3. Stability
@@ -97,8 +112,8 @@ Software running inside another process can, in principle, destabilize it. Frame
Frame timing is derived from high-resolution timestamps taken at the moment the game presents each frame; upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs. This is substantially more accurate than inferring settings from files on disk, but **no measurement is guaranteed to be exact**:
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-23.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.7`** (2026-09-23), an unsigned installer built from that tag with its
> ⚠ **What FrameLedger actually measures today — 2026-09-26.** 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
@@ -116,7 +131,9 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> 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)*. Intel XeSS is **not** read (its SDK licence
> 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
@@ -137,7 +154,8 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> 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.
> **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
@@ -154,9 +172,13 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> 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, in its folder or on its title lists — turns hooking off for that game, whether found
> 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.
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
> runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
+2 -2
View File
@@ -1,6 +1,6 @@
# FrameLedger — End User License Agreement (EULA)
**Version:** 1.2 · **Effective:** {{RELEASE_DATE}}
**Version:** 1.3 · **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.
@@ -14,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, turns hooking off for that game, and provides no means to override that refusal (Disclaimer §2A).
To measure rendering settings accurately, the Software can load a component into a game process, **but only for games you have individually enabled**, after a consent prompt that explains the risk. The Software refuses to do so when it detects anti-cheat or anti-tamper software, turns hooking off for that game, and provides no means to override that refusal — except a narrow, per-game exception for anti-cheat that works entirely in user mode, which you may make yourself, after a separate disclosure, for a game the Software has already measured successfully, and under which the Software still runs every check (Disclaimer §2A). By making such an exception you accept, for that game, the risk described in (b) below.
By enabling this feature for a game, you confirm that:
+5 -3
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.3 · **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.**
@@ -9,7 +9,7 @@
Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
- Your game library entries (names, executable paths, metadata you or the app filled in, and whether each one is recorded).
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, memory usage), session duration, crash flags, tags and notes you write.
- 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 (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.
@@ -37,11 +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 — 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); 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 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.
@@ -25,7 +25,9 @@ internal static class AgentIdentityFactory
// 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);
DisclosureVersion: SafetyDisclosure.Version,
// D33: the user-mode exception's disclosure, under the same rule.
ExceptionDisclosureVersion: AntiCheatExceptionDisclosure.Version);
}
private static string Version()
@@ -35,6 +35,9 @@ internal sealed class AgentRecording
private readonly CapturePause _pause;
private readonly IRecorderPolicy _policy;
private readonly IDriverProfileSource _profiles;
private readonly IUserModeExceptionSwitch _exceptions;
private readonly IOverlayToleranceChannel _tolerance;
private readonly UserModeExceptionLapsePolicy _exceptionLapse;
public AgentRecording(
IGameConsentStore store,
@@ -55,9 +58,15 @@ internal sealed class AgentRecording
ISessionObserver observer,
CapturePause pause,
IRecorderPolicy policy,
IDriverProfileSource profiles)
IDriverProfileSource profiles,
IUserModeExceptionSwitch exceptions,
IOverlayToleranceChannel tolerance,
UserModeExceptionLapsePolicy exceptionLapse)
{
_profiles = profiles;
_exceptions = exceptions;
_tolerance = tolerance;
_exceptionLapse = exceptionLapse;
_store = store;
_gate = gate;
_guard = guard;
@@ -108,7 +117,8 @@ internal sealed class AgentRecording
new RecorderOptions { MinimumSessionLength = minimum, PartialFlushInterval = flush },
_observer,
_policy,
_profiles);
_profiles,
_exceptionLapse);
}
/// <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>
@@ -174,7 +184,9 @@ internal sealed class AgentRecording
launcher,
observer,
_killSwitch,
_pause);
_pause,
_exceptions,
_tolerance);
/// <summary>The session and its collaborators, wired the only way the Agent allows; the recorder supplies the observer.</summary>
private sealed class Factory(AgentRecording owner, int seconds, IProcessLauncher? launcher) : ICaptureSessionFactory
@@ -70,6 +70,7 @@ internal static class AgentServices
services.AddSingleton<IRecorderPolicy, SettingsRecorderPolicy>();
services.AddSingleton<SettingsKillSwitch>();
services.AddSingleton<IKillSwitch>(static sp => sp.GetRequiredService<SettingsKillSwitch>());
AddUserModeException(services);
// The gate and the guard: one native facade, one managed gate in front of it.
services.AddSingleton<IAntiCheatGuard, NativeAntiCheatGuard>();
@@ -111,6 +112,18 @@ internal static class AgentServices
return services;
}
/// <summary>
/// D33 (owner decision 2026-09-26): the user-mode exception's option (one row in <c>settings</c>), its channel to the
/// Overlay (<c>Local\FrameLedger.Tolerate.&lt;pid&gt;</c>, created before an injection under it), and the policy that ends
/// it when a session under it ends badly.
/// </summary>
private static void AddUserModeException(IServiceCollection services)
{
services.AddSingleton<IUserModeExceptionSwitch, SettingsUserModeExceptionSwitch>();
services.AddSingleton<IOverlayToleranceChannel>(static _ => new OverlayToleranceChannel(static line => Serilog.Log.Information("{Line}", line)));
services.AddSingleton(static sp => new UserModeExceptionLapsePolicy(sp.GetRequiredService<IGameConsentStore>()));
}
/// <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
@@ -165,7 +178,10 @@ internal static class AgentServices
sp.GetRequiredService<IExecutableIdentitySource>(),
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<IIpcEventPublisher>(),
id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)));
id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id),
// D33: the evidence and the option the user-mode exception's eligibility needs.
sp.GetRequiredService<ISessionRepository>(),
sp.GetRequiredService<IUserModeExceptionSwitch>()));
// 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
@@ -197,33 +213,7 @@ internal static class AgentServices
// host's under --serve and a logged no-op under --console (TryAdd: --serve registers its own first).
services.AddSingleton<CapturePause>();
services.TryAddSingleton<IAgentLifetime, NoAgentLifetime>();
services.AddSingleton(static sp => new AgentCommandHandler(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IGameConsentStore>(),
sp.GetRequiredService<IAntiCheatGuard>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
sp.GetRequiredService<CaptureOrchestrator>(),
sp.GetRequiredService<CapturePause>(),
sp.GetRequiredService<IAgentLifetime>(),
// UpdateRules: re-seed the rules file, then wake the detection sweep (P4 PR-1) — a rules change is the
// re-run trigger 05_DETECTION §Caching names, so the games table follows within the same second.
async ct =>
{
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.
SafetyDisclosure.Version,
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),
sp.GetRequiredService<ExecutableRelocator>(),
// beta.8: an executable that cannot run as x64 is refused before anything is scanned or stamped.
new PeArchitectureSource()));
services.AddSingleton(static sp => CommandHandler(sp));
services.AddSingleton<IIpcRequestHandler>(static sp => new AgentRequestHandler(
AgentIdentityFactory.OfThisProcess(sp.GetRequiredService<AgentPaths>().VkLayerDirectory),
TelemetryDescriptor(),
@@ -250,6 +240,41 @@ internal static class AgentServices
}
/// <summary>The command half of the pipe (P3 PR-1b) over the Agent's own adapters — every command it answers, D33's included.</summary>
private static AgentCommandHandler CommandHandler(IServiceProvider sp) =>
new AgentCommandHandler(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IGameConsentStore>(),
sp.GetRequiredService<IAntiCheatGuard>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
sp.GetRequiredService<CaptureOrchestrator>(),
sp.GetRequiredService<CapturePause>(),
sp.GetRequiredService<IAgentLifetime>(),
// UpdateRules: re-seed the rules file, then wake the detection sweep (P4 PR-1) — a rules change is the
// re-run trigger 05_DETECTION §Caching names, so the games table follows within the same second.
async ct =>
{
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.
SafetyDisclosure.Version,
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),
sp.GetRequiredService<ExecutableRelocator>(),
// beta.8: an executable that cannot run as x64 is refused before anything is scanned or stamped.
new PeArchitectureSource(),
// D33: the user-mode exception's option, evidence and disclosure version.
new AntiCheatExceptionCommands(
sp.GetRequiredService<IUserModeExceptionSwitch>(),
sp.GetRequiredService<ISessionRepository>(),
AntiCheatExceptionDisclosure.Version));
/// <summary>
/// <c>HelloAck.telemetrySource</c>: the layers this machine composes, read once on the first <c>Hello</c> by
/// standing the composite up and taking it down again — a library start, which is why it is not done at
+4
View File
@@ -274,6 +274,10 @@ public partial class App : System.Windows.Application
// 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>();
builder.Services.AddSingleton<HookingConsent>();
// D33 (owner decision 2026-09-26): the user-mode exception's disclosure and the request it ends in; the list is
// Settings', the button on a blocked game's page.
builder.Services.AddSingleton<IAntiCheatExceptionPrompt, AntiCheatExceptionPrompt>();
builder.Services.AddSingleton<AntiCheatExceptions>();
AddLibrary(builder.Services);
@@ -0,0 +1,37 @@
<UserControl x:Class="FrameLedger.App.Dialogs.AntiCheatExceptionDialogContent"
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:vm="clr-namespace:FrameLedger.App.ViewModels"
d:DataContext="{d:DesignInstance Type=vm:AntiCheatExceptionDialogViewModel}"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
MaxWidth="640">
<!--
D33's disclosure (19_SAFETY §The user-mode exception), text from FrameLedger.Shared's Safety_Exception_* only,
versioned by AntiCheatExceptionDisclosure.Version. It states why the exception is offered, the risk, what is still
refused, how it ends, and that it turns nothing on; it recommends neither choice. Every colour is a theme brush.
-->
<ScrollViewer MaxHeight="520" VerticalScrollBarVisibility="Auto">
<StackPanel>
<ui:TextBlock Text="{Binding Intro}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,14,0,0" Text="{Binding Why}" TextWrapping="Wrap" />
<Border Margin="0,14,0,0" Padding="12" CornerRadius="6" Background="{DynamicResource CardBackgroundFillColorDefaultBrush}">
<ui:TextBlock FontWeight="SemiBold" Text="{Binding Risk}" TextWrapping="Wrap" />
</Border>
<ui:TextBlock Margin="0,14,0,0" Text="{Binding Still}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" Text="{x:Static vm:AntiCheatExceptionDialogViewModel.Ends}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" Text="{x:Static vm:AntiCheatExceptionDialogViewModel.Next}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" FontWeight="SemiBold" Text="{x:Static vm:AntiCheatExceptionDialogViewModel.Online}" TextWrapping="Wrap" />
<CheckBox x:Name="Acceptance"
Margin="0,18,0,0"
AutomationProperties.Name="{x:Static vm:AntiCheatExceptionDialogViewModel.AcceptText}"
Content="{x:Static vm:AntiCheatExceptionDialogViewModel.AcceptText}"
IsChecked="{Binding Accepted, Mode=TwoWay}" />
</StackPanel>
</ScrollViewer>
</UserControl>
@@ -0,0 +1,18 @@
using System.Windows.Controls;
using FrameLedger.App.ViewModels;
namespace FrameLedger.App.Dialogs;
/// <summary>The body of D33's <c>ContentDialog</c>; the buttons are the dialog's own (<see cref="Services.AntiCheatExceptionPrompt"/>).</summary>
public partial class AntiCheatExceptionDialogContent : UserControl
{
public AntiCheatExceptionDialogContent(AntiCheatExceptionDialogViewModel viewModel)
{
ViewModel = viewModel ?? throw new ArgumentNullException(nameof(viewModel));
DataContext = viewModel;
InitializeComponent();
Loaded += (_, _) => Acceptance.Focus();
}
public AntiCheatExceptionDialogViewModel ViewModel { get; }
}
@@ -150,6 +150,33 @@
</ui:CardControl.Header>
</ui:CardControl>
<!-- D33 (owner decision 2026-09-26): the user-mode exception on a blocked game, its state the Agent's (19_SAFETY §The user-mode exception) -->
<ui:CardControl Margin="0,12,0,0" Icon="{ui:SymbolIcon ShieldTask24}"
Visibility="{Binding ViewModel.ExceptionCardVisible, Converter={StaticResource BoolToVis}}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static vm:GameDetailViewModel.ExceptionHeader}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionText}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionInForceText}"
Visibility="{Binding ViewModel.ExceptionInForceText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionSuspendedText}"
Visibility="{Binding ViewModel.ExceptionSuspendedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Appearance="Tertiary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionLapseText}"
Visibility="{Binding ViewModel.ExceptionLapseText, Converter={StaticResource NullToCollapsed}}" />
</StackPanel>
</ui:CardControl.Header>
<StackPanel Orientation="Horizontal">
<ui:Button Appearance="Secondary"
Command="{Binding ViewModel.GrantExceptionCommand}"
Content="{x:Static vm:GameDetailViewModel.GrantExceptionText}"
Visibility="{Binding ViewModel.CanGrantException, Converter={StaticResource BoolToVis}}" />
<ui:Button Appearance="Secondary"
Command="{Binding ViewModel.WithdrawExceptionCommand}"
Content="{x:Static vm:GameDetailViewModel.WithdrawExceptionText}"
Visibility="{Binding ViewModel.CanWithdrawException, Converter={StaticResource BoolToVis}}" />
</StackPanel>
</ui:CardControl>
<!-- hooking control (FR-2.1 / FR-2.2 / FR-2.5) -->
<StackPanel Visibility="{Binding ViewModel.HookingSectionVisible, Converter={StaticResource BoolToVis}}">
<ui:CardControl Margin="0,12,0,0" Header="{x:Static vm:GameDetailViewModel.HookingHeader}" Icon="{ui:SymbolIcon ShieldTask24}">
@@ -66,6 +66,68 @@
IsChecked="{Binding ViewModel.HideAntiCheatHooking, Mode=TwoWay}" />
</ui:CardControl>
<!-- D33 (owner decision 2026-09-26): the user-mode anti-cheat exception — the option, off by default, and the games it concerns. -->
<ui:CardExpander Margin="0,8,0,0" IsExpanded="{Binding ViewModel.UserModeExceptions, Mode=OneWay}" Icon="{ui:SymbolIcon ShieldTask24}">
<ui:CardExpander.Header>
<Grid>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="Auto" />
</Grid.ColumnDefinitions>
<StackPanel Grid.Column="0">
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Exceptions_Label}" TextWrapping="Wrap" />
<ui:TextBlock MaxWidth="520" HorizontalAlignment="Left" Appearance="Secondary" TextWrapping="Wrap"
Text="{x:Static res:Strings.Settings_Exceptions_Body}" />
</StackPanel>
<ui:ToggleSwitch Grid.Column="1" Margin="12,0" AutomationProperties.Name="{x:Static res:Strings.Settings_Exceptions_Label}"
IsChecked="{Binding ViewModel.UserModeExceptions, Mode=TwoWay}" />
</Grid>
</ui:CardExpander.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Exceptions_Header}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static res:Strings.Settings_Exceptions_Suspended}"
Visibility="{Binding ViewModel.ExceptionsSuspended, Converter={StaticResource BoolToVis}}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static res:Strings.Settings_Exceptions_Checking}"
Visibility="{Binding ViewModel.ExceptionsChecking, Converter={StaticResource BoolToVis}}" />
<ui:TextBlock Appearance="Secondary" Text="{x:Static res:Strings.Settings_Exceptions_Empty}"
Visibility="{Binding ViewModel.ExceptionGames.Count, Converter={StaticResource ZeroToVisible}}" />
<ItemsControl ItemsSource="{Binding ViewModel.ExceptionGames}">
<ItemsControl.ItemTemplate>
<DataTemplate>
<Grid Margin="0,6">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="Auto" />
</Grid.ColumnDefinitions>
<StackPanel Grid.Column="0">
<ui:TextBlock FontTypography="BodyStrong" Text="{Binding Name}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding FindingText}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding SessionsText}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding StateText}" />
<ui:TextBlock Appearance="Tertiary" TextWrapping="Wrap" Text="{Binding LapseText}"
Visibility="{Binding LapseText, Converter={StaticResource NullToCollapsed}}" />
</StackPanel>
<StackPanel Grid.Column="1" Margin="12,0,0,0" VerticalAlignment="Center" Orientation="Horizontal">
<ui:Button Appearance="Secondary"
Command="{Binding GrantCommand}"
Content="{x:Static res:Strings.Settings_Exceptions_Grant}"
Visibility="{Binding CanGrant, Converter={StaticResource BoolToVis}}" />
<ui:Button Appearance="Secondary"
Command="{Binding WithdrawCommand}"
Content="{x:Static res:Strings.Settings_Exceptions_Withdraw}"
Visibility="{Binding CanWithdraw, Converter={StaticResource BoolToVis}}" />
</StackPanel>
</Grid>
</DataTemplate>
</ItemsControl.ItemTemplate>
</ItemsControl>
<ui:Button Margin="0,8,0,0"
Appearance="Secondary"
Command="{Binding ViewModel.RefreshExceptionsCommand}"
Content="{x:Static res:Strings.Settings_Exceptions_Refresh}" />
</StackPanel>
</ui:CardExpander>
<ui:CardExpander Margin="0,8,0,0" Icon="{ui:SymbolIcon Layer24}">
<ui:CardExpander.Header>
<Grid>
@@ -0,0 +1,4 @@
namespace FrameLedger.App.Services;
/// <summary>D33: what the exception's disclosure names — the game, the anti-cheat family and its signal, and the evidence.</summary>
public sealed record AntiCheatExceptionFacts(string GameName, string Family, string Signal, int Sessions);
@@ -0,0 +1,29 @@
namespace FrameLedger.App.Services;
/// <summary>D33: how a request to grant or withdraw one game's user-mode exception ended.</summary>
public enum AntiCheatExceptionOutcome
{
/// <summary>The Agent wrote the grant (<c>AntiCheatExceptionAck.granted = true</c>). Hooking is still off until FR-2.1.</summary>
Granted,
/// <summary>The exception is not in force any more (<c>granted = false</c> on a withdrawal).</summary>
Withdrawn,
/// <summary>The user closed the disclosure without accepting; nothing was sent.</summary>
Declined,
/// <summary>The Agent's own facts did not make the game eligible (<c>Refused</c>).</summary>
Refused,
/// <summary>The Agent grants against another version of the disclosure than this app shows; the dialog was not opened.</summary>
VersionMismatch,
/// <summary>The option is off in Settings (<c>Error ExceptionsOff</c>); nothing was granted.</summary>
OptionOff,
/// <summary>No connected Agent; nothing was sent.</summary>
AgentUnavailable,
/// <summary>The Agent answered and did not grant (a store outcome, an <c>Error</c>, a timeout); <c>Detail</c> says which.</summary>
Failed,
}
@@ -0,0 +1,41 @@
using System.Windows.Data;
using FrameLedger.App.Dialogs;
using FrameLedger.App.ViewModels;
using Wpf.Ui;
using Wpf.Ui.Controls;
namespace FrameLedger.App.Services;
/// <summary>
/// D33's disclosure in WPF UI, the same shape as FR-2.1's (<see cref="ConsentPrompt"/>): the primary button is bound to the
/// ticked acceptance and disabled until it is ticked; the close button keeps the game blocked and is the default, so Enter
/// never makes an exception.
/// </summary>
public sealed class AntiCheatExceptionPrompt : IAntiCheatExceptionPrompt
{
private readonly IContentDialogService _dialogs;
public AntiCheatExceptionPrompt(IContentDialogService dialogs) => _dialogs = dialogs ?? throw new ArgumentNullException(nameof(dialogs));
public async Task<bool> ShowAsync(AntiCheatExceptionFacts facts, CancellationToken ct = default)
{
var viewModel = new AntiCheatExceptionDialogViewModel(facts);
var dialog = new ContentDialog
{
Title = viewModel.Title,
Content = new AntiCheatExceptionDialogContent(viewModel),
PrimaryButtonText = AntiCheatExceptionDialogViewModel.GrantText,
CloseButtonText = AntiCheatExceptionDialogViewModel.CancelText,
// Enter keeps the game blocked; only a click on the (acceptance-gated) primary makes the exception.
DefaultButton = ContentDialogButton.Close,
IsPrimaryButtonEnabled = false,
DialogMaxWidth = 700,
};
_ = dialog.SetBinding(ContentDialog.IsPrimaryButtonEnabledProperty,
new Binding(nameof(AntiCheatExceptionDialogViewModel.Accepted)) { Source = viewModel, Mode = BindingMode.OneWay });
ContentDialogResult result = await _dialogs.ShowAsync(dialog, ct).ConfigureAwait(true);
// The binding is the gate on the button; this is the same rule read once more at the moment that matters.
return result == ContentDialogResult.Primary && viewModel.Accepted;
}
}
@@ -0,0 +1,46 @@
using System.Globalization;
using FrameLedger.Shared.Ipc;
namespace FrameLedger.App.Services;
/// <summary>D33: how an ask for a user-mode exception ended, and — for a refusal — what the Agent named.</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 sealed record AntiCheatExceptionResult(AntiCheatExceptionOutcome Outcome, string? Detail = null, RefusedAck? Refusal = null)
{
public static AntiCheatExceptionResult Of(AntiCheatExceptionOutcome outcome) => new(outcome);
/// <summary>The outcome a user wanted: the exception made, or withdrawn.</summary>
public bool Succeeded => Outcome is AntiCheatExceptionOutcome.Granted or AntiCheatExceptionOutcome.Withdrawn;
/// <summary>What to tell the user about <paramref name="gameName"/>, or null when there is nothing to say (a declined disclosure).</summary>
public string? MessageFor(string gameName) => Outcome switch
{
AntiCheatExceptionOutcome.Granted => string.Format(CultureInfo.CurrentCulture, Strings.Exception_Result_Granted_Format, gameName),
AntiCheatExceptionOutcome.Withdrawn => string.Format(CultureInfo.CurrentCulture, Strings.Exception_Result_Withdrawn_Format, gameName),
AntiCheatExceptionOutcome.Refused => string.Format(CultureInfo.CurrentCulture, Strings.Exception_Result_Refused_Format, gameName,
RefusalText() ?? Detail ?? Strings.Common_NotAvailable),
AntiCheatExceptionOutcome.VersionMismatch => Shared.Strings.Safety_Exception_VersionMismatch,
AntiCheatExceptionOutcome.OptionOff => Shared.Strings.Safety_Exception_OptionOff,
AntiCheatExceptionOutcome.AgentUnavailable => Shared.Strings.Safety_Consent_AgentUnavailable,
AntiCheatExceptionOutcome.Failed => Detail ?? Strings.Common_NotAvailable,
_ => null,
};
/// <summary>Why no exception was made, in the user's language: the session count, the finding, or the block's kind.</summary>
public string? RefusalText()
{
if (Refusal is null)
{
return null;
}
return Refusal.Reason switch
{
"TooFewSessions" => string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_TooFew_Format, Refusal.Signal ?? "0"),
"BlockNotExceptionable" => Strings.Exception_State_NotAsked,
"PreScanFailed" or "RulesUnreadable" or "RulesMalformed" or "RulesIncomplete" => Strings.Exception_State_CouldNotVerify,
_ => string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_Refused_Format,
Refusal.Family ?? Formats.GuardReasonText(Refusal.Reason), Refusal.Signal ?? Strings.Common_NotAvailable),
};
}
}
@@ -0,0 +1,104 @@
using System.IO;
using FrameLedger.Infrastructure.Ipc;
using FrameLedger.Shared.Ipc;
using FrameLedger.Shared.Safety;
using Serilog;
namespace FrameLedger.App.Services;
/// <summary>
/// D33 (owner decision 2026-09-26) from the App's side: the version handshake (the dialog is not opened when the Agent
/// grants against other text), the disclosure, and the one message that may ask for a user-mode exception
/// (<c>SetAntiCheatException</c>). Like <see cref="HookingConsent"/> it asserts nothing: it sends the version it showed,
/// and the Agent re-checks the option, the block, a tolerant pre-scan of the file on disk and the session count, and
/// grants or refuses (<c>07_IPC</c> §The pipe is not a trust boundary).
/// </summary>
public sealed class AntiCheatExceptions
{
private readonly IAgentRequests _agent;
private readonly IAntiCheatExceptionPrompt _prompt;
public AntiCheatExceptions(IAgentRequests agent, IAntiCheatExceptionPrompt prompt)
{
_agent = agent ?? throw new ArgumentNullException(nameof(agent));
_prompt = prompt ?? throw new ArgumentNullException(nameof(prompt));
}
/// <summary>Show the disclosure for the game in <paramref name="facts"/> and, on its acceptance, ask the Agent for the exception.</summary>
public async Task<AntiCheatExceptionResult> GrantAsync(long gameId, AntiCheatExceptionFacts facts, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(facts);
HelloAck? hello = _agent.Hello;
if (hello is null || !_agent.IsConnected)
{
return AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable);
}
if (!string.Equals(hello.ExceptionDisclosureVersion, AntiCheatExceptionDisclosure.Version, StringComparison.Ordinal))
{
// Showing text the Agent would not grant against is a dialog whose button cannot mean what it says.
Log.Warning("exception: the Agent grants against {Theirs}, this app shows {Ours}; the dialog was not opened",
hello.ExceptionDisclosureVersion, AntiCheatExceptionDisclosure.Version);
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.VersionMismatch, hello.ExceptionDisclosureVersion);
}
if (!await _prompt.ShowAsync(facts, ct).ConfigureAwait(true))
{
return AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.Declined);
}
return await SendAsync(new SetAntiCheatExceptionRequest(gameId, Enabled: true, AntiCheatExceptionDisclosure.Version), ct).ConfigureAwait(true);
}
/// <summary>Withdraw the game's exception; no dialog — a withdrawal only takes hooking away.</summary>
public Task<AntiCheatExceptionResult> WithdrawAsync(long gameId, CancellationToken ct = default) =>
_agent.IsConnected
? SendAsync(new SetAntiCheatExceptionRequest(gameId, Enabled: false, null), ct)
: Task.FromResult(AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable));
private async Task<AntiCheatExceptionResult> SendAsync(SetAntiCheatExceptionRequest request, CancellationToken ct)
{
try
{
IpcEnvelope ack = await _agent.RequestAsync(IpcMessageType.SetAntiCheatException, request, ct).ConfigureAwait(true);
return Interpret(ack, request.Enabled);
}
catch (Exception ex) when (ex is IpcRequestException or TimeoutException or IOException or InvalidOperationException)
{
Log.Warning(ex, "exception: SetAntiCheatException(game {GameId}, {Enabled}) did not complete", request.GameId, request.Enabled);
string? code = (ex as IpcRequestException)?.Code;
AntiCheatExceptionOutcome outcome = code switch
{
IpcErrorCode.DisclosureVersionMismatch => AntiCheatExceptionOutcome.VersionMismatch,
IpcErrorCode.ExceptionsOff => AntiCheatExceptionOutcome.OptionOff,
_ => AntiCheatExceptionOutcome.Failed,
};
return new AntiCheatExceptionResult(outcome, code ?? ex.GetType().Name);
}
}
private static AntiCheatExceptionResult Interpret(IpcEnvelope ack, bool granting)
{
if (string.Equals(ack.Type, IpcMessageType.Refused, StringComparison.Ordinal))
{
RefusedAck? refused = IpcCodec.Payload<RefusedAck>(ack);
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.Refused, refused?.Reason, refused);
}
if (!string.Equals(ack.Type, IpcMessageType.AntiCheatExceptionAck, StringComparison.Ordinal))
{
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.Failed, "UnexpectedAck:" + ack.Type);
}
AntiCheatExceptionAck? answer = IpcCodec.Payload<AntiCheatExceptionAck>(ack);
if (answer is null)
{
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.Failed, "EmptyAck");
}
// A withdrawal of an exception that was not in force is still the state the user asked for.
return granting
? answer.Granted ? new(AntiCheatExceptionOutcome.Granted, answer.Outcome) : new(AntiCheatExceptionOutcome.Failed, answer.Outcome)
: answer.Granted ? new(AntiCheatExceptionOutcome.Failed, answer.Outcome) : new(AntiCheatExceptionOutcome.Withdrawn, answer.Outcome);
}
}
@@ -0,0 +1,102 @@
using System.Globalization;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Persistence;
using FrameLedger.Domain.AntiCheat;
namespace FrameLedger.App.Services;
/// <summary>
/// D33 (owner decision 2026-09-26): a blocked game's user-mode exception as the App shows it — in force, eligible, being
/// checked, or why not — read from the Agent's columns (<see cref="GameRow.AcException"/>). The App decides nothing here:
/// every state is a reading of what the Agent wrote, and the grant itself is the Agent's to make.
/// </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 sealed record ExceptionView(ExceptionViewKind Kind, string Text, string? Family, string? Signal, int Sessions, string? LapseText)
{
/// <summary>An exception may be asked for now.</summary>
public bool CanGrant => Kind == ExceptionViewKind.Eligible;
/// <summary>An exception is on the row and may be withdrawn.</summary>
public bool CanWithdraw => Kind == ExceptionViewKind.Granted;
/// <summary>
/// The row's exception, or null for a row it says nothing about (not blocked). Granted first — a grant stays until the
/// Agent or the user ends it — then the block's kind, then the sweep's answer about THIS block.
/// </summary>
public static ExceptionView? Of(GameRow row)
{
ArgumentNullException.ThrowIfNull(row);
if (!row.BlockedByGuard)
{
return null;
}
AntiCheatExceptionState x = row.AcException;
StoredBlock? block = StoredBlock.Parse(row.HookBlockedReason);
string? lapse = x.LapsedReason is { } reason && x.LapsedAt is { } at
? string.Format(CultureInfo.CurrentCulture, Strings.Exception_Lapsed_Format, Formats.Date(at), LapseWords(reason))
: null;
if (x.IsGranted)
{
return new(ExceptionViewKind.Granted, string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_Granted_Format, Formats.Date(x.GrantedAt!.Value)),
x.Family, block?.Signal, x.Sessions, lapse);
}
if (block is not { IsExceptionable: true } b)
{
return new(ExceptionViewKind.NotEligible, Strings.Exception_State_NotAsked, block?.Family, block?.Signal, x.Sessions, lapse);
}
if (!string.Equals(x.CheckedBlock, row.HookBlockedReason, StringComparison.Ordinal))
{
return new(ExceptionViewKind.Checking, Strings.Exception_State_Checking, b.Family, b.Signal, x.Sessions, lapse);
}
return x.Eligible
? new(ExceptionViewKind.Eligible, Strings.Exception_State_Eligible, b.Family, b.Signal, x.Sessions, lapse)
: new(NotEligibleKind(x), WhyNot(b, x), b.Family, b.Signal, x.Sessions, lapse);
}
/// <summary>Why the last grant ended, in words.</summary>
public static string LapseWords(string reason) => reason switch
{
UserModeExceptionLapse.Withdrawn => Strings.Exception_Lapse_Withdrawn,
UserModeExceptionLapse.ExecutableChanged => Strings.Exception_Lapse_ExecutableChanged,
UserModeExceptionLapse.NoLongerEligible => Strings.Exception_Lapse_NoLongerEligible,
UserModeExceptionLapse.NewFinding => Strings.Exception_Lapse_NewFinding,
UserModeExceptionLapse.SafetyUnhook => Strings.Exception_Lapse_SafetyUnhook,
UserModeExceptionLapse.OverlayStopped => Strings.Exception_Lapse_OverlayStopped,
UserModeExceptionLapse.SessionCrashed => Strings.Exception_Lapse_SessionCrashed,
_ => reason,
};
/// <summary>The guard let the family through and only the evidence is short — the one "not yet" the Settings list shows.</summary>
private static ExceptionViewKind NotEligibleKind(AntiCheatExceptionState x) =>
StoredBlock.Parse(x.Verdict) is { Reason: AntiCheatRefusalReason.AllowedUnderUserModeException }
? ExceptionViewKind.TooFewSessions
: ExceptionViewKind.NotEligible;
private static string WhyNot(StoredBlock block, AntiCheatExceptionState x)
{
StoredBlock? verdict = StoredBlock.Parse(x.Verdict);
if (verdict is null)
{
return Strings.Exception_State_NotAsked;
}
if (verdict.Value.Reason == AntiCheatRefusalReason.AllowedUnderUserModeException)
{
return string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_TooFew_Format, x.Sessions);
}
if (!verdict.Value.IsExceptionable && verdict.Value.Family.Length == 0)
{
return Strings.Exception_State_CouldNotVerify;
}
// The same finding back means the guard does not honour this family: it is not user-mode throughout.
return string.Equals(verdict.Value.Family, block.Family, StringComparison.Ordinal)
? string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_NotUserMode_Format, block.Family)
: string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_Refused_Format, verdict.Value.Family, verdict.Value.Signal);
}
}
@@ -0,0 +1,20 @@
namespace FrameLedger.App.Services;
/// <summary>D33: the states a blocked game's user-mode exception is shown in (<see cref="ExceptionView"/>).</summary>
public enum ExceptionViewKind
{
/// <summary>An exception is on the row.</summary>
Granted,
/// <summary>The Agent found the game eligible; no exception has been made.</summary>
Eligible,
/// <summary>The guard would let the family through, and the game has fewer than two successful hooked sessions.</summary>
TooFewSessions,
/// <summary>The Agent has not answered about this block yet (the option was just turned on, or the block changed).</summary>
Checking,
/// <summary>Not eligible, for the reason in the text.</summary>
NotEligible,
}
@@ -0,0 +1,11 @@
namespace FrameLedger.App.Services;
/// <summary>
/// D33's disclosure as a question: shows the versioned text for one game and answers whether the user accepted the risk
/// and chose to make the exception. The WPF implementation is <see cref="AntiCheatExceptionPrompt"/>; a test substitutes an
/// answer.
/// </summary>
public interface IAntiCheatExceptionPrompt
{
Task<bool> ShowAsync(AntiCheatExceptionFacts facts, CancellationToken ct = default);
}
@@ -100,6 +100,13 @@ public sealed class SessionExporter
w.WriteLine("# started_at: " + row.StartedAt.ToString("O", _inv));
w.WriteLine("# ended_at: " + row.EndedAt.ToString("O", _inv));
w.WriteLine("# capture_tier: " + ((int)row.Tier).ToString(_inv) + (row.Tier == CaptureTier.Hooked ? " (hooked, measured)" : " (not hooked: duration and sensors only; no per-frame rows)"));
if (row.AcExceptionFamily is { Length: > 0 } excepted)
{
// D33: a session hooked under the game's user-mode anti-cheat exception says so wherever it goes (the JSON carries
// the column in its aggregates).
w.WriteLine("# ac_exception: " + excepted + " (hooked under the game's user-mode anti-cheat exception)");
}
w.WriteLine("# api: " + (row.Api ?? "N/A") + "; present_mode: " + (row.PresentMode ?? "N/A") + "; swap_effect: " + (row.SwapEffect ?? "N/A"));
w.WriteLine("# hardware: " + (hardware is null ? "N/A" : string.Join("; ", new[] { hardware.CpuName, hardware.GpuName, hardware.GpuDriver, hardware.OsBuild, hardware.DisplayRes }.Where(static s => !string.IsNullOrEmpty(s)))));
w.WriteLine("# rt: " + row.RtFlag + " (" + (row.RtSource ?? "n/a") + "); pt: " + row.PtFlag + " (" + (row.PtSource ?? "n/a") + "); rr: " + row.RrFlag + " (" + (row.RrSource ?? "n/a") + ")");
+114
View File
@@ -213,6 +213,27 @@ public static class Strings
nameof(End_WriterNeverInstalledHooks),
nameof(End_WriterSelfDisabled),
nameof(End_WriterStoppedBlocklisted),
nameof(Exception_Finding_Format),
nameof(Exception_Lapse_ExecutableChanged),
nameof(Exception_Lapse_NewFinding),
nameof(Exception_Lapse_NoLongerEligible),
nameof(Exception_Lapse_OverlayStopped),
nameof(Exception_Lapse_SafetyUnhook),
nameof(Exception_Lapse_SessionCrashed),
nameof(Exception_Lapse_Withdrawn),
nameof(Exception_Lapsed_Format),
nameof(Exception_Result_Granted_Format),
nameof(Exception_Result_Refused_Format),
nameof(Exception_Result_Withdrawn_Format),
nameof(Exception_Sessions_Format),
nameof(Exception_State_Checking),
nameof(Exception_State_CouldNotVerify),
nameof(Exception_State_Eligible),
nameof(Exception_State_Granted_Format),
nameof(Exception_State_NotAsked),
nameof(Exception_State_NotUserMode_Format),
nameof(Exception_State_Refused_Format),
nameof(Exception_State_TooFew_Format),
nameof(Exe_DriveMissing_Format),
nameof(Exe_FileMissing_Format),
nameof(Exit_Code_Format),
@@ -331,6 +352,11 @@ public static class Strings
nameof(GameDetail_Details_Store),
nameof(GameDetail_Details_Version),
nameof(GameDetail_Edit),
nameof(GameDetail_Exception_Grant),
nameof(GameDetail_Exception_Granted_Format),
nameof(GameDetail_Exception_Header),
nameof(GameDetail_Exception_Suspended),
nameof(GameDetail_Exception_Withdraw),
nameof(GameDetail_ExeMissing),
nameof(GameDetail_Hooking_Body),
nameof(GameDetail_Hooking_Busy),
@@ -363,6 +389,7 @@ public static class Strings
nameof(GameDetail_Tab_Trend),
nameof(Games_Add),
nameof(Games_Card_AntiCheat),
nameof(Games_Card_Exception),
nameof(Games_Card_HookOff),
nameof(Games_Card_HookOn),
nameof(Games_Card_LastPlayed_Format),
@@ -565,6 +592,7 @@ public static class Strings
nameof(Sensors_Series_VramProcess),
nameof(Sensors_Temps_Header),
nameof(Sensors_Vram_Header),
nameof(Session_UnderException_Format),
nameof(Sessions_Col_Api),
nameof(Sessions_Col_Date),
nameof(Sessions_Col_Displayed),
@@ -600,6 +628,15 @@ public static class Strings
nameof(Settings_Capture_Header),
nameof(Settings_Channel_Beta),
nameof(Settings_Channel_Stable),
nameof(Settings_Exceptions_Body),
nameof(Settings_Exceptions_Checking),
nameof(Settings_Exceptions_Empty),
nameof(Settings_Exceptions_Grant),
nameof(Settings_Exceptions_Header),
nameof(Settings_Exceptions_Label),
nameof(Settings_Exceptions_Refresh),
nameof(Settings_Exceptions_Suspended),
nameof(Settings_Exceptions_Withdraw),
nameof(Settings_FpsDecimals_Body),
nameof(Settings_FpsDecimals_Label),
nameof(Settings_Header),
@@ -723,6 +760,7 @@ public static class Strings
nameof(Tier_Dash_Tooltip),
nameof(Tier_Hooked),
nameof(Tier_Hooked_Tooltip),
nameof(Tier_HookedException),
nameof(Tier_NA_Tooltip),
nameof(Tier_NotHooked),
nameof(Tier_NotHooked_Tooltip),
@@ -1172,6 +1210,48 @@ public static class Strings
public static string End_WriterStoppedBlocklisted => ResourceManager.GetString(nameof(End_WriterStoppedBlocklisted), Culture) ?? nameof(End_WriterStoppedBlocklisted);
public static string Exception_Finding_Format => ResourceManager.GetString(nameof(Exception_Finding_Format), Culture) ?? nameof(Exception_Finding_Format);
public static string Exception_Lapse_ExecutableChanged => ResourceManager.GetString(nameof(Exception_Lapse_ExecutableChanged), Culture) ?? nameof(Exception_Lapse_ExecutableChanged);
public static string Exception_Lapse_NewFinding => ResourceManager.GetString(nameof(Exception_Lapse_NewFinding), Culture) ?? nameof(Exception_Lapse_NewFinding);
public static string Exception_Lapse_NoLongerEligible => ResourceManager.GetString(nameof(Exception_Lapse_NoLongerEligible), Culture) ?? nameof(Exception_Lapse_NoLongerEligible);
public static string Exception_Lapse_OverlayStopped => ResourceManager.GetString(nameof(Exception_Lapse_OverlayStopped), Culture) ?? nameof(Exception_Lapse_OverlayStopped);
public static string Exception_Lapse_SafetyUnhook => ResourceManager.GetString(nameof(Exception_Lapse_SafetyUnhook), Culture) ?? nameof(Exception_Lapse_SafetyUnhook);
public static string Exception_Lapse_SessionCrashed => ResourceManager.GetString(nameof(Exception_Lapse_SessionCrashed), Culture) ?? nameof(Exception_Lapse_SessionCrashed);
public static string Exception_Lapse_Withdrawn => ResourceManager.GetString(nameof(Exception_Lapse_Withdrawn), Culture) ?? nameof(Exception_Lapse_Withdrawn);
public static string Exception_Lapsed_Format => ResourceManager.GetString(nameof(Exception_Lapsed_Format), Culture) ?? nameof(Exception_Lapsed_Format);
public static string Exception_Result_Granted_Format => ResourceManager.GetString(nameof(Exception_Result_Granted_Format), Culture) ?? nameof(Exception_Result_Granted_Format);
public static string Exception_Result_Refused_Format => ResourceManager.GetString(nameof(Exception_Result_Refused_Format), Culture) ?? nameof(Exception_Result_Refused_Format);
public static string Exception_Result_Withdrawn_Format => ResourceManager.GetString(nameof(Exception_Result_Withdrawn_Format), Culture) ?? nameof(Exception_Result_Withdrawn_Format);
public static string Exception_Sessions_Format => ResourceManager.GetString(nameof(Exception_Sessions_Format), Culture) ?? nameof(Exception_Sessions_Format);
public static string Exception_State_Checking => ResourceManager.GetString(nameof(Exception_State_Checking), Culture) ?? nameof(Exception_State_Checking);
public static string Exception_State_CouldNotVerify => ResourceManager.GetString(nameof(Exception_State_CouldNotVerify), Culture) ?? nameof(Exception_State_CouldNotVerify);
public static string Exception_State_Eligible => ResourceManager.GetString(nameof(Exception_State_Eligible), Culture) ?? nameof(Exception_State_Eligible);
public static string Exception_State_Granted_Format => ResourceManager.GetString(nameof(Exception_State_Granted_Format), Culture) ?? nameof(Exception_State_Granted_Format);
public static string Exception_State_NotAsked => ResourceManager.GetString(nameof(Exception_State_NotAsked), Culture) ?? nameof(Exception_State_NotAsked);
public static string Exception_State_NotUserMode_Format => ResourceManager.GetString(nameof(Exception_State_NotUserMode_Format), Culture) ?? nameof(Exception_State_NotUserMode_Format);
public static string Exception_State_Refused_Format => ResourceManager.GetString(nameof(Exception_State_Refused_Format), Culture) ?? nameof(Exception_State_Refused_Format);
public static string Exception_State_TooFew_Format => ResourceManager.GetString(nameof(Exception_State_TooFew_Format), Culture) ?? nameof(Exception_State_TooFew_Format);
public static string Exe_DriveMissing_Format => ResourceManager.GetString(nameof(Exe_DriveMissing_Format), Culture) ?? nameof(Exe_DriveMissing_Format);
public static string Exe_FileMissing_Format => ResourceManager.GetString(nameof(Exe_FileMissing_Format), Culture) ?? nameof(Exe_FileMissing_Format);
@@ -1408,6 +1488,16 @@ public static class Strings
public static string GameDetail_Edit => ResourceManager.GetString(nameof(GameDetail_Edit), Culture) ?? nameof(GameDetail_Edit);
public static string GameDetail_Exception_Grant => ResourceManager.GetString(nameof(GameDetail_Exception_Grant), Culture) ?? nameof(GameDetail_Exception_Grant);
public static string GameDetail_Exception_Granted_Format => ResourceManager.GetString(nameof(GameDetail_Exception_Granted_Format), Culture) ?? nameof(GameDetail_Exception_Granted_Format);
public static string GameDetail_Exception_Header => ResourceManager.GetString(nameof(GameDetail_Exception_Header), Culture) ?? nameof(GameDetail_Exception_Header);
public static string GameDetail_Exception_Suspended => ResourceManager.GetString(nameof(GameDetail_Exception_Suspended), Culture) ?? nameof(GameDetail_Exception_Suspended);
public static string GameDetail_Exception_Withdraw => ResourceManager.GetString(nameof(GameDetail_Exception_Withdraw), Culture) ?? nameof(GameDetail_Exception_Withdraw);
public static string GameDetail_ExeMissing => ResourceManager.GetString(nameof(GameDetail_ExeMissing), Culture) ?? nameof(GameDetail_ExeMissing);
public static string GameDetail_Hooking_Body => ResourceManager.GetString(nameof(GameDetail_Hooking_Body), Culture) ?? nameof(GameDetail_Hooking_Body);
@@ -1472,6 +1562,8 @@ public static class Strings
public static string Games_Card_AntiCheat => ResourceManager.GetString(nameof(Games_Card_AntiCheat), Culture) ?? nameof(Games_Card_AntiCheat);
public static string Games_Card_Exception => ResourceManager.GetString(nameof(Games_Card_Exception), Culture) ?? nameof(Games_Card_Exception);
public static string Games_Card_HookOff => ResourceManager.GetString(nameof(Games_Card_HookOff), Culture) ?? nameof(Games_Card_HookOff);
public static string Games_Card_HookOn => ResourceManager.GetString(nameof(Games_Card_HookOn), Culture) ?? nameof(Games_Card_HookOn);
@@ -1876,6 +1968,8 @@ public static class Strings
public static string Sensors_Vram_Header => ResourceManager.GetString(nameof(Sensors_Vram_Header), Culture) ?? nameof(Sensors_Vram_Header);
public static string Session_UnderException_Format => ResourceManager.GetString(nameof(Session_UnderException_Format), Culture) ?? nameof(Session_UnderException_Format);
public static string Sessions_Col_Api => ResourceManager.GetString(nameof(Sessions_Col_Api), Culture) ?? nameof(Sessions_Col_Api);
public static string Sessions_Col_Date => ResourceManager.GetString(nameof(Sessions_Col_Date), Culture) ?? nameof(Sessions_Col_Date);
@@ -1946,6 +2040,24 @@ public static class Strings
public static string Settings_Channel_Stable => ResourceManager.GetString(nameof(Settings_Channel_Stable), Culture) ?? nameof(Settings_Channel_Stable);
public static string Settings_Exceptions_Body => ResourceManager.GetString(nameof(Settings_Exceptions_Body), Culture) ?? nameof(Settings_Exceptions_Body);
public static string Settings_Exceptions_Checking => ResourceManager.GetString(nameof(Settings_Exceptions_Checking), Culture) ?? nameof(Settings_Exceptions_Checking);
public static string Settings_Exceptions_Empty => ResourceManager.GetString(nameof(Settings_Exceptions_Empty), Culture) ?? nameof(Settings_Exceptions_Empty);
public static string Settings_Exceptions_Grant => ResourceManager.GetString(nameof(Settings_Exceptions_Grant), Culture) ?? nameof(Settings_Exceptions_Grant);
public static string Settings_Exceptions_Header => ResourceManager.GetString(nameof(Settings_Exceptions_Header), Culture) ?? nameof(Settings_Exceptions_Header);
public static string Settings_Exceptions_Label => ResourceManager.GetString(nameof(Settings_Exceptions_Label), Culture) ?? nameof(Settings_Exceptions_Label);
public static string Settings_Exceptions_Refresh => ResourceManager.GetString(nameof(Settings_Exceptions_Refresh), Culture) ?? nameof(Settings_Exceptions_Refresh);
public static string Settings_Exceptions_Suspended => ResourceManager.GetString(nameof(Settings_Exceptions_Suspended), Culture) ?? nameof(Settings_Exceptions_Suspended);
public static string Settings_Exceptions_Withdraw => ResourceManager.GetString(nameof(Settings_Exceptions_Withdraw), Culture) ?? nameof(Settings_Exceptions_Withdraw);
public static string Settings_FpsDecimals_Body => ResourceManager.GetString(nameof(Settings_FpsDecimals_Body), Culture) ?? nameof(Settings_FpsDecimals_Body);
public static string Settings_FpsDecimals_Label => ResourceManager.GetString(nameof(Settings_FpsDecimals_Label), Culture) ?? nameof(Settings_FpsDecimals_Label);
@@ -2192,6 +2304,8 @@ public static class Strings
public static string Tier_Hooked_Tooltip => ResourceManager.GetString(nameof(Tier_Hooked_Tooltip), Culture) ?? nameof(Tier_Hooked_Tooltip);
public static string Tier_HookedException => ResourceManager.GetString(nameof(Tier_HookedException), Culture) ?? nameof(Tier_HookedException);
public static string Tier_NA_Tooltip => ResourceManager.GetString(nameof(Tier_NA_Tooltip), Culture) ?? nameof(Tier_NA_Tooltip);
public static string Tier_NotHooked => ResourceManager.GetString(nameof(Tier_NotHooked), Culture) ?? nameof(Tier_NotHooked);
+153 -1
View File
@@ -2530,7 +2530,7 @@
<comment>review</comment>
</data>
<data name="Settings_HideAntiCheatHooking_Body" xml:space="preserve">
<value>アンチチートが検出されたゲームはフックできません。オンにするとゲームのページには検出内容だけが表示され、オフにすると無効化されたフックのスイッチも表示されます。どちらの場合も、フックなしで記録は続きます。</value>
<value>アンチチートが検出されたゲームは、ユーザーモード例外(下記)を作成しない限りフックできません。オンにするとゲームのページには検出内容だけが表示され、オフにすると無効化されたフックのスイッチも表示されます。どちらの場合も、フックなしで記録は続きます。</value>
<comment>review</comment>
</data>
<data name="Notice_HookingOff_Title_Format" xml:space="preserve">
@@ -3113,4 +3113,156 @@
<value>W</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Label" xml:space="preserve">
<value>以前に計測できたユーザーモードのアンチチート搭載ゲームでフックを許可する</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Body" xml:space="preserve">
<value>既定ではオフです。オンにすると、アンチチートがユーザーモードのみで動作し(カーネルドライバーがなく、ほかに何も検出されない)、フックで2回以上計測できたゲームに、開示を確認したうえでゲームごとに例外を与えられます。ガードはすべてのチェックを続け、アカウント停止の可能性は残ります。</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Header" xml:space="preserve">
<value>ユーザーモード例外</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Empty" xml:space="preserve">
<value>ライブラリに対象のゲームはありません。</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Suspended" xml:space="preserve">
<value>オプションがオフです。下の例外は保持されますが適用されません。</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Grant" xml:space="preserve">
<value>例外を作成…</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Withdraw" xml:space="preserve">
<value>取り消す</value>
<comment>review</comment>
</data>
<data name="Exception_Finding_Format" xml:space="preserve">
<value>{0} — {1}</value>
<comment>review</comment>
</data>
<data name="Exception_Sessions_Format" xml:space="preserve">
<value>フック計測の成功 {0} 回</value>
<comment>review</comment>
</data>
<data name="Exception_State_Granted_Format" xml:space="preserve">
<value>{0} から例外が有効</value>
<comment>review</comment>
</data>
<data name="Exception_State_Eligible" xml:space="preserve">
<value>対象 — 例外は未作成</value>
<comment>review</comment>
</data>
<data name="Exception_State_Checking" xml:space="preserve">
<value>確認中…</value>
<comment>review</comment>
</data>
<data name="Exception_State_TooFew_Format" xml:space="preserve">
<value>対象外: フック計測の成功は {0} 回で、2 回必要です</value>
<comment>review</comment>
</data>
<data name="Exception_State_Refused_Format" xml:space="preserve">
<value>対象外: ガードは {0}({1})も検出しました</value>
<comment>review</comment>
</data>
<data name="Exception_State_NotUserMode_Format" xml:space="preserve">
<value>対象外: {0} は完全なユーザーモードではない(ドライバーまたはサービスがある)ため、FrameLedger は例外にしません</value>
<comment>review</comment>
</data>
<data name="Exception_State_NotAsked" xml:space="preserve">
<value>対象外: この検出は単一のアンチチートのモジュール・ファイル・フォルダーではありません</value>
<comment>review</comment>
</data>
<data name="Exception_State_CouldNotVerify" xml:space="preserve">
<value>現在は対象外: 確認を完了できませんでした。自動で再実行されます</value>
<comment>review</comment>
</data>
<data name="Exception_Lapsed_Format" xml:space="preserve">
<value>直近の例外は {0} に終了しました: {1}</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_Withdrawn" xml:space="preserve">
<value>取り消されました</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_ExecutableChanged" xml:space="preserve">
<value>ゲームが更新されました</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_NoLongerEligible" xml:space="preserve">
<value>ゲームが条件を満たさなくなりました</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_NewFinding" xml:space="preserve">
<value>ゲームで新たなアンチチートが検出されました</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_SafetyUnhook" xml:space="preserve">
<value>例外下のセッションが安全のため停止されました</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_OverlayStopped" xml:space="preserve">
<value>別のアンチチートが読み込まれたため FrameLedger が観測を停止しました</value>
<comment>review</comment>
</data>
<data name="Exception_Lapse_SessionCrashed" xml:space="preserve">
<value>例外下のセッションがクラッシュしました</value>
<comment>review</comment>
</data>
<data name="Exception_Result_Granted_Format" xml:space="preserve">
<value>{0} の例外を作成しました。計測するときは、ゲームのページでフックをオンにしてください。</value>
<comment>review</comment>
</data>
<data name="Exception_Result_Withdrawn_Format" xml:space="preserve">
<value>{0} の例外を取り消しました。フックはオフです。</value>
<comment>review</comment>
</data>
<data name="Exception_Result_Refused_Format" xml:space="preserve">
<value>{0} の例外は作成されませんでした: {1}</value>
<comment>review</comment>
</data>
<data name="GameDetail_Exception_Header" xml:space="preserve">
<value>ユーザーモード例外</value>
<comment>review</comment>
</data>
<data name="GameDetail_Exception_Granted_Format" xml:space="preserve">
<value>{0} に対するユーザーモード例外のもとでフックできます。ガードはすべてのチェックを続け、アカウント停止の可能性は残ります。</value>
<comment>review</comment>
</data>
<data name="GameDetail_Exception_Suspended" xml:space="preserve">
<value>このゲームの例外は保持されていますが、設定でオプションがオフのため適用されません。</value>
<comment>review</comment>
</data>
<data name="GameDetail_Exception_Grant" xml:space="preserve">
<value>例外を作成…</value>
<comment>review</comment>
</data>
<data name="GameDetail_Exception_Withdraw" xml:space="preserve">
<value>例外を取り消す</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Refresh" xml:space="preserve">
<value>更新</value>
<comment>review</comment>
</data>
<data name="Settings_Exceptions_Checking" xml:space="preserve">
<value>キャプチャエージェントがライブラリを確認しています。対象のゲームは1分以内にここに表示されます。更新して確認してください。</value>
<comment>review</comment>
</data>
<data name="Tier_HookedException" xml:space="preserve">
<value>フック・例外</value>
<comment>review</comment>
</data>
<data name="Games_Card_Exception" xml:space="preserve">
<value>例外</value>
<comment>review</comment>
</data>
<data name="Session_UnderException_Format" xml:space="preserve">
<value>{0} のユーザーモード例外のもとでフック</value>
<comment>review</comment>
</data>
</root>
+115 -1
View File
@@ -1908,7 +1908,7 @@ The documents below are the full terms; this summary does not replace them.</val
<value>Hide hooking on anti-cheat games</value>
</data>
<data name="Settings_HideAntiCheatHooking_Body" xml:space="preserve">
<value>A game in which anti-cheat was found can never be hooked. On, its page shows only what was found; off, it also shows the disabled Hooking switch. Either way it is still recorded without hooking.</value>
<value>A game in which anti-cheat was found cannot be hooked, unless you make a user-mode exception for it (below). On, its page shows only what was found; off, it also shows the disabled Hooking switch. Either way it is still recorded without hooking.</value>
</data>
<data name="Notice_HookingOff_Title_Format" xml:space="preserve">
<value>{0}: hooking turned off</value>
@@ -2345,4 +2345,118 @@ The documents below are the full terms; this summary does not replace them.</val
<data name="Sensors_Axis_Watts" xml:space="preserve">
<value>W</value>
</data>
<data name="Settings_Exceptions_Label" xml:space="preserve">
<value>Allow hooking in games with user-mode anti-cheat that were measured before</value>
</data>
<data name="Settings_Exceptions_Body" xml:space="preserve">
<value>Off by default. On, a game whose only anti-cheat runs in user mode — no kernel driver, nothing else found — and that was measured hooked at least twice can be given an exception below, one game at a time, after a disclosure. The guard still runs every check, and a ban remains possible.</value>
</data>
<data name="Settings_Exceptions_Header" xml:space="preserve">
<value>User-mode exceptions</value>
</data>
<data name="Settings_Exceptions_Empty" xml:space="preserve">
<value>No game in your library qualifies.</value>
</data>
<data name="Settings_Exceptions_Suspended" xml:space="preserve">
<value>The option is off: the exceptions below are kept but do not apply.</value>
</data>
<data name="Settings_Exceptions_Grant" xml:space="preserve">
<value>Make exception…</value>
</data>
<data name="Settings_Exceptions_Withdraw" xml:space="preserve">
<value>Withdraw</value>
</data>
<data name="Exception_Finding_Format" xml:space="preserve">
<value>{0} — {1}</value>
</data>
<data name="Exception_Sessions_Format" xml:space="preserve">
<value>{0} successful hooked sessions</value>
</data>
<data name="Exception_State_Granted_Format" xml:space="preserve">
<value>Exception in force since {0}</value>
</data>
<data name="Exception_State_Eligible" xml:space="preserve">
<value>Eligible — no exception made</value>
</data>
<data name="Exception_State_Checking" xml:space="preserve">
<value>Checking…</value>
</data>
<data name="Exception_State_TooFew_Format" xml:space="preserve">
<value>Not eligible: {0} successful hooked session(s), two are needed</value>
</data>
<data name="Exception_State_Refused_Format" xml:space="preserve">
<value>Not eligible: the guard also found {0} ({1})</value>
</data>
<data name="Exception_State_NotUserMode_Format" xml:space="preserve">
<value>Not eligible: {0} is not user-mode throughout (it has a driver or a service), so FrameLedger never excepts it</value>
</data>
<data name="Exception_State_NotAsked" xml:space="preserve">
<value>Not eligible: this finding is not a module, file or folder of one anti-cheat</value>
</data>
<data name="Exception_State_CouldNotVerify" xml:space="preserve">
<value>Not eligible now: the check could not finish; it runs again by itself</value>
</data>
<data name="Exception_Lapsed_Format" xml:space="preserve">
<value>The last exception ended on {0}: {1}</value>
</data>
<data name="Exception_Lapse_Withdrawn" xml:space="preserve">
<value>you withdrew it</value>
</data>
<data name="Exception_Lapse_ExecutableChanged" xml:space="preserve">
<value>the game was updated</value>
</data>
<data name="Exception_Lapse_NoLongerEligible" xml:space="preserve">
<value>the game no longer qualifies</value>
</data>
<data name="Exception_Lapse_NewFinding" xml:space="preserve">
<value>new anti-cheat was found in the game</value>
</data>
<data name="Exception_Lapse_SafetyUnhook" xml:space="preserve">
<value>a session under it was stopped for safety</value>
</data>
<data name="Exception_Lapse_OverlayStopped" xml:space="preserve">
<value>FrameLedger stopped observing because another anti-cheat loaded</value>
</data>
<data name="Exception_Lapse_SessionCrashed" xml:space="preserve">
<value>a session under it crashed</value>
</data>
<data name="Exception_Result_Granted_Format" xml:space="preserve">
<value>Exception made for {0}. Turn hooking on for the game on its page when you want to measure it.</value>
</data>
<data name="Exception_Result_Withdrawn_Format" xml:space="preserve">
<value>Exception withdrawn for {0}; its hooking is off.</value>
</data>
<data name="Exception_Result_Refused_Format" xml:space="preserve">
<value>No exception was made for {0}: {1}</value>
</data>
<data name="GameDetail_Exception_Header" xml:space="preserve">
<value>User-mode exception</value>
</data>
<data name="GameDetail_Exception_Granted_Format" xml:space="preserve">
<value>Hooking may run under a user-mode exception for {0}. The guard still runs every check; a ban remains possible.</value>
</data>
<data name="GameDetail_Exception_Suspended" xml:space="preserve">
<value>An exception is kept for this game, but the option is off in Settings, so it does not apply.</value>
</data>
<data name="GameDetail_Exception_Grant" xml:space="preserve">
<value>Make exception…</value>
</data>
<data name="GameDetail_Exception_Withdraw" xml:space="preserve">
<value>Withdraw exception</value>
</data>
<data name="Settings_Exceptions_Refresh" xml:space="preserve">
<value>Refresh</value>
</data>
<data name="Settings_Exceptions_Checking" xml:space="preserve">
<value>The capture agent is checking your library; the games that qualify appear here within a minute. Refresh to see them.</value>
</data>
<data name="Tier_HookedException" xml:space="preserve">
<value>Hooked · exception</value>
</data>
<data name="Games_Card_Exception" xml:space="preserve">
<value>Exception</value>
</data>
<data name="Session_UnderException_Format" xml:space="preserve">
<value>Hooked under the user-mode exception for {0}</value>
</data>
</root>
+115 -1
View File
@@ -1903,7 +1903,7 @@ Các tài liệu bên dưới là điều khoản đầy đủ; phần tóm tắ
<value>Ẩn phần hooking ở game có anti-cheat</value>
</data>
<data name="Settings_HideAntiCheatHooking_Body" xml:space="preserve">
<value>Game được phát hiện có anti-cheat sẽ không bao giờ được hook. Bật: trang game chỉ hiện điều đã phát hiện; tắt: hiện thêm công tắc Hooking bị vô hiệu hoá. Dù bật hay tắt, game vẫn được ghi mà không hook.</value>
<value>Game được phát hiện có anti-cheat sẽ không được hook, trừ khi bạn tạo ngoại lệ user-mode cho nó (bên dưới). Bật: trang game chỉ hiện điều đã phát hiện; tắt: hiện thêm công tắc Hooking bị vô hiệu hoá. Dù bật hay tắt, game vẫn được ghi mà không hook.</value>
</data>
<data name="Notice_HookingOff_Title_Format" xml:space="preserve">
<value>{0}: đã tắt hooking</value>
@@ -2340,4 +2340,118 @@ Các tài liệu bên dưới là điều khoản đầy đủ; phần tóm tắ
<data name="Sensors_Axis_Watts" xml:space="preserve">
<value>W</value>
</data>
<data name="Settings_Exceptions_Label" xml:space="preserve">
<value>Cho phép hooking ở game có anti-cheat user-mode đã từng đo thành công</value>
</data>
<data name="Settings_Exceptions_Body" xml:space="preserve">
<value>Mặc định tắt. Khi bật, game có anti-cheat duy nhất chạy ở user mode — không có kernel driver, không phát hiện gì khác — và đã được đo ở chế độ hook ít nhất hai lần có thể được cấp ngoại lệ bên dưới, từng game một, sau một bản công bố rủi ro. Bộ bảo vệ vẫn chạy mọi bước kiểm tra, và vẫn có thể bị khoá tài khoản.</value>
</data>
<data name="Settings_Exceptions_Header" xml:space="preserve">
<value>Ngoại lệ user-mode</value>
</data>
<data name="Settings_Exceptions_Empty" xml:space="preserve">
<value>Không có game nào trong thư viện đủ điều kiện.</value>
</data>
<data name="Settings_Exceptions_Suspended" xml:space="preserve">
<value>Tuỳ chọn đang tắt: các ngoại lệ bên dưới được giữ lại nhưng không có hiệu lực.</value>
</data>
<data name="Settings_Exceptions_Grant" xml:space="preserve">
<value>Tạo ngoại lệ…</value>
</data>
<data name="Settings_Exceptions_Withdraw" xml:space="preserve">
<value>Rút lại</value>
</data>
<data name="Exception_Finding_Format" xml:space="preserve">
<value>{0} — {1}</value>
</data>
<data name="Exception_Sessions_Format" xml:space="preserve">
<value>{0} phiên hook thành công</value>
</data>
<data name="Exception_State_Granted_Format" xml:space="preserve">
<value>Ngoại lệ có hiệu lực từ {0}</value>
</data>
<data name="Exception_State_Eligible" xml:space="preserve">
<value>Đủ điều kiện — chưa tạo ngoại lệ</value>
</data>
<data name="Exception_State_Checking" xml:space="preserve">
<value>Đang kiểm tra…</value>
</data>
<data name="Exception_State_TooFew_Format" xml:space="preserve">
<value>Chưa đủ điều kiện: {0} phiên hook thành công, cần hai</value>
</data>
<data name="Exception_State_Refused_Format" xml:space="preserve">
<value>Không đủ điều kiện: bộ bảo vệ còn phát hiện {0} ({1})</value>
</data>
<data name="Exception_State_NotUserMode_Format" xml:space="preserve">
<value>Không đủ điều kiện: {0} không chạy hoàn toàn ở user mode (có driver hoặc service), nên FrameLedger không bao giờ cấp ngoại lệ</value>
</data>
<data name="Exception_State_NotAsked" xml:space="preserve">
<value>Không đủ điều kiện: phát hiện này không phải module, tệp hay thư mục của một anti-cheat</value>
</data>
<data name="Exception_State_CouldNotVerify" xml:space="preserve">
<value>Hiện chưa đủ điều kiện: lần kiểm tra không hoàn tất; nó sẽ tự chạy lại</value>
</data>
<data name="Exception_Lapsed_Format" xml:space="preserve">
<value>Ngoại lệ gần nhất đã kết thúc ngày {0}: {1}</value>
</data>
<data name="Exception_Lapse_Withdrawn" xml:space="preserve">
<value>bạn đã rút lại</value>
</data>
<data name="Exception_Lapse_ExecutableChanged" xml:space="preserve">
<value>game đã được cập nhật</value>
</data>
<data name="Exception_Lapse_NoLongerEligible" xml:space="preserve">
<value>game không còn đủ điều kiện</value>
</data>
<data name="Exception_Lapse_NewFinding" xml:space="preserve">
<value>phát hiện anti-cheat mới trong game</value>
</data>
<data name="Exception_Lapse_SafetyUnhook" xml:space="preserve">
<value>một phiên dưới ngoại lệ bị dừng vì an toàn</value>
</data>
<data name="Exception_Lapse_OverlayStopped" xml:space="preserve">
<value>FrameLedger ngừng quan sát vì một anti-cheat khác được nạp</value>
</data>
<data name="Exception_Lapse_SessionCrashed" xml:space="preserve">
<value>một phiên dưới ngoại lệ bị crash</value>
</data>
<data name="Exception_Result_Granted_Format" xml:space="preserve">
<value>Đã tạo ngoại lệ cho {0}. Khi muốn đo, hãy bật hooking cho game trên trang của nó.</value>
</data>
<data name="Exception_Result_Withdrawn_Format" xml:space="preserve">
<value>Đã rút ngoại lệ cho {0}; hooking của nó đã tắt.</value>
</data>
<data name="Exception_Result_Refused_Format" xml:space="preserve">
<value>Không tạo ngoại lệ cho {0}: {1}</value>
</data>
<data name="GameDetail_Exception_Header" xml:space="preserve">
<value>Ngoại lệ user-mode</value>
</data>
<data name="GameDetail_Exception_Granted_Format" xml:space="preserve">
<value>Hooking có thể chạy dưới ngoại lệ user-mode cho {0}. Bộ bảo vệ vẫn chạy mọi bước kiểm tra; vẫn có thể bị khoá tài khoản.</value>
</data>
<data name="GameDetail_Exception_Suspended" xml:space="preserve">
<value>Game này có ngoại lệ được giữ lại, nhưng tuỳ chọn đang tắt trong Cài đặt nên nó không có hiệu lực.</value>
</data>
<data name="GameDetail_Exception_Grant" xml:space="preserve">
<value>Tạo ngoại lệ…</value>
</data>
<data name="GameDetail_Exception_Withdraw" xml:space="preserve">
<value>Rút ngoại lệ</value>
</data>
<data name="Settings_Exceptions_Refresh" xml:space="preserve">
<value>Làm mới</value>
</data>
<data name="Settings_Exceptions_Checking" xml:space="preserve">
<value>Capture agent đang kiểm tra thư viện; các game đủ điều kiện sẽ hiện ở đây trong vòng một phút. Bấm Làm mới để xem.</value>
</data>
<data name="Tier_HookedException" xml:space="preserve">
<value>Hook · ngoại lệ</value>
</data>
<data name="Games_Card_Exception" xml:space="preserve">
<value>Ngoại lệ</value>
</data>
<data name="Session_UnderException_Format" xml:space="preserve">
<value>Được hook dưới ngoại lệ user-mode cho {0}</value>
</data>
</root>
@@ -0,0 +1,53 @@
using System.Globalization;
using CommunityToolkit.Mvvm.ComponentModel;
using FrameLedger.App.Services;
using SafetyStrings = FrameLedger.Shared.Strings;
namespace FrameLedger.App.ViewModels;
/// <summary>
/// D33's disclosure content (<c>19_SAFETY</c> §The user-mode exception): why the exception is offered, the risk at the same
/// grain as FR-2.1's dialog, what is still refused, how it ends, and that it turns nothing on. <see cref="Accepted"/> — the
/// user ticking "I accept the risk of a ban for this game" — is the one thing that enables the dialog's primary button.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime; a cached CompositeFormat would pin the first culture")]
public sealed partial class AntiCheatExceptionDialogViewModel : ObservableObject
{
[ObservableProperty]
private bool _accepted;
public AntiCheatExceptionDialogViewModel(AntiCheatExceptionFacts facts)
{
ArgumentNullException.ThrowIfNull(facts);
Facts = facts;
Title = string.Format(CultureInfo.CurrentCulture, SafetyStrings.Safety_Exception_Title_Format, facts.GameName);
Intro = string.Format(CultureInfo.CurrentCulture, SafetyStrings.Safety_Exception_Intro_Format, facts.Family, facts.Signal);
Why = string.Format(CultureInfo.CurrentCulture, SafetyStrings.Safety_Exception_Why_Format, facts.Family, facts.Sessions);
Risk = string.Format(CultureInfo.CurrentCulture, SafetyStrings.Safety_Exception_Risk_Format, facts.Family);
Still = string.Format(CultureInfo.CurrentCulture, SafetyStrings.Safety_Exception_Still_Format, facts.Family);
}
public AntiCheatExceptionFacts Facts { get; }
public string Title { get; }
public string Intro { get; }
public string Why { get; }
public string Risk { get; }
public string Still { get; }
public static string Ends => SafetyStrings.Safety_Exception_Ends;
public static string Next => SafetyStrings.Safety_Exception_Next;
public static string Online => SafetyStrings.Safety_Exception_Online;
public static string AcceptText => SafetyStrings.Safety_Exception_Accept;
public static string GrantText => SafetyStrings.Safety_Exception_Grant;
public static string CancelText => SafetyStrings.Safety_Exception_Cancel;
}
@@ -0,0 +1,52 @@
using System.Globalization;
using CommunityToolkit.Mvvm.Input;
using FrameLedger.App.Services;
namespace FrameLedger.App.ViewModels;
/// <summary>
/// One row of Settings ▸ Capture's user-mode exception list (D33): the game, what was found, the evidence, the state — and
/// the one action the state allows, making the exception (through its disclosure) or withdrawing it.
/// </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 sealed partial class ExceptionGameViewModel
{
private readonly Func<ExceptionGameViewModel, Task> _grant;
private readonly Func<ExceptionGameViewModel, Task> _withdraw;
public ExceptionGameViewModel(long gameId, string name, ExceptionView view, Func<ExceptionGameViewModel, Task> grant, Func<ExceptionGameViewModel, Task> withdraw)
{
ArgumentNullException.ThrowIfNull(view);
GameId = gameId;
Name = name ?? throw new ArgumentNullException(nameof(name));
View = view;
_grant = grant ?? throw new ArgumentNullException(nameof(grant));
_withdraw = withdraw ?? throw new ArgumentNullException(nameof(withdraw));
FindingText = string.Format(CultureInfo.CurrentCulture, Strings.Exception_Finding_Format, view.Family ?? Strings.Common_NotAvailable, view.Signal ?? Strings.Common_NotAvailable);
SessionsText = string.Format(CultureInfo.CurrentCulture, Strings.Exception_Sessions_Format, view.Sessions);
}
public long GameId { get; }
public string Name { get; }
public ExceptionView View { get; }
public string FindingText { get; }
public string SessionsText { get; }
public string StateText => View.Text;
public string? LapseText => View.LapseText;
public bool CanGrant => View.CanGrant;
public bool CanWithdraw => View.CanWithdraw;
[RelayCommand]
private Task GrantAsync() => _grant(this);
[RelayCommand]
private Task WithdrawAsync() => _withdraw(this);
}
@@ -25,7 +25,11 @@ public sealed class GameCardViewModel
// An entry the guard found anti-cheat in says so (beta.8): its hooking is off for good, and "Hooking off" read as
// a switch the user could still flip. Not recorded still comes first — nothing runs for it at all.
AntiCheat = Recorded && card.Row.BlockedByGuard;
// D33: a blocked game with a user-mode exception on its row says so; whether Settings' option lets it apply is the
// game page's to say.
Excepted = AntiCheat && card.Row.AcException.IsGranted;
HookText = !Recorded ? Strings.Games_Card_NotRecorded
: Excepted ? Strings.Games_Card_Exception
: AntiCheat ? Strings.Games_Card_AntiCheat
: HookOn ? Strings.Games_Card_HookOn : Strings.Games_Card_HookOff;
SessionCount = card.Summary?.SessionCount ?? 0;
@@ -63,6 +67,9 @@ public sealed class GameCardViewModel
/// </summary>
public bool AntiCheat { get; }
/// <summary>D33: the anti-cheat game carries a user-mode exception (<c>games.ac_exception_at</c>); the pill says "Exception".</summary>
public bool Excepted { get; }
public string HookText { get; }
public long SessionCount { get; }
@@ -42,10 +42,14 @@ public sealed partial class GameDetailViewModel : ObservableObject
private readonly IHardwareSnapshotRepository _hardware;
private readonly SessionSelection _selection;
private readonly RegisteredSettings? _settings;
private readonly AntiCheatExceptions? _exceptions;
private readonly long? _gameId;
// ui.hide_anticheat_hooking (2026-09-25), read at each load; on until the settings say otherwise, as its default is.
private bool _hideAntiCheatHooking = true;
// hooking.usermode_ac_exceptions (D33, 2026-09-26), read at each load; off until the settings say otherwise.
private bool _exceptionsOn;
private GameDetail? _detail;
[ObservableProperty]
@@ -107,6 +111,32 @@ public sealed partial class GameDetailViewModel : ObservableObject
[ObservableProperty]
private bool _hookingSectionVisible = true;
/// <summary>
/// D33: the user-mode exception's card on a blocked game — shown while the option is on, and for an exception kept while
/// it is off; its state is the Agent's (<see cref="ExceptionView"/>).
/// </summary>
[ObservableProperty]
private bool _exceptionCardVisible;
[ObservableProperty]
private string? _exceptionText;
/// <summary>D33: what an exception in force means, on the page it applies to; null otherwise.</summary>
[ObservableProperty]
private string? _exceptionInForceText;
[ObservableProperty]
private string? _exceptionSuspendedText;
[ObservableProperty]
private string? _exceptionLapseText;
[ObservableProperty]
private bool _canGrantException;
[ObservableProperty]
private bool _canWithdrawException;
/// <summary>
/// Why the switch cannot be turned on when the executable cannot run as x64 (beta.8, <c>exe_machine</c>); null otherwise.
/// A switch that is on for such a game can still be turned off.
@@ -172,8 +202,9 @@ public sealed partial class GameDetailViewModel : ObservableObject
public GameDetailViewModel(GameLibrary library, GameSelection selection, HookingConsent consent, IPageNavigator navigator,
IConfirmations confirmations, IEditGamePrompt edit, IMessageStrip strip, ISessionSummaryOpener summaries,
SessionSeriesLoader loader, IHardwareSnapshotRepository hardware, SessionSelection sessionSelection, IGamePicker picker,
RegisteredSettings? settings = null, IAgentLink? agent = null)
RegisteredSettings? settings = null, IAgentLink? agent = null, AntiCheatExceptions? exceptions = null)
{
_exceptions = exceptions;
_settings = settings;
_agent = agent;
_picker = picker ?? throw new ArgumentNullException(nameof(picker));
@@ -194,6 +225,12 @@ public sealed partial class GameDetailViewModel : ObservableObject
public static string BackText => Strings.GameDetail_Back;
public static string ExceptionHeader => Strings.GameDetail_Exception_Header;
public static string GrantExceptionText => Strings.GameDetail_Exception_Grant;
public static string WithdrawExceptionText => Strings.GameDetail_Exception_Withdraw;
public static string EditText => Strings.GameDetail_Edit;
public static string RemoveText => Strings.GameDetail_Remove;
@@ -346,6 +383,7 @@ public sealed partial class GameDetailViewModel : ObservableObject
if (_settings is not null)
{
_hideAntiCheatHooking = await _settings.GetBooleanAsync(SettingsRegistry.UiHideAntiCheatHooking, ct).ConfigureAwait(true);
_exceptionsOn = await _settings.GetBooleanAsync(SettingsRegistry.HookingUserModeExceptions, ct).ConfigureAwait(true);
}
Present(detail);
@@ -510,6 +548,13 @@ public sealed partial class GameDetailViewModel : ObservableObject
[RelayCommand]
private Task ToggleRecordingAsync() => RunAsync(ToggleRecordingCoreAsync);
/// <summary>D33: the exception's disclosure, then the request; the Agent gathers the facts and grants or refuses.</summary>
[RelayCommand]
private Task GrantExceptionAsync() => RunAsync(GrantExceptionCoreAsync);
[RelayCommand]
private Task WithdrawExceptionAsync() => RunAsync(WithdrawExceptionCoreAsync);
[RelayCommand]
private Task ReEnableHookingAsync() => RunAsync(EnableAsync);
@@ -671,6 +716,61 @@ public sealed partial class GameDetailViewModel : ObservableObject
_navigator.Navigate<GamesPage>();
}
private async Task GrantExceptionCoreAsync()
{
if (Game is null || ExceptionView.Of(Game) is not { CanGrant: true } view)
{
return;
}
Busy = true;
try
{
AntiCheatExceptionResult result = _exceptions is null
? AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable)
: await _exceptions.GrantAsync(Game.Id, new AntiCheatExceptionFacts(Game.Name, view.Family ?? string.Empty, view.Signal ?? string.Empty,
view.Sessions)).ConfigureAwait(true);
Notice(result, Game.Name);
}
finally
{
Busy = false;
}
await LoadAsync().ConfigureAwait(true);
}
private async Task WithdrawExceptionCoreAsync()
{
if (Game is null)
{
return;
}
Busy = true;
try
{
AntiCheatExceptionResult result = _exceptions is null
? AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable)
: await _exceptions.WithdrawAsync(Game.Id).ConfigureAwait(true);
Notice(result, Game.Name);
}
finally
{
Busy = false;
}
await LoadAsync().ConfigureAwait(true);
}
/// <summary>D33: an exception's outcome as this page's notice — a success is said, not only shown by the card changing.</summary>
private void Notice(AntiCheatExceptionResult result, string gameName)
{
NoticeText = result.MessageFor(gameName);
NoticeSeverity = result.Succeeded ? InfoBarSeverity.Success : InfoBarSeverity.Warning;
OnPropertyChanged(nameof(NoticeVisible));
}
/// <summary>A refusal, a mismatch or a failure is a persistent notice on the page; a success clears it.</summary>
private void Notice(HookingConsentResult result)
{
@@ -826,7 +926,11 @@ public sealed partial class GameDetailViewModel : ObservableObject
// An executable that cannot run as x64 (beta.8): turning hooking ON could only be refused; a switch that is on
// (enabled before this build read the file) can still be turned off.
bool notX64 = ExecutableArchitecture.IsKnownNotHookable(row.ExeMachine);
HookToggleEnabled = !blocked && !Busy && (row.HookEnabled || !notX64);
// D33: a blocked game whose user-mode exception is in force (the option on, a grant on the row) may be switched on —
// through FR-2.1's dialog as ever, and the Agent's pre-scan names the family; the finding stays on the page.
ExceptionView? exception = ExceptionView.Of(row);
bool exceptionInForce = _exceptionsOn && exception is { Kind: ExceptionViewKind.Granted };
HookToggleEnabled = (!blocked || exceptionInForce) && !Busy && (row.HookEnabled || !notX64);
NotX64Text = notX64 && !blocked
? string.Format(CultureInfo.CurrentCulture, Strings.Hooking_NotX64_Format, Formats.Architecture(row.ExeMachine))
: null;
@@ -838,7 +942,8 @@ public sealed partial class GameDetailViewModel : ObservableObject
// beta.8 (owner request 2026-09-25): for an anti-cheat game the card is a switch that can never be turned on, so
// by default it gives way to the finding alone. The setting off keeps the card, with the finding under it.
HookingSectionVisible = !(blocked && _hideAntiCheatHooking);
HookingSectionVisible = !(blocked && _hideAntiCheatHooking) || exceptionInForce;
PresentException(exception, exceptionInForce);
AntiCheatText = found is not null && !HookingSectionVisible
? string.Format(CultureInfo.CurrentCulture, Strings.GameDetail_AntiCheat_Format, found)
: null;
@@ -850,6 +955,20 @@ public sealed partial class GameDetailViewModel : ObservableObject
UnverifiedText = string.Equals(row.HookPrescanState, "unverified", StringComparison.Ordinal) ? Strings.GameDetail_Hooking_Unverified : null;
}
/// <summary>D33: the exception card — its state from the Agent's columns, and the one action that state allows.</summary>
private void PresentException(ExceptionView? view, bool inForce)
{
ExceptionCardVisible = view is not null && (_exceptionsOn || view.Kind == ExceptionViewKind.Granted);
ExceptionText = view?.Text;
ExceptionLapseText = view?.LapseText;
ExceptionInForceText = inForce && view?.Family is { } family
? string.Format(CultureInfo.CurrentCulture, Strings.GameDetail_Exception_Granted_Format, family)
: null;
ExceptionSuspendedText = view is { Kind: ExceptionViewKind.Granted } && !_exceptionsOn ? Strings.GameDetail_Exception_Suspended : null;
CanGrantException = _exceptionsOn && view is { CanGrant: true } && !Busy;
CanWithdrawException = view is { CanWithdraw: true } && !Busy;
}
private void PresentSessions(GameDetail detail)
{
Sessions.Clear();
@@ -1,3 +1,4 @@
using System.Globalization;
using FrameLedger.App.Services;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.TriState;
@@ -10,6 +11,7 @@ namespace FrameLedger.App.ViewModels;
/// <see cref="FpsPresentation"/> (<c>—</c> for a measured none, <c>N/A</c> for not measured, never blank, never
/// zero — FR-4.9), the lows, resolution · upscaler, the chips resolved with the annotation and the game default.
/// </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 sealed class SessionItemViewModel
{
public SessionItemViewModel(SessionRow row, SessionAnnotation? annotation, GameRow game)
@@ -21,8 +23,12 @@ public sealed class SessionItemViewModel
DateText = Formats.Date(row.StartedAt);
DurationText = Formats.Duration(row.DurationSeconds);
IsHooked = row.Tier == CaptureTier.Hooked;
TierText = IsHooked ? Strings.Tier_Hooked : Strings.Tier_NotHooked;
TierTooltip = IsHooked ? Strings.Tier_Hooked_Tooltip : Strings.Tier_NotHooked_Tooltip;
// D33: a hooked session under the game's user-mode exception is marked with it wherever its tier is said.
TierText = !IsHooked ? Strings.Tier_NotHooked : row.AcExceptionFamily is null ? Strings.Tier_Hooked : Strings.Tier_HookedException;
TierTooltip = !IsHooked ? Strings.Tier_NotHooked_Tooltip
: row.AcExceptionFamily is { } family
? Strings.Tier_Hooked_Tooltip + Environment.NewLine + string.Format(CultureInfo.CurrentCulture, Strings.Session_UnderException_Format, family)
: Strings.Tier_Hooked_Tooltip;
NativeText = FpsPresentation.NativeColumn(row);
DisplayedText = FpsPresentation.DisplayedColumn(row);
FgText = FpsPresentation.FactorColumn(row);
@@ -78,6 +78,10 @@ public sealed partial class SessionSummaryViewModel : ObservableObject
[ObservableProperty]
private string _exitLine = string.Empty;
/// <summary>D33: the session was hooked under the game's user-mode exception, and for which anti-cheat; null otherwise.</summary>
[ObservableProperty]
private string? _exceptionLine;
/// <summary>Tier 2's payload (2026-09-22): why this session measured nothing, from the row's notes; empty for a hooked row.</summary>
[ObservableProperty]
private string _tier2Reason = string.Empty;
@@ -321,6 +325,9 @@ public sealed partial class SessionSummaryViewModel : ObservableObject
Tier2Reason = IsHooked ? string.Empty : Formats.Tier2Reason(row.CaptureNotes);
ExitLine = string.Format(CultureInfo.CurrentCulture, Strings.Exit_Line_Format,
Formats.ExitText(row.ExitStatus, Application.Recording.CaptureNotes.Parse(row.CaptureNotes)));
ExceptionLine = row.AcExceptionFamily is { } family
? string.Format(CultureInfo.CurrentCulture, Strings.Session_UnderException_Format, family)
: null;
Readout = FpsPresentation.FromRow(row);
Line = string.Format(CultureInfo.CurrentCulture, Strings.Summary_Line_Format,
IsHooked ? Formats.Api(row.Api) : Strings.Tier_NotHooked, row.PresentMode ?? Strings.Common_NotAvailable,
@@ -39,6 +39,7 @@ public sealed partial class SettingsViewModel : ObservableObject
private readonly IAgentTool _tool;
private readonly WindowClosePolicy _closePolicy;
private readonly IFirstRunFlow _firstRun;
private readonly AntiCheatExceptions? _exceptions;
private bool _loading = true;
[ObservableProperty]
@@ -73,6 +74,18 @@ public sealed partial class SettingsViewModel : ObservableObject
[ObservableProperty]
private bool _hideAntiCheatHooking = true;
/// <summary>
/// <c>hooking.usermode_ac_exceptions</c> (D33, owner decision 2026-09-26): whether a game's user-mode anti-cheat exception
/// may apply at all. Off by default; off suspends every exception below without deleting any.
/// </summary>
[ObservableProperty]
[NotifyPropertyChangedFor(nameof(ExceptionsSuspended))]
private bool _userModeExceptions;
/// <summary>D33: the Agent has not answered about every blocked game yet (the option was just turned on).</summary>
[ObservableProperty]
private bool _exceptionsChecking;
/// <summary><c>ui.fps_decimals</c> (beta.8): every FPS figure with two decimals ("62.40") instead of a whole number.</summary>
[ObservableProperty]
private bool _fpsTwoDecimals;
@@ -120,8 +133,11 @@ public sealed partial class SettingsViewModel : ObservableObject
IMaintenanceState maintenance,
IAgentTool tool,
WindowClosePolicy closePolicy,
IFirstRunFlow firstRun)
IFirstRunFlow firstRun,
AntiCheatExceptions? exceptions = null)
{
// D33: the user-mode exception's requests; a composition without it (a test) answers that the Agent is unavailable.
_exceptions = exceptions;
_firstRun = firstRun ?? throw new ArgumentNullException(nameof(firstRun));
_maintenance = maintenance ?? throw new ArgumentNullException(nameof(maintenance));
_tool = tool ?? throw new ArgumentNullException(nameof(tool));
@@ -182,6 +198,15 @@ public sealed partial class SettingsViewModel : ObservableObject
public ObservableCollection<HookedGameViewModel> HookedGames { get; } = [];
/// <summary>
/// D33: the games the user-mode exception concerns — in force, eligible, or held back only by the session count. The rest
/// of the blocked games say why not on their own pages.
/// </summary>
public ObservableCollection<ExceptionGameViewModel> ExceptionGames { get; } = [];
/// <summary>D33: the option is off and exceptions are kept below that do not apply.</summary>
public bool ExceptionsSuspended => !UserModeExceptions && ExceptionGames.Any(static g => g.CanWithdraw);
public string KillSwitchState => KillSwitch ? Strings.Settings_KillSwitch_On : Strings.Settings_KillSwitch_Off;
/// <summary>12_BUILD: the registration exists only while a hook-enabled game references the Vulkan loader (P4 PR-2) — the button follows the same rule as the Agent's reconciler.</summary>
@@ -234,6 +259,21 @@ public sealed partial class SettingsViewModel : ObservableObject
partial void OnHideAntiCheatHookingChanged(bool value) => Persist(SettingsRegistry.UiHideAntiCheatHooking, value);
/// <summary>D33: the option is one settings row the Agent reads at every session start and command; the list follows it.</summary>
partial void OnUserModeExceptionsChanged(bool value)
{
if (!_loading)
{
Pending = WriteThenRefreshAsync(SettingsRegistry.HookingUserModeExceptions, value ? "1" : "0");
}
}
private async Task WriteThenRefreshAsync(SettingDefinition definition, string value)
{
await WriteAsync(definition, value).ConfigureAwait(true);
await RefreshCoreAsync().ConfigureAwait(true);
}
partial void OnFpsTwoDecimalsChanged(bool value)
{
if (_loading)
@@ -356,6 +396,7 @@ public sealed partial class SettingsViewModel : ObservableObject
BackgroundCapture = await _settings.GetBooleanAsync(SettingsRegistry.CaptureBackground).ConfigureAwait(true);
MinimizeToTray = await _settings.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true);
HideAntiCheatHooking = await _settings.GetBooleanAsync(SettingsRegistry.UiHideAntiCheatHooking).ConfigureAwait(true);
UserModeExceptions = await _settings.GetBooleanAsync(SettingsRegistry.HookingUserModeExceptions).ConfigureAwait(true);
FpsTwoDecimals = await _settings.GetBooleanAsync(SettingsRegistry.UiFpsDecimals).ConfigureAwait(true);
OnlineMetadata = await _settings.GetBooleanAsync(SettingsRegistry.PrivacyOnlineMetadata).ConfigureAwait(true);
UpdateChannel = await _settings.GetAsync(SettingsRegistry.UpdateChannel).ConfigureAwait(true);
@@ -381,6 +422,8 @@ public sealed partial class SettingsViewModel : ObservableObject
HookedGames.Add(new HookedGameViewModel(card.Row.Id, card.Row.Name, RevokeAsync, CapabilityFlags.Contains(card.Row.CapabilityFlagsJson, "vulkan")));
}
PresentExceptions(cards);
Shared.Ipc.HelloAck? hello = _agent.Hello;
ElevationText = hello is null ? Strings.Settings_VkLayer_Unknown : hello.Elevated ? Strings.Settings_Agent_Elevated : Strings.Settings_Agent_NotElevated;
MaintenanceSnapshot = await _maintenance.ReadAsync().ConfigureAwait(true);
@@ -410,6 +453,71 @@ public sealed partial class SettingsViewModel : ObservableObject
}
}
/// <summary>D33: the exception list from the Agent's columns — the App reads them and never writes one.</summary>
private void PresentExceptions(IReadOnlyList<GameCard> cards)
{
ExceptionGames.Clear();
bool checking = false;
foreach (GameCard card in cards.Where(static c => c.Row.InLibrary).OrderBy(static c => c.Row.Name, StringComparer.CurrentCultureIgnoreCase))
{
if (ExceptionView.Of(card.Row) is not { } view)
{
continue;
}
checking |= view.Kind == ExceptionViewKind.Checking;
// With the option off only a kept grant is listed (suspended): nothing may be made while it is off.
bool listed = UserModeExceptions
? view.Kind is ExceptionViewKind.Granted or ExceptionViewKind.Eligible or ExceptionViewKind.TooFewSessions
: view.Kind == ExceptionViewKind.Granted;
if (listed)
{
ExceptionGames.Add(new ExceptionGameViewModel(card.Row.Id, card.Row.Name, view, GrantExceptionAsync, WithdrawExceptionAsync));
}
}
ExceptionsChecking = UserModeExceptions && checking;
OnPropertyChanged(nameof(ExceptionsSuspended));
}
/// <summary>D33: the disclosure, then the request; the Agent gathers the facts and grants or refuses.</summary>
private async Task GrantExceptionAsync(ExceptionGameViewModel game)
{
AntiCheatExceptionResult result = _exceptions is null
? AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable)
: await _exceptions.GrantAsync(game.GameId, new AntiCheatExceptionFacts(game.Name, game.View.Family ?? string.Empty,
game.View.Signal ?? string.Empty, game.View.Sessions)).ConfigureAwait(true);
await ReportExceptionAsync(game.Name, result).ConfigureAwait(true);
}
private async Task WithdrawExceptionAsync(ExceptionGameViewModel game)
{
AntiCheatExceptionResult result = _exceptions is null
? AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable)
: await _exceptions.WithdrawAsync(game.GameId).ConfigureAwait(true);
await ReportExceptionAsync(game.Name, result).ConfigureAwait(true);
}
private async Task ReportExceptionAsync(string name, AntiCheatExceptionResult result)
{
if (result.MessageFor(name) is { } message)
{
if (result.Succeeded)
{
_strip.Success(name, message);
}
else
{
_strip.Warn(name, message);
}
}
await RefreshCoreAsync().ConfigureAwait(true);
}
[RelayCommand]
private Task RefreshExceptionsAsync() => RefreshAsync();
private async Task RevokeAsync(HookedGameViewModel game)
{
HookingConsentResult result = await _consent.DisableAsync(game.GameId).ConfigureAwait(true);
@@ -38,6 +38,8 @@
<!-- header line + chips -->
<ui:TextBlock Appearance="Secondary" Text="{Binding ViewModel.Line}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExitLine}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionLine}"
Visibility="{Binding ViewModel.ExceptionLine, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Appearance="Tertiary" TextWrapping="Wrap" Text="{Binding ViewModel.HardwareLine}" />
<ui:TextBlock Appearance="Tertiary" TextWrapping="Wrap" Text="{Binding ViewModel.LibrariesLine}"
Visibility="{Binding ViewModel.LibrariesLine, Converter={StaticResource NullToCollapsed}}" />
@@ -10,5 +10,12 @@ public sealed record AntiCheatPreScanReport
public int Current { get; init; }
public int Unreadable { get; init; }
public bool RulesUnusable { get; init; }
/// <summary>D33: blocked entries whose user-mode exception eligibility the pass (re)wrote.</summary>
public int ExceptionsChecked { get; init; }
/// <summary>D33: exceptions the pass ended — an executable that changed, a game no longer eligible.</summary>
public int ExceptionsEnded { get; init; }
public int Scanned => Found + Clean + Unverified;
}
@@ -1,3 +1,4 @@
using FrameLedger.Application.Capture;
using FrameLedger.Application.Consent;
using FrameLedger.Application.Detection;
using FrameLedger.Application.Ipc;
@@ -34,6 +35,13 @@ namespace FrameLedger.Application.AntiCheat;
/// session start whatever this sweep wrote, exactly as it did before. It never opens a game's process — the scan
/// reads the executable's path, its install folder and the store's files.
/// </para>
/// <para>
/// <b>A blocked entry is never scanned for a new block, and since D33 (owner decision 2026-09-26) it is asked one other
/// question</b> — whether its user-mode exception may be granted (<see cref="ExceptionPassAsync"/>): while the option is
/// on, a tolerant pre-scan naming the block's family, keyed like the pre-scan so it re-runs only when the rules, the
/// executable or the block change, and a count of the successful Tier-1 sessions. With the option on or off, a grant
/// made on bytes that are no longer on disk ends. Nothing here grants anything or clears a block.
/// </para>
/// </remarks>
public sealed class AntiCheatPreScanSweep : IDisposable
{
@@ -44,12 +52,19 @@ public sealed class AntiCheatPreScanSweep : IDisposable
private readonly IExecutableIdentitySource _identity;
private readonly IIpcEventPublisher? _pipe;
private readonly Func<long, bool> _isRecording;
private readonly ISessionRepository? _sessions;
private readonly IUserModeExceptionSwitch? _exceptions;
private readonly Action<string> _log;
private readonly SemaphoreSlim _wake = new(0, 1);
public AntiCheatPreScanSweep(IGameRepository games, IGameConsentStore consent, IAntiCheatGuard guard, IDetectionRulesSource rules,
IExecutableIdentitySource identity, Action<string> log, IIpcEventPublisher? pipe = null, Func<long, bool>? isRecording = null)
IExecutableIdentitySource identity, Action<string> log, IIpcEventPublisher? pipe = null, Func<long, bool>? isRecording = null,
ISessionRepository? sessions = null, IUserModeExceptionSwitch? exceptions = null)
{
// D33: the evidence and the option the exception pass needs; a sweep composed without them asks no exception
// question at all (the unshipped host, the tests that are not about it).
_sessions = sessions;
_exceptions = exceptions;
_games = games ?? throw new ArgumentNullException(nameof(games));
_consent = consent ?? throw new ArgumentNullException(nameof(consent));
_guard = guard ?? throw new ArgumentNullException(nameof(guard));
@@ -98,8 +113,9 @@ public sealed class AntiCheatPreScanSweep : IDisposable
ct.ThrowIfCancellationRequested();
if (game.BlockedByGuard)
{
// A block is final: nothing scans it again, and nothing this sweep writes could read as clearing it.
report = report with { Blocked = report.Blocked + 1 };
// A block is final: nothing scans it for a new one, and nothing this sweep writes could read as clearing
// it. What is asked of it since D33 is whether its user-mode exception may be granted.
report = await ExceptionPassAsync(game, rulesVersion, report with { Blocked = report.Blocked + 1 }, ct).ConfigureAwait(false);
continue;
}
@@ -124,7 +140,7 @@ public sealed class AntiCheatPreScanSweep : IDisposable
private async ValueTask<AntiCheatPreScanReport> ScanAsync(GameRow game, ExecutableFingerprint onDisk, string rulesVersion,
AntiCheatPreScanReport report, CancellationToken ct)
{
AntiCheatVerdict verdict = await _guard.PreScanGameAsync(onDisk.ExePath, ct).ConfigureAwait(false);
AntiCheatVerdict verdict = await _guard.PreScanGameAsync(onDisk.ExePath, toleratedFamily: null, ct).ConfigureAwait(false);
if (await _consent.RecordPreScanAsync(onDisk, verdict, rulesVersion, ct).ConfigureAwait(false) != ConsentWriteOutcome.Written)
{
return report;
@@ -150,6 +166,78 @@ public sealed class AntiCheatPreScanSweep : IDisposable
: report with { Unverified = report.Unverified + 1 };
}
/// <summary>
/// D33: the exception question about one BLOCKED entry. A grant made on bytes that are no longer on disk ends whether
/// or not the option is on; the rest runs only while it is — a tolerant pre-scan naming the block's family when the
/// rules, the executable or the block changed since the last one, and the session count every pass — and ends a grant
/// the facts no longer support. A scan that could not answer ends nothing: the session start runs the full check anyway.
/// </summary>
private async ValueTask<AntiCheatPreScanReport> ExceptionPassAsync(GameRow game, string rulesVersion, AntiCheatPreScanReport report,
CancellationToken ct)
{
if (_sessions is null || game.HookBlockedReason is not { Length: > 0 } block || _isRecording(game.Id)
|| _identity.Read(game.Fingerprint.ExePath) is not { } onDisk)
{
return report;
}
AntiCheatExceptionState state = game.AcException;
bool granted = state.IsGranted;
if (granted && !state.GrantCovers(onDisk))
{
report = await EndAsync(game, UserModeExceptionLapse.ExecutableChanged, "its executable changed", report, ct).ConfigureAwait(false);
granted = false;
}
if (_exceptions is null || !await _exceptions.IsOnAsync(ct).ConfigureAwait(false))
{
return report;
}
StoredBlock? parsed = StoredBlock.Parse(block);
int sessions = await _sessions.CountSuccessfulHookedAsync(game.Id, ct).ConfigureAwait(false);
bool fresh = state.IsCheckedFor(onDisk, rulesVersion, block);
AntiCheatVerdict? verdict = parsed is not { IsExceptionable: true } b
? null
: fresh && StoredVerdict(state.Verdict) is { } stored
? stored
: await _guard.PreScanGameAsync(onDisk.ExePath, b.Family, ct).ConfigureAwait(false);
bool eligible = verdict is { } v && UserModeExceptionRules.IsEligible(parsed, v, sessions);
if (!fresh || eligible != state.Eligible || sessions != state.Sessions)
{
if (await _consent.RecordExceptionEligibilityAsync(onDisk, block, verdict, sessions, rulesVersion, ct).ConfigureAwait(false)
== ConsentWriteOutcome.Written)
{
report = report with { ExceptionsChecked = report.ExceptionsChecked + 1 };
_log($"prescan: {game.Name} — user-mode exception {(eligible ? "eligible" : "not eligible")} "
+ $"({(verdict is { } said ? Said(said) : "not a module, file or folder finding")}; {sessions} successful hooked sessions)");
}
}
bool couldNotVerify = verdict is { IsAllowed: false, IsFindingAboutTheGame: false };
return granted && !eligible && !couldNotVerify
? await EndAsync(game, UserModeExceptionLapse.NoLongerEligible, "the game is no longer eligible", report, ct).ConfigureAwait(false)
: report;
}
private async ValueTask<AntiCheatPreScanReport> EndAsync(GameRow game, string lapse, string why, AntiCheatPreScanReport report, CancellationToken ct)
{
if (await _consent.RevokeAntiCheatExceptionAsync(game.Fingerprint.ExePath, lapse, ct).ConfigureAwait(false) != ConsentWriteOutcome.Written)
{
return report;
}
_log($"prescan: {game.Name} — user-mode exception ended: {why} ({lapse})");
return report with { ExceptionsEnded = report.ExceptionsEnded + 1 };
}
/// <summary>A stored tolerant verdict (<c>Reason|Family|Signal</c>) back as the verdict it was; null when it cannot be read.</summary>
private static AntiCheatVerdict? StoredVerdict(string? stored) =>
StoredBlock.Parse(stored) is { } v ? AntiCheatVerdict.FromNative((int)v.Reason, v.Family, v.Signal) : null;
private static string Said(AntiCheatVerdict v) => $"{v.Reason} {v.Family} {v.Signal}".Trim();
/// <summary>The pre-scan's own key (schema 0010) against the rules and the file right now: any difference is a re-scan.</summary>
public static bool IsStale(GameRow game, ExecutableFingerprint onDisk, string rulesVersion)
{
@@ -23,10 +23,16 @@ namespace FrameLedger.Application.AntiCheat;
/// the far side of a returned verdict.
/// </para>
/// </remarks>
public sealed class GuardSupervisor(IAntiCheatGuard guard)
public sealed class GuardSupervisor(IAntiCheatGuard guard, string? toleratedFamily = null)
{
private readonly IAntiCheatGuard _guard = guard ?? throw new ArgumentNullException(nameof(guard));
/// <summary>
/// D33: the family the session's user-mode exception covers, named to every re-scan exactly as it was to the injection
/// — the guard still honours it only for a user-mode family and refuses on anything else. Null for every other session.
/// </summary>
public string? ToleratedFamily { get; } = toleratedFamily;
/// <summary>
/// Completed guard evaluations. Published to <c>FlControlBlock.guardTicks</c>.
/// </summary>
@@ -66,7 +72,7 @@ public sealed class GuardSupervisor(IAntiCheatGuard guard)
return false;
}
AntiCheatVerdict verdict = await _guard.EvaluateAsync(targetPid, ct).ConfigureAwait(false);
AntiCheatVerdict verdict = await _guard.EvaluateAsync(targetPid, ToleratedFamily, ct).ConfigureAwait(false);
// THE ONE SITE. Everything above can fail, throw or cancel; nothing
// below runs unless a verdict actually came back.
@@ -31,8 +31,9 @@ namespace FrameLedger.Application.AntiCheat;
public sealed class HookRequest
{
private HookRequest(int targetPid, string payloadPath, bool hookEnabled, DateTimeOffset? consentedAt,
string? blockedReason, int waitForPresentationRuntimeMs, bool killSwitchEngaged)
string? blockedReason, int waitForPresentationRuntimeMs, bool killSwitchEngaged, string? toleratedFamily = null)
{
ToleratedFamily = toleratedFamily;
TargetPid = targetPid;
PayloadPath = payloadPath;
HookEnabled = hookEnabled;
@@ -86,6 +87,17 @@ public sealed class HookRequest
/// <summary><c>games.hook_blocked_reason</c>; non-null means the toggle is disabled.</summary>
public string? BlockedReason { get; }
/// <summary>
/// D33 (owner decision 2026-09-26): the anti-cheat family the game's user-mode exception covers for THIS session, or
/// null — the NAME the gate hands the guard, which decides itself whether to honour it.
/// </summary>
/// <remarks>
/// Set only by <see cref="FromConsent"/>, from the stored grant, and only when the caller says the exception is in force
/// for this session — the option is on and the Overlay's channel exists (<see cref="UserModeExceptionRules.CoveredFamily"/>).
/// Without it a blocked game is refused before the guard is asked, exactly as before D33.
/// </remarks>
public string? ToleratedFamily { get; }
/// <summary>
/// Build the request the gate evaluates, from a stored record and the executable
/// as it is on disk right now.
@@ -96,9 +108,13 @@ public sealed class HookRequest
/// <param name="payloadPath">The Overlay, resolved beside the guard (§S22).</param>
/// <param name="waitForPresentationRuntimeMs">Launch mode's budget; zero is attach mode.</param>
/// <param name="killSwitchEngaged">FR-2.4's global switch as read from the settings store just now (decision D7).</param>
/// <param name="exceptionInForce">
/// D33: <c>hooking.usermode_ac_exceptions</c> is on AND the Overlay's tolerance channel was published for this pid. False
/// — the default, and every caller before D33 — asks the guard to tolerate nothing.
/// </param>
public static HookRequest FromConsent(
GameConsentRecord record, ExecutableFingerprint observed, int targetPid, string payloadPath,
int waitForPresentationRuntimeMs = 0, bool killSwitchEngaged = false)
int waitForPresentationRuntimeMs = 0, bool killSwitchEngaged = false, bool exceptionInForce = false)
{
ArgumentException.ThrowIfNullOrWhiteSpace(payloadPath);
ArgumentOutOfRangeException.ThrowIfNegative(waitForPresentationRuntimeMs);
@@ -129,7 +145,9 @@ public sealed class HookRequest
consentedAt = null;
}
// THE FAMILY COMES FROM THE STORED GRANT, never from a caller: the caller can only say whether the exception is in
// force this session, which can only turn it off.
return new HookRequest(targetPid, payloadPath, record.HookEnabled, consentedAt, record.BlockedReason,
waitForPresentationRuntimeMs, killSwitchEngaged);
waitForPresentationRuntimeMs, killSwitchEngaged, UserModeExceptionRules.CoveredFamily(record, observed, exceptionInForce));
}
}
@@ -78,7 +78,7 @@ public sealed class HookedCaptureGate(IAntiCheatGuard guard)
"the per-game consent dialog has not been accepted");
}
if (request.BlockedReason is { Length: > 0 } blocked)
if (request.BlockedReason is { Length: > 0 } blocked && request.ToleratedFamily is null)
{
// 19_SAFETY §A game already enabled can become blocked later: a
// patch adds anti-cheat, or updated rules newly match. hook_enabled
@@ -87,11 +87,15 @@ public sealed class HookedCaptureGate(IAntiCheatGuard guard)
return AntiCheatVerdict.Refused(AntiCheatRefusalReason.PreviouslyBlocked, "previously blocked", blocked);
}
// D33 (owner decision 2026-09-26): a blocked game reaches the guard only under its user-mode exception, and then
// with the family NAMED — the guard honours it only for a family that is user-mode throughout, runs every check
// and keeps scanning past what it lets through. Every other game names none, which is the strict guard of before.
//
// Launch mode is the same gate reached through the guard's WAITING entry: the consent checks
// above are identical, and what differs is only WHEN the guard's full scan runs (P1 item 2).
return request.WaitForPresentationRuntimeMs > 0
? await _guard.GuardedInjectWhenReadyAsync(request.TargetPid, request.PayloadPath,
request.WaitForPresentationRuntimeMs, ct).ConfigureAwait(false)
: await _guard.GuardedInjectAsync(request.TargetPid, request.PayloadPath, ct).ConfigureAwait(false);
request.WaitForPresentationRuntimeMs, request.ToleratedFamily, ct).ConfigureAwait(false)
: await _guard.GuardedInjectAsync(request.TargetPid, request.PayloadPath, request.ToleratedFamily, ct).ConfigureAwait(false);
}
}
@@ -19,6 +19,14 @@ namespace FrameLedger.Application.AntiCheat;
/// then passes to an injector. <see cref="GuardedInjectAsync"/> injects, or
/// refuses. The guard owns the chokepoint (§S13(b)).
/// </para>
/// <para>
/// <b>Every method takes <c>toleratedFamily</c> since D33 (owner decision 2026-09-26)</b> — the NAME of the one anti-cheat
/// family a game's user-mode exception covers, or null for none, and required rather than defaulted so every caller
/// states which it means. It is a name and never evidence: the guard resolves it against its own rules, honours it only
/// for a family whose every signal is user-mode, runs every check and keeps scanning past what it lets through
/// (<c>19_SAFETY</c> §The user-mode exception). A pass that let something through is
/// <see cref="AntiCheatRefusalReason.AllowedUnderUserModeException"/>.
/// </para>
/// </remarks>
public interface IAntiCheatGuard
{
@@ -27,14 +35,14 @@ public interface IAntiCheatGuard
/// in-session re-scan of <c>19_SAFETY</c> §During a session, which must
/// reach a verdict about a process we are already inside.
/// </summary>
ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default);
ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default);
/// <summary>
/// Run every check and, only on a pass, inject. There is no overload that
/// skips the checks and no way to supply evidence — the guard collects its
/// own, so a caller can ask but only the guard answers.
/// </summary>
ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, CancellationToken ct = default);
ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily, CancellationToken ct = default);
/// <summary>
/// Launch mode (P1 item 2). Wait — up to <paramref name="timeoutMs"/> — until the target has mapped a
@@ -50,7 +58,7 @@ public interface IAntiCheatGuard
/// <see cref="AntiCheatRefusalReason.LaunchNoPresentationRuntime"/>. The caller launched and holds
/// the process; the guard creates and terminates nothing.
/// </remarks>
ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs,
ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, string? toleratedFamily,
CancellationToken ct = default);
/// <summary>
@@ -79,5 +87,5 @@ public interface IAntiCheatGuard
/// on passing while the thing it guards grew somewhere else.
/// </para>
/// </remarks>
ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, CancellationToken ct = default);
ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily, CancellationToken ct = default);
}
@@ -0,0 +1,29 @@
namespace FrameLedger.Application.AntiCheat;
/// <summary>
/// D33: why a user-mode exception ended — <c>games.ac_exception_lapsed_reason</c>, one of these words, which the App
/// says in the user's language (<c>19_SAFETY</c> §The user-mode exception, What ends it).
/// </summary>
public static class UserModeExceptionLapse
{
/// <summary>The user withdrew it.</summary>
public const string Withdrawn = "Withdrawn";
/// <summary>The executable is not the one the grant was made on: a game update, or <i>Change executable</i>.</summary>
public const string ExecutableChanged = "ExecutableChanged";
/// <summary>The guard no longer lets the game through under it: a new finding, a <c>.sys</c>, the family turned kernel-level, too few sessions.</summary>
public const string NoLongerEligible = "NoLongerEligible";
/// <summary>A finding about the game at a session's start, at the 30 s re-scan or when hooking was turned on.</summary>
public const string NewFinding = "NewFinding";
/// <summary>A session under it was unhooked for safety by the 30 s re-scan.</summary>
public const string SafetyUnhook = "SafetyUnhook";
/// <summary>The Overlay stopped observing on its own: another anti-cheat's module loaded in the game.</summary>
public const string OverlayStopped = "OverlayStopped";
/// <summary>A session under it ended in a crash.</summary>
public const string SessionCrashed = "SessionCrashed";
}
@@ -0,0 +1,61 @@
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
namespace FrameLedger.Application.AntiCheat;
/// <summary>
/// D33 (owner decision 2026-09-26): the managed rules of the user-mode exception — what a grant needs before the guard is
/// even asked to tolerate a family, and the words its end is recorded in. The guard's own rules (which family is user-mode,
/// what is never excepted, scanning past what it lets through) are native and are not repeated here
/// (<c>19_SAFETY</c> §The user-mode exception).
/// </summary>
/// <remarks>
/// <para>
/// <b>Everything here can only narrow.</b> <see cref="CoveredFamily"/> answers null unless every managed condition holds,
/// and a non-null answer is a NAME the guard may still decline — it honours only a family whose every signal is
/// user-mode, and it refuses on anything else it finds. There is no path from this class to an injection that the
/// guard did not pass.
/// </para>
/// </remarks>
public static class UserModeExceptionRules
{
/// <summary>The owner's threshold: successful Tier-1 sessions of the game before its exception may be granted.</summary>
/// <remarks>
/// "Successful" is <c>ISessionRepository.CountSuccessfulHookedAsync</c>'s: hooked, frames recorded, <c>exit_status =
/// normal</c> — which since beta.8 includes End task's exit code 1 and a user's stop, and never a crash, a safety
/// unhook, a degraded or an interrupted session.
/// </remarks>
public const int RequiredSessions = 2;
/// <summary>
/// The family the game's exception covers for a session against <paramref name="observed"/>, or null: the option is
/// on, the row carries a grant, the grant was made on this executable, and the block on the row is a module, file or
/// folder finding naming that same family.
/// </summary>
/// <param name="record">What the store returned.</param>
/// <param name="observed">The executable as it is on disk right now.</param>
/// <param name="optionOn"><c>hooking.usermode_ac_exceptions</c> as read just now; off suspends every exception.</param>
public static string? CoveredFamily(GameConsentRecord record, ExecutableFingerprint observed, bool optionOn)
{
if (!optionOn || !record.IsFromStore || record.Exception is not { } grant || !grant.Covers(observed))
{
return null;
}
return StoredBlock.Parse(record.BlockedReason) is { IsExceptionable: true } block
&& string.Equals(block.Family, grant.Family, StringComparison.Ordinal)
? grant.Family
: null;
}
/// <summary>
/// Whether <paramref name="verdict"/> — a tolerant pre-scan asked about <paramref name="block"/>'s family — makes the
/// game eligible, given <paramref name="sessions"/> successful Tier-1 sessions: the guard passed and named that same
/// family as what it let through, and the evidence reaches <see cref="RequiredSessions"/>.
/// </summary>
public static bool IsEligible(StoredBlock? block, AntiCheatVerdict verdict, int sessions) =>
block is { IsExceptionable: true } b
&& verdict.RanUnderException
&& string.Equals(verdict.Family, b.Family, StringComparison.Ordinal)
&& sessions >= RequiredSessions;
}
@@ -17,6 +17,13 @@ public sealed record CaptureOutcome
/// </summary>
public bool HookingTurnedOff { get; init; }
/// <summary>
/// D33 (owner decision 2026-09-26): the family the game's user-mode exception covered for this session — published to
/// the Overlay and named to the guard at the injection and at every re-scan — or null when none was in force. The
/// recorder marks a HOOKED session with it, and ends the exception when a session under it ends badly.
/// </summary>
public string? ExceptionFamily { get; init; }
public ShmAttachRefusal AttachRefusal { get; init; }
public IReadOnlyList<FlFrameRecord> Records { get; init; } = [];
@@ -44,7 +44,9 @@ public sealed class CaptureSession(
IProcessLauncher? launcher = null,
ICaptureObserver? observer = null,
IKillSwitch? killSwitch = null,
ICapturePauseSource? pause = null)
ICapturePauseSource? pause = null,
IUserModeExceptionSwitch? exceptions = null,
IOverlayToleranceChannel? tolerance = null)
{
/// <summary>Start one session, or say why not.</summary>
/// <remarks>
@@ -88,8 +90,12 @@ public sealed class CaptureSession(
// blocked by a finding, or auto-disabled — gets a Tier-2 session and nothing else: no OpenProcess, no resolver,
// no gate. Until this line existed the resolver ran first, and a hooking-off utility that runs elevated
// (Borderless Gaming, on the owner's machine) was reported as a process an anti-cheat driver protects.
//
// A BLOCKED row is hooking-off too unless its user-mode exception applies to this executable with the option on
// (D33): hook_enabled can be 1 on a blocked row only because the exception once applied, and without it the gate
// would refuse the row anyway — after the resolver had opened the process for nothing.
GameConsentRecord record = await store.FindAsync(normalisedExePath, ct).ConfigureAwait(false);
if (!record.HookEnabled)
if (!record.HookEnabled || await IsBlockedWithoutExceptionAsync(record, observed, ct).ConfigureAwait(false))
{
return await HoldUnhookedAsync(HookingOff(record), normalisedExePath, alive: null, pid: null, ct, stop).ConfigureAwait(false);
}
@@ -119,6 +125,11 @@ public sealed class CaptureSession(
.ConfigureAwait(false);
}
/// <summary>D33: a block on the row that no user-mode exception covers for <paramref name="observed"/> right now.</summary>
private async ValueTask<bool> IsBlockedWithoutExceptionAsync(GameConsentRecord record, ExecutableFingerprint? observed, CancellationToken ct) =>
record.BlockedReason is { Length: > 0 }
&& (observed is not { } exe || UserModeExceptionRules.CoveredFamily(record, exe, await IsExceptionOptionOnAsync(ct).ConfigureAwait(false)) is null);
/// <summary>The verdict a hooking-off row's Tier-2 session carries: the row's block when it has one, else "not enabled".</summary>
private static CaptureOutcome HookingOff(GameConsentRecord record) => new()
{
@@ -227,7 +238,12 @@ public sealed class CaptureSession(
// THE FOURTH INPUT (FR-2.4, decision D7) is read here and handed to the request, so the refusal is
// the gate's — a check upstream of it would make the gate's own "ONLY managed logic" remark false.
bool engaged = await IsKillSwitchEngagedAsync(ct).ConfigureAwait(false);
HookRequest request = HookRequest.FromConsent(record, observed, pid, payloadPath, waitMs, engaged);
// D33: the Overlay's channel is published BEFORE the request is built and the guard asked — the Overlay reads it
// once, before its loader detour exists — and a channel that could not be published is no exception at all: the
// request then names no family and the gate refuses the blocked game as before.
string? covered = UserModeExceptionRules.CoveredFamily(record, observed, await IsExceptionOptionOnAsync(ct).ConfigureAwait(false));
using IDisposable? channel = covered is null ? null : tolerance?.TryPublish(pid, covered);
HookRequest request = HookRequest.FromConsent(record, observed, pid, payloadPath, waitMs, engaged, exceptionInForce: channel is not null);
AntiCheatVerdict verdict = await gate.StartAsync(request, ct).ConfigureAwait(false);
TimeSpan? launchWait = started?.Elapsed;
// THE ONE VERDICT THAT IS NEITHER: the guard passed and injected nothing because the target
@@ -240,7 +256,15 @@ public sealed class CaptureSession(
// A finding about the game turns its hooking off here and now (owner decision 2026-09-22), not only at
// the pre-scan: the guard's start-time scan sees the process and the drivers the pre-scan cannot.
bool turnedOff = await TurnHookingOffAsync(observed, verdict, ct).ConfigureAwait(false);
var refused = new CaptureOutcome { Reason = RefusalOf(verdict.Reason), Verdict = verdict, LaunchWait = launchWait, HookingTurnedOff = turnedOff };
var refused = new CaptureOutcome
{
Reason = RefusalOf(verdict.Reason),
Verdict = verdict,
LaunchWait = launchWait,
HookingTurnedOff = turnedOff,
ExceptionFamily = request.ToleratedFamily,
};
channel?.Dispose();
// Launch mode's two guard refusals are the orchestrator's cue to elect a descendant (04_CAPTURE §Launch
// mode); holding the launcher's session open would delay that. Every other refusal is Tier 2 from here.
return refused.Reason is SessionEndReason.LaunchTargetExited or SessionEndReason.LaunchNoPresentationRuntime
@@ -258,13 +282,14 @@ public sealed class CaptureSession(
Verdict = verdict,
AttachRefusal = refusal,
LaunchWait = launchWait,
ExceptionFamily = request.ToleratedFamily,
}, observedPath, alive, pid, ct, stop).ConfigureAwait(false);
}
using (sink)
{
observer?.Attached(pid, sink.Handshake);
CaptureOutcome result = await DrainAsync(pid, alive, sink, verdict, observed, ct, stop).ConfigureAwait(false);
CaptureOutcome result = await DrainAsync(pid, alive, sink, verdict, observed, request.ToleratedFamily, ct, stop).ConfigureAwait(false);
return result with { LaunchWait = launchWait, TargetPid = pid, ExitCode = alive.ExitCode };
}
}
@@ -297,6 +322,10 @@ public sealed class CaptureSession(
_ => SessionEndReason.RefusedByGuard,
};
/// <summary>D33's option as this session reads it; a loop built without one reads "off", which applies no exception.</summary>
private async ValueTask<bool> IsExceptionOptionOnAsync(CancellationToken ct) =>
exceptions is not null && await exceptions.IsOnAsync(ct).ConfigureAwait(false);
/// <summary>FR-2.4 as this session reads it; a loop built without a switch reads "off".</summary>
private async ValueTask<bool> IsKillSwitchEngagedAsync(CancellationToken ct) =>
killSwitch is not null && await killSwitch.IsEngagedAsync(ct).ConfigureAwait(false);
@@ -331,9 +360,10 @@ public sealed class CaptureSession(
}
private async Task<CaptureOutcome> DrainAsync(int pid, ITargetLiveness alive, ICaptureSink sink,
AntiCheatVerdict verdict, ExecutableFingerprint observed, CancellationToken ct, CancellationToken stop)
AntiCheatVerdict verdict, ExecutableFingerprint observed, string? toleratedFamily, CancellationToken ct, CancellationToken stop)
{
var supervisor = new GuardSupervisor(guard);
// D33: every re-scan names the family the injection named, and nothing else.
var supervisor = new GuardSupervisor(guard, toleratedFamily);
var state = new DrainState(new ModuleTally(modules, ngx));
SessionEndReason end = await SuperviseAsync(pid, alive, sink, supervisor, state, ct, stop).ConfigureAwait(false);
@@ -351,6 +381,7 @@ public sealed class CaptureSession(
Reason = end,
Verdict = final,
HookingTurnedOff = turnedOff,
ExceptionFamily = toleratedFamily,
AttachRefusal = ShmAttachRefusal.Ok,
Records = state.Records,
GapBefore = state.GapBefore,
@@ -0,0 +1,28 @@
namespace FrameLedger.Application.Capture;
/// <summary>
/// D33 (owner decision 2026-09-26): the Agent's channel to the Overlay it is about to inject —
/// <c>Local\FrameLedger.Tolerate.&lt;pid&gt;</c> (<c>fl_tolerance.h</c>, <c>07_IPC</c> §D) — naming the family the game's
/// user-mode exception covers, so a module of that family loading AFTER the injection does not stop the Overlay.
/// </summary>
/// <remarks>
/// <para>
/// <b>Published before the guard is asked, held for the session.</b> The Overlay reads it once, on its init thread, before
/// its loader detour exists; a channel published after the injection would be read by nobody.
/// </para>
/// <para>
/// <b>A channel that could not be published is no exception.</b> <see cref="TryPublish"/> answers null — a name another
/// process already holds, a failed call — and the session then asks the guard to tolerate nothing, so the game is refused
/// as blocked. Injecting under a guard that tolerates the family while the Overlay does not would end in the Overlay's
/// own stop, which reads as the exception failing.
/// </para>
/// <para>
/// It carries a NAME and nothing else. The Overlay resolves it against its own compiled floor and honours only a
/// user-mode family; the 30 s re-scan keeps judging every signal.
/// </para>
/// </remarks>
public interface IOverlayToleranceChannel
{
/// <summary>Publish <paramref name="family"/> for <paramref name="pid"/>; dispose the result when the session ends. Null when it could not be published.</summary>
IDisposable? TryPublish(int pid, string family);
}
@@ -0,0 +1,22 @@
namespace FrameLedger.Application.Capture;
/// <summary>
/// D33 (owner decision 2026-09-26): Settings ▸ Capture's option that lets a game's user-mode anti-cheat exception apply at
/// all — <c>hooking.usermode_ac_exceptions</c>, off by default — as the capture path and the Agent's commands read it.
/// </summary>
/// <remarks>
/// <para>
/// <b>Off suspends every exception and deletes none.</b> A grant stays on its row, and the next session with the option on
/// uses it again; with it off, a blocked game is the blocked game of before D33 — no tolerance named to the guard, no
/// channel to the Overlay, a Tier-2 session (<c>19_SAFETY</c> §The user-mode exception).
/// </para>
/// <para>
/// Read fresh on every ask, like <see cref="IKillSwitch"/>: the App flips one row in <c>settings</c>, and the next session
/// start and the next command take it.
/// </para>
/// </remarks>
public interface IUserModeExceptionSwitch
{
/// <summary>True while the option is on and a game's exception may apply.</summary>
ValueTask<bool> IsOnAsync(CancellationToken ct = default);
}
@@ -0,0 +1,29 @@
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
namespace FrameLedger.Application.Consent;
/// <summary>
/// D33 (owner decision 2026-09-26): what a grant of a user-mode exception rests on, gathered by the Agent at the moment the
/// user accepted the disclosure — never supplied by a client (<c>07_IPC</c> §The pipe is not a trust boundary).
/// </summary>
public sealed record AntiCheatExceptionGrantRequest
{
/// <summary>The executable as it is on disk right now; the grant covers these bytes and no others.</summary>
public required ExecutableFingerprint Fingerprint { get; init; }
/// <summary>The row's <c>hook_blocked_reason</c> the facts below are about; the write happens only while the row still carries it.</summary>
public required string Block { get; init; }
/// <summary>The guard's tolerant pre-scan, asked about the block's family just now.</summary>
public required AntiCheatVerdict Verdict { get; init; }
/// <summary>Successful Tier-1 sessions of the game, counted just now.</summary>
public required int Sessions { get; init; }
/// <summary>The disclosure the user accepted — the Agent's own version, checked before this request exists.</summary>
public required string DisclosureVersion { get; init; }
/// <summary>The Agent's clock.</summary>
public required DateTimeOffset GrantedAt { get; init; }
}
@@ -24,4 +24,11 @@ public enum ConsentWriteOutcome
/// <summary>The write did not happen. Never treat this as "probably fine".</summary>
Failed = 3,
/// <summary>
/// D33: a user-mode exception was asked for a game the facts do not make eligible — the block is not a module, file or
/// folder finding, the tolerant pre-scan did not let that family through, or there are too few successful sessions.
/// Nothing was written.
/// </summary>
NotEligible = 4,
}
@@ -134,4 +134,39 @@ public interface IGameConsentStore
/// </remarks>
ValueTask<ConsentWriteOutcome> RecordPreScanAsync(
ExecutableFingerprint scanned, AntiCheatVerdict verdict, string rulesVersion, CancellationToken ct = default);
/// <summary>
/// D33 (owner decision 2026-09-26): the sweep's answer about one BLOCKED game — whether its user-mode exception may be
/// granted — from the facts it gathered: <paramref name="verdict"/>, a tolerant pre-scan asked about the block's family
/// (null when the block is not of a kind worth asking about), and <paramref name="sessions"/> successful Tier-1 sessions.
/// The rule is <c>UserModeExceptionRules.IsEligible</c>, applied here so the row cannot say "eligible" over facts that are not.
/// </summary>
/// <remarks>
/// Written with the key it was reached under — <paramref name="rulesVersion"/>, the executable's size and mtime in
/// <paramref name="scanned"/>, and the <paramref name="block"/> text — and only while the row still carries that block:
/// a block rewritten between the sweep's read and this write leaves the row alone (<see cref="ConsentWriteOutcome.NotFound"/>).
/// It never grants, never revokes, and never touches the block or the consent stamp.
/// </remarks>
ValueTask<ConsentWriteOutcome> RecordExceptionEligibilityAsync(
ExecutableFingerprint scanned, string block, AntiCheatVerdict? verdict, int sessions, string rulesVersion, CancellationToken ct = default);
/// <summary>
/// D33: grant a game's user-mode exception, on facts gathered just now — the tolerant pre-scan and the session count in
/// <paramref name="grant"/> — after the user accepted its disclosure.
/// </summary>
/// <remarks>
/// <see cref="ConsentWriteOutcome.NotEligible"/> and nothing written unless <c>UserModeExceptionRules.IsEligible</c> holds for
/// those facts; <see cref="ConsentWriteOutcome.NotFound"/> when the row no longer carries the block the facts are about.
/// It never clears the block, never enables hooking and never stamps consent: turning hooking on is FR-2.1's own
/// dialog, afterwards.
/// </remarks>
ValueTask<ConsentWriteOutcome> GrantAntiCheatExceptionAsync(AntiCheatExceptionGrantRequest grant, CancellationToken ct = default);
/// <summary>
/// D33: end a game's user-mode exception, for <paramref name="reason"/> (<c>UserModeExceptionLapse</c>), and turn its
/// hooking off while the block stands. The consent stamp is preserved, as a block preserves it; the family, the
/// disclosure and the executable the grant was made on stay on the row as history.
/// </summary>
/// <remarks><see cref="ConsentWriteOutcome.NotFound"/> when there was no exception in force.</remarks>
ValueTask<ConsentWriteOutcome> RevokeAntiCheatExceptionAsync(string normalisedExePath, string reason, CancellationToken ct = default);
}
@@ -39,6 +39,7 @@ public sealed class AgentCommandHandler
private readonly Func<CancellationToken, ValueTask<SweepRetentionAck>>? _sweepRetention;
private readonly ExecutableRelocator? _relocator;
private readonly IExecutableArchitectureSource? _architecture;
private readonly AntiCheatExceptionCommands? _exceptions;
/// <summary>
/// <c>Refused.reason</c> for an executable that cannot run as x64 (beta.8); <c>signal</c> carries its
@@ -46,6 +47,15 @@ public sealed class AgentCommandHandler
/// </summary>
public const string NotX64Reason = "ExecutableNotX64";
/// <summary>
/// D33: <c>Refused.reason</c> for an exception asked over a block that is not a module, file or folder finding of one
/// family — a title list, or a block written before 2026-09-25 that cannot be read back.
/// </summary>
public const string BlockNotExceptionableReason = "BlockNotExceptionable";
/// <summary>D33: <c>Refused.reason</c> for an exception asked with fewer successful hooked sessions than the owner's threshold; <c>signal</c> carries the count.</summary>
public const string TooFewSessionsReason = "TooFewSessions";
/// <summary>
/// <c>disclosureVersion</c> is the version of FR-2.1's reviewed disclosure this Agent carries
/// (<c>Shared.Safety.SafetyDisclosure.Version</c> under <c>--serve</c>); while it is null no <c>SetHookEnabled true</c>
@@ -55,8 +65,11 @@ public sealed class AgentCommandHandler
CaptureOrchestrator orchestrator, CapturePause pause, IAgentLifetime lifetime, Func<CancellationToken, ValueTask<string>> updateRules,
string? disclosureVersion = null, TimeProvider? clock = null, VkLayerReconciler? layer = null,
Func<CancellationToken, ValueTask<SweepRetentionAck>>? sweepRetention = null, ExecutableRelocator? relocator = null,
IExecutableArchitectureSource? architecture = null)
IExecutableArchitectureSource? architecture = null, AntiCheatExceptionCommands? exceptions = null)
{
// D33: the user-mode exception's collaborators — its option, its evidence, its disclosure version. Absent, no
// exception applies to SetHookEnabled and SetAntiCheatException is not answered (UnknownType).
_exceptions = exceptions;
// beta.8: an executable that cannot run as x64 is refused before anything is scanned or stamped; null skips the
// question (the guard's TargetIsWow64 at a session's start stays the check either way).
_architecture = architecture;
@@ -97,6 +110,7 @@ public sealed class AgentCommandHandler
IpcMessageType.StopSession => Stop(request),
IpcMessageType.UpdateRules => IpcCodec.Encode(IpcMessageType.UpdateRulesAck, request.Id, new UpdateRulesAck(await _updateRules(ct).ConfigureAwait(false))),
IpcMessageType.Shutdown => Shutdown(request),
IpcMessageType.SetAntiCheatException when _exceptions is not null => await SetAntiCheatExceptionAsync(request, _exceptions, ct).ConfigureAwait(false),
IpcMessageType.SweepRetention when _sweepRetention is not null =>
IpcCodec.Encode(IpcMessageType.SweepRetentionAck, request.Id, await _sweepRetention(ct).ConfigureAwait(false)),
_ => null,
@@ -196,20 +210,134 @@ public sealed class AgentCommandHandler
}
// The EXECUTABLE, not its folder (2026-09-25): the guard resolves the install root and runs check 3 on the
// name and the store identity as well as check 4 on the tree.
AntiCheatVerdict verdict = await _guard.PreScanGameAsync(path, ct).ConfigureAwait(false);
if (!verdict.IsAllowed)
// name and the store identity as well as check 4 on the tree. D33: a blocked game whose user-mode exception is in
// force for these bytes names the exception's family, and the guard decides whether to honour it.
string? tolerated = await CoveredFamilyAsync(path, fingerprint.Value, ct).ConfigureAwait(false);
AntiCheatVerdict verdict = await _guard.PreScanGameAsync(path, tolerated, ct).ConfigureAwait(false);
return verdict.IsAllowed
? await StampAsync(request, game, fingerprint.Value, payload.DisclosureVersion, verdict.RanUnderException ? "exception" : "clean", ct)
.ConfigureAwait(false)
: await RefuseEnableAsync(request, game, fingerprint.Value, verdict, tolerated, ct).ConfigureAwait(false);
}
/// <summary>
/// A refusal, or a scan that reached no answer: the store records which (a default verdict is "could not verify", never
/// a block), and both are answered as a refusal to enable. A finding about the game under its user-mode exception also
/// ends the exception (D33).
/// </summary>
private async ValueTask<byte[]> RefuseEnableAsync(IpcEnvelope request, GameRow game, ExecutableFingerprint fingerprint,
AntiCheatVerdict verdict, string? tolerated, CancellationToken ct)
{
await _consent.RecordGuardBlockAsync(fingerprint, verdict, ct).ConfigureAwait(false);
if (tolerated is not null && verdict.IsFindingAboutTheGame)
{
// A refusal, or a scan that reached no answer: the store records which (a default verdict is
// "could not verify", never a block), and both are answered as a refusal to enable.
await _consent.RecordGuardBlockAsync(fingerprint.Value, verdict, ct).ConfigureAwait(false);
await ReconcileLayerAsync(ct).ConfigureAwait(false);
string reason = verdict.Reason == AntiCheatRefusalReason.Allow ? "PreScanCouldNotVerify" : verdict.Reason.ToString();
return IpcCodec.Encode(IpcMessageType.Refused, request.Id,
new RefusedAck(game.Id, reason, NullIfEmpty(verdict.Family), NullIfEmpty(verdict.Signal)));
await _consent.RevokeAntiCheatExceptionAsync(fingerprint.ExePath, UserModeExceptionLapse.NewFinding, ct).ConfigureAwait(false);
}
return await StampAsync(request, game, fingerprint.Value, payload.DisclosureVersion, "clean", ct).ConfigureAwait(false);
await ReconcileLayerAsync(ct).ConfigureAwait(false);
string reason = verdict.Reason == AntiCheatRefusalReason.Allow ? "PreScanCouldNotVerify" : verdict.Reason.ToString();
return IpcCodec.Encode(IpcMessageType.Refused, request.Id,
new RefusedAck(game.Id, reason, NullIfEmpty(verdict.Family), NullIfEmpty(verdict.Signal)));
}
/// <summary>
/// D33: the family the game's user-mode exception covers for <paramref name="observed"/> right now — the option on, a
/// grant on the row made on these bytes, the block naming that family — or null (<see cref="UserModeExceptionRules.CoveredFamily"/>).
/// </summary>
private async ValueTask<string?> CoveredFamilyAsync(string path, ExecutableFingerprint observed, CancellationToken ct)
{
if (_exceptions is null || !await _exceptions.Switch.IsOnAsync(ct).ConfigureAwait(false))
{
return null;
}
GameConsentRecord record = await _consent.FindAsync(path, ct).ConfigureAwait(false);
return UserModeExceptionRules.CoveredFamily(record, observed, optionOn: true);
}
/// <summary>
/// D33 (owner decision 2026-09-26): grant or withdraw a game's user-mode exception. A withdrawal is the user's and needs
/// nothing. A grant needs the client's disclosure version to be this Agent's and the option on, then the facts the
/// Agent gathers itself (<see cref="GrantExceptionAsync"/>). Granting never turns hooking on: that is FR-2.1's dialog,
/// afterwards, through <c>SetHookEnabled</c>.
/// </summary>
private async ValueTask<byte[]> SetAntiCheatExceptionAsync(IpcEnvelope request, AntiCheatExceptionCommands exceptions, CancellationToken ct)
{
SetAntiCheatExceptionRequest? payload = IpcCodec.Payload<SetAntiCheatExceptionRequest>(request);
if (payload is null)
{
return Malformed(request, "SetAntiCheatException carries no payload");
}
GameRow? game = await FindGameAsync(payload.GameId, ct).ConfigureAwait(false);
if (game is null)
{
return Error(request, IpcErrorCode.UnknownGame, $"no games row has id {payload.GameId}");
}
if (!payload.Enabled)
{
ConsentWriteOutcome withdrawn = await _consent.RevokeAntiCheatExceptionAsync(game.Fingerprint.ExePath, UserModeExceptionLapse.Withdrawn, ct)
.ConfigureAwait(false);
await ReconcileLayerAsync(ct).ConfigureAwait(false);
return IpcCodec.Encode(IpcMessageType.AntiCheatExceptionAck, request.Id,
new AntiCheatExceptionAck(game.Id, Granted: false, withdrawn.ToString(), game.AcException.Family));
}
if (!string.Equals(payload.DisclosureVersion, exceptions.DisclosureVersion, StringComparison.Ordinal))
{
return Error(request, IpcErrorCode.DisclosureVersionMismatch,
$"the client showed exception disclosure '{payload.DisclosureVersion ?? "(none)"}' and this Agent grants against '{exceptions.DisclosureVersion}': nothing was granted — restart both");
}
return await exceptions.Switch.IsOnAsync(ct).ConfigureAwait(false)
? await GrantExceptionAsync(request, game, exceptions, ct).ConfigureAwait(false)
: Error(request, IpcErrorCode.ExceptionsOff, "the user-mode exception option is off, so nothing can be granted");
}
/// <summary>
/// D33: the facts a grant rests on, gathered here and now — the block on the row, a tolerant pre-scan of the executable on
/// disk naming the block's family, and the successful Tier-1 sessions — each refusal said as what it is; the store then
/// writes the grant only when they make the game eligible, and only while the row still carries that block.
/// </summary>
private async ValueTask<byte[]> GrantExceptionAsync(IpcEnvelope request, GameRow game, AntiCheatExceptionCommands exceptions, CancellationToken ct)
{
string path = game.Fingerprint.ExePath;
if (StoredBlock.Parse(game.HookBlockedReason) is not { IsExceptionable: true } block)
{
return IpcCodec.Encode(IpcMessageType.Refused, request.Id, new RefusedAck(game.Id, BlockNotExceptionableReason, Family: null, Signal: null));
}
if (_identity.Read(path) is not { } fingerprint)
{
return Error(request, IpcErrorCode.ExecutableUnreadable, $"{path} could not be read, so nothing can be scanned or granted");
}
AntiCheatVerdict verdict = await _guard.PreScanGameAsync(path, block.Family, ct).ConfigureAwait(false);
if (!verdict.RanUnderException || !string.Equals(verdict.Family, block.Family, StringComparison.Ordinal))
{
string reason = verdict.IsAllowed ? BlockNotExceptionableReason : verdict.Reason.ToString();
return IpcCodec.Encode(IpcMessageType.Refused, request.Id, new RefusedAck(game.Id, reason, NullIfEmpty(verdict.Family), NullIfEmpty(verdict.Signal)));
}
int sessions = await exceptions.Sessions.CountSuccessfulHookedAsync(game.Id, ct).ConfigureAwait(false);
if (sessions < UserModeExceptionRules.RequiredSessions)
{
return IpcCodec.Encode(IpcMessageType.Refused, request.Id, new RefusedAck(game.Id, TooFewSessionsReason, block.Family,
sessions.ToString(System.Globalization.CultureInfo.InvariantCulture)));
}
ConsentWriteOutcome outcome = await _consent.GrantAntiCheatExceptionAsync(new AntiCheatExceptionGrantRequest
{
Fingerprint = fingerprint,
Block = game.HookBlockedReason!,
Verdict = verdict,
Sessions = sessions,
DisclosureVersion = exceptions.DisclosureVersion,
GrantedAt = _clock.GetUtcNow(),
}, ct).ConfigureAwait(false);
return IpcCodec.Encode(IpcMessageType.AntiCheatExceptionAck, request.Id,
new AntiCheatExceptionAck(game.Id, Granted: outcome == ConsentWriteOutcome.Written, outcome.ToString(), block.Family));
}
/// <summary>
@@ -11,6 +11,7 @@ namespace FrameLedger.Application.Ipc;
/// <param name="VulkanLayerRegistered">Whether the HKCU implicit-layer registration named our manifest at this process's start (P3 PR-8b; a launch never needs it).</param>
/// <param name="CpuTempAvailable">False until the Agent composes a CPU sensor (LHM's CPU half is off unelevated).</param>
/// <param name="DisclosureVersion">The FR-2.1 disclosure this Agent stamps against (<c>Shared.Safety.SafetyDisclosure.Version</c> under <c>--serve</c>; null on a composition that carries none) — D14, P3 PR-4.</param>
/// <param name="ExceptionDisclosureVersion">D33: the user-mode exception's disclosure this Agent grants against (<c>Shared.Safety.AntiCheatExceptionDisclosure.Version</c> under <c>--serve</c>; null where none is carried).</param>
public sealed record AgentIdentity(
string AgentVersion,
int Pid,
@@ -18,4 +19,5 @@ public sealed record AgentIdentity(
string? OverlayBuildId,
bool VulkanLayerRegistered,
bool CpuTempAvailable,
string? DisclosureVersion = null);
string? DisclosureVersion = null,
string? ExceptionDisclosureVersion = null);
@@ -68,7 +68,8 @@ public sealed class AgentRequestHandler : IIpcRequestHandler
_identity.VulkanLayerRegistered,
Descriptor(),
_identity.CpuTempAvailable,
_identity.DisclosureVersion));
_identity.DisclosureVersion,
_identity.ExceptionDisclosureVersion));
}
/// <summary>Null when the layers cannot be composed at all — an absent descriptor, never an invented one.</summary>
@@ -0,0 +1,14 @@
using FrameLedger.Application.Capture;
using FrameLedger.Application.Persistence;
namespace FrameLedger.Application.Ipc;
/// <summary>
/// D33 (owner decision 2026-09-26): what <see cref="AgentCommandHandler"/> needs to answer for a game's user-mode exception —
/// the option, the evidence, and the disclosure version this Agent grants against. One parameter rather than three, so a
/// composition either has the exception or does not.
/// </summary>
/// <param name="Switch"><c>hooking.usermode_ac_exceptions</c>, read on every command.</param>
/// <param name="Sessions">Where the successful Tier-1 sessions are counted.</param>
/// <param name="DisclosureVersion"><c>Shared.Safety.AntiCheatExceptionDisclosure.Version</c> under <c>--serve</c>.</param>
public sealed record AntiCheatExceptionCommands(IUserModeExceptionSwitch Switch, ISessionRepository Sessions, string DisclosureVersion);
@@ -0,0 +1,70 @@
using FrameLedger.Domain.Consent;
namespace FrameLedger.Application.Persistence;
/// <summary>
/// D33 (owner decision 2026-09-26): <c>games.ac_exception_*</c> as read (schema 0014) — the Agent's eligibility answer
/// about a blocked game, the user's grant of its user-mode exception, and how the last grant ended. Read-only here: every
/// write is the consent store's (<c>IGameConsentStore</c>) or a downgrade in <c>ChangeExecutableAsync</c>.
/// </summary>
public sealed record AntiCheatExceptionState
{
/// <summary>A row that was never looked at and never granted anything.</summary>
public static AntiCheatExceptionState None { get; } = new();
/// <summary>The sweep's answer: the game's exception may be granted now.</summary>
public bool Eligible { get; init; }
/// <summary>The guard's tolerant pre-scan behind <see cref="Eligible"/>, as <c>Reason|Family|Signal</c>; null when nothing was asked.</summary>
public string? Verdict { get; init; }
/// <summary>Successful Tier-1 sessions of the game when the sweep last counted.</summary>
public int Sessions { get; init; }
/// <summary>The rules version <see cref="Verdict"/> was reached under.</summary>
public string? CheckedRulesVersion { get; init; }
/// <summary>The executable's size when <see cref="Verdict"/> was reached.</summary>
public long? CheckedExeSizeBytes { get; init; }
/// <summary>The executable's mtime (unix ms) when <see cref="Verdict"/> was reached.</summary>
public long? CheckedExeMtimeMs { get; init; }
/// <summary>The block text <see cref="Verdict"/> was reached about.</summary>
public string? CheckedBlock { get; init; }
/// <summary>When the user granted the exception in force; null when none is.</summary>
public DateTimeOffset? GrantedAt { get; init; }
/// <summary>The family the grant covers — or covered, once it has ended.</summary>
public string? Family { get; init; }
/// <summary>The disclosure the grant was accepted under.</summary>
public string? DisclosureVersion { get; init; }
/// <summary>The size of the executable the grant was made on.</summary>
public long? ExeSizeBytes { get; init; }
/// <summary>The mtime (unix ms) of the executable the grant was made on.</summary>
public long? ExeMtimeMs { get; init; }
/// <summary>When the last grant ended.</summary>
public DateTimeOffset? LapsedAt { get; init; }
/// <summary>Why the last grant ended (<c>UserModeExceptionLapse</c>).</summary>
public string? LapsedReason { get; init; }
/// <summary>An exception is in force on the row (whether the option lets it apply is the capture path's question).</summary>
public bool IsGranted => GrantedAt is not null && !string.IsNullOrEmpty(Family);
/// <summary>Whether <see cref="Verdict"/> was reached about <paramref name="block"/>, under these rules, over these bytes.</summary>
public bool IsCheckedFor(ExecutableFingerprint onDisk, string rulesVersion, string block) =>
string.Equals(CheckedRulesVersion, rulesVersion, StringComparison.Ordinal)
&& string.Equals(CheckedBlock, block, StringComparison.Ordinal)
&& CheckedExeSizeBytes == onDisk.SizeBytes
&& CheckedExeMtimeMs == onDisk.MtimeUnixMs;
/// <summary>Whether the grant in force was made on <paramref name="onDisk"/>'s bytes.</summary>
public bool GrantCovers(ExecutableFingerprint onDisk) =>
IsGranted && ExeSizeBytes == onDisk.SizeBytes && ExeMtimeMs == onDisk.MtimeUnixMs;
}
@@ -113,6 +113,12 @@ public sealed record GameRow
/// <summary>The capability files the game ships, with their versions (schema 0011, <c>library_versions</c>); empty when none or never looked.</summary>
public IReadOnlyList<LibraryFile> Libraries { get; init; } = [];
/// <summary>
/// D33 (owner decision 2026-09-26, schema 0014): the user-mode anti-cheat exception's columns — the Agent's eligibility
/// answer, the user's grant, and how the last one ended. Meaningful only on a blocked row.
/// </summary>
public AntiCheatExceptionState AcException { get; init; } = AntiCheatExceptionState.None;
public bool InLibrary => RemovedAt is null;
/// <summary>
@@ -39,6 +39,14 @@ public interface ISessionRepository
/// <summary>Sessions that started at or after <paramref name="since"/> (the Dashboard's "this week").</summary>
ValueTask<long> CountSinceAsync(DateTimeOffset since, CancellationToken ct = default);
/// <summary>
/// D33 (owner decision 2026-09-26): the game's successful Tier-1 sessions — hooked, frames recorded, <c>exit_status =
/// normal</c> — the evidence a user-mode exception needs <c>UserModeExceptionRules.RequiredSessions</c> of. Since beta.8
/// <c>normal</c> includes End task's exit code 1 and a user's stop; a crashed, unhooked-for-safety, degraded or
/// interrupted session never counts.
/// </summary>
ValueTask<int> CountSuccessfulHookedAsync(long gameId, CancellationToken ct = default);
ValueTask<int> SweepRetentionAsync(long gameId, int keep, CancellationToken ct = default);
/// <summary>
@@ -37,6 +37,12 @@ public sealed record SessionRow
public string? CaptureNotes { get; init; }
/// <summary>
/// D33 (owner decision 2026-09-26, schema 0014): the anti-cheat family the game's user-mode exception let through while
/// this session was hooked, or null when it ran under none. A Tier-2 session never carries one: nothing was hooked.
/// </summary>
public string? AcExceptionFamily { get; init; }
public bool LateAttach { get; init; }
public string? TelemetrySource { get; init; }
@@ -34,6 +34,9 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
/// <summary>The Win32 error a launch failed with (<c>launch_error=</c>, beta.8).</summary>
public int? LaunchError { get; init; }
/// <summary>D33: the family the game's user-mode exception let through while the session was hooked (<c>ac-exception=</c>).</summary>
public string? AcExceptionFamily { get; init; }
public static CaptureNotes Parse(string? notes)
{
if (string.IsNullOrWhiteSpace(notes))
@@ -41,7 +44,7 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
return default;
}
string? end = null, reason = null, family = null, signal = null;
string? end = null, reason = null, family = null, signal = null, acException = null;
int? exitCode = null, launchError = null;
bool crashEvent = false;
foreach (string raw in notes.Split(';'))
@@ -67,9 +70,26 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
{
(reason, family, signal) = Guard(part[6..]);
}
else if (part.StartsWith(_acExceptionPrefix, StringComparison.Ordinal))
{
acException = Blank(part[_acExceptionPrefix.Length..]);
}
}
return new CaptureNotes(end, reason, family, signal) { ExitCode = exitCode, CrashEvent = crashEvent, LaunchError = launchError };
return new CaptureNotes(end, reason, family, signal)
{
ExitCode = exitCode,
CrashEvent = crashEvent,
LaunchError = launchError,
AcExceptionFamily = acException,
};
}
/// <summary>D33: the slot that says a hooked session ran under the game's user-mode exception, and for which family.</summary>
public static string AcExceptionSlot(string family)
{
ArgumentException.ThrowIfNullOrWhiteSpace(family);
return _acExceptionPrefix + Clean(family);
}
/// <summary>The guard slot as the recorder writes it (beta.8): three positions, a <c>;</c> never inside one.</summary>
@@ -107,6 +127,8 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
};
}
private const string _acExceptionPrefix = "ac-exception=";
private static string Clean(string? s) => string.IsNullOrEmpty(s) ? string.Empty : s.Replace(';', ',');
private static string? Blank(string s) => s.Length > 0 ? s : null;
@@ -22,4 +22,7 @@ public sealed record RecordedSession
/// <summary>Whether the event log named the executable in the crash window.</summary>
public required bool CrashEventFound { get; init; }
/// <summary>D33: why this session ended the game's user-mode exception (<c>UserModeExceptionLapse</c>), or null when it did not.</summary>
public string? ExceptionLapse { get; init; }
}
@@ -43,12 +43,16 @@ public sealed class SessionRecorder : ISessionRecorder
private readonly IRecorderPolicy? _policy;
private readonly ISessionObserver? _observer;
private readonly IDriverProfileSource? _profiles;
private readonly UserModeExceptionLapsePolicy? _exceptionLapse;
public SessionRecorder(ICaptureSessionFactory sessions, IGameRepository games, IHardwareSnapshotRepository snapshots,
IHardwareSnapshotSource hardware, IPartialSessionStore partials, SessionFinalizer finalizer, ICrashEventSource crashes,
Func<RecorderOptions, ITelemetryPoller?> pollers, TimeProvider clock, RecorderOptions? options = null, ISessionObserver? observer = null,
IRecorderPolicy? policy = null, IDriverProfileSource? profiles = null)
IRecorderPolicy? policy = null, IDriverProfileSource? profiles = null, UserModeExceptionLapsePolicy? exceptionLapse = null)
{
// D33: ends a game's user-mode exception when a session under it ends badly; null in every recorder that has no
// consent store to write to (the tests, the unshipped host), where no exception can be in force either.
_exceptionLapse = exceptionLapse;
// beta.8: the NVIDIA driver profile the game runs under, read beside each session; null in every recorder that has
// no NVIDIA bridge to ask (the tests, the unshipped host).
_profiles = profiles;
@@ -212,6 +216,12 @@ public sealed class SessionRecorder : ISessionRecorder
crash = await _crashPolicy.ApplyAsync(ownerId, exit, outcome.ExitCode, run.AttachedAt, endedAt, ct).ConfigureAwait(false);
}
// D33: a session under the game's user-mode exception that ended badly ends the exception — after the row is
// stored, so the session that ended it is on the page the exception is gone from.
string? lapsed = _exceptionLapse is null
? null
: await _exceptionLapse.ApplyAsync(request.NormalisedExePath, outcome, exit, ct).ConfigureAwait(false);
return new RecordedSession
{
SessionGuid = header.SessionGuid,
@@ -221,6 +231,7 @@ public sealed class SessionRecorder : ISessionRecorder
Finalize = saved,
CrashPolicy = crash,
CrashEventFound = crashEvent,
ExceptionLapse = lapsed,
};
}
@@ -242,6 +253,13 @@ public sealed class SessionRecorder : ISessionRecorder
}
}
// A hooked session under the game's user-mode exception says so, and names the family (D33): the column is the
// App's, the notes travel into every bug bundle.
if (hooked && o.ExceptionFamily is { Length: > 0 } excepted)
{
notes += "; " + CaptureNotes.AcExceptionSlot(excepted);
}
// The session that turned the game's hooking off says so in its notes (2026-09-22): the row's block names
// the finding, and the notes travel into every bug bundle.
if (o.HookingTurnedOff)
@@ -269,6 +287,7 @@ public sealed class SessionRecorder : ISessionRecorder
DrainTicks = hooked ? o.DrainTicks : null,
ForegroundTicks = hooked ? o.ForegroundTicks : null,
GuardTicksPublished = hooked ? o.GuardTicksPublished : null,
AcExceptionFamily = hooked ? o.ExceptionFamily : null,
};
}
@@ -0,0 +1,77 @@
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Consent;
using FrameLedger.Domain.Sessions;
using FrameLedger.Shared;
namespace FrameLedger.Application.Recording;
/// <summary>
/// D33 (owner decision 2026-09-26): what a session under a game's user-mode exception does to the exception when it ends
/// badly (<c>19_SAFETY</c> §The user-mode exception, What ends it). A finding about the game at its start or at the 30 s
/// re-scan, a safety unhook, the Overlay's own stop on another anti-cheat's module, and a crash while hooked each end it —
/// the evidence the exception rests on said "this game is safe to measure", and each of those says otherwise.
/// </summary>
/// <remarks>
/// <para>
/// <b>It only ever ends an exception.</b> Nothing here grants one or clears a block; the end turns the game's hooking off
/// while its block stands and keeps the consent stamp, as a block keeps it. The user may grant it again once the sweep
/// finds the game eligible again, through the disclosure.
/// </para>
/// <para>
/// A session that ran under no exception is left alone, and so is an ordinary end under one — the game exited, the user
/// stopped it, End task (beta.8's <c>normal</c>), a refusal that found nothing about the game.
/// </para>
/// </remarks>
public sealed class UserModeExceptionLapsePolicy
{
private readonly IGameConsentStore _consent;
public UserModeExceptionLapsePolicy(IGameConsentStore consent) =>
_consent = consent ?? throw new ArgumentNullException(nameof(consent));
/// <summary>Why <paramref name="outcome"/> ends the exception it ran under (<see cref="UserModeExceptionLapse"/>), or null.</summary>
public static string? LapseOf(CaptureOutcome outcome, ExitStatus exit)
{
ArgumentNullException.ThrowIfNull(outcome);
if (outcome.ExceptionFamily is null)
{
return null;
}
if (outcome.HookingTurnedOff)
{
return UserModeExceptionLapse.NewFinding;
}
if (outcome.Reason == SessionEndReason.SafetyUnhook)
{
return UserModeExceptionLapse.SafetyUnhook;
}
if (outcome.Reason == SessionEndReason.WriterStoppedBlocklisted)
{
return UserModeExceptionLapse.OverlayStopped;
}
// A crash counts only while something of ours was in the process.
return outcome.AttachRefusal == ShmAttachRefusal.Ok && exit == ExitStatus.Crashed
? UserModeExceptionLapse.SessionCrashed
: null;
}
/// <summary>End the exception when <see cref="LapseOf"/> says so; the reason, when it was ended.</summary>
public async ValueTask<string?> ApplyAsync(string normalisedExePath, CaptureOutcome outcome, ExitStatus exit, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(normalisedExePath);
string? lapse = LapseOf(outcome, exit);
if (lapse is null)
{
return null;
}
return await _consent.RevokeAntiCheatExceptionAsync(normalisedExePath, lapse, ct).ConfigureAwait(false) == ConsentWriteOutcome.Written
? lapse
: null;
}
}
@@ -81,6 +81,19 @@ public static class SettingsRegistry
AgentReads = true,
};
/// <summary>
/// D33 (owner decision 2026-09-26): whether a game's user-mode anti-cheat exception may apply at all. Off by default;
/// on, the user still grants each eligible game through its disclosure, and off suspends every grant without deleting
/// any (<c>19_SAFETY</c> §The user-mode exception). Exactly "1" is on.
/// </summary>
public static readonly SettingDefinition HookingUserModeExceptions = new()
{
Key = "hooking.usermode_ac_exceptions",
Kind = SettingKind.Boolean,
Default = "0",
AgentReads = true,
};
/// <summary>FR-3.6: sessions shorter than this are discarded. Seconds.</summary>
public static readonly SettingDefinition CaptureMinSessionSeconds = new()
{
@@ -151,7 +164,7 @@ public static class SettingsRegistry
public static IReadOnlyList<SettingDefinition> All { get; } =
[
UiLanguage, UiTheme, UiStartWithWindows, UiMinimizeToTray, UiHideAntiCheatHooking, UiFpsDecimals,
CaptureBackground, HookingKillSwitch, CaptureMinSessionSeconds, TelemetryIntervalMs, RetentionRawSessionsPerGame,
CaptureBackground, HookingKillSwitch, HookingUserModeExceptions, CaptureMinSessionSeconds, TelemetryIntervalMs, RetentionRawSessionsPerGame,
UpdateChannel, UpdateAutoCheck, PrivacyOnlineMetadata, LogDebug,
];
@@ -207,6 +207,19 @@ public enum AntiCheatRefusalReason
/// </summary>
KillSwitchEngaged = 27,
// Value 28 was AllowedUnderUserBypass for one day (2026-09-21) and was withdrawn with the bypass on 2026-09-22. It
// was the last value, so nothing is renumbered; the native enum dropped it in the same change (GuardMirrorTests).
// Value 28 was AllowedUnderUserBypass for one day (2026-09-21) and was withdrawn with the bypass on 2026-09-22.
/// <summary>
/// D33 (owner decision 2026-09-26): every check ran and passed, and the only findings belonged to the ONE anti-cheat
/// family the game's user-mode exception names — a family whose whole footprint, floor and file, is user-mode, which
/// the native guard decides itself. <see cref="AntiCheatVerdict.Family"/> and <see cref="AntiCheatVerdict.Signal"/>
/// carry what was let through, so the session it starts is marked with it.
/// </summary>
/// <remarks>
/// An allow — the Overlay is in the target — and never the withdrawn bypass that once held this value: nothing
/// here injected past a refusal. A driver or service on the machine, a title list, a <c>.sys</c> in the tree, the
/// fuzzy tier, a scan that could not finish and any other family all refuse under an exception exactly as without
/// one (<c>19_SAFETY</c> §The user-mode exception).
/// </remarks>
AllowedUnderUserModeException = 28,
}
@@ -45,10 +45,17 @@ public readonly record struct AntiCheatVerdict
public string Signal { get; }
/// <summary>
/// True only when a real evaluation happened AND every check passed.
/// A default-constructed verdict is never allowed.
/// True only when a real evaluation happened AND every check passed — plainly, or under the game's user-mode
/// exception (D33, <see cref="RanUnderException"/>). A default-constructed verdict is never allowed.
/// </summary>
public bool IsAllowed => _evaluated && Reason == AntiCheatRefusalReason.Allow;
public bool IsAllowed => _evaluated
&& Reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException;
/// <summary>
/// D33: allowed because the only findings were the excepted family's; <see cref="Family"/> and <see cref="Signal"/>
/// say what was let through. The session is marked with them.
/// </summary>
public bool RanUnderException => _evaluated && Reason == AntiCheatRefusalReason.AllowedUnderUserModeException;
/// <summary>
/// A refusal. The default-constructed value is deliberately a refusal too:
@@ -69,14 +76,21 @@ public readonly record struct AntiCheatVerdict
or AntiCheatRefusalReason.AntiCheatFile;
public static AntiCheatVerdict Refused(AntiCheatRefusalReason reason, string family, string signal) =>
reason == AntiCheatRefusalReason.Allow
? throw new ArgumentOutOfRangeException(nameof(reason), "Refused() cannot carry Allow.")
reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException
? throw new ArgumentOutOfRangeException(nameof(reason), "Refused() cannot carry an allow.")
: new AntiCheatVerdict(reason, family, signal);
/// <summary>Every check passed.</summary>
public static AntiCheatVerdict Allowed() =>
new(AntiCheatRefusalReason.Allow, string.Empty, string.Empty);
/// <summary>D33: every check passed, and the only findings were the excepted family's — this one, through this signal.</summary>
public static AntiCheatVerdict AllowedUnderException(string family, string signal)
{
ArgumentException.ThrowIfNullOrWhiteSpace(family);
return new(AntiCheatRefusalReason.AllowedUnderUserModeException, family, signal ?? string.Empty);
}
/// <summary>
/// Build from the native ABI's reason code. An unrecognised code refuses:
/// it means the managed mirror has drifted from <c>fl::guard::Reason</c>,
@@ -0,0 +1,45 @@
namespace FrameLedger.Domain.AntiCheat;
/// <summary>
/// <c>games.hook_blocked_reason</c> read back: the guard reason that blocked the game, the anti-cheat family it named and
/// the signal it named it by — the Agent's <c>Reason|Family|Signal</c> (<c>SqliteGameConsentStore.BlockText</c>, since
/// 2026-09-25).
/// </summary>
/// <remarks>
/// A row written before 2026-09-25 says <c>"Reason: Family Signal"</c>, which cannot be split back apart (family names and
/// file names both carry spaces), and a reason this build does not know is not one it can reason about: both parse to
/// null, and D33's exception is never offered over a block nobody can read.
/// </remarks>
public readonly record struct StoredBlock(AntiCheatRefusalReason Reason, string Family, string Signal)
{
/// <summary>The stored text as the three slots, or null when it is not in that shape.</summary>
public static StoredBlock? Parse(string? stored)
{
if (string.IsNullOrEmpty(stored))
{
return null;
}
string[] parts = stored.Split('|', 3);
if (parts.Length != 3)
{
return null;
}
// Declared NAMES only, exactly cased: Enum.TryParse alone also accepts numbers and values nobody declared.
return Enum.TryParse(parts[0], ignoreCase: false, out AntiCheatRefusalReason reason)
&& Enum.IsDefined(reason)
&& string.Equals(reason.ToString(), parts[0], StringComparison.Ordinal)
? new StoredBlock(reason, parts[1], parts[2])
: null;
}
/// <summary>
/// D33 (owner decision 2026-09-26): a block of the kind a user-mode exception may be ASKED about — a module, a file or
/// a folder, naming one family. Never a title list (<c>BlockedExecutable</c>, <c>BlockedStoreId</c>: the notorious
/// titles are there by design). Whether the family is user-mode throughout, and whether nothing else is found, is the
/// guard's answer to a tolerant pre-scan, never this type's (<c>19_SAFETY</c> §The user-mode exception).
/// </summary>
public bool IsExceptionable => Family.Length > 0
&& Reason is AntiCheatRefusalReason.BlockedModule or AntiCheatRefusalReason.AntiCheatFile or AntiCheatRefusalReason.AntiCheatDirectory;
}
@@ -0,0 +1,43 @@
namespace FrameLedger.Domain.Consent;
/// <summary>
/// D33 (owner decision 2026-09-26): the user's grant of a user-mode anti-cheat exception for one game, as stored —
/// <c>games.ac_exception_*</c> (schema 0014). It names the family the user accepted the risk for, the disclosure they were
/// shown, and the executable (size and mtime) the grant was made on.
/// </summary>
/// <remarks>
/// <para>
/// <b>A grant is not a pass.</b> It is one input to <c>HookRequest.FromConsent</c>, which asks the guard to tolerate the
/// family only when the Settings option is on, the block on the row names that same family and the executable on disk is
/// the one the grant was made on; the guard then decides itself whether the family is user-mode and runs every check
/// (<c>19_SAFETY</c> §The user-mode exception).
/// </para>
/// <para>
/// It is only ever read out of a <see cref="GameConsentRecord"/>, which only a store can produce
/// (<see cref="GameConsentRecord.Stored"/> is internal) — the same reason a consent stamp cannot be minted.
/// </para>
/// </remarks>
public readonly record struct AntiCheatExceptionGrant
{
/// <summary>The anti-cheat family the exception covers, as the guard names it.</summary>
public required string Family { get; init; }
/// <summary>When the user granted it, UTC.</summary>
public required DateTimeOffset GrantedAt { get; init; }
/// <summary>Which wording of the exception's disclosure the user accepted (<c>AntiCheatExceptionDisclosure.Version</c>).</summary>
public required string DisclosureVersion { get; init; }
/// <summary>The size of the executable the grant was made on.</summary>
public required long ExeSizeBytes { get; init; }
/// <summary>The mtime (unix ms) of the executable the grant was made on.</summary>
public required long ExeMtimeUnixMs { get; init; }
/// <summary>
/// Whether <paramref name="observed"/> is the executable the grant was made on. Size and mtime only: a drive that changed
/// its letter moves the path and keeps the bytes, and a game update changes the bytes and ends the grant.
/// </summary>
public bool Covers(ExecutableFingerprint observed) =>
observed.SizeBytes == ExeSizeBytes && observed.MtimeUnixMs == ExeMtimeUnixMs;
}
@@ -60,7 +60,8 @@ public readonly record struct GameConsentRecord
string disclosureVersion,
string? blockedReason,
bool preScanUnverified,
DateTimeOffset updatedAt)
DateTimeOffset updatedAt,
AntiCheatExceptionGrant? exception)
{
Fingerprint = fingerprint;
HookEnabled = hookEnabled;
@@ -70,6 +71,7 @@ public readonly record struct GameConsentRecord
BlockedReason = blockedReason;
PreScanUnverified = preScanUnverified;
UpdatedAt = updatedAt;
Exception = exception;
_fromStore = true;
}
@@ -140,6 +142,14 @@ public readonly record struct GameConsentRecord
/// <summary>When this record was last written, UTC.</summary>
public DateTimeOffset UpdatedAt { get; }
/// <summary>
/// D33 (owner decision 2026-09-26): the user's grant of a user-mode anti-cheat exception for this game, when there is
/// one (<c>games.ac_exception_*</c>, schema 0014). It never clears <see cref="BlockedReason"/> — the exception is a
/// separate layer over the block, and only <c>HookRequest.FromConsent</c> reads it, together with the option, the block
/// and the executable on disk.
/// </summary>
public AntiCheatExceptionGrant? Exception { get; }
/// <summary>
/// True only for a record an <c>IGameConsentStore</c> actually returned.
/// </summary>
@@ -162,7 +172,8 @@ public readonly record struct GameConsentRecord
string? disclosureVersion,
string? blockedReason,
bool preScanUnverified,
DateTimeOffset updatedAt) =>
DateTimeOffset updatedAt,
AntiCheatExceptionGrant? exception = null) =>
new(fingerprint, hookEnabled, consentedAt, provenance, disclosureVersion ?? string.Empty, blockedReason,
preScanUnverified, updatedAt);
preScanUnverified, updatedAt, exception);
}
@@ -59,22 +59,28 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
// resolver were ever removed the fallback would still not probe the
// application directory. CA5393 rejects ApplicationDirectory for exactly
// the reason this comment exists.
// `toleratedFamilies` (D33): newline-separated family NAMES as NUL-terminated UTF-8 bytes (the byte[] shape
// FlGuardCheckRules takes, so no string crosses as ANSI), null for none — the one thing a caller may add, resolved
// and bounded by the guard itself (fl_guard_abi.h). Built by ToleranceBytes from the port's one family name.
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl)]
private static extern void FlGuardEvaluate(uint targetPid, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlGuardedInject(uint targetPid, string dllPath, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlGuardedInjectWhenReady(uint targetPid, string dllPath, uint timeoutMs,
private static extern void FlGuardEvaluate(uint targetPid, byte[]? toleratedFamilies,
out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlStaticPreScanGame(string exePath, out FlGuardResult result);
private static extern void FlGuardedInject(uint targetPid, string dllPath,
byte[]? toleratedFamilies, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlGuardedInjectWhenReady(uint targetPid, string dllPath, uint timeoutMs,
byte[]? toleratedFamilies, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlStaticPreScanGame(string exePath,
byte[]? toleratedFamilies, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl)]
@@ -106,50 +112,68 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
}
/// <inheritdoc />
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) =>
RunAsync(() =>
{
FlGuardEvaluate(checked((uint)targetPid), out FlGuardResult r);
FlGuardEvaluate(checked((uint)targetPid), ToleranceBytes(toleratedFamily), out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
/// <inheritdoc />
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath,
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily,
CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(payloadPath);
return RunAsync(() =>
{
FlGuardedInject(checked((uint)targetPid), payloadPath, out FlGuardResult r);
FlGuardedInject(checked((uint)targetPid), payloadPath, ToleranceBytes(toleratedFamily), out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
}
/// <inheritdoc />
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs,
CancellationToken ct = default)
string? toleratedFamily, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(payloadPath);
ArgumentOutOfRangeException.ThrowIfNegative(timeoutMs);
return RunAsync(() =>
{
FlGuardedInjectWhenReady(checked((uint)targetPid), payloadPath, checked((uint)timeoutMs),
out FlGuardResult r);
ToleranceBytes(toleratedFamily), out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
}
/// <inheritdoc />
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, CancellationToken ct = default)
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(executablePath);
return RunAsync(() =>
{
FlStaticPreScanGame(executablePath, out FlGuardResult r);
FlStaticPreScanGame(executablePath, ToleranceBytes(toleratedFamily), out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
}
/// <summary>
/// D33: the port's one family NAME as the ABI takes it — NUL-terminated UTF-8, or null for none. A name that could
/// not be one (a control character would split the ABI's newline-separated list into names nobody granted) crosses
/// as none: tolerating less is the safe direction, and the guard ignores an unknown or kernel-level name anyway.
/// </summary>
public static byte[]? ToleranceBytes(string? toleratedFamily)
{
if (string.IsNullOrWhiteSpace(toleratedFamily) || toleratedFamily.Any(char.IsControl))
{
return null;
}
byte[] name = System.Text.Encoding.UTF8.GetBytes(toleratedFamily);
byte[] terminated = new byte[name.Length + 1];
name.CopyTo(terminated, 0);
return terminated;
}
/// <summary>
/// The native name for a reason code. Used by the mirror test to prove the
/// two enumerations have not drifted; not for user-facing text, which comes
@@ -0,0 +1,162 @@
using System.Runtime.InteropServices;
using System.Security.Principal;
using FrameLedger.Application.Capture;
using FrameLedger.Infrastructure.Ipc;
using FrameLedger.Shared;
using Microsoft.Win32.SafeHandles;
namespace FrameLedger.Infrastructure.Capture;
/// <summary>
/// D33 (owner decision 2026-09-26): <see cref="IOverlayToleranceChannel"/> as the named file mapping <c>fl_tolerance.h</c>
/// describes — <c>Local\FrameLedger.Tolerate.&lt;pid&gt;</c>, one <see cref="FlTolerance"/> naming the family — created by
/// the Agent before it asks the guard to inject, and held until the session ends.
/// </summary>
/// <remarks>
/// <para>
/// <b>The security descriptor is stated, not defaulted</b> (<see cref="Sddl"/>): owned by the user, READ for the user and
/// for nobody else. An elevated Agent's default DACL grants Administrators and SYSTEM and not the user
/// (<see cref="PipeAccessControl"/> records the same trap), and the Overlay in an unelevated game could then not open it —
/// which would read as the exception failing the moment its family's module loaded. Nobody may open it to write: the
/// Agent writes once, through the handle that created it.
/// </para>
/// <para>
/// <b>A name that already exists is not ours.</b> <c>CreateFileMapping</c> hands back a handle to an existing object with
/// <c>ERROR_ALREADY_EXISTS</c>; that is refused (null), so the session asks the guard to tolerate nothing and the blocked
/// game is refused as before — whatever that other mapping says, nothing is injected under it.
/// </para>
/// </remarks>
public sealed class OverlayToleranceChannel : IOverlayToleranceChannel
{
private const uint _pageReadWrite = 0x04;
private const uint _fileMapWrite = 0x0002;
private const int _errorAlreadyExists = 183;
private static readonly IntPtr _invalidHandle = new(-1);
private readonly Action<string> _log;
public OverlayToleranceChannel(Action<string>? log = null) => _log = log ?? (static _ => { });
/// <summary>Owned by <paramref name="user"/>, a protected DACL granting <paramref name="user"/> read and nothing else.</summary>
public static string Sddl(SecurityIdentifier user)
{
ArgumentNullException.ThrowIfNull(user);
return $"O:{user.Value}D:P(A;;GR;;;{user.Value})";
}
/// <summary>The mapping's bytes for <paramref name="family"/>, or null for a name the Overlay could never match (not printable ASCII, or too long).</summary>
public static byte[]? Encode(string family)
{
if (string.IsNullOrWhiteSpace(family) || family.Length >= ToleranceLayout.NameLen || family.Any(static c => c is < ' ' or > '~'))
{
return null;
}
var tolerance = new FlTolerance { Magic = ToleranceLayout.Magic, Version = ToleranceLayout.Version, Count = 1 };
unsafe
{
System.Text.Encoding.ASCII.GetBytes(family, new Span<byte>(tolerance.Families, ToleranceLayout.NameLen - 1));
}
byte[] bytes = new byte[Marshal.SizeOf<FlTolerance>()];
MemoryMarshal.Write(bytes, in tolerance);
return bytes;
}
/// <inheritdoc />
public IDisposable? TryPublish(int pid, string family)
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(pid);
byte[]? bytes = Encode(family);
if (bytes is null)
{
_log($"tolerance: '{family}' cannot be named to the Overlay; no exception is in force for pid {pid}");
return null;
}
string name = ToleranceLayout.MappingName(pid);
byte[] descriptor = PipeAccessControl.DescriptorBytes(Sddl(PipeAccessControl.CurrentUser()));
SafeMemoryMappedFileHandle mapping = Create(name, descriptor, (uint)bytes.Length, out int error);
if (mapping.IsInvalid || error == _errorAlreadyExists)
{
mapping.Dispose();
_log($"tolerance: {name} could not be created (error {error}); no exception is in force for pid {pid}");
return null;
}
if (!Write(mapping, bytes))
{
mapping.Dispose();
_log($"tolerance: {name} could not be written (error {Marshal.GetLastPInvokeError()}); no exception is in force for pid {pid}");
return null;
}
_log($"tolerance: {name} names {family}");
return new Published(mapping);
}
private static unsafe SafeMemoryMappedFileHandle Create(string name, byte[] descriptor, uint size, out int error)
{
fixed (byte* sd = descriptor)
{
var attributes = new SecurityAttributes
{
Length = sizeof(SecurityAttributes),
SecurityDescriptor = (IntPtr)sd,
InheritHandle = 0,
};
SafeMemoryMappedFileHandle mapping = CreateFileMappingW(_invalidHandle, ref attributes, _pageReadWrite, 0, size, name);
error = Marshal.GetLastPInvokeError();
return mapping;
}
}
private static unsafe bool Write(SafeMemoryMappedFileHandle mapping, byte[] bytes)
{
IntPtr view = MapViewOfFile(mapping, _fileMapWrite, 0, 0, (nuint)bytes.Length);
if (view == IntPtr.Zero)
{
return false;
}
try
{
bytes.CopyTo(new Span<byte>((void*)view, bytes.Length));
return true;
}
finally
{
_ = UnmapViewOfFile(view);
}
}
[StructLayout(LayoutKind.Sequential)]
private struct SecurityAttributes
{
public int Length;
public IntPtr SecurityDescriptor;
public int InheritHandle;
}
/// <summary>The published mapping, held for the session; disposing it more than once is harmless.</summary>
private sealed class Published(SafeMemoryMappedFileHandle mapping) : IDisposable
{
public void Dispose() => mapping.Dispose();
}
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeMemoryMappedFileHandle CreateFileMappingW(IntPtr file, ref SecurityAttributes attributes, uint protect,
uint maximumSizeHigh, uint maximumSizeLow, string name);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport("kernel32.dll", SetLastError = true)]
private static extern IntPtr MapViewOfFile(SafeMemoryMappedFileHandle mapping, uint desiredAccess, uint offsetHigh, uint offsetLow,
nuint bytesToMap);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport("kernel32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool UnmapViewOfFile(IntPtr view);
}
@@ -0,0 +1,37 @@
-- 0014 (2026-09-26): the user-mode anti-cheat exception (beta.9, owner decision D33; 19_SAFETY §The user-mode exception).
--
-- A game whose only anti-cheat findings are one user-mode family, that ships no kernel driver, is on no title list and
-- has been measured hooked at least twice may be excepted by the user, per game, while Settings' option is on. The
-- block itself is never cleared: these columns are a separate layer over hook_blocked_reason, in three groups.
--
-- ELIGIBILITY, the Agent's sweep's answer about a blocked row: whether an exception may be granted, the guard's
-- tolerant pre-scan it rests on (Reason|Family|Signal; NULL = nothing was asked, the block is not a module, file or
-- folder finding), the successful Tier-1 sessions counted, and the key it was reached under — the rules version, the
-- executable's size and mtime, and the block text — so a pass re-scans only when one of them changes.
--
-- THE GRANT, the user's, after the exception's disclosure: when (NULL = no exception in force), for which family, under
-- which disclosure, and for which bytes of the executable (a game update ends it).
--
-- THE END of the last grant: when and why (UserModeExceptionLapse's words). The grant's family, disclosure and bytes
-- stay beside it as history.
--
-- sessions.ac_exception_family names the family a HOOKED session ran under the exception with; NULL for every other
-- session and for every row written before.
--
-- Written by the Agent only (06_DATA_MODEL §Writer ownership: hook-state columns are the Agent's); ADD COLUMN only.
ALTER TABLE games ADD COLUMN ac_exception_eligible INTEGER NOT NULL DEFAULT 0;
ALTER TABLE games ADD COLUMN ac_exception_verdict TEXT;
ALTER TABLE games ADD COLUMN ac_exception_sessions INTEGER NOT NULL DEFAULT 0;
ALTER TABLE games ADD COLUMN ac_exception_checked_rules_version TEXT;
ALTER TABLE games ADD COLUMN ac_exception_checked_exe_size_bytes INTEGER;
ALTER TABLE games ADD COLUMN ac_exception_checked_exe_mtime_ms INTEGER;
ALTER TABLE games ADD COLUMN ac_exception_checked_block TEXT;
ALTER TABLE games ADD COLUMN ac_exception_at INTEGER;
ALTER TABLE games ADD COLUMN ac_exception_family TEXT;
ALTER TABLE games ADD COLUMN ac_exception_disclosure_version TEXT;
ALTER TABLE games ADD COLUMN ac_exception_exe_size_bytes INTEGER;
ALTER TABLE games ADD COLUMN ac_exception_exe_mtime_ms INTEGER;
ALTER TABLE games ADD COLUMN ac_exception_lapsed_at INTEGER;
ALTER TABLE games ADD COLUMN ac_exception_lapsed_reason TEXT;
ALTER TABLE sessions ADD COLUMN ac_exception_family TEXT;
@@ -13,10 +13,10 @@ namespace FrameLedger.Infrastructure.Persistence;
internal static class SessionRowColumns
{
public const string Insert =
"INSERT INTO sessions (session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct) "
+ "VALUES (@session_guid, @game_id, @snapshot_id, @started_at, @ended_at, @duration_s, @qpc_epoch, @qpc_frequency, @capture_tier, @capture_mode, @capture_notes, @late_attach, @telemetry_source, @overlay_build_id, @exit_status, @drain_ticks, @foreground_ticks, @records_before_attach, @dxgi_presents_before_hook, @gap_count, @guard_ticks_published, @launch_wait_ms, @api, @present_mode, @swap_effect, @hdr_flag, @hdr_source, @sync_interval_mode, @upscaler, @upscaler_quality, @upscaler_sharpness, @upscaler_driver_reported, @render_w, @render_h, @output_w, @output_h, @upscale_ratio, @settings_changed_midsession, @fg_mode, @fg_source, @fg_factor, @fg_driver_reported, @fg_runtime_census, @fg_none_withheld_reason, @fg_refusal, @fg_refusal_detail, @fg_factor_scope, @fg_steady_share, @presented_fps, @presented_qualifier, @dxgi_unseen_total, @dxgi_present_samples, @displayed_counted_by, @sl_tag_census, @sl_interposer_version, @runtime_modules, @driver_profile, @executable_markers, @ngx_driver_words, @rt_flag, @rt_source, @pt_flag, @pt_source, @pt_confidence, @rr_flag, @rr_source, @rt_frame_pct, @rays_per_pixel, @rt_pso_count, @rt_tier, @hooks_installed_mask, @raster_pso_count, @frame_count, @app_frame_count, @displayed_frame_count, @dropped_frames, @native_fps, @displayed_fps, @median_fps, @p1_low_fps, @p01_low_fps, @displayed_p1_low_fps, @min_fps, @max_fps, @frametime_stddev_ms, @stutter_count, @stutter_time_pct, @pso_stutter_pct, @reflex_active, @latency_avg_us, @latency_p95_us, @dropped_records, @fault_count, @data_quality_warnings, @writer_status_at_end, @early_stop_family, @loader_signals, @vram_proc_avg_mb, @vram_proc_max_mb, @vram_budget_exceeded_pct, @vram_adapter_max_mb, @avg_cpu_temp, @max_cpu_temp, @avg_gpu_temp, @max_gpu_temp, @max_gpu_hotspot, @avg_gpu_load, @avg_cpu_load, @avg_ram_mb, @avg_gpu_power_w, @throttle_pct) RETURNING id";
"INSERT INTO sessions (session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, ac_exception_family, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct) "
+ "VALUES (@session_guid, @game_id, @snapshot_id, @started_at, @ended_at, @duration_s, @qpc_epoch, @qpc_frequency, @capture_tier, @capture_mode, @capture_notes, @ac_exception_family, @late_attach, @telemetry_source, @overlay_build_id, @exit_status, @drain_ticks, @foreground_ticks, @records_before_attach, @dxgi_presents_before_hook, @gap_count, @guard_ticks_published, @launch_wait_ms, @api, @present_mode, @swap_effect, @hdr_flag, @hdr_source, @sync_interval_mode, @upscaler, @upscaler_quality, @upscaler_sharpness, @upscaler_driver_reported, @render_w, @render_h, @output_w, @output_h, @upscale_ratio, @settings_changed_midsession, @fg_mode, @fg_source, @fg_factor, @fg_driver_reported, @fg_runtime_census, @fg_none_withheld_reason, @fg_refusal, @fg_refusal_detail, @fg_factor_scope, @fg_steady_share, @presented_fps, @presented_qualifier, @dxgi_unseen_total, @dxgi_present_samples, @displayed_counted_by, @sl_tag_census, @sl_interposer_version, @runtime_modules, @driver_profile, @executable_markers, @ngx_driver_words, @rt_flag, @rt_source, @pt_flag, @pt_source, @pt_confidence, @rr_flag, @rr_source, @rt_frame_pct, @rays_per_pixel, @rt_pso_count, @rt_tier, @hooks_installed_mask, @raster_pso_count, @frame_count, @app_frame_count, @displayed_frame_count, @dropped_frames, @native_fps, @displayed_fps, @median_fps, @p1_low_fps, @p01_low_fps, @displayed_p1_low_fps, @min_fps, @max_fps, @frametime_stddev_ms, @stutter_count, @stutter_time_pct, @pso_stutter_pct, @reflex_active, @latency_avg_us, @latency_p95_us, @dropped_records, @fault_count, @data_quality_warnings, @writer_status_at_end, @early_stop_family, @loader_signals, @vram_proc_avg_mb, @vram_proc_max_mb, @vram_budget_exceeded_pct, @vram_adapter_max_mb, @avg_cpu_temp, @max_cpu_temp, @avg_gpu_temp, @max_gpu_temp, @max_gpu_hotspot, @avg_gpu_load, @avg_cpu_load, @avg_ram_mb, @avg_gpu_power_w, @throttle_pct) RETURNING id";
public const string Select = "SELECT id, session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct FROM sessions";
public const string Select = "SELECT id, session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, ac_exception_family, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct FROM sessions";
public static Dictionary<string, object?> Parameters(SessionRow s)
{
@@ -44,6 +44,7 @@ internal static class SessionRowColumns
d["capture_tier"] = (long)s.Tier;
d["capture_mode"] = s.Mode == CaptureMode.Launch ? "launch" : "attach";
d["capture_notes"] = s.CaptureNotes;
d["ac_exception_family"] = s.AcExceptionFamily;
d["late_attach"] = s.LateAttach ? 1L : 0L;
d["telemetry_source"] = s.TelemetrySource;
d["overlay_build_id"] = s.OverlayBuildId;
@@ -172,6 +173,7 @@ internal static class SessionRowColumns
Tier = (CaptureTier)L(r, "capture_tier")!.Value,
Mode = string.Equals(S(r, "capture_mode"), "launch", StringComparison.Ordinal) ? CaptureMode.Launch : CaptureMode.Attach,
CaptureNotes = S(r, "capture_notes"),
AcExceptionFamily = S(r, "ac_exception_family"),
LateAttach = L(r, "late_attach") == 1,
TelemetrySource = S(r, "telemetry_source"),
OverlayBuildId = S(r, "overlay_build_id"),
@@ -1,5 +1,6 @@
using System.Data.Common;
using Dapper;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Consent;
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
@@ -34,7 +35,8 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
{
private const string _columns =
"exe_path, exe_size_bytes, exe_mtime_ms, hook_enabled, hook_consent_at, hook_consent_provenance, "
+ "hook_consent_disclosure_version, hook_blocked_reason, hook_prescan_state, updated_at";
+ "hook_consent_disclosure_version, hook_blocked_reason, hook_prescan_state, updated_at, "
+ "ac_exception_at, ac_exception_family, ac_exception_disclosure_version, ac_exception_exe_size_bytes, ac_exception_exe_mtime_ms";
private const string _selectOne = $"SELECT {_columns} FROM games WHERE exe_path = @path";
@@ -77,6 +79,27 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
+ "hook_prescan_exe_size_bytes = @size, hook_prescan_exe_mtime_ms = @mtime, updated_at = @at "
+ "WHERE exe_path = @path AND hook_blocked_reason IS NULL AND hook_prescan_state <> 'blocked'";
// D33 (schema 0014). The eligibility and the grant are each bound to the block they were reached about — the WHERE is
// the guarantee, so a block rewritten between the caller's read and this write leaves the row alone. Neither names
// hook_blocked_reason, hook_enabled or the consent columns in its SET list.
private const string _exceptionEligibility =
"UPDATE games SET ac_exception_eligible = @eligible, ac_exception_verdict = @verdict, ac_exception_sessions = @sessions, "
+ "ac_exception_checked_rules_version = @rules, ac_exception_checked_exe_size_bytes = @size, ac_exception_checked_exe_mtime_ms = @mtime, "
+ "ac_exception_checked_block = @block, updated_at = @at WHERE exe_path = @path AND hook_blocked_reason = @block";
private const string _exceptionGrant =
"UPDATE games SET ac_exception_at = @at, ac_exception_family = @family, ac_exception_disclosure_version = @disclosure, "
+ "ac_exception_exe_size_bytes = @size, ac_exception_exe_mtime_ms = @mtime, ac_exception_lapsed_at = NULL, ac_exception_lapsed_reason = NULL, "
+ "ac_exception_eligible = 1, ac_exception_verdict = @verdict, ac_exception_sessions = @sessions, updated_at = @at "
+ "WHERE exe_path = @path AND hook_blocked_reason = @block";
// The end of an exception keeps the consent stamp, as a block does, and turns hooking off while the block stands. The
// grant's family, disclosure and bytes stay as history; ac_exception_at going NULL is what ends it.
private const string _exceptionRevoke =
"UPDATE games SET ac_exception_at = NULL, ac_exception_lapsed_at = @at, ac_exception_lapsed_reason = @reason, "
+ "hook_enabled = CASE WHEN hook_blocked_reason IS NOT NULL THEN 0 ELSE hook_enabled END, updated_at = @at "
+ "WHERE exe_path = @path AND ac_exception_at IS NOT NULL";
private readonly LedgerDatabase _db;
public SqliteGameConsentStore(LedgerDatabase db) => _db = db ?? throw new ArgumentNullException(nameof(db));
@@ -173,8 +196,11 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
Row? existing = await ReadRowAsync(c, tx, fp.ExePath, token).ConfigureAwait(false);
// A FINGERPRINT THAT DOES NOT MATCH THE STORED ONE IS REFUSED when a BLOCK is at stake — never
// silently re-pointed at a different binary. An ordinary re-grant after a patch keeps working.
if (existing is not null && existing.BlockedReason is not null && !existing.Fingerprint.Matches(fp))
// silently re-pointed at a different binary. An ordinary re-grant after a patch keeps working, and
// so does one under a user-mode exception granted on exactly these bytes (D33): the user accepted the
// exception's disclosure for this file, and is now accepting FR-2.1's for it.
if (existing is not null && existing.BlockedReason is not null && !existing.Fingerprint.Matches(fp)
&& existing.Grant?.Covers(fp) != true)
{
return ConsentWriteOutcome.StaleFingerprint;
}
@@ -274,6 +300,99 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
}
}
/// <inheritdoc />
public async ValueTask<ConsentWriteOutcome> RecordExceptionEligibilityAsync(
ExecutableFingerprint scanned, string block, AntiCheatVerdict? verdict, int sessions, string rulesVersion, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(block);
ArgumentException.ThrowIfNullOrWhiteSpace(rulesVersion);
bool eligible = verdict is { } v && UserModeExceptionRules.IsEligible(StoredBlock.Parse(block), v, sessions);
try
{
return await _db.WriteAsync(async (c, tx, token) =>
{
var p = new
{
path = scanned.ExePath,
eligible = eligible ? 1 : 0,
verdict = verdict is { } answered ? BlockText(answered) : null,
sessions,
rules = rulesVersion,
size = scanned.SizeBytes,
mtime = scanned.MtimeUnixMs,
block,
at = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
};
int rows = await c.ExecuteAsync(new CommandDefinition(_exceptionEligibility, p, tx, cancellationToken: token)).ConfigureAwait(false);
return rows == 0 ? ConsentWriteOutcome.NotFound : ConsentWriteOutcome.Written;
}, ct).ConfigureAwait(false);
}
catch (SqliteException)
{
return ConsentWriteOutcome.Failed;
}
}
/// <inheritdoc />
public async ValueTask<ConsentWriteOutcome> GrantAntiCheatExceptionAsync(AntiCheatExceptionGrantRequest grant, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(grant);
ArgumentException.ThrowIfNullOrWhiteSpace(grant.DisclosureVersion, nameof(grant));
// THE STORE APPLIES THE RULE ITSELF: a grant over facts that do not make the game eligible is refused here, not
// only by the caller that gathered them.
StoredBlock? block = StoredBlock.Parse(grant.Block);
if (!UserModeExceptionRules.IsEligible(block, grant.Verdict, grant.Sessions))
{
return ConsentWriteOutcome.NotEligible;
}
try
{
return await _db.WriteAsync(async (c, tx, token) =>
{
var p = new
{
path = grant.Fingerprint.ExePath,
block = grant.Block,
family = block!.Value.Family,
disclosure = grant.DisclosureVersion,
size = grant.Fingerprint.SizeBytes,
mtime = grant.Fingerprint.MtimeUnixMs,
verdict = BlockText(grant.Verdict),
sessions = grant.Sessions,
at = grant.GrantedAt.ToUnixTimeMilliseconds(),
};
int rows = await c.ExecuteAsync(new CommandDefinition(_exceptionGrant, p, tx, cancellationToken: token)).ConfigureAwait(false);
return rows == 0 ? ConsentWriteOutcome.NotFound : ConsentWriteOutcome.Written;
}, ct).ConfigureAwait(false);
}
catch (SqliteException)
{
return ConsentWriteOutcome.Failed;
}
}
/// <inheritdoc />
public async ValueTask<ConsentWriteOutcome> RevokeAntiCheatExceptionAsync(string normalisedExePath, string reason, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(normalisedExePath);
ArgumentException.ThrowIfNullOrWhiteSpace(reason);
try
{
return await _db.WriteAsync(async (c, tx, token) =>
{
var p = new { path = normalisedExePath, reason, at = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() };
int rows = await c.ExecuteAsync(new CommandDefinition(_exceptionRevoke, p, tx, cancellationToken: token)).ConfigureAwait(false);
return rows == 0 ? ConsentWriteOutcome.NotFound : ConsentWriteOutcome.Written;
}, ct).ConfigureAwait(false);
}
catch (SqliteException)
{
return ConsentWriteOutcome.Failed;
}
}
private static Task<Row?> ReadRowAsync(SqliteConnection c, SqliteTransaction? tx, string path, CancellationToken ct) =>
SqliteReaders.ReadOneAsync(c, new CommandDefinition(_selectOne, new { path }, tx, cancellationToken: ct), Row.From);
@@ -286,7 +405,8 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
string DisclosureVersion,
string? BlockedReason,
string PreScanState,
long UpdatedAtMs)
long UpdatedAtMs,
AntiCheatExceptionGrant? Grant)
{
public static Row From(DbDataReader r) => new(
new ExecutableFingerprint
@@ -301,7 +421,21 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
r.GetString(6),
SqliteReaders.String(r, 7),
r.GetString(8),
r.GetInt64(9));
r.GetInt64(9),
ReadGrant(r));
/// <summary>D33: the grant in force (schema 0014, ordinals 10–14), or null when <c>ac_exception_at</c> is.</summary>
private static AntiCheatExceptionGrant? ReadGrant(DbDataReader r) =>
SqliteReaders.Int64(r, 10) is { } at && SqliteReaders.String(r, 11) is { Length: > 0 } family
? new AntiCheatExceptionGrant
{
GrantedAt = DateTimeOffset.FromUnixTimeMilliseconds(at),
Family = family,
DisclosureVersion = SqliteReaders.String(r, 12) ?? string.Empty,
ExeSizeBytes = SqliteReaders.Int64(r, 13) ?? -1,
ExeMtimeUnixMs = SqliteReaders.Int64(r, 14) ?? -1,
}
: null;
public GameConsentRecord ToRecord() => GameConsentRecord.Stored(
Fingerprint,
@@ -311,7 +445,8 @@ public sealed class SqliteGameConsentStore : IGameConsentStore
DisclosureVersion,
BlockedReason,
string.Equals(PreScanState, "unverified", StringComparison.Ordinal),
DateTimeOffset.FromUnixTimeMilliseconds(UpdatedAtMs));
DateTimeOffset.FromUnixTimeMilliseconds(UpdatedAtMs),
Grant);
}
/// <summary>
@@ -26,7 +26,11 @@ public sealed class SqliteGameRepository : IGameRepository
+ "rt_default, pt_default, rr_default, hook_consent_at, hook_prescan_state, removed_at, "
+ "detection_rules_version, detection_exe_size_bytes, detection_exe_mtime_ms, record_sessions, "
+ "hook_prescan_rules_version, hook_prescan_exe_size_bytes, hook_prescan_exe_mtime_ms, "
+ "exe_machine, exe_file_version, exe_product_version, library_versions";
+ "exe_machine, exe_file_version, exe_product_version, library_versions, "
+ "ac_exception_eligible, ac_exception_verdict, ac_exception_sessions, ac_exception_checked_rules_version, "
+ "ac_exception_checked_exe_size_bytes, ac_exception_checked_exe_mtime_ms, ac_exception_checked_block, ac_exception_at, "
+ "ac_exception_family, ac_exception_disclosure_version, ac_exception_exe_size_bytes, ac_exception_exe_mtime_ms, "
+ "ac_exception_lapsed_at, ac_exception_lapsed_reason";
private const string _selectByPath = $"SELECT {_columns} FROM games WHERE exe_path = @path";
@@ -46,11 +50,18 @@ public sealed class SqliteGameRepository : IGameRepository
// A downgrade by construction: the consent columns go to their "nothing happened" defaults, never to a grant, and
// hook_blocked_reason is not named (IGameRepository.ChangeExecutableAsync). NOT EXISTS is the UNIQUE index's answer
// as a false instead of a constraint exception. The pre-scan's key goes with its state (schema 0010), so the Agent's
// sweep scans the new executable on its next pass whatever its size and mtime happen to be.
// sweep scans the new executable on its next pass whatever its size and mtime happen to be. A user-mode exception
// (D33, schema 0014) ends with the consent it shared an executable with — its end recorded, its eligibility unknown
// until the sweep has looked at the new file. SQLite reads every SET expression from the row as it was, so the
// CASEs see the grant this statement clears.
private const string _changeExecutable =
"UPDATE games SET exe_path = @path, exe_size_bytes = @size, exe_mtime_ms = @mtime, hook_enabled = 0, hook_consent_at = NULL, "
+ "hook_consent_provenance = 'NotRecorded', hook_consent_disclosure_version = '', hook_prescan_state = 'not_run', "
+ "hook_prescan_rules_version = NULL, hook_prescan_exe_size_bytes = NULL, hook_prescan_exe_mtime_ms = NULL, "
+ "ac_exception_lapsed_reason = CASE WHEN ac_exception_at IS NOT NULL THEN 'ExecutableChanged' ELSE ac_exception_lapsed_reason END, "
+ "ac_exception_lapsed_at = CASE WHEN ac_exception_at IS NOT NULL THEN @at ELSE ac_exception_lapsed_at END, "
+ "ac_exception_at = NULL, ac_exception_eligible = 0, ac_exception_verdict = NULL, ac_exception_checked_rules_version = NULL, "
+ "ac_exception_checked_exe_size_bytes = NULL, ac_exception_checked_exe_mtime_ms = NULL, ac_exception_checked_block = NULL, "
+ "updated_at = @at "
+ "WHERE id = @id AND removed_at IS NULL AND NOT EXISTS (SELECT 1 FROM games other WHERE other.exe_path = @path AND other.id <> @id)";
@@ -351,6 +362,26 @@ public sealed class SqliteGameRepository : IGameRepository
ExeFileVersion = SqliteReaders.String(r, 36),
ExeProductVersion = SqliteReaders.String(r, 37),
Libraries = LibraryVersionsJson.Parse(SqliteReaders.String(r, 38)),
AcException = ReadException(r),
};
/// <summary>Schema 0014's columns, 39 onwards in <see cref="_columns"/>' order.</summary>
private static AntiCheatExceptionState ReadException(DbDataReader r) => new()
{
Eligible = r.GetInt64(39) != 0,
Verdict = SqliteReaders.String(r, 40),
Sessions = (int)r.GetInt64(41),
CheckedRulesVersion = SqliteReaders.String(r, 42),
CheckedExeSizeBytes = SqliteReaders.Int64(r, 43),
CheckedExeMtimeMs = SqliteReaders.Int64(r, 44),
CheckedBlock = SqliteReaders.String(r, 45),
GrantedAt = At(SqliteReaders.Int64(r, 46)),
Family = SqliteReaders.String(r, 47),
DisclosureVersion = SqliteReaders.String(r, 48),
ExeSizeBytes = SqliteReaders.Int64(r, 49),
ExeMtimeMs = SqliteReaders.Int64(r, 50),
LapsedAt = At(SqliteReaders.Int64(r, 51)),
LapsedReason = SqliteReaders.String(r, 52),
};
private static DateTimeOffset? At(long? unixMs) => unixMs is { } ms ? DateTimeOffset.FromUnixTimeMilliseconds(ms) : null;
@@ -165,6 +165,11 @@ public sealed class SqliteSessionRepository : ISessionRepository
_db.ReadAsync((c, token) => c.ExecuteScalarAsync<long>(new CommandDefinition(
"SELECT COUNT(*) FROM sessions WHERE started_at >= @since", new { since = since.ToUnixTimeMilliseconds() }, cancellationToken: token)), ct);
public ValueTask<int> CountSuccessfulHookedAsync(long gameId, CancellationToken ct = default) =>
_db.ReadAsync((c, token) => c.ExecuteScalarAsync<int>(new CommandDefinition(
"SELECT COUNT(*) FROM sessions WHERE game_id = @gameId AND capture_tier = 1 AND exit_status = 'normal' AND frame_count > 0",
new { gameId }, cancellationToken: token)), ct);
public ValueTask<IReadOnlyList<SegmentRow>> FindSegmentsAsync(long sessionId, CancellationToken ct = default) =>
_db.ReadAsync((c, token) => SqliteReaders.ReadAllAsync(
c, new CommandDefinition(_selectSegments, new { sessionId }, cancellationToken: token), ReadSegment), ct);
@@ -0,0 +1,25 @@
using FrameLedger.Application.Capture;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Settings;
namespace FrameLedger.Infrastructure.Settings;
/// <summary>
/// D33 (owner decision 2026-09-26): the user-mode exception option as one row in <c>settings</c> —
/// <c>hooking.usermode_ac_exceptions = 1</c> is on, anything else, including no row at all, is off. Read fresh on every
/// ask, like <see cref="SettingsKillSwitch"/>: the App flips the row, and the next session start and command take it.
/// </summary>
public sealed class SettingsUserModeExceptionSwitch : IUserModeExceptionSwitch
{
/// <summary>The one value that means on.</summary>
public const string OnValue = "1";
private readonly ISettingsStore _settings;
public SettingsUserModeExceptionSwitch(ISettingsStore settings) =>
_settings = settings ?? throw new ArgumentNullException(nameof(settings));
/// <inheritdoc />
public async ValueTask<bool> IsOnAsync(CancellationToken ct = default) =>
string.Equals(await _settings.GetAsync(SettingsRegistry.HookingUserModeExceptions.Key, ct).ConfigureAwait(false), OnValue, StringComparison.Ordinal);
}
@@ -39,6 +39,8 @@ namespace FrameLedger.Shared.Ipc;
[JsonSerializable(typeof(SetHookEnabledRequest))]
[JsonSerializable(typeof(HookEnabledAck))]
[JsonSerializable(typeof(RefusedAck))]
[JsonSerializable(typeof(SetAntiCheatExceptionRequest))]
[JsonSerializable(typeof(AntiCheatExceptionAck))]
[JsonSerializable(typeof(PauseCaptureRequest))]
[JsonSerializable(typeof(ResumeCaptureRequest))]
[JsonSerializable(typeof(PauseAck))]
+27 -2
View File
@@ -45,6 +45,14 @@ public static class IpcMessageType
public const string Shutdown = "Shutdown";
public const string ShutdownAck = "ShutdownAck";
/// <summary>
/// D33 (owner decision 2026-09-26): grant or withdraw a game's user-mode anti-cheat exception. The Agent re-checks every
/// condition itself — the option, the disclosure version, the block, a tolerant pre-scan, the session count — and
/// answers <see cref="AntiCheatExceptionAck"/>, <see cref="Refused"/> or <see cref="Error"/>.
/// </summary>
public const string SetAntiCheatException = "SetAntiCheatException";
public const string AntiCheatExceptionAck = "AntiCheatExceptionAck";
/// <summary>Tools ▸ Database maintenance (P4 PR-7): the on-demand retention sweep, which the Agent runs because the blob tables are its.</summary>
public const string SweepRetention = "SweepRetention";
public const string SweepRetentionAck = "SweepRetentionAck";
@@ -85,6 +93,9 @@ public static class IpcErrorCode
public const string UnknownGame = "UnknownGame";
public const string ExecutableUnreadable = "ExecutableUnreadable";
/// <summary>D33: <c>SetAntiCheatException true</c> while <c>hooking.usermode_ac_exceptions</c> is off — nothing is granted.</summary>
public const string ExceptionsOff = "ExceptionsOff";
}
/// <summary>Codes a <see cref="CaptureErrorEvent"/> carries (<c>07_IPC</c> §Messages, <c>CaptureError</c>).</summary>
@@ -108,7 +119,8 @@ public sealed record HelloRequest(string AppVersion, int Protocol);
/// (2026-08-28); <c>VulkanLayerRegistered</c> is false by construction today — the layer is handed to a launched
/// process through <c>VK_ADD_IMPLICIT_LAYER_PATH</c>, never registered machine-wide (P1 item 3).
/// <c>DisclosureVersion</c> (P3 PR-4, D14) is the FR-2.1 text this Agent stamps against; the App refuses to open
/// the consent dialog when it differs from its own <c>SafetyDisclosure.Version</c>.
/// the consent dialog when it differs from its own <c>SafetyDisclosure.Version</c>. <c>ExceptionDisclosureVersion</c>
/// (D33) is the same rule for the user-mode exception's disclosure (<c>AntiCheatExceptionDisclosure.Version</c>).
/// </summary>
public sealed record HelloAck(
string AgentVersion,
@@ -119,7 +131,8 @@ public sealed record HelloAck(
bool VulkanLayerRegistered,
string? TelemetrySource,
bool CpuTempAvailable,
string? DisclosureVersion = null);
string? DisclosureVersion = null,
string? ExceptionDisclosureVersion = null);
/// <summary><c>GetStatus</c>: no payload.</summary>
public sealed record GetStatusRequest;
@@ -302,6 +315,18 @@ public sealed record HookEnabledAck(long GameId, bool Enabled, string Outcome, s
/// <summary>The Agent's pre-scan refused to enable: the reason, and the family/signal when it named one. The block is on the row.</summary>
public sealed record RefusedAck(long GameId, string Reason, string? Family, string? Signal);
/// <summary>
/// <c>SetAntiCheatException</c> (D33). <c>DisclosureVersion</c> is the version of the exception's disclosure the client
/// showed and the user accepted; a grant is written only when it is the Agent's own. A withdrawal needs none.
/// </summary>
public sealed record SetAntiCheatExceptionRequest(long GameId, bool Enabled, string? DisclosureVersion);
/// <summary>
/// The Agent's answer to <c>SetAntiCheatException</c>: <c>Granted</c> is whether an exception is in force now, <c>Outcome</c>
/// the store's word, <c>Family</c> the anti-cheat family it covers.
/// </summary>
public sealed record AntiCheatExceptionAck(long GameId, bool Granted, string Outcome, string? Family);
public sealed record PauseCaptureRequest;
public sealed record ResumeCaptureRequest;
@@ -0,0 +1,16 @@
namespace FrameLedger.Shared.Safety;
/// <summary>
/// D33 (owner decision 2026-09-26): the version of the user-mode anti-cheat exception's disclosure this build carries — the
/// <c>Safety_Exception_*</c> strings in <c>Strings.resx</c> beside this file. The same rule as
/// <see cref="SafetyDisclosure"/>: the App shows the text and sends the version it showed, the Agent's <c>HelloAck</c>
/// carries its own, and <c>SetAntiCheatException</c> grants only when the two agree.
/// </summary>
/// <remarks>
/// Bump it whenever a <c>Safety_Exception_*</c> string changes MEANING in any language. A grant carries the version it was
/// made against (<c>games.ac_exception_disclosure_version</c>, schema 0014).
/// </remarks>
public static class AntiCheatExceptionDisclosure
{
public const string Version = "ac-exception-dialog/1";
}
+42
View File
@@ -755,3 +755,45 @@ public unsafe struct FlFrameRecord
/// </summary>
public uint SwapchainId;
}
/// <summary>
/// D33 (owner decision 2026-09-26) — <c>fl_tolerance.h</c>: the families the injected Overlay may see load without
/// stopping, under a game's user-mode exception. Written by the Agent into <c>Local\FrameLedger.Tolerate.&lt;pid&gt;</c>
/// BEFORE it asks the guard to inject, read once by the Overlay's init thread before its loader detour exists. NAMES,
/// never indices: the Overlay resolves them against its own compiled floor and honours only a user-mode family.
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public unsafe struct FlTolerance
{
/// <summary><see cref="ToleranceLayout.Magic"/>.</summary>
public uint Magic;
/// <summary><see cref="ToleranceLayout.Version"/>.</summary>
public uint Version;
/// <summary>Names used, at most <see cref="ToleranceLayout.MaxFamilies"/>.</summary>
public uint Count;
/// <summary>Must be zero.</summary>
public uint Reserved;
/// <summary><see cref="ToleranceLayout.MaxFamilies"/> NUL-terminated ASCII names, <see cref="ToleranceLayout.NameLen"/> bytes each.</summary>
public fixed byte Families[512];
}
/// <summary>The constants of <c>fl_tolerance.h</c>. Drift is caught by the mirror test.</summary>
public static class ToleranceLayout
{
/// <summary>"FLTL", little-endian.</summary>
public const uint Magic = 0x4C544C46u;
public const uint Version = 1u;
public const int MaxFamilies = 8;
public const int NameLen = 64;
/// <summary>The mapping's name for a game process — <c>MakeToleranceName</c>.</summary>
public static string MappingName(int pid) =>
"Local\\FrameLedger.Tolerate." + pid.ToString(System.Globalization.CultureInfo.InvariantCulture);
}
+39
View File
@@ -41,6 +41,19 @@ public static class Strings
nameof(Safety_Consent_Title_Format),
nameof(Safety_Consent_TypeToConfirm_Format),
nameof(Safety_Consent_VersionMismatch),
nameof(Safety_Exception_Accept),
nameof(Safety_Exception_Cancel),
nameof(Safety_Exception_Ends),
nameof(Safety_Exception_Grant),
nameof(Safety_Exception_Intro_Format),
nameof(Safety_Exception_Next),
nameof(Safety_Exception_Online),
nameof(Safety_Exception_OptionOff),
nameof(Safety_Exception_Risk_Format),
nameof(Safety_Exception_Still_Format),
nameof(Safety_Exception_Title_Format),
nameof(Safety_Exception_VersionMismatch),
nameof(Safety_Exception_Why_Format),
nameof(Safety_HookingTurnedOff),
nameof(Safety_RecordWithoutMeasuring),
nameof(Safety_Refused_CouldNotVerify),
@@ -80,6 +93,32 @@ public static class Strings
public static string Safety_Consent_VersionMismatch => ResourceManager.GetString(nameof(Safety_Consent_VersionMismatch), Culture) ?? nameof(Safety_Consent_VersionMismatch);
public static string Safety_Exception_Accept => ResourceManager.GetString(nameof(Safety_Exception_Accept), Culture) ?? nameof(Safety_Exception_Accept);
public static string Safety_Exception_Cancel => ResourceManager.GetString(nameof(Safety_Exception_Cancel), Culture) ?? nameof(Safety_Exception_Cancel);
public static string Safety_Exception_Ends => ResourceManager.GetString(nameof(Safety_Exception_Ends), Culture) ?? nameof(Safety_Exception_Ends);
public static string Safety_Exception_Grant => ResourceManager.GetString(nameof(Safety_Exception_Grant), Culture) ?? nameof(Safety_Exception_Grant);
public static string Safety_Exception_Intro_Format => ResourceManager.GetString(nameof(Safety_Exception_Intro_Format), Culture) ?? nameof(Safety_Exception_Intro_Format);
public static string Safety_Exception_Next => ResourceManager.GetString(nameof(Safety_Exception_Next), Culture) ?? nameof(Safety_Exception_Next);
public static string Safety_Exception_Online => ResourceManager.GetString(nameof(Safety_Exception_Online), Culture) ?? nameof(Safety_Exception_Online);
public static string Safety_Exception_OptionOff => ResourceManager.GetString(nameof(Safety_Exception_OptionOff), Culture) ?? nameof(Safety_Exception_OptionOff);
public static string Safety_Exception_Risk_Format => ResourceManager.GetString(nameof(Safety_Exception_Risk_Format), Culture) ?? nameof(Safety_Exception_Risk_Format);
public static string Safety_Exception_Still_Format => ResourceManager.GetString(nameof(Safety_Exception_Still_Format), Culture) ?? nameof(Safety_Exception_Still_Format);
public static string Safety_Exception_Title_Format => ResourceManager.GetString(nameof(Safety_Exception_Title_Format), Culture) ?? nameof(Safety_Exception_Title_Format);
public static string Safety_Exception_VersionMismatch => ResourceManager.GetString(nameof(Safety_Exception_VersionMismatch), Culture) ?? nameof(Safety_Exception_VersionMismatch);
public static string Safety_Exception_Why_Format => ResourceManager.GetString(nameof(Safety_Exception_Why_Format), Culture) ?? nameof(Safety_Exception_Why_Format);
public static string Safety_HookingTurnedOff => ResourceManager.GetString(nameof(Safety_HookingTurnedOff), Culture) ?? nameof(Safety_HookingTurnedOff);
public static string Safety_RecordWithoutMeasuring => ResourceManager.GetString(nameof(Safety_RecordWithoutMeasuring), Culture) ?? nameof(Safety_RecordWithoutMeasuring);
+13
View File
@@ -32,4 +32,17 @@
<data name="Safety_HookingTurnedOff" xml:space="preserve"><value>Hooking has been turned off for this game; its page says what was found.</value><comment>safety: human review required</comment></data>
<data name="Safety_Unhooked_Format" xml:space="preserve"><value>Capture stopped: {0} was detected while the game was running. FrameLedger unhooked and will not inject into this game again until you enable it again.</value><comment>safety: human review required</comment></data>
<data name="Safety_Refused_TargetUnreadable" xml:space="preserve"><value>The game is running, but Windows would not let FrameLedger open its process: it is protected by an anti-cheat driver, or it runs as administrator while FrameLedger does not. Nothing was injected and this run was not measured. FrameLedger will not work around another product's protection.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Title_Format" xml:space="preserve"><value>Make a user-mode exception for {0}?</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Intro_Format" xml:space="preserve"><value>FrameLedger found {0} in this game ({1}) and turned its hooking off. This dialog asks whether to make an exception for this game only. It recommends neither choice.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Why_Format" xml:space="preserve"><value>The exception is offered because {0} runs entirely in user mode — no kernel driver, no service and no driver file in the game's folder — and FrameLedger has already measured this game hooked, successfully, {1} times.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Risk_Format" xml:space="preserve"><value>The risk is the same as before, and it is yours. {0} is anti-cheat. It may detect FrameLedger in the game and warn, block or permanently ban your account — possibly days later, and FrameLedger cannot know whether it did. Sessions that went well before are no promise about the next one, or about the next update of the anti-cheat.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Still_Format" xml:space="preserve"><value>Under the exception the guard still runs every check, and still refuses a kernel driver in the game's folder, any other anti-cheat, an anti-cheat driver or service on this machine, a scan it cannot finish, and a title it refuses by name. The exception covers {0} and nothing else.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Ends" xml:space="preserve"><value>The exception ends by itself when something new is found, when a session under it crashes or is stopped for safety, when FrameLedger stops observing because another anti-cheat loaded, or when the game is updated. Turning the option off in Settings suspends it. You can withdraw it at any time.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Next" xml:space="preserve"><value>Making the exception does not turn hooking on. You turn hooking on for this game afterwards, through the usual consent dialog.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Online" xml:space="preserve"><value>FrameLedger is intended for offline and single-player play. Do not use this exception with a game you play online or competitively unless you accept losing that account.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Accept" xml:space="preserve"><value>I accept the risk of a ban for this game</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Grant" xml:space="preserve"><value>Make the exception</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Cancel" xml:space="preserve"><value>Keep it blocked</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_VersionMismatch" xml:space="preserve"><value>This app and the capture agent carry different versions of this text. Nothing was granted. Restart both, then try again.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_OptionOff" xml:space="preserve"><value>The user-mode exception option is off in Settings, so nothing was granted.</value><comment>safety: human review required</comment></data>
</root>
+15
View File
@@ -7,6 +7,8 @@
recommends neither; "limited", "reduced", "degraded" never describe Tier 2; no sentence names what the
user loses by declining. SafetyDisclosure.Version (Safety/SafetyDisclosure.cs) changes when any
Safety_Consent_* string changes meaning, and the Agent refuses to stamp against any other version.
AntiCheatExceptionDisclosure.Version (Safety/AntiCheatExceptionDisclosure.cs) is the same rule for the Safety_Exception_*
family, the user-mode exception's disclosure (D33, 2026-09-26): it states the risk at the same grain and recommends neither.
Strings.Designer.cs is generated by tools/resx-gen.ps1 and committed; tools/resx-audit.ps1 gates it.
-->
<resheader name="resmimetype"><value>text/microsoft-resx</value></resheader>
@@ -35,4 +37,17 @@
<data name="Safety_HookingTurnedOff" xml:space="preserve"><value>Hooking has been turned off for this game; its page says what was found.</value></data>
<data name="Safety_Unhooked_Format" xml:space="preserve"><value>Capture stopped: {0} was detected while the game was running. FrameLedger unhooked and will not inject into this game again until you enable it again.</value></data>
<data name="Safety_Refused_TargetUnreadable" xml:space="preserve"><value>The game is running, but Windows would not let FrameLedger open its process: it is protected by an anti-cheat driver, or it runs as administrator while FrameLedger does not. Nothing was injected and this run was not measured. FrameLedger will not work around another product's protection.</value></data>
<data name="Safety_Exception_Title_Format" xml:space="preserve"><value>Make a user-mode exception for {0}?</value></data>
<data name="Safety_Exception_Intro_Format" xml:space="preserve"><value>FrameLedger found {0} in this game ({1}) and turned its hooking off. This dialog asks whether to make an exception for this game only. It recommends neither choice.</value></data>
<data name="Safety_Exception_Why_Format" xml:space="preserve"><value>The exception is offered because {0} runs entirely in user mode — no kernel driver, no service and no driver file in the game's folder — and FrameLedger has already measured this game hooked, successfully, {1} times.</value></data>
<data name="Safety_Exception_Risk_Format" xml:space="preserve"><value>The risk is the same as before, and it is yours. {0} is anti-cheat. It may detect FrameLedger in the game and warn, block or permanently ban your account — possibly days later, and FrameLedger cannot know whether it did. Sessions that went well before are no promise about the next one, or about the next update of the anti-cheat.</value></data>
<data name="Safety_Exception_Still_Format" xml:space="preserve"><value>Under the exception the guard still runs every check, and still refuses a kernel driver in the game's folder, any other anti-cheat, an anti-cheat driver or service on this machine, a scan it cannot finish, and a title it refuses by name. The exception covers {0} and nothing else.</value></data>
<data name="Safety_Exception_Ends" xml:space="preserve"><value>The exception ends by itself when something new is found, when a session under it crashes or is stopped for safety, when FrameLedger stops observing because another anti-cheat loaded, or when the game is updated. Turning the option off in Settings suspends it. You can withdraw it at any time.</value></data>
<data name="Safety_Exception_Next" xml:space="preserve"><value>Making the exception does not turn hooking on. You turn hooking on for this game afterwards, through the usual consent dialog.</value></data>
<data name="Safety_Exception_Online" xml:space="preserve"><value>FrameLedger is intended for offline and single-player play. Do not use this exception with a game you play online or competitively unless you accept losing that account.</value></data>
<data name="Safety_Exception_Accept" xml:space="preserve"><value>I accept the risk of a ban for this game</value></data>
<data name="Safety_Exception_Grant" xml:space="preserve"><value>Make the exception</value></data>
<data name="Safety_Exception_Cancel" xml:space="preserve"><value>Keep it blocked</value></data>
<data name="Safety_Exception_VersionMismatch" xml:space="preserve"><value>This app and the capture agent carry different versions of this text. Nothing was granted. Restart both, then try again.</value></data>
<data name="Safety_Exception_OptionOff" xml:space="preserve"><value>The user-mode exception option is off in Settings, so nothing was granted.</value></data>
</root>
+13
View File
@@ -31,4 +31,17 @@
<data name="Safety_HookingTurnedOff" xml:space="preserve"><value>Hooking đã được tắt cho game này; trang của game ghi rõ đã phát hiện gì.</value></data>
<data name="Safety_Unhooked_Format" xml:space="preserve"><value>Đã dừng thu thập: phát hiện {0} khi game đang chạy. FrameLedger đã gỡ hook và sẽ không inject vào game này nữa cho đến khi bạn bật lại.</value></data>
<data name="Safety_Refused_TargetUnreadable" xml:space="preserve"><value>Game đang chạy, nhưng Windows không cho FrameLedger mở tiến trình của nó: tiến trình được driver anti-cheat bảo vệ, hoặc game chạy với quyền quản trị còn FrameLedger thì không. Không có gì được inject và lần chạy này không được đo. FrameLedger sẽ không tìm cách vượt qua cơ chế bảo vệ của sản phẩm khác.</value></data>
<data name="Safety_Exception_Title_Format" xml:space="preserve"><value>Tạo ngoại lệ user-mode cho {0}?</value></data>
<data name="Safety_Exception_Intro_Format" xml:space="preserve"><value>FrameLedger đã phát hiện {0} trong game này ({1}) và đã tắt hooking cho nó. Hộp thoại này hỏi bạn có muốn tạo ngoại lệ cho riêng game này không. Nó không khuyến nghị lựa chọn nào.</value></data>
<data name="Safety_Exception_Why_Format" xml:space="preserve"><value>Ngoại lệ được đề xuất vì {0} chạy hoàn toàn ở user mode — không có kernel driver, không có service và không có tệp driver nào trong thư mục game — và FrameLedger đã đo game này ở chế độ hook thành công {1} lần.</value></data>
<data name="Safety_Exception_Risk_Format" xml:space="preserve"><value>Rủi ro vẫn như trước, và bạn là người chịu. {0} là anti-cheat. Nó có thể phát hiện FrameLedger trong game và cảnh báo, chặn hoặc khoá vĩnh viễn tài khoản của bạn — có thể sau nhiều ngày, và FrameLedger không thể biết điều đó có xảy ra hay không. Các phiên đã chạy ổn trước đây không bảo đảm gì cho phiên tiếp theo, hay cho bản cập nhật tiếp theo của anti-cheat.</value></data>
<data name="Safety_Exception_Still_Format" xml:space="preserve"><value>Dưới ngoại lệ, bộ bảo vệ vẫn chạy mọi bước kiểm tra, và vẫn từ chối khi có kernel driver trong thư mục game, bất kỳ anti-cheat nào khác, driver hay service anti-cheat trên máy này, một lần quét không hoàn tất, và các tựa game bị từ chối theo tên. Ngoại lệ chỉ áp dụng cho {0}, không gì khác.</value></data>
<data name="Safety_Exception_Ends" xml:space="preserve"><value>Ngoại lệ tự kết thúc khi phát hiện điều gì mới, khi một phiên dưới ngoại lệ bị crash hoặc bị dừng vì an toàn, khi FrameLedger ngừng quan sát vì một anti-cheat khác được nạp, hoặc khi game được cập nhật. Tắt tuỳ chọn trong Cài đặt sẽ tạm ngưng nó. Bạn có thể rút lại bất cứ lúc nào.</value></data>
<data name="Safety_Exception_Next" xml:space="preserve"><value>Tạo ngoại lệ không bật hooking. Sau đó bạn tự bật hooking cho game này qua hộp thoại đồng ý thông thường.</value></data>
<data name="Safety_Exception_Online" xml:space="preserve"><value>FrameLedger dành cho chơi offline và chơi đơn. Đừng dùng ngoại lệ này với game bạn chơi online hoặc thi đấu, trừ khi bạn chấp nhận mất tài khoản đó.</value></data>
<data name="Safety_Exception_Accept" xml:space="preserve"><value>Tôi chấp nhận rủi ro bị khoá tài khoản cho game này</value></data>
<data name="Safety_Exception_Grant" xml:space="preserve"><value>Tạo ngoại lệ</value></data>
<data name="Safety_Exception_Cancel" xml:space="preserve"><value>Giữ chặn</value></data>
<data name="Safety_Exception_VersionMismatch" xml:space="preserve"><value>Ứng dụng và capture agent đang mang hai phiên bản khác nhau của văn bản này. Không có gì được cấp. Hãy khởi động lại cả hai rồi thử lại.</value></data>
<data name="Safety_Exception_OptionOff" xml:space="preserve"><value>Tuỳ chọn ngoại lệ user-mode đang tắt trong Cài đặt, nên không có gì được cấp.</value></data>
</root>
@@ -139,6 +139,108 @@ struct Rules {
std::size_t trustedSignerCount = 0;
};
// ---------------------------------------------------------------------------
// D33 (owner decision 2026-09-26) — the user-mode exception
// ---------------------------------------------------------------------------
//
// A user may except ONE game from the findings of ONE anti-cheat family, and only a family whose whole known footprint
// is user-mode (19_SAFETY §The user-mode exception). A caller can NAME a family (the ABI's `toleratedFamilies`) and
// nothing more: which families a name reaches, and whether that family is user-mode, are the guard's own answers from
// the rules it is evaluating with. A name that fails here is tolerated nowhere — fail closed.
// ASCII case-insensitive equality. Inline so the Overlay, which compiles no fl_ac_rules.cpp, resolves its tolerance
// against the compiled floor with the same comparison the guard uses.
[[nodiscard]] inline bool AsciiIEquals(const char* a, const char* b) noexcept {
if (a == nullptr || b == nullptr) {
return false;
}
for (;; ++a, ++b) {
char ca = *a;
char cb = *b;
if (ca >= 'A' && ca <= 'Z') {
ca = static_cast<char>(ca - 'A' + 'a');
}
if (cb >= 'A' && cb <= 'Z') {
cb = static_cast<char>(cb - 'A' + 'a');
}
if (ca != cb) {
return false;
}
if (ca == '\0') {
return true;
}
}
}
// True for a value ending in ".sys", ASCII case-insensitively.
[[nodiscard]] inline bool EndsWithSysSuffix(const char* value) noexcept {
if (value == nullptr) {
return false;
}
std::size_t n = 0;
while (value[n] != '\0') {
++n;
}
return n > 4 && AsciiIEquals(value + n - 4, ".sys");
}
// True iff `familyName` names at least one of `families` and EVERY entry naming it sits in a user-mode group —
// modules, directories, files — with no `*.sys` value. A family with a `drivers` or `services` entry anywhere (the
// floor or the file), or a kernel driver among its files, is kernel-level and never tolerable. A name no family carries
// — a title-list family such as Valve VAC, or the kernel-driver code rule's family — is false. The floor cannot be
// shrunk by data, so a rules file can make a family kernel-level (add a driver) and never the reverse.
[[nodiscard]] inline bool FamilyIsUserModeOnly(const Family* families, std::size_t count,
const char* familyName) noexcept {
if (families == nullptr || familyName == nullptr || familyName[0] == '\0') {
return false;
}
bool named = false;
for (std::size_t i = 0; i < count; ++i) {
const Family& f = families[i];
if (!AsciiIEquals(f.name, familyName)) {
continue;
}
named = true;
if (f.group == Group::kDrivers || f.group == Group::kServices) {
return false;
}
if (f.group == Group::kFiles) {
for (std::size_t v = 0; v < f.valueCount; ++v) {
if (EndsWithSysSuffix(f.values[v])) {
return false;
}
}
}
}
return named;
}
[[nodiscard]] inline bool FamilyIsUserModeOnly(const Rules& rules, const char* familyName) noexcept {
return FamilyIsUserModeOnly(rules.families, rules.familyCount, familyName);
}
// How many names one exception list may carry. v1 grants one family per game; the room is for a later version, and a
// longer list is read up to this many names — tolerating fewer is the safe direction.
inline constexpr std::size_t kMaxToleratedFamilies = 8;
// The families one evaluation tolerates, resolved against the rules it evaluates with: `family[i]` covers
// `rules.families[i]`. Value-initialised, it tolerates nothing.
struct Tolerance {
bool family[kMaxFamilies] = {};
bool any = false;
};
// `toleratedFamilies` is newline-separated family names; null or empty tolerates nothing. A name is honoured only when
// FamilyIsUserModeOnly(rules, name) — and then for every entry of that family, in every user-mode group. Unknown and
// kernel-level names, and a name longer than kMaxFamilyNameLen - 1, are ignored: they widen nothing.
void ResolveTolerance(const Rules& rules, const char* toleratedFamilies, Tolerance& out) noexcept;
// MatchName that never returns a family the tolerance covers. When `tolerated` is non-null it receives the first
// covered family that matched `observed` (and is left untouched when none did), so a caller can record what it let
// through while a non-covered family matching the same name still refuses.
[[nodiscard]] const Family* MatchNameTolerating(const Rules& rules, Group group, const char* observed,
const Tolerance& tolerance, const Family** tolerated) noexcept;
// Returns `r` to the state of a value-initialised `Rules{}` WITHOUT materialising one.
//
// `r = Rules{}` builds a ~530 KB temporary on the stack before copying it, and ParseRules runs inside the Vulkan
@@ -183,9 +183,20 @@ enum class Reason : std::uint8_t {
kKillSwitchEngaged,
// Value 28 was kAllowedUnderUserBypass, the one day the guard had an override (2026-09-21, withdrawn by the owner
// on 2026-09-22 before any release carried it past beta.4). It was the LAST enumerator, so removing it renumbers
// nothing; the managed mirror dropped it in the same change and GuardMirrorTests holds the two counts equal. A
// refusal is a refusal again: there is no entry point that injects past one.
// on 2026-09-22 before any release carried it past beta.4). It was the LAST enumerator, so removing it renumbered
// nothing, and a refusal stayed a refusal: there is no entry point that injects past one.
//
// D33 (owner decision 2026-09-26) reuses the slot for something narrower, and it is not that override back. The
// guard ran EVERY check; the only findings it saw were of the one family the caller named, and that family's whole
// footprint — floor and file — is user-mode (FamilyIsUserModeOnly: no driver, no service, no `.sys`). Everything
// else still refused as it always does: a driver or service on the machine, a title list, a `.sys` anywhere in the
// tree, the fuzzy tier, a scan that could not finish, another family. The verdict carries the tolerated family and
// the signal, so the session it starts is marked with them (19_SAFETY §The user-mode exception).
//
// Allowed() is true for it — the DLL is loaded, which is what Allowed() has meant since kInjectionFailed existed —
// and it is produced ONLY as EvaluateImpl's final answer, never by a sub-check, so the `!Allowed()` chains between
// checks read exactly as before.
kAllowedUserModeException,
// NOT A REASON. The count, so appending above it updates the exported
// FlGuardReasonCount by construction.
@@ -207,7 +218,20 @@ struct Verdict {
char family[64] = {}; // e.g. "Easy Anti-Cheat"
char signal[260] = {}; // e.g. "EasyAntiCheat_EOS.dll"
[[nodiscard]] bool Allowed() const noexcept { return reason == Reason::kAllow; }
// kAllowedUserModeException too (D33): every check ran, and the only findings belonged to the one user-mode family
// the caller's exception names. See the enumerator.
[[nodiscard]] bool Allowed() const noexcept {
return reason == Reason::kAllow || reason == Reason::kAllowedUserModeException;
}
};
// D33 — the first finding a tolerated family produced during one evaluation (a module in the scan set, or a file or
// folder in the install tree). When nothing else refuses, it becomes the kAllowedUserModeException verdict's family and
// signal, so the session is marked with what was let through.
struct ToleratedFinding {
bool seen = false;
char family[64] = {};
char signal[260] = {};
};
// The literal default must be a refusal, not an allow. Asserted rather than
@@ -450,7 +474,12 @@ struct Sources {
// While the injection primitive was a stub, a caller passing all-clean fakes
// was a theoretical hole; the moment injection became real it would have been
// a way into a game process that never consulted a single genuine signal.
[[nodiscard]] Verdict GuardedInject(std::uint32_t targetPid, const wchar_t* dllPath) noexcept;
//
// `toleratedFamilies` (D33) is the one thing a caller may add, and it is a NAME, not evidence: newline-separated
// anti-cheat families the user's exception covers for this game, resolved against the rules by ResolveTolerance, which
// honours only a family whose whole footprint is user-mode. Null or empty is the guard exactly as before.
[[nodiscard]] Verdict GuardedInject(std::uint32_t targetPid, const wchar_t* dllPath,
const char* toleratedFamilies = nullptr) noexcept;
// LAUNCH MODE. Poll `targetPid` -- every 50 ms, up to `timeoutMs` -- until it has
// mapped a presentation runtime (dxgi.dll with d3d11.dll or d3d12.dll, or
@@ -461,19 +490,24 @@ struct Sources {
// exits first, or never maps a runtime inside the budget, is refused with
// kLaunchTargetExited / kLaunchNoPresentationRuntime and nothing is injected.
// 04_CAPTURE §Launch mode; 20_OPEN_QUESTIONS §S1 / §S13(c).
[[nodiscard]] Verdict GuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath,
std::uint32_t timeoutMs) noexcept;
//
// A Vulkan target is evaluated WITHOUT the tolerance (D33): the implicit layer runs its own module self-scan and goes
// inert on any anti-cheat module, so an exception could not reach it and must not be spent on it.
[[nodiscard]] Verdict GuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
const char* toleratedFamilies = nullptr) noexcept;
// Evaluate the guard WITHOUT injecting. Exists for the 30 s in-session re-scan
// (19_SAFETY §During a session), which must reach a verdict on a process it is
// already inside and has nothing to inject. Deliberately cannot be used to
// pre-authorise an injection: it takes no dll path and returns no token, so the
// only way to act on a pass is to call GuardedInject, which re-collects.
[[nodiscard]] Verdict Evaluate(std::uint32_t targetPid) noexcept;
[[nodiscard]] Verdict Evaluate(std::uint32_t targetPid, const char* toleratedFamilies = nullptr) noexcept;
// There were two more entry points here for one day (GuardedInjectAcknowledged and its WhenReady twin, the user's
// bypass of 2026-09-21). Withdrawn 2026-09-22: the guard has no entry that injects past its own refusal, and a
// finding about the game turns that game's hooking off instead (19_SAFETY §What a finding does to the game).
// finding about the game turns that game's hooking off instead (19_SAFETY §What a finding does to the game). D33's
// `toleratedFamilies` is not that entry: it narrows what counts as a finding for one user-mode family, and the guard
// still runs, and refuses on, everything else.
#ifdef FL_GUARD_TESTABLE
// ---------------------------------------------------------------------------
@@ -487,11 +521,13 @@ struct Sources {
// cannot be exercised is an input whose failure path is unverified. So the seam
// exists — and is unavailable to anything a user runs.
// ---------------------------------------------------------------------------
[[nodiscard]] Verdict EvaluateWithSources(std::uint32_t targetPid, const Sources& sources) noexcept;
[[nodiscard]] Verdict GuardedInjectWithSources(std::uint32_t targetPid, const wchar_t* dllPath,
const Sources& sources) noexcept;
[[nodiscard]] Verdict EvaluateWithSources(std::uint32_t targetPid, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
[[nodiscard]] Verdict GuardedInjectWithSources(std::uint32_t targetPid, const wchar_t* dllPath, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
[[nodiscard]] Verdict GuardedInjectWhenReadyWithSources(std::uint32_t targetPid, const wchar_t* dllPath,
std::uint32_t timeoutMs, const Sources& sources) noexcept;
std::uint32_t timeoutMs, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
#endif
// Human-readable reason, for logs and for mapping to resx keys.
@@ -46,14 +46,23 @@ struct FlGuardResult {
char signal[260]; // e.g. "EasyAntiCheat_EOS.dll"
};
// `toleratedFamilies` — D33 (owner decision 2026-09-26), on the four evaluating entries below. The user's exception
// for ONE game, by NAME: newline-separated anti-cheat families (UTF-8), null or "" for none. It is not evidence and
// it is not a switch: the guard still collects everything itself and runs every check, resolves the names against
// its own rules, honours only a family whose whole footprint is user-mode (no driver, no service, no `.sys`), and
// then lets that family's modules, files and folders through while every other finding refuses as before. A pass
// that let something through answers AllowedUnderUserModeException with the family and the signal, never Allow.
// It is not the withdrawn bypass either (below): nothing here injects past a refusal the guard made.
// Run every pre-injection check against `targetPid`. No injection.
// Used for the 30 s in-session re-scan (19_SAFETY §During a session).
FL_GUARD_ABI void FlGuardEvaluate(std::uint32_t targetPid, FlGuardResult* out);
FL_GUARD_ABI void FlGuardEvaluate(std::uint32_t targetPid, const char* toleratedFamilies, FlGuardResult* out);
// Run every check and, only on a pass, inject `dllPath` via documented
// LoadLibraryW. There is no variant that skips the checks, and no way to hand
// in evidence — the guard collects its own.
FL_GUARD_ABI void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, FlGuardResult* out);
FL_GUARD_ABI void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, const char* toleratedFamilies,
FlGuardResult* out);
// LAUNCH MODE (P1 item 2). Wait -- polling every 50 ms, up to `timeoutMs` -- until
// `targetPid` has mapped a presentation runtime, then run every check and inject
@@ -63,8 +72,9 @@ FL_GUARD_ABI void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPat
// runtime inside the budget, answers LaunchTargetExited / LaunchNoPresentationRuntime
// with nothing injected. The caller launches and holds the process; this never
// creates or terminates one (04_CAPTURE §Launch mode, 20_OPEN_QUESTIONS §S1).
// A Vulkan target is evaluated without `toleratedFamilies`: the layer's own self-scan would go inert anyway.
FL_GUARD_ABI void FlGuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
FlGuardResult* out);
const char* toleratedFamilies, FlGuardResult* out);
// FlGuardedInjectAcknowledged, FlGuardedInjectWhenReadyAcknowledged and FlGuardIsJudgement were exported for one day
// (2026-09-21, the user's bypass) and withdrawn on 2026-09-22. The ABI has no entry that injects past a refusal.
@@ -82,7 +92,11 @@ FL_GUARD_ABI void FlGuardedInjectWhenReady(std::uint32_t targetPid, const wchar_
// It reports through FlGuardResult rather than an outcome enum of its own, so there is ONE reason table and ONE
// mirror surface: kAllow means clean; BlockedExecutable, BlockedStoreId, AntiCheatDirectory and AntiCheatFile name
// what was found; PreScanFailed or a Rules* reason means the scan could not reach an answer.
FL_GUARD_ABI void FlStaticPreScanGame(const wchar_t* exePath, FlGuardResult* out);
//
// With `toleratedFamilies`, AllowedUnderUserModeException means "this game passes checks 3 and 4 under its
// exception" — the question the Agent asks before it offers or keeps one (a `.sys` in the tree, a title list or
// another family still refuses).
FL_GUARD_ABI void FlStaticPreScanGame(const wchar_t* exePath, const char* toleratedFamilies, FlGuardResult* out);
// Stable name for a reason code. The managed mirror test compares these against
// its own enum, so this is a contract and not a debugging aid.
@@ -101,7 +101,13 @@ inline constexpr const char* kKernelDriverInTreeFamily = "Kernel driver in the g
// unverified (fl_guard.h rule 3). It grants nothing: it opens no process with
// injection rights, reaches no injection primitive, and returns a Verdict its
// only caller already had to reach anyway.
[[nodiscard]] Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t targetPid) noexcept;
//
// D33: with a `tolerance`, a file or folder of a tolerated family is recorded in `finding` and the walk goes on, so a
// kernel driver, another family or an unfinished walk further in still refuses. A `.sys` is never tolerated, whatever
// family names it. Without one (null), the check is exactly what it was.
[[nodiscard]] Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t targetPid,
const Tolerance* tolerance = nullptr,
ToleratedFinding* finding = nullptr) noexcept;
// Check 3's store half over an install root: the store identity it carries (Sources::StoreIdentity) against
// `blockedStoreIds`. An install with no store identity is NOT refused — "not a store title" is an answer, and
@@ -125,12 +131,17 @@ inline constexpr const char* kKernelDriverInTreeFamily = "Kernel driver in the g
//
// Loads the rules itself and uses SystemSources(), so a caller cannot choose the evidence — the same reason Evaluate
// and GuardedInject take no Sources.
[[nodiscard]] Verdict StaticPreScanGame(const wchar_t* exePath) noexcept;
//
// `toleratedFamilies` (D33), exactly as GuardedInject takes it: the verdict is kAllowedUserModeException when the only
// findings belonged to a tolerated user-mode family, which is how the Agent tells "this game would pass under its
// exception" from "it would not" without a second matcher.
[[nodiscard]] Verdict StaticPreScanGame(const wchar_t* exePath, const char* toleratedFamilies = nullptr) noexcept;
#ifdef FL_GUARD_TESTABLE
// TEST-ONLY, exactly as fl_guard.h defines the term: compiled out of everything
// that ships, and only src/native/tests may define the macro.
[[nodiscard]] Verdict StaticPreScanGameWithSources(const wchar_t* exePath, const Sources& sources) noexcept;
[[nodiscard]] Verdict StaticPreScanGameWithSources(const wchar_t* exePath, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
#endif
} // namespace fl::guard
Loaded 100 of 135 files, more files were not shown because too many files have changed in this diff. Show more