Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 18210e22a3 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)
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-26 04:09:35 +07:00
74 changed files with 2859 additions and 164 deletions

No files matched your search

+11
View File
@@ -38,6 +38,17 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
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.
## [0.1.0-beta.8] - 2026-09-25
+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
+4 -3
View File
@@ -280,7 +280,7 @@ Created by the Agent for the game's pid, current user only, held for the session
`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; the Agent writes it from PR-2.)*
`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`)
@@ -345,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.)* |
+6 -3
View File
@@ -522,9 +522,12 @@ and the user ticks each game), not reachable from the command line, and not evas
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, with nothing yet asking for either
(`NativeAntiCheatGuard` passes none). The Agent's eligibility, gate and records follow in PR-2; the option, the list,
the disclosure and the legal text in PR-3.*
*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 disclosure, the game page and the legal text.*
### The floor data cannot remove
+13
View File
@@ -1673,6 +1673,19 @@ invisible to every check.
`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
@@ -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
@@ -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") + ")");
@@ -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,
];
@@ -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);
}
@@ -61,7 +61,7 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
// 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). Null until the Agent's exception passes one.
// 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, byte[]? toleratedFamilies,
@@ -112,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), null, 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, null, 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), null,
out FlGuardResult r);
FlGuardedInjectWhenReady(checked((uint)targetPid), payloadPath, checked((uint)timeoutMs),
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, null, 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";
}
@@ -50,19 +50,26 @@ public sealed class AntiCheatPreScanSweepTests
public List<string> Scanned { get; } = [];
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) =>
/// <summary>D33: the family each scan named, in order (null for none).</summary>
public List<string?> Tolerated { get; } = [];
/// <summary>D33: the answer to a scan that names a family; <see cref="Answer"/> when unset.</summary>
public AntiCheatVerdict? TolerantAnswer { get; set; }
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) =>
throw new InvalidOperationException("the pre-scan never evaluates a process");
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily, CancellationToken ct = default) =>
throw new InvalidOperationException("the pre-scan never injects");
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, string? toleratedFamily, CancellationToken ct = default) =>
throw new InvalidOperationException("the pre-scan never injects");
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, CancellationToken ct = default)
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily, CancellationToken ct = default)
{
Scanned.Add(executablePath);
return ValueTask.FromResult(Answer);
Tolerated.Add(toleratedFamily);
return ValueTask.FromResult(toleratedFamily is not null && TolerantAnswer is { } tolerant ? tolerant : Answer);
}
}
@@ -103,17 +110,78 @@ public sealed class AntiCheatPreScanSweepTests
public ValueTask<ConsentWriteOutcome> RecordGuardBlockAsync(ExecutableFingerprint fingerprint, AntiCheatVerdict refusal, CancellationToken ct = default) =>
throw new NotSupportedException("the pre-scan writes through RecordPreScanAsync");
/// <summary>D33: every eligibility write, in order.</summary>
public List<(bool Eligible, string? Verdict, int Sessions)> Eligibility { get; } = [];
/// <summary>D33: every exception ended, in order.</summary>
public List<string> Revoked { get; } = [];
public ValueTask<ConsentWriteOutcome> RecordExceptionEligibilityAsync(ExecutableFingerprint scanned, string block, AntiCheatVerdict? verdict, int sessions,
string rulesVersion, CancellationToken ct = default)
{
GameRow row = games.Rows[scanned.ExePath];
if (!string.Equals(row.HookBlockedReason, block, StringComparison.Ordinal))
{
return ValueTask.FromResult(ConsentWriteOutcome.NotFound);
}
bool eligible = verdict is { } v && UserModeExceptionRules.IsEligible(StoredBlock.Parse(block), v, sessions);
string? text = verdict is { } said ? $"{said.Reason}|{said.Family}|{said.Signal}" : null;
Eligibility.Add((eligible, text, sessions));
games.Rows[scanned.ExePath] = row with
{
AcException = row.AcException with
{
Eligible = eligible,
Verdict = text,
Sessions = sessions,
CheckedRulesVersion = rulesVersion,
CheckedExeSizeBytes = scanned.SizeBytes,
CheckedExeMtimeMs = scanned.MtimeUnixMs,
CheckedBlock = block,
},
};
return ValueTask.FromResult(ConsentWriteOutcome.Written);
}
public ValueTask<ConsentWriteOutcome> GrantAntiCheatExceptionAsync(AntiCheatExceptionGrantRequest grant, CancellationToken ct = default) =>
throw new NotSupportedException("the sweep never grants");
public ValueTask<ConsentWriteOutcome> RevokeAntiCheatExceptionAsync(string normalisedExePath, string reason, CancellationToken ct = default)
{
GameRow row = games.Rows[normalisedExePath];
if (!row.AcException.IsGranted)
{
return ValueTask.FromResult(ConsentWriteOutcome.NotFound);
}
Revoked.Add(reason);
games.Rows[normalisedExePath] = row with
{
HookEnabled = row.HookBlockedReason is null && row.HookEnabled,
AcException = row.AcException with { GrantedAt = null, LapsedReason = reason, LapsedAt = DateTimeOffset.UnixEpoch },
};
return ValueTask.FromResult(ConsentWriteOutcome.Written);
}
}
private sealed class Rig : IDisposable
{
public Rig(FakeGameRepository games)
public Rig(FakeGameRepository games, bool exceptions = false)
{
Games = games;
Consent = new LibraryConsent(games);
Sweep = new AntiCheatPreScanSweep(games, Consent, Guard, Rules, Identity, static _ => { }, Pipe, Recording.Contains);
// D33: the exception's evidence and option are composed only where a test is about them.
Sweep = exceptions
? new AntiCheatPreScanSweep(games, Consent, Guard, Rules, Identity, static _ => { }, Pipe, Recording.Contains, Sessions, Option)
: new AntiCheatPreScanSweep(games, Consent, Guard, Rules, Identity, static _ => { }, Pipe, Recording.Contains);
}
public FakeSessionRepository Sessions { get; } = new();
public FakeExceptionSwitch Option { get; } = new();
public AntiCheatPreScanSweep Sweep { get; }
public FakeGameRepository Games { get; }
@@ -260,4 +328,159 @@ public sealed class AntiCheatPreScanSweepTests
(await r.Sweep.WaitAsync(TimeSpan.FromMinutes(5), Ct)).Should().BeTrue();
r.Sweep.Dispose();
}
private const string _yidun = "AntiCheatFile|NetEase Yidun|NEP2.dll";
private static readonly AntiCheatVerdict _letThrough = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll");
/// <summary>D33: a blocked entry, with the exception's evidence and option composed; optionally granted on the bytes on disk.</summary>
private static async Task<Rig> BlockedAsync(string block = _yidun, int sessions = 3, bool granted = false, bool optionOn = true)
{
var games = new FakeGameRepository();
GameRow row = await games.EnsureAsync(new ExecutableFingerprint { ExePath = _exe, SizeBytes = 5, MtimeUnixMs = 5 }, "Title", Ct).ConfigureAwait(false);
games.Rows[_exe] = row with
{
HookBlockedReason = block,
HookPrescanState = "blocked",
HookEnabled = granted,
AcException = granted
? new AntiCheatExceptionState { GrantedAt = DateTimeOffset.UnixEpoch, Family = "NetEase Yidun", ExeSizeBytes = 5, ExeMtimeMs = 5 }
: AntiCheatExceptionState.None,
};
var rig = new Rig(games, exceptions: true);
rig.Sessions.SuccessfulHooked[row.Id] = sessions;
rig.Option.On = optionOn;
rig.Guard.TolerantAnswer = _letThrough;
return rig;
}
/// <summary>
/// D33 (owner decision 2026-09-26): with the option on, a blocked entry is asked one question — a pre-scan NAMING its
/// block's family — and eligible when the guard let exactly that family through and the evidence reaches two sessions.
/// It is never scanned for a new block, and nothing is granted.
/// </summary>
[Fact]
public async Task WithTheOptionOnABlockedEntryIsAskedAboutItsExceptionAndNothingElse()
{
using Rig r = await BlockedAsync();
AntiCheatPreScanReport report = await r.Sweep.SweepOnceAsync(Ct);
report.Blocked.Should().Be(1);
report.Scanned.Should().Be(0, "a block is never scanned for a new one");
report.ExceptionsChecked.Should().Be(1);
r.Guard.Tolerated.Should().Equal("NetEase Yidun");
r.Consent.Writes.Should().BeEmpty("the pre-scan's own columns are not written over a block");
r.Consent.Eligibility.Should().ContainSingle().Which.Should().Be((true, "AllowedUnderUserModeException|NetEase Yidun|NEP2.dll", 3));
r.Games.Rows[_exe].AcException.IsGranted.Should().BeFalse("eligibility grants nothing; the user does, through the disclosure");
r.Games.Rows[_exe].HookBlockedReason.Should().Be(_yidun, "nothing clears a block");
}
[Fact]
public async Task WithTheOptionOffNothingIsAsked()
{
using Rig r = await BlockedAsync(optionOn: false);
(await r.Sweep.SweepOnceAsync(Ct)).ExceptionsChecked.Should().Be(0);
r.Guard.Scanned.Should().BeEmpty("off by default means no exception question is asked of any game");
r.Consent.Eligibility.Should().BeEmpty();
}
/// <summary>The answer is keyed like the pre-scan: rules, executable and the block itself; the count is re-read every pass.</summary>
[Fact]
public async Task TheExceptionQuestionIsKeyedAndTheCountIsLive()
{
using Rig r = await BlockedAsync(sessions: 1);
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Consent.Eligibility.Should().ContainSingle().Which.Eligible.Should().BeFalse("one session is not the owner's two");
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Guard.Scanned.Should().ContainSingle("nothing in the key changed");
r.Consent.Eligibility.Should().ContainSingle("and neither did the answer");
r.Sessions.SuccessfulHooked[r.Games.Rows[_exe].Id] = 2;
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Guard.Scanned.Should().ContainSingle("a new session is counted, not scanned for");
r.Consent.Eligibility[^1].Should().Be((true, "AllowedUnderUserModeException|NetEase Yidun|NEP2.dll", 2));
r.Rules.Version = "2026.09.6";
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Guard.Scanned.Should().HaveCount(2, "new rules may have turned the family kernel-level");
}
[Fact]
public async Task ATitleListBlockIsNeverAskedAndNeverEligible()
{
using Rig r = await BlockedAsync(block: "BlockedStoreId|Valve VAC|steam:730");
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Guard.Scanned.Should().BeEmpty("the notorious titles are on the lists by design");
r.Consent.Eligibility.Should().ContainSingle().Which.Should().Be((false, (string?)null, 3));
}
[Fact]
public async Task AKernelDriverInTheTreeIsNotEligible()
{
using Rig r = await BlockedAsync();
r.Guard.TolerantAnswer = AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "Kernel driver in the game folder", "NEPKernel.sys");
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Consent.Eligibility.Should().ContainSingle().Which.Eligible.Should().BeFalse("the Aniimo shape: D30 is never excepted");
}
/// <summary>A grant made on bytes no longer on disk ends — with the option off too: a game update is not the file the user accepted the risk for.</summary>
[Fact]
public async Task AGrantOnOtherBytesEndsWhateverTheOption()
{
using Rig r = await BlockedAsync(granted: true, optionOn: false);
r.Identity.OnDisk = new ExecutableFingerprint { ExePath = _exe, SizeBytes = 6, MtimeUnixMs = 6 };
AntiCheatPreScanReport report = await r.Sweep.SweepOnceAsync(Ct);
report.ExceptionsEnded.Should().Be(1);
r.Consent.Revoked.Should().Equal(UserModeExceptionLapse.ExecutableChanged);
r.Games.Rows[_exe].HookEnabled.Should().BeFalse("the block stands, so hooking goes off with the exception");
r.Guard.Scanned.Should().BeEmpty("with the option off nothing is asked");
}
[Fact]
public async Task AGrantTheFactsNoLongerSupportEnds()
{
using Rig r = await BlockedAsync(granted: true);
r.Guard.TolerantAnswer = AntiCheatVerdict.Refused(AntiCheatRefusalReason.BlockedModule, "BattlEye", "BEClient_x64.dll");
(await r.Sweep.SweepOnceAsync(Ct)).ExceptionsEnded.Should().Be(1);
r.Consent.Revoked.Should().Equal(UserModeExceptionLapse.NoLongerEligible);
r.Games.Rows[_exe].AcException.LapsedReason.Should().Be(UserModeExceptionLapse.NoLongerEligible);
}
/// <summary>A scan that could not look ends nothing: the session start runs the full check anyway, and a folder busy for one pass is not a finding.</summary>
[Fact]
public async Task AScanThatCouldNotAnswerEndsNoGrant()
{
using Rig r = await BlockedAsync(granted: true);
r.Guard.TolerantAnswer = AntiCheatVerdict.Refused(AntiCheatRefusalReason.PreScanFailed, string.Empty, "the game directory could not be listed");
(await r.Sweep.SweepOnceAsync(Ct)).ExceptionsEnded.Should().Be(0);
r.Consent.Revoked.Should().BeEmpty();
r.Consent.Eligibility.Should().ContainSingle().Which.Eligible.Should().BeFalse();
r.Games.Rows[_exe].AcException.IsGranted.Should().BeTrue();
}
[Fact]
public async Task NoExceptionQuestionWhileItsSessionRuns()
{
using Rig r = await BlockedAsync(granted: true);
r.Recording.Add(r.Games.Rows[_exe].Id);
r.Identity.OnDisk = new ExecutableFingerprint { ExePath = _exe, SizeBytes = 6, MtimeUnixMs = 6 };
_ = await r.Sweep.SweepOnceAsync(Ct);
r.Guard.Scanned.Should().BeEmpty();
r.Consent.Revoked.Should().BeEmpty("the session's own checks are running; the next pass after it ends looks");
}
}
@@ -0,0 +1,17 @@
using FrameLedger.Application.Capture;
namespace FrameLedger.Application.Tests.AntiCheat;
/// <summary>D33: <c>hooking.usermode_ac_exceptions</c> as a test says it is; every read is counted.</summary>
internal sealed class FakeExceptionSwitch(bool on = false) : IUserModeExceptionSwitch
{
public bool On { get; set; } = on;
public int Reads { get; private set; }
public ValueTask<bool> IsOnAsync(CancellationToken ct = default)
{
Reads++;
return ValueTask.FromResult(On);
}
}
@@ -22,24 +22,28 @@ public sealed class HookRequestFromConsentTests
{
public int InjectCalls { get; private set; }
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) =>
/// <summary>D33: the family the last injection named.</summary>
public string? LastTolerated { get; private set; }
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) =>
ValueTask.FromResult(AntiCheatVerdict.Allowed());
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath,
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily,
CancellationToken ct = default)
{
InjectCalls++;
LastTolerated = toleratedFamily;
return ValueTask.FromResult(AntiCheatVerdict.Allowed());
}
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath,
int timeoutMs, CancellationToken ct = default)
int timeoutMs, string? toleratedFamily, CancellationToken ct = default)
{
InjectCalls++;
return ValueTask.FromResult(AntiCheatVerdict.Allowed());
}
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath,
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily,
CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
}
@@ -58,11 +62,30 @@ public sealed class HookRequestFromConsentTests
"unshipped-host-operator/1", blockedReason, preScanUnverified: false,
updatedAt: DateTimeOffset.UnixEpoch);
private static async Task<(AntiCheatVerdict Verdict, int InjectCalls)> ThroughTheGateAsync(
GameConsentRecord record)
private const string _yidunBlock = "AntiCheatFile|NetEase Yidun|NEP2.dll";
/// <summary>D33: a blocked record carrying the user's grant of its user-mode exception, made on <paramref name="grantedOn"/>.</summary>
private static GameConsentRecord Excepted(string family = "NetEase Yidun", string block = _yidunBlock, ExecutableFingerprint? grantedOn = null)
{
RecordingGuard guard = new();
HookRequest request = HookRequest.FromConsent(record, OnDisk, targetPid: 4242, _payload);
ExecutableFingerprint bytes = grantedOn ?? OnDisk;
return GameConsentRecord.Stored(
OnDisk, hookEnabled: true, DateTimeOffset.UnixEpoch, ConsentProvenance.ConsentDialog, "consent-dialog/1", block,
preScanUnverified: false, updatedAt: DateTimeOffset.UnixEpoch,
exception: new AntiCheatExceptionGrant
{
Family = family,
GrantedAt = DateTimeOffset.UnixEpoch,
DisclosureVersion = "ac-exception-dialog/1",
ExeSizeBytes = bytes.SizeBytes,
ExeMtimeUnixMs = bytes.MtimeUnixMs,
});
}
private static async Task<(AntiCheatVerdict Verdict, int InjectCalls)> ThroughTheGateAsync(
GameConsentRecord record, bool exceptionInForce = false, RecordingGuard? recording = null)
{
RecordingGuard guard = recording ?? new();
HookRequest request = HookRequest.FromConsent(record, OnDisk, targetPid: 4242, _payload, exceptionInForce: exceptionInForce);
AntiCheatVerdict verdict = await new HookedCaptureGate(guard)
.StartAsync(request, TestContext.Current.CancellationToken)
.ConfigureAwait(false);
@@ -163,6 +186,57 @@ public sealed class HookRequestFromConsentTests
injectCalls.Should().Be(1);
}
/// <summary>
/// D33 (owner decision 2026-09-26): a blocked game whose user-mode exception is in force for these bytes reaches the
/// guard — naming the family, which the guard alone decides whether to honour — and nothing else about it changes.
/// </summary>
[Fact]
public async Task AnExceptionInForceTakesTheBlockedGameToTheGuardNamingItsFamily()
{
RecordingGuard guard = new();
(AntiCheatVerdict verdict, int injectCalls) = await ThroughTheGateAsync(Excepted(), exceptionInForce: true, guard);
verdict.IsAllowed.Should().BeTrue();
injectCalls.Should().Be(1);
guard.LastTolerated.Should().Be("NetEase Yidun");
HookRequest.FromConsent(Excepted(), OnDisk, 1, _payload, exceptionInForce: true).ToleratedFamily.Should().Be("NetEase Yidun");
}
/// <summary>Every condition narrows: without each one the blocked game is the blocked game of before D33.</summary>
[Fact]
public async Task AnExceptionThatDoesNotApplyIsTheBlockOfBefore()
{
GameConsentRecord[] notApplying =
[
Excepted(grantedOn: OnDisk with { SizeBytes = 1 }),
Excepted(family: "AhnLab HackShield"),
Excepted(block: "BlockedStoreId|NetEase Yidun|steam:1"),
Excepted(block: "AntiCheatFile: NetEase Yidun NEP2.dll"),
];
foreach (GameConsentRecord record in notApplying)
{
(AntiCheatVerdict verdict, int injectCalls) = await ThroughTheGateAsync(record, exceptionInForce: true);
verdict.Reason.Should().Be(AntiCheatRefusalReason.PreviouslyBlocked);
injectCalls.Should().Be(0);
}
(AntiCheatVerdict off, int offCalls) = await ThroughTheGateAsync(Excepted(), exceptionInForce: false);
off.Reason.Should().Be(AntiCheatRefusalReason.PreviouslyBlocked, "the option off, or no channel to the Overlay");
offCalls.Should().Be(0);
}
[Fact]
public async Task AnUnblockedGameNamesNoFamily()
{
RecordingGuard guard = new();
(AntiCheatVerdict verdict, int injectCalls) = await ThroughTheGateAsync(Consented(), exceptionInForce: true, guard);
verdict.IsAllowed.Should().BeTrue();
injectCalls.Should().Be(1);
guard.LastTolerated.Should().BeNull("an exception exists only over a block");
}
[Fact]
public void ThePayloadPathIsRequired()
{
@@ -0,0 +1,76 @@
using FluentAssertions;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
namespace FrameLedger.Application.Tests.AntiCheat;
/// <summary>
/// D33 (owner decision 2026-09-26): the managed half of the user-mode exception can only narrow. A family is named to the
/// guard only when the option is on, a grant is on the row for these bytes, and the block is a module, file or folder
/// finding of that family; a game is eligible only when the guard let exactly that family through and the evidence
/// reaches the owner's two sessions.
/// </summary>
public sealed class UserModeExceptionRulesTests
{
private const string _block = "AntiCheatFile|NetEase Yidun|NEP2.dll";
private static ExecutableFingerprint OnDisk => new() { ExePath = @"C:\Games\GF2\GF2_Exilium.exe", SizeBytes = 10, MtimeUnixMs = 20 };
private static GameConsentRecord Record(string? block = _block, AntiCheatExceptionGrant? grant = null) =>
GameConsentRecord.Stored(OnDisk, hookEnabled: true, DateTimeOffset.UnixEpoch, ConsentProvenance.ConsentDialog, "consent-dialog/1", block,
preScanUnverified: false, DateTimeOffset.UnixEpoch, grant);
private static AntiCheatExceptionGrant Grant(string family = "NetEase Yidun", long size = 10, long mtime = 20) => new()
{
Family = family,
GrantedAt = DateTimeOffset.UnixEpoch,
DisclosureVersion = "ac-exception-dialog/1",
ExeSizeBytes = size,
ExeMtimeUnixMs = mtime,
};
[Fact]
public void TheFamilyIsNamedOnlyWhenEveryConditionHolds()
{
UserModeExceptionRules.CoveredFamily(Record(grant: Grant()), OnDisk, optionOn: true).Should().Be("NetEase Yidun");
UserModeExceptionRules.CoveredFamily(Record(grant: Grant()), OnDisk, optionOn: false).Should().BeNull("off suspends every exception");
UserModeExceptionRules.CoveredFamily(Record(), OnDisk, optionOn: true).Should().BeNull("no grant, no exception");
UserModeExceptionRules.CoveredFamily(Record(grant: Grant(size: 11)), OnDisk, optionOn: true).Should().BeNull("a game update ends it");
UserModeExceptionRules.CoveredFamily(Record(grant: Grant(family: "Anybrain")), OnDisk, optionOn: true).Should().BeNull("the grant is for the block's family");
UserModeExceptionRules.CoveredFamily(Record(block: "BlockedStoreId|NetEase Yidun|steam:1", grant: Grant()), OnDisk, optionOn: true)
.Should().BeNull("a title list is never excepted");
UserModeExceptionRules.CoveredFamily(Record(block: null, grant: Grant()), OnDisk, optionOn: true).Should().BeNull("an exception exists only over a block");
UserModeExceptionRules.CoveredFamily(default, OnDisk, optionOn: true).Should().BeNull("a record nobody stored excepts nothing");
}
[Fact]
public void EligibleMeansTheGuardLetThatFamilyThroughAndTwoSessions()
{
StoredBlock? block = StoredBlock.Parse(_block);
AntiCheatVerdict through = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll");
UserModeExceptionRules.IsEligible(block, through, sessions: 2).Should().BeTrue();
UserModeExceptionRules.IsEligible(block, through, sessions: 1).Should().BeFalse("the owner's threshold is two");
UserModeExceptionRules.IsEligible(block, AntiCheatVerdict.Allowed(), sessions: 3).Should().BeFalse("a plain pass let nothing through, so it confirmed nothing");
UserModeExceptionRules.IsEligible(block, AntiCheatVerdict.AllowedUnderException("Anybrain", "x.dll"), sessions: 3).Should().BeFalse();
UserModeExceptionRules.IsEligible(block, AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "Kernel driver in the game folder", "NEPKernel.sys"),
sessions: 3).Should().BeFalse("the Aniimo shape");
UserModeExceptionRules.IsEligible(StoredBlock.Parse("BlockedExecutable|Valve VAC|cs2.exe"), through, sessions: 3).Should().BeFalse();
UserModeExceptionRules.IsEligible(null, through, sessions: 3).Should().BeFalse();
UserModeExceptionRules.RequiredSessions.Should().Be(2);
}
[Fact]
public void AStoredBlockIsReadOnlyInItsThreeSlotShape()
{
StoredBlock.Parse(_block).Should().Be(new StoredBlock(AntiCheatRefusalReason.AntiCheatFile, "NetEase Yidun", "NEP2.dll"));
StoredBlock.Parse("AntiCheatFile: NetEase Yidun NEP2.dll").Should().BeNull("a row from before 2026-09-25 cannot be split back apart");
StoredBlock.Parse("3|NetEase Yidun|NEP2.dll").Should().BeNull("a number is not a reason's name");
StoredBlock.Parse("antichEatfile|NetEase Yidun|NEP2.dll").Should().BeNull("names are exact");
StoredBlock.Parse(null).Should().BeNull();
StoredBlock.Parse("AntiCheatDirectory|NetEase Yidun|Yidun|x")!.Value.Signal.Should().Be("Yidun|x", "the signal is the last slot");
new StoredBlock(AntiCheatRefusalReason.BlockedModule, string.Empty, "x.dll").IsExceptionable.Should().BeFalse("a finding that names no family");
}
}
@@ -52,10 +52,10 @@ public sealed class CaptureSessionLaunchTests : IAsyncDisposable
public AntiCheatVerdict Verdict { get; set; } = AntiCheatVerdict.Allowed();
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) =>
ValueTask.FromResult(AntiCheatVerdict.Allowed());
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath,
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily,
CancellationToken ct = default)
{
InjectCalls++;
@@ -63,14 +63,14 @@ public sealed class CaptureSessionLaunchTests : IAsyncDisposable
}
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath,
int timeoutMs, CancellationToken ct = default)
int timeoutMs, string? toleratedFamily, CancellationToken ct = default)
{
WhenReadyCalls++;
WhenReadyWaitMs = timeoutMs;
return ValueTask.FromResult(Verdict);
}
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath,
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily,
CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
}
@@ -3,8 +3,11 @@ using FluentAssertions;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Consent;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Tests.AntiCheat;
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
using FrameLedger.Domain.Sessions;
using FrameLedger.Infrastructure.Persistence;
using FrameLedger.Shared;
@@ -72,9 +75,18 @@ public sealed class CaptureSessionTests : IAsyncDisposable
/// <summary>Throw only from the Nth evaluation onward, so the first scan can succeed.</summary>
public int EvaluateThrowsAfter { get; set; } = int.MaxValue;
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default)
/// <summary>D33: the family each injection and each re-scan named, in order.</summary>
public List<string?> InjectTolerated { get; } = [];
public List<string?> EvaluateTolerated { get; } = [];
/// <summary>D33: where "inject" is written, beside the tolerance channel's "publish-tolerance", so their order is observable.</summary>
public List<string>? Events { get; init; }
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default)
{
EvaluateCalls++;
EvaluateTolerated.Add(toleratedFamily);
if (EvaluateThrows is not null || EvaluateCalls > EvaluateThrowsAfter)
{
return ValueTask.FromException<AntiCheatVerdict>(
@@ -84,21 +96,23 @@ public sealed class CaptureSessionTests : IAsyncDisposable
return ValueTask.FromResult(EvaluateVerdict);
}
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath,
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily,
CancellationToken ct = default)
{
InjectCalls++;
InjectTolerated.Add(toleratedFamily);
Events?.Add("inject");
return ValueTask.FromResult(Verdict);
}
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath,
int timeoutMs, CancellationToken ct = default)
int timeoutMs, string? toleratedFamily, CancellationToken ct = default)
{
InjectCalls++;
return ValueTask.FromResult(Verdict);
}
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath,
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily,
CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
}
@@ -173,6 +187,26 @@ public sealed class CaptureSessionTests : IAsyncDisposable
}
}
/// <summary>D33: the Overlay's channel, recording what was published, in the order <see cref="CountingGuard.Events"/> keeps.</summary>
private sealed class FakeToleranceChannel(List<string> events, bool works = true) : IOverlayToleranceChannel
{
public List<(int Pid, string Family)> Published { get; } = [];
public int Disposed { get; private set; }
public IDisposable? TryPublish(int pid, string family)
{
events.Add("publish-tolerance");
Published.Add((pid, family));
return works ? new Held(this) : null;
}
private sealed class Held(FakeToleranceChannel owner) : IDisposable
{
public void Dispose() => owner.Disposed++;
}
}
private sealed class FakeLiveness : ITargetLiveness
{
private int _foregroundSamples = int.MaxValue;
@@ -272,7 +306,8 @@ public sealed class CaptureSessionTests : IAsyncDisposable
private static CaptureSession Loop(IGameConsentStore store, CountingGuard guard, FakeSink? sink,
FakeLiveness? alive = null, int? pid = _pid, SessionEndReason resolveReason = SessionEndReason.Running,
CaptureOptions? options = null, IKillSwitch? killSwitch = null, ICapturePauseSource? pause = null) =>
CaptureOptions? options = null, IKillSwitch? killSwitch = null, ICapturePauseSource? pause = null,
IUserModeExceptionSwitch? exceptions = null, IOverlayToleranceChannel? tolerance = null) =>
new(store,
new HookedCaptureGate(guard),
guard,
@@ -289,7 +324,9 @@ public sealed class CaptureSessionTests : IAsyncDisposable
LogFlushGrace = TimeSpan.FromMilliseconds(1),
},
killSwitch: killSwitch,
pause: pause);
pause: pause,
exceptions: exceptions,
tolerance: tolerance);
private static readonly bool[] _pauseThenResume = [true, false];
@@ -987,7 +1024,7 @@ public sealed class CaptureSessionTests : IAsyncDisposable
/// <summary>The loop with an explicit resolver and liveness: the Tier-2 hold's two clocks (2026-09-22).</summary>
private static CaptureSession With(IGameConsentStore store, CountingGuard guard, FixedResolver resolver, FakeLiveness? alive = null,
ICaptureObserver? observer = null, bool hold = true) =>
ICaptureObserver? observer = null, bool hold = true, IUserModeExceptionSwitch? exceptions = null, IOverlayToleranceChannel? tolerance = null) =>
new(store, new HookedCaptureGate(guard), guard, resolver,
new DelegateLivenessSource(_ => alive ?? new FakeLiveness()),
new DelegateRingAttacher(_ => (null, ShmAttachRefusal.BuildIdMismatch)),
@@ -998,7 +1035,9 @@ public sealed class CaptureSessionTests : IAsyncDisposable
MaxDuration = TimeSpan.FromSeconds(5),
AttachBudget = TimeSpan.FromMilliseconds(20),
},
observer: observer);
observer: observer,
exceptions: exceptions,
tolerance: tolerance);
/// <summary>
/// Tier 2 as a session (2026-09-22; <c>04_CAPTURE</c> §Tier selection): a row whose hooking is off is decided BEFORE the
@@ -1102,4 +1141,138 @@ public sealed class CaptureSessionTests : IAsyncDisposable
r.Reason.Should().Be(SessionEndReason.RefusedByGuard);
r.HeldUnhooked.Should().BeFalse("HoldUnhooked = false returns the refusal at once");
}
private const string _yidunBlock = "AntiCheatFile|NetEase Yidun|NEP2.dll";
/// <summary>
/// D33: the row as the owner's GIRLS' FRONTLINE 2 would be under its exception — consented, blocked for NetEase Yidun,
/// the exception granted on these bytes, and hooking turned on again through FR-2.1 — written through the real store.
/// </summary>
private async Task<IGameConsentStore> ExceptedStoreAsync()
{
CancellationToken ct = TestContext.Current.CancellationToken;
IGameConsentStore store = await StoreWithAsync().ConfigureAwait(false);
await store.RecordGuardBlockAsync(Fingerprint, AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "NetEase Yidun", "NEP2.dll"), ct)
.ConfigureAwait(false);
(await store.GrantAntiCheatExceptionAsync(new AntiCheatExceptionGrantRequest
{
Fingerprint = Fingerprint,
Block = _yidunBlock,
Verdict = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll"),
Sessions = 3,
DisclosureVersion = "ac-exception-dialog/1",
GrantedAt = DateTimeOffset.UnixEpoch,
}, ct).ConfigureAwait(false)).Should().Be(ConsentWriteOutcome.Written);
(await store.RecordOperatorAcknowledgementAsync(new OperatorAcknowledgement
{
Fingerprint = Fingerprint,
DisclosureVersion = _disclosure,
AcknowledgedAt = DateTimeOffset.UnixEpoch,
}, ct).ConfigureAwait(false)).Should().Be(ConsentWriteOutcome.Written);
GameConsentRecord record = await store.FindAsync(_exe, ct).ConfigureAwait(false);
record.HookEnabled.Should().BeTrue();
record.BlockedReason.Should().Be(_yidunBlock, "the exception is a layer over the block, never its clearing");
return store;
}
/// <summary>
/// D33 (owner decision 2026-09-26): under its exception the Overlay's channel is published BEFORE the injection — the
/// Overlay reads it before its loader detour exists — the injection and every re-scan name the family, and the channel
/// is let go with the session.
/// </summary>
[Fact]
public async Task UnderItsExceptionTheOverlayIsToldFirstAndEveryScanNamesTheFamily()
{
var events = new List<string>();
var guard = new CountingGuard
{
Verdict = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll"),
EvaluateVerdict = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll"),
Events = events,
};
using var sink = new FakeSink();
var channel = new FakeToleranceChannel(events);
CaptureSession loop = Loop(await ExceptedStoreAsync(), guard, sink, exceptions: new FakeExceptionSwitch(on: true), tolerance: channel);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.ExceptionFamily.Should().Be("NetEase Yidun");
r.AttachRefusal.Should().Be(ShmAttachRefusal.Ok);
channel.Published.Should().Equal((_pid, "NetEase Yidun"));
events.IndexOf("publish-tolerance").Should().BeLessThan(events.IndexOf("inject"), "a channel published after the injection is read by nobody");
guard.InjectTolerated.Should().Equal("NetEase Yidun");
guard.EvaluateTolerated.Should().NotBeEmpty().And.OnlyContain(static f => f == "NetEase Yidun");
channel.Disposed.Should().BeGreaterThan(0, "the channel is held for the session and let go with it");
}
[Fact]
public async Task WithTheOptionOffTheBlockedGameIsHookingOffAndItsProcessIsNeverOpened()
{
var guard = new CountingGuard();
var resolver = new FixedResolver(_pid, SessionEndReason.Running, runningTicks: 1);
var channel = new FakeToleranceChannel([]);
CaptureSession loop = With(await ExceptedStoreAsync(), guard, resolver, exceptions: new FakeExceptionSwitch(on: false), tolerance: channel);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.Verdict.Reason.Should().Be(AntiCheatRefusalReason.PreviouslyBlocked, "off suspends the exception, and the block is what is left");
resolver.ResolveCalls.Should().Be(0, "hook_enabled is 1 only because the exception once applied; without it this is a hooking-off row");
guard.InjectCalls.Should().Be(0);
channel.Published.Should().BeEmpty();
r.ExceptionFamily.Should().BeNull();
}
[Fact]
public async Task ABlockedGameOnOtherBytesIsHookingOff()
{
var guard = new CountingGuard();
var resolver = new FixedResolver(_pid, SessionEndReason.Running, runningTicks: 1);
CaptureSession loop = With(await ExceptedStoreAsync(), guard, resolver, exceptions: new FakeExceptionSwitch(on: true), tolerance: new FakeToleranceChannel([]));
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint with { SizeBytes = 1 }, "payload.dll", TestContext.Current.CancellationToken);
r.Verdict.Reason.Should().Be(AntiCheatRefusalReason.PreviouslyBlocked, "a game update is not the file the user accepted the risk for");
guard.InjectCalls.Should().Be(0);
resolver.ResolveCalls.Should().Be(0);
}
/// <summary>A channel that could not be published is no exception: the guard is asked nothing, and the game is refused as blocked.</summary>
[Fact]
public async Task AChannelThatCannotBePublishedIsNoException()
{
var guard = new CountingGuard();
using var sink = new FakeSink();
var channel = new FakeToleranceChannel([], works: false);
CaptureSession loop = Loop(await ExceptedStoreAsync(), guard, sink, exceptions: new FakeExceptionSwitch(on: true), tolerance: channel);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
channel.Published.Should().ContainSingle("it was tried");
r.Reason.Should().Be(SessionEndReason.RefusedPreviouslyBlocked);
guard.InjectCalls.Should().Be(0, "injecting while the Overlay would stop on the family's module would read as the exception failing");
r.ExceptionFamily.Should().BeNull();
}
/// <summary>
/// A finding about the game at the start of a session under the exception is written as the block, as every finding is,
/// and the outcome names the exception it ran under — the recorder's policy ends the exception on it.
/// </summary>
[Fact]
public async Task AStartTimeFindingUnderTheExceptionIsTheBlockAndEndsTheException()
{
var guard = new CountingGuard { Verdict = AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "Kernel driver in the game folder", "NEPKernel.sys") };
using var sink = new FakeSink();
var channel = new FakeToleranceChannel([]);
IGameConsentStore store = await ExceptedStoreAsync();
CaptureOutcome r = await Loop(store, guard, sink, exceptions: new FakeExceptionSwitch(on: true), tolerance: channel)
.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.Reason.Should().Be(SessionEndReason.RefusedByGuard);
r.HookingTurnedOff.Should().BeTrue();
r.ExceptionFamily.Should().Be("NetEase Yidun");
UserModeExceptionLapsePolicy.LapseOf(r, ExitStatus.Normal).Should().Be(UserModeExceptionLapse.NewFinding);
channel.Disposed.Should().BeGreaterThan(0);
(await store.FindAsync(_exe, TestContext.Current.CancellationToken)).BlockedReason.Should().Contain("NEPKernel.sys");
}
}
@@ -22,28 +22,51 @@ public sealed class GuardSupervisorTests
public Func<AntiCheatVerdict>? OnEvaluate { get; set; }
public int Calls { get; private set; }
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default)
/// <summary>D33: the family each re-scan named.</summary>
public List<string?> Tolerated { get; } = [];
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default)
{
Calls++;
Tolerated.Add(toleratedFamily);
ct.ThrowIfCancellationRequested();
return ValueTask.FromResult(OnEvaluate is null ? AntiCheatVerdict.Allowed() : OnEvaluate());
}
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath,
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily,
CancellationToken ct = default) =>
ValueTask.FromResult(AntiCheatVerdict.Allowed());
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath,
int timeoutMs, CancellationToken ct = default) =>
int timeoutMs, string? toleratedFamily, CancellationToken ct = default) =>
throw new InvalidOperationException("the supervisor must not launch or inject");
// The supervisor never asks check 4 anything: it re-evaluates a process
// it is already inside, and the pre-scan is the pre-launch question.
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath,
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily,
CancellationToken ct = default) =>
throw new InvalidOperationException("the supervisor must not call the pre-scan");
}
/// <summary>
/// D33: a session under a user-mode exception names the same family to every re-scan, and the guard's answer is judged
/// as ever — an allow under the exception continues, anything else latches the unhook.
/// </summary>
[Fact]
public async Task EveryReScanNamesTheSessionsFamilyAndAnyRefusalStillUnhooks()
{
ScriptedGuard guard = new() { OnEvaluate = static () => AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll") };
GuardSupervisor supervisor = new(guard, "NetEase Yidun");
(await supervisor.ScanOnceAsync(1234, TestContext.Current.CancellationToken)).Should().BeTrue();
guard.OnEvaluate = static () => AntiCheatVerdict.Refused(AntiCheatRefusalReason.BlockedModule, "BattlEye", "BEClient_x64.dll");
(await supervisor.ScanOnceAsync(1234, TestContext.Current.CancellationToken)).Should().BeFalse();
guard.Tolerated.Should().Equal("NetEase Yidun", "NetEase Yidun");
supervisor.UnhookRequested.Should().BeTrue();
new GuardSupervisor(guard).ToleratedFamily.Should().BeNull("every other session names none");
}
[Fact]
public async Task ACompletedCleanScan_AdvancesTheTick()
{
@@ -13,13 +13,14 @@ public sealed class HookedCaptureGateTests
public int InjectCalls { get; private set; }
public AntiCheatVerdict Next { get; set; } = AntiCheatVerdict.Allowed();
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) =>
ValueTask.FromResult(Next);
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath,
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily,
CancellationToken ct = default)
{
InjectCalls++;
Tolerated.Add(toleratedFamily);
return ValueTask.FromResult(Next);
}
@@ -27,17 +28,21 @@ public sealed class HookedCaptureGateTests
public int WhenReadyWaitMs { get; private set; }
/// <summary>D33: the family each injecting entry was asked to tolerate, in order.</summary>
public List<string?> Tolerated { get; } = [];
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath,
int timeoutMs, CancellationToken ct = default)
int timeoutMs, string? toleratedFamily, CancellationToken ct = default)
{
WhenReadyCalls++;
WhenReadyWaitMs = timeoutMs;
Tolerated.Add(toleratedFamily);
return ValueTask.FromResult(Next);
}
public int PreScanCalls { get; private set; }
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath,
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily,
CancellationToken ct = default)
{
PreScanCalls++;
@@ -95,6 +100,45 @@ public sealed class HookedCaptureGateTests
guard.InjectCalls.Should().Be(1);
}
/// <summary>
/// D33 (owner decision 2026-09-26): a blocked game under its user-mode exception reaches the guard through BOTH entries
/// with the family named, and the guard's answer is the gate's — the gate adds no judgement of its own.
/// </summary>
[Fact]
public async Task ABlockedGameUnderItsExceptionReachesTheGuardThroughBothEntriesNamingTheFamily()
{
var guard = new RecordingGuard { Next = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll") };
var gate = new HookedCaptureGate(guard);
CancellationToken ct = TestContext.Current.CancellationToken;
GameConsentRecord record = GameConsentRecord.Stored(
OnDisk, hookEnabled: true, DateTimeOffset.UnixEpoch, ConsentProvenance.ConsentDialog, "consent-dialog/1",
"AntiCheatFile|NetEase Yidun|NEP2.dll", preScanUnverified: false, updatedAt: DateTimeOffset.UnixEpoch,
exception: new AntiCheatExceptionGrant
{
Family = "NetEase Yidun",
GrantedAt = DateTimeOffset.UnixEpoch,
DisclosureVersion = "ac-exception-dialog/1",
ExeSizeBytes = OnDisk.SizeBytes,
ExeMtimeUnixMs = OnDisk.MtimeUnixMs,
});
AntiCheatVerdict attach = await gate.StartAsync(HookRequest.FromConsent(record, OnDisk, 1234, @"C:\FrameLedger\FrameLedger.Overlay.dll",
exceptionInForce: true), ct);
AntiCheatVerdict launch = await gate.StartAsync(HookRequest.FromConsent(record, OnDisk, 1234, @"C:\FrameLedger\FrameLedger.Overlay.dll",
waitForPresentationRuntimeMs: 60_000, exceptionInForce: true), ct);
attach.RanUnderException.Should().BeTrue();
launch.RanUnderException.Should().BeTrue();
guard.Tolerated.Should().Equal("NetEase Yidun", "NetEase Yidun");
guard.Next = AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "Kernel driver in the game folder", "NEPKernel.sys");
(await gate.StartAsync(HookRequest.FromConsent(record, OnDisk, 1234, @"C:\FrameLedger\FrameLedger.Overlay.dll", exceptionInForce: true), ct))
.Reason.Should().Be(AntiCheatRefusalReason.AntiCheatFile, "the guard's refusal is the gate's answer, exception or not");
(await gate.StartAsync(Request(), ct)).IsAllowed.Should().BeFalse("Next is still the refusal");
guard.Tolerated[^1].Should().BeNull("an unblocked game names no family");
}
[Fact]
public async Task AnEnabledConsentedGame_ReachesTheGuard()
{
@@ -7,6 +7,7 @@ using FrameLedger.Application.Detection;
using FrameLedger.Application.Ipc;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Tests.AntiCheat;
using FrameLedger.Application.Tests.Recording;
using FrameLedger.Application.Watch;
using FrameLedger.Domain.AntiCheat;
@@ -55,18 +56,24 @@ public sealed class AgentCommandHandlerTests : IAsyncDisposable
public List<string> Scanned { get; } = [];
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
/// <summary>D33: the family each pre-scan named (null for none), and the answer to one that names a family.</summary>
public List<string?> Tolerated { get; } = [];
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, CancellationToken ct = default) =>
public AntiCheatVerdict TolerantPreScan { get; set; } = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll");
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily, CancellationToken ct = default) =>
throw new InvalidOperationException("a command never injects");
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, string? toleratedFamily, CancellationToken ct = default) =>
throw new InvalidOperationException("a command never injects");
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, CancellationToken ct = default)
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily, CancellationToken ct = default)
{
Scanned.Add(executablePath);
return ValueTask.FromResult(PreScan);
Tolerated.Add(toleratedFamily);
return ValueTask.FromResult(toleratedFamily is null ? PreScan : TolerantPreScan);
}
}
@@ -128,6 +135,11 @@ public sealed class AgentCommandHandlerTests : IAsyncDisposable
public required FakeLifetime Lifetime { get; init; }
public int RulesUpdates { get; set; }
/// <summary>D33: the exception's evidence and option, when the harness composes the exception.</summary>
public required FakeSessionRepository Sessions { get; init; }
public required FakeExceptionSwitch Option { get; init; }
}
/// <summary>What the executable runs as, scripted (beta.8).</summary>
@@ -143,7 +155,7 @@ public sealed class AgentCommandHandlerTests : IAsyncDisposable
}
private async Task<Harness> BuildAsync(bool consented = true, string? disclosureVersion = null, Func<CancellationToken, ValueTask<SweepRetentionAck>>? sweep = null,
IExecutableArchitectureSource? architecture = null)
IExecutableArchitectureSource? architecture = null, bool exceptions = false)
{
_db ??= await LedgerDatabase.OpenAsync(Path.Combine(_dir, LedgerPaths.DatabaseFileName), ct: Ct).ConfigureAwait(false);
var consent = new SqliteGameConsentStore(_db);
@@ -166,9 +178,12 @@ public sealed class AgentCommandHandlerTests : IAsyncDisposable
var orchestrator = new CaptureOrchestrator(new FakeRecorder(), games, new FakeSnapshots(), identity,
new OrchestratorOptions { PayloadPath = @"C:\FL\FrameLedger.Overlay.dll" }, static _ => { });
Harness h = null!;
var sessions = new FakeSessionRepository();
var option = new FakeExceptionSwitch(on: true);
var handler = new AgentCommandHandler(games, consent, guard, identity, orchestrator, pause, lifetime,
_ => { h.RulesUpdates++; return ValueTask.FromResult("AlreadyCurrent"); },
disclosureVersion, new FakeClock(), sweepRetention: sweep, architecture: architecture);
disclosureVersion, new FakeClock(), sweepRetention: sweep, architecture: architecture,
exceptions: exceptions ? new AntiCheatExceptionCommands(option, sessions, _exceptionDisclosure) : null);
h = new Harness
{
Handler = handler,
@@ -179,6 +194,8 @@ public sealed class AgentCommandHandlerTests : IAsyncDisposable
Orchestrator = orchestrator,
Pause = pause,
Lifetime = lifetime,
Sessions = sessions,
Option = option,
};
return h;
}
@@ -468,4 +485,149 @@ public sealed class AgentCommandHandlerTests : IAsyncDisposable
Encoding.UTF8.GetString(IpcCodec.Encode(IpcMessageType.Ping, "9")).Should().NotContain("payload");
}
private const string _exceptionDisclosure = "ac-exception-dialog/1";
private const string _yidunBlock = "AntiCheatFile|NetEase Yidun|NEP2.dll";
/// <summary>D33: the owner's GIRLS' FRONTLINE 2 as beta.8 left it — consented, then blocked for NetEase Yidun — on both views of the row.</summary>
private async Task<Harness> BlockedAsync(int sessions = 3, string block = _yidunBlock, string? disclosureVersion = null)
{
Harness h = await BuildAsync(disclosureVersion: disclosureVersion, exceptions: true).ConfigureAwait(false);
StoredBlock parsed = StoredBlock.Parse(block)!.Value;
await h.Consent.RecordGuardBlockAsync(h.Identity.Read(_exe)!.Value, AntiCheatVerdict.Refused(parsed.Reason, parsed.Family, parsed.Signal), Ct)
.ConfigureAwait(false);
GameRow row = h.Games.Rows[_exe];
h.Games.Rows[_exe] = row with { HookBlockedReason = block, HookPrescanState = "blocked", HookEnabled = false };
h.Sessions.SuccessfulHooked[row.Id] = sessions;
return h;
}
private static SetAntiCheatExceptionRequest Grant(Harness h, string? version = _exceptionDisclosure) => new(h.Games.Rows[_exe].Id, true, version);
/// <summary>
/// D33 (owner decision 2026-09-26): the Agent grants against its own disclosure version and only while the option is on —
/// otherwise nothing is scanned and nothing is written.
/// </summary>
[Fact]
public async Task AGrantNeedsTheAgentsDisclosureAndTheOptionOn()
{
Harness h = await BlockedAsync().ConfigureAwait(true);
IpcEnvelope stale = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException, Grant(h, "ac-exception-dialog/0")).ConfigureAwait(true);
stale.Type.Should().Be(IpcMessageType.Error);
IpcCodec.Payload<ErrorAck>(stale)!.Code.Should().Be(IpcErrorCode.DisclosureVersionMismatch);
h.Option.On = false;
IpcEnvelope off = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException, Grant(h)).ConfigureAwait(true);
IpcCodec.Payload<ErrorAck>(off)!.Code.Should().Be(IpcErrorCode.ExceptionsOff);
h.Guard.Scanned.Should().BeEmpty();
(await h.Consent.FindAsync(_exe, Ct).ConfigureAwait(true)).Exception.Should().BeNull();
}
/// <summary>The facts are the Agent's own — a tolerant pre-scan of the file on disk, the session count — and a grant turns nothing on.</summary>
[Fact]
public async Task AGrantRestsOnFactsTheAgentGathersAndTurnsNothingOn()
{
Harness h = await BlockedAsync().ConfigureAwait(true);
IpcEnvelope ack = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException, Grant(h)).ConfigureAwait(true);
ack.Type.Should().Be(IpcMessageType.AntiCheatExceptionAck);
IpcCodec.Payload<AntiCheatExceptionAck>(ack).Should().Be(new AntiCheatExceptionAck(h.Games.Rows[_exe].Id, true, "Written", "NetEase Yidun"));
h.Guard.Tolerated.Should().Equal("NetEase Yidun");
GameConsentRecord after = await h.Consent.FindAsync(_exe, Ct).ConfigureAwait(true);
after.Exception.Should().NotBeNull();
after.Exception!.Value.Family.Should().Be("NetEase Yidun");
after.Exception.Value.DisclosureVersion.Should().Be(_exceptionDisclosure);
after.HookEnabled.Should().BeFalse("turning hooking on is FR-2.1's dialog, afterwards");
after.BlockedReason.Should().Be(_yidunBlock, "nothing clears a block");
}
[Fact]
public async Task TooFewSessionsATitleListOrAGuardThatLetsNothingThroughIsRefused()
{
Harness one = await BlockedAsync(sessions: 1).ConfigureAwait(true);
IpcEnvelope few = await AskAsync(one.Handler, IpcMessageType.SetAntiCheatException, Grant(one)).ConfigureAwait(true);
few.Type.Should().Be(IpcMessageType.Refused);
IpcCodec.Payload<RefusedAck>(few).Should().Be(new RefusedAck(one.Games.Rows[_exe].Id, AgentCommandHandler.TooFewSessionsReason, "NetEase Yidun", "1"));
one.Guard.TolerantPreScan = AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "Kernel driver in the game folder", "NEPKernel.sys");
one.Sessions.SuccessfulHooked[one.Games.Rows[_exe].Id] = 3;
RefusedAck driver = IpcCodec.Payload<RefusedAck>(await AskAsync(one.Handler, IpcMessageType.SetAntiCheatException, Grant(one)).ConfigureAwait(true))!;
driver.Reason.Should().Be(nameof(AntiCheatRefusalReason.AntiCheatFile), "the Aniimo shape: D30 is never excepted");
driver.Signal.Should().Be("NEPKernel.sys");
(await one.Consent.FindAsync(_exe, Ct).ConfigureAwait(true)).Exception.Should().BeNull();
}
[Fact]
public async Task ATitleListIsNeverAsked()
{
Harness h = await BlockedAsync(block: "BlockedStoreId|Valve VAC|steam:730").ConfigureAwait(true);
IpcEnvelope ack = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException, Grant(h)).ConfigureAwait(true);
IpcCodec.Payload<RefusedAck>(ack)!.Reason.Should().Be(AgentCommandHandler.BlockNotExceptionableReason);
h.Guard.Scanned.Should().BeEmpty();
}
/// <summary>
/// Under an exception in force, turning hooking on is FR-2.1's stamp as ever — the pre-scan naming the family, the stamp
/// made on the Agent's clock — and the block stays on the row.
/// </summary>
[Fact]
public async Task UnderTheExceptionTurningHookingOnNamesTheFamilyAndStamps()
{
Harness h = await BlockedAsync(disclosureVersion: "consent-dialog/1").ConfigureAwait(true);
_ = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException, Grant(h)).ConfigureAwait(true);
IpcEnvelope ack = await AskAsync(h.Handler, IpcMessageType.SetHookEnabled,
new SetHookEnabledRequest(h.Games.Rows[_exe].Id, true, "consent-dialog/1")).ConfigureAwait(true);
ack.Type.Should().Be(IpcMessageType.HookEnabledAck);
HookEnabledAck payload = IpcCodec.Payload<HookEnabledAck>(ack)!;
payload.Enabled.Should().BeTrue();
payload.Prescan.Should().Be("exception");
h.Guard.Tolerated[^1].Should().Be("NetEase Yidun");
GameConsentRecord after = await h.Consent.FindAsync(_exe, Ct).ConfigureAwait(true);
after.HookEnabled.Should().BeTrue();
after.BlockedReason.Should().Be(_yidunBlock);
// With the option off the family is named to nobody, and the strict pre-scan finds it as it always did.
h.Option.On = false;
h.Guard.PreScan = AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "NetEase Yidun", "NEP2.dll");
IpcEnvelope suspended = await AskAsync(h.Handler, IpcMessageType.SetHookEnabled,
new SetHookEnabledRequest(h.Games.Rows[_exe].Id, true, "consent-dialog/1")).ConfigureAwait(true);
suspended.Type.Should().Be(IpcMessageType.Refused);
h.Guard.Tolerated[^1].Should().BeNull();
}
[Fact]
public async Task WithdrawingEndsTheExceptionAndTurnsHookingOff()
{
Harness h = await BlockedAsync(disclosureVersion: "consent-dialog/1").ConfigureAwait(true);
_ = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException, Grant(h)).ConfigureAwait(true);
_ = await AskAsync(h.Handler, IpcMessageType.SetHookEnabled, new SetHookEnabledRequest(h.Games.Rows[_exe].Id, true, "consent-dialog/1")).ConfigureAwait(true);
IpcEnvelope ack = await AskAsync(h.Handler, IpcMessageType.SetAntiCheatException,
new SetAntiCheatExceptionRequest(h.Games.Rows[_exe].Id, false, null)).ConfigureAwait(true);
IpcCodec.Payload<AntiCheatExceptionAck>(ack)!.Granted.Should().BeFalse();
GameConsentRecord after = await h.Consent.FindAsync(_exe, Ct).ConfigureAwait(true);
after.Exception.Should().BeNull();
after.HookEnabled.Should().BeFalse("the block stands, so hooking goes off with the exception");
after.ConsentedAt.Should().NotBeNull("the consent stamp is kept, as a block keeps it");
}
[Fact]
public async Task WithoutTheExceptionComposedTheCommandIsNotAnswered()
{
Harness h = await BuildAsync().ConfigureAwait(true);
byte[]? ack = await h.Handler.HandleAsync(IpcCodec.Decode(IpcCodec.Encode(IpcMessageType.SetAntiCheatException, "1",
new SetAntiCheatExceptionRequest(h.Games.Rows[_exe].Id, true, _exceptionDisclosure))), Ct).ConfigureAwait(true);
ack.Should().BeNull("an Agent composed without the exception answers UnknownType");
}
}
@@ -91,6 +91,12 @@ internal sealed class FakeSessionRepository : ISessionRepository
public ValueTask<long> CountSinceAsync(DateTimeOffset since, CancellationToken ct = default) =>
ValueTask.FromResult((long)Stored.Count(s => s.Row.StartedAt >= since));
/// <summary>D33: each game's successful Tier-1 sessions, as the tests say; a game not named has none.</summary>
public Dictionary<long, int> SuccessfulHooked { get; } = [];
public ValueTask<int> CountSuccessfulHookedAsync(long gameId, CancellationToken ct = default) =>
ValueTask.FromResult(SuccessfulHooked.GetValueOrDefault(gameId));
public ValueTask<IReadOnlyList<SegmentRow>> FindSegmentsAsync(long sessionId, CancellationToken ct = default) =>
ValueTask.FromResult(sessionId >= 1 && sessionId <= Stored.Count ? Stored[(int)sessionId - 1].Segments : []);
@@ -6,6 +6,7 @@ using FrameLedger.Application.Consent;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Telemetry;
using FrameLedger.Application.Tests.AntiCheat;
using FrameLedger.Application.Tests.Capture;
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
@@ -69,14 +70,14 @@ public sealed class SessionRecorderTests : IAsyncDisposable
{
public AntiCheatVerdict Verdict { get; set; } = AntiCheatVerdict.Allowed();
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, CancellationToken ct = default) => ValueTask.FromResult(Verdict);
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily, CancellationToken ct = default) => ValueTask.FromResult(Verdict);
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> GuardedInjectWhenReadyAsync(int targetPid, string payloadPath, int timeoutMs, string? toleratedFamily, CancellationToken ct = default) =>
ValueTask.FromResult(Verdict);
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, CancellationToken ct = default) =>
public ValueTask<AntiCheatVerdict> PreScanGameAsync(string executablePath, string? toleratedFamily, CancellationToken ct = default) =>
ValueTask.FromResult(AntiCheatVerdict.Allowed());
}
@@ -182,7 +183,14 @@ public sealed class SessionRecorderTests : IAsyncDisposable
}
}
private sealed class Factory(IGameConsentStore store, FakeGuard guard, SteppingClock clock, int records, FakeLiveness liveness) : ICaptureSessionFactory
/// <summary>D33: the Overlay's channel, always published.</summary>
private sealed class OpenChannel : IOverlayToleranceChannel
{
public IDisposable? TryPublish(int pid, string family) => new MemoryStream();
}
private sealed class Factory(IGameConsentStore store, FakeGuard guard, SteppingClock clock, int records, FakeLiveness liveness,
IUserModeExceptionSwitch? exceptions = null) : ICaptureSessionFactory
{
public CaptureSession Create(ICaptureObserver observer) => new(
store, new HookedCaptureGate(guard), guard, new FixedResolver(),
@@ -197,7 +205,9 @@ public sealed class SessionRecorderTests : IAsyncDisposable
LogFlushGrace = TimeSpan.FromMilliseconds(1),
HoldInterval = TimeSpan.FromMilliseconds(1),
},
observer: observer);
observer: observer,
exceptions: exceptions,
tolerance: exceptions is null ? null : new OpenChannel());
}
private sealed class NoCrashEvents : ICrashEventSource
@@ -228,6 +238,8 @@ public sealed class SessionRecorderTests : IAsyncDisposable
public required FakePartialSessionStore Partials { get; init; }
public required SteppingClock Clock { get; init; }
public required SqliteGameConsentStore Store { get; init; }
}
/// <summary>What the driver-profile source answers (beta.8); a throwing one proves a failed read costs the column, not the session.</summary>
@@ -243,7 +255,7 @@ public sealed class SessionRecorderTests : IAsyncDisposable
}
private async Task<Harness> MakeAsync(bool consented = true, AntiCheatVerdict? verdict = null, int records = 3_000, FakeLiveness? liveness = null, bool poller = true,
bool clockStepsOnDrain = false, IDriverProfileSource? profiles = null)
bool clockStepsOnDrain = false, IDriverProfileSource? profiles = null, bool excepted = false)
{
_db ??= await LedgerDatabase.OpenAsync(Path.Combine(_dir, LedgerPaths.DatabaseFileName), ct: TestContext.Current.CancellationToken).ConfigureAwait(false);
var store = new SqliteGameConsentStore(_db);
@@ -257,18 +269,47 @@ public sealed class SessionRecorderTests : IAsyncDisposable
}, TestContext.Current.CancellationToken).ConfigureAwait(false);
}
if (excepted)
{
await ExceptAsync(store).ConfigureAwait(false);
}
var clock = new SteppingClock();
var guard = new FakeGuard { Verdict = verdict ?? AntiCheatVerdict.Allowed() };
var games = new FakeGameRepository();
var sessions = new FakeSessionRepository();
var partials = new FakePartialSessionStore();
var recorder = new SessionRecorder(
new Factory(store, guard, clock, records, liveness ?? _alive),
new Factory(store, guard, clock, records, liveness ?? _alive, excepted ? new FakeExceptionSwitch(on: true) : null),
games, new FakeSnapshots(), new FixedHardware(), partials,
new SessionFinalizer(sessions, new RawSeriesCodec()), new NoCrashEvents(),
_ => poller ? new FakePoller(clockStepsOnDrain ? clock : null) : null, clock,
new RecorderOptions { PartialFlushInterval = TimeSpan.FromSeconds(10) }, profiles: profiles);
return new Harness { Recorder = recorder, Games = games, Sessions = sessions, Partials = partials, Clock = clock };
new RecorderOptions { PartialFlushInterval = TimeSpan.FromSeconds(10) }, profiles: profiles,
exceptionLapse: new UserModeExceptionLapsePolicy(store));
return new Harness { Recorder = recorder, Games = games, Sessions = sessions, Partials = partials, Clock = clock, Store = store };
}
/// <summary>D33: block the consented row for NetEase Yidun, grant its exception on these bytes, and turn hooking on again.</summary>
private static async Task ExceptAsync(SqliteGameConsentStore store)
{
CancellationToken ct = TestContext.Current.CancellationToken;
await store.RecordGuardBlockAsync(Fingerprint, AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "NetEase Yidun", "NEP2.dll"), ct)
.ConfigureAwait(false);
await store.GrantAntiCheatExceptionAsync(new AntiCheatExceptionGrantRequest
{
Fingerprint = Fingerprint,
Block = "AntiCheatFile|NetEase Yidun|NEP2.dll",
Verdict = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll"),
Sessions = 2,
DisclosureVersion = "ac-exception-dialog/1",
GrantedAt = DateTimeOffset.UnixEpoch,
}, ct).ConfigureAwait(false);
await store.RecordOperatorAcknowledgementAsync(new OperatorAcknowledgement
{
Fingerprint = Fingerprint,
DisclosureVersion = "operator-disclosure/test",
AcknowledgedAt = DateTimeOffset.UnixEpoch,
}, ct).ConfigureAwait(false);
}
private static RecordRequest Request(CaptureMode mode = CaptureMode.Attach) => new()
@@ -279,6 +320,43 @@ public sealed class SessionRecorderTests : IAsyncDisposable
Mode = mode,
};
/// <summary>
/// D33 (owner decision 2026-09-26): a hooked session under the game's user-mode exception is marked with the family —
/// the column the App reads, the notes a bug bundle carries — and an ordinary end leaves the exception in force.
/// </summary>
[Fact]
public async Task ASessionUnderTheExceptionIsMarkedAndAnOrdinaryEndKeepsTheException()
{
Harness h = await MakeAsync(verdict: AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll"), excepted: true);
RecordedSession r = await h.Recorder.RecordAsync(Request(), TestContext.Current.CancellationToken);
r.Row.Tier.Should().Be(CaptureTier.Hooked);
r.Row.AcExceptionFamily.Should().Be("NetEase Yidun");
r.Row.CaptureNotes.Should().Contain("ac-exception=NetEase Yidun");
CaptureNotes.Parse(r.Row.CaptureNotes).AcExceptionFamily.Should().Be("NetEase Yidun");
r.ExceptionLapse.Should().BeNull();
(await h.Store.FindAsync(_exe, TestContext.Current.CancellationToken)).Exception.Should().NotBeNull();
}
/// <summary>D33: a crash while hooked under the exception ends it — hooking off, the block standing, the reason recorded.</summary>
[Fact]
public async Task ACrashUnderTheExceptionEndsIt()
{
using var crashed = new FakeLiveness(exited: true, exitCode: unchecked((int)0xC0000005));
Harness h = await MakeAsync(verdict: AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll"), excepted: true, liveness: crashed);
RecordedSession r = await h.Recorder.RecordAsync(Request(), TestContext.Current.CancellationToken);
r.ExitStatus.Should().Be(ExitStatus.Crashed);
r.ExceptionLapse.Should().Be(UserModeExceptionLapse.SessionCrashed);
GameConsentRecord after = await h.Store.FindAsync(_exe, TestContext.Current.CancellationToken);
after.Exception.Should().BeNull();
after.HookEnabled.Should().BeFalse("the block stands, so hooking goes off with the exception");
after.BlockedReason.Should().Be("AntiCheatFile|NetEase Yidun|NEP2.dll", "nothing clears a block");
after.ConsentedAt.Should().NotBeNull("the end of an exception keeps the consent stamp, as a block does");
}
[Fact]
public async Task AHookedSessionIsRecordedEndToEnd()
{
@@ -0,0 +1,45 @@
using FluentAssertions;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Recording;
using FrameLedger.Domain.Sessions;
using FrameLedger.Shared;
namespace FrameLedger.Application.Tests.Recording;
/// <summary>
/// D33: which ends of a session under a game's user-mode exception end the exception — a finding about the game, a safety
/// unhook, the Overlay's own stop, a crash while hooked — and that nothing else does.
/// </summary>
public sealed class UserModeExceptionLapsePolicyTests
{
private static CaptureOutcome Under(SessionEndReason reason, bool hooked = true, bool turnedOff = false, string? family = "NetEase Yidun") => new()
{
Reason = reason,
AttachRefusal = hooked ? ShmAttachRefusal.Ok : ShmAttachRefusal.NotEvaluated,
HookingTurnedOff = turnedOff,
ExceptionFamily = family,
};
[Theory]
[InlineData(SessionEndReason.RefusedByGuard, false, true, ExitStatus.Normal, UserModeExceptionLapse.NewFinding)]
[InlineData(SessionEndReason.SafetyUnhook, true, true, ExitStatus.UnhookedSafety, UserModeExceptionLapse.NewFinding)]
[InlineData(SessionEndReason.SafetyUnhook, true, false, ExitStatus.UnhookedSafety, UserModeExceptionLapse.SafetyUnhook)]
[InlineData(SessionEndReason.WriterStoppedBlocklisted, true, false, ExitStatus.Normal, UserModeExceptionLapse.OverlayStopped)]
[InlineData(SessionEndReason.TargetExited, true, false, ExitStatus.Crashed, UserModeExceptionLapse.SessionCrashed)]
public void TheseEndsEndIt(SessionEndReason reason, bool hooked, bool turnedOff, ExitStatus exit, string lapse) =>
UserModeExceptionLapsePolicy.LapseOf(Under(reason, hooked, turnedOff), exit).Should().Be(lapse);
[Theory]
[InlineData(SessionEndReason.TargetExited, true, ExitStatus.Normal)]
[InlineData(SessionEndReason.StoppedByUser, true, ExitStatus.Normal)]
[InlineData(SessionEndReason.RefusedByGuard, false, ExitStatus.Normal)]
[InlineData(SessionEndReason.AttachRefused, false, ExitStatus.Crashed)]
[InlineData(SessionEndReason.KillSwitchEngaged, true, ExitStatus.Normal)]
public void AnOrdinaryEndOrACrashWithNothingOfOursInsideLeavesIt(SessionEndReason reason, bool hooked, ExitStatus exit) =>
UserModeExceptionLapsePolicy.LapseOf(Under(reason, hooked), exit).Should().BeNull();
[Fact]
public void ASessionUnderNoExceptionIsNeverTheExceptionsBusiness() =>
UserModeExceptionLapsePolicy.LapseOf(Under(SessionEndReason.SafetyUnhook, turnedOff: true, family: null), ExitStatus.UnhookedSafety).Should().BeNull();
}
@@ -20,11 +20,24 @@ public sealed class SettingsRegistryTests
SettingsRegistry.Find("nobody.knows").Should().BeNull();
}
/// <summary>D33: the exception option is off unless the user turns it on — and exactly "1" is on.</summary>
[Fact]
public void TheUserModeExceptionOptionIsOffByDefault()
{
SettingDefinition d = SettingsRegistry.HookingUserModeExceptions;
d.Key.Should().Be("hooking.usermode_ac_exceptions");
d.Default.Should().Be("0");
d.Kind.Should().Be(SettingKind.Boolean);
d.AgentReads.Should().BeTrue("the Agent reads it at every session start and command");
}
[Fact]
public void TheAgentReadsExactlyTheFourPrefixesD16Names()
{
string[] agent = [.. SettingsRegistry.All.Where(static d => d.AgentReads).Select(static d => d.Key)];
agent.Should().BeEquivalentTo(["capture.background", "hooking.kill_switch", "capture.min_session_s", "telemetry.interval_ms", "retention.raw_sessions_per_game"]);
// hooking.usermode_ac_exceptions joined on 2026-09-26 (D33): the user-mode exception's option, off by default.
agent.Should().BeEquivalentTo(["capture.background", "hooking.kill_switch", "hooking.usermode_ac_exceptions", "capture.min_session_s",
"telemetry.interval_ms", "retention.raw_sessions_per_game"]);
agent.Should().OnlyContain(static k => k.StartsWith("hooking.", StringComparison.Ordinal) || k.StartsWith("capture.", StringComparison.Ordinal)
|| k.StartsWith("telemetry.", StringComparison.Ordinal) || k.StartsWith("retention.", StringComparison.Ordinal));
}
@@ -39,6 +39,15 @@ public sealed class VkLayerReconcilerTests
public ValueTask<ConsentWriteOutcome> RecordGuardBlockAsync(ExecutableFingerprint fingerprint, AntiCheatVerdict verdict, CancellationToken ct = default) => throw new NotSupportedException();
public ValueTask<ConsentWriteOutcome> RecordPreScanAsync(ExecutableFingerprint scanned, AntiCheatVerdict verdict, string rulesVersion, CancellationToken ct = default) => throw new NotSupportedException();
public ValueTask<ConsentWriteOutcome> RecordExceptionEligibilityAsync(ExecutableFingerprint scanned, string block, AntiCheatVerdict? verdict, int sessions,
string rulesVersion, CancellationToken ct = default) => throw new NotSupportedException();
public ValueTask<ConsentWriteOutcome> GrantAntiCheatExceptionAsync(AntiCheatExceptionGrantRequest grant, CancellationToken ct = default) =>
throw new NotSupportedException();
public ValueTask<ConsentWriteOutcome> RevokeAntiCheatExceptionAsync(string normalisedExePath, string reason, CancellationToken ct = default) =>
throw new NotSupportedException();
}
private sealed class FakeRegistrar : IVkLayerRegistrar
@@ -0,0 +1,97 @@
using System.IO.MemoryMappedFiles;
using System.Runtime.InteropServices;
using System.Security.Principal;
using System.Text;
using FluentAssertions;
using FrameLedger.Infrastructure.AntiCheat;
using FrameLedger.Infrastructure.Capture;
using FrameLedger.Shared;
namespace FrameLedger.Infrastructure.Tests.Capture;
/// <summary>
/// D33 (owner decision 2026-09-26): the Agent's channel to the Overlay — <c>Local\FrameLedger.Tolerate.&lt;pid&gt;</c> — says
/// the family in the layout <c>fl_tolerance.h</c> fixes, is readable by the user and writable by nobody, refuses a name that
/// already exists, and is gone when it is let go.
/// </summary>
public sealed class OverlayToleranceChannelTests
{
/// <summary>A pid for the name alone: nothing runs as it, and each test has its own.</summary>
private static int NamePid() => System.Security.Cryptography.RandomNumberGenerator.GetInt32(1_000_000, int.MaxValue);
private static unsafe string FamilyOf(FlTolerance t) => Encoding.ASCII.GetString(new ReadOnlySpan<byte>(t.Families, ToleranceLayout.NameLen)).TrimEnd('\0');
[Fact]
public void ThePublishedMappingNamesTheFamilyAndNobodyMayWriteIt()
{
int pid = NamePid();
using IDisposable? held = new OverlayToleranceChannel().TryPublish(pid, "NetEase Yidun");
held.Should().NotBeNull();
using var mapping = MemoryMappedFile.OpenExisting(ToleranceLayout.MappingName(pid), MemoryMappedFileRights.Read);
using MemoryMappedViewAccessor view = mapping.CreateViewAccessor(0, Marshal.SizeOf<FlTolerance>(), MemoryMappedFileAccess.Read);
view.Read(0, out FlTolerance t);
t.Magic.Should().Be(ToleranceLayout.Magic);
t.Version.Should().Be(ToleranceLayout.Version);
t.Count.Should().Be(1);
t.Reserved.Should().Be(0);
FamilyOf(t).Should().Be("NetEase Yidun");
Action write = () => MemoryMappedFile.OpenExisting(ToleranceLayout.MappingName(pid), MemoryMappedFileRights.ReadWrite).Dispose();
write.Should().Throw<UnauthorizedAccessException>("the DACL grants the user read and nothing else: the Agent wrote once, through the creating handle");
}
[Fact]
public void ANameAlreadyTakenIsNotOurs()
{
int pid = NamePid();
using var squatter = MemoryMappedFile.CreateNew(ToleranceLayout.MappingName(pid), 528);
new OverlayToleranceChannel().TryPublish(pid, "NetEase Yidun").Should().BeNull("whatever that mapping says, nothing is injected under it");
}
[Fact]
public void LettingGoRemovesTheNameAndTwiceIsHarmless()
{
int pid = NamePid();
var channel = new OverlayToleranceChannel();
IDisposable held = channel.TryPublish(pid, "Anybrain")!;
held.Dispose();
held.Dispose();
Action open = () => MemoryMappedFile.OpenExisting(ToleranceLayout.MappingName(pid), MemoryMappedFileRights.Read).Dispose();
open.Should().Throw<FileNotFoundException>();
using IDisposable? again = channel.TryPublish(pid, "Anybrain");
again.Should().NotBeNull("the next session for a recycled pid can publish again");
}
[Theory]
[InlineData("")]
[InlineData(" ")]
[InlineData("Net\nEase")]
[InlineData("Ñetease")]
[InlineData("a family name of sixty-four characters is one more than the Overlay reads")]
public void ANameTheOverlayCouldNeverMatchIsNotPublished(string family)
{
OverlayToleranceChannel.Encode(family).Should().BeNull();
new OverlayToleranceChannel().TryPublish(NamePid(), family).Should().BeNull();
}
[Fact]
public void TheDescriptorIsTheUsersReadAndNothingElse()
{
var user = new SecurityIdentifier("S-1-5-21-1-2-3-1001");
OverlayToleranceChannel.Sddl(user).Should().Be("O:S-1-5-21-1-2-3-1001D:P(A;;GR;;;S-1-5-21-1-2-3-1001)");
}
/// <summary>The port's one name as the guard ABI takes it: NUL-terminated UTF-8, or nothing for a name that could split the list.</summary>
[Fact]
public void TheGuardIsHandedOneTerminatedNameOrNone()
{
NativeAntiCheatGuard.ToleranceBytes("NetEase Yidun").Should().Equal([.. Encoding.UTF8.GetBytes("NetEase Yidun"), (byte)0]);
NativeAntiCheatGuard.ToleranceBytes(null).Should().BeNull();
NativeAntiCheatGuard.ToleranceBytes(" ").Should().BeNull();
NativeAntiCheatGuard.ToleranceBytes("NetEase Yidun\nEasy Anti-Cheat").Should().BeNull("a newline would name a second family nobody granted");
}
}
@@ -139,4 +139,20 @@ public sealed class IpcCodecTests
IpcCodec.Payload<StatusAck>(IpcCodec.Decode(IpcCodec.Encode(IpcMessageType.StatusAck, "1", status)))!.ActiveSessions.Single().Hold
.Should().Be(new SessionHold("RefusedHookNotEnabled"));
}
/// <summary>D33: the exception's command and answer, and HelloAck's second disclosure version, on the wire in camelCase.</summary>
[Fact]
public void TheUserModeExceptionMessagesRoundTrip()
{
byte[] request = IpcCodec.Encode(IpcMessageType.SetAntiCheatException, "7", new SetAntiCheatExceptionRequest(56, true, "ac-exception-dialog/1"));
Encoding.UTF8.GetString(request).Should().Contain("\"disclosureVersion\":\"ac-exception-dialog/1\"");
IpcCodec.Payload<SetAntiCheatExceptionRequest>(IpcCodec.Decode(request)).Should().Be(new SetAntiCheatExceptionRequest(56, true, "ac-exception-dialog/1"));
byte[] ack = IpcCodec.Encode(IpcMessageType.AntiCheatExceptionAck, "7", new AntiCheatExceptionAck(56, true, "Written", "NetEase Yidun"));
IpcCodec.Payload<AntiCheatExceptionAck>(IpcCodec.Decode(ack)).Should().Be(new AntiCheatExceptionAck(56, true, "Written", "NetEase Yidun"));
byte[] hello = IpcCodec.Encode(IpcMessageType.HelloAck, "1",
new HelloAck("0.1.0-beta.9", IpcProtocol.Version, 1, false, null, false, null, false, "consent-dialog/1", "ac-exception-dialog/1"));
IpcCodec.Payload<HelloAck>(IpcCodec.Decode(hello))!.ExceptionDisclosureVersion.Should().Be("ac-exception-dialog/1");
}
}
@@ -86,6 +86,11 @@ public sealed class NoSecondMatcherTests
// 4 again since 2026-09-22. It was 6 for one day: the user's bypass of 2026-09-21 added
// GuardedInjectAcknowledgedAsync and its WhenReady twin, and the owner withdrew the bypass with them. A
// way into a game process that overrules the guard's judgement is exactly what this count exists to notice.
//
// Still 4 under D33 (2026-09-26): the user-mode exception added no method. Each of the four gained
// `string? toleratedFamily` — a NAME, a string like every other parameter here, which the native guard
// resolves against its own rules and honours only for a family that is user-mode throughout. It adds no
// evidence and no rules; the loop below would refuse either.
methods.Should().HaveCount(4);
// Stronger than the count, and it survives the port growing: every
@@ -2,6 +2,7 @@ using System.Text.RegularExpressions;
using Dapper;
using FluentAssertions;
using FluentAssertions.Specialized;
using FrameLedger.Application.Persistence;
using FrameLedger.Infrastructure.Import;
using FrameLedger.Infrastructure.Persistence;
using Microsoft.Data.Sqlite;
@@ -133,6 +134,45 @@ public sealed class LedgerDatabaseTests
cancellationToken: Ct)).ConfigureAwait(false);
}
/// <summary>
/// Schema 0014 (2026-09-26, D33): the user-mode exception's columns, ADD COLUMN only — a row blocked before it keeps its
/// block, is not eligible and carries no grant; a session written before it ran under no exception.
/// </summary>
[Fact]
public async Task ScriptFourteenAddsTheExceptionColumnsAndChangesNoRow()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
MigrationRunner.LatestVersion.Should().BeGreaterThanOrEqualTo(14);
string path = f.Path;
await f.Db.DisposeAsync().ConfigureAwait(true);
var c13 = new SqliteConnection(new SqliteConnectionStringBuilder { DataSource = path, Pooling = false }.ToString());
await using (c13.ConfigureAwait(true))
{
await c13.OpenAsync(Ct).ConfigureAwait(true);
await RewindToAsync(c13, 13).ConfigureAwait(true);
await c13.ExecuteAsync(new CommandDefinition(
"INSERT INTO games (name, exe_path, hook_blocked_reason, hook_prescan_state, added_at, updated_at) "
+ "VALUES ('GF2', 'C:\\GF2\\GF2_Exilium.exe', 'AntiCheatFile|NetEase Yidun|NEP2.dll', 'blocked', 0, 0)", cancellationToken: Ct)).ConfigureAwait(true);
}
LedgerDatabase migrated = await LedgerDatabase.OpenAsync(path, ct: Ct).ConfigureAwait(true);
await using (migrated.ConfigureAwait(true))
{
migrated.SchemaVersion.Should().Be(MigrationRunner.LatestVersion);
IReadOnlyList<string> games = await migrated.ReadAsync(async (c, ct) =>
(IReadOnlyList<string>)[.. await c.QueryAsync<string>(new CommandDefinition(
"SELECT name FROM pragma_table_info('games') WHERE name LIKE 'ac_exception_%'", cancellationToken: ct)).ConfigureAwait(false)], Ct).ConfigureAwait(true);
games.Should().HaveCount(14);
long sessions = await migrated.ReadAsync((c, ct) => c.ExecuteScalarAsync<long>(new CommandDefinition(
"SELECT COUNT(*) FROM pragma_table_info('sessions') WHERE name = 'ac_exception_family'", cancellationToken: ct)), Ct).ConfigureAwait(true);
sessions.Should().Be(1);
GameRow row = (await new SqliteGameRepository(migrated).FindAsync(@"C:\GF2\GF2_Exilium.exe", Ct).ConfigureAwait(true))!;
row.HookBlockedReason.Should().Be("AntiCheatFile|NetEase Yidun|NEP2.dll", "0014 edits no row");
row.AcException.Should().BeEquivalentTo(AntiCheatExceptionState.None, "no eligibility and no grant until the Agent and the user say so");
}
}
/// <summary>Schema 0013 (2026-09-25): <c>frame_blobs.first_present_ms</c>, NULL for every row written before.</summary>
[Fact]
public async Task ScriptThirteenAddsTheFirstPresentColumn()
@@ -1,6 +1,7 @@
using Dapper;
using FluentAssertions;
using FrameLedger.Application.Consent;
using FrameLedger.Application.Persistence;
using FrameLedger.Domain.AntiCheat;
using FrameLedger.Domain.Consent;
using FrameLedger.Infrastructure.Persistence;
@@ -368,4 +369,146 @@ public sealed class SqliteGameConsentStoreTests
.Should().Be(ConsentWriteOutcome.NotFound, "the library is the App's and the watcher's to add to");
(await store.FindAsync(@"C:\Games\Other\other.exe", Ct)).IsFromStore.Should().BeFalse();
}
// --- The user-mode exception (D33, owner decision 2026-09-26; schema 0014) ----------------------------------------------
private const string _yidun = "AntiCheatFile|NetEase Yidun|NEP2.dll";
private static readonly AntiCheatVerdict _letThrough = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll");
private static AntiCheatExceptionGrantRequest GrantOf(ExecutableFingerprint? fp = null, string block = _yidun, AntiCheatVerdict? verdict = null, int sessions = 3) => new()
{
Fingerprint = fp ?? Fingerprint(),
Block = block,
Verdict = verdict ?? _letThrough,
Sessions = sessions,
DisclosureVersion = "ac-exception-dialog/1",
GrantedAt = DateTimeOffset.FromUnixTimeMilliseconds(1_000),
};
/// <summary>A consented row, blocked for NetEase Yidun: GIRLS' FRONTLINE 2 as beta.8 left it.</summary>
private static async Task<SqliteGameConsentStore> BlockedAsync(LedgerFixture f)
{
var store = new SqliteGameConsentStore(f.Db);
await store.RecordOperatorAcknowledgementAsync(Ack(), Ct).ConfigureAwait(false);
await store.RecordGuardBlockAsync(Fingerprint(), AntiCheatVerdict.Refused(AntiCheatRefusalReason.AntiCheatFile, "NetEase Yidun", "NEP2.dll"), Ct)
.ConfigureAwait(false);
return store;
}
[Fact]
public async Task AGrantIsWrittenOnlyOverFactsThatMakeTheGameEligibleAndClearsNothing()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
SqliteGameConsentStore store = await BlockedAsync(f);
(await store.GrantAntiCheatExceptionAsync(GrantOf(sessions: 1), Ct)).Should().Be(ConsentWriteOutcome.NotEligible, "the owner's threshold is two");
(await store.GrantAntiCheatExceptionAsync(GrantOf(verdict: AntiCheatVerdict.Allowed()), Ct)).Should().Be(ConsentWriteOutcome.NotEligible,
"a pass that let nothing through confirmed nothing");
(await store.GrantAntiCheatExceptionAsync(GrantOf(block: "BlockedStoreId|Valve VAC|steam:730"), Ct)).Should().Be(ConsentWriteOutcome.NotEligible);
(await store.GrantAntiCheatExceptionAsync(GrantOf(block: "BlockedModule|NetEase Yidun|NEP2.dll"), Ct)).Should().Be(ConsentWriteOutcome.NotFound,
"the facts are about a block the row does not carry");
(await store.FindAsync(Fingerprint().ExePath, Ct)).Exception.Should().BeNull();
(await store.GrantAntiCheatExceptionAsync(GrantOf(), Ct)).Should().Be(ConsentWriteOutcome.Written);
GameConsentRecord r = await store.FindAsync(Fingerprint().ExePath, Ct);
r.Exception.Should().Be(new AntiCheatExceptionGrant
{
Family = "NetEase Yidun",
GrantedAt = DateTimeOffset.FromUnixTimeMilliseconds(1_000),
DisclosureVersion = "ac-exception-dialog/1",
ExeSizeBytes = 90_000,
ExeMtimeUnixMs = 1_700_000_000_000,
});
r.BlockedReason.Should().Be(_yidun, "the exception is a layer over the block, never its clearing");
r.HookEnabled.Should().BeFalse("a grant turns nothing on");
r.ConsentedAt.Should().NotBeNull();
}
/// <summary>
/// FR-2.1 under the exception: the stamp may re-point a blocked row at the bytes the exception was granted on — the user
/// accepted both disclosures for that file — and at no other bytes.
/// </summary>
[Fact]
public async Task UnderAGrantTheConsentStampMayMoveToTheGrantedBytesAndNoOthers()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
SqliteGameConsentStore store = await BlockedAsync(f);
ExecutableFingerprint patched = Fingerprint() with { SizeBytes = 91_000 };
(await store.GrantAntiCheatExceptionAsync(GrantOf(patched), Ct)).Should().Be(ConsentWriteOutcome.Written);
(await store.RecordOperatorAcknowledgementAsync(Ack(Fingerprint() with { SizeBytes = 92_000 }), Ct)).Should().Be(ConsentWriteOutcome.StaleFingerprint);
(await store.RecordOperatorAcknowledgementAsync(Ack(patched), Ct)).Should().Be(ConsentWriteOutcome.Written);
GameConsentRecord r = await store.FindAsync(Fingerprint().ExePath, Ct);
r.HookEnabled.Should().BeTrue();
r.Fingerprint.SizeBytes.Should().Be(91_000);
r.BlockedReason.Should().Be(_yidun);
}
[Fact]
public async Task TheEndOfAnExceptionTurnsHookingOffKeepsTheStampAndTheHistory()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
SqliteGameConsentStore store = await BlockedAsync(f);
(await store.RevokeAntiCheatExceptionAsync(Fingerprint().ExePath, "SessionCrashed", Ct)).Should().Be(ConsentWriteOutcome.NotFound, "nothing in force");
await store.GrantAntiCheatExceptionAsync(GrantOf(), Ct);
await store.RecordOperatorAcknowledgementAsync(Ack(), Ct);
(await store.RevokeAntiCheatExceptionAsync(Fingerprint().ExePath, "SessionCrashed", Ct)).Should().Be(ConsentWriteOutcome.Written);
GameConsentRecord r = await store.FindAsync(Fingerprint().ExePath, Ct);
r.Exception.Should().BeNull();
r.HookEnabled.Should().BeFalse("the block stands");
r.ConsentedAt.Should().NotBeNull("an ended exception is not a withdrawn consent");
GameRow row = (await new SqliteGameRepository(f.Db).FindAsync(Fingerprint().ExePath, Ct))!;
row.AcException.LapsedReason.Should().Be("SessionCrashed");
row.AcException.LapsedAt.Should().NotBeNull();
row.AcException.Family.Should().Be("NetEase Yidun", "the family stays as history");
row.AcException.IsGranted.Should().BeFalse();
}
[Fact]
public async Task EligibilityIsWrittenWithItsKeyOnlyOverTheBlockItWasReachedAbout()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
SqliteGameConsentStore store = await BlockedAsync(f);
ExecutableFingerprint onDisk = Fingerprint() with { MtimeUnixMs = 1_800_000_000_000 };
(await store.RecordExceptionEligibilityAsync(onDisk, "BlockedModule|X|y.dll", _letThrough, 3, "2026.09.5", Ct)).Should().Be(ConsentWriteOutcome.NotFound);
(await store.RecordExceptionEligibilityAsync(onDisk, _yidun, _letThrough, 3, "2026.09.5", Ct)).Should().Be(ConsentWriteOutcome.Written);
AntiCheatExceptionState x = (await new SqliteGameRepository(f.Db).FindAsync(onDisk.ExePath, Ct))!.AcException;
x.Eligible.Should().BeTrue();
x.Verdict.Should().Be("AllowedUnderUserModeException|NetEase Yidun|NEP2.dll");
x.Sessions.Should().Be(3);
x.IsCheckedFor(onDisk, "2026.09.5", _yidun).Should().BeTrue();
x.IsGranted.Should().BeFalse("eligibility grants nothing");
(await store.RecordExceptionEligibilityAsync(onDisk, _yidun, null, 3, "2026.09.5", Ct)).Should().Be(ConsentWriteOutcome.Written);
x = (await new SqliteGameRepository(f.Db).FindAsync(onDisk.ExePath, Ct))!.AcException;
x.Eligible.Should().BeFalse("nothing was asked");
x.Verdict.Should().BeNull();
}
[Fact]
public async Task ChangingTheExecutableEndsTheExceptionAndForgetsItsEligibility()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
SqliteGameConsentStore store = await BlockedAsync(f);
await store.RecordExceptionEligibilityAsync(Fingerprint(), _yidun, _letThrough, 3, "2026.09.5", Ct);
await store.GrantAntiCheatExceptionAsync(GrantOf(), Ct);
var games = new SqliteGameRepository(f.Db);
long id = (await games.FindAsync(Fingerprint().ExePath, Ct))!.Id;
(await games.ChangeExecutableAsync(id, Fingerprint(@"C:\Games\Title\other.exe"), DateTimeOffset.UnixEpoch, Ct)).Should().BeTrue();
GameRow row = (await games.FindByIdAsync(id, Ct))!;
row.AcException.IsGranted.Should().BeFalse();
row.AcException.LapsedReason.Should().Be("ExecutableChanged");
row.AcException.Eligible.Should().BeFalse("the new file has not been looked at");
row.AcException.CheckedRulesVersion.Should().BeNull();
row.HookBlockedReason.Should().Be(_yidun, "the block outlives Change executable, as before");
}
}
@@ -38,6 +38,7 @@ public sealed class SqliteSessionRepositoryTests
Tier = CaptureTier.Hooked,
Mode = CaptureMode.Launch,
ExitStatus = ExitStatus.Normal,
AcExceptionFamily = "NetEase Yidun",
FrameCount = 5400,
AppFrameCount = 5400,
DisplayedFrameCount = 5400,
@@ -362,4 +363,33 @@ public sealed class SqliteSessionRepositoryTests
accepted.Version.Should().Be("2026-09");
accepted.AcceptedAt.Should().Be(DateTimeOffset.FromUnixTimeMilliseconds(1_700_000_000_000));
}
/// <summary>
/// D33 (owner decision 2026-09-26): the evidence a user-mode exception needs — hooked, frames recorded, <c>normal</c> —
/// and nothing else: a crash, a safety unhook, a Tier-2 session and a hooked session that recorded no frame do not count.
/// </summary>
[Fact]
public async Task OnlyHookedNormalSessionsWithFramesAreSuccessful()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
(long gameId, long snapshotId) = await SeedAsync(f);
var repo = new SqliteSessionRepository(f.Db);
SessionRow[] rows =
[
Row(gameId, snapshotId),
Row(gameId, snapshotId) with { ExitStatus = ExitStatus.Crashed },
Row(gameId, snapshotId) with { ExitStatus = ExitStatus.UnhookedSafety },
Row(gameId, snapshotId) with { ExitStatus = ExitStatus.Degraded },
Row(gameId, snapshotId) with { Tier = CaptureTier.NotHooked },
Row(gameId, snapshotId) with { FrameCount = 0, AppFrameCount = 0, DisplayedFrameCount = 0 },
Row(gameId, snapshotId),
];
foreach (SessionRow row in rows)
{
await repo.InsertFinalizedAsync(new FinalizedSession { Row = row }, Ct);
}
(await repo.CountSuccessfulHookedAsync(gameId, Ct)).Should().Be(2);
(await repo.CountSuccessfulHookedAsync(gameId + 1, Ct)).Should().Be(0);
}
}
@@ -320,7 +320,7 @@ public sealed class ShmDrainIntegrationTests
// The REAL guard with REAL sources — no test seam. The harness carries no anti-cheat, so a
// refusal here is a genuine finding about this machine, not a fixture problem.
AntiCheatVerdict verdict = await guard.GuardedInjectAsync(harness.Id, Payload, TestContext.Current.CancellationToken);
AntiCheatVerdict verdict = await guard.GuardedInjectAsync(harness.Id, Payload, toleratedFamily: null, TestContext.Current.CancellationToken);
verdict.IsAllowed.Should().BeTrue(
$"the guard refused our own harness: {verdict.Reason} {verdict.Family} {verdict.Signal}");
@@ -525,7 +525,7 @@ public sealed class ShmDrainIntegrationTests
try
{
var guard = new NativeAntiCheatGuard();
(await guard.GuardedInjectAsync(harness.Id, Payload, TestContext.Current.CancellationToken))
(await guard.GuardedInjectAsync(harness.Id, Payload, toleratedFamily: null, TestContext.Current.CancellationToken))
.IsAllowed.Should().BeTrue();
using ShmRingReader reader = await AttachAsync(harness.Id, NativeAntiCheatGuard.BuildId());
@@ -617,7 +617,7 @@ public sealed class ShmDrainIntegrationTests
try
{
var guard = new NativeAntiCheatGuard();
(await guard.GuardedInjectAsync(harness.Id, Payload, TestContext.Current.CancellationToken))
(await guard.GuardedInjectAsync(harness.Id, Payload, toleratedFamily: null, TestContext.Current.CancellationToken))
.IsAllowed.Should().BeTrue();
using ShmRingReader reader = await AttachAsync(harness.Id, NativeAntiCheatGuard.BuildId());
@@ -680,7 +680,7 @@ public sealed class ShmDrainIntegrationTests
try
{
var guard = new NativeAntiCheatGuard();
(await guard.GuardedInjectAsync(harness.Id, Payload, TestContext.Current.CancellationToken)).IsAllowed.Should().BeTrue();
(await guard.GuardedInjectAsync(harness.Id, Payload, toleratedFamily: null, TestContext.Current.CancellationToken)).IsAllowed.Should().BeTrue();
string ownBuildId = NativeAntiCheatGuard.BuildId();
using (ShmRingReader reader = await AttachAsync(harness.Id, ownBuildId))