Compare commits

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

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

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

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

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

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

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

No hook-path change: the Overlay is untouched.

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

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

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

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

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

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

---------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Also:
- LibraryImporter no longer adds a twin: a store executable that is a
  library entry's path on another letter, with that entry's file gone, is
  shown "In the library under another drive letter" (Import_Note_Moved,
  en/vi/ja) and skipped at import.
- DetectionSweep does not call a merged-away entry unreadable.
- DetectionHostedService catches DbException: a service that throws stops
  the Agent's host, and a busy ledger is a retry.

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

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

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

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

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

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

---------

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

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

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

Also:
- LibraryImporter no longer adds a twin: a store executable that is a
  library entry's path on another letter, with that entry's file gone, is
  shown "In the library under another drive letter" (Import_Note_Moved,
  en/vi/ja) and skipped at import.
- DetectionSweep does not call a merged-away entry unreadable.
- DetectionHostedService catches DbException: a service that throws stops
  the Agent's host, and a busy ledger is a retry.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-21 23:27:06 +07:00
452 changed files with 29557 additions and 3226 deletions

No files matched your search

+540 -4
View File
@@ -27,7 +27,539 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
## [Unreleased]
_Nothing yet — entries continue here after `0.1.0-beta.4`._
## [0.1.0-beta.10] - 2026-09-28
**The tenth pre-release: how each game was shown, the agent as administrator if you choose it, and the exact Unreal
Engine version.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
What changed for a user:
- **The display mode** — exclusive full-screen, borderless, windowed or minimised, as a share of each session, with the
window's size and the monitor's — on the session summary, the game page, the Trend (three new metrics) and Compare,
for measured and unmeasured sessions alike. Only a measured Direct3D game can say *exclusive*; others read
*full-screen or borderless* when the window covers the screen.
- **Run the agent as administrator** — a Settings option, off by default. Windows asks every time the agent starts;
games you start from FrameLedger still run with your standard rights; it changes nothing in the anti-cheat guard.
- **The exact Unreal Engine version** on a game's page, read from its executable, with what it rests on.
- **What FrameLedger cannot do** is one page — Help ▸ Limitations, and `LIMITATIONS.md` — and the games it has been run
with are listed in `docs/LIST_GAME_TESTED.md`.
- **The Privacy Policy (2.5) and the Disclaimer (2.8) say so**, so the Legal Gate opens once after the update. The EULA
is unchanged.
**Updating from `0.1.0-beta.9`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schemas 0015 and 0016 add columns; the database opens in place. Sessions recorded before show the display mode as N/A.
- The shared-memory layout between the agent and a measured game changed (version 4): **a game that was running while
you updated must be restarted before it can be measured** — the app says so when it meets the old layout.
- Every game is re-detected once (rules `2026.09.6`), which fills in the Unreal Engine versions.
### Added
- **The exact Unreal Engine version on a game's page** (owner request, beta.10). The Agent reads it from the game's
shipping executable on disk — its version number and the engine's build name compiled into it (`++UE5+Release-5.1`)
— and the page says which of the two it rests on: *Unreal Engine 4.27.2* for Lies of P, *5.4.4* for Clair Obscur:
Expedition 33, *5.1* for SILENT HILL 2 (whose studio replaced the version number with its own), and "not found in the
executable" where neither says anything (Cronos, Rune Factory). Measured on ten installed Unreal titles before it was
written: eight read, two honestly none. The file is read, never the game's process; a protected executable is scanned
whole, once per version of the file (up to 7.5 s on a USB drive for Black Myth: Wukong), and the scan stops if the Agent
is asked to. Rules `2026.09.6`: every game is re-detected once. Schema 0015 adds `games.engine_version_source`.
- **How each game was shown, and for how much of the session** (owner request, beta.10): exclusive fullscreen, borderless,
windowed or minimised, with the window's size, the monitor it was on and its refresh rate, and the swap chain's back
buffer. On the session summary (a *Display* card and a line with every share), the game page (the last measured session,
and a *Display* column in Sessions), the Trend (three new metrics: the share of each session in exclusive fullscreen,
borderless and windowed), Compare (three rows, never ranked) and both exports (the CSV's `# display:` line, the JSON's
aggregates). **Both tiers:** a game that was not hooked has its window read from outside, which can say windowed or
*fullscreen or borderless* but never which of those two — only the swap chain of a hooked DirectX game can say
exclusive. What Windows does with an exclusive game behind the scenes ("fullscreen optimizations") is not visible to
FrameLedger, and a game's menu may call a borderless window "Fullscreen": the swap chain's answer is the one shown.
Sessions recorded before, and one recovered after a crash, read N/A. Schema 0016 adds fifteen `sessions.display_*`
columns, and `sessions.swap_effect` — a column with no writer since the first schema — is now filled.
- **Run the capture agent as administrator — your choice, off by default** (owner request, beta.10). Settings ▸ Capture
agent ▸ *Run the agent as administrator* shows what it adds (measuring a game that itself runs as administrator; the CPU
temperature where PawnIO is installed), what it does not change (a game with anti-cheat is still refused; a Vulkan game
run as administrator is still not measured) and the risk of a per-user, unsigned install, before it turns on. Then
**Windows asks every time the agent starts** — also at logon, when its prompt may wait on the taskbar; there is no
silent way. Answer No and the agent runs with your standard rights and says so; answer with another administrator
account and that agent refuses to run, because its data would not be yours. **Games you start from FrameLedger always
run with your standard rights**, and nothing FrameLedger does enables a privilege (a CI test on an elevated runner and a
source check hold both). While the prompt waits, the status pill says so. With the option off, an App started as
administrator no longer makes the agent an administrator's too. Updating now also waits for an administrator agent's
process to let go of its files.
- **What FrameLedger cannot do, in one place** (beta.10). `LIMITATIONS.md` lists the limits of the whole software in
plain words — the games it will not measure, what an unmeasured session holds, frame generation, upscaling and ray
tracing, the display mode, the engine version, sensors, the admin mode, the platform and your data — each linked to its
details; the app shows it under **Help ▸ Limitations**. `docs/LIST_GAME_TESTED.md` lists the real games FrameLedger has
been run with and what was measured on each.
### Changed
- **The legal documents say what beta.10 does** — you will be shown two of them again once. **Privacy Policy 2.5** adds
how a tracked game's window is shown (read from Windows) and the engine version read from an Unreal Engine game's
executable, and says for the first time two things the software already did: it reads the content of a library game's
executable (engine and library markers, its import table) and the processor load and memory in use. **Disclaimer 2.8**
adds §5A — running the capture agent as administrator, what it does and does not do, and its risk — and points at the
new limitations page and the tested-games list. The End-User License Agreement is unchanged (1.3).
- **Groundwork for the display mode (beta.10): the injected component reports how the game presents** — whether its swap
chain is in exclusive fullscreen, which window it presents to, its back buffer and swap effect — at most twice a second,
from two getters on the swap chain the game passed (measured at 13–15 ns each on the test fixture: nothing a frame rate
can see). The shared-memory layout moves to version 4 (a new region; the frame ring moved behind it): **a game that is
running while FrameLedger is updated must be restarted before it can be measured**, which the app already says when it
meets an old layout. What the app shows from it is the display mode under *Added*.
### Fixed
- **An Unreal game's engine version was a bare "4" or "5"** — and for most titles nothing at all. The rule's pattern had two
capture groups and the evaluator keeps the first, and it read only a version string most executables leave empty.
Schema 0015 removes the digits the old rule wrote (only where detection wrote them — a version you typed stays), and the
rules validator now refuses any version pattern that does not compile or that captures anything but exactly one group.
- **A Direct3D 12 game that resized through `ResizeBuffers1` kept its old output size in every later frame.** That call is
not hooked; the swap chain's size is now re-read twice a second, so a resize by either route is seen.
## [0.1.0-beta.9] - 2026-09-26
**The ninth pre-release: one narrow exception you can make yourself for a game whose only anti-cheat runs in user
mode and that FrameLedger has measured before.** The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
- **A user-mode anti-cheat exception, per game, off by default** (Settings ▸ Capture). It is offered only where the
only anti-cheat found runs entirely in user mode — no driver or service, no driver file in the game's folder — the
game is on no title list, and FrameLedger has measured it hooked successfully at least twice. You make it one game
at a time, after a disclosure that states the ban risk; the guard still runs every check under it and ends it on
anything new, a crash or safety stop under it, or a game update. Sessions under it are marked.
- **The Disclaimer (2.7) and the EULA (1.3) say so**, so the Legal Gate opens once after the update. The Privacy
Policy is unchanged.
**Updating from `0.1.0-beta.8`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schema 0014 adds columns; the database opens in place. Nothing changes for any game until you turn the option on.
- With the option on, the Agent looks at each game whose hooking it turned off within a minute and lists the ones
that qualify; a game shipping a kernel driver (Aniimo's `NEPKernel.sys`, for one) never does.
### Added
- **A user-mode anti-cheat exception you can make yourself, per game** (owner decision D33). Settings ▸ Capture ▸
*Allow hooking in games with user-mode anti-cheat that were measured before* — off by default. On, it lists the games
FrameLedger found eligible: the only anti-cheat in the game runs entirely in user mode (no driver or service, no
driver file anywhere in the game's folder), the game is on no title list, and FrameLedger has measured it hooked
successfully at least twice. **Make exception…** shows a disclosure — the ban risk, possibly days later and invisible
to FrameLedger; what is still refused; how the exception ends — and asks you to accept the risk for that game. The
exception turns nothing on: you then turn hooking on for the game on its page, through the usual consent dialog, and
the guard still runs every check and refuses anything else it finds. The game's page shows the exception's state
(eligible; not eligible and why; in force; suspended; ended and why), the library card says **Exception**, and a
session hooked under it is marked in the Sessions tab and its summary. It ends by itself on a new finding, a crash or
safety stop under it, FrameLedger stopping because another anti-cheat loaded, or a game update; turning the option
off suspends every exception. Aniimo stays blocked: it ships a kernel driver (`NEPKernel.sys`).
- **Groundwork for the user-mode anti-cheat exception** (owner decision D33, 2026-09-26; the option, the list and the
disclosure arrive later in this train). The guard can now be asked to let ONE named anti-cheat family through, and
grants it only for a family whose every signal — in the built-in floor and in the rules file — is user-mode: no
driver, no service, no `.sys` (on today's rules NetEase Yidun, AhnLab HackShield, Anybrain and FredaikisAntiCheat).
It still runs every check and keeps scanning past what it let through, so a second anti-cheat, a kernel driver in
the game's folder, a title list, a driver or service on the machine, or a scan that could not finish still refuses;
a pass that let something through says so and names it. The injected Overlay learns the same family before it
starts watching the game's module loads, so a late-loading module of that family does not stop it and any other
anti-cheat still does. Nothing asks for any of this yet: every game is judged exactly as in beta.8.
- **The Agent can grant, keep and end a user-mode anti-cheat exception** (D33; the Settings option, the list and the
disclosure arrive in the next PR, so nothing in the App asks for one yet). With the option on
(`hooking.usermode_ac_exceptions`, off by default), the Agent's library scan asks each blocked game one question —
would the guard let exactly its blocking family through, with no kernel driver and nothing else found — and counts
its successful hooked sessions; a game with both and at least two sessions is eligible. A grant rests on facts the
Agent gathers itself when asked, is bound to the executable's bytes and turns nothing on: hooking is the usual
consent dialog afterwards. Under it the Agent tells the Overlay the family before injecting, names it to the guard at
the start and at every 30 s re-scan, and marks the session with it. It ends — hooking off, the block standing, the
reason kept — on a new finding, a safety unhook, the Overlay stopping for another anti-cheat, a crash while hooked, a
game update, or when the user withdraws it; turning the option off suspends every exception without deleting any.
Schema 0014 adds the columns; the database opens in place.
### Changed
- **Legal: Disclaimer 2.7 and EULA 1.3.** Disclaimer §2A describes the user-mode exception and its risk; the EULA's
code-injection clause names it and what making one means. The accuracy block and SECURITY.md say it too. The Legal
Gate shows the two changed documents once more; the Privacy Policy is unchanged (2.4).
## [0.1.0-beta.8] - 2026-09-25
**The eighth pre-release: anti-cheat is found before you ask, a session says what the game and the driver were, and
a frame-generation session's numbers and charts are the application's.** The same unsigned installer: verify its
hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
- **Anti-cheat is looked for harder, and before you ask.** Twenty-two families (74 entries), any kernel driver in a
game's folder, and per-title lists by Steam app id and executable name. The Agent checks every game in your library
on its own, turns hooking off for those with anti-cheat, and their pages show what was found instead of the hooking
switch. Their sessions are still recorded, with play time and sensors.
- **A game's page says what its files say** — 64-bit or 32-bit, the file and store versions, the DLSS / FSR / XeSS
libraries it ships — and a 32-bit game's hooking cannot be turned on.
- **NVIDIA App overrides are shown**: each session records the driver profile the game ran under (DLSS preset and
mode, frame generation, Smooth Motion), read from the driver and never changed.
- **Reasons read as what they are**: End task is not a crash, a refusal says what happened, a launch that could not
start says why, a missing executable says whether its drive is disconnected.
- **Trend works on first open**, with Native and Presented FPS as two metrics, and FPS can show two decimals
(Settings ▸ Window).
- **A frame-generation session's lows, median and stutter are over application frames**, a pause no longer counts as
one long frame, and the charts draw what they say — including the sensors of a session that was not hooked.
- **The Privacy Policy (2.4) is updated**, so the Legal Gate opens once after the update: it now names what the
software reads to check every library game for anti-cheat, the version information of the game's files, and the
NVIDIA driver's settings for your games — all on your PC, none of it sent anywhere.
**Updating from `0.1.0-beta.7`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schemas 0010–0013 add columns; the database opens in place.
- Shortly after the Agent starts it checks every game in your library for anti-cheat, once; a game where it finds
some has its hooking turned off for good, with a notice if hooking was on.
- Sessions recorded before keep the numbers they were stored with; the corrected lows and the in-step sensor overlay
apply to sessions recorded from now on.
### Added
- **FrameLedger finds the anti-cheat games in your library on its own, and hides their hooking switch** (owner decision
2026-09-25). The Agent now scans every game in the library for anti-cheat — once, and again whenever the rules or the
game's executable change — where until now it scanned only a game someone asked to hook, so most games had never
been scanned at all. A game it finds anti-cheat in has its hooking turned off for good, as any finding does, and a
notice says so when hooking had been on. The library card says **Anti-cheat**; the game's page says what was found —
"BattlEye — its module BEClient_x64.dll was loaded in the game", "Easy Anti-Cheat — its folder EasyAntiCheat ships
with the game", in your language — in place of the Hooking switch, which could only be refused. Settings ▸ Capture ▸
*Hide hooking on anti-cheat games* (on by default) brings the disabled switch back beside the finding. Sessions of
such a game are still recorded, with play time and sensors. The scan reads the game's files only: it opens no process
and decides nothing on its own — every session start still runs the full check. Schema 0010 adds three columns; the
database opens in place, and the first scan of the library runs when the Agent starts.
- **The game page has a Details card: what the game's files say about it.** Whether the executable is 64-bit (x64),
32-bit (x86), ARM or .NET "any CPU"; its file and product versions; the store's build ("Steam build 20374416" — the
subtitle labels it that way too, instead of a bare number); the engine; and the upscaler and frame-generation files
it ships with their versions — "DLSS: nvngx_dlss.dll 3.7.10.0", Streamline, FSR, XeSS. FSR is named by its file: its
DLL's version is the SDK's, and FrameLedger does not guess which FSR that is. The capture agent reads every game in
the library once after the update. Schema 0011 adds four columns; the database opens in place.
- **A session's summary lists the libraries the game had loaded** — recorded since the first beta and shown nowhere
until now — and says when one differs from the copy the game ships ("nvngx_dlss.dll 310.2.1.0 (the game ships
3.7.10.0: another copy was loaded, for example by the driver or the NVIDIA App)").
- **FPS with two decimals** (Settings ▸ Window ▸ *Show FPS with two decimals*, off by default): every FPS figure reads
"62.40" instead of "62". Whole numbers now round half up (62.5 is 63); they rounded half to even.
- **FrameLedger says when the NVIDIA App overrides a game's DLSS.** Each session now records the NVIDIA driver profile
the game ran under — read from the driver's own settings, never from the game — and its summary says what that
profile overrides: "NVIDIA profile “…”: DLSS override (preset K, Quality) · Frame Generation override (×4)", Ray
Reconstruction, Streamline's override, a forced frame-generation mode, Smooth Motion. It also says what the driver
reported applying inside the game ("DLSS DLL chosen by the driver · preset K · Quality"), and the game page's Details
card names the overrides from the newest session. These are the driver's settings, not measurements: what FrameLedger
measured is shown as before. FrameLedger only reads these settings; it never changes them. Schema 0012 adds one
column; the database opens in place.
- **A 32-bit game's hooking switch cannot be turned on, and the page says why**: FrameLedger's hook runs in 64-bit
games only. Until now the switch turned on and every launch was refused by the guard. A 32-bit game whose hooking
was already on has it turned off the first time the capture agent reads it; its sessions are still recorded, with
play time and sensors.
### Changed
- **The anti-cheat blocklist names twenty-two families, twice as many, most through more than one signal.** New:
EA AntiCheat, Activision Ricochet (`randgrid.sys` and its `atvi-randgrid_*` services — the family 19_SAFETY carried
as "no data yet" since August), NetEase Anti-Cheat, NetEase Yidun, Nexon Game Security (BlackCipher), TenProtect,
AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion. Existing families gained the groups they
lacked: BattlEye's driver `BEDaisy.sys` and its services, FACEIT's and ESEA's drivers and services, HoYoverse's
`HoYoKProtect.sys` (which the `mhyprot` prefix never matched), Xigncode3's driver and service, Denuvo Anti-Cheat's
driver, GameGuard's folder, files and service, EAC's `start_protected_game.exe` launcher and setup files. 19 entries
became 74 (rules `2026.09.3`). Every new name is documented — SteamDB's file-detection rules (MIT), the vendors'
support pages, LOLDrivers, DRML — and none is measured on a real title yet; each entry's `note` says which. Three
services are deliberately left out because they run outside play and would refuse every session on the machine:
`EAAntiCheatService`, PunkBuster's `PnkBstrA`, and Denuvo's update service.
- **Check 3 is live in both halves, and the per-title lists are seeded** (rules `2026.09.4`, owner decision
2026-09-25). The store half reads the store's own files through a seam the guard owns — `appmanifest_*.acf` in the
Steam library that holds the game, `goggame-<id>.info` for GOG — so nothing is handed in by a caller and nothing is
read from the game. 30 Steam app ids and 33 executable names across nine families are listed: Valve's VAC titles
(CS2, Dota 2, TF2, Deadlock and the older ones), VALORANT and League of Legends, Roblox, Blizzard's online titles,
Call of Duty, Marvel Rivals, NARAKA, FragPunk, Once Human, Delta Force, Arena Breakout: Infinite, HoYoverse's games,
Battlefield 2042/6 and EA SPORTS FC 25/26 — the titles whose anti-cheat leaves nothing of the game's own for the
other checks to find. A game no store names is not refused by this half; a Steam library whose manifests cannot be
read is. Both lists are floored like the families, so a rules file can add a title and never take one off, and the
validator refuses names engines share (`Game.exe`, `Client-Win64-Shipping.exe`…). The AreWeAntiCheatYet bulk list was
considered and declined: community data that outlives a game's anti-cheat would turn hooking off for good.
- **Any kernel driver in a game's folder counts as anti-cheat** (owner decision 2026-09-25). A `*.sys` file in the
install tree that no rule names is reported as "Kernel driver in the game folder" and turns that game's hooking off,
like any finding. Every driver found in a game so far was an anti-cheat's; this catches the next one before anyone
names it. It is code, so no rules file can remove it — and a game that ships a driver for another reason loses
hooking with no way back, which is the trade the owner took.
- **FSR 3's and XeSS's DX11 libraries count as "Supports FSR" / "Supports XeSS"** (rules `2026.09.5`):
`ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` and `libxess_dx11.dll` matched no rule before.
- **The guard holds 256 blocklist entries instead of 64** (2 × 74 no longer fitted the worst case of the compiled-in
floor plus a drifted file). The parsed rules are ~530 KB, so they are now reset in place instead of being copied from
a temporary: the Vulkan layer parses them on whichever of a game's threads creates its Vulkan instance, and a
temporary that size on a small thread stack would crash the game. The native tests hold them on the heap.
### Fixed
- **A frame-generation session's lows, median, min / max, σ and stutter count are over application frames**, as
`03_METRICS` always said they were: they were computed over every present, generated ones included, so a ×2
session's 1% low could sit above its native average, and a game that submits its generated frames in a burst —
the owner's Onimusha demo capture, DLSS frame generation ×3 — read a median of 2,073 FPS at a native 60. Sessions
recorded before this release keep the numbers they were stored with; their charts use the corrected rule.
- **Pausing capture no longer puts a pause-long frame and the paused minutes into the session.** The first frame
after a resume was measured from the last one before the pause; it follows a gap now, and every average is over
the time that was measured. Records lost when the capture agent fell behind are left out of that time the same way,
so an average reads the rate the game ran at rather than the survivors spread over the lost time.
- **The charts are honest about what they draw.** The frametime chart's default line is application frame to
application frame (it was each frame's interval to the generated frame before it), of the one swapchain the
statistics are over (two swapchains' intervals were drawn interleaved); the every-present line no longer draws
0 ms frames after gaps and says that presents are timed at submission; segments are labelled with their settings;
the sensor overlay is in step with the frames (it was drawn from the session's start, tens of seconds early —
schema 0013 records where the first frame sits, so sessions recorded before keep the overlay off). The histogram
is binned over the 0.5th–99.5th percentile with its bars centred on their bins; the percentile curve and its
1% / 0.1% low markers are drawn only where the session has the frames for them, the rule the stat cards follow.
The Sensors charts put power on a watt axis, call the memory plot *Memory*, leave out VRAM readings of 0, give
every line its own colour in the light theme too, and chart **sessions that were not hooked** — their sensors
were recorded and shown nowhere.
- **A game's page updates when one of its sessions finishes** — its sessions, trend and header kept what the page
opened with until it was left and reopened.
- **The Trend tab was blank the first time a game's page opened.** It is drawn at once, on a date axis that keeps its
label and the theme's colours. "Average" is two metrics now — Native FPS and Presented FPS — so a line never mixes
the two, and never shows a presented rate that includes generated frames. Temperatures, loads, power and memory
include sessions recorded without hooking; points that describe only part of their session are drawn hollow; several
hardware changes on one day are one marker.
- **A steady-state frame-generation factor always shows the share of the session it covers** — the average card,
Compare and the Sessions grid's FG× column dropped it. The game header's "Lifetime average" was the last measured
session and is labelled so.
- **Compare**: the best value is highlighted in the accent colour (it was only bold), two values that read the same are
both best, CPU and GPU load are not ranked, the percentile chart spans 0–100 again, and exported PNGs have a solid
background.
- **Ending a game with End task is no longer a "crash".** Every non-zero exit code was one, and Task Manager leaves 1.
A crash is now an exception's exit code or Windows' own crash record, and the session summary says how each session
ended: "crashed (0xC0000005 access violation)", "ended with exit code 1 — what End task and taskkill leave". The
crash safety still counts an early abnormal exit of either kind, so hooking still turns itself off after two in a row.
- **Reasons read as what they are.** Every way a session can end has its own sentence, a refusal that names no
anti-cheat says what happened ("the game is 32-bit…", "the game's process could not be opened") instead of calling
its detail "detected in this game", a launch that could not start says why (for example "the game requires
administrator rights"), and a missing executable says whether its drive is disconnected or the file is gone. A
refusal's details were stored so that a detail could be read as an anti-cheat's name; they are stored in three fixed
places now, and older sessions are read correctly.
- **The NVIDIA bridge's native test could not fail on a machine with an NVIDIA GPU.** It was registered to pass on
its "which branch" line alone, which makes ctest ignore the exit code; its reference-counting check had been failing
on every GPU machine unseen. The check is corrected and a failed assertion now fails the test.
- **Turning hooking on for an Unreal game now sees its `EasyAntiCheat` folder.** The scan that runs when hooking is
enabled was given the executable's own folder — `<game>\<Project>\Binaries\Win64\` for Unreal titles — and scanned
exactly that, while `EasyAntiCheat\` sits at the game's root. The session-time scan always looked at the root, so no
injection was ever allowed by the gap, but the toggle could be switched on and the refusal came only at launch. The
guard now takes the executable and finds the root itself, and also checks the executable's name and its store id.
- **A game blocked for anti-cheat no longer offers "Turn hooking back on" after a crash auto-disable.** The button
could only be refused.
- **19_SAFETY's fixture rule is enforced for every family, not eleven.** A generated test walks every value of the
shipped seed and requires it to match its own family in its own group — which also catches a later row that an
earlier prefix shadows. The rules file's note that called XIGNCODE3's `x3.xem` "not a loadable module" is corrected:
XIGNCODE3 loads it as its loader, so the modules group names it too.
## [0.1.0-beta.7] - 2026-09-23
**The seventh pre-release: a program in the library can be left unrecorded, and Steam's own tools already are.** The
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
user:
- **The game page has a Recording switch.** Off, FrameLedger does not watch for that program at all — no session, no
measurement, no injection — and a session of it that is running stops; sessions already recorded stay. The library
card says **Not recorded**. Use it for a utility that starts with Windows: until now every program in the library was
recorded whenever it ran, at every boot.
- **Steam's own tools already in your library start with it off** — Borderless Gaming, Wallpaper Engine, SteamVR,
Blender, the Steam runtimes and Proton — so a tool imported before 0.1.0-beta.5 stops being recorded without you
doing anything.
- **The Privacy Policy (2.3) and the Disclaimer (2.6) are updated**, so the Legal Gate opens once after the update.
**Updating from `0.1.0-beta.6`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schema 0009 adds one column; the database opens in place, and the Steam tools above are switched off once.
- Sessions a tool recorded before stay in its history; to remove them, remove the entry with *Delete sessions too* —
the import will not add it again.
### Added
- **A library entry can be left unrecorded.** Borderless Gaming starts with Windows, and every program in the library
was recorded whenever it ran — so each boot added a session of it, for as long as it ran, to the playtime totals. The
game page now has a **Recording** switch: off, FrameLedger does not watch for that program at all — no session, no
measurement, no injection — and a session of it that is running stops (sessions already recorded stay). The library
card says **Not recorded**. Entries an earlier import made for Steam's own tools (Borderless Gaming, Wallpaper Engine,
SteamVR, Blender, the Steam runtimes and Proton) start with it off; the import has skipped them since 0.1.0-beta.5.
The Privacy Policy (2.3) says so — a program whose recording is off is not watched — and the Disclaimer (2.6) carries
the updated accuracy statement, including the correction made in 0.1.0-beta.6; the Legal Gate shows both once after
the update. Schema 0009 adds one column; the database opens in place.
## [0.1.0-beta.6] - 2026-09-23
**The sixth pre-release: a game is recorded under its own entry, one entry per game after a drive changes its
letter, a game that is not measured is shown while it runs, and RE Engine and FromSoftware games are detected.** The
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
user:
- **Another game's `Game.exe` is no longer recorded under your entry.** A process that matches an entry by file name
only starts nothing — unless it is that entry's own executable on a drive that changed its letter — so an RPG Maker
game can no longer be recorded under another RPG Maker game's name, twice, as *HELLO, HELLO WORLD!* was under
*Flower in Us*.
- **A game that is not measured is shown while it runs.** Hooking off, refused by the guard, or a process Windows
would not open: the Dashboard shows the game, the time and the temperatures, says why nothing is measured, and the
tray turns to recording-only — until now it said "Nothing is being captured." for as long as the game ran.
- **One entry per game when a drive changes its letter.** Two entries for the same executable under two letters
merge on their own (the older one stays, with both histories); a game updated while its drive had another letter is
followed with hooking off; the library import no longer adds a game again under the new letter.
- **A game removed while it runs keeps its session** (under the entry that holds its executable), and a session file
left behind can no longer stop the Agent at every start.
- **RE Engine and FromSoftware games are detected**, engines are shown by name, and a game added by hand whose
executable is `Game.exe` is named after the game.
**Updating from `0.1.0-beta.5`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- No schema change; the database opens in place. Every game is re-detected once (rules `2026.09.2`).
- Session files in `%LOCALAPPDATA%\FrameLedger\tmp` that beta.5 could not store are stored at the Agent's first start —
under the entry that holds their executable — or dropped with a line in `agent-*.log`; the Agent keeps running either
way.
- An entry that a beta.5 file-name match created for another game keeps its wrong name until you rename it (*Edit…*)
or remove it; its executable path says which game it is.
- A game whose **folder** moved — not only its drive letter — now records nothing until *Change executable* points its
entry at the new file.
### Added
- **RE Engine and FromSoftware games are detected.** Capcom's RE Engine titles (RESIDENT EVIL 2/3/4/7/Village, Devil
May Cry 5, Monster Hunter Rise/Wilds, Street Fighter 6, Dragon's Dogma 2, Onimusha…) by their `re_chunk_000.pak`
archive; FromSoftware's (DARK SOULS II/III, ELDEN RING, Sekiro…) by their `.bhd` + `.bdt` archive pairs. Both are
relative signals — a file layout, not a proof — like every engine rule. Every game in the library is re-detected on
the next sweep. Engines are now shown by name ("RPG Maker MV/MZ", "Unreal Engine") instead of the rule's id
(`rpgmaker_mv`). A game added by hand whose executable says nothing (`Game.exe`) is named after the game — RPG
Maker's own title when the folder carries one, else its folder — instead of "Game".
### Fixed
- **Another game's `Game.exe` no longer runs under a library entry — no wrong name, no second session.** On
2026-09-23 00:16 *HELLO, HELLO WORLD!* (itch) started its RPG Maker runtime, `swiftshader\Game.exe`, and the Agent
matched it by FILE NAME to the only entry named `Game.exe`, *Flower in Us*: it recorded the session under that name,
which created a new "Flower in Us" entry at HHW's path, and an NW.js child process then matched the new entry and
started a second session beside the first (57 s and 56 s). A process that matches an entry by file name only now
starts nothing — unless it is that entry's own executable on a drive that changed its letter, in which case the entry
follows it as before — and the log says once that it is not in the library. The same match can no longer move an
entry onto another game whose `Game.exe` has identical bytes (every RPG Maker MV game ships the same one). One session
per executable, whatever id its entry has; a session that could not be hooked is timed by its own executable instead
of any process with its file name; the resolver says in the Agent's log why a process could not be read; an
unreadable entry is logged once instead of every 15 s. **Changed:** a game whose folder moved records nothing until
*Change executable* points its entry at the new file. The "Flower in Us" entry the old match created stays until you
rename it (it points at HHW's `swiftshader\Game.exe`, the file to measure HHW by) or remove it.
- **One entry per game after a drive letter changes — the two side by side become one.** When the owner's USB drive
came back as `H:` for a morning, a second entry was made for each game played from it, and once the letter was back
neither entry could move onto the other's path: two of each game, and "could not be moved" in the log every 15 s.
Now the Agent merges two entries for the same executable (same path on two letters, same size and modification
time): the entry made first stays, the other's sessions join it, a block on either is kept, and no consent moves
between them — it waits while either game runs. A game whose executable changed on the new letter (it was updated
meanwhile) is followed with hooking off, as *Change executable* does; turn hooking on again to measure it. The
library import no longer adds a game again when it is already in the library under another drive letter. And a
database error during the Agent's 15 s library pass no longer stops the Agent.
- **A game removed from the library while it runs no longer loses its session — or stops the Agent at the next
start.** On 2026-09-22 23:26 and 2026-09-23 00:25 a GIRLS' FRONTLINE 2 session ended `FAULTED` on the database's
foreign key: its entry had been removed (and re-imported) while the game ran, and the session was written under the
id it started with. Each left a `.partial` file, and the recovery that runs at every start would have failed on it
the same way — with no guard, so the Agent's host would have stopped at every start and nothing would have been
captured. Now the session is stored under the entry that holds its executable when the one it started with is gone
(the re-imported entry); when no entry does — the game was removed with its sessions — it is dropped with a log line
that says so. Recovery never throws: a file it cannot finalize is set aside as `<guid>.partial.failed`, kept for a bug
report, and the next file is recovered. The `FAULTED` and end-of-session log lines now name the session, the game and
its executable, and the Agent's host logs its own warnings and errors into `agent-*.log`.
- **A game that is recorded without measuring is shown while it runs.** A game with hooking off, one the guard
refused, or one whose process could not be read is recorded (duration, sensors, the reason) since beta.5 — but the
Agent announced only hooked sessions, so for as long as such a game ran the Dashboard said "Nothing is being
captured." and the tray stayed idle. Now the live card shows it with the T2 badge, the elapsed time, the
temperatures, "Recording duration and sensors only — nothing is measured." and why, in the sentence its summary will
use (no FPS readout: nothing is measured, so nothing is shown); the tray turns to recording-only; the refusal notice
appears when the game starts rather than when it exits. A Dashboard opened after a game started shows it at once
(it used to wait for the next start), a session running when the App connects is in the tray, the notice after a
session names that session's game (it could name the previous one), a session that fails is let go of instead of
staying on the card, and an update downloaded after a session ends is ready to install instead of waiting for the
App to reconnect. A game whose executable changed since hooking was turned on — after a store update, usually — now
says so in its summary instead of `RefusedConsentMissing`.
## [0.1.0-beta.5] - 2026-09-22
**The fifth pre-release: the guard override is gone, Tier 2 exists, and a drive that changes its letter is followed.**
The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for
a user:
- **The "Bypass the anti-cheat guard" switch is removed.** Where FrameLedger finds anti-cheat in a game — before it
injects, when a session starts, or during one — it refuses and **turns hooking off for that game**, says so in the
notice and on the game's page, and offers no way to turn it back on for that executable. The terms say so
(Disclaimer 2.5, EULA 1.2), so the Legal Gate opens once after the update.
- **Sessions that could not be hooked are recorded now.** A refused or hooking-off game gets a T2 row with its
duration, hardware telemetry and the reason — the summary says why ("the guard refused — …", "hooking was off for
this game", "Windows would not let FrameLedger open the process"). Until now every such session was thrown away
within a second.
- **A hooking-off entry that runs as administrator (Borderless Gaming, imported from Steam) no longer gets the
"anti-cheat driver" notice**, and Steam's tools are no longer imported as games. An entry you already have for one
stays until you remove it.
- **A drive that changes its letter no longer loses your games.** The Agent finds the same file under the new letter
and moves the entry to it with its consent kept — within about 15 s in the background, at once when you launch the
game, and when you click the hooking switch. The game's page says when its executable is not where the entry points.
**Updating from `0.1.0-beta.4`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
- Schema 0008 drops the five columns of the removed switch; the database opens in place, nothing else changes.
- Entries whose switch was on lose it; if the guard blocked such a game, its hooking is off and its page says why.
### Removed
- **The per-game guard override ("Bypass the anti-cheat guard") is gone** — owner decision 2026-09-22, two pre-releases
after it arrived. Its first real use could not reach a process an anti-cheat driver protects, and where it could
inject it only exposed the user to the risk its own warning described. Removed entirely: the native entries
(`FlGuardedInjectAcknowledged`, its WhenReady twin, `FlGuardIsJudgement`, reason 28), the `SetGuardBypass` message, the
App's card and dialog, the session mark and its export line, the `Safety_Bypass_*` strings, and schema 0007's five
columns (schema 0008 drops them — the first `DROP COLUMN` in the migration set). Sessions that ran under it keep
`guard-bypass=` in their notes. CLAUDE.md rule 2 reads "there is no override" again; Disclaimer 2.5 and EULA 1.2 say
so, so the Legal Gate opens once.
### Added
- **Tier 2 exists now: a session that could not be hooked is recorded — duration, hardware telemetry and the
reason — instead of being thrown away.** Until 2026-09-22 every refusal returned within a second and the 30 s
minimum discarded it (`Discarded (tier 2, exit=Normal, frames=0)` for every one in the owner's log), so "the session
is still recorded" in the notice was false. The loop now holds a refused session open, ticking the telemetry poller,
until the game exits; the row lands as T2 with N/A everywhere a measurement would be, and its summary says why
("Why: the guard refused — Easy Anti-Cheat (…)", "Why: hooking was off for this game", "Why: Windows would not let
FrameLedger open the process"). The unshipped operator host keeps returning at the refusal.
- **A drive that changes its letter no longer loses your games.** When the drive holding a library comes back as
another letter (the owner's external drive: `D:` one evening, `H:` the next morning), every game on it read
"executable unreadable" and a game launched from the new letter ran as a stranger with no consent. The Agent now
finds the same file — same size, same modified time, under exactly one other drive letter — and moves the entry to
it with consent, block and detection kept: within about 15 s in the background sweep, at once when such a game is
launched, and when you click the hooking switch. The game's page says when its executable is not where the entry
points. *Change executable* is still the way to point an entry at a different file.
- **Steam's tools are no longer imported as games**: Steamworks Common Redistributables, Borderless Gaming, Wallpaper
Engine, SteamVR, the Proton and Steam Linux Runtime entries and Blender are skipped by app id. A row you already have
for one of them stays until you remove it.
### Fixed
- **A hooking-off entry that runs as administrator no longer gets the "anti-cheat driver" notice.** Borderless Gaming,
imported from Steam with hooking off, produced a red "hooking refused" notice on every launch: the Agent tried to
open its process before it looked at whether hooking was on. Hooking-off is decided first now — no process is
opened, no resolver, no gate — and the row gets a quiet Tier-2 session like any other hooking-off game.
### Changed
- **A finding turns the game's hooking off, wherever the guard makes it** (`19_SAFETY` §What a finding does to the game). The
pre-scan always did this; now a finding at a session's start or at the 30 s re-scan writes the same block — hooking
off, the reason on the row, the toggle disabled on the game's page — when it names an anti-cheat *in the game* (its
process, its folder, its title lists). A machine-wide driver or service refuses that session only. The notice says
"Hooking has been turned off for this game", the session's notes carry `hooking-turned-off=`, and `CaptureRefused` /
`SafetyUnhook` carry `hookingTurnedOff`.
- **`0.1.0-beta.4`'s notes named a cause they had no evidence for, and are corrected in place** (see its *Updating*
section). The owner reported afterwards that the external USB drive holding the Steam library had a loose cable that
evening. Windows' System and Application logs for 2026-09-21 agree and re-date the day's symptoms: disk resets and
paging errors on that drive from 20:42; `start_protected_game.exe` (20:56) and `GF2_Exilium.exe` (21:45) both
ended with `0xc0000006`, an in-page I/O error — the drive, not FrameLedger, and **FrameLedger had injected nothing
into ELDEN RING in any run**; the Agent's "executable unreadable" for all 46 titles and the two pipe timeouts at
21:12–21:13 sit inside a burst of 30 disk errors. **What the drive does NOT explain, and beta.4's fixes stand on:**
Easy Anti-Cheat's own log says "successfully loaded in-game" for ELDEN RING at 21:29:28, the second the resolver
found a process it could not open (`TargetUnreadable`); the two App instances started 360 ms apart at 21:07; the
English safety texts and the contradictory line are in the screenshot itself.
## [0.1.0-beta.4] - 2026-09-21
@@ -46,9 +578,13 @@ its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed
**Updating from `0.1.0-beta.3`:**
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer. On 2026-09-21 an
install over a running Agent left a half-replaced folder and the App failed to start three times
(`Could not load … Microsoft.Data.Sqlite`) until it was installed again.
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
> **Corrected the same evening.** This bullet went on to say that on 2026-09-21 "an install over a running Agent left
> a half-replaced folder and the App failed to start three times". **That cause was a guess and the logs do not
> support it**: nothing was installed between the three failed starts (20:59–21:01, `Could not load …
> Microsoft.Data.Sqlite`) and the start that worked at 21:02. What Windows' own event log shows for that hour is a
> failing external USB drive (the owner's report: a loose cable) and two restarts of the PC at 20:57 and 21:02. The
> three failed starts are **unexplained**; the advice to stop the Agent before installing stands on its own.
- The Disclaimer moved to 2.4 (one paragraph about the bypass), so the Legal Gate opens once.
- No schema change. A bypass you already accepted stays on; the new warning text is shown the next time you turn one on.
+9 -7
View File
@@ -11,14 +11,12 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
## Non-negotiable rules
1. **Injection is opt-in, per game, never automatic.** The user must add the game *and* enable hooking for it. There is no "hook everything" mode, no global auto-inject.
2. **The anti-cheat guard is a hard gate, not a warning.** Before injecting, scan the target for known anti-cheat/anti-tamper modules (`19_SAFETY`). If any is found → **refuse**, log, tell the user why. ~~There is no override switch, no "I understand, continue anyway" button. Do not add one.~~
2. **The anti-cheat guard is a hard gate, not a warning.** Before injecting, scan the target for known anti-cheat/anti-tamper modules (`19_SAFETY`). If any is found → **refuse**, log, tell the user why. There is no override switch, no "I understand, continue anyway" button. Do not add one.
> **Amended 2026-09-21 (owner decision): there is exactly ONE override, and its shape is the rule now.** The owner asked for a "bypass the guard" mode at the user's own risk. It exists (`docs/19_SAFETY_AND_ANTICHEAT.md` §The user's bypass) and everything about it is a constraint a PR may not loosen:
> - **Per game, OFF by default, never global.** There is no settings key, no CLI switch, no environment variable, no field in `rules/detection-rules.json` (its schema still makes one a validation error) and no "apply to all". Do not add one.
> - **A recorded human act.** It is turned on only through its own disclosure — which states the ban risk and that the user carries the entire risk and the developers none — accepted by BOTH a ticked acknowledgement and the typed phrase, stamped by the Agent with the disclosure's version, keyed on the executable's fingerprint like consent, and gone when hooking is turned off or the executable changes.
> - **It overrules the guard's JUDGEMENT and nothing else.** The kill switch, a game that was merely added, a missing consent, a foreign payload, a 32-bit target and a failed injection refuse exactly as before. The guard still runs every check, still reports what it found, and the verdict is `AllowedUnderUserBypass` — never `Allow`. A Vulkan title the guard refuses stays refused.
> - **Rule 3 is untouched, and that is the line.** The bypass changes WHETHER FrameLedger injects, never HOW: the same documented `LoadLibraryW`, the DLL's real name, exports and version info, in one chokepoint file. Nothing about it makes FrameLedger harder for anti-cheat to see, and a PR that did would still be rejected on principle.
> - **It is visible afterwards.** A session that started under it is marked on its row, with what the guard found, on every surface and in every export.
> **Amended 2026-09-22 (owner decision): the override of 2026-09-21 is withdrawn, and the sentence above is the rule again.** For one day (releases `0.1.0-beta.3` and `beta.4`) a per-game override existed. The owner withdrew it: no entry point, no message, no column (schema 0008 drops 0007's five), no string. Do not add one in any form.
>
> **A finding turns the game's hooking off** (`19_SAFETY` §What a finding does to the game). An anti-cheat named in the game itself — its process, its title lists, its folder — is written to the row exactly as the pre-scan always wrote it (`hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`), and since 2026-09-22 also when the guard finds it at a session's start or at the 30 s re-scan (`AntiCheatVerdict.IsFindingAboutTheGame`). A machine-wide driver or service refuses that session only. The notice, the game's page, the session's notes and the Agent's log all say it happened. Nothing clears the block, as before.
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
3. **Never implement evasion.** No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented `LoadLibraryW`. The DLL keeps its real name, real exports, and version info. A performance tool must be *visible* to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle.
4. **Never read or write game memory outside our own hooks.** We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
5. **The hook must never crash the game.** Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (`17_HOOK_ENGINE` §Fault policy).
@@ -178,6 +176,10 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
8. `docs/18_GPU_VENDOR_APIS.md` — layered GPU telemetry (DXGI/PDH · LHM · NVAPI) + vendor-SDK licence rules
9. `docs/06_DATA_MODEL.md` · `docs/07_IPC.md` · `docs/08_UI.md` · `docs/16_WPFUI_SYNTAX.md`
10. Remaining (`09`–`15`).
11. **`LIMITATIONS.md`** (repository root; shown in the App under Help ▸ Limitations) — what the WHOLE software cannot
do, in the user's words, each item linked to its details. When a change moves a limit, the page changes in the same
PR (D36, 2026-09-27). **`docs/LIST_GAME_TESTED.md`** — the real games FrameLedger has been run with and what each
session measured, from a copy of the owner's ledger and the repository's own evidence (D35).
**Before writing native or capture code, read `docs/20_OPEN_QUESTIONS.md`.** It
lists the defects and gaps that survived the doc audit — things the other
+129
View File
@@ -0,0 +1,129 @@
# What FrameLedger cannot do
FrameLedger measures a game by loading a small component into it — only for a game you added and switched
hooking on for — and reading the graphics calls the game makes. That is why it can tell the real render
resolution, the upscaler, frame generation and ray tracing apart. It is also where its limits come from. This
page lists them in plain words; each item links to the document that has the details.
*Beta software: this page describes version 0.1.0-beta.10.*
## Games it will not measure
- **Games with anti-cheat.** FrameLedger looks for anti-cheat before it touches a game and refuses when it
finds one — there is no switch that overrides this. The one exception is an anti-cheat that runs entirely
inside the game (no driver, no service), which you can allow per game after a warning and two good
sessions; a ban is still possible and may come days later. Kernel anti-cheat is never allowed.
([Safety](docs/19_SAFETY_AND_ANTICHEAT.md))
- **Anti-cheat FrameLedger does not know about.** The list of anti-cheat products is FrameLedger's own and
can be incomplete. A game protected by something unknown may be hooked; that is a risk to your account
that you take by switching hooking on.
- **32-bit games and Direct3D 9 games.** Only 64-bit Direct3D 11, Direct3D 12 and OpenGL games are measured
from their own calls; a 32-bit or Direct3D 9 game is recorded without measurement.
- **Vulkan games, unless FrameLedger starts them.** A Vulkan game is measured only when FrameLedger launches it
with its Vulkan layer switched on; one started another way is not observed by the layer.
- **Games that run as administrator,** unless you turn on *Run the agent as administrator* in Settings
(off by default; Windows asks every time the agent starts). **A process Windows protects** stays closed
either way.
- **Vulkan games that run as administrator.** Windows' Vulkan loader does not load FrameLedger's Vulkan
layer into an elevated game, so admin mode does not help there.
- **A game that was already running when FrameLedger was updated** — restart the game once.
- **Games you did not switch hooking on for.** Adding a game only records its sessions; measuring it is a
separate, per-game choice with its own warning.
## What an unmeasured session contains
When a game is not measured — any of the reasons above — its session still records **how long it ran, the
machine's sensors (GPU temperature, load, power; CPU load; memory) and why nothing was measured.** Every
frame-rate, upscaler, frame-generation and ray-tracing value reads **N/A**, never 0. How the game's window was
shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
## Frame rate and frame generation
- **One inflated number is never shown.** When frame generation is measured, the page shows the game's own
frames and the displayed frames together (`62 → 118 FPS (×1.9 FG)`). When it cannot be measured, the page
shows **Presented FPS** with a sentence saying whether generated frames could be included.
- **Frame generation done by the driver outside the game** (AMD Fluid Motion Frames, NVIDIA Smooth Motion)
is not visible to FrameLedger; the rates shown are what the game presented.
- Frame generation is counted on **Direct3D games** only. DLSS Frame Generation and FSR frame generation are
named from the calls the game makes; any other generator is shown only as *active*, never named, and where
the generated frames cannot be counted the page shows Presented FPS with a note instead of a factor.
- **A session whose frame generation changed** (menus, loading, a settings change) shows the factor of the
state it spent most of its time in, with the share of the session it covers — never an average of the two.
([Metrics](docs/03_METRICS.md))
## Upscaling and ray tracing
- The upscaler is read from the game's calls: DLSS and NIS through NVIDIA Streamline, and FSR through AMD's
FidelityFX libraries. **Intel XeSS is not read** (its licence forbids it), FSR 2 and upscalers built into the
game are not identified, and Vulkan and OpenGL games read N/A. Where no hook saw DLSS but the NVIDIA driver
reports it, the page says it is the driver's report.
- **The quality preset** (Quality, Balanced, …) has not been reported on any game yet, and the render
resolution is N/A where the game's own calls do not carry it (DLSS without Streamline, for one).
- **Ray tracing** is *Yes*, *No* or *N/A* — measured from the game's ray-tracing calls on Direct3D 12, and
N/A where FrameLedger could not look. **Path tracing is never stated as a fact**: there is no API signal
for it. You can correct any of these by hand, and your correction is labelled as yours.
- HDR output, NVIDIA Reflex latency, each game's own video-memory use and shader-compilation stutter are
**not measured yet** — they read N/A. Video memory in use on the whole graphics card is recorded.
([Accuracy](legal/ACCURACY.md))
## Display mode (full-screen, borderless, windowed)
- **Exclusive full-screen is known only for a measured Direct3D (DXGI) game** — the game's own swap chain
says so. For OpenGL, Vulkan and unmeasured games, a window covering the screen reads *Fullscreen or
borderless*, never either one.
- **What Windows does behind the game is not visible:** a game in exclusive full-screen may still be shown
through Windows' compositor ("fullscreen optimizations"), and a game's menu may call a borderless window
"Fullscreen". FrameLedger reports what the game asked for.
- The mode is sampled ten times a second in a measured session and once a second in an unmeasured one; very
short switches can be missed. A session recovered after a crash, and every session recorded before
beta.10, read N/A. ([Display mode](docs/03_METRICS.md#display-mode--both-tiers-beta10))
## Engine version
- The exact version is read for **Unreal Engine 4 and 5** games, from the game's executable file on disk.
A studio can remove or rename what it is read from; then the page says the version was not found.
**Unreal Engine 3 and older are not recognised.** Other engines show a version only where their files
state one. ([Detection](docs/05_DETECTION.md))
## Sensors
- GPU temperature, load, power and memory are best supported on **NVIDIA** GPUs. **AMD and Intel GPUs have
not been tested** on real hardware yet.
- **CPU temperature** needs *Run the agent as administrator* and the separately installed PawnIO driver, and
has not been verified on real hardware yet. CPU load is the time the processor was busy — not Task
Manager's "utility" figure, which can exceed 100%. ([Telemetry](docs/18_GPU_VENDOR_APIS.md))
## Running the agent as administrator
Off by default. When on, **Windows asks every time the agent starts** and names an unknown publisher, because
FrameLedger is not signed. It lets FrameLedger open games that run as administrator and read the CPU
temperature; it does not bypass anti-cheat, does not open protected processes, and does not make games you
start from FrameLedger run as administrator. **The risk:** FrameLedger is installed in your user folder, so a
program running under your account could replace its files and would then run as administrator the next time
you accept the prompt. Turn it on only if you trust everything that runs under your account.
([Architecture, ADR-9](docs/01_ARCHITECTURE.md))
## Platform and what has been tested
- **Windows 10 22H2 or Windows 11, 64-bit only.**
- The games FrameLedger has actually been run with, and what was measured on each, are listed in
[LIST_GAME_TESTED.md](docs/LIST_GAME_TESTED.md). Everything was measured on one machine (an NVIDIA
GeForce RTX 5080 with an Intel Core i7-14700KF on Windows 11); other hardware is untested.
- **No real Vulkan or OpenGL game has been measured yet** — only FrameLedger's own test program.
- There is **no in-game overlay**; everything is shown in the FrameLedger window.
## Your data
- Everything stays on your computer (`%LOCALAPPDATA%\FrameLedger`). FrameLedger sends no telemetry; its only
network requests are the update check and the update download, both to GitHub, and the check can be switched
off. The anti-cheat list and the detection rules ship with each version — **a newer list reaches you only with
the next update.** ([Privacy policy](legal/PRIVACY_POLICY.md))
- Per-frame data is kept for the **last 20 sessions of each game** (configurable); older sessions keep their
summaries.
- A newer version upgrades the database in place, and an **older version cannot open it again** — there is
no downgrade.
## Installation
FrameLedger's programs are **not code-signed**: Windows SmartScreen may warn when you install it, and the
administrator prompt names an unknown publisher. Each release publishes SHA-256 checksums you can compare.
+33 -19
View File
@@ -5,12 +5,12 @@
> No telemetry. No accounts. All data stays on your machine.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-21.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.4`** (2026-09-21), an unsigned installer built from that tag with its
> ⚠ **What FrameLedger actually measures today — 2026-09-28.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.10`** (2026-09-28), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs, injects only into games you enabled and only past the safety guard (or,
> for a game whose guard bypass you turned on yourself, past your own acceptance of that risk), and
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> and only past the safety guard, and
> stores sessions in a local database. What that path measures:
>
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
@@ -23,8 +23,10 @@
> NVIDIA Streamline (with Ray Reconstruction Yes/No), and FSR through AMD's shipped FidelityFX DLLs:
> named FSR 3 from the older DLLs, and FSR without a version from the newer ones, which host both
> FSR 3.1 and FSR 4. FSR 2, and FSR shipped any other way, is not identified. For DLSS titles that
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session, labelled
> *driver-reported*; the app does not display it yet. Intel XeSS is **not** read (its SDK licence
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session and shown
> as *DLSS (driver-reported)*. The NVIDIA driver's profile for the game — the DLSS and frame-generation
> overrides the NVIDIA App sets — is read, never changed, and shown as the driver's settings beside what
> was measured. Intel XeSS is **not** read (its SDK licence
> forbids it), and neither is an upscaler compiled into the game: those read `N/A`, or "Unknown
> upscaler" when another vendor's hook ran in the game. Vulkan and OpenGL titles read `N/A`.
> - **Quality preset:** not reported on any title measured. The one route this software may use — the
@@ -45,9 +47,18 @@
> FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled into the game)
> is shown only as active with the technology not identified, and is never named. Where a technology is
> named but its frames could not be counted, or frame generation is not measured, the software shows
> **Presented FPS** with a note on what it may include — never a Native figure.
> **Presented FPS** with a note on what it may include — never a Native figure. Where generated frames
> were counted, the lows, median and stutter are taken over application frames only.
> - **Ray tracing:** Yes/No measured on Direct3D 12 from ray-dispatch and acceleration-structure-build
> calls; the technique and path tracing are `N/A`, and so is ray tracing on other APIs.
> - **Display mode:** how each game's window was shown — exclusive full-screen, borderless, windowed or
> minimised — as a share of the session, with the window's size and the monitor's, in every session.
> Exclusive full-screen is known only for Direct3D titles FrameLedger injects into, from the game's own
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
> files state.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
@@ -55,17 +66,20 @@
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
> administrator with PawnIO installed, and that reading has not yet been checked on real hardware;
> everywhere else it is `N/A`.
> administrator — an option, off by default, for which Windows asks at every start of the Agent — with
> PawnIO installed, and that reading has not yet been checked on real hardware; everywhere else it is `N/A`.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
> goes passthrough. A global switch in Settings turns all hooking off, and a running capture stops at
> its next check; it can only refuse, never permit. **There is one override, and only one:** a per-game
> "bypass the anti-cheat guard" switch, off by default, that you can turn on only by accepting its own
> warning (a tick and a typed word). With it on, FrameLedger injects into that game even where the
> checks find anti-cheat, the 30 s re-check no longer stops the capture for that finding, and every
> session started that way is marked. It never changes HOW FrameLedger injects: nothing is hidden.
> its next check; it can only refuse, never permit. **There is no override.** A finding about a game — anti-cheat
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
> runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
@@ -101,7 +115,7 @@ FrameLedger is built to keep that risk small and to be honest about it:
| Safeguard | |
|---|---|
| **Off by default** | Injection is disabled for every game until you enable it individually, after a consent prompt |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>**One narrow exception since beta.9 (owner decision D33):** per game, after its own disclosure and only while a Settings option (off by default) is on, a game whose only finding is one anti-cheat that runs entirely in user mode — no driver file in its folder, on no title list — and that FrameLedger has measured successfully at least twice may be hooked under a user-mode exception. The guard still runs every check under it, refuses anything else it finds, and ends it on anything new; a ban remains possible (`legal/DISCLAIMER.md` §2A).<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **No evasion, ever** | FrameLedger does not hide, rename, obfuscate, or disguise itself. It keeps its real name, real exports, and version info. It is meant to be plainly visible to any security software that looks. This is an architectural rule, not a setting |
| **Read-only** | It never reads or writes game memory, never modifies game behavior, never touches saves or input, and never changes GPU clocks, fans, or power limits |
| **Always a way out** | FrameLedger refuses rather than pushes through. When the guard finds anti-cheat, or the hook fails, or you have not enabled a game, it **stops** — and records the session anyway: start, end, duration, whatever hardware sensors your machine provides, and the reason there is nothing else. Every measured value reads `N/A`; it never estimates one.<br><br>**The way out is that it does not inject, not that it measures another way.** An earlier version of this row promised a no-injection measurement mode. It was designed around Intel PresentMon, that was dropped on 2026-08-27 after measurement, and no replacement was chosen — so **frame times require hooking**. Said in this row rather than a footnote because the row is in the SAFETY table, and a reader deciding whether to enable a game needs the real alternative, not a comfortable one |
@@ -124,11 +138,11 @@ The tier is recorded on every session and shown in the UI. Metrics unavailable a
| Component | Runs as | Role |
|---|---|---|
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
| `FrameLedger.Agent.exe` | Standard user (elevation optional) | Injection control, safety guard, data collection, GPU telemetry, storage |
| `FrameLedger.Agent.exe` | Standard user — as administrator only when you turn that on in Settings, and Windows asks at every start (beta.10) | Injection control, safety guard, data collection, GPU telemetry, storage |
| `FrameLedger.Overlay.dll` | Inside the game | C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks |
| `FrameLedger.VkLayer.dll` | Inside the game | Vulkan implicit layer (Vulkan titles use this instead of injection) |
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (not read yet — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on.
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (~~not read yet~~ read with PawnIO, not yet checked on real hardware — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on. **Since beta.10 it is a choice in Settings** — *Run the agent as administrator*, off by default: Windows asks every time the agent starts, games you start from FrameLedger still run as you, and `LIMITATIONS.md` says what it does not change.
## Requirements
@@ -138,7 +152,7 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
## Install
> **The latest pre-release is `v0.1.0-beta.4` (2026-09-21); before it `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
> **The latest pre-release is `v0.1.0-beta.10` (2026-09-28); before it `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
1. Download the latest `FrameLedger.App-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases). It installs into `%LOCALAPPDATA%\FrameLedger.App`; your data stays in `%LOCALAPPDATA%\FrameLedger`, and uninstalling asks before touching it.
2. SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then **More info → Run anyway**.
@@ -166,4 +180,4 @@ If you find a game with anti-cheat that FrameLedger fails to detect, please open
---
**Status:** pre-release (beta). Four tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
**Status:** pre-release (beta). Ten tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
+27 -6
View File
@@ -23,13 +23,34 @@ to refuse, never how to evade (`docs/19_SAFETY_AND_ANTICHEAT.md`).
This is a one-person project. The intent is to acknowledge a private report within a week and to say
plainly what will happen next; that is an intent, not a contractual response time.
## The guard bypass is a feature, not a vulnerability
## The guard has no override
Since 0.1.0-beta.3 a user can overrule the anti-cheat guard for one game through a disclosure they must accept by two
separate acts (`docs/19_SAFETY_AND_ANTICHEAT.md` §The user's bypass). That is documented behaviour. What IS a security
report: any way to reach an injection past the guard WITHOUT that disclosure having been accepted for that game — a
flag, a setting, a crafted rules file, a pipe message, a database edit the Agent then honours without the stamp's
version — or any session that ran under the bypass and is not marked as such.
For two pre-releases (0.1.0-beta.3 and beta.4) a user could overrule the anti-cheat guard for one game through a
disclosure. That switch was withdrawn on 2026-09-22 (`docs/19_SAFETY_AND_ANTICHEAT.md` §What a finding does to the game): a finding
now turns the game's hooking off. What IS a security report: any way to reach an injection past a refusal — a flag, a
setting, a crafted rules file, a pipe message, a database edit the Agent honours — or a finding about a game that
does not turn its hooking off.
Since 0.1.0-beta.9 one narrow exception exists (owner decision D33, `docs/19_SAFETY_AND_ANTICHEAT.md` §The user-mode
exception): per game, only for one anti-cheat family that is user-mode throughout, with the guard still running every
check. The grant is a record in your own database, like the consent stamp; what keeps it narrow is the guard, which
decides itself which family it may let through. So these are security reports too: the guard letting through a family
that has a driver, a service or a `.sys` in the floor or the rules; an exception applying to a game with a kernel
driver in its folder, on a title list, or with a second anti-cheat; the Agent writing a grant on a pipe message
without its own tolerant pre-scan and session count; an exception that survives a new finding, a crash or safety stop
under it, or a changed executable; and the Overlay tolerating a family the guard did not.
## Running the agent as administrator
Since 0.1.0-beta.10 the capture agent can run as administrator — an option, off by default (owner decision D34,
`docs/01_ARCHITECTURE.md` ADR-9) — and Windows asks at every start of the agent. The residual risk is stated to the user
rather than solved: FrameLedger installs per user and unsigned, so a program running under the same account could replace
its files and be run as administrator when the user next accepts the prompt. What IS a security report: any way the
agent becomes administrator WITHOUT that prompt (a task, a service, an inherited token the option did not choose); a game
or any other program that an elevated agent starts with its own token instead of the desktop shell's; any privilege the
agent enables (none is — `tools/chokepoint-check.ps1` forbids the enablers under `src/`); an elevated agent that runs for
another account than the one that asked; and a named object an elevated agent creates that the same user's unelevated
processes can no longer open, or that another user can.
## A safety gap — a game with anti-cheat that FrameLedger fails to detect
+14
View File
@@ -142,3 +142,17 @@ covers\*.jpg
- **ADR-7 (2026-07, core change):** **Capture moves to in-process graphics-API hooking**, C++20 DLL + MinHook, with a Vulkan implicit layer for Vulkan. Rationale: passive detection of DLSS/upscaling/frame-generation/RT state showed large errors against real games; those states are only knowable at the API boundary. Trade-offs accepted: anti-cheat exposure (mitigated by the hard guard in `19_SAFETY`, offline titles only), crash risk in the host process (mitigated by SEH guards + fault policy + auto-disable), a second toolchain in the build, and per-API maintenance as vendors change SDKs. Scope limited to titles the user explicitly opts in.
- **ADR-8:** **No evasion, ever** (`19_SAFETY` §What we will never build). This is an architectural constraint, not a preference — it defines what "correct" means for this codebase.
- **ADR-9:** Elevation demoted from required to optional; the Agent runs as a standard user by default.
**Chosen, not inherited, since beta.10 (owner decision D34, 2026-09-27):** Settings ▸ Capture agent ▸ *Run the agent as
administrator* (`capture.run_elevated`, off by default, a versioned disclosure — `agent-admin-dialog/1` — before it turns
on). With it on, **Windows is asked every time the Agent starts** — a UAC prompt owned by the App's window when the App
starts it, flashing on the taskbar when the logon task does — and there is no silent path: no "highest privileges" task,
no service. The elevated Agent is started for one user (`--serve --for-user <SID>`) and refuses to run as another
account (exit 11: a standard user answered with an administrator's password, and that account's `%LOCALAPPDATA%` is not
this user's ledger); a declined prompt leaves a standard user's Agent that says so (`--elevation declined`,
`HelloAck.ElevationOutcome`). With it off, an App started as administrator starts the Agent with the desktop shell's
token. **A game an elevated Agent starts gets the shell's token too** (`Infrastructure.Startup.UnelevatedProcess`) —
`LaunchGame` reaches the Agent over a pipe any process of the user may open, so an elevated launch would be a silent
elevation — and nothing enables a privilege (`TokenPrivileges` reads them; `tools/chokepoint-check.ps1` forbids the
enablers under `src/`). It buys what it always did: attaching to a game that runs as administrator, and the CPU
temperature with PawnIO. It does not open a process an anti-cheat driver protects (D21), and a Vulkan game that runs as
administrator stays unmeasured — the Khronos loader ignores the HKCU implicit layers for an elevated process.
+12 -5
View File
@@ -10,13 +10,15 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable.
- FR-1.4 Remove game (asks whether to keep or delete its sessions).
- FR-1.5 "Supports" row shows shipped-capability hints (DLSS/FSR/XeSS/FG) — visually distinct from measured per-session values (`05_DETECTION` §Capability hints).
- FR-1.6 Recording switch per entry (2026-09-23, HANDOFF D29): off, the program is not watched at all — no session, no measurement, no injection — and a session of it that is running stops. On by default; entries an old import made for Steam's own tools start with it off. The library card says "Not recorded".
### FR-2 Hooking consent & control (new, safety-critical — see `19_SAFETY`)
- FR-2.1 Hooking is **off by default for every game**. Enabling requires a per-game consent dialog stating what is injected, why, and the anti-cheat/ban risk.
- FR-2.2 The static anti-cheat pre-scan disables the toggle outright for titles shipping anti-cheat; the reason is shown and the control is not clickable.
- FR-2.3 The runtime guard refuses injection and refuses to continue a session when anti-cheat is detected. **No override exists anywhere in the UI, config, or CLI.**
- FR-2.2 The static anti-cheat pre-scan disables the toggle outright for titles shipping anti-cheat; the reason is shown and the control is not clickable. Since 2026-09-25 (beta.8, owner decision) the Agent runs that pre-scan over every library entry itself — once per rules version and executable, whether or not hooking was ever asked for — and by default the game's page shows only the finding in place of the Hooking card (Settings: *Hide hooking on anti-cheat games*, `ui.hide_anticheat_hooking`); the library card says "Anti-cheat". The reason is always on the page (`19_SAFETY` §What a finding does to the game).
- FR-2.3 The runtime guard refuses injection and refuses to continue a session when anti-cheat is detected. **No override exists anywhere in the UI, config, or CLI.** *(Since 2026-09-26 one narrow, evidence-bound exception exists — FR-2.8. It is not an override: the guard still runs every check and decides itself which anti-cheat family it may let through.)*
- FR-2.4 Global "disable all hooking" kill switch in Settings; also honored by the Vulkan layer.
- FR-2.7 (owner decision 2026-09-21) A per-game **"bypass the anti-cheat guard"** switch, off by default, never global. Turning it on requires its own disclosure — naming the ban risk and that the user carries the entire risk and the developers none — accepted by a ticked acknowledgement AND a typed phrase, stamped by the Agent. It overrules the guard's judgement only (`19_SAFETY` §The user's bypass lists both sides), never changes how FrameLedger injects (CLAUDE.md rule 3), and every session started under it is marked as such permanently.
- 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.
@@ -57,8 +59,9 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-6.5 Session tags and notes.
### FR-7 Detection
- FR-7.1 Static: engine, engine version, store platform, store id, publisher, game version (`05_DETECTION`).
- FR-7.2 Runtime: API, present mode, swap effect, HDR, upscaler, FG, RT — all Tier 1, all measured.
- FR-7.1 Static: engine, engine version, store platform, store id, publisher, game version (`05_DETECTION`; the Unreal Engine version since 2026-09-27, §Engine version).
- FR-7.2 Runtime: API, present mode, swap effect, HDR, upscaler, FG, RT — all Tier 1, all measured. (Present mode and HDR have no writer yet, `05_DETECTION` §Runtime facts; swap effect is written since beta.10 from the display-mode sample.)
- FR-7.4 Display mode (beta.10, owner request 2026-09-27): how each session's game was shown — exclusive fullscreen, borderless, windowed, minimised, or *fullscreen or borderless* where nothing could tell the two apart — as a share of the session's time, with the window, back buffer and monitor sizes; both tiers (Tier 2 from the window alone); shown on the session summary, the game page, the Trend (three share metrics) and Compare, and exported (`03_METRICS` §Display mode).
- FR-7.3 Rules ship as `detection-rules.json`, updatable independently of releases; **anticheat-block updates apply regardless of the user's rules auto-update preference.**
### FR-8 Tri-state flags
@@ -72,6 +75,10 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-9.3 Chart PNG.
### FR-10 Settings
> **beta.10 (D34):** "Agent elevation (optional — explains what it unlocks)" is the admin mode — *Run the agent as
> administrator*, off by default, a disclosure before it turns on, Windows' prompt at every Agent start (`01_ARCHITECTURE`
> ADR-9, `08_UI` §Settings).
Language (en/vi/ja), theme, start with Windows, minimize to tray, background capture, **global hooking kill switch**, min session length, telemetry interval, retention, Agent elevation (optional — explains what it unlocks), Vulkan layer registration state, update channel, online metadata opt-in, reopen legal documents.
### FR-11 Legal Gate
+99 -1
View File
@@ -55,8 +55,32 @@ entirely rather than counted as one long frame. Including it would fabricate a
stutter — the exact artifact these metrics exist to detect honestly. Gaps count
toward the session's data-quality warnings.
> **Since beta.8 a pause is a gap, and a gap is not time either.** The Overlay records nothing while FR-3.9's pause
> holds, so the first record after the resume is QPC-apart from the last one before it by the whole pause: counted, a
> fabricated minutes-long frame in every statistic — the Overlay's own comment on its pause check (`MayObserve`) names that
> artefact — and paused minutes in every average. `CaptureSession` reads the QPC as it tells the ring to resume and marks
> a gap before the first record stamped at or after it (`CaptureSessionTests.TheFirstRecordPresentedAfterAResumeFollowsAGap`,
> red before the fix). And **`D`, the time base of every average, is the time the kept intervals span** — first to last
> present less every interval a gap sat in (`FrameTimeSeries.MeasuredSeconds`, `FgWindow.Seconds`): Presented FPS is
> the kept intervals over the seconds they span, and Native / Displayed leave the gaps out of their seconds too. For
> lost records this reads the survivors' rate (a drop is the Agent falling behind, not the game) where it read the
> survivors spread over the lost time — a rate nobody measured; with no gap nothing changes.
**Lows use application frames only.** Generated frames smooth display cadence but do not represent simulation stalls; mixing them hides real stutter. A secondary "Displayed 1% Low" is stored for the Displayed chart series but never replaces the headline.
> **And since beta.8 (2026-09-25) they are computed that way — until then they were not.** Where generated frames were
> counted (`fg_mode` a technology, or `active`), `SessionAggregator` took the median, the lows, min / max, σ and the stutter
> rule over every present of the dominant stream: the 1% low of a ×2 session sat above its native average, and on the
> owner's Onimusha demo capture (DLSS FG ×3, which submits each generated frame half a millisecond after its application
> frame) the stored median read **2,073 FPS on a 60 FPS game**. `ft_app` is now `Domain.Metrics.FrameTimeSeries.ApplicationFrames`:
> the interval between two consecutive presents that carried an application frame's token, the generated presents between
> them adding no interval of their own; a gap or a present that does not claim the count breaks the chain. The segments'
> lows follow; the Displayed 1% low stays over every present. **A technology named and no application frame counted**
> (`no_evaluations`, `not_counted`) has no frame statistic at all — N/A rather than a low over presents that include
> generated frames. Per-present attribution is accurate to one present (§Frame Generation); it was measured regular —
> application, generated, generated, repeating — on that capture. **Rows written before beta.8 keep their stored
> numbers**, as with the steady state (#198); their charts are drawn from the blob with the new rule.
> **When frame generation is NOT measured, the lows are taken over presents and labelled
> `(presented)`** — added 2026-09-03 with Presented FPS. On a title with no in-process frame
> generation that is exactly the application-frame low; on one that generates frames through a
@@ -477,6 +501,15 @@ carries the three shapes.
## Upscaling — measured, not guessed (Tier 1)
> **The NVIDIA driver's overrides are a configuration, not a measurement (beta.8, 2026-09-25).** A session now also
> stores the driver profile its executable ran under (`sessions.driver_profile`: the NVIDIA App's DLSS, Ray
> Reconstruction and frame-generation overrides, read from the driver's settings store — never from the game's process
> or memory, CLAUDE.md rule 4) and the driver's own per-process override report in full (`ngx_driver_words`: preset,
> mode, ratio beside the masks). Both are shown as what the driver was set to do and what it says it did — "NVIDIA
> profile …: DLSS override (preset K, Quality)" — and neither changes a measured value, a rung of the upscaler ladder or
> the frame-generation factor: those stay what the hooks saw. A profile override the hooks contradict is two true
> statements about different things, and the page shows both.
From the upscaler hooks we get, per frame:
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`) — from the API that was called, not from a DLL sitting on disk.
@@ -648,6 +681,70 @@ Derived extras (Tier 1): `rays_per_pixel` (mean dispatch volume ÷ output pixels
> 2026-08-20 `maxTraceRecursionDepth` has no producer: `CreateStateObject` is a separate PR,
> and `pt_confidence` reads it, which is one of the reasons Path Tracing is still `N/A`.
## Display mode — both tiers (beta.10)
**Owner request, 2026-09-27:** "detect the game's window size and whether it runs full-screen, borderless or windowed,
and how much of the time". Schema 0016 (`06_DATA_MODEL`), shared-memory region 4 (`07_IPC`, layout 4), the Agent's
`Application.Capture.DisplaySampler`, Domain's `Display.DisplayModeClassifier` and `Display.DisplayTally`.
**Two witnesses, and neither reads the game.**
1. *The swap chain's own answer* — Tier 1, DXGI only. The Overlay asks `IDXGISwapChain::GetFullscreenState` and `GetDesc`
on the chain the game passed to `Present`, at most twice a second per chain, and publishes the chain with the largest
back buffer in region 4: its window, back buffer, swap effect, and whether it is exclusive (`17_HOOK_ENGINE` §Hook
inventory — polled, not a `SetFullscreenState` hook). OpenGL publishes its window and client area with no exclusive
answer; the Vulkan layer publishes nothing yet.
2. *The window from outside* — both tiers. The Agent asks user32 about the game's top-level window: minimised or not, the
client area in screen coordinates, the monitor it is on and that monitor's refresh rate — per-monitor DPI aware while it
asks, because the Agent runs DPI-unaware and Windows would otherwise scale another process's coordinates
(`Infrastructure.Display.WindowGeometryProbe`). The window is the one region 4 names when it still belongs to the game
(a handle is reused once its window is gone), else the largest visible, uncloaked, non-tool top-level window of any
process running the game's executable — found by image path in the watcher's snapshot for a Tier-2 session that never
opened the process. This is the focus sample's class of question: CLAUDE.md rule 4 is about game memory, and no handle
to the game's process is opened for it.
**The ladder, per sample** (`DisplayModeClassifier`):
| Mode | When | Column (ms) |
|---|---|---|
| No window | no window could be read and the chain did not say exclusive | `display_nowindow_ms` — outside every share |
| Minimized | the window is minimised | `display_minimized_ms` |
| Exclusive fullscreen | a region-4 sample under 2 s old in which the swap chain SAID exclusive | `display_exclusive_ms` |
| Borderless | the client area covers its monitor (±1 px each edge) and the chain said not exclusive | `display_borderless_ms` |
| Fullscreen or borderless | the client area covers its monitor and nothing could say which — OpenGL, Vulkan, every Tier-2 session | `display_covers_ms` |
| Windowed | anything else | `display_windowed_ms` |
**Time, not ticks.** A sample stands for the wall time until the next: every drain tick (100 ms) hooked, every hold tick
(1 s) at Tier 2 — so the two add up in one unit, milliseconds. An interval that ends on a paused tick is dropped, which
excludes a pause to within one tick at each edge, as the frame series' gap does. A mode's **share** is its milliseconds
over the observed time (every mode but *No window*). `display_changes` counts samples whose mode differs from the one
before, no-window samples skipped. The sizes — `display_window_*` (client area), `display_buffer_*` (back buffer),
`display_monitor_*` and `display_monitor_hz` — are the ones seen in the mode that lasted longest; `display_source` is the
strongest witness any sample had (`swapchain` > `opengl` > `window`). `sessions.swap_effect`, a column since 0001 with no
writer, is written from region 4.
**What it cannot say** (the user-facing list is `LIMITATIONS.md`):
- *Exclusive* is what the game asked DXGI for. Windows may still present such a game through the compositor ("fullscreen
optimizations"), and a flip-model borderless window may be promoted to independent flip; neither is visible without a
trace session, which FrameLedger does not have (`20_OPEN_QUESTIONS` §G).
- A game's menu may call a borderless window "Fullscreen"; the swap chain's answer is what is reported.
- A minimised game issues only occlusion probes, which the hook drops before sampling: a region-4 sample older than 2 s
keeps its window and loses its exclusive bits.
- Tier 2, OpenGL and Vulkan can never tell exclusive from borderless. Their covering time is *Fullscreen or borderless*,
and the trend draws no exclusive or borderless point for a session with any of it.
- A session recovered from its `.partial` file has no display facts — the tally is not in the crash file — and reads
N/A. The focus pair, which the partial carries, is the precedent this does not follow.
**A side effect of region 4's poll (layout 4).** `GetDesc` every 500 ms also refreshes the chain's output size, which
catches a `ResizeBuffers1` the hook inventory does not have: a title that resizes through it now splits its segments at the
change and reads "settings changed mid-session" (FR-6.4), which is what it was.
**Where it is shown** (`08_UI`): the session summary's Display card and line, the game page's last measured session and
its Sessions column, three Trend metrics — *Exclusive fullscreen share %*, *Borderless share %*, *Windowed share %*, every
tier, and a mode switch is not a mid-session change for them (switching resizes the swap chain; the share is what that
switch was) — three Compare rows, never ranked, and the CSV's `# display:` line (§Export schema) and the JSON's aggregates.
## Per-process VRAM (Tier 1)
`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).
@@ -667,6 +764,7 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline
| Path tracing | heuristic, confidence-scored, never asserted | not available |
| Per-process VRAM | exact | not available |
| PC latency | as reported by Reflex | not available |
| Display mode (beta.10) | per 100 ms sample: exclusive fullscreen as the swap chain answers it (DXGI; OpenGL and Vulkan cannot say), borderless, windowed, minimised; the window's size from user32 | per 1 s sample, from the window alone: windowed, minimised, or *fullscreen or borderless* — never split |
| GPU temp / load / power | vendor API accuracy, ±1 s sampling | same |
| CPU temperature | sensor-inherent ±1–2 °C, needs LHM + PawnIO + elevation. **Read since 2026-09-21** (`Telemetry.LhmCpuTemperatureReader`: the package sensor, else the hottest core) and **unmeasured on real hardware** — no elevated run with PawnIO has been taken (`20_OPEN_QUESTIONS` §CPU) | same |
| CPU load | **time busy over elapsed, every logical processor** (`GetSystemTimes`, 1 Hz, unprivileged; since 2026-09-21). Not Task Manager's "utility", which is frequency-scaled and exceeds 100 under turbo — the two are different numbers and this one is stated as what it is. Null on a session's first tick (no interval yet), never 0 | same |
@@ -699,4 +797,4 @@ Per-column sources, and what a *Tier-2* export does instead:
| `vram_mb` | `vram_proc` per-frame blob. Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so | `N/A` |
| `reflex_latency_us` | `latency_us` blob; **finalize must write it** | `N/A` |
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, hardware snapshot, segment list, the tri-state flags with their sources, and the note that `vram_mb` is 1 Hz-sampled. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, swap effect, **the display line** (beta.10: `# display:` with each mode's milliseconds, the changes, the source and the window / back buffer / monitor sizes, or `N/A` for a session recorded before — §Display mode; a mode is the session's, not a frame's, so it is not a column), hardware snapshot, segment list, the tri-state flags with their sources, and the note that `vram_mb` is 1 Hz-sampled. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
+117 -6
View File
@@ -38,7 +38,9 @@ public interface IFrameSource : IAsyncDisposable
> with `FlGuardBuildId`), `ITargetLivenessSource` (`HeldProcessLivenessSource`, §S29(e)),
> `ITargetResolver` (`TargetResolver`, path only — never a pid), `IProcessLauncher`
> (`ProcessLauncher`, launch mode), `IRuntimeModuleSnapshot`, `INgxDriverProbe`,
> `IExecutableMarkerScan`. `ShmRingReader` itself gains no interface and no second consumer
> ~~`IExecutableMarkerScan`~~ — **corrected 2026-09-27:** the marker scan is the recorder's, not the loop's; the loop's
> later ports are `IKillSwitch` (FR-2.4), `ICapturePauseSource`, `IUserModeExceptionSwitch` and
> `IOverlayToleranceChannel` (D33) and `IDisplayProbe` (beta.10). `ShmRingReader` itself gains no interface and no second consumer
> (`NoSecondRingReaderTests`). A **pure move**: the loop's ordering rules, its tests and the
> capture host's report are byte-for-byte what they were; the host is now a thin shell that
> composes the same objects. What the table below used to call `HookedFrameSource` is this.
@@ -74,6 +76,28 @@ promises.** It is stated here, in `README` §Capture tiers and in `03_METRICS`
frame times without injection and a reader who remembers that will otherwise assume
it still holds.
> **Built 2026-09-22 — until then Tier 2 did not exist in practice.** Every refusal returned from
> `CaptureSession` within about a second and `SessionFinalizer`'s 30 s minimum discarded the row, so the
> table above described a tier no session had ever reached (the owner's log: `Discarded (tier 2, exit=Normal,
> frames=0)` for every refusal). Now the loop **holds** a refused session open — `HoldUnhookedAsync`, one tick
> per `CaptureOptions.HoldInterval` (1 s), each tick draining the telemetry poller through the observer as a
> hooked session's ticks do — until the target exits, the user stops it or `MaxDuration` runs out. The clock is
> the pinned liveness when the loop holds a pin, and ~~the executable's NAME~~ **the executable's image path in the
> watcher's own 1 Hz snapshot** (`ITargetResolver.IsRunning` over `LatestProcessSnapshot`, 2026-09-23; a process
> whose path could not be read still counts by its name; the console verbs, where nothing polls, keep the name
> list) when it never opened the process — by name, another game's `Game.exe` held an RPG Maker game's session
> open. Nothing about the hold touches the target, and no process is opened for it. **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
> first, and a row whose hooking is off — merely added, blocked by a finding, auto-disabled — goes straight to
> the hold with `RefusedHookNotEnabled` (its verdict is the row's block when it has one, `PreviouslyBlocked`).
> The resolver used to run first, and a hooking-off utility that runs elevated (Borderless Gaming, imported from
> Steam) was reported as a process an anti-cheat driver protects, with the notice that sentence deserves.
> `TargetNotRunning` alone returns at once — there is nothing to hold. Launch mode's two guard refusals
> (`LaunchTargetExited`, `LaunchNoPresentationRuntime`) return at once too, because the descendant election
> is waiting on them. The unshipped operator host sets `HoldUnhooked = false`: to an operator a refusal is the
> answer and the exit code. The discard rule is unchanged: a Tier-2 row under 30 s is still dropped, which is
> now a game that ran under 30 s rather than every refusal. `PartialRecovery` no longer reads a tick as proof of
> a hooked session — a held session flushes ticks with no records and no `attached` note.
**The reason is the payload of Tier 2**, not a consolation attached to it. A session
that records duration and sensors while saying nothing about *why* it measured
nothing is indistinguishable from a broken capture. `sessions.capture_notes` and the
@@ -103,7 +127,7 @@ which makes the notification more important than it was, not less.
## Process watcher
- 1 Hz snapshot via `CreateToolhelp32Snapshot` (CsWin32): pid, ppid, exe path (`QueryFullProcessImageName`).
- Watchlist match on normalized full path (`GetFinalPathNameByHandle` — junctions/symlinks), filename fallback with a stale-path warning badge.
- Watchlist match on normalized full path (`GetFinalPathNameByHandle` — junctions/symlinks), ~~filename fallback with a stale-path warning badge~~ **and a file name alone never starts a session (2026-09-23, HANDOFF D25): it can only be the entry's own executable on a drive that changed its letter (the relocator's rule), or it is not in the library.**
- Process tree assembled from ppid chains; the **capture target** is the descendant that actually presents. In launch mode we know it; in attach mode we wait for the first ring handshake. ~~or (Tier 2) elect the PID with the most presents in the first 10 s~~ — there is no Tier-2 present stream to elect from. Re-elect if the presenting PID dies while the tree lives (level-transition relaunches).
> **Built 2026-09-10 (P2 PR-F), in `Application.Watch` with one adapter.** `ToolhelpProcessSnapshotSource`
@@ -113,7 +137,20 @@ which makes the notification more important than it was, not less.
> both null so it can match nothing. `ProcessWatcher` diffs it against the watchlist — the `games` rows — on the
> normalised full path first and on the file name only when exactly ONE row carries it (`StalePath`, the
> "stale-path warning badge"; the session is keyed on the path the process actually runs from, so consent for the
> old path does not follow the binary). `ProcessTree` reads ppid chains with the one rule that defeats pid
> old path does not follow the binary — **unless it IS the same binary on a drive that changed its letter**, 2026-09-22:
> `CaptureOrchestrator.AdoptIfMovedAsync` asks `ExecutableRelocator` first, and when the row's file is gone and the
> running one has the row's size and mtime, the row is moved and the session is the row's, consent and all;
> `19_SAFETY` §A moved drive is the same executable). **Narrowed 2026-09-23 (D25): a `StalePath` match that is not
> adopted records NOTHING.** The stranger session was keyed on the real path and named after the matched row, and
> `SessionRecorder`'s `EnsureAsync` turned that into a new library entry with the other game's name: *HELLO, HELLO
> WORLD!*'s `swiftshader\Game.exe` became a second "Flower in Us" (the only entry named `Game.exe`), and its NW.js
> children, matching the new entry exactly, started a second session beside the first. Now the process is said once
> in the log ("not in the library, so nothing is recorded") and its exit is silent; the adopt itself accepts only the
> row's path with its drive letter changed (an RPG Maker `Game.exe` has the same bytes in every game); and the
> running-session table is keyed by the executable's path, so a re-imported or merged entry's new id cannot start a
> second session for the same executable. The launch election registers its session there too, and skips a child the
> watcher already records. **Behaviour change:** a game whose folder moved (not its drive letter) records nothing until
> *Change executable* points its entry at the new file. `ProcessTree` reads ppid chains with the one rule that defeats pid
> reuse: a child that started before its parent is not its child. `DescendantElection` picks the newest-started
> descendant whose image is tracked — a launcher's consent does not extend to what it spawns, so the elected image
> needs its own record. `CaptureOrchestrator` is the `--serve` loop: one snapshot per second, ONE session per game
@@ -125,11 +162,28 @@ which makes the notification more important than it was, not less.
> (`05_DETECTION` §Caching) on its own task, because `GameFileProbe` blocks on file I/O and the 1 Hz poll must
> not wait on it. It reads game files and writes the detected columns of `games`; it never touches a process,
> a hook, or a consent column.**
>
> **The watchlist is the entries whose recording is on (2026-09-23, FR-1.6, D29).** Borderless Gaming starts with
> Windows on the owner's machine, and since Tier 2 exists every library entry that runs gets a session — one per boot,
> for as long as the utility ran, in the playtime totals. `games.record_sessions = 0` (schema 0009, the user's switch on
> the game page) takes an entry out of the watchlist `PollOnceAsync` hands the watcher, and out of the launch election's
> tracked set: its process appearing is no event, no session and no log line. Switched off while a session of it runs,
> the orchestrator cancels that session's stop token at its next poll — the loop ends as a user stop and saves what it
> had — and `LaunchGame` answers `RecordingOff`. Switched back on, a process that is still running is picked up by
> the next poll (a pid the watcher never matched is new to it). Detection and the drive-letter relocator still follow
> the entry; they read files, not processes.
## Launch mode vs attach mode
**Launch mode (preferred).** User starts the game from FrameLedger (or FrameLedger is set as the launch wrapper): `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
> **An elevated Agent starts the game as a standard user (beta.10, the admin mode, D34).** `ProcessLauncher` checks its
> own token: elevated, it starts the game with the desktop shell's token (`Infrastructure.Startup.UnelevatedProcess` —
> `GetShellWindow`'s process, its token duplicated, `CreateProcessWithTokenW`, the same explicit environment the kill
> switch decides), pins it from the start's own handle, and never falls back to its own token: with no shell the launch
> fails with `Launch_Error_1400`. `LaunchGame` is a pipe command any process of the user can send; an elevated launch would
> be an elevation without a prompt.
> **Built 2026-09-06 (P1 item 2) as "inject late", which is the only shape §S1 left possible, and the
> sentence above is kept as the intent it does not quite describe.** A `CREATE_SUSPENDED` target has
> loaded nothing and the module scan *fails* against it (`ERROR_PARTIAL_COPY`, §S1 measured), so the guard
@@ -182,6 +236,18 @@ Its result is authoritative: no code path may inject without a passing check, an
What the Agent checks **before** asking the guard is the thing the native side structurally cannot see: **per-game consent** (CLAUDE.md rule 1). Consent is a record of something a human did, so `HookedCaptureGate` refuses an unconsented or un-enabled game without the guard ever being called.
> **The user-mode exception (D33, 2026-09-26) — one branch, and it only narrows.** A blocked game is refused
> `PreviouslyBlocked` before the guard is asked, as ever, UNLESS `HookRequest.FromConsent` found its exception in
> force: `hooking.usermode_ac_exceptions` on, a grant on the row made on the executable on disk, the block naming that
> family (`UserModeExceptionRules.CoveredFamily`) — and the session could publish the Overlay's channel
> (`IOverlayToleranceChannel`, `07_IPC` §D) BEFORE building the request. Then the gate hands the guard the family's
> NAME through the same entry (`GuardedInjectAsync` / `…WhenReadyAsync`), the guard decides whether to honour it and
> runs every check, and every 30 s re-scan names it again (`GuardSupervisor(guard, toleratedFamily)`). A blocked row
> whose exception does not apply is hooking-off before the process is opened, like any other. A hooked session under
> it is marked (`sessions.ac_exception_family`, `; ac-exception=<family>` in the notes), and a finding about the game,
> a safety unhook, the Overlay's own stop or a crash while hooked ends the exception (`UserModeExceptionLapsePolicy`,
> after the row is stored). `19_SAFETY` §The user-mode exception is the rule; this is where the loop applies it.
> **Where it lives, corrected 2026-08-06.** This sentence said "lives in SQLite", and was the
> only line in the tree that said where consent lives — while no database, no `games` table
> and no consent writer existed in any `.cs` file (§S27). The port is
@@ -234,6 +300,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
> **The PAIR, because zero is not a finding.** A process owning no top-level window at all — `hook-harness` presents to a composition swapchain and has none — is unfocused on every tick of every run. Reporting that as focus loss would fire on every integration run and teach the reader to ignore the line, which is the could-not-look/looked-and-found-nothing collision `FlRtTier` and `upscalerQuality` already exist to avoid.
>
> **It is attribution, never the guard.** What refuses a mixed window is `FgWindow.BatchRefusal`, computed from the records alone, so a caller that never wires focus still cannot publish an averaged ratio. Focus is what lets the report name the cause.
- **Each drain tick also samples the display mode (beta.10)** — `Application.Capture.DisplaySampler` on the same tick as focus: shared-memory region 4 (the presenting chain's window, back buffer, swap effect and exclusive state, as the Overlay last asked them) and the window's geometry from outside (`IDisplayProbe`, `Infrastructure.Display.WindowGeometryProbe`), classified and added up by the time each sample stood for; a paused tick drops the interval it ends. The last sample is closed before the last drain, and the tally rides out on `CaptureOutcome.Display`. **The Tier-2 hold samples too**, once per hold tick (1 s): the window only — by the pinned pid when the loop holds one, else by every process running the executable in the watcher's snapshot (`ITargetResolver.PidsOf`, image path only — never a name), still opening nothing. The recorder writes the tally on the row's skeleton, so both tiers store it (`03_METRICS` §Display mode, `06_DATA_MODEL` 0016).
- **Dropped records are computed here, not read from the header.** The Overlay has no reader index and cannot know whether a slot it overwrites was consumed. The Agent owns the read index, so it owns the accounting: when `writeIndex - readIndex > capacity`, add the excess to the session's data-quality counter and resume at `writeIndex - capacity`. A non-zero value means the Agent stalled for over ~16 s — log it, surface it as a session warning, never silently accept it.
> **That sentence is true only because the read index is seeded from the writer at
@@ -254,7 +321,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
| Thread | Cadence | Owns | Touches |
|---|---|---|---|
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground per tick, drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground and the display mode per tick (beta.10), drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
| **Telemetry** (`fl-telemetry`, `TelemetryPoller`, one per session) | 1 Hz, never faster than 500 ms | Its own `ConcurrentQueue` of `TelemetrySample` | Reads the composite source only; L2 has a thread of its own inside the library, and the composite is read from this thread and no other |
| **Watcher** (built 2026-09-10, PR-F: `CaptureOrchestrator.RunAsync` on a `PeriodicTimer(1 s)`) | 1 Hz process snapshot | The watcher's events and the running-session table — ~~`PollOnceAsync` is their only writer; there is no `Channel`, because there is no second consumer~~ **since 2026-09-13 (P3 PR-1b) the table has one lock**: `PollOnceAsync` on the timer, `LaunchAsync` and `StopSession` from the pipe's tasks (HANDOFF §P3 D12 as built — two commands do not justify a channel); the sessions themselves never take it | The `games` rows (one read per poll) and never the ring; each session it starts runs on its own task |
| **Finalize** (PR-D) | Once, on the session loop's task | The one SQLite connection, behind a `SemaphoreSlim(1)` | `ApplicationStopping` cancels the loop; finalize gets a grace window, then the `.partial` stays for recovery |
@@ -270,6 +337,12 @@ than a tuning knob. ~~There is no UI thread in P2; the pipe reader (P3) joins as
the pipe's tasks touches the ring or the recorder, and the session loop never waits on a client. The command half (PR-1b) is the
`Channel` producer this sentence anticipated.
> **The pause is a gap (beta.8).** FR-3.9's pause stops the Overlay recording; the loop reads the QPC as it tells the ring
> to resume (`ApplyPause`, before `SetPaused(false)`, on the Overlay's own clock — `Stopwatch` is `QueryPerformanceCounter`)
> and marks a gap before the first drained record stamped at or after it (`MarkResume`). A record drained after the
> resume but stamped before it is a straggler the pause had not reached. `03_METRICS` §Data gaps says what a gap then
> does to the statistics and to `D`.
## Telemetry poller
1 Hz on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) + optional CPU sample when the Agent is elevated and PawnIO is present. Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
@@ -317,6 +390,22 @@ because a layer cannot leave a running game's loader chain.
**Discard rule:** duration < min session length (default 30 s) → discard silently (log only).
> **A session whose entry was removed while it ran (2026-09-23).** Step 5 wrote under the id the session *started*
> with, and the owner's GIRLS' FRONTLINE 2 entry was removed — and re-imported — twice while the game ran: both
> sessions died on the foreign key (`session: FAULTED SqliteException: … FOREIGN KEY constraint failed`, 2026-09-22
> 23:26 and 2026-09-23 00:25), and each left a `.partial` whose recovery would have died the same way at the next
> start — stopping the host, because recovery ran before the watcher with no guard. As built:
> - **The owner is looked up, not assumed** (`ISessionRepository.ResolveOwnerAsync`, `FinalizeInput.ExePath`): the id
> the session started under when that row predates the session or holds its executable (an id SQLite reused for a
> later game is neither — `games.id` has no AUTOINCREMENT), else the row that holds the executable's path now (the
> re-imported entry), else **`GameRemoved`**: the user removed the game with its sessions and this was one of them.
> Nothing is written, the `.partial` is deleted, and the log says which. The write transaction re-checks the row, so a
> removal between the lookup and the insert is the same answer rather than the foreign key's exception.
> - **Recovery never throws.** A file it cannot finalize is set aside as `<guid>.partial.failed` (never retried, kept for
> a bug report) and reported `Failed`; the next file is recovered, and the watcher starts either way.
> - The Agent's host logs through Serilog since the same day: a background service that stops the host is now in
> `agent-*.log`, where before it was in no file at all.
> **Built 2026-09-10 (P2 PR-D): `Application.Recording`.** The state machine above is the intent; what
> runs is one class per box. `SessionRecorder` owns a session end to end — the row's identity and time
> base (`session_guid`, `qpc_epoch`/`qpc_frequency` from `TimeProvider.GetTimestamp`, which is QPC), the
@@ -342,8 +431,8 @@ because a layer cannot leave a running game's loader chain.
## Crash & exit classification
- Normal: presenting PID exit code 0.
- `crashed`: nonzero exit code, **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
- Normal: presenting PID exit code 0 — **and since beta.8 any exit code that is not an exception's** (End task and taskkill leave 1; a program's own error exit; Ctrl+C's `0xC000013A`), kept in `capture_notes` and said as what it is.
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
- `unhooked_safety`: the guard fired mid-session.
- `degraded`: Overlay self-disabled after faults, or ring layout mismatch mid-session.
- `interrupted`: Agent died mid-session; recovered from `.partial` on next start.
@@ -361,6 +450,21 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
> exit code and the witness (`end=TargetExited; exit_code=-1073741819; crash_event=application_log`).
> `CrashAutoDisablePolicy` counts only crashes inside the 60 s window after the attach — `hook_crash_count`
> is that count and nothing else — and disables on the second; it never re-enables.
>
> **Corrected 2026-09-25 (beta.8, owner item 5): End task is not a crash.** The owner's sessions ended by Task Manager
> read *Crashed* — every non-zero code was one, and `TerminateProcess` leaves 1. A crash is now an exception's code or
> the event log's witness; any other code is `normal` with the code in the notes, and the session summary says it
> ("ended with exit code 1 — what End task and taskkill leave…", "crashed (0xC0000005 access violation)", "0xC0000006
> in-page I/O error: a disk or drive failed…"). **The safety policy did not get looser:** it takes the exit code beside
> the status and still counts every non-zero exit inside its window — a game the hook hung that the user then ended is
> the shape it exists for — and its row reason says "ended abnormally", not "crashed" (`19_SAFETY` §Crash & stability).
>
> **The notes' guard slot has three positions since the same day:** `guard=Reason|Family|Signal`, every slot present
> and `;` never inside one (`CaptureNotes.GuardSlot`). It was `Reason/Family/Signal` with an empty family dropped, so
> a refusal no family names put its signal where the family goes — and the notice read "Access is denied was detected
> in this game" — and a signal with a `;` was cut there. Old rows are read by the one rule that separates them: findings
> and the gate's own refusals carry a family, every other reason's second part was its signal. A launch that cannot
> start keeps Windows' reason (`launch_error=740`; `IProcessLauncher.Start(…, out win32Error)`).
## Live progress
@@ -373,6 +477,13 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
> stands alone with the census qualifier (`FgLadder.PresentedQualifier`, the row's). CPU temperature is null until the Agent composes a
> CPU sensor, and every other unmeasured field is null, never 0. Rate-limited to 1 Hz inside the observer's `Tick`, computed only while
> a client is connected, and a fault in the computation is counted rather than allowed to end the session.
>
> **A held session is live too (2026-09-23).** The hold's ticks carry the refusal (`CaptureProgress.Held`, with the pid the loop
> holds, 0 for a hooking-off hold that never opened the process). The publisher's first held tick announces the session —
> `SessionStarted` at tier 2 with its `hold`, and the refusal's own event at once rather than when the game exits — and every tick
> after feeds `SessionHeld` (elapsed and sensors, nothing measured) at the same 1 Hz while a client listens. It is never run through
> `SessionProgressCalculator`, whose window over no records would still emit a qualifier. A session whose task faults now also
> completes on the pipe (`finalize: faulted`, `07_IPC`), so nothing is left shown as running.
## Overhead rules (NFR-1)
+115 -9
View File
@@ -26,11 +26,16 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
| Reflex on + PC latency | NVAPI Reflex hooks |
| Per-process VRAM | `QueryVideoMemoryInfo` |
| PSO compilation events | pipeline-creation hooks |
| Display mode — exclusive fullscreen / borderless / windowed / minimised, with the window, back buffer and monitor (beta.10) | `GetFullscreenState` + `GetDesc` polled on the presenting chain (≤ 2 Hz, shared-memory region 4), and the window's geometry read by the Agent **out of process** — so this row is **both tiers**: a Tier-2 session has the window alone, and never splits exclusive from borderless (`03_METRICS` §Display mode) |
> **Not built, 2026-09-15:** four rows above have no writer yet — HDR output, Reflex and PC latency, per-process
> VRAM, and PSO compilation events. The Overlay never sets their measured bits, so every calculator over them
> returns nothing and the columns stay null; `legal/ACCURACY.md` lists them as not measured. This table is the
> design; the block is the state.
>
> **2026-09-27 (beta.10):** the first row's *swap effect* has a writer since schema 0016 — region 4's `GetDesc`, stored
> in `sessions.swap_effect` as a name (`flip_discard`, …) — and the display-mode row is new. **Present mode has none**,
> and the block above did not list it: `sessions.present_mode` is null on every row, and the pages say N/A.
> **"present-count delta" is removed from the FG row, and it was not merely unreliable —
> it was structurally zero.** `03_METRICS` §Frame Generation retired that rung on
@@ -42,7 +47,7 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
> stale-by-not-being-touched failure this project keeps recording; `06_DATA_MODEL`'s
> `fg_source` enum carried the same value and is corrected in the same pass.
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement.
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement. **The one exception since beta.10 is how its window was shown** (the display-mode row), which the Agent reads from outside the game in either tier.
## Static hints — rules engine
@@ -61,7 +66,7 @@ Rules are **data, not code**: `rules/detection-rules.json`, bundled and updatabl
The `anticheat` block is the same file that feeds the hard guard in `19_SAFETY` — shipping it as updatable data is what lets a newly-protected game be blocked without waiting for an app release. **Rules updates that touch the `anticheat` block are treated as security updates:** applied on next check regardless of the user's auto-update preference for other rules.
Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`, `sibling_glob`, **`path_contains`**, `pe_company_contains`, `pe_product_contains`, `strings_contains` (bounded 8 MB scan), `manifest_field`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`.
Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`, `sibling_glob`, **`path_contains`**, `pe_company_contains`, `pe_product_contains`, `strings_contains` (bounded 8 MB scan), `manifest_field`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`, and since 2026-09-27 **`unreal_build`** (no parameter; decided in code, §Engine version). A regex extractor must capture exactly **one** group — the evaluator returns the first — and `rules-validate.ps1` refuses any other count and any pattern that does not compile (both promised by the rules file's `$comment` and enforced by nothing until beta.10).
> `path_contains` and `strings_regex` were in the shipped data and the schema
> and missing from this list; the schema's own `$comment` said so and nobody had
@@ -132,11 +137,13 @@ Recorded as a residual risk, not as a solved problem.
| Engine | Signals | Version |
|---|---|---|
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | FileVersion of `UnityPlayer.dll` |
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)` |
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | `unreal_build` (since 2026-09-27, §Engine version): the shipping executable's numeric file version and the engine's branch name inside it. ~~ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)`~~ — two capture groups, of which the evaluator returns the first, so every Unreal version it ever stored was a bare `4` or `5` |
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
| GameMaker | `data.win` | `N/A` |
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `N/A` — the `.js` header needs a `from` that `strings_regex` lacks |
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `N/A` — one rule, the variant unnamed |
| RE Engine (Capcom) | `re_chunk_000.pak` sibling, the exact name (since 2026-09-23) | `N/A` |
| FromSoftware | a `*.bhd` **and** a `*.bdt` sibling (since 2026-09-23) | `N/A` |
| Ren'Py | `renpy/` dir **or** `*.rpa` | `renpy/__init__` strings / `log.txt` first line |
| CryEngine | `CrySystem.dll` | FileVersion |
| Source | `gameinfo.txt` + `bin/engine.dll` | `N/A` |
@@ -160,6 +167,25 @@ Order matters (first match wins). Engine is user-overridable.
> `every_engine_marker` canary carries both engines' markers and still expects `unity`. `rulesVersion` is
> `2026.09.1`, so the sweep's cache key changes and every game is re-detected on the next pass.
> **RE Engine and FromSoftware, 2026-09-23 (owner request, "mang tính tương đối" — a relative signal, not a proof).**
> Both are file-layout signals, checked on the owner's disk before they were written. **RE Engine:** every Capcom RE
> Engine title ships its content as `re_chunk_000.pak` beside the executable, with patches as
> `re_chunk_000.pak.patch_00N.pak` (RESIDENT EVIL 2 and the Onimusha demo). The rule names the base archive exactly — a
> glob without a star is the whole leaf name — so a patch archive alone is not it. **FromSoftware:** the studio's
> titles keep their data as `.bhd` header + `.bdt` data pairs beside the executable — DARK SOULS II
> (`GameDataEbl.bhd/.bdt`), DARK SOULS III (`Data0`–`Data5`), ELDEN RING (`Data0`–`Data3`, plus `DLC`) and Sekiro
> (`Data1`–`Data5`). The request described the second extension as `.bht`; on disk it is **`.bdt`**. An `all` group
> over the two globs — half a pair is not a pair. The request also described a `<Game>\Game\` layout; it is not a
> signal here, because Sekiro has no `Game\` folder and "the parent folder is named X" is not a signal type anyway.
> None of the owner's other 80 Steam titles carries either marker. Both rules sit after the RPG Maker rules and
> before `godot`, whose `*.pck` would also match a loose Wwise sound bank (an `Unknown` there would stop the walk
> before these rules). Fixtures `engines/re_engine` and `engines/fromsoftware`; the `every_engine_marker` canary
> carries both engines' markers and still expects `unity`. `rulesVersion` is `2026.09.2`, so every stored game is
> re-detected on the next sweep. Engine detection never feeds the guard: ELDEN RING stays refused by its anti-cheat
> whatever engine it is shown as. **Engines are shown by name since the same date** (`Formats.Engine` in the App —
> proper nouns, not resources; an unknown id, or one the user typed, passes through): the game card and page used
> to show the raw id (`rpgmaker_mv`).
⛔ *(kept for the record — the two rows above were the ones this note described)* **Two rows cannot be expressed in schemaVersion 2**, and are documented rather than half-implemented — a rule that exists but never fires is worse than one that is absent, because it reads as coverage:
- ~~**RPG Maker MV/MZ.** The signal is `nw.dll` **and** (`www/` **or** `package.json`) — a nested group, and `signalGroup` sets `maxProperties: 1` with its own `$comment` saying nesting is unsupported in v2.~~ Its version is a header inside a sibling `.js`, and `strings_regex` carries no `from`, so it cannot be aimed at a file other than the executable.
@@ -167,6 +193,52 @@ Order matters (first match wins). Engine is user-overridable.
Everything else in the table is in the data and has a fixture; `rules-validate.ps1` fails if a rule id has no fixture directory, or a fixture no rule.
### Engine version — Unreal Engine (beta.10, 2026-09-27, schema 0015)
The owner asked for "the exact Unreal Engine version (3.0, 4.5, 5.1 …) on the game's page". What was shipped could not
give one: the rule read only the executable's `ProductVersion` string, which most shipping executables leave empty, and
its regex had two capture groups, so the one answer it could give was `4` or `5`. **Measured before anything was written,
read-only, on the owner's ten Unreal titles** (`spike-notes` §Unreal Engine versions):
| Title | Numeric file version | Version strings / company | Branch name in the bytes | Read as |
|---|---|---|---|---|
| Black Myth: Wukong | 5.0.0.0 | none | `++UE5+Release-5.0` (290 MB into `.code`; `.rdata` 8 KB) | 5.0.0 |
| Cronos: The New Dawn (demo) | 1.2.0.0 | the studio's | none | — |
| Clair Obscur: Expedition 33 | 5.4.4.0 | none | none | 5.4.4 (file version) |
| Hell Is Us | 5.5.4.0 | `UE5-CL-0` / Nacon | none (the studio's own branch) | 5.5.4 (file version) |
| Lies of P | 4.27.2.0 | none | none | 4.27.2 (file version) |
| Martha Is Dead | 4.27.0.0 | none | `++UE4+Release-4.27` (`.rdata`) | 4.27.0 |
| Rune Factory: Guardians of Azuma | 1.0.3.0 | none | none | — |
| SILENT HILL 2 | 1.0.0.5 | the studio's | `++UE5+Release-5.1` (`.rdata`) | 5.1 |
| UMIGARI | 5.5.4.0 | `++UE5+Release-5.5-CL-40574608` / Epic Games, Inc. | (in the strings) | 5.5.4 |
| AbyssMemory | 4.26.1.0 | none | `++UE4+Release-4.26` (`.rdata`) | 4.26.1 |
**Two witnesses, each wrong in its own way.** The numeric file version (`VS_FIXEDFILEINFO`) is the engine's
MAJOR.MINOR.PATCH unless the studio replaced it (Cronos, SILENT HILL 2, Rune Factory); the branch name the engine compiles
in (a UTF-16 string) names the release line and no patch, and is missing wherever a studio renamed its branch or the
executable is packed. `Domain.Detection.UnrealVersion.Decide` takes them in order: **(1)** both, agreeing on MAJOR.MINOR →
the file's MAJOR.MINOR.PATCH (`unreal_branch_file`); **(2)** a branch name alone → MAJOR.MINOR (`unreal_branch`); **(3)**
no branch name, and a file version that reads as an engine's (4.0–4.27, 5.0–5.9, patch ≤ 20) where nothing says the studio
replaced it — no version strings, a string naming the same `UE4`/`UE5`, or Epic's company name → MAJOR.MINOR.PATCH
(`unreal_file_version`); **(4)** anything else → no version. The third rung is the weakest (a studio could number its own
game 4.2 and ship no strings), which is why `games.engine_version_source` keeps the rung and the game page says it.
**Where it is read.** `StaticGameDetector` makes a second read for the one engine that matched — never the probe for every
game in the library: `GameFileProbe.ReadUnrealBuildAsync` picks the row's own executable when it is the shipping build
(`*-Win64-Shipping.exe`, `*-WinGDK-Shipping.exe`), else the largest shipping executable the walk listed (a row pointing at
the launcher stub at the install root), and `UnrealBuildReader` reads its version resource and — unless the version strings
already name the branch — scans its `.rdata` section for the branch name: 15–39 MB in nine of the ten titles. An `.rdata`
under 1 MiB (Black Myth's protector merged its constants elsewhere) sends the scan over the whole file, bounded at 1 GiB and
stopping at the first chunk that names a release line. Chunks are 4 MB with an overlap, so a name cut by a chunk's edge is
read whole and never as the digits that fitted; cancellation is observed between chunks. Measured through the shipped
reader on the same ten files: every row above as tabled, 16 ms to 1.1 s each and 7.5 s for Black Myth, on the owner's USB
drive — once per executable, because the detection key (rules version + size + mtime) changes only when the file does.
**What it is not.** UE3 titles are not detected as Unreal at all (the rule's signals are UE4/5's layout) and have no
numbered release lines to report. A version the user typed is never overwritten and carries no witness. Rules
`2026.09.6` change the key, so every library entry is read again once; schema 0015 removes the bare `4`/`5` the old rule
wrote, where detection wrote it.
### Platform signatures & metadata
| Platform | Signals | Metadata |
@@ -177,7 +249,7 @@ Everything else in the table is in the data and has a fixture; `rules-validate.p
| itch.io | `.itch\receipt.json.gz` | **`%APPDATA%\itch\db\butler.db`** (`install_locations` + `caves`, butler's `verdict` names the executable) since 2026-09-16, then the receipt JSON: title, id |
| None/Manual | fallback | PE VersionInfo |
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf`; GOG via `HKLM\SOFTWARE\WOW6432Node\GOG.com\Games\*`; Epic via `Manifests\*.item`; itch by receipt scan. Import presents a review checklist; nothing is launched, nothing is hooked on import.
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf` except `SteamLibrarySource.KnownTools` (2026-09-22: Steamworks Common Redistributables, Borderless Gaming, Wallpaper Engine, SteamVR, the Proton and Steam Linux Runtime entries, Blender — tools Steam's manifests do not distinguish from games, and which became library rows the watcher recorded); GOG via `HKLM\SOFTWARE\WOW6432Node\GOG.com\Games\*`; Epic via `Manifests\*.item`; itch by receipt scan. Import presents a review checklist; nothing is launched, nothing is hooked on import.
> **Built 2026-09-14 (P4 PR-4).** `Application.Import.LibraryImporter` over four `IStoreLibrarySource` adapters in
> `Infrastructure.Import` — `SteamLibrarySource` (`libraryfolders.vdf` + `appmanifest_*.acf` through
@@ -214,7 +286,7 @@ Everything else in the table is in the data and has a fixture; `rules-validate.p
> is fetched (CLAUDE.md rule 8's "opt-in store metadata" is the online lookup, which does not exist). First-run
> step 4 now points at File ▸ Import library… rather than saying "later build".
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days.
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days. *(Since beta.8 the PE versions are stored beside the store's rather than instead of it — §What the files say about themselves; the page labels a store's value with its store, "Steam build 20374416".)*
## Capability hints (explicitly labelled as such)
@@ -222,8 +294,8 @@ Files shipped with a game tell us what it *supports*. These populate a **"Suppor
- DLSS SR `nvngx_dlss.dll` · DLSS-G `nvngx_dlssg.dll` · **Ray Reconstruction `nvngx_dlssd.dll`**
- Streamline `sl.interposer.dll`, `sl.dlss_g.dll`, `sl.reflex.dll`
- FSR `ffx_fsr2_*.dll`, `ffx_frameinterpolation_*.dll`, `amd_fidelityfx_*.dll`, `ffx_api*.dll` — a hint still, even though `amd_fidelityfx_dx12.dll` / `_upscaler_dx12.dll` / `_framegeneration_dx12.dll` are *hooked* since 2026-09-04: the measured chip comes from the dispatch, never from the file
- XeSS `libxess.dll`, XeFG `libxess_fg.dll`
- FSR `ffx_fsr2_*.dll`, `ffx_fsr3*.dll` (since rules 2026.09.5 — FSR 3's `ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` matched nothing before), `ffx_frameinterpolation_*.dll`, `amd_fidelityfx_*.dll`, `ffx_api*.dll` — a hint still, even though `amd_fidelityfx_dx12.dll` / `_upscaler_dx12.dll` / `_framegeneration_dx12.dll` are *hooked* since 2026-09-04: the measured chip comes from the dispatch, never from the file
- XeSS `libxess.dll`, `libxess_dx11.dll` (since rules 2026.09.5), XeFG `libxess_fg.dll`
- DXR-capable: `d3d12.dll` usage + RT-capable GPU (capability only — says nothing about the game)
- **Vulkan (since P4 PR-2, 2026-09-14) — a code-level fact, not a rule.** The rules can only ask about files
beside the executable, and the Vulkan loader is not one of them (`vulkan-1.dll` lives in System32). So
@@ -236,11 +308,42 @@ Files shipped with a game tell us what it *supports*. These populate a **"Suppor
The UI wording is deliberate: **"Supports DLSS-G"** (capability, from files) versus **"Frame Generation: DLSS-G ×1.9"** (measured, from this session). Users conflating these is exactly the confusion the old design created.
### What the files say about themselves (beta.8, 2026-09-25, schema 0011)
The owner asked for the game's version, the DLSS / FSR versions and whether a game is 32- or 64-bit. The sweep read
most of it already and kept none of it; since beta.8 it keeps four more facts per game, written whole with each
detection (`DetectionWrite`, `games.exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`):
- **What the executable runs as** — `PeImports.ReadArchitecture`, from the same bounded header read as the imports:
the COFF machine and, for a .NET executable, the CLR header's flags (`Domain.Detection.ExecutableArchitecture`:
`x64 | x86 | arm64 | arm | anycpu | anycpu32 | other | unknown`). An "AnyCPU" assembly carries an I386 machine and
runs as a 64-bit process unless it prefers or requires 32-bit, which is why the machine alone is not the answer.
`x86`, `anycpu32`, `arm64` and `arm` are **known not hookable** — the hook is an x64 DLL loaded with `LoadLibraryW`
(CLAUDE.md rule 3) — so enabling hooking on one is refused before anything is scanned or stamped
(`Refused { reason: "ExecutableNotX64", signal: <id> }`, `07_IPC`), and a row enabled before this build read the file
has its hooking turned off by the sweep (`hook_autodisabled_reason` = `executable is x86: the hook runs in x64
processes only`). `unknown` and `other` are not: the guard's `TargetIsWow64` at a session's start stays the check.
A row whose `exe_machine` is NULL is stale once, so every library entry is read under this build.
- **The executable's own versions** — the PE `FileVersion` and `ProductVersion` strings. The file's word, kept apart
from `game_version`, which is the store's (a Steam build id, a GOG or Epic version string) or the user's. For an
Unreal title the file version is often the *engine's*; the page labels both and does not pick one.
- **What it ships, with versions** — every file a capability rule names among those the walk listed, with the
numeric version of its `VS_FIXEDFILEINFO` (the version *string* may carry text, and Streamline stamps `2,8,0,0`):
`nvngx_dlss.dll 3.7.10.0`, `sl.interposer.dll 2.8.0.0`, `ffx_fsr2_api_x64.dll …`. Bounded at 48 files. A file with
no version resource is listed with none — it is shipped either way. FSR is named by its file, never mapped to an
"FSR 2.2" number: the DLL's version is the SDK's, and no table of that mapping has been measured.
**Shipped is not loaded.** `library_versions` is what the game folder holds. What the process loaded is
`sessions.runtime_modules` (Tier 1), and the two differ exactly when something else supplied the DLL — the NVIDIA
App's DLSS override loads the driver's `nvngx_dlss.dll` from the driver store under the same name. The session
summary prints the loaded list and names such a difference ("the game ships 3.7.10.0: another copy was loaded");
it does not claim who loaded it.
## Anti-cheat pre-scan (static)
Before a game is ever launched with hooking enabled, the static scan checks for anti-cheat SDKs shipped alongside it (`EasyAntiCheat/` directory, BattlEye binaries, EOS anti-cheat components, etc.). A hit **disables the hooking toggle for that game entirely** in the UI, with an explanation — the user cannot enable it, so the guard never even has to fire at launch. Prevention beats interception.
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as `FlStaticPreScan`). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1).
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` since 2026-09-25, which takes the executable, resolves the install root itself and runs check 3 as well). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1).
Three things this section previously implied that are not true, and are worth stating:
@@ -256,7 +359,10 @@ Three things this section previously implied that are not true, and are worth st
> `DetectionHostedService` (`--serve` only) sweeps the library on its own task — every 15 s, and at once
> when `UpdateRules` re-seeds the rules file — through `Application.Detection.DetectionSweep`, which runs
> `StaticGameDetector` over the real `GameFileProbe` for every game whose key is stale and persists through
> `IGameRepository.ApplyDetectionAsync`. A game the App adds is scanned on the next tick (the App writes the
> `IGameRepository.ApplyDetectionAsync`. *A missing executable is asked one more question before it is skipped
> (2026-09-22): is the same file — same size, same mtime — under exactly one other drive letter? When it is, the row
> follows it (`ExecutableRelocator`, `19_SAFETY` §A moved drive is the same executable) and this very pass scans
> it there; `DetectionSweepReport.Relocated` counts them.* A game the App adds is scanned on the next tick (the App writes the
> row, the Agent reads the table); no Agent running means no scan, and the game page says "not scanned yet".
> *The key's exe half is NOT `exe_size_bytes` / `exe_mtime_ms`:* those are the consent fingerprint the gate
> reads (`SqliteGameConsentStore` refuses a mismatch while a block stands), so schema 0004 gave the key its own
+141 -11
View File
@@ -2,7 +2,7 @@
`%LOCALAPPDATA%\FrameLedger\ledger.db`. Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=5000`. `Microsoft.Data.Sqlite` + Dapper; all writes in explicit transactions.
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms` — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; never a `hook_*` column), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It is the one Agent write that deletes a `games` row; it never touches a consent column. **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **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)
@@ -40,10 +40,15 @@ CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER
CREATE TABLE games (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
exe_path TEXT NOT NULL UNIQUE,
exe_path TEXT NOT NULL UNIQUE, -- where the executable lives; rewritten by ExecutableRelocator when the
-- SAME bytes (exe_size_bytes, exe_mtime_ms) turn up under another drive
-- letter (2026-09-22), and by Change executable for a DIFFERENT binary
platform TEXT NOT NULL DEFAULT 'none', -- steam|gog|epic|itch|none
store_id TEXT,
engine TEXT, engine_version TEXT,
-- (schema 0015, ALTERed last) engine_version_source TEXT: where engine_version came from — a
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version, or the rule's
-- extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
publisher TEXT, game_version TEXT,
cover_path TEXT, notes TEXT,
removed_at INTEGER, -- schema 0002 (P3 PR-3): FR-1.4 "remove, keep sessions" — the row stays
@@ -53,7 +58,30 @@ CREATE TABLE games (
-- hooking state (19_SAFETY)
hook_enabled INTEGER NOT NULL DEFAULT 0, -- 0 = Tier 2, i.e. nothing measured; default for every new game
hook_consent_at INTEGER, -- per-game informed consent timestamp
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI.
-- 'Reason|Family|Signal' since 2026-09-25 (SqliteGameConsentStore.
-- BlockText), so the App can say it in the user's language; older
-- rows keep "Reason: Family Signal" and are shown as stored
hook_prescan_rules_version TEXT, -- schema 0010 (2026-09-25): the key the Agent's pre-scan of the
hook_prescan_exe_size_bytes INTEGER, -- library last scanned the row under — the rules version and the
hook_prescan_exe_mtime_ms INTEGER, -- executable's size and mtime; NULL = never scanned by the sweep.
-- Change executable clears them with hook_prescan_state
-- schema 0014 (2026-09-26, D33): the user-mode anti-cheat exception, a layer OVER hook_blocked_reason, never its clearing
ac_exception_eligible INTEGER NOT NULL DEFAULT 0, -- the Agent's sweep: the exception may be granted now
ac_exception_verdict TEXT, -- its tolerant pre-scan, Reason|Family|Signal; NULL = nothing asked
ac_exception_sessions INTEGER NOT NULL DEFAULT 0, -- 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
@@ -67,6 +95,14 @@ CREATE TABLE games (
rr_default TEXT NOT NULL DEFAULT 'na',
detection_rules_version TEXT,
exe_machine TEXT, -- schema 0011 (2026-09-25): what the executable runs as, from its PE
-- headers (x64|x86|arm64|arm|anycpu|anycpu32|other|unknown); NULL =
-- not read by this build yet, which the detection sweep reads as stale
exe_file_version TEXT, -- schema 0011: the executable's PE FileVersion (the file's word; game_version
exe_product_version TEXT, -- is the store's or the user's) and its ProductVersion
library_versions TEXT, -- schema 0011: JSON array, the capability files the game SHIPS —
-- {"capability","path","fileVersion","productVersion"}; what a session
-- LOADED is sessions.runtime_modules
field_provenance TEXT, -- JSON: {"engine":"detected","publisher":"user",...}
-- absent or unrecognised reads as "user"
added_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
@@ -238,7 +274,23 @@ CREATE TABLE sessions (
avg_cpu_temp REAL, max_cpu_temp REAL,
avg_gpu_temp REAL, max_gpu_temp REAL, max_gpu_hotspot REAL,
avg_gpu_load REAL, avg_cpu_load REAL, avg_ram_mb REAL,
avg_gpu_power_w REAL, throttle_pct REAL
avg_gpu_power_w REAL, throttle_pct REAL,
-- schema 0016 (2026-09-27, beta.10): the display mode, both tiers (03_METRICS §Display mode). Milliseconds per mode,
-- each sample standing for the time until the next (100 ms hooked, 1 s at Tier 2), a pause not counted; nowindow is
-- outside every share. NULL before, on a session recovered from its .partial file, and where the loop never sampled —
-- N/A, never 0. Written on the recorder's SKELETON: a Tier-2 session never reaches the aggregator.
display_exclusive_ms INTEGER, -- the swap chain SAID exclusive (DXGI only)
display_borderless_ms INTEGER, -- covers its monitor, the chain said not exclusive
display_windowed_ms INTEGER,
display_covers_ms INTEGER, -- covers its monitor and nothing could say which ("fullscreen or borderless")
display_minimized_ms INTEGER,
display_nowindow_ms INTEGER, -- no window could be read
display_changes INTEGER, -- mode changes between samples
display_source TEXT, -- swapchain | opengl | window: the strongest witness any sample had
display_window_w INTEGER, display_window_h INTEGER, -- client area, in the mode that lasted longest
display_buffer_w INTEGER, display_buffer_h INTEGER, -- the swap chain's back buffer, same mode
display_monitor_w INTEGER, display_monitor_h INTEGER, display_monitor_hz INTEGER
);
CREATE INDEX ix_sessions_game_started ON sessions(game_id, started_at DESC);
@@ -276,17 +328,18 @@ CREATE TABLE frame_blobs (
dispatch_rays BLOB, -- uint32[] : ray volume per frame, tier 1 only
pso_created BLOB, -- uint16[] : compile COUNT per frame, not a flag
vram_proc BLOB, -- uint32[] MB per frame; held 1 Hz sample, see 03_METRICS
latency_us BLOB -- uint32[], tier 1 + Reflex only
latency_us BLOB, -- uint32[], tier 1 + Reflex only
first_present_ms REAL -- schema 0013 (beta.8): the dominant stream's first present, ms from qpc_epoch —
-- the sensors' zero (t_ms) against the frames'. NULL before; the charts then
-- keep the sensor overlay off rather than draw it out of step
);
CREATE TABLE sensor_blobs (
session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-- (schema 0007, 2026-09-21 - 19_SAFETY §The user's bypass) lives on TWO tables and nowhere else:
-- games.guard_bypass_at INTEGER, games.guard_bypass_disclosure_version TEXT NOT NULL DEFAULT ''
-- NULL/'' = off, every row's default. Both or neither: a timestamp without its version is not an
-- acknowledgement. Written only through IGuardBypassStore; cleared by revoking consent and by Change executable.
-- sessions.guard_bypassed INTEGER NOT NULL DEFAULT 0, guard_bypass_family TEXT, guard_bypass_signal TEXT
-- 1 when the session STARTED under the bypass. A session recovered from a .partial does not carry it.
-- schema 0007 (2026-09-21) added five guard-override columns (games.guard_bypass_at,
-- games.guard_bypass_disclosure_version; sessions.guard_bypassed, guard_bypass_family, guard_bypass_signal) and
-- schema 0008 (2026-09-22) DROPPED them with the feature (19_SAFETY §What a finding does to the game). Sessions that
-- ran under it keep "guard-bypass=" in capture_notes.
series TEXT NOT NULL, -- cpu_temp|gpu_temp|gpu_hotspot|gpu_load|gpu_power|vram_proc|vram_adapter|cpu_load|ram_mb
-- cpu_load / ram_mb / cpu_temp and sessions.avg_cpu_load, avg_cpu_temp, max_cpu_temp,
-- avg_ram_mb were in schema 0001 with NO producer until 2026-09-21 (Telemetry.SystemTelemetrySource
@@ -334,8 +387,12 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `ui.theme` | choice | `system` | `system` · `light` · `dark` | UI |
| `ui.start_with_windows` | bool | `0` | | UI (P4) |
| `ui.minimize_to_tray` | bool | `0` | | UI (PR-8) |
| `ui.hide_anticheat_hooking` | bool | `1` | | UI (beta.8, 2026-09-25): the game page of an entry the guard found anti-cheat in shows the finding in place of its Hooking card (`08_UI` §Game detail) |
| `ui.fps_decimals` | bool | `0` | | UI (beta.8, 2026-09-25): every FPS figure with two decimals ("62.40") instead of a whole number |
| `capture.background` | bool | `1` | | Agent |
| `hooking.kill_switch` | bool | `0` | | Agent (FR-2.4, since P2 PR-F) |
| `hooking.usermode_ac_exceptions` | bool | `0` | | Agent, at every session start and command (FR-2.8, D33, 2026-09-26): off suspends every user-mode exception without deleting any; on, the user still grants each eligible game |
| `capture.run_elevated` | bool | `0` | | The App when it starts the Agent, and an Agent the logon task started — both BEFORE the Agent exists, through `Infrastructure.Startup.RunElevatedSetting` (one row, `PRAGMA query_only`, no version gate, anything but `1` is off) (D34, beta.10): on, Windows is asked for administrator rights at every Agent start (`01_ARCHITECTURE` ADR-9) |
| `capture.min_session_s` | int | `30` | 5–600 | Agent, per session (FR-3.6) |
| `telemetry.interval_ms` | int | `1000` | 500–2000 | Agent, per session (FR-3.5) |
| `retention.raw_sessions_per_game` | int | `20` | 0–10000; **0 = unlimited** | Agent, per session (§Retention) |
@@ -359,6 +416,9 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> record ON THE SAME SWAPCHAIN; the first record of a stream, and any record after a torn slot or an
> overwrite skip, carries 0 with the `frame_flags` gap bit set, so the statistics exclude it and the export
> still reconstructs `qpc_ms`. `swapchain_ids` is present only when the session held more than one stream.
> **Schema 0013 (beta.8)** adds `frame_blobs.first_present_ms`: the charts draw the dominant stream from its first present
> and the sensors from `qpc_epoch`, and nothing said how far apart the two zeros were. Gaps stay closed up on the frame
> axis (a gap's interval is stored as 0), so a series still drifts ahead of its sensors past each gap.
> Sensor series are aligned to `t_ms` (milliseconds from `qpc_epoch`) and a tick with no reading is stored as
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.s (NaN forbidden — assert).
@@ -389,6 +449,16 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> column computed from the prefix exactly as a live finalize would. **Rejected:** a `sessions_in_progress`
> table — a blob churn every minute, a lock fight with the UI in P3, and `04_CAPTURE` had already named a
> file under `tmp\`.
>
> **The header's `game_id` is where the session started, not necessarily where it lands (2026-09-23).** A live
> finalize and a recovery both ask `ISessionRepository.ResolveOwnerAsync`: that id when the row predates the session
> or holds the header's exe path; else the row that holds the exe path now (an entry removed and re-imported while
> the game ran); else nothing — `FinalizeStatus.GameRemoved` / `RecoveryStatus.GameRemoved`, file deleted, nothing
> written. `games.id` is `INTEGER PRIMARY KEY` without AUTOINCREMENT, so a deleted id can be handed to the next row
> added; `added_at` after the session's start and another path is how that row is told apart. A file recovery cannot
> finalize for any other reason is renamed `<guid>.partial.failed` (`IPartialSessionStore.Quarantine`) — not listed
> again, not retried, kept for a bug report — and recovery goes on to the next file: it runs before the watcher on
> every start, and one file used to be able to stop them all.
## Retention
@@ -447,6 +517,66 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
> detail still set beside it. A reader that ignores the scope reads a steady factor as a session one, which is why
> every surface prints the share. Existing rows keep NULL. `LatestVersion` is 6.
> **`0007_guard_bypass.sql` (2026-09-21) and `0008_withdraw_guard_bypass.sql` (2026-09-22) — the first DROP.** 0007
> added five columns for the per-game guard override; the owner withdrew the feature a day later and 0008 drops them
> (`ALTER TABLE … DROP COLUMN`, SQLite ≥ 3.35 — `LedgerDatabaseTests` asserts the engine's version beside the columns'
> absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The
> data dropped is the override acknowledgements themselves, which is the decision. `LatestVersion` is 8.
> **`0010_prescan_key.sql` (2026-09-25) — `games.hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` /
> `hook_prescan_exe_mtime_ms`.** The Agent pre-scans every library entry for anti-cheat since beta.8, and again
> whenever the rules or the executable change, so it needs what each row was last scanned against — its own key, as
> 0004's columns are the detection sweep's, and apart from `exe_size_bytes` / `exe_mtime_ms` for the same reason
> (the consent fingerprint must never be refreshed by a background scan). `ALTER TABLE ADD COLUMN` only; existing
> rows read NULL, which the sweep reads as "never scanned" and scans on its first pass. `LatestVersion` is 10;
> `LedgerDatabaseTests.ScriptTenAddsThePreScanKeyEmptyForExistingRows` applies it from 9 to a ledger holding a row.
> **`0011_executable_facts.sql` (2026-09-25) — `games.exe_machine` / `exe_file_version` / `exe_product_version` /
> `library_versions`.** The owner asked for the game's version, its DLSS / FSR versions and 32- or 64-bit; the detection
> sweep read the PE version resource and walked the tree for the capability files, and kept neither. Four columns,
> written whole by that sweep (`05_DETECTION` §What the files say about themselves) — facts about files, so no
> provenance and no user override. Existing rows read NULL, and a NULL `exe_machine` makes the sweep read the row once
> more on its first pass. `LatestVersion` is 11; `LedgerDatabaseTests.ScriptElevenAddsTheExecutableFactsEmptyForExistingRows`.
> **`0012_driver_profile.sql` (2026-09-25) — `sessions.driver_profile`.** The NVIDIA driver profile the session's
> executable ran under, read by the Agent's recorder beside every session (both tiers) through the NVAPI bridge's
> read-only DRS entry point (`18_GPU_VENDOR_APIS` §L3, ABI 2): JSON (`Application.Recording.DriverProfileRecord`) —
> `Outcome` (`Application` | `Global` | `Degraded`), `Profile`, and one entry per setting of
> `Application.Capture.NvidiaDriverSettings` with its `Value` (null = set in no profile), `Location` and `Predefined`.
> A driver configuration, never a measurement (`03_METRICS` §Upscaling). NULL for every row before, and where no
> NVIDIA bridge was there to ask. The same day `ngx_driver_words` gained `Ratio`, `Mode`, `Preset`, `FgCount`,
> `FgPreset`, `FgMode` beside its masks (additive JSON fields; older rows lack them). `LatestVersion` is 12;
> `LedgerDatabaseTests.ScriptTwelveAddsTheDriverProfileColumn`.
> **`0014_usermode_ac_exception.sql` (beta.9, 2026-09-26, owner decision D33) — the user-mode anti-cheat exception.**
> Fourteen `games.ac_exception_*` columns in three groups — the Agent's eligibility answer about a blocked row and its
> key, the user's grant, and how the last grant ended — and `sessions.ac_exception_family`, the family a HOOKED session
> ran under the exception with. `ADD COLUMN` only; no row changes, so a blocked row stays blocked, not eligible, with
> no grant, until the Agent and the user say otherwise (`19_SAFETY` §The user-mode exception). Written through
> `IGameConsentStore` only — `RecordExceptionEligibilityAsync` (the sweep), `GrantAntiCheatExceptionAsync` (the
> `SetAntiCheatException` command; the store applies `UserModeExceptionRules.IsEligible` itself), `RevokeAntiCheatExceptionAsync`
> (every end) — plus one downgrade in `ChangeExecutableAsync`, which ends a grant (`ExecutableChanged`) and forgets
> the eligibility. The grant and the eligibility are each bound in SQL to the block they were reached about. `LatestVersion`
> is 14; `LedgerDatabaseTests.ScriptFourteenAddsTheExceptionColumnsAndChangesNoRow`.
> **`0015_engine_version_source.sql` (beta.10, 2026-09-27) — where an engine version came from.** `games.engine_version_source`
> (`05_DETECTION` §Engine version): the witness an Unreal version rests on, or the rule's extractor type for every other
> engine; written by `ApplyDetectionAsync` only where the run's version was taken (a `user` field keeps none), cleared by a
> user's edit of the version (`UpdateMetadataAsync`). The script's one data change removes the bare `4` / `5` the old
> Unreal rule wrote (a two-group regex returning its first group) — **only where `field_provenance` says `detected`**: a
> value the user typed, one with no badge (which reads as the user's) and one whose provenance does not parse stay as they
> were, and the last does not fail the migration (`CASE WHEN json_valid(…)`, since SQLite promises no order for `AND`).
> `LatestVersion` is 15; `LedgerDatabaseTests.ScriptFifteenAddsTheWitnessAndRemovesOnlyTheOldRulesDetectedDigit`.
> **`0016_display_mode.sql` (beta.10, 2026-09-27) — how the game was shown.** Fifteen `sessions.display_*` columns
> (`03_METRICS` §Display mode): milliseconds in each mode, the changes, the witness, and the window / back buffer / monitor
> sizes in the mode that lasted longest. ADD COLUMN only, no data change: a session recorded before reads N/A. Written by
> the recorder on the row's skeleton (`Recording.SessionDisplayColumns.WithDisplay`), so a Tier-2 session — which never
> reaches the aggregator — has them too; `sessions.swap_effect`, a column since 0001, gets its first writer from the same
> facts. `SessionRowColumns` is hand-edited (its generator is not in the repository) and reads by name. `LatestVersion` is
> 16; `LedgerDatabaseTests.ScriptSixteenAddsTheDisplayColumnsAndAnEarlierSessionHasNone`,
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`.
> **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
+100 -15
View File
@@ -12,13 +12,15 @@ Three channels, each chosen for its constraints:
Created by the Overlay on init, opened by the Agent. Name is deliberately plain and identifiable (`19_SAFETY` — no obfuscated object names).
Layout — **four regions, each exactly one 64-byte cache line before the ring**:
Layout — **~~four~~ five regions, each exactly one 64-byte cache line before the ring** (layout 4 since
2026-09-27, beta.10: region 4 is new and the ring moved from `0xC0` to `0x100`):
```
[0x0000] FlShmHandshake 64 B write-once by the Overlay at init
[0x0040] FlWriterState 64 B Overlay-written (writeIndex touched every present)
[0x0080] FlControlBlock 64 B Agent-written
[0x00C0] FlFrameRecord[capacity] (64 B each, power-of-two capacity)
[0x00C0] FlDisplayState 64 B Overlay-written, at most every 500 ms per chain (layout 4)
[0x0100] FlFrameRecord[capacity] (64 B each, power-of-two capacity)
```
The header is split in two on purpose. The immutable handshake and the
@@ -49,9 +51,19 @@ struct alignas(64) FlWriterState { // Overlay-written
uint32_t rtStateObjectsCreated; // @32 session count, published at 1 Hz
uint32_t rasterPsoCreated; // @36 session count, published at 1 Hz
uint32_t runtimeCensus; // @40 FlRuntimeCensus bits; watchdog-published, OR-only (2026-09-03, took reserved[0])
uint32_t reserved[5]; // @44..63 must be zero; reserved for additive fields
uint32_t slTagCensus; // @44 FlSlTagType bits per route (2026-09-05)
uint32_t dxgiPresentsUnseen; // @48 presents DXGI counted beyond the hooked ones (2026-09-05, saturating)
uint32_t dxgiPresentSamples; // @52 hooked presents on which that counter was read
uint16_t loaderSignals; // @56 the LoadLibrary detour's installed bit + wake count (2026-09-06)
uint16_t earlyStopFamily; // @58 1-based floor family index of an early stop; 0 = none (2026-09-06)
uint32_t dxgiPresentsBeforeHook; // @60 presents before the first hooked one (2026-09-06) -- the LAST word:
// no slack left, so layout 4 added a region rather than a field
};
> **This block showed `reserved[5]` at @44 until 2026-09-27** — five words the header had spent by 2026-09-06
> (`slTagCensus`, the two DXGI counters, the loader words, `dxgiPresentsBeforeHook`). `fl_shm.h` is normative and the
> mirror test reads the header, so nothing broke; a reader of this page was told there was room where there was none.
struct alignas(64) FlControlBlock { // Agent-written
uint32_t pauseRequested; // @0
uint32_t unhookRequested; // @4 19_SAFETY: set when the guard fires mid-session
@@ -61,12 +73,41 @@ struct alignas(64) FlControlBlock { // Agent-written
uint32_t reserved[11]; // @20..63 must be zero
};
struct alignas(64) FlDisplayState { // Overlay-written (layout 4, 2026-09-27, beta.10)
uint32_t seq; // @0 seqlock: odd while a writer is inside; the writer CASes and SKIPS if taken
uint32_t flags; // @4 FlDisplayFlags: SAMPLED | EXCLUSIVE_KNOWN | EXCLUSIVE | OPENGL
uint64_t hwnd; // @8 OutputWindow (DXGI) or WindowFromDC (OpenGL); 0 = a composition chain
uint32_t bufferWidth; // @16 the back buffer (DXGI) / client area (OpenGL)
uint32_t bufferHeight; // @20
uint32_t swapEffect; // @24 DXGI_SWAP_EFFECT + 1 (DISCARD is 0); 0 = not read
uint32_t swapFlags; // @28 DXGI_SWAP_CHAIN_DESC.Flags
uint32_t chainId; // @32 the FlFrameRecord.swapchainId described
uint32_t samples; // @36 samples published (wraps)
uint64_t sampleQpc; // @40 QPC of the last sample
uint32_t reserved[4]; // @48..63 must be zero
};
static_assert(sizeof(FlShmHandshake) == 64);
static_assert(sizeof(FlWriterState) == 64);
static_assert(sizeof(FlControlBlock) == 64);
static_assert(FL_SHM_RING_OFFSET == 0xC0 && FL_SHM_RING_OFFSET % 64 == 0);
static_assert(sizeof(FlDisplayState) == 64);
static_assert(FL_SHM_DISPLAY_OFFSET == 0xC0 && FL_SHM_RING_OFFSET == 0x100 && FL_SHM_RING_OFFSET % 64 == 0);
```
**Region 4 — the presenting swap chain's display facts (layout 4, 2026-09-27, beta.10).** The owner asked for the game's
window size and display mode (exclusive fullscreen / borderless / windowed) and the share of a session each took. The two
facts only the process knows — whether the chain is in exclusive fullscreen, and which window it presents to — are
getters on the chain the title passed to the hooked Present (`GetFullscreenState`, `GetDesc`), asked at most every 500 ms
per chain; everything else — the window's rectangle and style, its monitor, the classification — is the Agent's, read
out of process with user32 at the drain tick, exactly as the foreground sample is (`03_METRICS` §Display mode). The
region describes ONE chain: the largest back buffer, and a chain silent for 2 s gives way; `chainId` names it. It is a
seqlock the writer never waits on — a writer that finds `seq` odd (another presenting thread inside) skips the sample and
the next present retries — and `ShmRingReader.DisplayState` takes a copy between two reads of an even, unchanged `seq`
(eight attempts, then null for that tick). The Vulkan layer never writes it (all zeros: nothing sampled); an OpenGL stream
writes the window and client size with no exclusive bits, which a reader treats as *unknown*, never as *windowed*. A
minimised game presents only `DXGI_PRESENT_TEST`, which the hook drops before sampling, so a `sampleQpc` older than 2 s
leaves the exclusive bits unknown.
The cross-process fields are declared as plain integers and accessed through
`std::atomic_ref` rather than as `std::atomic<T>` members. `std::atomic<T>` has
no guaranteed layout, cannot be memcpy'd, and cannot be mirrored by a C#
@@ -260,6 +301,28 @@ same class of bug as record drift.
Agent is inert from the beginning rather than enjoying a grace window.
- If `unhookRequested` is set, the Overlay disables hooks within one frame and sets `status = unhooked`. This path must be the fastest, most-tested code in the DLL: it is the safety stop.
## D — the tolerance mapping (`Local\FrameLedger.Tolerate.<pid>`), D33 (2026-09-26)
Agent → Overlay, once, BEFORE the injection it concerns: the anti-cheat family NAMES a game's user-mode exception
covers (`19_SAFETY` §The user-mode exception). It cannot live in A + B: the Overlay creates that mapping on init and the
Agent opens it afterwards, while the Overlay's loader detour must know the tolerance from the moment it exists.
```cpp
struct FlTolerance { // fl_tolerance.h; 16 + 8 x 64 = 528 B, no padding
uint32_t magic; // @0 FL_TOLERANCE_MAGIC ("FLTL")
uint32_t version; // @4 FL_TOLERANCE_VERSION (1)
uint32_t count; // @8 names used, <= 8
uint32_t reserved; // @12 zero
char families[8][64]; // @16 NUL-terminated ASCII family names
};
```
Created by the Agent for the game's pid, current user only, held for the session; read once by the Overlay's
`InitThread` before `InstallLoaderHook`, which resolves every name against its own compiled floor and honours only a
user-mode family. Absent, malformed or naming anything else: nothing is tolerated. Mirrored as `FlTolerance` /
`ToleranceLayout` in `FrameLedger.Shared` and held to the native layout by `ShmLayoutMirrorTests` through
`fl-layout-dump`. *(Built in beta.9: PR-1, the Overlay reads it; PR-2, the Agent writes it — `Infrastructure.Capture.OverlayToleranceChannel`, security descriptor `O:<user>D:P(A;;GR;;;<user>)` stated rather than defaulted (an elevated Agent's default DACL omits the user, and the Overlay in an unelevated game could not open it), a name that already exists refused as not ours, and a channel that cannot be published is no exception: the session then names no family and the blocked game is refused as before.)*
## C — command pipe (`\\.\pipe\FrameLedger.v2`)
Unchanged in spirit from v1, bumped to `v2` for the new message set.
@@ -323,24 +386,26 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
| Type | Dir | Payload / notes |
|---|---|---|
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. `vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered) and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` |
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, exceptionDisclosureVersion /* D33, 2026-09-26: the user-mode exception's disclosure this Agent grants against */, elevationOutcome /* beta.10, D34: the admin mode's answer at this start — granted, declined, other-account, failed — or null when nobody asked */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. `vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered) and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` — and `activeSessions[]`, one `{ sessionGuid, gameId, gameName?, pid, tier, startedAt, hold? }` per running session. **`hold` added 2026-09-23, optional:** present on a session held unhooked (Tier 2), with the same words `SessionStarted.hold` carries; a session listed at tier 2 WITHOUT a `hold` has not attached yet — it is starting, not held. The App reads this list on every (re)connect (§Client behavior) |
| `SetWatchlist` | UI→A | `{ entries: [{ gameId?, exePath }] }` — ~~full replace~~ **ensure, never remove** (built 2026-09-13, PR-1b): each entry's path is normalised by the Agent, its row ensured with hooking OFF when new, and the ack is `WatchlistAck { games: [{ gameId, exePath, name }], unreadable: [exePath] }`; `gameId` in a request is a hint and never trusted over the path. UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary). *Since the App writes `games` rows itself under `06_DATA_MODEL` §Writer ownership (HANDOFF §P3 D15), this is the pipe's way of adding a row, not the only one; the watcher reads the table at 1 Hz either way.* |
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable`. *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* |
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable` · `RecordingOff` (2026-09-23: the entry's recording switch is off, FR-1.6 — FrameLedger does not start what it will not record). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). **Since D33 (2026-09-26):** for a blocked game whose user-mode exception is in force for the executable on disk (the option on, a grant made on these bytes, the block naming that family) the pre-scan NAMES the family, and a pass under it is stamped as ever and answered `prescan: "exception"`; a finding about the game under it also ends the exception. |
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — 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.)* |
| `Shutdown` | UI→A | graceful stop → `ShutdownAck`, then the host stops (sessions finalize inside its grace window). *(Built 2026-09-13, PR-1b: `IAgentLifetime`, the host's under `--serve`, a logged no-op under `--console`.)* |
| `SweepRetention` | UI→A | **no payload** — a trigger, like `UpdateRules`: the Agent applies `06_DATA_MODEL` §Retention to every game with the `retention.raw_sessions_per_game` it reads itself → `SweepRetentionAck { keep, games, sessions }` (`keep` 0 = unlimited, and then nothing was swept). *(Built 2026-09-15, P4 PR-7, for Tools ▸ Database maintenance: `Application.Recording.RetentionSweep` over `ISessionRepository.SweepRetentionAllAsync`, composed into `AgentCommandHandler` under `--serve`. The client names no number because the rows are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the dialog reads as "restart the Agent". Carries no safety fact.)* |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt }` — **published at the attach**, i.e. when the session becomes Tier 1 and the live card has something to show; a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2) and, when a refusal or error caused that, the event below that names it |
| `SetGuardBypass` | UI→A | `{ gameId, enabled, disclosureVersion? }` → `GuardBypassAck { gameId, enabled, outcome }` (owner decision 2026-09-21, `19_SAFETY` §The user's bypass). `enabled: true` records that the user accepted the bypass disclosure for this game's executable: refused with `DisclosureVersionMismatch` for any version but the Agent's own `GuardBypassDisclosure.Version`, `ExecutableUnreadable`, `UnknownGame`, or `DisclosureUnavailable` where no store was composed; `outcome` is the store's `ConsentWriteOutcome` (`StaleFingerprint` when the binary is not the row's). `enabled: false` withdraws it. It writes two columns and enables nothing. **There is no global form of this message.** `HookEnabledAck.prescan` gains the value `"bypassed"`: the pre-scan refused, the finding was written, and the consent was stamped beside it |
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt, hold? }` — **published once per session**: at the attach (tier 1, `startedAt` the attach), or — **since 2026-09-23** — at the first tick of a session held unhooked (tier 2, `startedAt` the session's start, `pid` 0 when the loop never opened the process, as a hooking-off hold never does). ~~a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2)~~ — that was the beta.5 wire, and every hooking-off, refused or unreadable game read "Nothing is being captured." for as long as it ran. **`hold` (optional, tier 2 only)** is why nothing is measured: `{ reason, guardReason?, family?, signal?, hookingTurnedOff }` — the loop's `SessionEndReason` and, when the guard said anything but allow, its reason, family and signal: the same words the row's `capture_notes` will carry, so the live card and the summary read one sentence (`Formats.Tier2HoldReason` / `Tier2Reason`). The refusal's own event (`CaptureRefused` and the rest, below) goes out with this start rather than when the game exits, and is not repeated at the end |
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct? }` — how long it has run and the machine's sensors. **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus? }` — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason` |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal? }` — **guard fired**; UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal? }` — anti-cheat appeared mid-session; prominent UI notice. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
| `CaptureError` | A→UI | `{ sessionGuid?, code, message }` — `InjectFailed`, `RingVersionMismatch`, `AttachRefused`, ~~`EtwAccessDenied`~~ (struck 2026-09-13 with the tier), ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed`, `SessionFaulted` (the session's task threw before finalize; the `.partial` stays for recovery, and no `SessionCompleted` follows). *(Built: `RingVersionMismatch` for a layout / record-size / build-id refusal — the "restart the game after an update" case — `AttachRefused` for the rest of the ring's refusals, `InjectFailed` for a target that could not be started, pinned, read or singled out.)* |
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff }` — anti-cheat appeared mid-session; prominent UI notice; `hookingTurnedOff` as on `CaptureRefused`. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
| `HookingTurnedOff` | A→UI | `{ gameId, gameName?, reason, family?, signal? }` — **since 2026-09-25 (beta.8):** the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) found anti-cheat in a game whose hooking the user had turned on, and turned it off. Not a session event — no session is running — so the UI's notice carries no "record without measuring" action, only Dismiss (`SafetyNoticeKind.HookingOff`). A finding on a game whose hooking was already off sends nothing: its page and its library card change, nothing the user switched on did. Additive: a client that does not know the type ignores it (§Versioning). |
| `CaptureError` | A→UI | `{ sessionGuid?, code, message }` — `InjectFailed`, `RingVersionMismatch`, `AttachRefused`, ~~`EtwAccessDenied`~~ (struck 2026-09-13 with the tier), ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed`, `SessionFaulted` (the session's task threw before finalize; the `.partial` stays for recovery, and ~~no `SessionCompleted` follows~~ a `SessionCompleted` with `finalize: faulted` follows since 2026-09-23). *(Built: `RingVersionMismatch` for a layout / record-size / build-id refusal — the "restart the game after an update" case — `AttachRefused` for the rest of the ring's refusals, `InjectFailed` for a target that could not be started, pinned, read or singled out.)* |
| `Ping`/`Pong` | ~~both~~ UI→A | 15 s keepalive, **client-driven** (built 2026-09-13): the client pings, the Agent answers; the Agent initiates nothing on an idle connection |
## The pipe is not a trust boundary
@@ -381,6 +446,13 @@ message, and that message always re-scans.
## Client behavior (UI)
- **The running sessions are the status's, then the events' (2026-09-23).** Every list of running sessions the App
keeps is seeded from `StatusAck.activeSessions` on every (re)connect and moved by `SessionStarted` /
`SessionCompleted` after that; a lost Agent empties it. The Dashboard reads the App-lifetime `LiveSessions`
service (it is rebuilt per visit, so a list of its own would start empty); the tray and the updater seed their
own from the same status. Before this a Dashboard opened after a game started read "Nothing is being captured.",
the tray stayed idle for a session that began before the App connected, and the updater held an update at
*Deferred* on a status read hours earlier.
- Connect with 250 ms × 8 backoff; on failure start the Agent, retry; then show an Agent status banner with Repair.
> **Amended 2026-09-17: never a second Agent.** A round that ends without a connection starts one only when no
@@ -390,9 +462,22 @@ message, and that message always re-scans.
> before this the reason was swallowed, and a refusal looked exactly like an absent Agent). The Agent it does start
> is watched until it exits and its exit code logged, so exit 10 — the folder was already claimed — is visible in
> the App's log. `AgentConnectionTests` pins both.
> **Amended 2026-09-27 (beta.10, the admin mode, D34): a start may ask Windows first.** With `capture.run_elevated` on
> and this App a standard user's, the start is a UAC prompt owned by the App's window (`IAgentLauncher.WillAskForElevation`
> turns the pill into *Waiting for administrator permission*), and while it is up the folder's `ElevationMarker`
> (`Local\FrameLedger.Agent.Elevating.<hash>`) is held — `RunningAgent` reads it as "an Agent is coming", so the App never
> prompts beside the logon task's Agent, which holds the same marker while its own prompt waits on the taskbar. A declined
> prompt starts the standard user's Agent with `--elevation declined`; an elevated Agent that exits 11 (another account
> answered) makes the App start standard-user Agents until it restarts.
- **Named objects an elevated process creates state their DACL (beta.10).** An elevated token's default DACL grants
Administrators and SYSTEM and not the user, so an object an elevated Agent creates with it cannot be opened by the same
user's unelevated App or game: the pipe (`PipeAccessControl`), the tolerance mapping (§D) and — since beta.10 — the
ledger's migration lock (`Infrastructure.Startup.SharedMutex`: owner the user, full access to the user, Administrators
and SYSTEM) each carry an explicit descriptor. The instance lock and the elevation marker are only ever probed, and a
probe that is refused reads as "held".
- Treat the pipe as unreliable: library, history and charts must all work with the Agent offline. Only live status degrades.
- SQLite is the source of truth for anything persisted; pipe events are refresh signals (except `SessionProgress`, which is live-only by design).
- `CaptureRefused` and `SafetyUnhook` are **never** collapsed into a generic error toast — they get dedicated, explanatory UI (`08_UI` §Notifications).
- `CaptureRefused`, `SafetyUnhook` and (since 2026-09-25) `HookingTurnedOff` are **never** collapsed into a generic error toast — they get dedicated, explanatory UI (`08_UI` §Notifications).
## Versioning
+212 -4
View File
@@ -24,7 +24,11 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
**Menu bar**
- **File:** Add game… · Import library (Steam / GOG / Epic / itch.io) · Export ▸ (Session CSV / Session JSON / Chart PNG) · Exit
- **Tools:** Agent status… · Update detection rules · Vulkan layer registration… · Open data folder · Database maintenance…
- **Help:** Check for updates · Report a bug… · Documentation · About FrameLedger (App / Developer / Third-party licenses tabs)
- **Help:** Check for updates · Report a bug… · Documentation · Limitations · About FrameLedger (App / Developer / Third-party licenses tabs)
> **Help ▸ Limitations, beta.10 (D36):** `LIMITATIONS.md` as the build embeds it (`Services.LimitationsDocument`), in a
> read-only, scrolling WPF UI `MessageBox` with *Open on GitHub*. It is information, not one of FR-11's documents:
> nothing is accepted or recorded, and the Disclaimer points at it.
The Menu sits in its own row **below** the TitleBar (never inside the drag region — 16 §Gotchas).
@@ -93,7 +97,12 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
> duration and hardware telemetry — with every frame-derived value at N/A"). The one button is
> `Safety_RecordWithoutMeasuring` on a refusal and Dismiss otherwise; it removes the notice and does nothing
> else, because the Agent already records Tier 2 on a refusal (owner decision 2026-08-28) — the button is the
> user's acknowledgement, not a second request. `CaptureError` (non-fatal) goes to the 4 s strip. The safety
> user's acknowledgement, not a second request. *(That sentence became true on 2026-09-22: until then every
> refused session was discarded under the minimum length, and for one day `TargetUnreadable` omitted the
> "still recorded" sentence for that reason. `04_CAPTURE` §Tier selection.)* The session summary of a Tier-2 row
> says WHY under its Tier-2 sentence (`Formats.Tier2Reason` over `capture_notes`: hooking off, the block on the
> row, the guard's family and signal, a process that could not be opened, or the end reason by name —
> `Summary_Tier2_Why_*`). `CaptureError` (non-fatal) goes to the 4 s strip. The safety
> documentation link lives on the Settings page's Capture section rather than in every notice. Tests:
> `SafetyNoticesTests` (the three kinds, the sentence per refusal reason, the strip for errors, nothing for a
> session event, dismiss only by the user).
@@ -106,6 +115,14 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
> `PagesLoadTests.TheInfoBarTemplateRendersItsContent`, which renders both templates and fails when upstream
> gains a presenter — the signal to delete the copy.
> **The pre-scan's notice (2026-09-25, beta.8).** The Agent's pre-scan of the library (`19_SAFETY` §What a finding
> does to the game) sends `HookingTurnedOff` when it turned off hooking the user had turned on; `SafetyNotices` makes
> it a `SafetyNotice` of kind `HookingOff` — Error, persistent like the others, titled *"{game}: hooking turned off"*
> (`Notice_HookingOff_Title_Format`), the refusal sentence naming the family and the signal followed by
> `Safety_HookingTurnedOff`. It has **no** `Notice_Refused_Recording` and its button is Dismiss, not
> `Safety_RecordWithoutMeasuring`: no session is running, so there is nothing to record without measuring. A finding
> on a game whose hooking was already off raises no notice; its card and its page say it (§Games).
## FPS display rule (global, FR-4.2 / CLAUDE.md rule 6)
Reusable control `FpsReadout` (custom control styled with WPF UI theme brushes):
@@ -142,6 +159,19 @@ All screens are `Page`s registered with the navigation page provider and navigat
> session reloads the lists (the row is in SQLite, `07_IPC` §Client behavior). Totals = the library's games,
> `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. Capability badges and the Repair button are
> PR-8's with the Agent section.
>
> **Amended 2026-09-23: the card shows every running session, measured or not.** A session held unhooked
> (Tier 2 — hooking off, refused, unreadable) shows its name, the T2 badge, the elapsed time and the
> machine's temperatures from `SessionHeld`, the line "Recording duration and sensors only — nothing is
> measured." and **why**, in the sentence its summary will carry (`Formats.Tier2HoldReason` over the start's
> `hold`, the same words `Tier2Reason` reads from `capture_notes`) — and no `FpsReadout` at all. A session the
> status lists at tier 2 with no `hold` has not attached yet: its name and badge until the attach's start arrives,
> never the held line and never the "Attached — waiting" one. A hooked session takes the card from a held one,
> never the reverse. The card is seeded from the
> App-lifetime `LiveSessions` when the Dashboard is built, so a session that started while another page was
> open is on it at once; the completion notice names the session that completed (`SessionCompleted.gameName`)
> and a `faulted` completion is no notice (the strip's `CaptureError` already said it). Until this date the
> Agent announced only hooked sessions: every other game read "Nothing is being captured." while it ran.
### Games (grid → detail)
- `GridView`-style panel of cover cards (`ui:CardAction`): name, platform badge, engine badge, total playtime, last played, mini trend sparkline (avg Native FPS last 10 sessions). Sort/filter/`ui:AutoSuggestBox` search.
@@ -163,7 +193,7 @@ All screens are `Page`s registered with the navigation page provider and navigat
> fields), **the row's executable path under the subtitle and Change executable… since 2026-09-21** (a store import
> guesses the executable and everything downstream is keyed on it; the pick re-points the row, which comes back
> hooking-off and unconsented like a new game, consent revoked over the pipe first, a block never cleared —
> `05_DETECTION` §Library import), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), **the guard-bypass switch since 2026-09-21** (`19_SAFETY` §The user's bypass, FR-2.7: a `CardControl` with a `OneWay` toggle under the hooking card, its body text, and — while it is on — a non-closable **Error** `InfoBar` saying so; ON opens `GuardBypassPrompt`, a `ContentDialog` whose Danger primary button is enabled only while the acknowledgement is ticked AND `BYPASS` is typed, `DefaultButton = Close`; OFF needs no dialog; the switch shows the ROW, never the click; a blocked row's hooking toggle becomes usable while the bypass is on and the block's text stays on the page — as "The guard found: … You chose to bypass it", not as "Hooking is disabled for this game", which is what beta.3 printed beside a hooking switch that was ON; a session that started under it reads "· Guard bypassed: <family>" in the list's exit column and carries an Error `InfoBar` in its summary), **Supports** (from `capability_flags`; ~~empty until P4's scan writes it, and the card says so~~ **written by the Agent's detection sweep since P4 PR-1, 2026-09-14** — the rule ids as product names via `CapabilityNames`, "not scanned yet" only until the Agent's next tick) beside
> `05_DETECTION` §Library import), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), ~~**the guard-bypass switch since 2026-09-21**~~ **withdrawn 2026-09-22** (the card, its dialog, the session mark and the export line are gone; a blocked row's toggle is disabled and `Safety_Blocked_Toggle_Format` is the whole story; a refusal or unhook notice that turned hooking off ends with `Safety_HookingTurnedOff` — `19_SAFETY` §What a finding does to the game), **Supports** (from `capability_flags`; ~~empty until P4's scan writes it, and the card says so~~ **written by the Agent's detection sweep since P4 PR-1, 2026-09-14** — the rule ids as product names via `CapabilityNames`, "not scanned yet" only until the Agent's next tick) beside
> **Last session measured** (upscaler · resolution, frame generation, the non-N/A chips — accent pills, from the
> hooks). Hooking: the toggle is `OneWay` from the row and its command runs `HookingConsent`; a refusal, a
> mismatch or a failure is a persistent `InfoBar` on the page (never a toast); a blocked row disables the
@@ -173,11 +203,75 @@ All screens are `Page`s registered with the navigation page provider and navigat
> with tooltips. Frametime / Distribution / Trend / Sensors / Latency say which build brings them (PR-6, PR-7).
> `PagesLoadTests` loads every page and both control templates under the real theme dictionaries on an STA
> thread, so a binding typo is red in CI rather than a `XamlParseException` at first navigation.
>
> **The recording switch (2026-09-23, FR-1.6).** A `ui:CardControl` **Recording** above the hooking control, its
> `ToggleSwitch` `OneWay` from `games.record_sessions` and its command writing the row through
> `GameLibrary.SetRecordingAsync` — no dialog (it deletes nothing; sessions already recorded stay) and nothing over
> the pipe (the Agent reads the table each tick). Status line *Recorded when it runs* / *Ignored — nothing is
> recorded*; the body says what off means (the program is not watched; a running session stops) and when to use it
> (a utility that starts with Windows). The library card shows **Not recorded** in place of the hooking badge, since an
> ignored program is never hooked whatever its hooking switch says. The hooking control stays independent: a user can
> keep a consent on an entry they stopped recording for a while.
>
> **Anti-cheat games (2026-09-25, beta.8, owner decision).** The Agent pre-scans every library entry now, so the App
> knows which games ship anti-cheat before anyone asks to hook them (`19_SAFETY` §What a finding does to the game).
> The library card says **Anti-cheat** in place of *Hooking off* — the caution fill with primary text, the warning
> qualifier's pair that `ContrastTests` measures in both themes — for an entry that is recorded (*Not recorded* still
> comes first). On the game's page the Hooking card is a switch that could only be refused, so while
> `ui.hide_anticheat_hooking` is on — its default, Settings ▸ Capture *Hide hooking on anti-cheat games* — the card
> and its lines give way to one **Anti-cheat** card: *"Found: {what}. Hooking is off for this game and cannot be
> turned on; its sessions record play time and sensors only."* Off, the card is back with the switch disabled and
> `Safety_Blocked_Toggle_Format` under it. `{what}` is `Services.BlockedReasonText` over the stored
> `Reason|Family|Signal` — *"BattlEye — its module BEClient_x64.dll was loaded in the game"*, *"Easy Anti-Cheat —
> its folder EasyAntiCheat ships with the game"*, *"… is a listed title"*, *"the game's store id … is listed"* —
> and a row stored before that form is shown as it was. The crash auto-disable's re-enable bar is not offered on a
> blocked row: its one action could only be refused. Tests: `GameDetailViewModelTests` (hidden, shown, the card
> pill), `BlockedReasonTextTests`, `PagesLoadTests.AnAntiCheatGamesPageRendersTheFindingInPlaceOfTheHookingCard`.
>
> **The user-mode exception (2026-09-26, beta.9, owner decision D33).** While Settings' option is on, a blocked
> game's page shows a **User-mode exception** card with the Agent's answer about it (`Services.ExceptionView` over
> `GameRow.AcException` — the App reads those columns and writes none): *Eligible — no exception made* with **Make
> exception…**; *Checking…* until the Agent has looked at this block; *Not eligible: N successful hooked session(s), two
> are needed*; *Not eligible: the guard also found {family} ({signal})* — Aniimo's *Kernel driver in the game folder
> (NEPKernel.sys)*; *Not eligible: {family} is not user-mode throughout*; and how the last exception ended. **Make
> exception…** opens the exception's disclosure (`AntiCheatExceptionPrompt`, text `Safety_Exception_*` versioned by
> `AntiCheatExceptionDisclosure.Version`, the primary button bound to the ticked *I accept the risk of a ban for this
> game*, Enter = *Keep it blocked*) and then `SetAntiCheatException`; the Agent gathers the facts and grants or
> refuses, and the page says which. An exception in force brings the Hooking card back — even while anti-cheat cards
> are hidden — with its switch usable through FR-2.1's dialog as ever, the finding still under it; **Withdraw
> exception** ends it and turns hooking off. With the option off a kept exception is shown *suspended* and the switch
> is disabled again. The library card says **Exception** for a game carrying one; a hooked session under it is
> *Hooked · exception* in the Sessions tab (the tooltip names the family) and its summary has one line saying so.
> Tests: `GameDetailViewModelTests.AnEligibleGameOffersTheExceptionAndOneInForceMakesTheSwitchUsable`,
> `…WhyAGameIsNotEligibleIsSaidOnItsPage`, `AntiCheatExceptionsTests`.
>
> **Details (2026-09-25, beta.8, schema 0011).** A `ui:CardExpander` **Details** under the two rows, expanded, says
> what the game's files and its store say (`05_DETECTION` §What the files say about themselves): *Runs as* (64-bit
> (x64) · 32-bit (x86) · ARM64 · .NET, any CPU (runs as 64-bit) · …), *File version* and *Product version* (the
> executable's PE resource — for an Unreal title often the engine's), *Store* ("Steam build 20374416", "GOG version
> 1.2.3" — or *Version* when the user typed it), *Engine*, and *Ships with*, one line per capability file: "DLSS:
> nvngx_dlss.dll 3.7.10.0", "XeSS: libxess.dll (no version)". A row the Agent has not read yet says so. The subtitle
> labels the store's version the same way and then drops the bare store name it would repeat. **An executable that
> cannot run as x64** (x86, 32-bit-preferring .NET, ARM) disables the hooking switch with `Hooking_NotX64_Format` under
> it and no re-enable bar — turning it on could only be refused (the Agent refuses `ExecutableNotX64` anyway); a switch
> already on can still be turned off. Tests: `GameDetailViewModelTests.TheDetailsCardSaysWhatTheFilesSayAndAnX86SwitchCannotBeTurnedOn`,
> `FormatsTests`, and the page renders in `PagesLoadTests`. **The Details card's *NVIDIA App override* row** (same day)
> is the newest session that read a driver profile, in the same words; no row where none did. Tests:
> `NvidiaOverridesTests`, `GameDetailViewModelTests.TheDetailsCardNamesTheNvidiaAppsOverridesFromTheNewestSessionThatReadThem`.
- Tabs (WPF `TabControl`, Fluent-styled):
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. Multi-select → "Compare". Tier-2 rows render `—` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why.
2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
3. **Distribution** — FPS histogram + percentile curve of selected session(s).
4. **Trend** — metric-over-date line (selector: Native avg / Displayed avg / 1% Low / 0.1% Low / max GPU temp), vertical **hardware-change markers** with tooltip "GPU driver 572.16 → 576.02" (FR-6.3).
> **The display mode, beta.10 (FR-7.4, `03_METRICS` §Display mode).** The **Last session measured** row adds how that
> session was shown — the mode that lasted longest with its share and the window's size (`Display: Borderless 92% ·
> 2560×1440`); the **Sessions** tab has a *Display* column for every session, Tier 2 included (the mode shown longest,
> with a tooltip carrying every share, the changes, the window on its monitor, the back buffer and the witness), `N/A`
> for a session recorded before; the **Trend** has three more metrics — *Exclusive fullscreen share %*, *Borderless
> share %*, *Windowed share %* — over every session whatever its tier, never left out as a mid-session change (a mode
> switch resizes the swap chain, and the share is what that switch was), with no exclusive or borderless point for a
> session that had any time nothing could split (`Services.DisplayText`, `Charts.TrendSeriesBuilder.DisplayShare`).
5. **Sensors** — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series.
6. **Latency** *(Tier 1 + Reflex only)* — PC latency timeline, avg/p95.
@@ -193,9 +287,36 @@ All screens are `Page`s registered with the navigation page provider and navigat
> per-present `vram_proc` (a held 1 Hz sample) and the adapter-wide `vram_adapter` sensor as two
> differently-labelled series. **Latency**: the `latency_us` blob with the stored avg / p95 lines, shown only
> when Reflex reported (`reflex_active`); otherwise the tab says so.
>
> **Trend, corrected 2026-09-25 (beta.8, owner item 6: "does Trend really work?").** It did not, on first open: the
> view model started loading before the page existed, and a load that finished first raised `TrendPresented` to nobody
> — the tab was blank until something reloaded it. The page now draws what the view model holds when it is made
> (`PagesLoadTests.TheTrendIsDrawnWhenThePageIsMadeOnADateAxisThatKeepsItsLabel`). Also: the date axis is created
> BEFORE the theme and the label (`DateTimeTicksBottom` replaces the bottom axis, and made afterwards it dropped both);
> **Average is two metrics** — *Presented FPS* on sessions that counted no generated frame (never on one that did: its
> presented rate includes them, the single inflated number rule 6 forbids) and *Native FPS* where frame generation was
> measured — and the trend opens on Native when the newest measured session counted generated frames; the machine
> metrics count **Tier-2 sessions too** (a game never hooked had no trend); a point that describes part of its session —
> settings changed, or a steady state, for Native and Displayed as well as the factor — is drawn **hollow** and the
> note says so; hardware changes on one day are **one** marker; the metric list is built in the language the page opens
> in; the empty text names the metric.
>
> **FPS with two decimals (same day, owner item 7).** Settings ▸ Window: *Show FPS with two decimals*
> (`ui.fps_decimals`, off by default) — every FPS figure through `Formats.FpsNumber`: "62.40" when on, "62" when off,
> rounded half away from zero both ways (it rounded half to even). `Services.FpsDecimals` holds it for the process
> like `LoggingLevel`: read at start, moved at once by the toggle, shown by a page the next time it formats.
>
> **Rule 6, the places that dropped the share (same day).** A steady-state factor is never shown without its share:
> the readout line ("58 → 116 FPS (×2.0 FG · 75%)"), which the Average card and Compare use, and the Sessions grid's
> FG× column ("×2.0 · 75%"). The header's "Lifetime average" was the last measured session's readout and says so now.
>
> **Compare (same day).** The best cell is in the accent colour — a local `Foreground` on the cell outranked the
> trigger, so it was only ever bold — and "best" is the best as shown (62.4 and 62.3 both read 62, both best); the load
> rows rank nothing; the percentile axis is 0–100 again (`AutoScale` ran after `SetLimitsX` and undid it); exported
> PNGs have an opaque background (`ChartTheme.SavePng`: the window's colour under the transparent figure).
### Session summary (secondary `FluentWindow`, also the post-session toast target)
Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration), TriState chips, API/PresentMode/upscaler line, crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons.
Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration, **Display** — beta.10: the mode shown longest with its share and the window's size, both tiers), TriState chips, API/PresentMode/upscaler line, **the display line** (beta.10: every mode's share, the changes, the window on its monitor at its refresh rate, the back buffer and swap effect, and what the facts rested on — "the swap chain said whether it was exclusive" or "from the window alone: exclusive fullscreen cannot be told from borderless"; absent for a session recorded before), crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons.
> **Built 2026-09-14 (P3 PR-6).** `Windows/SessionSummaryWindow` (a secondary `FluentWindow` with its own
> `ContentDialogHost`), opened from a Sessions-tab row (double-click or Open) and from the Dashboard's recent
@@ -212,6 +333,41 @@ Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutte
> has no per-frame source yet), the segment ribbon as alternating spans when there is more than one segment,
> and GPU temperature / load on the right axis behind the sensor toggle; `DistributionChart` draws the FPS
> histogram and the percentile curve (`Domain.Metrics.Percentile`, so the two lows are two points on it).
>
> **Honest charts, 2026-09-25 (beta.8, owner item 8: "fix the charts that are not reasonable").** Measured first on the
> owner's own Onimusha demo capture (DLSS FG ×3, read from a copy of the ledger): the title submits each generated frame
> half a millisecond after its application frame, so the "native" series — each application frame's interval to the
> present before it — was a generated frame's half millisecond, and the stored median read 2,073 FPS on a 60 FPS game.
> What changed, each with a test (`SessionSeriesLoaderTests`, `ChartMathTests`, `PagesLoadTests`):
> - **One stream.** `SessionSeriesLoader` charts the swapchain the statistics are over (`SegmentBuilder.DominantStream`,
> identified first, then the most presents) — the stored intervals are per swapchain, and two streams interleaved on
> one axis drew neither — with that stream's segments; the CSV export is the same stream (its header says so).
> - **Application frame to application frame.** The default series is each application frame's time from the previous
> application frame, the generated presents between them adding their intervals to it; a gap breaks the chain. It is
> labelled *Application frames* where frame generation was counted and *Presents* where it was not — never "Native"
> alone. A session whose presents were all generated (the `no_evaluations` refusal) charts every present and says so.
> - **The every-present line** (FR-5.4's toggle) leaves out the presents after a gap, which were drawn as 0 ms frames,
> and a note says what it is not: presents are timed at submission, and a burst of generated frames is not the
> display's cadence.
> - **Segments are labelled** with their settings (upscaler, render → output, frame generation) where the segment is
> wide enough; the label was computed for every segment and drawn for none.
> - **The sensor overlay is in step.** Schema 0013's `frame_blobs.first_present_ms` says where the first present sits on
> the sensors' clock; the overlay was drawn tens of seconds early (the launch and the loading screen). A session
> recorded before keeps the overlay off rather than drawn out of step; gaps are still closed up on the frame axis, and
> the note says how many when the overlay is on.
> - **Distribution.** The histogram is binned over the 0.5th–99.5th percentile, not min–max (one 0.3 ms non-frame set the
> axis to thousands of FPS), with the frames outside counted in a note, and its bars sit on their bins' centres (they
> sat half a bin left: ScottPlot's bins are lower edges). The percentile curve is drawn only where ten frames lie
> beyond a percentile on each side — FR-4.8's rule, generalised — so its 1% and 0.1% lows are marked exactly where
> the stat cards publish them, and the single shortest interval no longer sets the axis; the 0–100 axis holds.
> - **Sensors** (the tab and a new section of the summary window): power on a watt axis at the right, the second
> plot is *Memory* (the game's VRAM, the adapter's, the system's RAM), a per-present VRAM of 0 is a present the sample
> did not reach and is left out, the time axis says where its zero is, and every line has its own colour in both
> themes (the light theme drew power and CPU temperature in one gold). **A session that was not hooked charts its
> sensors** — kept since 2026-09-22, shown nowhere until now.
> - **The game page follows the Agent while it is shown**: a `SessionCompleted` for this game reloads it
> (`GameDetailViewModel.Attach` / `Detach` on the page's Loaded / Unloaded; the link is a singleton and must not hold the
> page). Its sessions, trend and header were the ones it opened with.
> **FR-5.3:** `Charts/Decimator` — every bucket's min and max in order, ≤ 4000 points per series per draw, a
> 500k-point series keeps its spike and its dip (`DecimatorTests`). Zoom and pan are ScottPlot's.
> **FR-9:** `SessionExporter` — the CSV with `03_METRICS` §Export schema's column line verbatim and the `#`
@@ -220,6 +376,32 @@ Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutte
> aggregates with N/A omitted, segments, the annotation); PNG through `Plot.SavePng`. Tags (comma-separated,
> de-duplicated) and notes save to the annotation row. **FR-3.8** is an in-app notice on `SessionCompleted`
> (saved / discarded); the tray toast with "View" arrives with the tray (PR-8).
>
> **The loaded libraries (2026-09-25, beta.8).** Under the hardware line, a Tier-1 session says what it had loaded —
> `sessions.runtime_modules`, written since P2 and shown nowhere until then — sorted, one line: *"Loaded:
> nvngx_dlss.dll 310.2.1.0 (the game ships 3.7.10.0: another copy was loaded, for example by the driver or the NVIDIA
> App) · sl.interposer.dll 2,8,0,0"*. The comparison is with the game's own copy (`games.library_versions`) as the
> same four numbers (`Formats.SameVersion`: Streamline's `2,8,0,0` string equals `2.8.0.0`); it names a difference and
> never who made it. Older rows show their list the day this ships; a Tier-2 row has none and no line.
>
> **The NVIDIA driver's side (2026-09-25, beta.8).** Two more lines where they have something to say
> (`Services.NvidiaOverrides`): the driver profile the game ran under and what it overrides — *"NVIDIA profile “Clair
> Obscur: Expedition 33”: DLSS override (preset K, Quality) · Frame Generation override (×4, latest preset)"*, or "no
> DLSS or frame generation override", or the global profile's when none names the game — and what the driver
> reported applying in the game's process from its override bits (*"NVIDIA driver, for this game's process: DLSS DLL
> chosen by the driver · preset K · Quality"*). Smooth Motion is labelled a setting community tools document, not
> NVIDIA. Neither line is a measurement (`03_METRICS` §Upscaling); a machine without an NVIDIA driver shows neither.
>
> **How it ended, and why (2026-09-25, beta.8, owner item 5).** Under the header line, *"How it ended: …"*
> (`Formats.ExitText`): a crash names its exception ("crashed (0xC0000005 access violation)", "0xC0000006 in-page I/O
> error: a disk or drive failed while the game read its files"), End task's exit code is an ordinary end said as
> what it is, and the event log's witness is named as such. The Tier-2 sentence has words for **every**
> `SessionEndReason` (`Formats.EndReasonText`, an enum-walk test keeps it so) and for every refusal no anti-cheat
> family names (`Formats.GuardSentence`: "The anti-cheat guard did not hook this game: the game is 32-bit…") — the
> safety notice and the enable-time refusal use the same words instead of "<signal> was detected in this game"; a
> launch that could not start says Windows' reason. The game page's missing-executable bar says whether the **drive**
> is not connected (FrameLedger finds the game again when it is) or the file is gone from its path, and so does the
> notice when enabling hooking meets an unreadable executable. Tests: `ReasonTextTests`, `Tier2ReasonTests`.
### Compare
Session picker (2–5, cross-game allowed) → overlaid percentile curves + stat table with best-value highlighting; FG columns always show Native and Displayed separately. Export PNG.
@@ -235,6 +417,9 @@ Session picker (2–5, cross-game allowed) → overlaid percentile curves + stat
> separate rows (never one column), Median, the lows, stutter time %, max GPU °C, duration — with the best
> value of each row bold and accent-coloured (higher wins for FPS, lower for temperature and stutter; N/A is
> never best), and a Tier-2 session's cells at N/A. Export PNG through `Plot.SavePng`.
>
> **beta.10:** three rows after Duration — *Display mode* (every share), *Window* and *Monitor* (with its refresh
> rate) — facts, not scores: no mode is better than another, so none is ever marked best, and every tier has them.
### Logs
Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:AutoSuggestBox`), pause-scroll; buttons: Open logs folder, Export bug bundle (routes to 10_LOGGING flow).
@@ -256,6 +441,17 @@ Sections per FR-10 using the WPF UI settings idiom: `ui:CardControl`/`ui:CardExp
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", background capture toggle. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
> **The admin mode, beta.10 (owner decision D34; `01_ARCHITECTURE` ADR-9).** The Agent section has a switch, *Run the agent
> as administrator* (`capture.run_elevated`, off by default). Turning it on opens a `ContentDialog`
> (`Services.AgentAdminPrompt`, text `FrameLedger.Shared`'s `Safety_AdminMode_*`, version `agent-admin-dialog/1` in its
> corner) whose primary button is enabled only by ticking "I understand…" and whose default button keeps standard rights;
> declined, nothing is written. Either way the row is written and the Agent restarts — asked to stop over the pipe, its
> instance lock waited out, the connection's next round starting it the new way — **except under a running session**,
> which the restart would end: then the snackbar says the change applies at the Agent's next start. The elevation line
> says why a standard user's Agent is one when Windows was asked (`HelloAck.ElevationOutcome`: declined, answered by
> another account, could not start), and while the prompt waits the status pill reads *Waiting for administrator
> permission* (`AgentConnectionState.Elevating`).
> **Built 2026-09-14 (P3 PR-8a), with three rows deferred to PR-8b and one to PR-9.** `SettingsViewModel` over
> `Application.Settings.RegisteredSettings` (the registry of `06_DATA_MODEL` §Settings registry — every write is
> one `settings` row, and a key the Agent reads gets the 4 s "Applied. The capture agent reads it at the next
@@ -293,6 +489,18 @@ Agent section: elevation state with a plain explanation of what elevation *optio
> enforces on its own after every consent change and every sweep — the button is the repair tool, `12_BUILD`
> §The Vulkan layer is not registered at install time); Repair appears
> when the task's action names another path (a moved install). "Minimize to tray on close" is honoured.
>
> **2026-09-25 (beta.8):** Capture gained *Hide hooking on anti-cheat games* (`ui.hide_anticheat_hooking`, on by
> default) between the kill switch and the Vulkan layer row — §Games says what it hides; the game's page reads it at
> each load. It hides a control that could only be refused, never the finding.
>
> **2026-09-26 (beta.9, D33):** Capture gained *Allow hooking in games with user-mode anti-cheat that were measured
> before* (`hooking.usermode_ac_exceptions`, off by default), below the hide switch, and under it the **User-mode
> exceptions** list — the games the Agent found eligible (**Make exception…**), held back only by the session count,
> or carrying an exception (**Withdraw**), each with its finding, its successful hooked sessions and its state; with
> the option off only kept exceptions are listed, *suspended*. *Checking…* shows until the Agent has answered about
> every blocked game, and **Refresh** re-reads the list (the Agent's sweep runs every 15 s). The option is an
> Agent-read key and takes effect at the next session start and command.
### First-run flow
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept.
+4 -1
View File
@@ -6,7 +6,7 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
> AND `FrameLedger.Shared.Strings.Culture`. The second was missing: the safety family fell back to the thread's
> `CurrentUICulture`, and a culture set inside the App's async start flows with that async context, not to the
> dispatcher's later operations — so on an English Windows a Vietnamese UI showed the consent dialog, the refusal
> notices and the guard-bypass card in English. A resource accessor that depends on which thread asks is the defect;
> notices in English (and, for one day, a guard-override card). A resource accessor that depends on which thread asks is the defect;
> `StringsTests.ApplyingTheUiLanguageSetsTheSafetyFamilyToo` holds it with the thread deliberately left English.
## Mechanics
@@ -62,6 +62,9 @@ Consent, refusal, and safety-unhook text (FR-2.1, `19_SAFETY`) is **reviewed lik
- No machine-drafted `ja` in this category — a mistranslated ban warning is a real harm. These keys are marked `<comment>safety: human review required</comment>` and ~~the `ja` build fails the resx audit until a human reviewer signs off; until then the `en` string is shown as fallback rather than an unreviewed translation~~ **as built (2026-09-13): the audit is red on a `Safety_*` key in `ja` that carries neither `safety: human review required` nor `safety: reviewed by <name>`, and red on one marked review-required whose value is anything but the `en` string verbatim** — the key-set rule forbids leaving it out, so "shown as `en` until signed" is true by construction (the value IS the English), not by a runtime fallback. Signing = replacing the comment with `safety: reviewed by <name>` beside the reviewed text.
- Never soften the wording per locale. "May result in a permanent ban of your account" must survive translation with the same force in all three languages.
- Key prefix `Safety_*` so they are easy to audit as a group.
- **`Safety_Exception_*` (2026-09-26, D33)** is the user-mode exception's disclosure: the same rules — `ja` ships the
English verbatim marked for review — and its own version, `AntiCheatExceptionDisclosure.Version`, bumped when any of
those strings changes meaning, exactly as `SafetyDisclosure.Version` is for `Safety_Consent_*`.
> **What is in scope, stated 2026-08-06 because a binary now exists that is not.** These rules
> govern the **shipped** application's user-visible strings — what `12_BUILD` §Publish & package
+15 -3
View File
@@ -36,6 +36,11 @@ Binaries are not code-signed (project policy). Consequences and mitigations, doc
SemVer `MAJOR.MINOR.PATCH`. Tag `vX.Y.Z` triggers the release workflow (13_CI_CD). `MAJOR` bumps for DB schema or IPC protocol breaks; migrations must cover every released `MAJOR-1` version.
> **Under `0.x` this rule is not applied, and every pre-release says so by shipping one anyway** (SemVer §4: a major version
> zero is initial development). Schemas 0008–0015 and the shared-memory layout 4 (2026-09-27, beta.10) each shipped in a
> `0.1.0-beta.N`. What protects a user is not the number: the ledger migrates in place (`06_DATA_MODEL` §Migrations), and a
> layout mismatch is refused at attach with "restart the game" (`07_IPC` §Protocol rules). The rule applies from `1.0.0`.
## Built 2026-09-14 (P4 PR-5) — what exists, and where it deviates from the above
`src/FrameLedger.App/Update/`. Velopack 1.2.0 (`Directory.Packages.props`, pinned since P0, referenced since
@@ -58,12 +63,19 @@ flow, and the tests run the flow over a fake client because nothing here may tou
- **FR-12 is the shape of the flow, not a check at the end.** A downloaded package is `Ready` only while the Agent
reports no session (its `StatusAck` at connect, then `SessionStarted` / `SessionCompleted` on the pipe);
otherwise it is `Deferred`, the button is disabled and the body says why, and it becomes `Ready` when the last
session ends. The apply is refused again inside if a session started meanwhile. A recording-only (Tier 2)
session ends. The apply is refused again inside if a session started meanwhile. ~~A recording-only (Tier 2)
session that began before the App connected is covered by the status; one that begins afterwards raises no
`SessionStarted` (that event is the ring's) and is not — a known gap, recorded rather than hidden: the Overlay
is not on disk under such a session, so the rule's reason does not apply to it.
is not on disk under such a session, so the rule's reason does not apply to it.~~ **Closed 2026-09-23:** a held
(Tier 2) session raises its own `SessionStarted`, so it defers an update like any other; and the status read at
connect SEEDS the running set rather than being OR-ed with it forever — before, a session running when the App
connected held every download at `Deferred` until the next reconnect, hours after it ended.
- **Apply:** `Shutdown` to the Agent over the pipe, the connection's relaunch held (`IAgentLink.SetLaunchHold`),
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so),
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so) —
**and since beta.10 the data folder's instance lock watched until it is let go, within the same 10 s**: an Agent run as
administrator (the admin mode) holds the install directory's files exactly as long as its process lives, and one that
holds the folder without answering this App (still starting, another version) is never updated under — the apply is
refused with `Update_AgentStillRunning` instead,
then `WaitExitThenApplyUpdates(asset, silent: false, restart: true)` and the host ends. The restarted App
starts the Agent beside itself as always, and when Velopack reports the restart (`OnRestarted`) the host reads
the logon task: `Stale` (the action path moved) runs `--install-task`, this user's own task, and says so in the
+1 -1
View File
@@ -88,7 +88,7 @@ Launch profiles:
Native debugging notes: use **`hook-harness`, never a real game**, for step-through debugging — a breakpoint inside a present hook of a real game freezes it in ways anti-cheat and drivers both dislike. Enable the Vulkan validation layers when touching `FrameLedger.VkLayer`. Application Verifier + PageHeap on the harness catches ring-buffer bugs early.
Agent flags: `--serve`, `--console`, `--write-crash-dump <file>` (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — `10_LOGGING` §Crash handling), ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
Agent flags: `--serve` (since beta.10 with at most one of `--for-user <SID>` — the account an Agent started as administrator must be, else it exits 11 — or `--elevation declined|other-account|failed` — its starter asked Windows and got this; both from the admin mode, `01_ARCHITECTURE` ADR-9), `--console`, `--write-crash-dump <file>` (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — `10_LOGGING` §Crash handling), ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
> **Built 2026-09-10 (P2 PR-F): `--serve` and `--console`; the other five answer "not implemented in P2"
> with exit 2** rather than being silently accepted (`--diag` is the App's anyway, `10_LOGGING`). The console
+3 -3
View File
@@ -8,13 +8,13 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. ~~Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).~~ **Landed long since** — `ctest` runs 31 native suites on every gate (`fl_guard` alone is ~100 s); the sentence was left in the future tense until 2026-09-21.
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set.
- **The user's bypass (2026-09-21) has its own proofs, and they are about what it must NOT do.** Native (`[bypass]` in `guard_test.cpp`): a blocklisted target is refused by the plain entry and injected by the acknowledged one with the same family and signal and a verdict that is not `kAllow`; a clean target is a plain allow; a foreign or absent payload is still refused and nothing is loaded; `IsGuardJudgement` is exactly its list. Managed: `GuardMirrorTests` holds the C# list against the native one for every reason; `HookedCaptureGateTests` proves the kill switch, an un-enabled game and a missing consent still refuse with the guard never asked, that an acknowledged request never takes the plain entry (and the reverse), and that a guard which does not know the bypass is the hard gate (the port's default implementation); `HookRequestFromConsentTests` that the fifth input needs a stored record naming its disclosure and the same executable; `GuardSupervisorTests` that a judgement is counted, kept and overruled while a fact still unhooks; `SqliteGuardBypassStoreTests` that it cannot exist for a game nobody added or another binary, touches neither block nor consent, and ends with consent or the executable; `AgentCommandHandlerTests` that the pipe re-checks everything; `GameDetailViewModelTests` that a declined disclosure sends nothing and the switch shows the row.
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set. **Since 2026-09-25** the fixture is generated from the shipped seed (`rules_budget_test.cpp`: every entry's every value matches its own family in its own group, which also catches a row an earlier prefix shadows), and Ricochet's fixture asserts its data; VAC's still asserts that no family entry fakes it.
- **A finding turns the game's hooking off (2026-09-22), and the proofs are about WHICH findings.** `AntiCheatVerdictTests` pins `IsFindingAboutTheGame` per reason (in the game: yes; machine-wide driver or service, heuristics, failed scans, the latch: no) and that a finding without a family is not one; `CaptureSessionTests` that a start-time `BlockedModule` writes the block, keeps the consent stamp and says `HookingTurnedOff`, that a `BlockedDriver` refuses the session and leaves the row alone, and that the 30 s re-scan's finding writes the same block; `RecordedSessionEventsTests` and `SafetyNoticesTests` that the flag travels to the notice. The override of 2026-09-21 had its own proofs for one day; they went with it, and `NoSecondMatcherTests` counts the port's four methods again.
- **Fail-closed proofs:** malformed `detection-rules.json`, missing `anticheat` block, unreadable target process, `EnumProcessModulesEx` failure, partial module list → **all must refuse injection**, never allow. Each is a named test.
- **Measured error paths that must be named tests** (`spike-notes.md` §1): `ERROR_PARTIAL_COPY (299)` from a suspended target, `ERROR_ACCESS_DENIED (5)` from a protected one, a driver-list parse whose paths are not native paths, and a service query returning `ACCESS_DENIED` — the last of which **cannot be produced on real services by a standard user**, so it exists only as a fake. Every one means REFUSE.
- Mid-session detection: simulated late-loading anti-cheat module → `unhookRequested` set, hooks disabled within one frame, session finalized `unhooked_safety`. Cover the **driver** scan too, not only modules: a machine-wide driver can start after injection.
- **Absence-of-override test:** no code path may reach the injection primitive without a passing guard result. The mechanism previously described here — a `sealed` token type "only the guard can produce" — does not work and was disproved by compiling (`20_OPEN_QUESTIONS` §S8: C# accessibility flows inward, `CS0122`). The replacement is structural: the guard **owns the chokepoint** and calls the primitive itself, the primitive has internal linkage in the guard's own translation unit so no other TU has a symbol to call, and a build-time check asserts that nothing else references it. A token that escapes can be ignored; a symbol that does not exist cannot.
- Static pre-scan: a game directory containing `EasyAntiCheat/` renders `hook_enabled` un-settable; API-level attempt to set it is rejected — including via `SetWatchlist`, which no longer carries hooking state at all (`07_IPC` §The pipe is not a trust boundary). ~~**The toggle half needs persistence and is not built yet**~~ **built in P2/P3**: `SqliteGameConsentStore.RecordGuardBlockAsync` forces `hook_enabled = 0`, `AgentCommandHandler.SetHookEnabledAsync` re-runs the pre-scan and answers `Refused`, and `GameDetailViewModel` disables the toggle on a blocked row (corrected 2026-09-21; the one way past it is `19_SAFETY` §The user's bypass); the scan itself is ctest `fl_prescan`, whose matrix is mostly fail-closed: a listing that FAILED, one that was TRUNCATED, a directory that could not be established, unusable rules, and a missing evidence source must each be *undetermined*, never clean. Two cases exist only to stop the rest passing vacuously — a genuinely clean directory must be **allowed**, and a name matching the wrong group (a directory named like a `files` entry) must **not** fire. One case removes a family from the rules and asserts the hit disappears, which is what proves there is a single matcher rather than a second one that happens to agree.
- Static pre-scan: a game directory containing `EasyAntiCheat/` renders `hook_enabled` un-settable; API-level attempt to set it is rejected — including via `SetWatchlist`, which no longer carries hooking state at all (`07_IPC` §The pipe is not a trust boundary). ~~**The toggle half needs persistence and is not built yet**~~ **built in P2/P3**: `SqliteGameConsentStore.RecordGuardBlockAsync` forces `hook_enabled = 0`, `AgentCommandHandler.SetHookEnabledAsync` re-runs the pre-scan and answers `Refused`, and `GameDetailViewModel` disables the toggle on a blocked row (corrected 2026-09-21; since 2026-09-22 a finding at a session's start or at the re-scan writes the same block — `CaptureSessionTests`); the scan itself is ctest `fl_prescan`, whose matrix is mostly fail-closed: a listing that FAILED, one that was TRUNCATED, a directory that could not be established, unusable rules, and a missing evidence source must each be *undetermined*, never clean. Two cases exist only to stop the rest passing vacuously — a genuinely clean directory must be **allowed**, and a name matching the wrong group (a directory named like a `files` entry) must **not** fire. One case removes a family from the rules and asserts the hit disappears, which is what proves there is a single matcher rather than a second one that happens to agree.
## Native unit tests (Catch2)
+1 -1
View File
@@ -298,7 +298,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
> `logs\overlay-<pid>-*.log` (init / Agent request / stop), `opengl32!wglSwapBuffers` with the harness's
> `--opengl` mode. **D3D9 is not built and will not be**: `20_OPEN_QUESTIONS` §Scope decisions rules it out
> of v1 (the Overlay is x64-only and those titles are 32-bit); listing it here was the roadmap's, not the
> scope's. What P1 still leaves ⏳ in `17_HOOK_ENGINE` §Hook inventory: `SetFullscreenState`,
> scope's. What P1 still leaves ⏳ in `17_HOOK_ENGINE` §Hook inventory: ~~`SetFullscreenState`~~ (polled instead, 2026-09-27),
> `SetColorSpace1`, `CreateSwapChain*`, `ID3D12Device5::CreateStateObject`, the Vulkan RT / pipeline entries,
> §Pipeline and §Memory/latency — feature rows, each with its own measurement question, not P1's core. P2
> (the Agent, the recorder, SQLite) is next per this file.
+13 -3
View File
@@ -57,6 +57,16 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
> them and the loader does not list them. Body under `FL_HOOK_GUARD`, no allocation, no lock, no
> logging (rule 5). Exercised by `hook-harness --load-after-ms N PATH` (up to four), against the real
> Overlay in a real target, both jobs.
>
> **D33 (2026-09-26): one family may be tolerated.** Before `InstallLoaderHook`, `InitThread` reads
> `Local\FrameLedger.Tolerate.<pid>` once (`fl_tolerance.h`; absent = nothing tolerated, the ordinary case),
> resolves each name against its OWN compiled floor, honours only a family whose whole footprint there is
> user-mode (`fl::guard::FamilyIsUserModeOnly`) and keeps a 64-bit mask over the floor's module families. The
> detour's only change is one bit test before (b): a tolerated family's module loading late is not an early stop.
> **Overhead:** one relaxed-acquire `uint64` load, a shift and a compare, on the floor-match branch alone — a branch
> that fires approximately never — and nothing on the present path; the tolerance is read on the init thread, not in
> a hook body (and logged there as `TOLERANCE`). ctest `fl_guard` `[D33]` loads a decoy `NEP2.dll` 2.5 s in: the
> Overlay keeps recording when the mapping names NetEase Yidun, and stops when it names Easy Anti-Cheat.
4. Install present hooks for what exists (below).
5. Install feature hooks (upscaler / RT / PSO) lazily — the first time their module appears.
6. Publish `status = ready` in the handshake block.
@@ -133,7 +143,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
> Reset is load-bearing — and no vendor symbol is resolved by name, so `FL_HOOK_INVENTORY`
> and `hookinventory-check` do not cover them at all.
> **Every other row below is unwritten**, including
> `SetFullscreenState`, `SetColorSpace1`, `CreateSwapChain*`, ~~`wglSwapBuffers`~~ (built 2026-09-06, #141, its row below),
> ~~`SetFullscreenState`~~ (polled instead since 2026-09-27, its row below), `SetColorSpace1`, `CreateSwapChain*`, ~~`wglSwapBuffers`~~ (built 2026-09-06, #141, its row below),
> `ID3D12Device5::CreateStateObject`, §Pipeline and §Memory/latency.
>
> Stated here because the distinction is invisible from the table. What a writer may then
@@ -169,7 +179,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|---|---|
| ✅ `IDXGISwapChain::Present`, `Present1` | Frame boundary, QPC, sync interval, present flags. **`DXGI_PRESENT_TEST` calls are dropped without a record** — the occlusion probe submits nothing, and a minimised game emits a stream of them (`07_IPC` §Protocol rules). **Since 2026-09-05 the hook also reads `IDXGISwapChain::GetLastPresentCount` on the chain it just saw** (rule 4: the same COM object `FindOrAdd` already calls `GetDesc` on, no new hook) and publishes `dxgiPresentSamples` / `dxgiPresentsUnseen` — DXGI's count of presents on that chain that this hook never saw, the in-process half of `20_OPEN_QUESTIONS` §H5 Leg 1. One virtual call per hooked present, costed by `hook-harness --probe-frames`. **And per record since the same night: `dxgiUnseen` @52 under `FL_MEASURED_DXGI_PRESENTS`**, so the consumer's window counts `Displayed = hooked + unseen` per bucket (`03_METRICS` §Displayed may be DXGI-COUNTED) — measured 2.90 / 2.95 on DL:TB at Streamline 2.8.0, 0 on 2.7.3 and 2.10.3. **And since 2026-09-06 (P1 item 2) the same read, at the FIRST hooked present on the first hooked chain, is published once as `FlWriterState.dxgiPresentsBeforeHook` @60** — DXGI's count of presents that ran before the hook was in, launch mode's cost meter (`20_OPEN_QUESTIONS` §S1); 0xFFFFFFFF until a present is seen, set before the present hooks go in. **Corrected 2026-09-14 (`fl_dxgi_count.h`, ctest `fl_dxgi_count`):** a reading that went *backwards* — a chain released and re-created at the same address inherits the slot's old count — used to wrap `now − previous` to ~4e9, saturate the record byte at 255 (the `DxgiSaturated` refusal) and add the wrap to the session total: the owner's ledger held `dxgi_unseen_total = 4294967243`. A regression is now a reset (no delta claimed, nothing added, the slot re-armed) and the total saturates at `UINT32_MAX` rather than wrapping. Cost: one compare on the same virtual call; measured per `14_TESTING` §Hook overhead in the PR |
| ✅ `IDXGISwapChain::ResizeBuffers` · ⏳ `ResizeTarget` | Output resolution changes mid-session. `ResizeBuffers` re-reads the swapchain description *after* the original returns; `ResizeTarget` is not hooked |
| ⏳ `IDXGISwapChain::SetFullscreenState` | Fullscreen ↔ borderless transitions |
| ~~⏳ `IDXGISwapChain::SetFullscreenState`~~ **not hooked — polled (2026-09-27, beta.10)** | ~~Fullscreen ↔ borderless transitions~~ **Region 4, `FlDisplayState` (`07_IPC`, layout 4).** DXGI leaves exclusive fullscreen by itself — focus lost, Alt+Enter inside its own window hook — without the title calling this method, so a hook would miss exactly the transitions a mode share must count. Instead the present hook asks, **at most every 500 ms per chain**, two getters on the chain the title passed: `GetFullscreenState(&fs, nullptr)` (no `IDXGIOutput` taken) and `GetDesc` (the window, the back buffer, the swap effect). Rule 4: the same object `FindOrAdd` already calls `GetDesc` on and the counter reads — no new hook, no read beyond it; the window's geometry and the classification are the Agent's, out of process. `GetDesc` again also refreshes the size every record carries, which closes `IDXGISwapChain3::ResizeBuffers1` (unhooked: a D3D12 title resizing through it kept its old size until now). Published through a seqlock the writer never waits on (a taken lock skips the sample). OpenGL publishes the window and client size `ReadGlSize` already holds, with no exclusive bits. Cost per `14_TESTING` §Hook overhead in the PR |
| ⏳ `IDXGISwapChain3::SetColorSpace1` | HDR output detection. **`IDXGISwapChain3`, not 4** — 4 adds only `SetHDRMetaData` (`20_OPEN_QUESTIONS` §H9 — *answered and removed with H1/H3/H4 in the P0 spike (`6b1fa83`); this row used to say `IDXGISwapChain4`, and the corrected interface here IS the answer, so the citation points at history rather than at a live entry*). Unbuilt, which is why `colorSpace` reads `NOT_REPORTED` and `FL_MEASURED_HDR` stays clear. **When it is built, the writer must initialise `colorSpace = FL_COLOR_SPACE_SDR` at swapchain identification** — an SDR title never calls `SetColorSpace1`, so "hook live, no call" would otherwise sit at `NOT_REPORTED` forever and HDR's definite `No` would be unreachable. DXGI documents G22/Rec.709 as the default, which makes SDR a *measured* default rather than an affirmative negative |
| ⏳ `IDXGIFactory::CreateSwapChain*` | Capture swapchain desc (format, buffer count, swap effect, flags) at creation. Unbuilt — the swapchain description is currently read on demand in the present hook via `GetDesc` |
| ✅ `wglSwapBuffers` (2026-09-06, P1 item 4) | OpenGL titles: one record per `opengl32!wglSwapBuffers`, `api` = OpenGL, the output size from `GetClientRect` on the window the HDC belongs to (first sighting and every 256th present, so a resize is caught without a second hook), **no `FL_MEASURED_PRESENT_ARGS`** — the call has no sync interval and no flags. A MinHook inline patch on the flat export (measured 2026-08-05: a `jmp` thunk into the vendor ICD, relocated like any first instruction), installed at init when `opengl32.dll` is already mapped and lazily on the watchdog otherwise, with the `LoadLibrary` detour waking it for `opengl32.dll`. Exercised by `hook-harness --opengl --hold-presenting N`, which calls **gdi32's `SwapBuffers`** the way a title does — measured to reach the hook (ctest `fl_guard` `[opengl]`, on Microsoft's generic renderer, so it runs on CI too). The one system-module row below carries the inventory asymmetry |
@@ -614,7 +624,7 @@ Every hook body is wrapped:
```
- Any SEH exception inside our code ⇒ increment `faultCount`, record which hook, **return control to the original function** so the game continues.
- 3 faults total ⇒ set `status = self_disabled`, uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
- 3 faults total ⇒ set `status = self_disabled`, ~~uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`)~~ restore each patch's prologue only while its bytes are still our jump (compare-and-restore per patch through `StopObserving`, §Unhooking, §H7 — `MH_ALL_HOOKS` would have removed an overlay chained after us; corrected 2026-09-27), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
- Never `__try` around the call to the original function — only around *our* code, so we never mask a game bug as ours or vice versa.
- The trampoline call to the original is always executed exactly once, on every path, including error paths.
+28 -2
View File
@@ -122,7 +122,10 @@ CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, an
> unelevated by design, so the unprivileged layer's behaviour never depends on privilege) only when the process is
> elevated AND `PawnIo.IsInstalled`; it takes the package sensor (`CPU Package`, `Core (Tctl/Tdie)`) and falls back to the
> hottest core. **Unmeasured on real hardware**: exercised against a fake `ILhmComputer` only; the first elevated run
> with PawnIO is the measurement. `HelloAck.cpuTempAvailable` reports those same two conditions (it was a constant
> with PawnIO is the measurement — **which the user can now choose to make (beta.10, the admin mode: Settings ▸ Capture
> agent ▸ Run the agent as administrator, `01_ARCHITECTURE` ADR-9)**; until beta.10 an elevated Agent existed only when an
> App started as administrator happened to start it, and `PrivilegeFootprintTests` now asserts on the elevated CI runner
> that opening this CPU group enables no privilege. `HelloAck.cpuTempAvailable` reports those same two conditions (it was a constant
> `false`). A tick only the machine answered is still queued, under a placeholder `GpuSample` with
> `TelemetryLayer.None` and no field. The `.partial` sensor chunk carries the three values in bits 12–14 of the
> existing 16-bit presence mask, so an older file reads back with an empty reading.
@@ -161,6 +164,29 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
> **Not in this build, stated so nobody infers it from the table below:** VRAM (`FlNvSample.vram` is
> reserved and its bit is never set — see the Memory row), power, hotspot temperature, per-domain
> utilisation beyond the GPU domain, and anything Reflex (§M8: a hook fact, not a poller field).
>
> **ABI 2 (2026-09-25, beta.8): the driver profile, read-only.** The owner asked whether the NVIDIA App overrides a
> game's DLSS (frame generation, ray reconstruction, the model preset). The NVIDIA App writes those overrides into the
> driver's own settings store (DRS), so `FlNvDriverProfile(exePath, ids, count, out)` reads them there: a DRS session
> is created, the settings loaded, the profile the driver applies to that path found (`NvAPI_DRS_FindApplicationByName`
> — a fully qualified path returns the profile the driver will apply on launch; none named → the current global
> profile), each id read with `NvAPI_DRS_GetSetting` (value, where it comes from, whether someone set it), and the
> session destroyed. **No DRS setter exists in the bridge** — not `SetSetting`, not `SaveSettings`, not
> `RestoreProfileDefault`, not `NvAPI_NGX_SetNGXOverrideState`: the overrides are the user's, and this only reports
> them. A path longer than NVAPI's string is refused, never truncated (a truncated path names another program).
> The ids and their values' meanings are NVIDIA's `NvApiDriverSettings.h` (github.com/NVIDIA/nvapi, MIT), written into
> `Application.Capture.NvidiaDriverSettings` as eighteen constants rather than vendored as a header; Smooth Motion
> (`0xB0D384C0`) is not in NVIDIA's header and is documented by community profile tools only, which every surface
> that shows it says. Managed: `NvapiDriverProfileSource` (`IDriverProfileSource`) — the Agent's recorder reads the
> profile beside every session, both tiers, and stores it in `sessions.driver_profile` (schema 0012). Verified by
> ctest `fl_nvapi_bridge` (argument refusals, DEGRADED before init, the global profile of the test's own executable on
> a GPU machine) and `NvapiBridgeMirrorTests` (`FlNvDriverProfileSize`, ABI 2).
>
> **The ctest could not fail on a GPU machine until the same day.** `fl_nvapi_bridge` was registered with
> `PASS_REGULAR_EXPRESSION` alone, which makes ctest ignore the exit code: the AVAILABLE branch's reference-counting
> check (two references, two releases, then a read expected to work) failed on every machine with an NVIDIA GPU while
> ctest reported Passed, and CI — no driver — never takes that branch. The check is corrected and the registration now
> carries a `FAIL_REGULAR_EXPRESSION` on Catch2's failure lines.
| Purpose | Function |
|---|---|
@@ -282,7 +308,7 @@ on the NVIDIA dev box even though nothing in it may be hooked or declared.
- Poll at 1 Hz on a dedicated Agent thread. Never from the game process, never from the Overlay.
- Any layer that throws or hangs twice is disabled for the session and its fields report `N/A`, rather than being retried in a loop.
- **Read-only, always.** These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile.
- **Read-only, always.** These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile. *(Since beta.8 the same holds for the driver's settings store: the bridge reads DRS profiles and has no entry point that writes, saves or restores one — §L3, ABI 2.)*
## Capability matrix (fill during P0 on real hardware)
+341 -63
View File
@@ -18,7 +18,7 @@ These are permanently out of scope. A PR implementing any of them is rejected re
- Hiding, renaming, or randomizing the DLL, its exports, or its shared-memory object names
- Thread hiding (`NtSetInformationThread`/`ThreadHideFromDebugger`) or debugger-evasion tricks
- Signature-breaking obfuscation/packing of our own binaries
- Any "stealth mode", or documentation explaining how to defeat the guard below. *(This line also read "'bypass' setting" until 2026-09-21. The owner decided that day that one bypass exists — §The user's bypass, under the guard — and what stays on THIS list is everything that would make FrameLedger harder to see: that bypass changes whether we inject, never how.)*
- Any "bypass" setting, "stealth mode", or documentation explaining how to defeat the guard below. *(The first two words left this line on 2026-09-21 and returned on 2026-09-22 — §What a finding does to the game. The one exception the owner has granted since, D33 on 2026-09-26, is not a bypass: the guard still runs every check and decides itself which family is user-mode — §The user-mode exception.)*
- Reading or writing game memory outside the arguments of APIs we hooked
- Kernel drivers of our own
@@ -220,6 +220,35 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> never as *clean*. `20_OPEN_QUESTIONS` §S7 tracks the remaining work.
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, updatable independently of app releases (`05_DETECTION` §Rules updates).
> **Both halves are wired and seeded since 2026-09-25** (owner: "as many and as strict as possible"; rules
> `2026.09.4`). The block below is the history it replaces, kept for the reasoning.
>
> **The store half reads the store's own files, through a seam the guard owns.** `Sources::StoreIdentity` takes the
> install root the guard already derives from the pid (check 4's `ImageDirectory`) and answers from disk: under
> `<library>\steamapps\common\<folder>`, the one `appmanifest_<id>.acf` whose `installdir` is `<folder>` →
> `steam:<id>`; a `goggame-<id>.info` in the root → `gog:<id>`. Nothing is handed in by a caller (§S3 is untouched —
> the ABI still takes a pid and nothing else) and nothing is read from the game's process (rule 4).
>
> **The matrix §S14 asked for:** a listed identity refuses (`BlockedStoreId`, naming the family); an install no store
> names — a loose folder, a GOG-less, manifest-less copy — is **not** refused, because "no store identity" is an
> answer, not an unknown, and refusing it would be the gate that cannot pass; a store layout whose metadata could not
> be read (a manifest that will not open, more than 4096 of them, a listing error) refuses as `PreScanFailed`. With
> nothing listed, nothing is read. Epic has no reader: an Epic install carries no identity to this check.
>
> **What is listed, and why a title list at all:** 30 Steam app ids and 33 executable names across nine families —
> Valve VAC (CS2, Dota 2, TF2, Deadlock and Valve's older VAC titles), Riot Vanguard, Roblox Hyperion, Blizzard's
> online titles ("Blizzard Warden"), Call of Duty (Activision Ricochet), NetEase (Marvel Rivals, NARAKA, FragPunk,
> Once Human), ACE (Delta Force, Arena Breakout: Infinite), HoYoverse and EA (Battlefield 2042/6, EA SPORTS FC 25/26).
> These are the titles whose anti-cheat leaves nothing of the game's own for checks 1, 2 and 4 to find — VAC runs
> inside Steam, Blizzard's scanner is built into the game — or whose kernel driver loads only after the checks run.
> Every app id was checked against its Steam store page; Call of Duty's changed when Activision split CoD HQ, so only
> ids with a live store page are listed. The per-title lists are **floored** like the families: a rules file can
> add a title and cannot take one off. `rules-validate` refuses a name engines and tools share (`Game.exe`,
> `Client-Win64-Shipping.exe`, `hl2.exe`…), an exact rule that names no `.exe`, and duplicates.
>
> **The owner declined the bulk list** (AreWeAntiCheatYet's ~250 Steam ids): community data that keeps listing a game
> after it drops its anti-cheat would turn hooking off for good on a title that no longer needs it.
> ⚠ **◐ The EXECUTABLE half is wired as of 2026-08-05; the STORE-ID half is
> blocked.** `CheckBlockedExecutable` runs inside `EvaluateImpl` between the
> module scan and the pre-scan, and an unresolvable identity refuses with
@@ -250,6 +279,23 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> rules file — and therefore every title on the machine (§S17).
4. **Multiplayer heuristic** — if the pre-launch file scan finds an anti-cheat SDK shipped alongside the game (e.g. EOS anti-cheat binaries, `EasyAntiCheat/` directory) even when not currently loaded → refuse and explain.
> **Any kernel driver in the install tree counts, since 2026-09-25 (owner decision).** A `*.sys` file that no
> `files` entry names is reported as `AntiCheatFile` under the family **"Kernel driver in the game folder"**. Every
> driver this project has found shipped inside a game — `PGameProtectDriver_X64.sys`, `randgrid.sys`,
> `NeacSafe64.sys`, `BlackCat64.sys`, `mhyprot*.sys` — was an anti-cheat's, and naming each one in data first is how
> the next one walks past, as ACE's did in August. The rule is **code, not data** (`fl_prescan.cpp`,
> `kKernelDriverInTreeFamily`): no rules file can remove it or rename its family. A named `files` entry still wins,
> so `randgrid.sys` reads as Activision Ricochet. **The cost the owner accepted:** a game that ships a driver for
> some other purpose (a wheel, a peripheral, an old disc check) has its hooking turned off like any finding, and
> nothing clears it.
>
> **The advisory pre-scan takes the executable and resolves the install root itself, since 2026-09-25.**
> `FlStaticPreScan(gameDirectory)` scanned the directory it was handed, and its one caller (`SetHookEnabled`) handed
> it the executable's own folder — so for an Unreal title, the scan that decides whether hooking may be turned on
> looked at `<root>\<Project>\Binaries\Win64\`, exactly where the Lies of P measurement below says `EasyAntiCheat/`
> is not. The chokepoint always resolved the root. `FlStaticPreScanGame(exePath)` replaces it: the same
> `ResolveInstallRoot`, plus check 3 on the executable's name and the install's store identity.
> **Implemented, and stated narrowly.** `fl_prescan.cpp` walks the target's
> own directory (derived from its pid, never from a caller-supplied path) to
> **depth 3** — raised from 2 on 2026-08-04 (§S22, `spike-notes.md` §13), because a
@@ -311,7 +357,7 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> That needs a real game library, and it is a false-refusal path, so it is
> recorded rather than assumed benign.
Any check failing ⇒ **injection is refused**. The UI shows which check fired and offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing (`04_CAPTURE` §Frame source abstraction).
Any check failing ⇒ **injection is refused**. The UI shows which check fired and ~~offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing (`04_CAPTURE` §Frame source abstraction)~~ **records the session unmeasured — Tier 2: its duration, the machine's sensors and the reason — which needs no injection and no elevation; there is no ETW rung and no Tier 3 since 2026-08-28** (corrected 2026-09-27: this sentence outlived the ladder it described by a month).
### The payload is checked too, and for a long time it was not
@@ -348,54 +394,143 @@ the injection primitive, not a fifth question about the title.
- **Absent** is still `kInjectionFailed`, not `kPayloadNotOurs`. A damaged install
and a misuse of the ABI are different problems and must not share a reason.
> ~~There is no override.~~ **There is one, since 2026-09-21, and it is none of the things this paragraph named**: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below.
> **There is no override.** ~~There is one, since 2026-09-21, and it is none of the things this paragraph named~~ *(one day; withdrawn 2026-09-22)*: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below — and since 2026-09-26 (D33), one narrow, evidence-bound exception for anti-cheat that is user-mode throughout, which lets a named family through while every check still runs (§The user-mode exception).
### The user's bypass — owner decision 2026-09-21
### What a finding does to the game — owner decision 2026-09-22
The owner asked for a mode that skips the guard at the user's own risk, behind a warning the user MUST accept first. This section is that mode's whole specification; CLAUDE.md rule 2 carries the same constraints as a rule.
**The per-game override of 2026-09-21 is withdrawn.** It shipped in `0.1.0-beta.3` and `beta.4`. Its first real use
(D21, below) showed that it could not reach a process an anti-cheat driver protects, and where it could inject it only
exposed the user to the risk its own disclosure described. The owner withdrew it on 2026-09-22: the native entries, the
pipe message, the App's dialog and card, the strings and the five columns of schema 0007 are gone (schema 0008 drops
them). Sessions that ran under it keep `guard-bypass=` in `capture_notes`; nothing else remembers it.
**What it is.** A per-game switch on the game's page, **off by default**, that lets a user overrule the guard's *judgement* for that one game. With it on, the Agent reaches the guard through `FlGuardedInjectAcknowledged` / `FlGuardedInjectWhenReadyAcknowledged` instead of the plain entries. The guard still runs **every** check in the same order. Where the evaluation refuses with a reason `fl::guard::IsGuardJudgement` accepts, the injection proceeds and the verdict is **`AllowedUnderUserBypass` (28)** — `family` and `signal` still name what was found. It is not `Allow`: `Verdict::Allowed()` and `AntiCheatVerdict.IsAllowed` stay false for it, so every caller written before it existed keeps refusing, and `CaptureSession` — the one caller that may proceed — asks `IsAllowedUnderBypass` by name.
**What replaced it is the opposite of an override: a finding turns the game's hooking off.** The pre-scan has done
this since P2 (`RecordGuardBlockAsync`: `hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`).
Every later moment the guard can find something writes the same block — a fourth since 2026-09-25:
**What it overrules: a judgement. What it never overrules: a fact.**
| Moment | Where | What it sees |
|---|---|---|
| hooking is turned on | `AgentCommandHandler.SetHookEnabledAsync` | checks 3 and 4 over the executable and its install root (`PreScanGameAsync`; check 4 over the executable's own folder until 2026-09-25) |
| a session starts | `CaptureSession.SessionAsync`, after the gate | checks 1–4 over the live process, its tree, the drivers, the folder |
| the 30 s re-scan | `CaptureSession.DrainAsync`, on a `SafetyUnhook` | the same, for an anti-cheat that loaded late |
| the Agent's pre-scan of the library | `AntiCheatPreScanSweep`, under `--serve` | checks 3 and 4 over every entry, whether or not its hooking was ever on |
| Overruled (the guard's judgement) | Never overruled |
|---|---|
| `BlockedModule`, `BlockedDriver`, `BlockedService`, `BlockedExecutable`, `BlockedStoreId`, `AntiCheatDirectory`, `AntiCheatFile`, `SuspiciousUnsigned` | `KillSwitchEngaged` (FR-2.4 outranks everything) |
| the scans that could not look, which the guard treats as findings: `ModuleScanFailed`, `ProcessUnreadable`, `ProcessTreeUnavailable`, `DriverScanFailed`, `ServiceQueryFailed`, `PreScanFailed` | `HookNotEnabled`, `ConsentMissing` — the bypass is not a second way to enable or to consent |
| unusable rules: `RulesUnreadable`, `RulesMalformed`, `RulesIncomplete` | `PayloadNotOurs` — no acknowledgement loads a foreign DLL (§S22 stands) |
| the latch a past judgement left on the row: `PreviouslyBlocked`, and the pre-scan's "could not verify" | `TargetIsWow64`, `InjectionFailed`, `LaunchTargetExited`, `LaunchNoPresentationRuntime` |
| | **a Vulkan title the guard refuses**: the layer has its own in-process guard, and this path does not talk past it |
**The Agent's pre-scan of the library — owner decision 2026-09-25 (beta.8).** Until then the first three moments were
the only ones, and each needs the user to have asked for hooking: a game nobody enabled stayed
`hook_prescan_state = 'not_run'`, so the App could not tell an anti-cheat game from any other. The owner asked for the
hooking part of anti-cheat games to be hidden, which needs to know which they are, so the Agent now asks the advisory
question itself (`AntiCheatPreScanHostedService`: at start, every 15 s, and at once after `UpdateRules`):
The list exists twice — `fl::guard::IsGuardJudgement` and `AntiCheatVerdict.IsGuardJudgement` — and `GuardMirrorTests` holds them against each other for every reason through the exported `FlGuardIsJudgement`. `PreviouslyBlocked` is the one deliberate difference: managed-only, because the native guard never produces it.
- **Which entries.** Every library row not removed, once per rules version and executable — the key is its own
(schema 0010: `hook_prescan_rules_version`, `hook_prescan_exe_size_bytes`, `hook_prescan_exe_mtime_ms`), so a rules
update that names a game already in the library, or a game update that adds anti-cheat, is a re-scan. Skipped: a
blocked row (it is never asked again), an executable that cannot be read, an entry whose session is running (that
session's own checks are). *Change executable* clears the key with the state, so the new binary is scanned.
- **What it writes** (`IGameConsentStore.RecordPreScanAsync`): a finding about the game is the block above, the
consent stamp kept; a pass is `'clean'`; a scan that could not answer is `'unverified'`, which leaves the toggle
alone. It never writes over a block and never adds a row — the `UPDATE` itself requires both, so a block written
between the sweep's read and its write still stands.
- **What it tells.** A `HookingTurnedOff` event (`07_IPC`) only when the entry's hooking was on: the one case where
something the user switched on changed. Every other finding changes only the game's page and card.
- **What it is not.** It gates nothing: every session start still runs checks 1–4 against the live process, whatever
the sweep wrote. It opens no process — the scan reads the executable's path, its install folder and the stores'
files. It holds the guard's lock for one walk at a time (`NativeAntiCheatGuard` serialises every native call), so a
session start waits for at most the one walk in flight.
**How it is turned on — a recorded human act, the shape consent has.**
1. The App shows its own disclosure (`GuardBypassPrompt`, text in `FrameLedger.Shared` `Safety_Bypass_*`, reviewed as the safety text it is; `ja` ships the English until a reviewer signs, `09_I18N`). It states what the guard found for THIS game, that anti-cheat treats a loaded DLL as tampering whatever it does, that the account can be flagged, suspended or **permanently banned** without warning or appeal, that FrameLedger does not hide and never will, and — in the owner's words — that **by turning it on the user accepts the entire risk and the developers accept no responsibility or liability** for anything that follows.
2. The primary button is the Danger one and is enabled only while **both** acts are performed: a ticked acknowledgement **and** the typed phrase `BYPASS` (`GuardBypassDisclosure.ConfirmationPhrase`, the same five letters in every language). Enter keeps the guard on.
3. The App writes nothing. It sends `SetGuardBypass` (`07_IPC`); the Agent refuses any disclosure version but its own (`GuardBypassDisclosure.Version`), re-reads the executable, and stamps `games.guard_bypass_at` + `guard_bypass_disclosure_version` (schema 0007) through `IGuardBypassStore` — a port of its own, so nothing that can grant consent can by the same call overrule the guard.
4. It enables nothing. Hooking is still its own switch and its own FR-2.1 dialog; with the bypass recorded, `SetHookEnabled` still runs the pre-scan and **still writes the finding** (`hook_blocked_reason` stays on the row and stays true) and then stamps the consent beside it, answering `prescan: "bypassed"`.
**Which findings** — `AntiCheatVerdict.IsFindingAboutTheGame`: an anti-cheat *named* (family non-empty) in the game's
own process (`BlockedModule`), on its title lists (`BlockedExecutable`, `BlockedStoreId`) or in its folder
(`AntiCheatDirectory`, `AntiCheatFile`). **Not** a machine-wide driver or service (`BlockedDriver`, `BlockedService`):
a driver running for another game says nothing about this one, so that refuses this session and writes nothing. Not a
scan that could not look, not unusable rules, not the unsigned-module heuristic, not the latch of an earlier block.
**What it cannot do, measured on its first real use (2026-09-21, the owner, ELDEN RING under Easy Anti-Cheat).** A
kernel anti-cheat does not only detect a loaded DLL; its driver strips other processes' handles to the game. From the
Agent that looks like this: the watcher sees the process (its image path is readable with limited rights), and
`TargetResolver` cannot read its main module — every candidate exists and none can be opened. That is
`SessionEndReason.TargetUnreadable` since 2026-09-21 (it was reported as `TargetAmbiguous`, "more than one process is
running it", about one process; reached the user as a toast reading `InjectFailed: TargetAmbiguous`; and the one-second
session was discarded for being short — so with the bypass ON the whole visible result was nothing). **The bypass does
not change this and nothing will be built that does**: it overrules FrameLedger's own refusal, and a process another
product's driver has closed to us stays closed — opening it anyway would be defeating that product, which is rule 3,
not rule 2. The user now gets a persistent notice that says so (`Safety_Refused_TargetUnreadable`), the bypass
disclosure says it before they accept (`GuardBypassDisclosure.Version` is `/2` for that sentence), and
`legal/DISCLAIMER.md` §2A says it. The same reason covers a game that runs as administrator while the Agent does not.
**What the user sees.** The refusal or unhook notice ends with `Safety_HookingTurnedOff`; the game's page shows the
block (`Safety_Blocked_Toggle_Format`) with the toggle disabled; `capture_notes` carry
`hooking-turned-off=<reason>/<family>`; the Agent's session line carries `; hooking-turned-off`; `CaptureRefused` and
`SafetyUnhook` carry `hookingTurnedOff` (`07_IPC`). `CaptureOutcome.HookingTurnedOff` is the loop's word for it.
Since 2026-09-25 (beta.8): the block is stored as `Reason|Family|Signal` so the App says what was found in the user's
language (rows written before keep `"Reason: Family Signal"` and are shown as stored); the library card says
*Anti-cheat* instead of *Hooking off*; and the game's page shows the finding **in place of** the Hooking card, whose
switch could only be refused, while `ui.hide_anticheat_hooking` is on — its default (`08_UI` §Game detail). Off, the
card is back with the finding under its disabled switch. The finding itself is on the page either way (FR-2.2).
**How it ends.** Turning the switch off (no dialog needed to restore the guard); turning hooking off (`RevokeAsync` clears it — the row returns to its safest state); the executable changing (`HookRequest.FromConsent` drops it on a fingerprint mismatch exactly as it drops consent, and *Change executable…* clears the columns).
**What clears it.** Nothing, as before: the block outlives *Change executable* and a re-import (§A game already enabled
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
switch. *(Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
exception.)*
**During a session.** `GuardSupervisor` still scans every 30 s and the tick still counts — the Overlay's own stop is fed by it. A scan that refuses on a *judgement* is kept (`LastVerdict`), counted (`JudgementsOverruled`) and does not unhook: it is the refusal the user overruled, re-discovered. A refusal that is not a judgement still unhooks.
**D21 stands as a fact.** A process an anti-cheat driver protects is `SessionEndReason.TargetUnreadable` (2026-09-21:
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
Nothing will be built that opens it — that would be defeating another product's protection, which is rule 3. The same
reason covers a game that runs as administrator while the Agent does not.
**Afterwards.** `CaptureOutcome.StartedUnderBypass` carries the start verdict; the row gets `guard_bypassed = 1`, `guard_bypass_family`, `guard_bypass_signal`, and `capture_notes` gains `guard-bypass=<family>/<signal>`. The sessions list, the session summary (an Error `InfoBar`), the CSV header and the JSON export all say so. **Recorded limit:** a session recovered from a `.partial` after an Agent crash does not carry the mark — the verdict is known only to the live loop.
**What did not change.** `InjectViaLoadLibrary` keeps internal linkage in `fl_guard.cpp` and `tools/chokepoint-check.ps1`
still finds the injection primitives in exactly that file and the evasion primitives nowhere. `IAntiCheatGuard` is back
to four methods (`NoSecondMatcherTests`). `FloorFamilies` is untouched.
**What did NOT change, and may not.** `InjectViaLoadLibrary` still has internal linkage in `fl_guard.cpp` and `tools/chokepoint-check.ps1` still finds the injection primitives in exactly that file and the evasion primitives nowhere. `FloorFamilies` is untouched: the bypass does not shrink what the guard looks for, so §S21 stays closed — that was a bypass a crafted *data file* performed silently; this is one a *person* performs through a disclosure, and the difference is the whole design. The rules schema still rejects any `enabled` / `severity` / `warnOnly` field. There is no global form, and none may be added.
**Withdrawing it.** Pre-committed: if a report shows a user reached an injection under this path without having seen the disclosure, or the mark failing to appear on a session that ran under it, the switch is removed from the App in the next release and re-enters only with the defect's test.
### The user-mode exception — owner decision 2026-09-26 (D33)
**Why it exists.** The beta.8 library sweep turned hooking off for *GIRLS' FRONTLINE 2: EXILIUM* on a documented,
unmeasured rule — NetEase Yidun, `AntiCheatFile NEP2.dll` — after FrameLedger had measured that game hooked (three
normal Tier-1 sessions in the owner's ledger, 474,143 frames). The owner asked for a way to keep measuring a game like
that, and chose, against the rule this document had kept since 2026-09-22 and with that rule quoted back to them, **an
exception the user grants per game, bound to evidence, and only for anti-cheat that is user-mode throughout.** The
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — an exception is only
offered where FrameLedger has already measured the game hooked; it "only exposed the user to the risk its own disclosure
described" — that risk stands, and the disclosure says so, including that a ban can arrive days later and that FrameLedger
cannot know.
**What may be excepted — all of it must hold:**
- every finding about the game is `BlockedModule`, `AntiCheatFile` or `AntiCheatDirectory` of **one** family;
- that family's whole footprint is user-mode — no `drivers` entry, no `services` entry and no `*.sys` among its `files`, in
the compiled floor or the rules file (`fl::guard::FamilyIsUserModeOnly`). The floor cannot be shrunk, so data can make a
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain and
FredaikisAntiCheat; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
other family carry a driver or a service and are never excepted;
- no `*.sys` anywhere in the install tree — the kernel-driver rule (D30) is never excepted, whichever family a driver
belongs to (so *Aniimo*, which unpacks `NEPKernel.sys` beside `NEP2.dll` on its first run, stays blocked);
- the game is on no title list (`BlockedExecutable`, `BlockedStoreId` — the notorious titles are there by design);
- the ledger holds **at least two successful Tier-1 sessions** of the game: hooked, frames recorded, `exit_status = normal`
(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.
**Never excepted, whatever the user ticked:** a machine-wide `BlockedDriver` or `BlockedService`, the fuzzy tier
(`SuspiciousUnsigned`), a scan that could not look or finish, unusable rules, `TargetUnreadable` (D21), a 32-bit target,
the kill switch, and a Vulkan target (the implicit layer's own self-scan stays strict).
**How the guard takes it.** The four evaluating ABI entries carry `toleratedFamilies` — a NAME, never evidence
(`fl_guard_abi.h`). The guard resolves it against its own rules (`ResolveTolerance`), keeps only a user-mode family,
runs every check, lets that family's modules, files and folders through **and keeps scanning past them**, so a second
family, a suspicious module or a `.sys` further in still refuses. A pass that let something through is
`kAllowedUserModeException` (reason 28, the slot the withdrawn bypass left) with the family and the signal; the session it
starts is marked with them.
**How the Overlay takes it.** The Overlay stops observing when a floor module loads after injection, so the Agent
publishes the exception's family names in `Local\FrameLedger.Tolerate.<pid>` (`fl_tolerance.h`) before it asks the guard
to inject, and the Overlay's init thread reads them once, before its loader detour exists — resolving each against its
own compiled floor and honouring only a user-mode family. A mapping that names anything else tolerates nothing, and the
Agent's 30 s re-scan keeps judging every other signal.
**What ends it.** A new finding outside the excepted family at any of the four moments above writes the block as before
and revokes the exception; a session under it that crashes, is unhooked for safety or is stopped by the Overlay's
in-process floor stop revokes it; an executable change ends it with the consent it shared a fingerprint with; turning
the option off suspends every exception. **The block itself is never cleared** — the exception is a separate layer over
it, and the finding stays on the game's page (FR-2.2).
**What it is not.** Not a bypass of a live refusal, not a global switch (a Settings option off by default enables the list,
and the user ticks each game), not reachable from the command line, and not evasion: the DLL stays `LoadLibraryW`-loaded,
named and visible (rule 3). `InjectViaLoadLibrary` still has internal linkage in `fl_guard.cpp`; `tools/chokepoint-check.ps1`
is unchanged.
*Built in beta.9. PR-1: the guard's tolerance and the Overlay's channel. PR-2: the Agent — the option
(`hooking.usermode_ac_exceptions`, off), the sweep's eligibility pass (a tolerant pre-scan keyed on the rules, the
executable and the block; the session count every pass), the `SetAntiCheatException` command (the Agent gathers the
facts itself; the store applies the rule), the gate's one branch with the channel published before the request, the
re-scans naming the family, the session's mark, and every end (`UserModeExceptionLapse`) — schema 0014. PR-3: the
option and the list in Settings, the versioned disclosure (`Safety_Exception_*`, `AntiCheatExceptionDisclosure`), the
game page's exception card and its usable switch under an exception in force, the marks, and the legal text
(Disclaimer §2A 2.7, EULA 1.3, the accuracy block, SECURITY.md) — `08_UI` §Games.*
### The floor data cannot remove
@@ -469,32 +604,107 @@ earlier version of this table produced an entry that was matched *literally* and
therefore never fired. A silent hole in the blocklist, created by its own
normative documentation. Write tokens here exactly as the data must hold them.
| Family | Group | Match | Tokens |
|---|---|---|---|
| Easy Anti-Cheat | `modules` | prefix | `EasyAntiCheat`, `EasyAntiCheat_EOS` |
| Easy Anti-Cheat | `directories` | name | `EasyAntiCheat` |
| Easy Anti-Cheat | `services` | name | `EasyAntiCheat`, `EasyAntiCheat_EOS`, `EasyAntiCheat_EOSSys` |
| Easy Anti-Cheat | `drivers` | prefix | `EasyAntiCheat` — **machine-wide refusal** (check 2) |
| BattlEye | `modules` | prefix | `BEClient`, `BEService` |
| BattlEye | `directories` | name | `BattlEye` |
| Riot Vanguard | `drivers` | exact | `vgk.sys` — **machine-wide refusal** (check 2) |
| Riot Vanguard | `services` | name | `vgc` |
| Denuvo Anti-Cheat | `modules` | prefix | `denuvo` |
| nProtect GameGuard | `modules` | prefix | `GameGuard`, `npgg`, `GameMon` |
| Xigncode3 | `modules` | prefix | `xhunter` |
| Xigncode3 | `files` | name | `x3.xem` |
| mihoyo protect | `drivers` | prefix | `mhyprot` |
| FACEIT | `modules` | prefix | `faceit` |
| ESEA | `modules` | prefix | `esea` |
| PunkBuster | `modules` | prefix | `PnkBstr`, `pbcl`, `pbsv` |
| Anti-Cheat Expert | `drivers` | exact | `ACE-BASE.sys`, `ACE-ADVT.sys`, `ACE-GAME.sys` — **machine-wide refusal** (check 2) |
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service` |
| Anti-Cheat Expert | `files` | name | `PGameProtectDriver_X64.sys` |
| **Activision Ricochet** | — | — | **No data yet** — driver and service names unconfirmed (`20_OPEN_QUESTIONS` §S5) |
| **Valve VAC** | — | — | **No data yet** — needs `blockedStoreIds`, whose half of check 3 **cannot be called** (§S14; the executable half was wired in #52, but a renamed exe defeats it anyway, which is why this row reserves the store-id route). **Measured 2026-08-04: a real VAC title returns `Allow`** (`spike-notes.md` §13) |
| Family | Group | Match | Tokens | Added |
|---|---|---|---|---|
| Easy Anti-Cheat | `modules` | prefix | `EasyAntiCheat`, `EasyAntiCheat_EOS` | seed |
| Easy Anti-Cheat | `drivers` | prefix | `EasyAntiCheat` — **machine-wide refusal** (check 2) | seed |
| Easy Anti-Cheat | `directories` | name | `EasyAntiCheat`, `EasyAntiCheat_EOS` | seed; `EasyAntiCheat_EOS` 2026-09-25 |
| Easy Anti-Cheat | `services` | name | `EasyAntiCheat`, `EasyAntiCheat_EOS`, `EasyAntiCheat_EOSSys` | seed |
| Easy Anti-Cheat | `files` | name | `EasyAntiCheat_EOS_Setup.exe`, `EasyAntiCheat_Setup.exe`, `EasyAntiCheat_x64.dll`, `EasyAntiCheat_x86.dll`, `EasyAntiCheat_EOS.sys`, `start_protected_game.exe`, `eac_server64.dll` | 2026-09-25 |
| BattlEye | `modules` | prefix | `BEClient`, `BEService` | seed |
| BattlEye | `drivers` | exact | `BEDaisy.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| BattlEye | `directories` | name | `BattlEye` | seed |
| BattlEye | `services` | name | `BEService`, `BEDaisy` | 2026-09-25 |
| BattlEye | `files` | name | `BEService.exe`, `BEService_x64.exe`, `BEClient.dll`, `BEClient_x64.dll`, `BEDaisy.sys` | 2026-09-25 |
| Denuvo Anti-Cheat | `modules` | prefix | `denuvo` | seed |
| Denuvo Anti-Cheat | `drivers` | exact | `denuvo-anti-cheat.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Denuvo Anti-Cheat | `services` | name | `denuvo-anti-cheat` | 2026-09-25 |
| Denuvo Anti-Cheat | `files` | name | `denuvo-anti-cheat.sys`, `denuvo-anti-cheat-runtime.dll`, `denuvo-anti-cheat-update-service.exe` | 2026-09-25 |
| nProtect GameGuard | `modules` | prefix | `GameGuard`, `npgg`, `GameMon` | seed |
| nProtect GameGuard | `directories` | name | `GameGuard` | 2026-09-25 |
| nProtect GameGuard | `services` | name | `npggsvc` | 2026-09-25 |
| nProtect GameGuard | `files` | name | `GameGuard.des`, `GameMon.des`, `GameMon64.des`, `npggNT.des`, `npggNT64.des`, `npsc.des` | 2026-09-25 |
| Xigncode3 | `modules` | prefix | `xhunter` | seed |
| Xigncode3 | `modules` | exact | `x3.xem` | 2026-09-25 |
| Xigncode3 | `drivers` | prefix | `xhunter` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Xigncode3 | `directories` | name | `XIGNCODE`, `XIGNCODE3` | 2026-09-25 |
| Xigncode3 | `services` | name | `xhunter1` | 2026-09-25 |
| Xigncode3 | `files` | name | `x3.xem`, `xhunter1.sys` | seed; `xhunter1.sys` 2026-09-25 |
| PunkBuster | `modules` | prefix | `PnkBstr`, `pbcl`, `pbsv` | seed |
| PunkBuster | `drivers` | prefix | `PnkBstrK` — **machine-wide refusal** (check 2) | 2026-09-25 |
| PunkBuster | `directories` | name | `PunkBuster` | 2026-09-25 |
| PunkBuster | `files` | name | `pbsvc.exe`, `PnkBstrA.exe`, `PnkBstrB.exe`, `pbsv.dll`, `pbcl.dll`, `pbag.dll` | 2026-09-25 |
| FACEIT | `modules` | prefix | `faceit` | seed |
| FACEIT | `drivers` | exact | `FACEIT.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| FACEIT | `services` | name | `FACEIT`, `FACEITService` | 2026-09-25 |
| ESEA | `modules` | prefix | `esea` | seed |
| ESEA | `drivers` | prefix | `ESEADriver` — **machine-wide refusal** (check 2) | 2026-09-25 |
| ESEA | `services` | name | `ESEADriver2` | 2026-09-25 |
| Riot Vanguard | `drivers` | exact | `vgk.sys` — **machine-wide refusal** (check 2) | seed |
| Riot Vanguard | `services` | name | `vgc`, `vgk` | seed; `vgk` 2026-09-25 |
| mihoyo protect | `modules` | prefix | `mhypbase` | 2026-09-25 |
| mihoyo protect | `drivers` | prefix | `mhyprot`, `HoYoKProtect` — **machine-wide refusal** (check 2) | seed; `HoYoKProtect` 2026-09-25 |
| mihoyo protect | `services` | name | `mhyprot2`, `mhyprot3`, `HoYoKProtect` | 2026-09-25 |
| mihoyo protect | `files` | name | `mhypbase.dll`, `mhyprot2.sys`, `mhyprot3.sys`, `HoYoKProtect.sys` | 2026-09-25 |
| Anti-Cheat Expert | `modules` | prefix | `SGuard`, `AntiCheatExpert` | 2026-09-25 |
| Anti-Cheat Expert | `drivers` | exact | `ACE-BASE.sys`, `ACE-ADVT.sys`, `ACE-GAME.sys` — **machine-wide refusal** (check 2) | seed |
| Anti-Cheat Expert | `directories` | name | `AntiCheatExpert`, `AceAntibotClient` | 2026-09-25 |
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service` | seed |
| Anti-Cheat Expert | `files` | name | `PGameProtectDriver_X64.sys`, `SGuard64.exe`, `SGuardSvc64.exe` | seed; `SGuard64.exe`, `SGuardSvc64.exe` 2026-09-25 |
| EA AntiCheat | `modules` | prefix | `EAAntiCheat` | 2026-09-25 |
| EA AntiCheat | `drivers` | exact | `EAAntiCheat.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| EA AntiCheat | `files` | name | `EAAntiCheat.Installer.exe`, `EAAntiCheat.GameServiceLauncher.exe`, `EAAntiCheat.GameServiceLauncher.dll` | 2026-09-25 |
| NetEase Anti-Cheat | `modules` | prefix | `NeacSafe`, `NeacClient` | 2026-09-25 |
| NetEase Anti-Cheat | `drivers` | prefix | `NeacSafe` — **machine-wide refusal** (check 2) | 2026-09-25 |
| NetEase Anti-Cheat | `files` | name | `NeacSafe64.sys`, `NeacSafe64_ex.sys` | 2026-09-25 |
| NetEase Yidun | `modules` | exact | `NEP2.dll` | 2026-09-25 |
| NetEase Yidun | `files` | name | `NEP2.dll` | 2026-09-25 |
| Nexon Game Security | `modules` | prefix | `BlackCipher`, `BlackCall`, `BlackXchg` | 2026-09-25 |
| Nexon Game Security | `drivers` | exact | `BlackCat64.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Nexon Game Security | `directories` | name | `BlackCipher` | 2026-09-25 |
| Nexon Game Security | `files` | name | `BlackCipher.aes`, `BlackCipher64.aes`, `BlackCall.aes`, `BlackCall64.aes`, `BlackCat64.sys` | 2026-09-25 |
| TenProtect | `modules` | prefix | `TP3Helper`, `TenSafe` | 2026-09-25 |
| TenProtect | `drivers` | exact | `TesSafe.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| TenProtect | `files` | name | `TP3Helper.exe` | 2026-09-25 |
| AhnLab HackShield | `modules` | prefix | `EhSvc`, `HShield`, `HSInst` | 2026-09-25 |
| AhnLab HackShield | `directories` | name | `HShield` | 2026-09-25 |
| AhnLab HackShield | `files` | name | `HSInst.dll`, `EhSvc.dll` | 2026-09-25 |
| Anybrain | `modules` | exact | `anybrainSDK.dll`, `Cerebro.dll` | 2026-09-25 |
| Anybrain | `files` | name | `anybrainSDK.dll`, `Cerebro.dll` | 2026-09-25 |
| Roblox Hyperion | `modules` | exact | `RobloxPlayerBeta.dll` | 2026-09-25 |
| Roblox Hyperion | `files` | name | `RobloxPlayerBeta.dll` | 2026-09-25 |
| EQU8 | `modules` | prefix | `equ8` | 2026-09-25 |
| EQU8 | `drivers` | prefix | `EQU8_HELPER` — **machine-wide refusal** (check 2) | 2026-09-25 |
| EQU8 | `files` | name | `equ8_conf.json` | 2026-09-25 |
| Activision Ricochet | `drivers` | exact | `randgrid.sys`, `brynhildr.sys`, `atvi-brynhildr.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
| Activision Ricochet | `services` | name | `atvi-randgrid_sr`, `atvi-randgrid_msstore` | 2026-09-25 |
| Activision Ricochet | `files` | name | `randgrid.sys` | 2026-09-25 |
| FredaikisAntiCheat | `directories` | name | `FredaikisAntiCheat` | 2026-09-25 |
| **Valve VAC** | — | — | ~~**No data yet** — needs `blockedStoreIds`, whose half of check 3 **cannot be called**~~ **Per-title lists since 2026-09-25** (check 3): 13 Steam app ids and 8 executables, the store half wired. VAC runs inside Steam, so no module, driver or file of the game's own can name it — this row stays a dash on purpose. (**Measured 2026-08-04: a real VAC title returned `Allow`**, `spike-notes.md` §13 — the gap these lists close.) | 2026-09-25 |
The "no data yet" rows are deliberately kept rather than deleted. An admitted
gap is reviewable; a deleted row is invisible.
gap is reviewable; a deleted row is invisible. ~~Activision Ricochet's was one of them~~ — it has data since
2026-09-25 (below); VAC's stays until its per-title route exists.
> **Expanded 2026-09-25 (owner: "as many anti-cheats and as strict as possible").** Eleven families became
> twenty-two and 19 entries became 74: EA AntiCheat, Activision Ricochet, NetEase Anti-Cheat, NetEase Yidun, Nexon
> Game Security, TenProtect, AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion are new, and
> most existing families gained the groups they lacked — BattlEye's `BEDaisy.sys`, FACEIT's and ESEA's drivers,
> `HoYoKProtect.sys` (which the `mhyprot` prefix never matched), Xigncode3's driver and service, Denuvo's driver.
> **Every new token is DOCUMENTED, not measured**: the sources are SteamDB's `FileDetectionRuleSets` (MIT), the
> vendors' own support pages (Activision RICOCHET, EA, FACEIT, BattlEye), LOLDrivers and DRML, named per entry in
> the data's `note`. The ACE rule above still holds — a blocklist may over-cover and must never under-cover, and a
> wrong token fails closed by never firing — so an unmeasured token is admitted, labelled, and left for a real title
> to confirm. `kMaxFamilies` went 64 → 256 with it (2 × 74 no longer fitted).
>
> **Three services are deliberately absent**, and the reason is the RUNNING rule above: a service counts while it
> runs, and a service that runs outside play refuses every session on the machine. `EAAntiCheatService` can be set
> to start automatically; PunkBuster's `PnkBstrA` runs at every boot once installed; Denuvo's update service runs
> apart from the game. Each family is caught through its driver, its modules or its files instead.
>
> **New `modules` rows are appended, never inserted.** The Overlay's `LoadLibrary` detour reports a 1-based index
> into this group's order (`FlWriterState.earlyStopFamily` → `sessions.early_stop_family`), so a row inserted above
> an existing one would change what indexes already stored mean.
> **Anti-Cheat Expert was added 2026-08-04 from measurement, not from reading.**
> `ACE-BASE.sys` and `ACE-ADVT.sys` were found installed under `System32\drivers`
@@ -652,6 +862,26 @@ injected or layered**.
If `OpenProcess` with the needed rights fails (protected process, higher integrity), do **not** escalate creatively. Report "cannot attach" and offer Tier-2. Never attempt to acquire privileges beyond running the Agent elevated at the user's explicit request.
> **The explicit request exists since beta.10 (owner decision D34, 2026-09-27): the admin mode.** An option off by default,
> turned on through a versioned disclosure (`Safety_AdminMode_*`, `agent-admin-dialog/1`) that states what it adds, what it
> does not change, how Windows asks and the risk of a per-user install; then **Windows asks at every start of the Agent**
> (`01_ARCHITECTURE` ADR-9). What it does NOT do, each held by code rather than by this paragraph:
>
> - **It clears no finding and opens no protected process.** The guard runs exactly as unelevated: the driver scan asks
> `NtQuerySystemInformation`, and a process an anti-cheat driver protects stays `TargetUnreadable` (D21) — elevation turns
> "could not look" into an answer only where Windows would give any administrator one.
> - **It enables no privilege.** An elevated token holds `SeDebugPrivilege` and `SeLoadDriverPrivilege` disabled and they
> stay so: `AdjustTokenPrivileges`, `RtlAdjustPrivilege`, `EnterDebugMode` and the debug privilege's name may not appear
> under `src/` (`tools/chokepoint-check.ps1`), and `PrivilegeFootprintTests` asserts on the elevated CI runner that opening
> targets and LibreHardwareMonitor's CPU group enabled none.
> - **It elevates no game.** A game started from FrameLedger gets the desktop shell's token (`UnelevatedProcess`); with no
> shell to take one from, the launch is refused with that reason (`Launch_Error_1400`), never made elevated instead.
> - **It is not silent.** Every start asks; a start that was declined serves as a standard user and says so; the prompt
> answered by another account ends that Agent before it touches anything (exit 11).
>
> The residual risk is stated to the user, not solved: FrameLedger installs per user and unsigned, so a program running
> under the account could replace its files and be run as administrator the next time the user accepts the prompt.
## User-facing consent
Enabling hooking is a **per-game** action, gated by a one-time dialog per game that states, in plain language:
@@ -715,7 +945,55 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
> publishing `unhookRequested`, and keeps the Vulkan layer off by never setting `FRAMELEDGER_ENABLE_VK_LAYER`
> on a launch.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game.
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection).
### A moved drive is the same executable — owner ask 2026-09-22
Every row is keyed on its executable's path, and consent is a record about one executable: path, size, mtime
(`ExecutableFingerprint`). On 2026-09-21/22 the owner's external drive came back as `H:` instead of `D:`, and
every one of 46 games read "executable unreadable" until the letter came back; a game launched from `H:` matched
its row by file name only and ran as a stranger, keyed on the new path, with no consent. **The path is where the
bytes live; the size and the mtime are what the consent is about.** So `ExecutableRelocator` may move a row to the
same file under another drive-letter root — and only then — with everything kept: consent, block, pre-scan state,
detection. The conditions are the safety of it:
- the file is gone from the row's path (both files present is two copies, not a move; nothing happens);
- exactly one other root holds a file with the same size and the same mtime (two is an ambiguity, and ambiguity
refuses, as it does in the resolver);
- the repository's write requires the same size and mtime again (`RelocateExecutableAsync`), so no caller can point
a consent at a different binary through it;
- no process is opened for any of this; the relocator reads files. It is asked by the 15 s sweep, by the watcher on
a file-name match, and by the enable-hooking command before it says "unreadable".
- **the candidate is the row's own path with only the drive letter changed — for every caller (2026-09-23).** The
watcher's adopt used to accept ANY running path with the row's size and mtime, and every RPG Maker MV game ships
the same NW.js `Game.exe`, byte for byte, with the mtime an unzip keeps: a hooking-on entry whose drive was unplugged
could have followed another game's executable, consent and all. The adopt now requires the drive-letter twin and the
same one-candidate rule as the sweep (over the drive list plus the running file's own drive). A file-name match that
is not adopted records nothing at all (`04_CAPTURE` §Process watcher, HANDOFF D25).
*Change executable* is the other operation and stays what it was: a different binary, so hooking off, consent gone,
pre-scan not run — it is the user saying "that file", not "that file moved".
**Two more answers, 2026-09-23 (owner decisions D26, D27).** Both are downgrades or neutral by construction; neither
can move a consent onto a binary it was not given for.
- **D27 — the file moved and changed.** When the row's file is gone and the only file at its path under another
letter has OTHER bytes (the game updated while the drive had another letter), the row follows it through *Change
executable*'s write (`ChangeExecutableAsync`): the new size and mtime, hooking off, consent cleared, the pre-scan
back to not run, the block kept. The user turns hooking on again for the new binary, through the disclosure, as
for any changed executable. Two such files (two drives) is an ambiguity and refuses. The same rule holds for the
watcher's adopt, whose session is then Tier 2 until the user does.
- **D26 — two entries for one file.** When the move is refused because another entry already holds the target path
— a twin made while the letter was different, as the owner's `H:` entries were — and the file there has the bytes
the stale entry recorded, the two become one (`IGameMerge`, one transaction): the entry made first stays (its name,
notes, consent and history), the other's sessions are re-parented to it, a block either carried is kept (hooking
off; nothing clears a block, and a merge must not be how one disappears), a crash auto-disable still in force is
kept, the crash counts add, and the dropped row is deleted. **Nothing about consent moves between the rows:** the
survivor keeps its own record — which, when it is the entry that moves, is about these same bytes — and the dropped
row's goes with it. A merge waits while a session of either entry runs or waits in a `.partial` to be recovered (a
session finalized under a deleted entry would be dropped), and it is never done with an entry removed from the
library. Other bytes under the twin are not merged: they do not prove the other entry is this game, so the log says
so once and the user removes the entry they do not want.
### A game already enabled can become blocked later
@@ -744,7 +1022,7 @@ rules feed can switch injection on for a game without anyone looking.
## Crash & stability safety
- Two crashes of the same game within 60 s of injection ⇒ hooking auto-disabled for that game, UI explains, Tier-2 takes over. Recorded in `games.hook_autodisabled_reason`.
- Two crashes of the same game within 60 s of injection ⇒ hooking auto-disabled for that game, UI explains, Tier-2 takes over. Recorded in `games.hook_autodisabled_reason`. *"Crash" here is any abnormal end: since beta.8 a session whose exit code is not an exception's (End task's 1) is `normal` on its row, and this policy still counts it inside the window — a hang our hook caused, ended by the user, is the case it exists for. The row's reason says "ended abnormally twice within 60 s of injection" (`04_CAPTURE` §Crash & exit classification).*
- The Overlay DLL self-disables after 3 faults in hook bodies (`17_HOOK_ENGINE` §Fault policy) and reports it.
- Every hooked session writes a breadcrumb file before injection; if the game process dies before the first frame record arrives, the next run is recorded as suspect.
+33 -4
View File
@@ -34,6 +34,22 @@ Rules for this document:
> one, so that would be a code list); and the ja text, which ships as English until a reviewer signs. **Pre-committed
> withdrawal:** an injection reached under it without the disclosure having been shown, or a session under it that is
> not marked, removes the switch from the App in the next release.
>
> **2026-09-22 — withdrawn by the owner, for a reason the pre-commitment did not list.** Its first real use (ELDEN
> RING under Easy Anti-Cheat) reached `TargetUnreadable`: the switch could not do anything where it was wanted, and
> where it could inject it only exposed the user. The owner asked for the opposite: a finding turns the game's hooking
> off, wherever the guard makes it. `19_SAFETY` §What a finding does to the game is the specification; CLAUDE.md rule 2 is
> unstruck. The two open items above (kernel-level families, the ja text) are moot.
>
> **2026-09-26 — one narrow exception, by owner decision D33, with the 2026-09-22 withdrawal quoted back.** Beta.8's
> library sweep blocked a game FrameLedger had measured hooked (GIRLS' FRONTLINE 2: EXILIUM, NetEase Yidun `NEP2.dll`),
> and the owner chose an evidence-bound, per-game exception for anti-cheat that is user-mode throughout (`19_SAFETY`
> §The user-mode exception; CLAUDE.md rule 2's amendment). The two reasons D22 gave are answered: it is offered only
> where FrameLedger has already measured the game hooked, and its risk is stated in its own disclosure. **What stays
> open, and is the owner's:** the `ja` text of `Safety_Exception_*`, which ships as English until a reviewer signs;
> whether a family the rules file makes kernel-level later should end existing exceptions at once (today it does, at
> the sweep's next pass and at every session start); and a real-hardware check that NEP2.dll's load time relative to
> the injection is covered on the owner's machine (the ctest decoy covers the late load).
| # | Decision | Consequence |
|---|---|---|
@@ -88,7 +104,7 @@ or it becomes the next stale status claim this file exists to record.
| **S1** | ◐ **launch mode built as "inject late" 2026-09-06 (P1 item 2); the cost is now measured per title** | `FlGuardedInjectWhenReady` polls until a presentation runtime is mapped, then runs the full guard; `dxgiPresentsBeforeHook` and the reported wait are the input the 2026-08-05 deferral lacked. The ruling "inject late vs. no launch mode" is answered by construction — inject late exists — and whether it is *preferred* per title is what the numbers decide |
| **S13(c)** | ✅ **salvageable, and salvaged 2026-09-06** | The externally observable proxy the entry proposed is what was built; the missing input is produced by every launched session |
| **S19(b)** | 🅓 **deferred, rationale written — and MEASURED** | CI 2026-08-05: the fragment fires on `System.Security.Cryptography.ProtectedData.dll` loaded by a .NET **test host**, i.e. inside a real scan set in the launch-mode arrangement — refusing our own injection. The entry's "plausible and unmeasured" is superseded; the deferral rationale (a `CryptCATAdmin*` PR doing network I/O inside the hard gate, NFR-10) still stands. *(Marked 🔴 until 2026-08-27. The measurement belongs in this cell, not in the marker — a glyph that means "deferred" and a glyph that means "open defect" cannot be the same one in a table audited by counting.)* |
| **S14** | 🅓 **exe half wired 2026-08-05; store-id half deferred to P4, rationale written 2026-09-06** | The store-id half's only in-policy route is P4's platform metadata extractors feeding a guard-side resolver; a resolver with no extractor would refuse every title. No title is blocked by store id today because none is listed |
| **S14** | ✅ **both halves wired and seeded 2026-09-25** (exe half 2026-08-05) | ~~The store-id half's only in-policy route is P4's platform metadata extractors feeding a guard-side resolver~~ — built as a guard-side seam that reads Steam's `appmanifest_*.acf` and GOG's `goggame-<id>.info` itself; an install no store names is not refused, unreadable store metadata is. 30 Steam ids and 33 executables listed (rules 2026.09.4), floored. Epic has no reader |
| **S23-1** | ✅ **resolved 2026-08-05** | `FlGuardBuildId` gives the Agent a build id of its own, and `ShmHandshakeValidator` performs the comparison `07_IPC` and `04_CAPTURE` both specify. Every refusal path is driven, including **both ids empty** — the shape the feature shipped in, where `"" == ""` reported `Ok` for every process on the machine |
| **S23-4** | ✅ **resolved 2026-08-05** | `19_SAFETY` §During a session said "the module scan and the driver scan"; `EvaluateImpl` runs four. Reworded to "every pre-injection check" so it cannot go stale when a check is added, with the two omissions named — `services` is the only tier measured firing on real anti-cheat, and the pre-scan is the only one touching the filesystem |
| **S2 part three** | ✅ **built 2026-09-06 (P1 item 3)** | In-layer supervision on the present path, landed with `vkQueuePresentKHR`; `unhookRequested` and the tick deadline both stop the layer (passthrough with the reason on the mapping), proven by a fake loader chain and a 1.5 s test-only flavour of the DLL |
@@ -165,6 +181,10 @@ the recount becomes the next thing that needs recounting.
> as ◐ two here rather than re-glyphing the rows: the rows were right and the paragraph was
> wrong, and the residue of each is a run, not a rationale. P2's sequencing is `HANDOFF` §P2.
>
> **2026-09-25: S14 ✅.** The store-id half, one of the six deferrals of 2026-09-06 (to P4), is built and seeded
> in the beta.8 train: a guard-side seam reads the store's own metadata, and the lists carry 30 Steam ids and 33
> executables. The deferred set is five; ◐ stays two (S1, H11); nothing else in this count moved.
>
> **STILL TEN on 2026-08-27, for the third consecutive movement.** S31 moved from ❓ to ◐,
> so ❓ goes four to three and ◐ goes two to three. **The number has now stayed at ten across
> three different changes**, and that is worth saying out loud precisely because a reader
@@ -1631,7 +1651,9 @@ a system DLL.
**Two families remain unrepresented in the data** — Activision Ricochet (driver
and service names unconfirmed) and Valve VAC (needs `blockedStoreIds`). Recorded
in the seed's own `$comment`. The `heuristic.trustedSigners` list is a guess and
in the seed's own `$comment`. ~~Ricochet~~ **has data since 2026-09-25** (`randgrid.sys`,
`atvi-randgrid_sr`/`_msstore`, from Activision's support pages — documented, unmeasured; `19_SAFETY`
§Blocklist seed). VAC still has none. The `heuristic.trustedSigners` list is a guess and
is marked UNVERIFIED.
### S13(c) · Is launch-mode injection salvageable?
@@ -3152,7 +3174,14 @@ gate.
> and the block's own comment says so. The block was rewritten to 2026-09-06 truth in the same
> PR (the previous §4 note still said frame generation and ray tracing had no hook).
### S14 ◐ · Pre-injection check 3 is **unwired**, and has no "cannot determine" state
### S14 ✅ · Pre-injection check 3 ~~is **unwired**, and has no "cannot determine" state~~ — both halves wired and seeded 2026-09-25
> **Closed 2026-09-25 (beta.8, owner decision: title lists yes, the AreWeAntiCheatYet bulk list no).** The store
> half reads the store's own metadata through `Sources::StoreIdentity`, from the install root the guard derives
> from the pid — the ABI is unchanged, which was reason (2). Reason (3) is answered by the matrix in `19_SAFETY`
> check 3: listed refuses, no store identity is not applicable, unreadable store metadata refuses. Both lists are
> seeded (30 Steam ids, 33 executables) and floored. What stays open is Epic, which has no reader and so carries no
> identity to this check. The body below is the history.
Found 2026-08-02 while hardening the rules toolchain. `19_SAFETY` §Pre-injection
checks lists a per-title blocklist as check 3, but `anticheat.blockedExecutables`
@@ -4319,7 +4348,7 @@ Each of these is referenced by an existing doc but specified nowhere.
| Area | What is missing | Referenced by |
|---|---|---|
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) ~~elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator~~ **closed 2026-09-27 (beta.10, owner decision D34): chosen** — `capture.run_elevated`, a UAC prompt at every Agent start, the logon task's Agent asking through its own prompt, and with the option off an administrator's App starts the Agent with the shell's token (`01_ARCHITECTURE` ADR-9). "How elevation is requested and persisted" is that: requested by the prompt, persisted as one settings row and never as a task's run level | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
| **Session identity** | ~~`sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`.~~ **`sessions.session_guid` (UNIQUE) exists since 2026-09-09 (P2 PR-B), with `qpc_epoch` / `qpc_frequency` beside it.** ~~Still open: the `.partial` file format is undefined, and it is the crash-recovery artifact — PR-D's, pre-committed in HANDOFF §P2 (CRC-framed append-only chunks, the valid prefix wins)~~ **Built 2026-09-10 (P2 PR-D): `06_DATA_MODEL` §The `.partial` file, `PartialSessionFile` + `PartialRecovery`, killed at every byte in the merge gate.** What stays open here is the pipe's use of the guid (P3) | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
| ~~**Settings registry**~~ | ~~The `settings` table is key/value with no key list, defaults, types, or validation — and no message for the UI to push a changed setting to the Agent.~~ **Decided 2026-09-13 (HANDOFF §P3 decision D16)**: the key list with defaults and ranges, and *no* push message — the Agent re-reads its keys at each session start. **Built the same day (P3 PR-3):** `06_DATA_MODEL` §Settings registry (12 keys), `Application.Settings.SettingsRegistry` + `RegisteredSettings` (validating writes, tolerant reads), `SettingsRecorderPolicy` resolving `capture.min_session_s` / `telemetry.interval_ms` / `retention.raw_sessions_per_game` at each session start. **Row closed** | `06_DATA_MODEL`, FR-10 |
| **Error taxonomy** | `07_IPC` lists `CaptureError` codes; no canonical mapping to resx keys and user-facing text, though `09_I18N` requires safety strings to be reviewed as legal text | `07_IPC`, `09_I18N` |
+372 -23
View File
@@ -746,8 +746,11 @@ Cyberpunk 2077 never chains `sl::DLSSOptions`, so 0xFF there is the title's trut
call, and if built, the byte stays 0xFF and the report says *derived*.
- **Do not** reach for `slDLSSSetOptions` via `slGetFeatureFunction`: §2b refused it on five
grounds that have not changed, and NGX-direct `NVSDK_NGX_Parameter_GetUI` is licence-blocked.
- **Alan Wake 2 did not run on 2026-09-04** (the owner tried every workaround; the title is
broken on this machine), so the measurement moved to **Dying Light: The Beast at DLSS**, the
- ~~**Alan Wake 2 did not run on 2026-09-04** (the owner tried every workaround; the title is
broken on this machine)~~ **Corrected 2026-09-27 (owner):** it did run late that evening — the run reports
`alanwake2-224851` and `alanwake2-230707` hold two captures (DLSS + RR, ray tracing *Yes*, 92.52 FPS; then ray
tracing off, Presented 114.52), neither with the quality preset, which is what this item needed. The earlier
attempts that day failed, so the measurement moved to **Dying Light: The Beast at DLSS**, the
first Streamline title measured whose batches carry `kFeatureDLSS` — identity `Dlss` on 4,575
of 4,575 batches. It read `UpscalerParams = 0` on three captures, because DL:TB ships
**Streamline 2.8.0, which deprecates `slSetTag` for `slSetTagForFrame`**, and only the
@@ -1310,9 +1313,13 @@ charts (6) after Games (5) because the summary opens from the Sessions tab; Sett
(`PipeTransmissionMode.Message`, `PipeOptions.Asynchronous | CurrentUserOnly`, remote clients rejected,
two instances), the ACL a `PipeSecurity` of the current user's SID plus Administrators~~ **`CreateNamedPipe`
itself (CsWin32), so the flags and the DACL are stated in code rather than left to a library default:**
message mode, overlapped, `PIPE_REJECT_REMOTE_CLIENTS`, two instances, the SDDL `D:P(A;;GA;;;<user>)(A;;GA;;;BA)`
on every instance, and the client's token user compared to the server's by impersonation on the client's
first frame (the kernel refuses it earlier). The CLIENT uses `PipeOptions.CurrentUserOnly`. *(As built
message mode, overlapped, `PIPE_REJECT_REMOTE_CLIENTS`, two instances, the SDDL ~~`D:P(A;;GA;;;<user>)(A;;GA;;;BA)`~~
`O:<user>D:P(A;;GA;;;<user>)(A;;GA;;;BA)` (the owner stated since 2026-09-17) on every instance, and the client's
token user compared to the server's by impersonation on the client's first frame (the kernel refuses it earlier).
The CLIENT ~~uses `PipeOptions.CurrentUserOnly`~~ checks the pipe's owner against its own token USER
(`PipeAccessControl.RequireOwnedByCurrentUser`, 2026-09-17) — `CurrentUserOnly` compares the token's default owner,
which an elevated token sets to Administrators, and refused the same user's Agent across elevation (corrected
2026-09-27). *(As built
2026-09-13; the wording above was the plan's, kept struck because it named a library path the build did not
take.)* Framing is
`07_IPC` §C as written: 4-byte LE length + UTF-8 JSON ≤ 1 MB, `Shared.Ipc.IpcEnvelope { type, id?, payload }`,
@@ -1361,7 +1368,7 @@ charts (6) after Games (5) because the summary opens from the Sessions tab; Sett
*PRs #204-#210. Status is where status lives (`CHANGELOG.md` `[0.1.0-beta.3]`); this is only what no other file carries.*
**Decisions (owner, 2026-09-21).**
- **D18 — the guard has one override, and its shape is fixed.** Per game, off by default, never global, a two-act
- ~~**D18 — the guard has one override, and its shape is fixed.**~~ **Withdrawn 2026-09-22 (D22, below).** Per game, off by default, never global, a two-act
disclosure stamped by the Agent, overruling the guard's JUDGEMENT only, never changing HOW FrameLedger injects.
`19_SAFETY` §The user's bypass is the specification and CLAUDE.md rule 2 carries it as a rule. The owner chose this
over a global switch and over a variant that kept kernel-level families refused. **Do not widen it**: no settings key,
@@ -1372,9 +1379,9 @@ charts (6) after Games (5) because the summary opens from the Sessions tab; Sett
`--diag` and Settings ▸ System (with Copy) carry it instead.
**Owed by the owner after this release.** `20_OPEN_QUESTIONS` M10 (one elevated session with PawnIO beside a reference
tool decides whether `cpu_temp` stays); a look at the light theme's pills, the bypass dialog and Settings ▸ System in the
running App — no FrameLedger binary was run against the owner's data folder in the session that built them; the ja
review of `Safety_Bypass_*`, which ships as English until signed.
tool decides whether `cpu_temp` stays); a look at the light theme's pills ~~, the bypass dialog~~ and Settings ▸ System in the
running App — no FrameLedger binary was run against the owner's data folder in the session that built them ~~; the ja
review of `Safety_Bypass_*`, which ships as English until signed~~ (moot since 2026-09-22: the strings are gone).
**Traps.**
- **xUnit.net v3 4.x defaults to Microsoft Testing Platform v2.** `build.ps1` is VSTest-shaped (collector, `results.trx`);
@@ -1394,23 +1401,32 @@ review of `Safety_Bypass_*`, which ships as English until signed.
*Status is `CHANGELOG.md` `[0.1.0-beta.4]`; this is what no other file carries.*
**Decision (D21).** A process an anti-cheat driver protects is `TargetUnreadable`, and **the bypass stops there**: D18's
override overrules FrameLedger's own guard; it is not, and may not become, a way past another product's protection.
Any proposal to "make the bypass work on EAC titles" is rule 3, not rule 2 — refuse it.
**Decision (D21).** A process an anti-cheat driver protects is `TargetUnreadable`, and nothing FrameLedger offers changes
that: it is not, and may not become, a way past another product's protection (rule 3, not rule 2). ~~"the bypass
stops there"~~ — the override itself is gone since 2026-09-22 (D22).
**Found and NOT fixed — each needs its own PR.**
- **A refused session is not recorded, though the notice says it is.** `Notice_Refused_Recording` ("the session is still
recorded — duration and hardware telemetry") is appended to every refusal, and `CaptureSession` returns at the
refusal: the run lasts about a second and `SessionFinalizer` discards it as under the minimum length. CLAUDE.md's
Tier 2 ("duration + sensors + the reason") has no producer for a refusal. The new `TargetUnreadable` notice does not
make the claim; the older refusals still do.
- ~~**A refused session is not recorded, though the notice says it is.**~~ **Fixed 2026-09-22 (D23):** the loop holds a
refused session open until the target exits, so Tier 2 has a producer and the sentence is true for every refusal.
- **A released Overlay logs its build as `v0.1.0-beta.3-dirty`**: the CI checkout is dirty by the time CMake runs
`git describe`. Both sides of the handshake compile the same string, so nothing breaks; it is a release that calls
itself dirty.
- **An install over a running Agent half-replaces the folder** (three failed starts, `Microsoft.Data.Sqlite` not found).
The in-app updater stops the Agent first; `Setup.exe` run by hand does not, and only the CHANGELOG says to.
- **A GF2 session ended `SafetyUnhook` 35 s in (2026-09-21 21:45) and nothing recorded which finding fired.** The
Agent's log line names it from this release on; read it the next time it happens before guessing.
- ~~**An install over a running Agent half-replaces the folder** (three failed starts, `Microsoft.Data.Sqlite` not
found).~~ **A GUESS, WITHDRAWN the same evening, and it had already been published in beta.4's notes.** Nothing was
installed between the failures (20:59–21:01) and the start that worked (21:02); the PC had been restarted at 20:57
and was again at 21:02 (System log 1074), and the owner's external USB drive was failing all evening. The three
failed starts are UNEXPLAINED. What is still true and still unbuilt: `Setup.exe` run by hand does not stop the Agent,
and only the CHANGELOG says to.
- **A GF2 session ended `SafetyUnhook` 35 s in (2026-09-21 21:45) and nothing recorded which finding fired.** ~~read it
the next time it happens before guessing~~ **Mostly explained by the owner's report:** the game is on the failing
drive, `GF2_Exilium.exe` crashed at 21:45:50 with `0xc0000006` (in-page I/O error, Application log 1000/1005, eleven
Ntfs errors in that minute), and the Agent saved the session at 21:45:52. The 30 s re-scan reads the game's directory
(check 4) and the process; either failing is a refusal by design, so a dying drive reads as a safety unhook. **Open:**
that row says `UnhookedSafety` about a game Windows says crashed — whether a crash witness should outrank the unhook
in `ExitStatusMapper` is a decision, not a bug fix. The log line's new `guard=` detail will say which check it was.
- **Read Windows' event logs before attributing a symptom** (`Get-WinEvent` System: disk 51/153, UASPStor 129, Ntfs;
Application: 1000/1005). On 2026-09-21 the first pass published one cause that was wrong and left one 'unknown' that
those two logs answered in a minute.
**Traps.**
- **`CultureInfo.CurrentUICulture` set inside an `async` start does not reach later dispatcher operations.** A resource
@@ -1420,6 +1436,321 @@ Any proposal to "make the bypass work on EAC titles" is rule 3, not rule 2 — r
- **`Mutex` is thread-affine**: `SingleInstance` is claimed and disposed on `Main`'s thread; its tests are synchronous
on purpose.
## 2026-09-22 — the override withdrawn; a finding turns hooking off; Tier 2 exists; a moved drive is followed
*Status is `CHANGELOG.md` `[0.1.0-beta.5]`; this is what no other file carries.*
**Decision (D23, owner: "Tier 2 does not work — what does it record, and show it").** Tier 2 is now a held session
(`04_CAPTURE` §Tier selection): duration, telemetry and the reason, saved under the same 30 s rule as Tier 1. **Two
choices inside it that a later session may want to revisit:** (a) *every* library row is still watched, so a
hooking-off game accumulates play-time rows — the documented behaviour (`06_DATA_MODEL` "0 = Tier 2"), kept; the
alternative, watching only rows the user enabled or FrameLedger itself disabled, is one predicate in
`CaptureOrchestrator` and a doc change; (b) a hooking-off row is decided BEFORE the process is opened, so an
elevated utility in the library (the owner's Borderless Gaming) is a quiet Tier-2 row rather than a red notice — and
`SteamLibrarySource.KnownTools` keeps the next import from adding one. The owner's existing Borderless Gaming row is
theirs to remove.
**Decision (D24, owner: "handle the drive changing its letter while the data does not").** A row may follow its
executable to another drive-letter root when the file is gone from the row's path and exactly one other root holds a
file with the same size and mtime — with consent, block and detection kept (`19_SAFETY` §A moved drive is the same
executable). Three callers: the 15 s sweep, the watcher's file-name match, the enable-hooking command. The owner's
log of the same morning is the case: 46 rows unreadable on `D:` while the drive sat on `H:`, GF2 and ELDEN RING
running from `H:` "BY FILE NAME ONLY". ~~**Not done, on purpose:** re-import does not merge a duplicate row an earlier
re-scan created at the new path (`LibraryImporter` still dedupes on path); the relocator refuses to move onto a path
another row owns and says so in the log.~~ **Done 2026-09-23 (D26/D27, the beta.6 section below):** twins with the
same bytes merge, a changed file is followed with hooking off, and the import no longer adds a twin.
**Trap.** `FakeIdentity` in three test classes answers the same fingerprint for ANY path; a relocation test needs one
that answers per path, or the "exactly one candidate" rule reads every root as a match.
**Decision (D22, owner).** The per-game guard override (D18) is withdrawn entirely — the owner's words: a switch that
can be turned on and still does nothing is meaningless. In its place a finding about the game turns that game's hooking
off, at the pre-scan (as before), at a session's start and at the 30 s re-scan (new): `19_SAFETY` §What a finding does to the game.
Machine-wide drivers and services refuse the session only. D18 and D21's "the bypass stops there" are history; D21's
fact stands.
**Traps.**
- **Removing an enum value that is LAST on both sides of the ABI renumbers nothing**, and `GuardMirrorTests` fails until
the native DLL in the test output is rebuilt (`./build.ps1 native`) — it looks like a managed defect and is not.
- **The first `DROP COLUMN` migration.** SQLite ≥ 3.35 is asserted in `LedgerDatabaseTests`. The test helper
`RewindSchemaAsync` deletes `schema_migrations` rows and leaves columns in place; a rewind to below 8 followed by a
re-migration would run 0008 against columns that are gone. Today it rewinds to 2 and never re-migrates.
- **Meziantou MA0004 fires on the SECOND await of a test method** once a lambda inside it used `ConfigureAwait(false)`.
- **A patch script must not carry `\r\n` inside a bash heredoc**; the helper module is written with the Write tool.
## 2026-09-23 — the beta.6 train: a file name is not an identity, one entry per executable, Tier 2 shown live
*Status is `CHANGELOG.md` `[0.1.0-beta.6]`; this is what no other file carries. The owner's list and the
evidence behind each item are in the approved plan the PRs cite; the decisions it took are D25–D28.*
**Decision (D25, owner: "HELLO, HELLO WORLD! was recorded as Flower in Us, twice").** A file name is not an identity:
a process that matches an entry by file name only starts nothing unless the relocator moves that entry to it, and the
relocator accepts only the entry's own path with its drive letter changed. The stranger session is gone (it created a
wrongly-named entry through `SessionRecorder`'s `EnsureAsync`); the running table is keyed by executable path; the
launch election registers its session and defers to the watcher's. **What it costs:** a game whose FOLDER moved records
nothing until *Change executable* — accepted, because the alternative is exactly what put HHW's sessions under Flower
in Us. **D28 (owner, same day):** HHW itself is measured by pointing an entry at `swiftshader\Game.exe` (the NW.js
runtime its .NET launcher starts); no launcher-following in beta.6.
**Decision (D26, owner: "the library still shows two entries side by side after the drive letter changed, with the
data unchanged").** The Agent merges two entries for one executable under two drive letters by itself: the stale
entry's file is gone, the other entry holds the same path on another letter, and the file there has the bytes the
stale entry recorded. The entry made first stays; the other's sessions join it; a block or a crash auto-disable in
force is kept; no consent moves between them; it waits while a session of either runs or waits to be recovered
(`CaptureOrchestrator.IsRecording`, `IPartialSessionStore.PendingGameIds`). `19_SAFETY` §A moved drive has the rules,
`06_DATA_MODEL` the writer. The import no longer adds a twin: a store's executable that is a library entry's path on
another letter, with that entry's file gone, is shown "in the library under another drive letter" and skipped.
**D27 (owner, same day):** when the only file at the entry's path on another letter has other bytes, the entry follows
it with hooking off (`ChangeExecutableAsync`, the *Change executable* write). Other bytes under a twin are NOT merged
— the log says once which entry to remove.
**Traps.**
- **`IGameMerge` is a second writer that can delete a `games` row.** Only the relocator calls it; a test that removes
rows under a running session must expect the merge to wait (busy), not to race it.
- **Python patch scripts: `\"` inside a normal triple-quoted string is an escaped quote**, so `@"C:\"` silently loses
its backslash and the replace finds nothing (or worse, writes the wrong text). Use raw strings (`r"""…"""`) for C#.
- **`FakeIdentity` in `CaptureOrchestratorTests` answers every path with the same bytes — which is exactly the hazard
D25 closed**, so it is the right fake for "identical bytes in another folder are another game" and the wrong one for
any test that needs a relocation to succeed (use `ExecutableRelocatorTests.DiskByPath`).
- **A background service that throws stops the Agent's host, and until 2026-09-23 it said so nowhere.** The Generic
Host's default `BackgroundServiceExceptionBehavior` is `StopHost`, and `ServeAsync` never routed
Microsoft.Extensions.Logging into Serilog, so the reason reached no file. `WatcherHostedService` runs recovery before
the watcher: one `.partial` whose finalize threw would have stopped every start, and the App would have started a new
Agent into the same failure each time. `PartialRecovery` never throws now, and the host logs through `AddSerilog`.
- **Removing an entry while its game runs used to lose the session.** Both of the owner's GIRLS' FRONTLINE 2 faults
were a removal (to clean up an `H:` twin) under a running session. The finalize now resolves the owner; a test that
deletes a row mid-session must expect `GameRemoved` or a re-keyed row, never an exception.
**Tier 2 on the wire (item 4a, owner: "capture still does not show when some titles are launched").** `SessionStarted`
is published ONCE per session — at the attach, or at a held session's first tick carrying `hold` — so the card never
flickers between tiers; a held session's 1 Hz is `SessionHeld`, never `SessionProgress` (its required fields would put
zeros that look measured on the wire); the refusal's event goes out when the hold begins and is not repeated at the
end; a faulted session completes with `finalize: faulted`. Every list of running sessions the App keeps is seeded from
the status at each connect (`07_IPC` §Client behavior). All fields are additive: `IpcProtocol.Version` stays 2.
**Traps.**
- **Only `hold` means held.** The status lists every session that has not attached yet at tier 2 (beta.5's shape,
kept), so a tier-2 `ActiveSession` without `hold` is a session STARTING. The card shows its name and badge and
nothing else; "nothing is measured" and "Attached — waiting for the first frames…" would both be false there.
- **`sed -i` in this machine's Git Bash writes a CRLF file back as LF.** Twice on 2026-09-23 a one-line `sed -i` turned
a test file into `w/lf` (`git ls-files --eol`), which `dotnet format` then fails on for no visible reason. Check
`git ls-files --eol -m -o --exclude-standard | grep -v w/crlf` after any shell edit; `unix2dos` repairs it.
- **Heredocs that carry C# with nested quotes can fail to parse in the Bash tool** ("unexpected EOF while looking for
matching `'`") even when quoted `<<'EOF'` — write the script with the Write tool and run it by path, as the traps
above already say for patches.
## 2026-09-23 (after 0.1.0-beta.6) — the recording switch
*Status is `CHANGELOG.md` `[0.1.0-beta.7]`; this is what no other file carries.*
**Decision (D29, owner: "the Agent records Borderless Gaming although hooking is off, and it starts with Windows —
propose an ignore list, a disable, or something suitable").** Both, as one mechanism: a per-entry **Recording**
switch (`games.record_sessions`, schema 0009, FR-1.6) the user owns, and the import's known-tools list
(`SteamLibrarySource.KnownTools`) applied once to the entries an earlier import made, which start with it off. Off
means the program is not watched at all (the watchlist is the entries whose recording is on), a running session of it
stops at the next poll, and `LaunchGame` answers `RecordingOff`. Not chosen: a hard-coded list the watcher consults
(no user control, and a list is never complete), and D23's recorded alternative of recording Tier 2 only for entries
hooking was once enabled for (it would take back the Tier-2 sessions the owner asked for). The Privacy Policy (2.3) and
the Disclaimer (2.6, whose accuracy block also carries #224's correction) were bumped with the owner's leave ("sửa docs
và legal"), so the Legal Gate shows both once.
**Traps.**
- **A pid the watcher matched stays matched.** Switching recording off stops the session but leaves the process in
`ProcessWatcher`'s table, so switching it back on while the same process still runs starts nothing until it restarts.
A process the watcher never matched (off from the start) is picked up by the next poll.
- **A migration that changes data needs its own rewind in a test.** `RewindSchemaAsync` leaves columns in place, so
`ScriptNineAddsTheRecordingSwitchOffForSteamToolsOnly` drops the column itself before re-applying 0009.
- **`SqliteGameRepository._columns` is read by ordinal** (`ReadMore`): a new column goes at the end of the list, and the
twin merge reads its own columns — both had to learn `record_sessions`.
## 2026-09-25 — the beta.8 train
*Status is `CHANGELOG.md` `[0.1.0-beta.8]`; this is what no other file carries. The owner's list
(eight items: the anti-cheat set as large and strict as possible, hiding the hook part for anti-cheat games, more
metadata, NVIDIA App overrides, clearer reasons, a working Trend, FPS decimals, chart fixes) is planned as nine PRs in
one approved plan; each PR cites it.*
**Decision (D30, owner, asked before any code: "which strict rules, beyond named tokens?").** Two of three: **any
kernel driver (`*.sys`) inside a game's install tree** is a finding (code, not data — `kKernelDriverInTreeFamily`),
and **per-title lists** (30 Steam ids, 33 executables across nine families, floored like the families). **Not** the
AreWeAntiCheatYet bulk import (~250 Steam ids): community data that keeps listing a game after it drops its anti-cheat
would turn hooking off for good, since nothing clears a block. Recorded because the next person to "expand the list"
will find that import one search away.
**Decision (D31, owner): the store half's matrix.** Listed → refuse; no store identity (a loose folder, an Epic
install, a Steam folder no manifest names) → not applicable, recorded as nothing; a store layout whose metadata cannot
be read → refuse (`PreScanFailed`). §S14's "unknown must never read clean" is kept by the third row; the second is not
an unknown — it is the answer "this is not a store title", and refusing it would be the gate that cannot pass.
**Decision (D32, owner, item 2: "an option to hide the hook part for games with anti-cheat").** Hide **and** scan:
the Agent pre-scans every library entry itself (`AntiCheatPreScanSweep`, checks 3 and 4, once per rules version and
executable — schema 0010's key), a finding is the same block every other moment writes, and the game's page shows
the finding in place of the Hooking card while `ui.hide_anticheat_hooking` is on (default on). Tier 2 is still
recorded. **Why not the setting alone:** most entries sat at `hook_prescan_state = 'not_run'` — the pre-scan ran only
when someone asked for hooking — so a hide keyed on a finding would have hidden nothing on most libraries. **What it
must never become:** a gate. The chokepoint runs checks 1–4 at every session start whatever the sweep wrote; the sweep
only answers early, writes through the consent store's block-preserving `UPDATE`, and hides a control that could
only be refused, never the finding (FR-2.2).
**Traps.**
- **`Rules` is ~650 KB now** (256 families, 128 per-title rules). `x = Rules{}` builds that on the stack before
copying — use `ResetRules`. The Vulkan layer parses on a game's own `vkCreateInstance` thread, and native tests hold
it on the heap (two in one test function overflowed the 1 MB default).
- **New `anticheat.modules` rows go at the END.** The Overlay's early stop reports a 1-based index into that order, and
`sessions.early_stop_family` stores it.
- **`sed -i` and the Bash tool's heredocs strike again**: a heredoc halved `\\` in a Python patch (a C# verbatim path
still matched by luck), and a one-line `sed -i` turned `layer.cpp` into LF. Scripts go through the Write tool and run
by path; `git ls-files --eol -m` after any shell edit.
- **`'clean'` is not new.** `AgentCommandHandler` has stamped it on every consented enable since P3; the sweep adds it
for entries nobody enabled. Nothing gates on it — a reader that treats `'clean'` as "may hook" is a second gate.
- **The sweep's notice is not a refusal.** `HookingTurnedOff` is `SafetyNoticeKind.HookingOff` with Dismiss: a
`Refused` kind would offer "record this session without measuring it" with no session running.
- **Analyzers on tests:** CA2000 flags a disposable passed into a record's constructor (construct it inside a class
that disposes it), MA0023 a regex with numbered groups (name them), CA1062 a `[Theory]` string parameter
dereferenced without a check.
- **`exe_machine` NULL is stale (schema 0011).** The detection sweep re-reads any row whose executable facts this build
has not written — so a test double of `IGameRepository.ApplyDetectionAsync` that drops the new fields makes every
sweep test re-scan forever. `unknown` is the stored "looked, could not tell".
- **`FileVersionInfo` on a System32 file reads its `.mui`.** `version.dll` read in place said 6.2.x, its copy in a temp
folder 10.0.x: compare a version against the file that was read, never against its source.
- **`PASS_REGULAR_EXPRESSION` alone makes ctest ignore the exit code.** `fl_nvapi_bridge` passed for weeks with a failing
assertion on every GPU machine (CI has no driver, so never took the branch). Any test that must print a line AND
pass needs a `FAIL_REGULAR_EXPRESSION` beside it; running the test binary directly is the check.
- **A C ABI cannot give a function and a struct one name** (`FlNvDriverProfile` the export, `FlNvDriverProfileRead` the
struct): C puts typedefs and functions in one namespace, and MSVC's error names neither clearly.
- **The driver profile is a configuration.** `sessions.driver_profile` says what the NVIDIA App set; it never feeds
the upscaler ladder or the factor. The bridge has no DRS writer, and a PR that adds one is a different product.
- **Present-to-present is not a frame time on a frame-generation title.** DLSS FG submits its generated frames in a
burst (measured: half a millisecond apart on the owner's Onimusha capture); anything over `ft_app` — lows, median,
σ, stutter, the charts' default line — is application frame to application frame (`FrameTimeSeries.ApplicationFrames`,
`SessionSeriesLoader.ApplicationFrames`).
- **A gap is neither a frame time nor time** (beta.8): `FrameTimeSeries.MeasuredSeconds` and `FgWindow.Seconds` leave
out every interval a gap sat in. A pause is a gap (`CaptureSession.MarkResume`); do not mark one any other way.
- **Reading the owner's ledger for evidence: copy it (`ledger.db` + `-wal`) to the scratchpad and read the copy** with
plain SQLite — never a FrameLedger binary against the data folder. `capture_tier` is an integer (1 = hooked); the
frame flags are Generated = 1, Gap = 4.
- **A view model that loads in its constructor raises its events to nobody** until the page subscribes; a page must
draw what the view model already holds when it is made (the Trend tab was blank on every first open).
- **`Axes.DateTimeTicksBottom()` replaces the bottom axis**: call it before the theme and the label, or both are lost.
- **A local property value outranks a style trigger** (Compare's best cell was never accent-coloured): defaults a
trigger may change go in the Style as Setters.
- **`ui.fps_decimals` is process-wide state** (`FpsDecimals`): a test that moves it belongs to `StringsCultureCollection`
with every test that reads FPS text, and restores it.
- **A status is not a policy input.** Splitting End task (exit 1) out of `crashed` would have loosened the crash
auto-disable had the policy kept reading the status alone; it takes the exit code too. Check every reader of a value
whose meaning you narrow.
- **The gate's own refusals carry a label in the family slot** (`not enabled`, `no consent`, `kill switch`, `previously
blocked`, `HookedCaptureGate`), so "has a family" does not mean "is a finding" — `IsFindingAboutTheGame` is the test.
- **`add_strings.py` replaced an existing key in place** (`Exit_Normal`, the Sessions grid's word) — it now refuses
without `--replace`; diff the resx for `-.*<value>` before committing new strings.
- **A 32-bit refusal is not a block.** `ExecutableNotX64` writes nothing — no `hook_blocked_reason`, no stamp — so a
64-bit build of the same game under *Change executable* can be hooked; the sweep's turn-off uses
`hook_autodisabled_reason`, which the page does not offer to undo while the file is still 32-bit.
## 2026-09-26 — the beta.9 train: the user-mode exception (D33)
*Status is `CHANGELOG.md` `[0.1.0-beta.9]`; this is what no other file carries. The approved plan
is four PRs: PR-1 the guard's tolerance and the Overlay's channel, PR-2 the Agent (eligibility, gate, records, schema
0014, IPC), PR-3 the App, strings, docs and legal text, PR-4 the release.*
**Decision (D33, owner, 2026-09-26, asked with rule 2 and D22 quoted back).** The beta.8 sweep turned hooking off for
GIRLS' FRONTLINE 2: EXILIUM (NetEase Yidun, `AntiCheatFile NEP2.dll`, a documented and unmeasured rule) after it had
been measured hooked; the owner asked for an exception list for user-mode anti-cheat games measured at Tier 1 before.
Chosen, all four options as recommended: **evidence-bound, per game** (a Settings option off by default, then the user
ticks each eligible game); **≥ 2 successful Tier-1 sessions**; **Aniimo stays blocked** (it unpacks `NEPKernel.sys` beside
`NEP2.dll` — the D30 `.sys` rule is never excepted); **the legal text changes** (Disclaimer §2A 2.7, EULA 1.3, the
accuracy block, SECURITY.md, FR-2.3; Privacy stays 2.4). Eligibility, what is never excepted and every lapse are in
`19_SAFETY` §The user-mode exception; the rule-2 amendment is in CLAUDE.md.
**Evidence it rests on (read from a COPY of the owner's ledger and their logs, 2026-09-26).** GF2: three normal Tier-1
sessions under the current entry (474,143 frames; three more from 2026-09-21 went with a removed entry), no `.sys` in
its tree. Aniimo: one Tier-1 session stored `crashed` (End task before beta.8, no exit code kept). A randomly named
kernel driver (`lyoxztfx.sys`) was installed on 2026-09-21 at 15:38 and is gone now, service and file, by something
the logs cannot name — the residual the disclosure states: a driver outside the game folder that no rule names is
invisible to every check.
**Traps met on the way:**
- **The ring cannot carry anything the Overlay needs before its detour is armed** — the Overlay creates it. Hence the
separate `Local\FrameLedger.Tolerate.<pid>` mapping the Agent creates BEFORE the injection (`fl_tolerance.h`).
- **A tolerant scan must keep scanning.** Every sink that used to stop at the first hit returns `true` on a tolerated
one, or a second family / a `.sys` further in would pass: the same load-order fail-open §S22(b) closed for the
exemption.
- **A prefix value of a user-mode family can match a `.sys`**; the tolerant file sink refuses any `.sys` itself.
- **CA2101 rejects `[MarshalAs(LPUTF8Str)] string`** on a P/Invoke; the tolerance crosses as NUL-terminated UTF-8
`byte[]`, the shape `FlGuardCheckRules` already used.
- **The Vulkan branch evaluates strictly**: the layer's self-scan goes inert on any anti-cheat module, so an exception
there could only buy a session that measures nothing.
- **An elevated Agent's default DACL omits the user** (`PipeAccessControl`'s remarks): a tolerance mapping created with
it could not be opened by the Overlay in an unelevated game, and the exception would fail as the Overlay's own stop.
`OverlayToleranceChannel` states `O:<user>D:P(A;;GR;;;<user>)`; a test proves the user can read it and nobody can
open it to write.
- **`hook_enabled` can be 1 on a blocked row now** — only because an exception once applied. `CaptureSession.RunAsync`
therefore treats a blocked row whose exception does not apply right now as hooking-off BEFORE the resolver opens
anything, or the option off would reopen the Borderless-Gaming problem of 2026-09-22.
- **The store applies the eligibility rule itself** (`GrantAntiCheatExceptionAsync` answers `NotEligible`), and the
grant and the eligibility are bound in SQL to the block text they were reached about: a block rewritten between the
read and the write leaves the row alone. SQLite evaluates every `SET` from the old row, which is what lets
`ChangeExecutableAsync`'s `CASE WHEN ac_exception_at IS NOT NULL` record the end of the grant it clears.
- **CA1711 rejects a type whose name ends in `Exception`**: the rules class is `UserModeExceptionRules`, the reasons
`UserModeExceptionLapse`.
## 2026-09-27 — the beta.10 train: the display mode, the admin mode, the Unreal Engine version
*Status is `CHANGELOG.md` `[0.1.0-beta.10]`; this is what no other file carries. The approved plan was six PRs:
PR-1 the Unreal version (schema 0015), PR-2 the Overlay's display region (shared-memory layout 4), PR-3 the display mode
in the Agent and the App (schema 0016), PR-4 the admin mode, PR-5 docs, legal text and the tested-games list, PR-6 the
release.*
**Decisions (owner, 2026-09-27, asked before the plan — do not re-ask):**
- **D34 — the admin mode asks Windows at EVERY Agent start.** The UAC prompt appears whenever the Agent starts with
`capture.run_elevated` on — owned by the App's window when the App starts it, flashing on the taskbar when the logon
task does. No "highest privileges" task, no service, no silent path. Games an elevated Agent starts get the desktop
shell's token. The elevated Agent is started for one user (`--for-user <SID>`) and exits 11 as any other account.
- **D35 — the tested-games list comes from a COPY of the owner's ledger** (scratchpad, Python `sqlite3`; never a
FrameLedger binary against the data folder) plus the repository's own evidence, and **the owner reviews it before it
is committed** — the repository is public.
- **D36 — legal text changes where it would become false** (Privacy 2.5, Disclaimer 2.8; EULA stays 1.3), **and
`LIMITATIONS.md` exists**: a user-facing list of what the WHOLE software cannot do, at the repository root and in the
App under Help ▸ Limitations — not one of FR-11's accepted documents (the Legal Gate records an acceptance per
document, and this is information, not terms).
- **D37 — each PR merges when its CI is green**, then the release PR and the GPG-signed tag.
**What was measured before it was written:**
- **Unreal versions, ten installed titles, read-only** (`spike-notes` §15): eight read (4.26.1 … 5.5.4), two honestly
none (Cronos demo, Rune Factory). Black Myth: Wukong's executable is protected (`.rdata` empty) and its build name sits
in `.code` — the whole-file fallback read it in 7.5 s from the owner's USB drive.
- **The display region's cost** (hook-harness `--probe-frames`, WARP): `GetFullscreenState` 12.6–13.1 ns, `GetDesc`
13.6–14.5 ns per call, at most twice a second per swap chain.
**Traps met on the way:**
- **A test run reseeds the rules file in the REAL data folder** (`RulesSeeder` in the integration tests writes
`%LOCALAPPDATA%\FrameLedger\rules`). PR-1's rules `2026.09.6` carry an extractor type (`unreal_build`) the installed
beta.9 cannot parse: its detection sweep says "rules unusable" until that Agent restarts — its seeder sees a file it
wrote itself (the marker's hash) and puts its own back — or beta.10 is installed. The guard reads the same file and is
unaffected (it ignores version extractors). Worth a scratch rules folder for the tests one day.
- **`DXGI_SWAP_EFFECT_DISCARD` is 0** — region 4 stores the effect plus one, the vendor-zero trap.
- **A minimised game presents only what the hook drops** (occlusion probes): a region-4 sample older than 2 s says
nothing about exclusivity now; the Agent keeps its window and drops its exclusive bits.
- **The Agent is DPI-unaware**: Windows scales another process's window coordinates for it. The window reader switches
its thread to per-monitor-aware (V2) for the calls and back.
- **A Tier-2 session never reaches the aggregator** — display columns live on the recorder's skeleton, or a Tier-2 row
would carry none.
- **`SessionRowColumns` is generated by a script that is not in the repository** — edit it by hand, by name.
- **`CreateProcessWithTokenW` needs `SeImpersonatePrivilege`**, which an unelevated (filtered) token does not hold: the
shell-token start is testable only on the elevated CI runner, and a runner with UAC off has an elevated shell — so the
test compares the child's elevation with the SHELL's, never with "unelevated".
- **An elevated token's default DACL omits the user** (again): the ledger's migration lock is now a `SharedMutex` with a
stated descriptor; the instance lock and the elevation marker are only probed, and a refused probe reads as held.
- **`CA2025` flags a disposable handed to an un-awaited task** even when ownership moves to it; the launcher says so in
a suppression with its reason, or splits the method so the analyzer can see it.
- **Heredocs mangle backslashes and `\a`** (`D:\another` became `D:<BEL>nother` in a test). Patch scripts are written
with the Write tool and run by path; a scan for control characters before the gate catches the rest.
**Owner-only, added to the list below:** item 7.
## Owner-only — no PR can close these
1. **§S23-2 — branch protection.** `Rules / validate` is not a required status check on
@@ -1435,8 +1766,9 @@ Any proposal to "make the bypass work on EAC titles" is rule 3, not rule 2 — r
2026-09-03 (P4) and 2026-09-04 (P1); done.** What is still owed here is the **quality
preset** on a title that chains `sl::DLSSOptions` — Alan Wake 2 is the candidate — and
the DLSS-G identity on a title where `kFeatureDLSS_G` is evaluated, if one exists.
3. **Which titles** go in `blockedExecutables` — a product decision with false-refusal
consequences. The list ships empty until it is taken.
3. ~~**Which titles** go in `blockedExecutables` — a product decision with false-refusal
consequences. The list ships empty until it is taken.~~ **Taken 2026-09-25 (D30):** per-title
lists by Steam id and executable name, seeded and floored (§2026-09-25 — the beta.8 train).
4. **§H7's confirmation against the overlays actually resident on the dev machine.** The
compare-and-restore path is proven against a fixture (ctest `fl_unhook_inline`); §H7 still
says the six real overlays are *"worth doing once the Overlay has real hooks"*, and it has
@@ -1444,6 +1776,23 @@ Any proposal to "make the bypass work on EAC titles" is rule 3, not rule 2 — r
5. **Re-ratify §S18 blocker 3 and §S27's basis** once P2's PR-C/PR-F make the Agent the shipped
injecting entry point (§P2, decision D4). The PRs restate both entries; whether the
restatement stands is the owner's.
6. ~~**D33's first real use (beta.9).**~~ **Done by 2026-09-27, read from a copy of the owner's ledger:** three normal
hooked sessions of GIRLS' FRONTLINE 2 under the exception (NetEase Yidun) on 2026-09-26 and 09-27, the longest
3 h 9 min; the `ja` review below is still owed. *(The item as written:)* Turn the option on; GIRLS' FRONTLINE 2 should be listed eligible (NetEase
Yidun, `NEP2.dll`, three sessions); make the exception, turn hooking on and play one session: hooked, marked
*Hooked · exception*, not stopped by the 30 s re-scan or by the Overlay when `NEP2.dll` loads. Aniimo should read
*not eligible* with its `NEPKernel.sys`; the option off makes the next session Tier 2 with the exception kept. And
the `ja` text of `Safety_Exception_*`, which ships as English until a reviewer signs.
7. **beta.10 on real hardware.** (a) **The display mode:** one DXGI game taken through exclusive full-screen →
borderless → windowed in one session — the summary's shares, the Sessions column, the Trend's three share metrics —
with a note of what the game's own menu called each mode. (b) **The admin mode:** turn it on → the disclosure → the
UAC prompt → Settings says *Running elevated*; decline it → *the administrator prompt was declined*; sign out and in
with the logon task → the prompt waits on the taskbar and one Agent results; start a game from FrameLedger while
elevated → Task Manager's *Elevated* column says *No*; a game that runs as administrator → hooked; the CPU temperature
with PawnIO (closes §M10 if it reads). (c) **The Unreal Engine version** on each Unreal game's page. (d) The Legal
Gate shows Privacy 2.5 and Disclaimer 2.8 once. (e) The `ja` text of `Safety_AdminMode_*`, English until reviewed.
(f) `docs/LIST_GAME_TESTED.md` — reviewed and approved by the owner before it was committed (D35, 2026-09-27);
keep it current as games are run.
**Answered 2026-08-05, do not re-ask:** remove `gameguard` and keep `guard` (approved
over a red `Rules` gate, with the reasoning recorded in the merge commit); vendor NVAPI
+71
View File
@@ -0,0 +1,71 @@
# Games FrameLedger has been run with
*As of 2026-09-27 (0.1.0-beta.10). Built from a copy of the developer's own FrameLedger database and the repository's
measurement notes, and reviewed by the project's owner before it was published. It lists what happened on one machine;
it promises nothing about any other.*
**The machine.** Every row below was run on one PC: an NVIDIA GeForce RTX 5080 (the only graphics card), an Intel Core
i7-14700KF, 32 GB of DDR5, Windows 11 (Insider builds 26300 → 29648) and a 2560×1440, 240 Hz monitor. **No AMD or Intel
graphics card and no second machine has been tested**, and **no real Vulkan or OpenGL game has been measured** — every
measurement below is Direct3D 11 or 12. What the tiers mean and what FrameLedger cannot do: [LIMITATIONS.md](../LIMITATIONS.md).
**Two periods.** From 2026-08-03 to 2026-09-06 the games were measured with the developer's capture tool, one run at a
time against the game's own settings menu (reports in [spike-notes.md](spike-notes.md)). From 2026-09-16 the shipped
app and agent recorded them as a user would; the database holds the sessions from 2026-09-22 on — earlier ones went
with the 2026-09-16 recovery and with library entries removed since.
## Measured — hooked (Tier 1)
| Game | Engine | API | What was measured | When | Evidence |
|---|---|---|---|---|---|
| Cyberpunk 2077 | — | D3D12 | DLSS Balanced 1485×835 → 2560×1440, exact against its settings file; DLSS Frame Generation off ×1.00, ×3 (61.4 → 183.5 FPS), ×4 (58.7 → 234.1); FSR 3 + FSR frame generation ×2 (74.3 → 148.6); ray tracing *Yes* with path tracing on and *No* with it off, as set | 2026-08-15 → 09-05, about 25 runs | [spike-notes §8, §9, §11](spike-notes.md) |
| Dying Light: The Beast | — | D3D12 | DLSS Frame Generation ×4: Native 70.5 → Displayed 282.1 FPS, counted through DXGI; FSR + FSR frame generation ×2 (70.5 → 140.9); ray tracing *Yes* | 2026-09-04 → 09-06 | [spike-notes §9](spike-notes.md), [03_METRICS §Frame Generation](03_METRICS.md) |
| Hell Is Us | Unreal Engine 5.5.4 | D3D12 | DLSS Frame Generation ×4 (76.5 → 306.2); DLSS shown as *driver-reported* (it bypasses Streamline); FSR + FSR frame generation ×2 (85.7 → 171.4); XeSS frame generation shown as Presented FPS only; ray tracing *No* | 2026-09-03 → 09-16 | [spike-notes §8, §9](spike-notes.md) |
| Black Myth: Wukong | Unreal Engine 5.0.0 | D3D12 | DLSS Frame Generation ×4 (55.4 → 221.5); ray tracing *Yes* (16.2 % of frames in the app's session); a session that changed state showed its steady state (×4.1) instead of an average | 2026-08-20 → 09-16 | [spike-notes §9, §14](spike-notes.md) |
| Clair Obscur: Expedition 33 | Unreal Engine 5.4.4 | D3D12 | DLSS + Frame Generation ×4 (54.9 → 218.4) and ×2 (76.0 → 149.8); frame generation off read *none*, with DXGI agreeing; ray tracing *No* | 2026-09-04 → 09-06 | [spike-notes §9](spike-notes.md) |
| Rune Factory: Guardians of Azuma | Unreal Engine (version not in the executable) | D3D12 | DLSS Frame Generation ×4 (128.9 → 513.0); FSR frame generation compiled into the game counted ×2 but not named; ray tracing *No* (the game has none) | 2026-08-20 → 09-06 | [spike-notes §9](spike-notes.md) |
| Kingdom Come: Deliverance II | — | D3D12 | FSR (3.1 or 4) at 1505×847 → 2560×1440; frame generation *none* (the game ships none); ray tracing *No* | 2026-09-04 | [spike-notes §9](spike-notes.md) |
| Lies of P | Unreal Engine 4.27.2 | D3D12 | FSR 3 at 1506×848 → 2560×1440 with FSR frame generation ×2.04 (57.1 → 116.4) in the app; frame generation off read *none*; DLSS shown as *driver-reported*; ray tracing *No* | 2026-08-03 → 09-16 | [spike-notes §7, §9, §14](spike-notes.md) |
| Onimusha: Way of the Sword (demo) | RE Engine | D3D12 | DLSS + DLSS Frame Generation: ×3.67 and ×3.93 with the capture tool, ×4.00 in the app's steady state (60 → 240 FPS), ×3.0 (60 → 180) in the app on 2026-09-22; ray tracing *Yes* | 2026-09-05 → 09-22 | [spike-notes §9, §14](spike-notes.md), database |
| Cronos: The New Dawn (demo) | Unreal Engine (version not in the executable) | D3D12 | DLSS with frame generation off (105 FPS, *none*); on ×2 (86.8 → 172.7), DLSS Frame Generation named; ray tracing *Yes* | 2026-09-06 → 09-16 | [spike-notes §9, §14](spike-notes.md) |
| Alan Wake 2 | — | D3D12 | Path tracing Ultra with DLSS and Ray Reconstruction: ray tracing *Yes* (96.8 % of frames), frame generation read ×1.00 (the game did not apply the setting that run). On 2026-09-04: DLSS with ray tracing *Yes* (99 % of frames), 92.5 FPS, frame generation *none* by count; then ray tracing off (*No*), DLSS, Presented 114.5 FPS. The quality preset was never read | 2026-08-04 → 09-04 | [spike-notes §8](spike-notes.md), run reports |
| SILENT HILL 2 | Unreal Engine 5.1 | D3D12 | DLSS Frame Generation identified, frames not counted (Presented 78 FPS); DLSS *driver-reported*; ray tracing *Yes* | 2026-09-25 | database |
| DARK SOULS III | FromSoftware | D3D11 | Presented 59.8 FPS; no upscaler, frame generation or ray tracing loaded | 2026-09-03 | [spike-notes §9](spike-notes.md) |
| Sekiro: Shadows Die Twice | FromSoftware | D3D11 | Presented 60 FPS (the game's cap), two sessions of 15 min and 2 h 18 min | 2026-09-26 | database |
| Yu-Gi-Oh! Master Duel | Unity 6000.0 | D3D11 | Presented 239 FPS across six sessions (up to 5 h 25 min) | 2026-09-22 → 09-25 | database |
| GIRLS' FRONTLINE 2: EXILIUM | Unity 2019.4 | D3D11 | Presented 53–101 FPS; the last three sessions under the user-mode anti-cheat exception (NetEase Yidun), one of them 3 h 9 min, all ended normally | 2026-09-21 → 09-27 | database, [HANDOFF](HANDOFF.md) |
| Aniimo | Unity 2022.3 | D3D12 | DLSS at 1707×960 → 2560×1440, frame generation *none* (×1.00, 205 FPS), ray tracing *No* — then blocked (below) | 2026-09-22 | database |
| AbyssMemory | Unreal Engine 4.26.1 | D3D11 | Presented 55 FPS, one short session | 2026-09-22 | database |
| Umamusume: Pretty Derby | Unity 2022.3 | D3D11 | Presented 37 FPS, one session | 2026-09-27 | database |
| 恋しかるべき (KOISHIKARUBEKI) | Unity 6000.3 | D3D11 | Presented 59.6 FPS | 2026-09-03 | [spike-notes §9](spike-notes.md) |
| Flower in Us | RPG Maker MV/MZ (NW.js) | D3D11 | Presented 59.8 FPS over three swap chains, after two refusals that found the game's browser process ambiguous (fixed) | 2026-09-03 → 09-04 | [spike-notes §9](spike-notes.md) |
| UMIGARI | Unreal Engine 5.5.4 | D3D12 | Presented 95–97 FPS, frame generation *none*, ray tracing *No* | 2026-09-05 → 09-06 | run reports only |
## Recorded without measurement (Tier 2)
| Game | Why nothing was measured | When | Evidence |
|---|---|---|---|
| HELLO, HELLO WORLD! | A 32-bit game (RPG Maker MV): refused by the guard once, and two sessions with hooking switched off — each recorded with its duration and sensors | 2026-09-23 | database |
| Umamusume: Pretty Derby | Three sessions played with hooking switched off for the game | 2026-09-27 | database |
| Sekiro: Shadows Die Twice | One session played with hooking switched off | 2026-09-25 | database |
| GIRLS' FRONTLINE 2: EXILIUM | One session whose process Windows would not let FrameLedger open, and two recovered after the agent itself stopped mid-session (*interrupted*) | 2026-09-22 → 09-23 | database |
## Refused by the anti-cheat guard
| Game | What was found | When | Evidence |
|---|---|---|---|
| ELDEN RING | Easy Anti-Cheat: its folder, and a process Windows would not let FrameLedger open. Nothing was ever injected; eight sessions recorded without measurement | 2026-09-21 → 09-27 | [CHANGELOG](../CHANGELOG.md), database |
| GIRLS' FRONTLINE 2: EXILIUM | NetEase Yidun (`NEP2.dll`, user mode) — turned hooking off after it had been measured; measured again since 2026-09-26 under the user-mode exception its owner made | 2026-09-25 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
| Aniimo | NetEase Yidun with a kernel driver (`NEPKernel.sys`) in the game's folder — never eligible for an exception | 2026-09-25 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
| Goose Goose Duck | Easy Anti-Cheat's service running, and its folder | 2026-08-04 | [spike-notes §13](spike-notes.md) |
| Neverness To Everness | Anti-Cheat Expert's kernel driver in the game's folder | 2026-08-04 | [spike-notes §13](spike-notes.md) |
| Counter-Strike 2 | Valve Anti-Cheat — refused by FrameLedger's title list since beta.8. On 2026-08-04 the checks alone allowed it (VAC is invisible to them); nothing was injected | 2026-08-04, beta.8 | [spike-notes §13](spike-notes.md), [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
Also refused before any injection: **Deadly Heart Gambit** — a 32-bit game (2026-08-03).
## Engine version read from the executable only
The Unreal Engine version (beta.10) was checked against ten installed Unreal games without running them: Hell Is Us
5.5.4, Black Myth: Wukong 5.0.0, Clair Obscur: Expedition 33 5.4.4, Lies of P 4.27.2, SILENT HILL 2 5.1, UMIGARI 5.5.4,
AbyssMemory 4.26.1, **Martha Is Dead 4.27.0**; Cronos (demo) and Rune Factory name no version in their executables and
read *not found*. ([spike-notes §15](spike-notes.md), [05_DETECTION §Engine version](05_DETECTION.md))
+21 -1
View File
@@ -2489,7 +2489,9 @@ FrameLedger.Agent --console sessions --last 1
```
**The row half is read — 2026-09-16, the shipped Agent, not the console.** The owner ran the App with its `--serve`
Agent for an afternoon (18 hooked sessions, attach mode, `late_attach = 1`, every one watcher-driven from a Steam
Agent for an afternoon (18 hooked sessions — **count note, 2026-09-27:** `CHANGELOG` 2026-09-17 says *all nine hooked
sessions of 2026-09-16*; neither count was re-made when the other was written, and the ledger as it stands today holds no
session from that day, so the discrepancy is recorded rather than resolved — attach mode, `late_attach = 1`, every one watcher-driven from a Steam
launch rather than the `launch` verb above — a Steam title started from its Shipping executable relaunches through
Steam, so the console recipe is the wrong vehicle for a Steam library and the product's own path is the right one).
`sessions.id = 10`, **Lies of P**, 16:11, 147 s, `d3d12`, 16,221 frames, `guard_ticks_published = 5`, Overlay
@@ -2564,3 +2566,21 @@ inspects module sizes is the way to fill it.
Unchanged by P2 and repeated here because it is the other measurement no PR can close: the
compare-and-restore path is proven against a fixture (`ctest fl_unhook_inline`), and §H7 still asks
for one capture with each of the six overlays actually resident on the dev machine.
## 15 · Unreal Engine versions in shipping executables *(2026-09-27, beta.10)*
Measured read-only on the owner's machine (i7-14700KF, RTX 5080, Windows 11 29648): every `*-Win64-Shipping.exe`
under `D:\SteamLibrary\steamapps\common` (a USB drive), before the extractor was written, then again through the
shipped `UnrealBuildReader` once it was. Nothing was copied or written; the numbers are in `05_DETECTION` §Engine version
(the table is not repeated here).
- **Numeric file version** (`VS_FIXEDFILEINFO`): the engine's MAJOR.MINOR.PATCH in seven of ten; a studio's own in three
(Cronos 1.2.0.0, Rune Factory 1.0.3.0, SILENT HILL 2 1.0.0.5). The version *strings* are empty in six of ten.
- **Branch name** (UTF-16 `++UE4+Release-M.m` / `++UE5+Release-M.m`): present in five — in `.rdata` in four (15–30 MB
sections), and 290 MB into `.code` in Black Myth: Wukong, whose protected executable has an 8 KB `.rdata`; in UMIGARI
also in the version strings. Absent in five (Hell Is Us carries `UE5-CL-0`: a renamed branch).
- **The shipped reader, same ten files:** every version as tabled — 8 read, 2 honestly none — in 16 ms to 1.1 s each and
7.5 s for Black Myth (the whole-file fallback, stopping at the first chunk that names a release line). A first pass
that scanned only a PE's `.rdata` read Black Myth as `5.0.0` from the file version alone; the 1 MiB `.rdata` floor
(`UnrealBuildReader.MinRdataBytes`) is what moved it to the stronger rung.
- No UE3 title is installed; the rule does not detect UE3 at all.
+28 -14
View File
@@ -11,12 +11,12 @@
that changes what FrameLedger.Overlay or the capture host does; date the change.
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-09-21.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.4`** (2026-09-21), an unsigned installer built from that tag with its
> ⚠ **What FrameLedger actually measures today — 2026-09-28.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.10`** (2026-09-28), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs, injects only into games you enabled and only past the safety guard (or,
> for a game whose guard bypass you turned on yourself, past your own acceptance of that risk), and
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> and only past the safety guard, and
> stores sessions in a local database. What that path measures:
>
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
@@ -29,8 +29,10 @@
> NVIDIA Streamline (with Ray Reconstruction Yes/No), and FSR through AMD's shipped FidelityFX DLLs:
> named FSR 3 from the older DLLs, and FSR without a version from the newer ones, which host both
> FSR 3.1 and FSR 4. FSR 2, and FSR shipped any other way, is not identified. For DLSS titles that
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session, labelled
> *driver-reported*; the app does not display it yet. Intel XeSS is **not** read (its SDK licence
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session and shown
> as *DLSS (driver-reported)*. The NVIDIA driver's profile for the game — the DLSS and frame-generation
> overrides the NVIDIA App sets — is read, never changed, and shown as the driver's settings beside what
> was measured. Intel XeSS is **not** read (its SDK licence
> forbids it), and neither is an upscaler compiled into the game: those read `N/A`, or "Unknown
> upscaler" when another vendor's hook ran in the game. Vulkan and OpenGL titles read `N/A`.
> - **Quality preset:** not reported on any title measured. The one route this software may use — the
@@ -51,9 +53,18 @@
> FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled into the game)
> is shown only as active with the technology not identified, and is never named. Where a technology is
> named but its frames could not be counted, or frame generation is not measured, the software shows
> **Presented FPS** with a note on what it may include — never a Native figure.
> **Presented FPS** with a note on what it may include — never a Native figure. Where generated frames
> were counted, the lows, median and stutter are taken over application frames only.
> - **Ray tracing:** Yes/No measured on Direct3D 12 from ray-dispatch and acceleration-structure-build
> calls; the technique and path tracing are `N/A`, and so is ray tracing on other APIs.
> - **Display mode:** how each game's window was shown — exclusive full-screen, borderless, windowed or
> minimised — as a share of the session, with the window's size and the monitor's, in every session.
> Exclusive full-screen is known only for Direct3D titles FrameLedger injects into, from the game's own
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
> files state.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
@@ -61,17 +72,20 @@
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
> administrator with PawnIO installed, and that reading has not yet been checked on real hardware;
> everywhere else it is `N/A`.
> administrator — an option, off by default, for which Windows asks at every start of the Agent — with
> PawnIO installed, and that reading has not yet been checked on real hardware; everywhere else it is `N/A`.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
> goes passthrough. A global switch in Settings turns all hooking off, and a running capture stops at
> its next check; it can only refuse, never permit. **There is one override, and only one:** a per-game
> "bypass the anti-cheat guard" switch, off by default, that you can turn on only by accepting its own
> warning (a tick and a typed word). With it on, FrameLedger injects into that game even where the
> checks find anti-cheat, the 30 s re-check no longer stops the capture for that finding, and every
> session started that way is marked. It never changes HOW FrameLedger injects: nothing is hidden.
> its next check; it can only refuse, never permit. **There is no override.** A finding about a game — anti-cheat
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
> runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
+67 -40
View File
@@ -1,6 +1,6 @@
# FrameLedger — Disclaimer
**Version:** 2.4 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.8 · **Effective:** {{RELEASE_DATE}}
> **How this document is kept true.** The statement of what FrameLedger measures (§4) is `legal/ACCURACY.md`,
> embedded here and in `README.md` and bound to its source by `tools/accuracy-check.ps1`, which fails the build when a
@@ -11,7 +11,9 @@
## 0. This is pre-release (beta) software
**FrameLedger is a beta.** Every build published so far is a pre-release. It has been tested on a small number of
machines and games, and **it certainly still contains bugs — some of them not yet known to anyone.** Features can
machines and games — the games are listed in `docs/LIST_GAME_TESTED.md` in the project's repository, and what the software
cannot do is listed in `LIMITATIONS.md` there and in the app under Help ▸ Limitations — and **it certainly still contains
bugs — some of them not yet known to anyone.** Features can
change or disappear between builds, recorded data can turn out to be wrong, and an update can require your data to be
migrated.
@@ -53,7 +55,7 @@ Install it somewhere only you can write to, and verify the published SHA-256 che
FrameLedger is designed to reduce that risk substantially:
- Injection is **off by default** and must be enabled by you **per game**.
- Before injecting, and every 30 seconds afterwards, FrameLedger scans for known anti-cheat and anti-tamper components. **If it finds one, it refuses to inject; if a session is already running, it stops at the next scan.** No setting turns this off globally; the one exception is the per-game bypass described in §2A, which only you can turn on, one game at a time. Because the scan runs every 30 seconds rather than continuously, anti-cheat that loads mid-session may be present for **up to 30 seconds** before FrameLedger detects it and stops.
- Before injecting, and every 30 seconds afterwards, FrameLedger scans for known anti-cheat and anti-tamper components. **If it finds one, it refuses to inject; if a session is already running, it stops at the next scan.** No setting turns this off, globally or per game; the one exception you can make yourself, per game, still runs every check and is described in §2A. Because the scan runs every 30 seconds rather than continuously, anti-cheat that loads mid-session may be present for **up to 30 seconds** before FrameLedger detects it and stops.
**And there is a second, longer window you should know about.** The part of FrameLedger running inside the game also stops on its own if it loses contact with the part doing the scanning — because a scanner that has stopped cannot protect you. It waits **65 seconds** before concluding that contact is lost, so that one delayed scan on a busy machine does not end your session. In the worst case those windows combine: if the scanner stops at the moment anti-cheat appears, the component inside the game may keep running for up to **65 seconds** afterwards. That number is 65 and not 30, and this document says so rather than leaving the 30 above to imply it.
@@ -79,33 +81,29 @@ FrameLedger is designed to reduce that risk substantially:
**FrameLedger is intended for offline and single-player play. If you enable injection for a game with any online or competitive component, you do so entirely at your own risk and are solely responsible for the consequences, including compliance with that game's terms of service.**
## 2A. The guard bypass — entirely at your own risk
## 2A. There is no way past the guard — and one narrow exception you can make yourself
Since version 0.1.0-beta.3 each game's page has a switch labelled **"Bypass the anti-cheat guard (at your own risk)"**.
It is **off by default**, it applies to that one game only, and there is no way to turn it on for all games at once.
Versions 0.1.0-beta.3 and 0.1.0-beta.4 offered a per-game switch to overrule the guard. **It has been removed.** If
FrameLedger finds anti-cheat or anti-tamper software in a game — before it injects, when a session starts, or during a
session — it refuses, turns hooking off for that game, and says so on the game's page. There is no setting, per game or
global, that overrules that. Sessions recorded under the earlier switch stay in your database, marked as such in their
notes.
Turning it on tells FrameLedger to inject into that game **even where its checks find anti-cheat or anti-tamper
software** — that is, in exactly the situation §2 says can get an account banned. The checks still run and what they
found is still recorded; they simply no longer stop the injection or the running session for that game. FrameLedger
still does nothing to hide itself: it loads under its real name and is fully visible to the anti-cheat.
**Since 0.1.0-beta.9 there is one exception, and it is not a way past the guard.** A Settings option, off unless you
turn it on, lets you make an exception — one game at a time, after a disclosure you must accept — for a game whose only
finding is a single anti-cheat that works entirely in user mode (no kernel driver, no service, and no driver file
anywhere in the game's folder), that is on no list of titles FrameLedger refuses, and that FrameLedger has already
measured successfully at least twice. Under it the guard still runs every check, before injecting and every 30
seconds, and still refuses anything else it finds; the exception ends by itself when something new is found, when a
session under it crashes or is stopped for safety, or when the game is updated, and turning the option off suspends
it. Sessions recorded under it are marked with the anti-cheat they ran beside.
**It does not make FrameLedger work everywhere.** Several anti-cheat systems protect the game's process so that no
other program can open it. FrameLedger cannot measure such a game with or without the bypass, it says so when that
happens, and it will never try to get around another product's protection. Turning the bypass on for such a game
gains you nothing and still marks your intent to load software into it.
**It exists because users asked for it, and it carries exactly the risk this document describes.** That anti-cheat
may still detect FrameLedger in the game and warn, block or permanently ban your account — possibly days later — and
FrameLedger cannot know whether it did. Earlier sessions that went well are no promise about the next one. **Do not
use it with a game you play online or competitively unless you accept losing that account;** the developer cannot
reverse a ban.
You can turn it on only by accepting a warning inside the application, by **both** ticking a statement and typing a
word. **BY TURNING IT ON YOU ACCEPT THE ENTIRE RISK YOURSELF.** The developer and the contributors accept **no
responsibility and no liability whatsoever** for anything that happens on your side as a result — including, without
limitation, an account that is flagged, suspended or **permanently banned** (in that game or in others from the same
publisher or platform), purchases, progress or data that are lost, a game that crashes or will not start, or any
dispute with a publisher or platform under their terms of service. Nobody can undo a ban for you.
Every session started with the bypass on is permanently marked as such in the application and in every export,
together with what the checks found. The bypass turns itself off when you turn hooking off for the game or when the
game's executable changes.
**If you are not certain, leave it off.**
## 3. Stability
@@ -116,12 +114,12 @@ Software running inside another process can, in principle, destabilize it. Frame
Frame timing is derived from high-resolution timestamps taken at the moment the game presents each frame; upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs. This is substantially more accurate than inferring settings from files on disk, but **no measurement is guaranteed to be exact**:
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-09-21.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.4`** (2026-09-21), an unsigned installer built from that tag with its
> ⚠ **What FrameLedger actually measures today — 2026-09-28.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.10`** (2026-09-28), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs, injects only into games you enabled and only past the safety guard (or,
> for a game whose guard bypass you turned on yourself, past your own acceptance of that risk), and
> game in the library runs (unless you switched its recording off), injects only into games you enabled
> and only past the safety guard, and
> stores sessions in a local database. What that path measures:
>
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
@@ -134,8 +132,10 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> NVIDIA Streamline (with Ray Reconstruction Yes/No), and FSR through AMD's shipped FidelityFX DLLs:
> named FSR 3 from the older DLLs, and FSR without a version from the newer ones, which host both
> FSR 3.1 and FSR 4. FSR 2, and FSR shipped any other way, is not identified. For DLSS titles that
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session, labelled
> *driver-reported*; the app does not display it yet. Intel XeSS is **not** read (its SDK licence
> bypass Streamline, the NVIDIA driver's own per-process record is stored with the session and shown
> as *DLSS (driver-reported)*. The NVIDIA driver's profile for the game — the DLSS and frame-generation
> overrides the NVIDIA App sets — is read, never changed, and shown as the driver's settings beside what
> was measured. Intel XeSS is **not** read (its SDK licence
> forbids it), and neither is an upscaler compiled into the game: those read `N/A`, or "Unknown
> upscaler" when another vendor's hook ran in the game. Vulkan and OpenGL titles read `N/A`.
> - **Quality preset:** not reported on any title measured. The one route this software may use — the
@@ -156,9 +156,18 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled into the game)
> is shown only as active with the technology not identified, and is never named. Where a technology is
> named but its frames could not be counted, or frame generation is not measured, the software shows
> **Presented FPS** with a note on what it may include — never a Native figure.
> **Presented FPS** with a note on what it may include — never a Native figure. Where generated frames
> were counted, the lows, median and stutter are taken over application frames only.
> - **Ray tracing:** Yes/No measured on Direct3D 12 from ray-dispatch and acceleration-structure-build
> calls; the technique and path tracing are `N/A`, and so is ray tracing on other APIs.
> - **Display mode:** how each game's window was shown — exclusive full-screen, borderless, windowed or
> minimised — as a share of the session, with the window's size and the monitor's, in every session.
> Exclusive full-screen is known only for Direct3D titles FrameLedger injects into, from the game's own
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
> files state.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
@@ -166,17 +175,20 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
> administrator with PawnIO installed, and that reading has not yet been checked on real hardware;
> everywhere else it is `N/A`.
> administrator — an option, off by default, for which Windows asks at every start of the Agent — with
> PawnIO installed, and that reading has not yet been checked on real hardware; everywhere else it is `N/A`.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
> goes passthrough. A global switch in Settings turns all hooking off, and a running capture stops at
> its next check; it can only refuse, never permit. **There is one override, and only one:** a per-game
> "bypass the anti-cheat guard" switch, off by default, that you can turn on only by accepting its own
> warning (a tick and a typed word). With it on, FrameLedger injects into that game even where the
> checks find anti-cheat, the 30 s re-check no longer stops the capture for that finding, and every
> session started that way is marked. It never changes HOW FrameLedger injects: nothing is hidden.
> its next check; it can only refuse, never permit. **There is no override.** A finding about a game — anti-cheat
> named in its process or in its folder (any kernel driver there counts), or the game on a title list by its
> store id or executable name — turns hooking off for that game, whether found by the Agent's own check of every
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
> runs every check under it and ends it on anything new; a ban remains possible.
>
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
@@ -208,6 +220,21 @@ be the difference between a game that runs and one that does not. Turn hooking o
FrameLedger reads GPU telemetry through vendor libraries that ship with your graphics driver. It **only reads** — it never changes clocks, fan curves, power limits, or any other hardware setting. Optional CPU-temperature support relies on the separate third-party **PawnIO** driver, which you install at your own discretion under its own license; some anti-cheat systems object to third-party kernel drivers regardless of what they are used for.
## 5A. Running the capture agent as administrator — optional, and your decision
Since 0.1.0-beta.10 a Settings option, off unless you turn it on, starts FrameLedger's capture agent as administrator.
**Windows asks you every time the agent starts** — also when you sign in — and the prompt names an unknown publisher,
because FrameLedger is not code-signed. It lets FrameLedger open and measure a game that itself runs as administrator,
and read the CPU temperature where PawnIO is installed. It changes nothing in the anti-cheat guard (§2, §2A), opens no
process that Windows or an anti-cheat driver protects, and never starts a game as administrator: games you start from
FrameLedger run with your standard rights.
**The risk is yours.** FrameLedger is installed in your user folder, which any program running under your Windows
account can change (§1). If such a program replaced FrameLedger's files, it would run with administrator rights the next
time you accept the prompt. Accept it only for a copy you installed from the project's GitHub Releases, and turn the
option on only if you trust everything that runs under your account. The developer is not responsible for what runs
under an administrator prompt you accept.
## 6. Third-party names
Windows and DirectX are trademarks of Microsoft Corporation. NVIDIA, DLSS, Reflex, NVAPI, AMD, FSR, Intel, XeSS, Vulkan, Steam, GOG, Epic Games, itch.io, Unity, Unreal Engine, and all other product names are trademarks of their respective owners. FrameLedger is an independent project and is **not affiliated with, endorsed by, or sponsored by** any of them, including any game publisher or anti-cheat vendor.
+2 -2
View File
@@ -1,6 +1,6 @@
# FrameLedger — End User License Agreement (EULA)
**Version:** 1.1 · **Effective:** {{RELEASE_DATE}}
**Version:** 1.3 · **Effective:** {{RELEASE_DATE}}
This End User License Agreement ("Agreement") applies to **FrameLedger** ("the Software"), developed and published by **poli0981** ("the Developer"), contactable at <contact@poli0981.dev> — see <https://poli0981.dev/> for other contact channels.
@@ -14,7 +14,7 @@ The Software records game performance data, hardware telemetry (temperatures, lo
## 2A. Code injection — your responsibility
To measure rendering settings accurately, the Software can load a component into a game process, **but only for games you have individually enabled**, after a consent prompt that explains the risk. The Software refuses to do so when it detects anti-cheat or anti-tamper software. It provides exactly one means to override that refusal: a per-game "bypass the anti-cheat guard" switch, off by default, which you can turn on only by accepting a separate in-application warning by two distinct acts (Disclaimer §2A). **If you turn it on, you do so entirely at your own risk, and the Developer accepts no responsibility or liability for any consequence**, including a suspended or permanently banned account.
To measure rendering settings accurately, the Software can load a component into a game process, **but only for games you have individually enabled**, after a consent prompt that explains the risk. The Software refuses to do so when it detects anti-cheat or anti-tamper software, turns hooking off for that game, and provides no means to override that refusal — except a narrow, per-game exception for anti-cheat that works entirely in user mode, which you may make yourself, after a separate disclosure, for a game the Software has already measured successfully, and under which the Software still runs every check (Disclaimer §2A). By making such an exception you accept, for that game, the risk described in (b) below.
By enabling this feature for a game, you confirm that:
+11 -5
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.2 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.5 · **Effective:** {{RELEASE_DATE}}
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
@@ -8,8 +8,8 @@
Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
- Your game library entries (names, executable paths, metadata you or the app filled in).
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, memory usage), session duration, crash flags, tags and notes you write.
- Your game library entries (names, executable paths, metadata you or the app filled in, and whether each one is recorded).
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, memory usage), session duration, crash flags, the graphics driver's settings the game ran under (NVIDIA only), how the game's window was shown (full-screen, borderless or windowed, for how long, its size and the monitor's), tags and notes you write.
- A hardware snapshot per session (CPU/GPU model, driver version, RAM size, OS build, display mode) used for the "what changed between sessions" feature.
- App settings, logs (rotated daily — the app keeps 7 days, the capture agent 14 — including the logs written by the component loaded into games), and, after a crash of the app itself, crash dump files.
- Which games you enabled code injection for, and when you consented.
@@ -37,9 +37,15 @@ The "Report a bug" feature builds a zip file **on your device**, shows you exact
## 4. What the app can technically observe
To do its job, FrameLedger observes: which of *your tracked* executables are running and their process trees; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); video-memory usage reported by the graphics runtime; loaded module names of a game being captured (for detection and for the anti-cheat safety check); and hardware sensor values from your graphics driver's own libraries.
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); video-memory usage reported by the graphics runtime; loaded module names of a game being captured (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), and the store files that name it (Steam's and GOG's, on your disk) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and how busy the processor is and how much memory is in use, from Windows' own counters.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for games you added to your library, and injects only into games you individually enabled.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
> **History.** Version 2.3 (2026-09-23) adds the per-entry recording switch. Before it, every program in your library was recorded whenever it ran, which recorded a utility that starts with Windows at every boot.
>
> Version 2.4 (2026-09-25, 0.1.0-beta.8) names what the software reads to check every game in your library for anti-cheat — until then it checked only a game you asked to hook — and to name the versions of its files, and the NVIDIA driver's settings for your games. The files of a library game's folder were already read to detect its engine and features; this version is the first to say so.
>
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
All of this stays on your device. None of it is transmitted anywhere.
+190 -25
View File
@@ -15,16 +15,15 @@
"compilability, case-insensitive duplicate values — stay imperative in",
"tools/rules-validate.ps1.",
"",
"STILL INCOMPLETE AS DATA: docs/19_SAFETY §Blocklist seed names two families",
"with no representation here at all — Activision Ricochet (driver/service",
"names not yet confirmed) and Valve VAC (needs blockedStoreIds entries).",
"STILL INCOMPLETE AS DATA: docs/19_SAFETY §Blocklist seed names one family",
"with no representation here at all — Valve VAC (needs blockedStoreIds",
"entries). Activision Ricochet was the other until 2026-09-25, when its",
"driver and services arrived from Activision's own support pages.",
"",
"PRE-INJECTION CHECK 3 MATCHES NOTHING, because `blockedExecutables` and",
"`blockedStoreIds` are both empty. That is a fact about THIS DATA, which is",
"why it is stated here; seeding the lists is a product decision (which",
"titles, and what an unresolvable store id means) tracked as",
"docs/20_OPEN_QUESTIONS.md §S14. Recorded rather than left to be inferred",
"from two empty arrays.",
"PRE-INJECTION CHECK 3 MATCHED NOTHING until 2026-09-25, because",
"`blockedExecutables` and `blockedStoreIds` were both empty. The owner seeded",
"them that day (rules 2026.09.4); what an unresolvable store id means is",
"the matrix in docs/19_SAFETY check 3 (docs/20_OPEN_QUESTIONS.md §S14).",
"",
"WHICH CHECKS RUN IS DELIBERATELY NOT STATED HERE ANY MORE. This comment used",
"to list them — a FOURTH restatement of the gate's composition, in the one",
@@ -41,7 +40,7 @@
"level, which made it a check that could not fire."
],
"schemaVersion": 2,
"rulesVersion": "2026.09.1",
"rulesVersion": "2026.09.6",
"engines": [
{
@@ -60,7 +59,7 @@
{ "type": "sibling_glob", "value": "*-Win64-Shipping.exe" },
{ "type": "sibling_glob", "value": "*/Content/Paks/*.pak" }
] },
"version": { "type": "pe_product_version_regex", "value": "\\+\\+UE(4|5)\\+Release-(\\d+\\.\\d+)" }
"version": { "type": "unreal_build" }
},
{
"id": "rpgmaker_mv",
@@ -84,6 +83,23 @@
] },
"version": null
},
{
"id": "re_engine",
"name": "RE Engine",
"signals": { "any": [
{ "type": "sibling_glob", "value": "re_chunk_000.pak" }
] },
"version": null
},
{
"id": "fromsoftware",
"name": "FromSoftware",
"signals": { "all": [
{ "type": "sibling_glob", "value": "*.bhd" },
{ "type": "sibling_glob", "value": "*.bdt" }
] },
"version": null
},
{
"id": "godot",
"name": "Godot",
@@ -166,8 +182,8 @@
{ "id": "dlss_g", "name": "DLSS Frame Gen", "signals": [ "nvngx_dlssg.dll", "sl.dlss_g.dll" ] },
{ "id": "dlss_rr", "name": "Ray Reconstruction","signals": [ "nvngx_dlssd.dll" ] },
{ "id": "streamline", "name": "Streamline", "signals": [ "sl.interposer.dll", "sl.reflex.dll" ] },
{ "id": "fsr", "name": "FSR", "signals": [ "ffx_fsr2_*.dll", "ffx_frameinterpolation_*.dll", "amd_fidelityfx_*.dll", "ffx_api*.dll" ] },
{ "id": "xess", "name": "XeSS", "signals": [ "libxess.dll" ] },
{ "id": "fsr", "name": "FSR", "signals": [ "ffx_fsr2_*.dll", "ffx_fsr3*.dll", "ffx_frameinterpolation_*.dll", "amd_fidelityfx_*.dll", "ffx_api*.dll" ] },
{ "id": "xess", "name": "XeSS", "signals": [ "libxess.dll", "libxess_dx11.dll" ] },
{ "id": "xefg", "name": "XeSS Frame Gen", "signals": [ "libxess_fg.dll" ] }
],
@@ -181,30 +197,129 @@
{ "family": "Xigncode3", "match": "prefix", "values": [ "xhunter" ] },
{ "family": "PunkBuster", "match": "prefix", "values": [ "PnkBstr", "pbcl", "pbsv" ] },
{ "family": "FACEIT", "match": "prefix", "values": [ "faceit" ] },
{ "family": "ESEA", "match": "prefix", "values": [ "esea" ] }
{ "family": "ESEA", "match": "prefix", "values": [ "esea" ] },
{ "family": "Anti-Cheat Expert", "match": "prefix", "values": [ "SGuard", "AntiCheatExpert" ],
"note": "APPENDED 2026-09-25, as every row below: the Overlay reports a 1-based index into this array (sessions.early_stop_family), so a row inserted above shifts what stored indexes mean. SGuard64/SGuardSvc64 are ACE's guard processes (documented, file.net; unmeasured)." },
{ "family": "EA AntiCheat", "match": "prefix", "values": [ "EAAntiCheat" ],
"note": "EA Javelin: EAAntiCheat.GameServiceLauncher.dll / EAAntiCheat.GameService.exe (documented, EA forums). Unmeasured." },
{ "family": "NetEase Anti-Cheat", "match": "prefix", "values": [ "NeacSafe", "NeacClient" ],
"note": "NEAC (Naraka, Marvel Rivals, FragPunk). NeacSafe64 is documented (LOLDrivers, SteamDB NetEase_AntiCheatExperts); NeacClient unmeasured." },
{ "family": "NetEase Yidun", "match": "exact", "values": [ "NEP2.dll" ],
"note": "Documented (SteamDB FileDetectionRuleSets, NetEase_Yidun). Unmeasured." },
{ "family": "Nexon Game Security", "match": "prefix", "values": [ "BlackCipher", "BlackCall", "BlackXchg" ],
"note": "BlackCipher64.aes runs as its own process in the game's tree (The First Descendant, MapleStory). Documented (SteamDB BlackCipher). Unmeasured." },
{ "family": "mihoyo protect", "match": "prefix", "values": [ "mhypbase" ],
"note": "mhypbase.dll is the user-mode half HoYoverse titles load. Documented; unmeasured." },
{ "family": "TenProtect", "match": "prefix", "values": [ "TP3Helper", "TenSafe" ],
"note": "Tencent TenProtect. TP3Helper documented (SteamDB); TenSafe unmeasured." },
{ "family": "AhnLab HackShield", "match": "prefix", "values": [ "EhSvc", "HShield", "HSInst" ],
"note": "Documented (SteamDB HackShield: HShield/HSInst.dll). Unmeasured." },
{ "family": "Anybrain", "match": "exact", "values": [ "anybrainSDK.dll", "Cerebro.dll" ],
"note": "Behavioural, user-mode. Documented (SteamDB AnyBrain). Unmeasured." },
{ "family": "Roblox Hyperion", "match": "exact", "values": [ "RobloxPlayerBeta.dll" ],
"note": "Hyperion (Byfron) protects this module inside the Roblox player. Documented; unmeasured." },
{ "family": "EQU8", "match": "prefix", "values": [ "equ8" ],
"note": "Splitgate. Documented (SteamDB EQU8); module names unmeasured." },
{ "family": "Xigncode3", "match": "exact", "values": [ "x3.xem" ],
"note": "x3.xem is XIGNCODE3's loader, LoadLibrary'd as an ordinary module (documented). The files row names the same token in the install tree." }
],
"drivers": [
{ "family": "Riot Vanguard", "match": "exact", "values": [ "vgk.sys" ], "scope": "machine" },
{ "family": "mihoyo protect", "match": "prefix", "values": [ "mhyprot" ], "scope": "machine" },
{ "family": "mihoyo protect", "match": "prefix", "values": [ "mhyprot", "HoYoKProtect" ], "scope": "machine",
"note": "HoYoKProtect.sys (Genshin Impact's overseas client, 2025) is NOT matched by the mhyprot prefix, so it is named here (documented; unmeasured)." },
{ "family": "Easy Anti-Cheat", "match": "prefix", "values": [ "EasyAntiCheat" ], "scope": "machine",
"note": "MEASURED 2026-08-04: EasyAntiCheat_EOSSys was Running as a kernel driver while a real EAC title played, and matched NOTHING in this group — the refusal came from the service check instead. A family caught through only one of five groups is one rename away from being missed." },
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "ACE-BASE.sys", "ACE-ADVT.sys", "ACE-GAME.sys" ], "scope": "machine",
"note": "ACE-BASE.sys and ACE-ADVT.sys MEASURED under System32\\drivers on the dev machine 2026-08-04. ACE-GAME.sys is a documented sibling and is UNMEASURED: a blocklist may over-cover, never under-cover. Exact not prefix — 'ACE-' is four characters over a namespace we do not own." }
"note": "ACE-BASE.sys and ACE-ADVT.sys MEASURED under System32\\drivers on the dev machine 2026-08-04. ACE-GAME.sys is a documented sibling and is UNMEASURED: a blocklist may over-cover, never under-cover. Exact not prefix — 'ACE-' is four characters over a namespace we do not own." },
{ "family": "BattlEye", "match": "exact", "values": [ "BEDaisy.sys" ], "scope": "machine",
"note": "BattlEye's kernel driver, loaded by BEService while a protected game runs and unloaded after (documented, BattlEye FAQ). Unmeasured." },
{ "family": "FACEIT", "match": "exact", "values": [ "FACEIT.sys" ], "scope": "machine",
"note": "Loaded while the FACEIT AC client runs (documented, FACEIT support). Unmeasured." },
{ "family": "ESEA", "match": "prefix", "values": [ "ESEADriver" ], "scope": "machine",
"note": "ESEADriver2.sys (documented). Unmeasured." },
{ "family": "EA AntiCheat", "match": "exact", "values": [ "EAAntiCheat.sys" ], "scope": "machine",
"note": "EA Javelin's kernel driver, loaded with the game (documented, EA forums). Unmeasured. Its user-mode EAAntiCheatService is deliberately NOT listed: it can be set to start automatically, and a service that is always running would refuse every session on the machine." },
{ "family": "Activision Ricochet", "match": "exact", "values": [ "randgrid.sys", "brynhildr.sys", "atvi-brynhildr.sys" ], "scope": "machine",
"note": "RICOCHET's kernel driver randgrid.sys (documented, Activision support; a kernel service pointing at the file in the game folder); brynhildr is its 2021 predecessor (Microsoft Q&A). Unmeasured." },
{ "family": "NetEase Anti-Cheat", "match": "prefix", "values": [ "NeacSafe" ], "scope": "machine",
"note": "NeacSafe64.sys, a minifilter loaded during play (documented, LOLDrivers). Unmeasured." },
{ "family": "Xigncode3", "match": "prefix", "values": [ "xhunter" ], "scope": "machine",
"note": "xhunter1.sys, XIGNCODE3's kernel driver (documented, LOLDrivers / Wellbia FAQ). Unmeasured." },
{ "family": "Denuvo Anti-Cheat", "match": "exact", "values": [ "denuvo-anti-cheat.sys" ], "scope": "machine",
"note": "Loaded only while a protected game runs (documented, Irdeto Q&A; file name from DRML). Unmeasured." },
{ "family": "EQU8", "match": "prefix", "values": [ "EQU8_HELPER" ], "scope": "machine",
"note": "EQU8_HELPER_<n>.sys (documented). Unmeasured." },
{ "family": "PunkBuster", "match": "prefix", "values": [ "PnkBstrK" ], "scope": "machine",
"note": "PnkBstrK.sys, PunkBuster's kernel component. Unmeasured." },
{ "family": "TenProtect", "match": "exact", "values": [ "TesSafe.sys" ], "scope": "machine",
"note": "Tencent game-protection driver (documented). Unmeasured." },
{ "family": "Nexon Game Security", "match": "exact", "values": [ "BlackCat64.sys" ], "scope": "machine",
"note": "Documented (SteamDB BlackCipher). Unmeasured." }
],
"directories": [
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat" ] },
{ "family": "BattlEye", "values": [ "BattlEye" ] }
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat", "EasyAntiCheat_EOS" ] },
{ "family": "BattlEye", "values": [ "BattlEye" ] },
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert", "AceAntibotClient" ],
"note": "Documented (SteamDB FileDetectionRuleSets, AntiCheatExpert). Unmeasured." },
{ "family": "nProtect GameGuard", "values": [ "GameGuard" ] },
{ "family": "Xigncode3", "values": [ "XIGNCODE", "XIGNCODE3" ] },
{ "family": "AhnLab HackShield", "values": [ "HShield" ],
"note": "Documented (SteamDB HackShield). Unmeasured." },
{ "family": "Nexon Game Security", "values": [ "BlackCipher" ],
"note": "Measured by others at M1/Binaries/Win64/BlackCipher/ (The First Descendant, Steam community); unmeasured here." },
{ "family": "PunkBuster", "values": [ "PunkBuster" ],
"note": "Documented (SteamDB PunkBuster). The two-letter pb/ folder some titles use is deliberately NOT a token: too short to be a signal." },
{ "family": "FredaikisAntiCheat", "values": [ "FredaikisAntiCheat" ],
"note": "Documented (SteamDB FileDetectionRuleSets). Unmeasured." }
],
"services": [
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat", "EasyAntiCheat_EOS", "EasyAntiCheat_EOSSys" ] },
{ "family": "Riot Vanguard", "values": [ "vgc" ] },
{ "family": "Riot Vanguard", "values": [ "vgc", "vgk" ],
"note": "vgk is the kernel driver's service, started at boot like vgk.sys itself." },
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert Protection", "AntiCheatExpert Service" ],
"note": "'AntiCheatExpert Protection' MEASURED registered on the dev machine 2026-08-04 by Neverness To Everness. The sibling name is unmeasured." }
"note": "'AntiCheatExpert Protection' MEASURED registered on the dev machine 2026-08-04 by Neverness To Everness. The sibling name is unmeasured." },
{ "family": "BattlEye", "values": [ "BEService", "BEDaisy" ],
"note": "BEService is started by a protected game and stops after it; BEDaisy is the driver's service. A stopped service is absent (19_SAFETY). Unmeasured." },
{ "family": "FACEIT", "values": [ "FACEIT", "FACEITService" ],
"note": "Running while the FACEIT AC client runs (documented, FACEIT support). Unmeasured." },
{ "family": "ESEA", "values": [ "ESEADriver2" ] },
{ "family": "Activision Ricochet", "values": [ "atvi-randgrid_sr", "atvi-randgrid_msstore" ],
"note": "Kernel services pointing at randgrid.sys; running only while Call of Duty runs (documented, Activision support). Unmeasured." },
{ "family": "mihoyo protect", "values": [ "mhyprot2", "mhyprot3", "HoYoKProtect" ] },
{ "family": "Xigncode3", "values": [ "xhunter1" ] },
{ "family": "Denuvo Anti-Cheat", "values": [ "denuvo-anti-cheat" ],
"note": "The driver's service. The separate update service runs outside play and is deliberately NOT listed." },
{ "family": "nProtect GameGuard", "values": [ "npggsvc" ] }
],
"files": [
{ "family": "Xigncode3", "values": [ "x3.xem" ], "note": "Data file shipped beside the game, not a loadable module." },
{ "family": "Anti-Cheat Expert", "values": [ "PGameProtectDriver_X64.sys" ],
"note": "A KERNEL DRIVER shipped inside the game install. MEASURED at 'Neverness To Everness/NTEGlobal/driver/' 2026-08-04, where check 4 returned Allow: no group named it, and the fuzzy tier is modules-only — so a name containing 'protect' sat in the game's tree and the static scan walked past." }
{ "family": "Xigncode3", "values": [ "x3.xem", "xhunter1.sys" ],
"note": "Shipped beside the game. This note said 'not a loadable module' until 2026-09-25: XIGNCODE3 LoadLibrary's x3.xem as its loader (documented), which is why the modules group names it too." },
{ "family": "Anti-Cheat Expert", "values": [ "PGameProtectDriver_X64.sys", "SGuard64.exe", "SGuardSvc64.exe" ],
"note": "A KERNEL DRIVER shipped inside the game install. MEASURED at 'Neverness To Everness/NTEGlobal/driver/' 2026-08-04, where check 4 returned Allow: no group named it, and the fuzzy tier is modules-only — so a name containing 'protect' sat in the game's tree and the static scan walked past." },
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat_EOS_Setup.exe", "EasyAntiCheat_Setup.exe", "EasyAntiCheat_x64.dll", "EasyAntiCheat_x86.dll", "EasyAntiCheat_EOS.sys", "start_protected_game.exe", "eac_server64.dll" ],
"note": "For a layout where the EasyAntiCheat folder sits deeper than the scan reaches. start_protected_game.exe is the EAC launcher FromSoftware titles ship (ELDEN RING's appeared in the owner's Windows Application log on 2026-09-21)." },
{ "family": "BattlEye", "values": [ "BEService.exe", "BEService_x64.exe", "BEClient.dll", "BEClient_x64.dll", "BEDaisy.sys" ],
"note": "Documented (SteamDB BattlEye). Unmeasured." },
{ "family": "EA AntiCheat", "values": [ "EAAntiCheat.Installer.exe", "EAAntiCheat.GameServiceLauncher.exe", "EAAntiCheat.GameServiceLauncher.dll" ],
"note": "Documented (SteamDB EA_AntiCheat; EA forums). Unmeasured." },
{ "family": "Activision Ricochet", "values": [ "randgrid.sys" ],
"note": "The driver ships inside the game folder (documented, Activision support). Unmeasured." },
{ "family": "mihoyo protect", "values": [ "mhypbase.dll", "mhyprot2.sys", "mhyprot3.sys", "HoYoKProtect.sys" ] },
{ "family": "NetEase Anti-Cheat", "values": [ "NeacSafe64.sys", "NeacSafe64_ex.sys" ],
"note": "Documented (SteamDB NetEase_AntiCheatExperts). Unmeasured." },
{ "family": "NetEase Yidun", "values": [ "NEP2.dll" ] },
{ "family": "Nexon Game Security", "values": [ "BlackCipher.aes", "BlackCipher64.aes", "BlackCall.aes", "BlackCall64.aes", "BlackCat64.sys" ] },
{ "family": "TenProtect", "values": [ "TP3Helper.exe" ] },
{ "family": "EQU8", "values": [ "equ8_conf.json" ] },
{ "family": "AhnLab HackShield", "values": [ "HSInst.dll", "EhSvc.dll" ] },
{ "family": "nProtect GameGuard", "values": [ "GameGuard.des", "GameMon.des", "GameMon64.des", "npggNT.des", "npggNT64.des", "npsc.des" ],
"note": "GameGuard's engine files (documented, file.net / SteamDB). Unmeasured." },
{ "family": "PunkBuster", "values": [ "pbsvc.exe", "PnkBstrA.exe", "PnkBstrB.exe", "pbsv.dll", "pbcl.dll", "pbag.dll" ],
"note": "Files in the install tree, not services: PnkBstrA runs at every boot once installed, so as a service it would refuse every session on the machine." },
{ "family": "Anybrain", "values": [ "anybrainSDK.dll", "Cerebro.dll" ] },
{ "family": "Denuvo Anti-Cheat", "values": [ "denuvo-anti-cheat.sys", "denuvo-anti-cheat-runtime.dll", "denuvo-anti-cheat-update-service.exe" ],
"note": "Documented (DRML). Unmeasured." },
{ "family": "Roblox Hyperion", "values": [ "RobloxPlayerBeta.dll" ] }
],
"heuristic": {
"$comment": [
@@ -254,7 +369,57 @@
],
"action": "warn_and_refuse"
},
"blockedExecutables": [],
"blockedStoreIds": []
"blockedExecutables": [
{ "family": "Valve VAC", "match": "exact", "values": [ "cs2.exe", "csgo.exe", "dota2.exe", "tf_win64.exe", "deadlock.exe", "project8.exe", "left4dead2.exe", "gmod.exe" ],
"reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "family": "Riot Vanguard", "match": "exact", "values": [ "VALORANT-Win64-Shipping.exe", "League of Legends.exe" ],
"reason": "Protected by Riot Vanguard, a kernel anti-cheat that loads at boot." },
{ "family": "Roblox Hyperion", "match": "exact", "values": [ "RobloxPlayerBeta.exe" ],
"reason": "The Roblox player is protected by Hyperion anti-tamper." },
{ "family": "Blizzard Warden", "match": "exact", "values": [ "Overwatch.exe", "Diablo IV.exe", "Diablo III64.exe", "Wow.exe", "WowClassic.exe", "SC2_x64.exe", "HeroesOfTheStorm_x64.exe" ],
"reason": "An online Blizzard title: its anti-cheat is built into the game and ships no file of its own." },
{ "family": "Activision Ricochet", "match": "exact", "values": [ "cod.exe", "ModernWarfare.exe", "BlackOpsColdWar.exe" ],
"reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "family": "NetEase Anti-Cheat", "match": "exact", "values": [ "Marvel-Win64-Shipping.exe", "NarakaBladepoint.exe" ],
"reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "DeltaForceClient-Win64-Shipping.exe" ],
"reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
{ "family": "mihoyo protect", "match": "exact", "values": [ "GenshinImpact.exe", "YuanShen.exe", "StarRail.exe", "ZenlessZoneZero.exe", "BH3.exe" ],
"reason": "A HoYoverse title, protected by its kernel anti-cheat driver." },
{ "family": "EA AntiCheat", "match": "exact", "values": [ "bf2042.exe", "bf6.exe", "FC25.exe", "FC26.exe" ],
"reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." }
],
"blockedStoreIds": [
{ "store": "steam", "id": "730", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "570", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "440", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "1422450", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "240", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "10", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "80", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "550", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "500", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "4000", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "320", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "300", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "20", "family": "Valve VAC", "reason": "A VAC-secured online title. VAC runs inside Steam, so no file of the game's own names it." },
{ "store": "steam", "id": "1938090", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "1962663", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "3595270", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "4384550", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "2519060", "family": "Activision Ricochet", "reason": "Call of Duty, protected by the RICOCHET kernel anti-cheat." },
{ "store": "steam", "id": "2357570", "family": "Blizzard Warden", "reason": "An online Blizzard title: its anti-cheat is built into the game and ships no file of its own." },
{ "store": "steam", "id": "2344520", "family": "Blizzard Warden", "reason": "An online Blizzard title: its anti-cheat is built into the game and ships no file of its own." },
{ "store": "steam", "id": "2767030", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "1203220", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "2943650", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "2139460", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
{ "store": "steam", "id": "2507950", "family": "Anti-Cheat Expert", "reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
{ "store": "steam", "id": "2073620", "family": "Anti-Cheat Expert", "reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
{ "store": "steam", "id": "1517290", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
{ "store": "steam", "id": "2807960", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
{ "store": "steam", "id": "2669320", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
{ "store": "steam", "id": "3405690", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." }
]
}
}
+18 -9
View File
@@ -196,6 +196,15 @@
"type": { "const": "manifest_field" },
"field": { "$ref": "#/$defs/manifestFieldPath" }
}
},
{
"$comment": "beta.10: Unreal Engine's build facts (the shipping executable's numeric file version and the engine's branch name inside it), decided in code (Domain.Detection.UnrealVersion) rather than by a pattern - which is why it takes no parameter.",
"type": "object",
"additionalProperties": false,
"required": ["type"],
"properties": {
"type": { "const": "unreal_build" }
}
}
]
}
@@ -404,7 +413,7 @@
"$comment": "maxItems is fl::guard::kMaxFamilies, and it bounds the SUM of all five groups, not this one array - the parser fills a single families[kMaxFamilies] from all of them. A schema cannot express a cross-array total, so the per-array cap is set to the total (no single array can breach it alone) and tools/rules-validate.ps1 checks the sum imperatively. Exceeding it is ParseResult::kTooLarge for the whole file, i.e. the guard refuses every title.",
"type": "array",
"minItems": 1,
"maxItems": 64,
"maxItems": 256,
"items": { "$ref": "#/$defs/acMatchGroup" },
"allOf": [
{
@@ -420,7 +429,7 @@
"drivers": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"maxItems": 256,
"items": { "$ref": "#/$defs/acDriverGroup" },
"allOf": [
{
@@ -429,29 +438,29 @@
]
},
"directories": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/$defs/acNameGroup" } },
"services": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/$defs/acNameGroup" } },
"directories": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "$ref": "#/$defs/acNameGroup" } },
"services": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "$ref": "#/$defs/acNameGroup" } },
"files": {
"$comment": "NEW in this schema. 19_SAFETY lists Xigncode3's `x3.xem`, which is a data file shipped beside the game rather than a loadable module - the previous seed had nowhere to put it. Also the home for the anti-cheat SDK payloads that 19_SAFETY check 4 (multiplayer heuristic) looks for during the static pre-scan.",
"$comment": "NEW in this schema. 19_SAFETY lists Xigncode3's `x3.xem`, which is a data file shipped beside the game rather than a loadable module - the previous seed had nowhere to put it (2026-09-25: XIGNCODE3 also LoadLibrary's it as its loader, so modules names it too). Also the home for the anti-cheat SDK payloads that 19_SAFETY check 4 (multiplayer heuristic) looks for during the static pre-scan.",
"type": "array",
"minItems": 1,
"maxItems": 64,
"maxItems": 256,
"items": { "$ref": "#/$defs/acNameGroup" }
},
"heuristic": { "$ref": "#/$defs/heuristic" },
"blockedExecutables": {
"$comment": "May legitimately be empty - a per-title list, not the family blocklist. minItems is deliberately absent here and deliberately present on modules/drivers. maxItems is fl::guard::kMaxTitleRules; at kMaxValuesPerTitleRule values each that is 512 blockable names, more than the 4096 this used to claim could ever have survived the parser.",
"$comment": "May legitimately be empty - a per-title list, not the family blocklist. minItems is deliberately absent here and deliberately present on modules/drivers. maxItems is fl::guard::kMaxTitleRules (128 since 2026-09-25); at kMaxValuesPerTitleRule values each that is 1024 blockable names, more than the 4096 this used to claim could ever have survived the parser.",
"type": "array",
"maxItems": 64,
"maxItems": 128,
"items": { "$ref": "#/$defs/acBlockedExecutable" }
},
"blockedStoreIds": {
"type": "array",
"maxItems": 64,
"maxItems": 128,
"items": { "$ref": "#/$defs/acBlockedStoreId" }
}
}
+52 -4
View File
@@ -1,4 +1,6 @@
using System.Globalization;
using System.Security.Principal;
using FrameLedger.Infrastructure.Startup;
namespace FrameLedger.Agent.Cli;
@@ -11,6 +13,13 @@ namespace FrameLedger.Agent.Cli;
/// <b><c>--data-dir</c> exists only under <c>--console</c></b> (HANDOFF §P2 decision D6): an integration test
/// needs a scratch ledger, and CI must never touch the profile. <c>--serve</c> with it is an error rather than an
/// ignored option, because an ignored option is how the product directory becomes selectable by accident.
/// <para>
/// <b><c>--serve</c> takes two options since beta.10, and only these</b> (the Agent's admin mode, owner decision D34):
/// <c>--for-user &lt;SID&gt;</c>, which the starter passes to the Agent it asked Windows to elevate — the Agent refuses to run
/// as any other account (<c>AgentElevation.ExitOtherAccount</c>) — and <c>--elevation &lt;outcome&gt;</c>, which says the
/// starter asked and was not granted, so this Agent does not ask again. Neither names a directory, a target or a check; the
/// data folder is still the profile's and nothing else.
/// </para>
/// </remarks>
internal sealed record AgentCommandLine
{
@@ -29,7 +38,7 @@ internal sealed record AgentCommandLine
};
private const string _usage =
"usage: FrameLedger.Agent --serve\n"
"usage: FrameLedger.Agent --serve [--for-user <SID> | --elevation declined|other-account|failed]\n"
+ " FrameLedger.Agent --register-vklayer | --unregister-vklayer | --install-task | --uninstall-task\n"
+ " FrameLedger.Agent --write-crash-dump <file> (started by a crashing App or Agent; dumps that parent)\n"
+ " FrameLedger.Agent --console [--data-dir <dir>] consent list | consent grant --exe <path> | consent revoke --exe <path>\n"
@@ -59,6 +68,12 @@ internal sealed record AgentCommandLine
public string? DataDirectory { get; init; }
/// <summary><c>--serve --for-user</c>: the account whose Agent this elevated process must be (beta.10, D34).</summary>
public string? ForUser { get; init; }
/// <summary><c>--serve --elevation</c>: the starter asked for elevation and got this instead (<c>AgentElevation.Refusals</c>).</summary>
public string? ElevationRefusal { get; init; }
/// <summary>The file <see cref="AgentVerb.WriteCrashDump"/> writes — a path, never a pid.</summary>
public string? CrashDumpFile { get; init; }
@@ -97,9 +112,7 @@ internal sealed record AgentCommandLine
if (string.Equals(args[0], "--serve", StringComparison.Ordinal))
{
return args.Length == 1
? new AgentCommandLine { Verb = AgentVerb.Serve }
: new AgentCommandLine { Error = "--serve takes no options; --data-dir exists only under --console (the product directory is not selectable)" };
return ParseServe(args[1..]);
}
if (!string.Equals(args[0], "--console", StringComparison.Ordinal))
@@ -110,6 +123,41 @@ internal sealed record AgentCommandLine
return ParseConsole(args[1..]);
}
/// <summary><c>--serve</c>, alone or with ONE of its two admin-mode options (beta.10).</summary>
private static AgentCommandLine ParseServe(string[] rest)
{
const string onlyThese = "--serve takes only --for-user <SID> or --elevation declined|other-account|failed (the agent's admin mode); "
+ "--data-dir exists only under --console (the product directory is not selectable)";
if (rest.Length == 0)
{
return new AgentCommandLine { Verb = AgentVerb.Serve };
}
if (rest.Length != 2)
{
return new AgentCommandLine { Error = onlyThese };
}
switch (rest[0])
{
case "--for-user":
try
{
// A SID in its string form, validated as one: the Agent compares it with its own token's user.
return new AgentCommandLine { Verb = AgentVerb.Serve, ForUser = new SecurityIdentifier(rest[1]).Value };
}
catch (ArgumentException)
{
return new AgentCommandLine { Error = $"--for-user needs a SID, not '{rest[1]}'" };
}
case "--elevation" when AgentElevation.Refusals.Contains(rest[1], StringComparer.Ordinal):
return new AgentCommandLine { Verb = AgentVerb.Serve, ElevationRefusal = rest[1] };
default:
return new AgentCommandLine { Error = onlyThese };
}
}
private static AgentCommandLine ParseConsole(string[] rest)
{
(AgentVerb verb, int at, int words) = VerbOf(rest);
@@ -0,0 +1,8 @@
namespace FrameLedger.Agent.Composition;
/// <summary>
/// The admin mode's answer at this Agent's start (beta.10, owner decision D34): registered by <c>--serve</c> alone, read into
/// <c>HelloAck.ElevationOutcome</c>. Null when nobody asked — the option off, or elevation inherited from whoever started it.
/// </summary>
/// <param name="Outcome">One of <c>Infrastructure.Startup.AgentElevation</c>'s outcomes, or null.</param>
internal sealed record AgentElevationState(string? Outcome);
@@ -9,7 +9,7 @@ namespace FrameLedger.Agent.Composition;
/// <summary>What <c>HelloAck</c> says about this process, read once at composition.</summary>
internal static class AgentIdentityFactory
{
public static AgentIdentity OfThisProcess(string vkLayerDirectory)
public static AgentIdentity OfThisProcess(string vkLayerDirectory, string? elevationOutcome = null)
{
ArgumentException.ThrowIfNullOrWhiteSpace(vkLayerDirectory);
string buildId = NativeAntiCheatGuard.BuildId();
@@ -25,7 +25,11 @@ 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,
// beta.10 (D34): what the admin mode's prompt answered at this start; null when nobody asked.
ElevationOutcome: elevationOutcome);
}
private static string Version()
@@ -4,6 +4,7 @@ using FrameLedger.Application.Consent;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Telemetry;
using FrameLedger.Infrastructure.Display;
using FrameLedger.Infrastructure.Telemetry;
namespace FrameLedger.Agent.Composition;
@@ -34,6 +35,11 @@ internal sealed class AgentRecording
private readonly ISessionObserver _observer;
private readonly CapturePause _pause;
private readonly IRecorderPolicy _policy;
private readonly IDriverProfileSource _profiles;
private readonly IUserModeExceptionSwitch _exceptions;
private readonly IOverlayToleranceChannel _tolerance;
private readonly WindowGeometryProbe _display = new();
private readonly UserModeExceptionLapsePolicy _exceptionLapse;
public AgentRecording(
IGameConsentStore store,
@@ -53,8 +59,16 @@ internal sealed class AgentRecording
ICrashEventSource crashes,
ISessionObserver observer,
CapturePause pause,
IRecorderPolicy policy)
IRecorderPolicy policy,
IDriverProfileSource profiles,
IUserModeExceptionSwitch exceptions,
IOverlayToleranceChannel tolerance,
UserModeExceptionLapsePolicy exceptionLapse)
{
_profiles = profiles;
_exceptions = exceptions;
_tolerance = tolerance;
_exceptionLapse = exceptionLapse;
_store = store;
_gate = gate;
_guard = guard;
@@ -104,7 +118,9 @@ internal sealed class AgentRecording
TimeProvider.System,
new RecorderOptions { MinimumSessionLength = minimum, PartialFlushInterval = flush },
_observer,
_policy);
_policy,
_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>
@@ -170,7 +186,11 @@ internal sealed class AgentRecording
launcher,
observer,
_killSwitch,
_pause);
_pause,
_exceptions,
_tolerance,
// beta.10: the game's window, read out of process on the loop's ticks (03_METRICS §Display mode).
_display);
/// <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
@@ -61,7 +61,6 @@ internal static class AgentServices
// Persistence: the one ledger, the Agent's own (%LOCALAPPDATA%\FrameLedger, §S18 blocker 3).
services.AddSingleton<IGameConsentStore, SqliteGameConsentStore>();
services.AddSingleton<IGuardBypassStore, SqliteGuardBypassStore>();
services.AddSingleton<IGameRepository, SqliteGameRepository>();
services.AddSingleton<ISessionRepository, SqliteSessionRepository>();
services.AddSingleton<IHardwareSnapshotRepository, SqliteHardwareSnapshotRepository>();
@@ -71,18 +70,26 @@ 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>();
services.AddSingleton<HookedCaptureGate>();
// The capture path's adapters (PR-C).
services.AddSingleton<ITargetResolver>(static _ => new TargetResolver(AgentConsole.Line));
// The capture path's adapters (PR-C). The resolver's notes reach the Agent's log too (2026-09-23: there were none in
// it), and its Tier-2 liveness reads the watcher's snapshot by image path, never a process of its own.
services.AddSingleton<LatestProcessSnapshot>();
services.AddSingleton<ITargetResolver>(static sp => new TargetResolver(
static line =>
{
AgentConsole.Line(line);
Serilog.Log.Information("{Line}", line);
},
sp.GetRequiredService<LatestProcessSnapshot>()));
services.AddSingleton<ITargetLivenessSource, HeldProcessLivenessSource>();
services.AddSingleton<IRingAttacher>(static _ => new ShmRingAttacher(NativeAntiCheatGuard.BuildId()));
services.AddSingleton<IRuntimeModuleSnapshot>(static _ => new RuntimeModuleSnapshot(CensusNames.ModuleFileNames));
services.AddSingleton<NvapiNgxStateProbe>();
services.AddSingleton<INgxDriverProbe>(static sp => sp.GetRequiredService<NvapiNgxStateProbe>());
AddNvidia(services);
// The recorder's adapters (PR-D).
services.AddSingleton<IPartialSessionStore>(_ => new PartialSessionStore(paths.Tmp));
@@ -105,6 +112,31 @@ 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
/// frame-generation overrides — read from the driver's settings store through the bridge's read-only DRS entry point.
/// </summary>
private static void AddNvidia(IServiceCollection services)
{
services.AddSingleton<NvapiNgxStateProbe>();
services.AddSingleton<INgxDriverProbe>(static sp => sp.GetRequiredService<NvapiNgxStateProbe>());
services.AddSingleton<NvapiDriverProfileSource>();
services.AddSingleton<IDriverProfileSource>(static sp => sp.GetRequiredService<NvapiDriverProfileSource>());
}
/// <summary>The static detection sweep (P4 PR-1, <c>05_DETECTION</c> §Caching): hosted under <c>--serve</c> only, composed and inert under <c>--console</c>.</summary>
private static void AddDetection(IServiceCollection services, AgentPaths paths)
{
@@ -113,12 +145,43 @@ internal static class AgentServices
// --serve only (DetectionHostedService); composed and inert under --console.
services.AddSingleton<IDetectionRulesSource>(static _ => new DetectionRulesFile());
services.AddSingleton<IGameFileProbe, GameFileProbe>();
// A drive that changed its letter (2026-09-22): one relocator, asked by the sweep, the watcher and the enable-hooking
// command, over the BCL's drive list. Since 2026-09-23 it also merges two entries for one executable (D26), and waits
// while a session of either runs — the orchestrator's table, read when asked (it holds the relocator itself) — or
// waits in a .partial to be recovered.
services.AddSingleton<IGameMerge>(static sp => new SqliteGameMerge(sp.GetRequiredService<LedgerDatabase>()));
services.AddSingleton(static sp => new ExecutableRelocator(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
VolumeRoots.Ready,
static line => Serilog.Log.Information("{Line}", line),
merge: sp.GetRequiredService<IGameMerge>(),
busy: id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)
|| sp.GetRequiredService<IPartialSessionStore>().PendingGameIds().Contains(id)));
services.AddSingleton(static sp => new DetectionSweep(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IDetectionRulesSource>(),
sp.GetRequiredService<IGameFileProbe>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
static line => Serilog.Log.Information("{Line}", line)));
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<ExecutableRelocator>()));
// The anti-cheat pre-scan of the library (beta.8, 19_SAFETY §What a finding does to the game): every entry through
// the guard's advisory checks 3 and 4, again whenever the rules or the executable change. It waits while a session
// of the entry runs (the session's own checks are running then), and tells the App only when it turned hooking off
// for an entry the user had turned on. Hosted under --serve only, beside the detection sweep.
services.AddSingleton(static sp => new AntiCheatPreScanSweep(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IGameConsentStore>(),
sp.GetRequiredService<IAntiCheatGuard>(),
sp.GetRequiredService<IDetectionRulesSource>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<IIpcEventPublisher>(),
id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id),
// 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
@@ -150,32 +213,9 @@ 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();
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),
// Owner decision 2026-09-21: the per-game guard bypass is written through its own port, never the consent one.
sp.GetRequiredService<IGuardBypassStore>()));
services.AddSingleton(static sp => CommandHandler(sp));
services.AddSingleton<IIpcRequestHandler>(static sp => new AgentRequestHandler(
AgentIdentityFactory.OfThisProcess(sp.GetRequiredService<AgentPaths>().VkLayerDirectory),
AgentIdentityFactory.OfThisProcess(sp.GetRequiredService<AgentPaths>().VkLayerDirectory, sp.GetService<AgentElevationState>()?.Outcome),
TelemetryDescriptor(),
() => sp.GetRequiredService<SessionEventPublisher>().Status,
() => sp.GetRequiredService<AgentCommandHandler>()));
@@ -193,11 +233,48 @@ internal static class AgentServices
sp.GetRequiredService<IExecutableIdentitySource>(),
new OrchestratorOptions { PayloadPath = AgentPaths.Payload },
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<ILaunchRecorderFactory>()));
sp.GetRequiredService<ILaunchRecorderFactory>(),
sp.GetRequiredService<ExecutableRelocator>(),
sp.GetRequiredService<LatestProcessSnapshot>()));
services.AddSingleton<ILaunchRecorderFactory, AgentLaunches>();
}
/// <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
@@ -0,0 +1,61 @@
using System.Data.Common;
using FrameLedger.Application.AntiCheat;
using Microsoft.Extensions.Hosting;
using Serilog;
namespace FrameLedger.Agent.Hosting;
/// <summary>
/// <c>--serve</c> (beta.8, 2026-09-25): the anti-cheat pre-scan of the library on its own background task. One pass at
/// start, then one every <see cref="Interval"/>, and one as soon as <c>UpdateRules</c> re-seeds the rules file
/// (<see cref="AntiCheatPreScanSweep.RequestNow"/>). It reads executables' paths, install folders and the stores' own
/// files, and writes the pre-scan's hook-state columns of <c>games</c>; it never opens a game's process
/// (<c>19_SAFETY</c> §What a finding does to the game, CLAUDE.md rule 4).
/// </summary>
/// <remarks>
/// Its own task, like <see cref="DetectionHostedService"/>'s, because the guard's directory walk blocks on file I/O.
/// A pass that throws is logged and retried on the next tick rather than ending the service: a game's folder going away
/// mid-walk is ordinary, a busy ledger is a retry, and a service that throws stops the Agent's host.
/// </remarks>
internal sealed class AntiCheatPreScanHostedService(AntiCheatPreScanSweep sweep) : BackgroundService
{
/// <summary>The idle cadence, the detection sweep's: a game the App just added is scanned within it.</summary>
public static readonly TimeSpan Interval = TimeSpan.FromSeconds(15);
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
Log.Information("prescan: scanning the library for anti-cheat every {Seconds} s, and on every rules update", Interval.TotalSeconds);
while (!stoppingToken.IsCancellationRequested)
{
try
{
AntiCheatPreScanReport r = await sweep.SweepOnceAsync(stoppingToken).ConfigureAwait(false);
// Said when something happened: a pass over an unchanged library scans nothing and says nothing.
if (r.Scanned > 0 || r.RulesUnusable)
{
Log.Information("prescan: scanned {Scanned} — anti-cheat {Found}, clean {Clean}, could not verify {Unverified}; blocked {Blocked}, current {Current}{Rules}",
r.Scanned, r.Found, r.Clean, r.Unverified, r.Blocked, r.Current, r.RulesUnusable ? ", rules unusable" : string.Empty);
}
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
break;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidOperationException or DbException)
{
Log.Warning(ex, "prescan: pass did not complete; retrying on the next tick");
}
try
{
await sweep.WaitAsync(Interval, stoppingToken).ConfigureAwait(false);
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
break;
}
}
Log.Information("prescan: stopped");
}
}
@@ -1,3 +1,4 @@
using System.Data.Common;
using FrameLedger.Application.Detection;
using FrameLedger.Application.Vulkan;
using Microsoft.Extensions.Hosting;
@@ -15,7 +16,9 @@ namespace FrameLedger.Agent.Hosting;
/// Its own task because <c>GameFileProbe</c> blocks on file I/O (a bounded directory walk, an 8 MB strings pass):
/// the orchestrator's 1 Hz poll must not wait on it, and a session's drain must never share a thread with it.
/// A sweep that throws is logged and retried on the next tick rather than ending the service — a game's
/// directory going away mid-walk is ordinary, and one bad game must not stop the scan of the rest.
/// directory going away mid-walk is ordinary, and one bad game must not stop the scan of the rest. A database error
/// is one of those since 2026-09-23: the sweep writes rows (a relocation, a merge), a service that throws stops the
/// Agent's host (the Generic Host's default), and a busy or locked ledger is a retry, not a reason to stop capturing.
/// </remarks>
internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconciler layer) : BackgroundService
{
@@ -25,17 +28,22 @@ internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconc
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
Log.Information("detect: sweeping the library every {Seconds} s, and on every rules update", Interval.TotalSeconds);
DetectionSweepReport? previous = null;
while (!stoppingToken.IsCancellationRequested)
{
try
{
DetectionSweepReport r = await sweep.SweepOnceAsync(stoppingToken).ConfigureAwait(false);
if (r.Scanned > 0 || r.Unreadable > 0 || r.RulesUnusable)
// Said when something happened or changed (2026-09-23): an unreadable entry used to repeat this line every
// 15 s — 5,760 a day — with nothing new in it.
if (r.Scanned > 0 || r.Relocated > 0 || r.RulesUnusable || (r.Unreadable > 0 && r.Unreadable != previous?.Unreadable))
{
Log.Information("detect: sweep scanned {Scanned}, current {Current}, unreadable {Unreadable}{Rules}",
r.Scanned, r.Current, r.Unreadable, r.RulesUnusable ? ", rules unusable" : string.Empty);
}
previous = r;
// The layer follows the ledger after every sweep (P4 PR-2): a Vulkan fact that arrived after the
// consent, and the crash policy's auto-disable, both converge here within one interval.
_ = await layer.ReconcileAsync(stoppingToken).ConfigureAwait(false);
@@ -44,7 +52,7 @@ internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconc
{
break;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidOperationException)
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidOperationException or DbException)
{
Log.Warning(ex, "detect: sweep did not complete; retrying on the next tick");
}
@@ -14,16 +14,26 @@ namespace FrameLedger.Agent.Hosting;
/// a session somebody lost, and it becomes an <c>interrupted</c> row before any new session can write beside
/// it. Then the orchestrator polls until the host stops; its sessions finalize inside the host's shutdown
/// grace, and one that does not make it leaves its <c>.partial</c> for the next start — the same rule.
/// <b>Nothing recovery does can keep the watcher from starting (2026-09-23)</b>: the host's default for a background
/// service that throws is to stop the whole Agent, so a file recovery could not finalize would have stopped every start
/// after it. <see cref="PartialRecovery"/> no longer throws; the guard here is for what it cannot foresee.
/// </remarks>
internal sealed class WatcherHostedService(PartialRecovery recovery, CaptureOrchestrator orchestrator) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
IReadOnlyList<RecoveryOutcome> recovered = await recovery.RecoverAsync(stoppingToken).ConfigureAwait(false);
Log.Information("recover: {Count} pending .partial file(s)", recovered.Count);
foreach (RecoveryOutcome o in recovered)
try
{
Log.Information("recover: {Guid} {Status} {Detail}", o.SessionGuid.ToString("N"), o.Status, o.Detail);
IReadOnlyList<RecoveryOutcome> recovered = await recovery.RecoverAsync(stoppingToken).ConfigureAwait(false);
Log.Information("recover: {Count} pending .partial file(s)", recovered.Count);
foreach (RecoveryOutcome o in recovered)
{
Log.Information("recover: {Guid} {Status} {Detail}", o.SessionGuid.ToString("N"), o.Status, o.Detail);
}
}
catch (Exception ex) when (ex is not OperationCanceledException and not OutOfMemoryException)
{
Log.Warning(ex, "recover: did not complete; the watcher starts anyway and the files stay for the next start");
}
Log.Information("serve: watching the games table at 1 Hz; hooking only where a game is enabled and consented ({Elevation}, pid {Pid})",
+132 -28
View File
@@ -14,7 +14,12 @@
//
// The maintenance flags (P3 PR-8b) — --register-vklayer, --unregister-vklayer, --install-task, --uninstall-task —
// run over the product directory and exit; --diag is the App's (10_LOGGING) and answers "not implemented", exit 2.
//
// The admin mode (beta.10, owner decision D34): with capture.run_elevated on, a plain --serve that is not elevated — the
// logon task's — asks Windows once (a UAC prompt on the taskbar) to start an elevated Agent for this user and hands over to
// it; declined, it serves as before and says so. Decided before the folder is claimed or anything is written.
using System.Diagnostics;
using FrameLedger.Agent.Cli;
using FrameLedger.Agent.Composition;
using FrameLedger.Agent.Hosting;
@@ -51,6 +56,12 @@ internal static class Program
}
AgentPaths paths = cmd.DataDirectory is { } dir ? new AgentPaths(Path.GetFullPath(dir)) : AgentPaths.Default;
ElevationDecision elevation = cmd.Verb == AgentVerb.Serve ? await DecideElevationAsync(cmd, paths).ConfigureAwait(false) : ElevationDecision.NotAsked;
if (elevation.Exit is { } decided)
{
return decided;
}
using AgentInstanceLock? claim = ClaimDataDirectory(cmd.Verb, paths, out bool heldElsewhere);
if (heldElsewhere)
{
@@ -59,36 +70,11 @@ internal static class Program
ConfigureLogging(paths);
HookCrashHandlers(paths);
LogElevation(elevation);
try
{
// Before anything else. The guard reads this file on every evaluation and refuses every title
// when it is absent, so a capture started before the seed lands would fail for a reason that
// has nothing to do with the game (§S20).
RulesSeedOutcome seeded = await new RulesSeeder(new FileSystemRulesStore()).EnsureSeededAsync().ConfigureAwait(false);
AgentConsole.Line($"rules: {Describe(seeded)}");
Log.Information("rules: {Outcome}", seeded);
if (seeded is RulesSeedOutcome.WriteFailed or RulesSeedOutcome.PackagedSeedUnusable)
{
return _exitRulesFailed;
}
LedgerDatabase? db = await OpenLedgerOrSayWhyAsync(cmd.Verb, paths).ConfigureAwait(false);
if (db is null)
{
return cmd.Verb == AgentVerb.DbPath ? _exitOk : _exitLedgerRefused;
}
await using (db.ConfigureAwait(false))
{
return cmd.Verb switch
{
AgentVerb.Serve => await ServeAsync(db, paths).ConfigureAwait(false),
AgentVerb.RegisterVkLayer or AgentVerb.UnregisterVkLayer or AgentVerb.InstallTask or AgentVerb.UninstallTask =>
await new MaintenanceVerbs(db, paths).RunAsync(cmd).ConfigureAwait(false),
_ => await ConsoleAsync(cmd, db, paths).ConfigureAwait(false),
};
}
return await RunAsync(cmd, paths, elevation.Outcome).ConfigureAwait(false);
}
catch (Exception ex) when (ex is not OutOfMemoryException)
{
@@ -103,6 +89,38 @@ internal static class Program
}
}
/// <summary>The rules, the ledger and the verb, once the folder is claimed and the log is open.</summary>
private static async Task<int> RunAsync(AgentCommandLine cmd, AgentPaths paths, string? elevationOutcome)
{
// Before anything else. The guard reads this file on every evaluation and refuses every title
// when it is absent, so a capture started before the seed lands would fail for a reason that
// has nothing to do with the game (§S20).
RulesSeedOutcome seeded = await new RulesSeeder(new FileSystemRulesStore()).EnsureSeededAsync().ConfigureAwait(false);
AgentConsole.Line($"rules: {Describe(seeded)}");
Log.Information("rules: {Outcome}", seeded);
if (seeded is RulesSeedOutcome.WriteFailed or RulesSeedOutcome.PackagedSeedUnusable)
{
return _exitRulesFailed;
}
LedgerDatabase? db = await OpenLedgerOrSayWhyAsync(cmd.Verb, paths).ConfigureAwait(false);
if (db is null)
{
return cmd.Verb == AgentVerb.DbPath ? _exitOk : _exitLedgerRefused;
}
await using (db.ConfigureAwait(false))
{
return cmd.Verb switch
{
AgentVerb.Serve => await ServeAsync(db, paths, elevationOutcome).ConfigureAwait(false),
AgentVerb.RegisterVkLayer or AgentVerb.UnregisterVkLayer or AgentVerb.InstallTask or AgentVerb.UninstallTask =>
await new MaintenanceVerbs(db, paths).RunAsync(cmd).ConfigureAwait(false),
_ => await ConsoleAsync(cmd, db, paths).ConfigureAwait(false),
};
}
}
/// <summary>A usage error or a flag this binary does not implement is answered before any file is touched.</summary>
private static int? AnswerWithoutLogging(AgentCommandLine cmd)
{
@@ -164,6 +182,83 @@ internal static class Program
return claim;
}
/// <summary>What the admin mode decided at this start: the outcome <c>HelloAck</c> reports, and an exit code when this process stops here.</summary>
private sealed record ElevationDecision(string? Outcome, int? Exit, string? Detail)
{
public static readonly ElevationDecision NotAsked = new(null, null, null);
}
/// <summary>
/// The admin mode (beta.10, D34), before anything is claimed or written: an elevated Agent started for another account
/// stops (exit 11); an Agent told the answer was no says so; a plain <c>--serve</c> with the option on and no elevation —
/// the logon task's — asks Windows once and hands over to the elevated Agent, or carries on as a standard user's.
/// </summary>
private static async Task<ElevationDecision> DecideElevationAsync(AgentCommandLine cmd, AgentPaths paths)
{
if (cmd.ForUser is { } sid)
{
if (!AgentElevation.IsCurrentUser(sid))
{
// The prompt was answered with another account's credentials: its %LOCALAPPDATA% is not this user's ledger.
AgentConsole.Problem($"this elevated Agent runs as another account than the one that asked ({sid}); it exits (exit {AgentElevation.ExitOtherAccount})");
return new ElevationDecision(null, AgentElevation.ExitOtherAccount, null);
}
return new ElevationDecision(Environment.IsPrivilegedProcess ? AgentElevation.Granted : null, null, "started for this user by a UAC prompt");
}
if (cmd.ElevationRefusal is { } refusal)
{
return new ElevationDecision(refusal, null, "the process that started this Agent asked Windows and got: " + refusal);
}
if (Environment.IsPrivilegedProcess || !RunElevatedSetting.Read(paths.Database) || AgentInstanceLock.IsHeld(paths.DataDirectory))
{
// Elevated already (inherited), the option off, or an Agent already serves: nothing to ask; the claim decides the rest.
return ElevationDecision.NotAsked;
}
using ElevationMarker? marker = ElevationMarker.TryAcquire(paths.DataDirectory);
if (marker is null)
{
AgentConsole.Problem($"another FrameLedger Agent is being started as administrator for {paths.DataDirectory}; this one exits (exit {AgentInstanceLock.ExitHeldElsewhere})");
return new ElevationDecision(null, AgentInstanceLock.ExitHeldElsewhere, null);
}
string arguments = "--serve --for-user " + AgentElevation.CurrentUserSid();
using Process? elevated = AgentElevation.Start(Environment.ProcessPath ?? Path.Combine(AppContext.BaseDirectory, "FrameLedger.Agent.exe"),
arguments, ownerWindow: 0, out string? refused, out int? error);
if (elevated is null)
{
return new ElevationDecision(refused, null, $"the UAC prompt was {(string.Equals(refused, AgentElevation.Declined, StringComparison.Ordinal) ? "declined" : "not shown")} (error {error?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "none"})");
}
(bool claimed, int? code) = await AgentElevation.WaitForClaimAsync(elevated, paths.DataDirectory, TimeSpan.FromMinutes(2)).ConfigureAwait(false);
if (claimed)
{
// Handed over: the elevated Agent logs its own start; this one writes nothing and leaves.
return new ElevationDecision(null, _exitOk, null);
}
return code == AgentElevation.ExitOtherAccount
? new ElevationDecision(AgentElevation.OtherAccount, null, "the UAC prompt was answered with another account, whose Agent refused to run")
: new ElevationDecision(AgentElevation.Failed, null, $"the elevated Agent did not start serving (exit {code?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "none"})");
}
/// <summary>The decision in the log, and what an elevated Agent's token has enabled (read, never changed: TokenPrivileges).</summary>
private static void LogElevation(ElevationDecision elevation)
{
if (elevation.Outcome is { } outcome)
{
Log.Information("elevation: {Outcome} — {Detail}", outcome, elevation.Detail);
}
if (Environment.IsPrivilegedProcess)
{
Log.Information("elevation: this Agent runs as administrator; enabled privileges: {Privileges}", string.Join(", ", TokenPrivileges.Enabled()));
}
}
/// <summary>
/// Null when a print verb refuses the ledger — at another schema, or not there — said on the console and in the log
/// rather than as a crash: nothing about this machine is broken.
@@ -200,6 +295,9 @@ internal static class Program
Directory.CreateDirectory(paths.Logs);
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Information()
// The host's own lines reach this file since 2026-09-23 (ServeAsync's AddSerilog): its warnings and errors —
// a background service that stopped the host — not its start/stop chatter.
.MinimumLevel.Override("Microsoft", Serilog.Events.LogEventLevel.Warning)
.WriteTo.File(Path.Combine(paths.Logs, "agent-.log"), formatProvider: System.Globalization.CultureInfo.InvariantCulture,
rollingInterval: RollingInterval.Day, retainedFileCountLimit: 14)
.CreateLogger();
@@ -233,15 +331,21 @@ internal static class Program
}
/// <summary>The product's mode: a Generic Host around the watcher, stopped by Ctrl+C or the service manager.</summary>
private static async Task<int> ServeAsync(LedgerDatabase db, AgentPaths paths)
private static async Task<int> ServeAsync(LedgerDatabase db, AgentPaths paths, string? elevationOutcome)
{
HostApplicationBuilder builder = Host.CreateApplicationBuilder();
// The admin mode's answer at this start (beta.10), for HelloAck.
builder.Services.AddSingleton(new AgentElevationState(elevationOutcome));
// The host's log into agent-*.log (2026-09-23). A background service that threw stopped the host with nothing in
// the file: the Generic Host logs that through Microsoft.Extensions.Logging, which was never routed here.
builder.Services.AddSerilog();
// Before the composition, so its TryAdd keeps this one: Shutdown over the pipe stops the host (PR-1b).
builder.Services.AddSingleton<IAgentLifetime, HostAgentLifetime>();
builder.Services.AddFrameLedgerAgent(db, paths);
builder.Services.AddHostedService<WatcherHostedService>();
// The static detection sweep (P4 PR-1, 05_DETECTION §Caching): its own task, because the probe blocks on file I/O.
builder.Services.AddHostedService<DetectionHostedService>();
builder.Services.AddHostedService<AntiCheatPreScanHostedService>();
// The pipe (07_IPC §C), the product's UI channel: --serve only, never under --console (P3 PR-1).
builder.Services.AddHostedService<PipeServerHostedService>();
// Finalize's grace on shutdown (04_CAPTURE §Threading model): a session that does not make it leaves
+28 -16
View File
@@ -98,6 +98,7 @@ public partial class App : System.Windows.Application
ApplyCulture(appearance.Language);
var registered = new RegisteredSettings(store);
LoggingLevel.SetDebug(await registered.GetBooleanAsync(SettingsRegistry.LogDebug).ConfigureAwait(true));
FpsDecimals.Two = await registered.GetBooleanAsync(SettingsRegistry.UiFpsDecimals).ConfigureAwait(true);
var closePolicy = new WindowClosePolicy { MinimizeToTray = await registered.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true) };
_host = BuildHost(_db, appearance, registered, closePolicy);
@@ -244,8 +245,8 @@ public partial class App : System.Windows.Application
// THE SAFETY FAMILY TOO (2026-09-21). FrameLedger.Shared's Strings had no culture of its own and fell back to the
// thread's - and CurrentUICulture set inside this async start does not reach the dispatcher's later operations,
// so on an English Windows a Vietnamese UI showed the consent dialog, the refusal notices and the guard-bypass
// card in English (the owner's screenshot, beta.3). An explicit culture does not depend on which thread asks.
// so on an English Windows a Vietnamese UI showed the consent dialog and the refusal notices in English (the
// owner's screenshot, beta.3). An explicit culture does not depend on which thread asks.
Shared.Strings.Culture = culture;
}
@@ -268,20 +269,17 @@ public partial class App : System.Windows.Application
builder.Services.AddSingleton(closePolicy);
builder.Services.AddSingleton<IThemeApplier, WpfThemeApplier>();
// The Agent over the pipe (07_IPC §Client behavior): connect, start it when it is not there, tell the shell.
builder.Services.AddSingleton<IAgentLauncher, AgentLauncher>();
builder.Services.AddSingleton(static sp => new AgentConnection(
sp.GetRequiredService<IAgentLauncher>(),
static () => new PipeClient(),
new AgentConnectionOptions(),
UiIdentity.Version));
builder.Services.AddHostedService<AgentConnectionHostedService>();
builder.Services.AddSingleton<IAgentRequests>(static sp => sp.GetRequiredService<AgentConnection>());
builder.Services.AddSingleton<IAgentLink>(static sp => sp.GetRequiredService<AgentConnection>());
AddAgentLink(builder.Services);
// FR-2.1 (P3 PR-4): the consent dialog and the request it ends in; the toggle that opens it is the game page's (PR-5).
builder.Services.AddSingleton<IConsentPrompt, ConsentPrompt>();
builder.Services.AddSingleton<HookingConsent>();
// D33 (owner decision 2026-09-26): the user-mode exception's disclosure and the request it ends in; the list is
// Settings', the button on a blocked game's page.
builder.Services.AddSingleton<IAntiCheatExceptionPrompt, AntiCheatExceptionPrompt>();
// The admin mode's disclosure (beta.10, D34), shown before capture.run_elevated is turned on.
builder.Services.AddSingleton<IAgentAdminPrompt, AgentAdminPrompt>();
builder.Services.AddSingleton<AntiCheatExceptions>();
AddLibrary(builder.Services);
@@ -309,6 +307,24 @@ public partial class App : System.Windows.Application
return builder.Build();
}
/// <summary>The Agent over the pipe (07_IPC §Client behavior): connect, start it when it is not there, tell the shell.</summary>
private static void AddAgentLink(IServiceCollection services)
{
// The admin mode's prompt (beta.10) belongs to the main window; the handle is read when a start asks, never earlier.
services.AddSingleton<IAgentLauncher>(static sp => AgentLauncher.ForApp(() => sp.GetRequiredService<ShellHost>().Handle));
services.AddSingleton(static sp => new AgentConnection(
sp.GetRequiredService<IAgentLauncher>(),
static () => new PipeClient(),
new AgentConnectionOptions(),
UiIdentity.Version));
services.AddHostedService<AgentConnectionHostedService>();
services.AddSingleton<IAgentRequests>(static sp => sp.GetRequiredService<AgentConnection>());
services.AddSingleton<IAgentLink>(static sp => sp.GetRequiredService<AgentConnection>());
// What the Agent runs right now (2026-09-23), for the pages rebuilt on every visit; built before the connection's
// first round by AgentConnectionHostedService, so it never misses a session.
services.AddSingleton(static sp => new LiveSessions(sp.GetRequiredService<IAgentLink>()));
}
/// <summary>
/// The library (P3 PR-5): the ports the pages read and write, the selection that travels between pages, and the
/// pickers, prompts and confirmations behind interfaces so the view models are testable without a window.
@@ -327,10 +343,6 @@ public partial class App : System.Windows.Application
services.AddSingleton<IMessageStrip, SnackbarStrip>();
services.AddSingleton<IEditGamePrompt, EditGamePrompt>();
// The per-game guard bypass (owner decision 2026-09-21): its own disclosure, its own service, no global form.
services.AddSingleton<IGuardBypassPrompt, GuardBypassPrompt>();
services.AddSingleton<GuardBypass>();
// The session summary (P3 PR-6): the series loader over the ports, the exports' file picker, the window opener.
services.AddSingleton<IHardwareSnapshotRepository, SqliteHardwareSnapshotRepository>();
// Settings > System (2026-09-21): the same source the Agent stamps every session with, read for this PC now.
@@ -57,6 +57,25 @@ public sealed record ChartPalette(
return new ChartPalette(c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7], c[8], c[9], c[10], c[11], c[12]);
}
/// <summary>The colour a key names — how a chart that assigns palette entries to series by name reads them (<c>SensorsChart</c>).</summary>
public Color ByKey(string key) => key switch
{
"Chart_Figure" => Figure,
"Chart_Data" => Data,
"Chart_Axis" => Axis,
"Chart_Grid" => Grid,
"Chart_Native" => Native,
"Chart_Displayed" => Displayed,
"Chart_Stutter" => Stutter,
"Chart_StutterPso" => StutterPso,
"Chart_Sensor" => Sensor,
"Chart_SensorSecondary" => SensorSecondary,
"Chart_Segment" => Segment,
"Chart_Histogram" => Histogram,
"Chart_Percentile" => Percentile,
_ => throw new ArgumentOutOfRangeException(nameof(key), key, "not a chart palette key"),
};
private static ChartPalette Load(ApplicationTheme theme)
{
string file = theme == ApplicationTheme.Light ? "ChartPalette.Light.xaml" : "ChartPalette.Dark.xaml";
+35
View File
@@ -32,6 +32,41 @@ public static class ChartTheme
plot.Legend.FontColor = p.Axis;
}
/// <summary>
/// Save the plot as a PNG with an OPAQUE background (beta.8): on screen the figure is transparent over its card, but an
/// exported image has no card behind it, and a viewer painted its own colour under the theme's text — white axis labels
/// on a white page. The window's colour is painted for the file and the plot restored.
/// </summary>
public static void SavePng(Plot plot, string path, int width, int height)
{
ArgumentNullException.ThrowIfNull(plot);
ArgumentException.ThrowIfNullOrWhiteSpace(path);
Color figure = plot.FigureBackground.Color;
Color data = plot.DataBackground.Color;
Color window = ApplicationThemeManager.GetAppTheme() == ApplicationTheme.Light ? Color.FromHex("#F3F3F3") : Color.FromHex("#202020");
try
{
plot.FigureBackground.Color = Over(figure, window);
plot.DataBackground.Color = Over(data, Over(figure, window));
plot.SavePng(path, width, height);
}
finally
{
plot.FigureBackground.Color = figure;
plot.DataBackground.Color = data;
}
}
/// <summary>Source-over: <paramref name="top"/> composited on an opaque <paramref name="under"/>.</summary>
internal static Color Over(Color top, Color under)
{
double a = top.A / 255.0;
return new Color(
(byte)Math.Round((top.R * a) + (under.R * (1 - a))),
(byte)Math.Round((top.G * a) + (under.G * (1 - a))),
(byte)Math.Round((top.B * a) + (under.B * (1 - a))));
}
/// <summary>Registers a control so a theme change re-applies and refreshes it (weakly held; a closed window is forgotten).</summary>
public static void Attach(WpfPlot control)
{
@@ -44,8 +44,10 @@ public partial class CompareChart : UserControl
if (DrawnCurves > 0)
{
plot.Axes.SetLimitsX(0, 100);
// The percentile axis is 0–100 whatever the data: AutoScale first, then the X limits (beta.8 — the other way
// round, AutoScale undid them).
plot.Axes.AutoScale();
plot.Axes.SetLimitsX(0, 100);
plot.ShowLegend(Alignment.UpperRight);
}
@@ -1,10 +1,15 @@
<UserControl x:Class="FrameLedger.App.Charts.DistributionChart"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:sp="clr-namespace:ScottPlot.WPF;assembly=ScottPlot.WPF"
MinHeight="240">
<!-- FR-5.1: the FPS histogram and the percentile curve, side by side. -->
<!-- FR-5.1: the FPS histogram and the percentile curve, side by side; the note says what the histogram's range left out (beta.8). -->
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="*" />
<RowDefinition Height="Auto" />
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="12" />
@@ -12,5 +17,6 @@
</Grid.ColumnDefinitions>
<sp:WpfPlot x:Name="Histogram" Grid.Column="0" />
<sp:WpfPlot x:Name="Percentiles" Grid.Column="2" />
<ui:TextBlock x:Name="Note" Grid.Row="1" Grid.ColumnSpan="3" Margin="0,4,0,0" Appearance="Tertiary" TextWrapping="Wrap" Visibility="Collapsed" />
</Grid>
</UserControl>
@@ -1,3 +1,5 @@
using System.Globalization;
using System.Windows;
using System.Windows.Controls;
using ScottPlot;
using ScottPlot.Plottables;
@@ -7,8 +9,10 @@ namespace FrameLedger.App.Charts;
/// <summary>
/// FR-5.1's distribution: a histogram of instantaneous FPS over application frames, and the percentile curve —
/// FPS at each percentile of frametime under <c>03_METRICS</c>' linear method (<c>Domain.Metrics.Percentile</c>),
/// so the 1% and 0.1% lows on the stat cards are two points on this curve.
/// so the 1% and 0.1% lows on the stat cards are two points on this curve, marked where the session has the frames for
/// them (<see cref="PercentileCurve"/>).
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public partial class DistributionChart : UserControl
{
private const int _bins = 60;
@@ -22,38 +26,46 @@ public partial class DistributionChart : UserControl
public ScottPlot.Plot HistogramPlot => Histogram.Plot;
/// <summary>The percentile plot, for a test's look at its axis.</summary>
public ScottPlot.Plot PercentilePlot => Percentiles.Plot;
public void Show(SessionSeries? series)
{
DrawHistogram(series);
int outside = DrawHistogram(series);
DrawPercentiles(series);
Note.Text = outside > 0 ? string.Format(CultureInfo.CurrentCulture, Strings.Chart_Note_OutsideRange_Format, outside) : string.Empty;
Note.Visibility = outside > 0 ? Visibility.Visible : Visibility.Collapsed;
}
private void DrawHistogram(SessionSeries? series)
/// <summary>Draws the histogram; the frames its range left out.</summary>
private int DrawHistogram(SessionSeries? series)
{
ScottPlot.Plot plot = Histogram.Plot;
plot.Clear();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Fps);
plot.YLabel(Strings.Chart_Axis_Count);
int outside = 0;
if (series is { AppFrameTimesMs.Length: > 1 })
{
double[] fps = [.. series.AppFrameTimesMs.Where(static f => f > 0).Select(static f => 1000.0 / f)];
if (fps.Length > 1)
FpsHistogram histogram = FpsHistogram.Of(series.AppFrameTimesMs, _bins);
if (histogram.Centers.Length > 0)
{
var histogram = ScottPlot.Statistics.Histogram.WithBinCount(_bins, fps);
BarPlot bars = plot.Add.Bars(histogram.Bins, histogram.Counts.Select(static c => (double)c));
BarPlot bars = plot.Add.Bars(histogram.Centers, histogram.Counts);
bars.Color = ChartTheme.Current.Histogram;
foreach (Bar bar in bars.Bars)
{
bar.Size = histogram.FirstBinSize;
bar.Size = histogram.BinWidth;
bar.LineWidth = 0;
}
outside = histogram.Outside;
plot.Axes.AutoScale();
}
}
Histogram.Refresh();
return outside;
}
private void DrawPercentiles(SessionSeries? series)
@@ -66,11 +78,24 @@ public partial class DistributionChart : UserControl
if (series is { AppFrameTimesMs.Length: > 1 })
{
(double[] xs, double[] ys) = PercentileCurve.Of(series.AppFrameTimesMs);
Scatter line = plot.Add.ScatterLine(xs, ys, ChartTheme.Current.Percentile);
line.LineWidth = 2;
line.LegendText = Strings.Chart_Series_Percentile;
plot.Axes.SetLimitsX(0, 100);
if (xs.Length > 0)
{
Scatter line = plot.Add.ScatterLine(xs, ys, ChartTheme.Current.Percentile);
line.LineWidth = 2;
line.LegendText = Strings.Chart_Series_Percentile;
}
foreach ((double x, double fps, bool pointOne) in PercentileCurve.Lows(series.AppFrameTimesMs))
{
Scatter low = plot.Add.ScatterPoints(new[] { x }, new[] { fps }, ChartTheme.Current.Stutter);
low.MarkerSize = 7;
low.LegendText = pointOne ? Strings.Summary_Stat_P01Low : Strings.Summary_Stat_P1Low;
}
// The axis is 0–100 whatever the curve covers: AutoScale first, then the X limits (AutoScale afterwards undid them).
plot.Axes.AutoScale();
plot.Axes.SetLimitsX(0, 100);
plot.ShowLegend(Alignment.LowerLeft);
}
Percentiles.Refresh();
@@ -0,0 +1,54 @@
using FrameLedger.Domain.Metrics;
namespace FrameLedger.App.Charts;
/// <summary>
/// The distribution tab's histogram of instantaneous FPS over application frames (FR-5.1), binned over the 0.5th to the
/// 99.5th percentile and drawn at each bin's CENTRE (beta.8). Binned over min to max, one frame of a fraction of a
/// millisecond — a present that followed another by nothing — stretched the axis to thousands of FPS and squeezed every
/// real frame into two bars; and a bar is drawn centred on its position, where ScottPlot's bins are lower edges, so every
/// bar sat half a bin to the left of what it counted.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1819:Properties should not return arrays", Justification = "a data carrier for ScottPlot, which draws double[]")]
public sealed record FpsHistogram(double[] Centers, double[] Counts, double BinWidth, int Outside)
{
/// <summary>The share cut from each end before binning.</summary>
public const double TailFraction = 0.005;
public static FpsHistogram Of(IReadOnlyList<double> appFrameTimesMs, int bins = 60)
{
ArgumentNullException.ThrowIfNull(appFrameTimesMs);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(bins);
double[] fps = [.. appFrameTimesMs.Where(static f => f > 0).Select(static f => 1000.0 / f)];
if (fps.Length == 0)
{
return new FpsHistogram([], [], 0, 0);
}
IReadOnlyList<double> sorted = Percentile.Sorted(fps);
double lo = Percentile.Linear(sorted, TailFraction) ?? sorted[0];
double hi = Percentile.Linear(sorted, 1 - TailFraction) ?? sorted[^1];
if (hi - lo < 1e-9)
{
// Every frame at one rate: one bar, a frame per second wide, centred on it.
return new FpsHistogram([lo], [fps.Length], 1, 0);
}
double width = (hi - lo) / bins;
var counts = new double[bins];
int outside = 0;
foreach (double v in fps)
{
if (v < lo || v > hi)
{
outside++;
continue;
}
counts[Math.Min(bins - 1, (int)((v - lo) / width))]++;
}
double[] centers = [.. Enumerable.Range(0, bins).Select(b => lo + ((b + 0.5) * width))];
return new FpsHistogram(centers, counts, width, outside);
}
}
+11 -2
View File
@@ -1,8 +1,17 @@
<UserControl x:Class="FrameLedger.App.Charts.FrametimeChart"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:sp="clr-namespace:ScottPlot.WPF;assembly=ScottPlot.WPF"
MinHeight="260">
<!-- 08_UI §Session summary / FR-5.1: the frametime timeline, min/max decimated (FR-5.3); zoom and pan are ScottPlot's. -->
<sp:WpfPlot x:Name="Plot" />
<!-- 08_UI §Session summary / FR-5.1: the frametime timeline, min/max decimated (FR-5.3); zoom and pan are ScottPlot's.
The note above it says what the lines are not, when that is not obvious (beta.8). -->
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="*" />
</Grid.RowDefinitions>
<ui:TextBlock x:Name="Note" Grid.Row="0" Margin="0,0,0,4" Appearance="Tertiary" TextWrapping="Wrap" Visibility="Collapsed" />
<sp:WpfPlot x:Name="Plot" Grid.Row="1" />
</Grid>
</UserControl>
+107 -11
View File
@@ -1,3 +1,5 @@
using System.Globalization;
using System.Windows;
using System.Windows.Controls;
using ScottPlot;
using ScottPlot.Plottables;
@@ -5,13 +7,17 @@ using ScottPlot.Plottables;
namespace FrameLedger.App.Charts;
/// <summary>
/// The frametime timeline (FR-5.1, FR-5.3, FR-5.4, FR-5.5): the application-frame series by default, the
/// displayed (every present) series on request, stutter markers coloured by cause where the PSO count says so,
/// the segment ribbon as translucent spans, and the sensor overlay on the right axis. Series are min/max
/// decimated per draw; the raw arrays stay in the <see cref="SessionSeries"/>.
/// The frametime timeline (FR-5.1, FR-5.3, FR-5.4, FR-5.5): the application-frame series by default, every present on
/// request, stutter markers coloured by cause where the PSO count says so, the segment ribbon as translucent spans with
/// their settings named, and the sensor overlay on the right axis. Series are min/max decimated per draw; the raw arrays
/// stay in the <see cref="SessionSeries"/>.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public partial class FrametimeChart : UserControl
{
/// <summary>A segment narrower than this share of the axis keeps its shading and loses its label (the labels would overlap).</summary>
private const double _labelledSegmentShare = 0.12;
private SessionSeries? _series;
private bool _displayed;
private bool _sensors;
@@ -28,6 +34,9 @@ public partial class FrametimeChart : UserControl
/// <summary>How many points the last draw put on the axes (a test's window into the decimation).</summary>
public int DrawnPoints { get; private set; }
/// <summary>The note the last draw showed above the plot; empty when it had nothing to say.</summary>
public string NoteText => Note.Text;
public void Show(SessionSeries? series, bool displayed, bool sensors)
{
_series = series;
@@ -48,6 +57,37 @@ public partial class FrametimeChart : UserControl
Redraw();
}
/// <summary>
/// What the lines are not, when that is not obvious (beta.8): a session whose presents were all generated is charted as
/// presents; every present is timed at submission, which is not the display's cadence; and the overlay's sensors run ahead
/// of the frames past every gap the time axis closes up.
/// </summary>
internal static string NoteFor(SessionSeries? series, bool displayed, bool sensors)
{
if (series is null || series.Presents == 0)
{
return string.Empty;
}
var lines = new List<string>(2);
if (series.NoApplicationFrames)
{
lines.Add(Strings.Chart_Note_NoApplicationFrames);
}
else if (displayed && series.HasGenerated)
{
lines.Add(Strings.Chart_Note_PresentsTiming);
}
int gaps = series.Gap.Skip(1).Count(static g => g);
if (sensors && series.SensorsAligned && gaps > 0)
{
lines.Add(string.Format(CultureInfo.CurrentCulture, Strings.Chart_Note_GapsClosed_Format, gaps));
}
return string.Join(Environment.NewLine, lines);
}
private void Redraw()
{
ScottPlot.Plot plot = Plot.Plot;
@@ -56,6 +96,8 @@ public partial class FrametimeChart : UserControl
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Time);
plot.YLabel(Strings.Chart_Axis_Frametime);
Note.Text = NoteFor(_series, _displayed, _sensors);
Note.Visibility = Note.Text.Length > 0 ? Visibility.Visible : Visibility.Collapsed;
if (_series is null || _series.Presents == 0)
{
Plot.Refresh();
@@ -63,26 +105,33 @@ public partial class FrametimeChart : UserControl
}
ChartPalette p = ChartTheme.Current;
bool generating = _series.HasGenerated && !_series.NoApplicationFrames;
DrawSegments(plot, p);
if (_displayed && _series.HasGenerated)
if (_displayed && generating)
{
DrawSeries(plot, _series.TimesS, [.. _series.FrameTimesMs.Select(static f => (double)f)], p.Displayed, Strings.Chart_Series_Displayed);
DrawPresents(plot, p);
}
DrawSeries(plot, _series.AppTimesS, _series.AppFrameTimesMs, p.Native, Strings.Chart_Series_Native);
DrawSeries(plot, _series.AppTimesS, _series.AppFrameTimesMs, p.Native, generating ? Strings.Chart_Series_AppFrames : Strings.Chart_Series_Presents);
DrawStutter(plot, p);
if (_sensors)
if (_sensors && _series.SensorsAligned)
{
DrawSensors(plot, p);
}
plot.Axes.AutoScale();
LabelSegments(plot, p);
plot.ShowLegend(Alignment.UpperRight);
Plot.Refresh();
}
private void DrawSeries(ScottPlot.Plot plot, double[] xs, double[] ys, Color color, string label)
private void DrawSeries(ScottPlot.Plot plot, IReadOnlyList<double> xs, IReadOnlyList<double> ys, Color color, string label)
{
if (xs.Count == 0)
{
return;
}
(double[] dx, double[] dy) = Decimator.MinMax(xs, ys);
DrawnPoints += dx.Length;
SignalXY line = plot.Add.SignalXY(dx, dy, color);
@@ -90,6 +139,23 @@ public partial class FrametimeChart : UserControl
line.LegendText = label;
}
/// <summary>Every present but those after a gap, whose stored interval is 0 — not a frame, and it was drawn as a 0 ms one.</summary>
private void DrawPresents(ScottPlot.Plot plot, ChartPalette p)
{
var xs = new List<double>(_series!.Presents);
var ys = new List<double>(_series.Presents);
for (int i = 0; i < _series.Presents; i++)
{
if (!_series.Gap[i])
{
xs.Add(_series.TimesS[i]);
ys.Add(_series.FrameTimesMs[i]);
}
}
DrawSeries(plot, xs, ys, p.Displayed, Strings.Chart_Series_Displayed);
}
private void DrawStutter(ScottPlot.Plot plot, ChartPalette p)
{
if (_series?.Stutter is null)
@@ -152,6 +218,34 @@ public partial class FrametimeChart : UserControl
}
}
/// <summary>
/// Each segment's settings at its top-left corner (beta.8: the label was computed for every segment and drawn for none),
/// where the segment is wide enough to hold it. Placed after the axes are scaled, at their top.
/// </summary>
private void LabelSegments(ScottPlot.Plot plot, ChartPalette p)
{
if (_series is null || _series.Segments.Count < 2)
{
return;
}
AxisLimits limits = plot.Axes.GetLimits();
double width = limits.Right - limits.Left;
foreach (SegmentSpan segment in _series.Segments.Where(s => s.Label.Length > 0 && s.EndS - s.StartS >= width * _labelledSegmentShare))
{
Text label = plot.Add.Text(segment.Label, segment.StartS, limits.Top);
label.LabelFontSize = 11;
label.LabelFontColor = p.Axis;
label.LabelAlignment = Alignment.UpperLeft;
label.LabelOffsetX = 4;
label.LabelOffsetY = 4;
}
}
/// <summary>
/// GPU temperature and load on the right axis, over the frames' span only: the sensors sit on the frames' axis when the
/// blob said where the first present is (schema 0013), and ticks before it are the launch and the loading screen.
/// </summary>
private void DrawSensors(ScottPlot.Plot plot, ChartPalette p)
{
if (_series is null)
@@ -162,14 +256,16 @@ public partial class FrametimeChart : UserControl
IYAxis right = plot.Axes.Right;
right.Label.Text = Strings.Chart_Axis_Sensor;
int n = 0;
double end = _series.DurationS;
foreach (SensorSeries sensor in _series.Sensors.Where(static s => s.Name is "gpu_temp" or "gpu_load"))
{
if (sensor.TimesS.Length == 0)
int[] inside = [.. Enumerable.Range(0, sensor.TimesS.Length).Where(i => sensor.TimesS[i] >= 0 && sensor.TimesS[i] <= end)];
if (inside.Length == 0)
{
continue;
}
(double[] dx, double[] dy) = Decimator.MinMax(sensor.TimesS, sensor.Values, 1000);
(double[] dx, double[] dy) = Decimator.MinMax([.. inside.Select(i => sensor.TimesS[i])], [.. inside.Select(i => sensor.Values[i])], 1000);
DrawnPoints += dx.Length;
Scatter line = plot.Add.ScatterLine(dx, dy, n++ == 0 ? p.Sensor : p.SensorSecondary);
line.LineWidth = 1;
+63 -8
View File
@@ -2,9 +2,22 @@ using FrameLedger.Domain.Metrics;
namespace FrameLedger.App.Charts;
/// <summary>FPS at each percentile (0…100) of frametime, under <c>03_METRICS</c>' linear method — the distribution tab's curve and Compare's overlay.</summary>
/// <summary>
/// FPS at each percentile of frametime, under <c>03_METRICS</c>' linear method — the distribution tab's curve and Compare's
/// overlay — drawn only where the session has the frames to say it (beta.8).
/// </summary>
/// <remarks>
/// <b>A percentile is drawn when at least <see cref="FramesBeyond"/> frames lie beyond it on each side</b> — FR-4.8's rule
/// generalised: the 1% low (the 99th percentile) needs 1,000 frames and the 0.1% low (the 99.9th) 10,000, which is exactly
/// ten frames beyond each. The curve drew 0 to 100 whatever the count: its 100th point was the single worst frame, its 0th
/// the single shortest interval — thousands of FPS that set the axis for every other point — and its 99th was a 1% low the
/// stat card beside it refused to publish.
/// </remarks>
public static class PercentileCurve
{
/// <summary>Frames that must lie beyond a percentile, on each side, for it to be drawn.</summary>
public const int FramesBeyond = 10;
public static (double[] Xs, double[] Ys) Of(IReadOnlyList<double> appFrameTimesMs)
{
ArgumentNullException.ThrowIfNull(appFrameTimesMs);
@@ -14,15 +27,57 @@ public static class PercentileCurve
}
IReadOnlyList<double> sorted = Percentile.Sorted(appFrameTimesMs);
var xs = new double[101];
var ys = new double[101];
for (int i = 0; i <= 100; i++)
var xs = new List<double>(103);
var ys = new List<double>(103);
foreach (double p in Percents())
{
xs[i] = i;
double? ft = Percentile.Linear(sorted, i / 100.0);
ys[i] = ft is > 0 ? 1000.0 / ft.Value : 0;
if (Supported(sorted.Count, p) && Fps(sorted, p) is double fps)
{
xs.Add(p);
ys.Add(fps);
}
}
return (xs, ys);
return ([.. xs], [.. ys]);
}
/// <summary>The 1% and 0.1% lows as points on the curve (x 99 and 99.9), each only where the session has the frames for it.</summary>
public static IReadOnlyList<(double X, double Fps, bool PointOne)> Lows(IReadOnlyList<double> appFrameTimesMs)
{
ArgumentNullException.ThrowIfNull(appFrameTimesMs);
IReadOnlyList<double> sorted = Percentile.Sorted(appFrameTimesMs);
var lows = new List<(double, double, bool)>(2);
if (Supported(sorted.Count, 99) && Fps(sorted, 99) is double p1)
{
lows.Add((99, p1, false));
}
if (Supported(sorted.Count, 99.9) && Fps(sorted, 99.9) is double p01)
{
lows.Add((99.9, p01, true));
}
return lows;
}
/// <summary>At least <see cref="FramesBeyond"/> of <paramref name="frames"/> lie beyond <paramref name="percent"/> on each side.</summary>
public static bool Supported(int frames, double percent) =>
frames * Math.Min(percent, 100 - percent) / 100.0 >= FramesBeyond - 1e-9;
/// <summary>0, 0.1, 1 … 99, 99.9, 100 — in order, because the curve is drawn as a line through them.</summary>
private static IEnumerable<double> Percents()
{
yield return 0;
yield return 0.1;
for (int i = 1; i <= 99; i++)
{
yield return i;
}
yield return 99.9;
yield return 100;
}
private static double? Fps(IReadOnlyList<double> sorted, double percent) =>
Percentile.Linear(sorted, percent / 100.0) is > 0 and double ft ? 1000.0 / ft : null;
}
+85 -27
View File
@@ -5,12 +5,32 @@ using ScottPlot.Plottables;
namespace FrameLedger.App.Charts;
/// <summary>
/// The Sensors tab: GPU core / hotspot temperature and load / power on one plot (°C and % left, W right),
/// and VRAM on another — the game's own usage (the per-present <c>vram_proc</c> blob, a held 1 Hz sample)
/// and the adapter-wide figure (the <c>vram_adapter</c> sensor) as two differently-labelled series.
/// The Sensors tab: GPU core / hotspot temperature, load, CPU temperature and load on one plot (°C and % left) with the GPU's
/// power on a watt axis at the right, and memory on another — the game's own VRAM (the per-present <c>vram_proc</c> blob, a
/// held 1 Hz sample), the adapter-wide VRAM (the <c>vram_adapter</c> sensor) and the system's RAM as differently-labelled
/// series. Since beta.8 it draws a session that was not hooked too: its sensors are all it has.
/// </summary>
public partial class SensorsChart : UserControl
{
/// <summary>The temperatures-and-load plot's series, each with the palette key it is drawn in and whether it is on the watt axis.</summary>
internal static readonly IReadOnlyList<(string Series, string PaletteKey, bool Watts)> TempsPlot =
[
("gpu_temp", "Chart_Sensor", false),
("gpu_hotspot", "Chart_Stutter", false),
("gpu_load", "Chart_Native", false),
("gpu_power", "Chart_SensorSecondary", true),
("cpu_temp", "Chart_Percentile", false),
("cpu_load", "Chart_Displayed", false),
];
/// <summary>The memory plot's series and their palette keys; <c>vram_proc</c> is the per-present blob, the others sensors.</summary>
internal static readonly IReadOnlyList<(string Series, string PaletteKey)> MemoryPlot =
[
("vram_proc", "Chart_Displayed"),
("vram_adapter", "Chart_SensorSecondary"),
("ram_mb", "Chart_Percentile"),
];
public SensorsChart()
{
InitializeComponent();
@@ -20,29 +40,38 @@ public partial class SensorsChart : UserControl
public int DrawnSeries { get; private set; }
/// <summary>The temperatures plot, for a test's look at its axes.</summary>
public ScottPlot.Plot TempsPlotView => Temps.Plot;
public void Show(SessionSeries? series)
{
DrawnSeries = 0;
DrawTemps(series);
DrawVram(series);
DrawMemory(series);
}
/// <summary>The time axis says where its zero is: the first frame when the sensors sit on the frames' axis, the session's start otherwise.</summary>
internal static string TimeAxisLabel(SessionSeries? series) =>
series is { SensorsAligned: true, Presents: > 0 } ? Strings.Chart_Axis_TimeFromFirstFrame : Strings.Chart_Axis_TimeFromStart;
private void DrawTemps(SessionSeries? series)
{
ScottPlot.Plot plot = Temps.Plot;
plot.Clear();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Time);
plot.XLabel(TimeAxisLabel(series));
plot.YLabel(Strings.Chart_Axis_Sensor);
if (series is not null)
{
ChartPalette p = ChartTheme.Current;
Line(plot, series, "gpu_temp", Strings.Sensors_Series_GpuTemp, p.Sensor, null);
Line(plot, series, "gpu_hotspot", Strings.Sensors_Series_GpuHotspot, p.Stutter, null);
Line(plot, series, "gpu_load", Strings.Sensors_Series_GpuLoad, p.Native, null);
Line(plot, series, "gpu_power", Strings.Sensors_Series_GpuPower, p.SensorSecondary, plot.Axes.Right);
Line(plot, series, "cpu_temp", Strings.Sensors_Series_CpuTemp, p.Percentile, null);
Line(plot, series, "cpu_load", Strings.Sensors_Series_CpuLoad, p.Displayed, null);
foreach ((string name, string key, bool watts) in TempsPlot)
{
if (Line(plot, series, name, Label(name), p.ByKey(key), watts ? plot.Axes.Right : null) && watts)
{
plot.Axes.Right.Label.Text = Strings.Sensors_Axis_Watts;
}
}
plot.Axes.AutoScale();
plot.ShowLegend(Alignment.UpperRight);
}
@@ -50,28 +79,19 @@ public partial class SensorsChart : UserControl
Temps.Refresh();
}
private void DrawVram(SessionSeries? series)
private void DrawMemory(SessionSeries? series)
{
ScottPlot.Plot plot = Vram.Plot;
plot.Clear();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Chart_Axis_Time);
plot.XLabel(TimeAxisLabel(series));
plot.YLabel(Strings.Sensors_Axis_Mb);
if (series is not null)
{
ChartPalette p = ChartTheme.Current;
if (series.VramProcMb is { Length: > 0 } proc)
{
int n = Math.Min(proc.Length, series.TimesS.Length);
(double[] xs, double[] ys) = Decimator.MinMax(series.TimesS[..n], [.. proc.Take(n).Select(static v => (double)v)], 1000);
Scatter line = plot.Add.ScatterLine(xs, ys, p.Displayed);
line.LineWidth = 1;
line.LegendText = Strings.Sensors_Series_VramProcess;
DrawnSeries++;
}
Line(plot, series, "vram_adapter", Strings.Sensors_Series_VramAdapter, p.SensorSecondary, null);
Line(plot, series, "ram_mb", Strings.Sensors_Series_Ram, p.Percentile, null);
DrawProcessVram(plot, series, p.ByKey(MemoryPlot[0].PaletteKey));
Line(plot, series, "vram_adapter", Strings.Sensors_Series_VramAdapter, p.ByKey(MemoryPlot[1].PaletteKey), null);
Line(plot, series, "ram_mb", Strings.Sensors_Series_Ram, p.ByKey(MemoryPlot[2].PaletteKey), null);
plot.Axes.AutoScale();
plot.ShowLegend(Alignment.UpperRight);
}
@@ -79,12 +99,49 @@ public partial class SensorsChart : UserControl
Vram.Refresh();
}
private void Line(ScottPlot.Plot plot, SessionSeries series, string name, string label, Color color, IYAxis? axis)
/// <summary>
/// The game's own VRAM, per present on the frames' axis — a 0 is a present the sample did not reach (the record's zero,
/// SessionFinalizer.Series), never a reading, and is left out (beta.8).
/// </summary>
private void DrawProcessVram(ScottPlot.Plot plot, SessionSeries series, Color color)
{
if (series.VramProcMb is not { Length: > 0 } proc)
{
return;
}
int n = Math.Min(proc.Length, series.TimesS.Length);
int[] read = [.. Enumerable.Range(0, n).Where(i => proc[i] > 0)];
if (read.Length == 0)
{
return;
}
(double[] xs, double[] ys) = Decimator.MinMax([.. read.Select(i => series.TimesS[i])], [.. read.Select(i => (double)proc[i])], 1000);
Scatter line = plot.Add.ScatterLine(xs, ys, color);
line.LineWidth = 1;
line.LegendText = Strings.Sensors_Series_VramProcess;
DrawnSeries++;
}
private static string Label(string series) => series switch
{
"gpu_temp" => Strings.Sensors_Series_GpuTemp,
"gpu_hotspot" => Strings.Sensors_Series_GpuHotspot,
"gpu_load" => Strings.Sensors_Series_GpuLoad,
"gpu_power" => Strings.Sensors_Series_GpuPower,
"cpu_temp" => Strings.Sensors_Series_CpuTemp,
"cpu_load" => Strings.Sensors_Series_CpuLoad,
_ => series,
};
/// <summary>Draws one sensor series if the session has it; whether it did.</summary>
private bool Line(ScottPlot.Plot plot, SessionSeries series, string name, string label, Color color, IYAxis? axis)
{
SensorSeries? sensor = series.Sensors.FirstOrDefault(s => string.Equals(s.Name, name, StringComparison.Ordinal));
if (sensor is null || sensor.TimesS.Length == 0)
{
return;
return false;
}
(double[] xs, double[] ys) = Decimator.MinMax(sensor.TimesS, sensor.Values, 1000);
@@ -97,5 +154,6 @@ public partial class SensorsChart : UserControl
}
DrawnSeries++;
return true;
}
}
+46 -5
View File
@@ -1,15 +1,20 @@
namespace FrameLedger.App.Charts;
/// <summary>
/// A session's per-present series decoded for the charts and the export: every present in drained order with its
/// time from the session start, its interval, whether it was generated, whether a gap sat before it; the
/// application-frame view (non-generated, non-gap) with the stutter flags over it; the segments on the time
/// axis; the sensor series. Decoded once per window, decimated per draw.
/// A session's per-present series decoded for the charts and the export: every present of the charted stream in drained
/// order with its time from the stream's first present, its interval, whether it was generated, whether a gap sat before
/// it; the application-frame view with the stutter flags over it; the segments on the time axis; the sensor series.
/// Decoded once per window, decimated per draw.
/// </summary>
/// <remarks>
/// <b>One stream (beta.8).</b> A session that presented to more than one swapchain is charted on the one its statistics are
/// over (<c>SegmentBuilder.DominantStream</c>: identified first, then the most presents) — the stored intervals are per
/// swapchain, and interleaving two streams' intervals on one time axis drew neither.
/// </remarks>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1819:Properties should not return arrays", Justification = "a data carrier for the charts: ScottPlot draws double[] and a 500k-frame session is decimated per draw, not copied per read")]
public sealed record SessionSeries
{
/// <summary>Seconds from the first present, per present (a cumulative sum of the intervals).</summary>
/// <summary>Seconds from the stream's first present, per present (a cumulative sum of the intervals; a gap adds none).</summary>
public required double[] TimesS { get; init; }
/// <summary>The stored interval per present, ms; 0 on the first present and after a gap.</summary>
@@ -37,23 +42,59 @@ public sealed record SessionSeries
public ushort[]? RenderRes { get; init; }
// the application-frame view
/// <summary>The time of each application frame's present, seconds.</summary>
public required double[] AppTimesS { get; init; }
/// <summary>
/// Each application frame's time, ms: from the previous application frame's present to its own (beta.8) — the generated
/// presents between them add no interval, and a gap breaks the chain. Every present's interval where nothing was generated.
/// </summary>
public required double[] AppFrameTimesMs { get; init; }
/// <summary>Index into the per-present arrays for each application frame.</summary>
public required int[] AppPresentIndex { get; init; }
/// <summary>
/// Every present was generated — frame generation counted and no application frame's token arrived (the <c>no_evaluations</c>
/// refusal) — so the application-frame view is every present instead, and the chart says so.
/// </summary>
public bool NoApplicationFrames { get; init; }
/// <summary>Per application frame, from <c>Domain.Metrics.StutterDetector</c>; null when the session is too short for the window.</summary>
public bool[]? Stutter { get; init; }
public required IReadOnlyList<SegmentSpan> Segments { get; init; }
/// <summary>
/// The sensor series. On the frames' axis — seconds from the first present, negative before it — when
/// <see cref="SensorsAligned"/>; from the session's start otherwise.
/// </summary>
public required IReadOnlyList<SensorSeries> Sensors { get; init; }
/// <summary>
/// The sensors are placed on the frames' time axis: the blob said where the first present sits on the sensors' clock
/// (schema 0013). A session recorded before cannot draw them over its frames.
/// </summary>
public bool SensorsAligned { get; init; }
public int Presents => TimesS.Length;
public bool HasGenerated => Generated.Any(static g => g);
public double DurationS => TimesS.Length == 0 ? 0 : TimesS[^1];
/// <summary>A series with no frames: a session that was not hooked still has its sensors (beta.8).</summary>
public static SessionSeries SensorsOnly(IReadOnlyList<SensorSeries> sensors) => new()
{
TimesS = [],
FrameTimesMs = [],
Generated = [],
Gap = [],
AppTimesS = [],
AppFrameTimesMs = [],
AppPresentIndex = [],
Segments = [],
Sensors = sensors,
};
}
+139 -30
View File
@@ -6,10 +6,11 @@ using FrameLedger.Infrastructure.Blobs;
namespace FrameLedger.App.Charts;
/// <summary>
/// Decodes one session's blobs into a <see cref="SessionSeries"/>: the frametime series with the gap and
/// generated bits, the application-frame view with <c>StutterDetector</c> over it (the same rule the stored
/// <c>stutter_count</c> came from), the segments mapped from frame index to seconds, and the sensors aligned to
/// their <c>t_ms</c>. Null when the session has no frame blob (Tier 2, or swept by retention).
/// Decodes one session's blobs into a <see cref="SessionSeries"/>: the charted stream's frametime series with the gap
/// and generated bits, the application-frame view with <c>StutterDetector</c> over it (the rule the stored
/// <c>stutter_count</c> came from), the segments mapped from frame index to seconds, and the sensors. Null when the
/// session has no frame blob (Tier 2, or swept by retention); <see cref="LoadSensorsAsync"/> reads a Tier-2 session's
/// sensors on their own.
/// </summary>
public sealed class SessionSeriesLoader
{
@@ -30,61 +31,165 @@ public sealed class SessionSeriesLoader
return Decode(frames, segments, sensors);
}
/// <summary>
/// The sensor series alone, timed from the session's start — what a session that was not hooked has to chart (beta.8: the
/// Tier-2 row has kept its sensors since 2026-09-22, and no chart read them). Empty when none were recorded.
/// </summary>
public async Task<IReadOnlyList<SensorSeries>> LoadSensorsAsync(long sessionId, CancellationToken ct = default) =>
DecodeSensors(await _sessions.FindSensorsAsync(sessionId, ct).ConfigureAwait(false), offsetS: 0);
public static SessionSeries Decode(FrameBlobs frames, IReadOnlyList<SegmentRow> segments, IReadOnlyList<SensorBlob> sensors)
{
ArgumentNullException.ThrowIfNull(frames);
ArgumentNullException.ThrowIfNull(segments);
ArgumentNullException.ThrowIfNull(sensors);
float[] frametimes = SeriesCodec.DecodeFloat32(frames.FrameTimes.ToArray());
byte[] flags = SeriesCodec.DecodeBytes(frames.FrameFlags.ToArray());
int n = Math.Min(frametimes.Length, flags.Length);
float[] allFrametimes = SeriesCodec.DecodeFloat32(frames.FrameTimes.ToArray());
byte[] allFlags = SeriesCodec.DecodeBytes(frames.FrameFlags.ToArray());
int total = Math.Min(allFrametimes.Length, allFlags.Length);
uint[]? swapchains = frames.SwapchainIds is { } ids ? SeriesCodec.DecodeUInt32(ids.ToArray()) : null;
(int[] keep, uint? swapchain) = ChartedStream(total, swapchains);
float[] frametimes = Pick(allFrametimes, keep);
byte[] flags = Pick(allFlags, keep);
int n = keep.Length;
var times = new double[n];
var generated = new bool[n];
var gap = new bool[n];
double t = 0;
var appTimes = new List<double>(n);
var appFrametimes = new List<double>(n);
var appIndex = new List<int>(n);
for (int i = 0; i < n; i++)
{
t += frametimes[i] / 1000.0;
times[i] = t;
generated[i] = (flags[i] & (byte)FrameFlagBits.Generated) != 0;
gap[i] = (flags[i] & (byte)FrameFlagBits.Gap) != 0;
if (i > 0 && !generated[i] && !gap[i] && frametimes[i] > 0)
{
appTimes.Add(t);
appFrametimes.Add(frametimes[i]);
appIndex.Add(i);
}
}
(List<int> appIndex, List<double> appFrametimes, bool noApplicationFrames) = ApplicationFrames(frametimes, generated, gap);
StutterResult? stutter = StutterDetector.Detect(appFrametimes);
uint[]? frameIndex = frames.FrameIndex is { } fi ? SeriesCodec.DecodeUInt32(fi.ToArray()) : null;
uint[]? frameIndex = frames.FrameIndex is { } fi ? PickOptional(SeriesCodec.DecodeUInt32(fi.ToArray()), keep) : null;
double? offsetS = frames.FirstPresentMs / 1000.0;
return new SessionSeries
{
TimesS = times,
FrameTimesMs = frametimes.Length == n ? frametimes : frametimes[..n],
FrameTimesMs = frametimes,
Generated = generated,
Gap = gap,
FrameIndex = frameIndex,
RtFlags = frames.RtFlags is { } rt ? SeriesCodec.DecodeBytes(rt.ToArray()) : null,
DispatchRays = frames.DispatchRays is { } dr ? SeriesCodec.DecodeUInt32(dr.ToArray()) : null,
PsoCreated = frames.PsoCreated is { } pso ? SeriesCodec.DecodeUInt16(pso.ToArray()) : null,
VramProcMb = frames.VramProc is { } vram ? SeriesCodec.DecodeUInt32(vram.ToArray()) : null,
LatencyUs = frames.LatencyUs is { } lat ? SeriesCodec.DecodeUInt32(lat.ToArray()) : null,
RenderRes = frames.RenderRes is { } rr ? SeriesCodec.DecodeUInt16(rr.ToArray()) : null,
AppTimesS = [.. appTimes],
RtFlags = frames.RtFlags is { } rt ? PickOptional(SeriesCodec.DecodeBytes(rt.ToArray()), keep) : null,
DispatchRays = frames.DispatchRays is { } dr ? PickOptional(SeriesCodec.DecodeUInt32(dr.ToArray()), keep) : null,
PsoCreated = frames.PsoCreated is { } pso ? PickOptional(SeriesCodec.DecodeUInt16(pso.ToArray()), keep) : null,
VramProcMb = frames.VramProc is { } vram ? PickOptional(SeriesCodec.DecodeUInt32(vram.ToArray()), keep) : null,
LatencyUs = frames.LatencyUs is { } lat ? PickOptional(SeriesCodec.DecodeUInt32(lat.ToArray()), keep) : null,
RenderRes = frames.RenderRes is { } rr ? PickQuads(SeriesCodec.DecodeUInt16(rr.ToArray()), keep) : null,
AppTimesS = [.. appIndex.Select(i => times[i])],
AppFrameTimesMs = [.. appFrametimes],
AppPresentIndex = [.. appIndex],
NoApplicationFrames = noApplicationFrames,
Stutter = stutter is null ? null : [.. stutter.IsStutter],
Segments = MapSegments(segments, times, frameIndex),
Sensors = DecodeSensors(sensors),
Segments = MapSegments([.. segments.Where(s => swapchain is null || s.SwapchainId == swapchain.Value)], times, frameIndex),
Sensors = DecodeSensors(sensors, offsetS ?? 0),
SensorsAligned = offsetS is not null,
};
}
/// <summary>
/// The presents of the stream the charts draw — the one the session's statistics are over (<c>SegmentBuilder.DominantStream</c>:
/// identified first, then the most presents) — as indices into the blob, and that stream's id; every present, and no id,
/// when the blob held one stream.
/// </summary>
internal static (int[] Keep, uint? Swapchain) ChartedStream(int count, uint[]? swapchains)
{
if (swapchains is null || swapchains.Length < count)
{
return ([.. Enumerable.Range(0, count)], null);
}
IReadOnlyList<int> keep = SegmentBuilder.DominantStream([.. Enumerable.Range(0, count)], i => swapchains[i]);
return ([.. keep], keep.Count > 0 ? swapchains[keep[0]] : null);
}
/// <summary>
/// The application-frame view: each application frame's time is from the previous application frame's present to its own —
/// the generated presents between them add their intervals to it, never an interval of their own — and a gap breaks the
/// chain. Where every present was generated, every present's interval, and the flag that says so.
/// </summary>
internal static (List<int> Index, List<double> FrametimesMs, bool NoApplicationFrames) ApplicationFrames(float[] frametimes, bool[] generated, bool[] gap)
{
ArgumentNullException.ThrowIfNull(frametimes);
ArgumentNullException.ThrowIfNull(generated);
ArgumentNullException.ThrowIfNull(gap);
bool noApplicationFrames = generated.Length > 0 && generated.All(static g => g);
var index = new List<int>(frametimes.Length);
var ms = new List<double>(frametimes.Length);
bool chain = false;
double sinceApplicationFrame = 0;
for (int i = 0; i < frametimes.Length; i++)
{
if (gap[i])
{
chain = false;
sinceApplicationFrame = 0;
}
else
{
sinceApplicationFrame += frametimes[i];
}
if (generated[i] && !noApplicationFrames)
{
continue;
}
if (chain && sinceApplicationFrame > 0)
{
index.Add(i);
ms.Add(sinceApplicationFrame);
}
chain = true;
sinceApplicationFrame = 0;
}
return (index, ms, noApplicationFrames);
}
private static T[] Pick<T>(T[] values, int[] keep)
{
if (keep.Length == values.Length)
{
return values;
}
var picked = new T[keep.Length];
for (int i = 0; i < keep.Length; i++)
{
picked[i] = values[keep[i]];
}
return picked;
}
/// <summary>A per-present series the blob may have written shorter than the frames: only the kept presents it covers.</summary>
private static T[] PickOptional<T>(T[] values, int[] keep) => keep.Length == values.Length ? values : [.. keep.Where(i => i < values.Length).Select(i => values[i])];
private static ushort[] PickQuads(ushort[] values, int[] keep)
{
if (keep.Length * 4 == values.Length)
{
return values;
}
var picked = new List<ushort>(keep.Length * 4);
foreach (int i in keep.Where(i => (i * 4) + 3 < values.Length))
{
picked.AddRange(values.AsSpan(i * 4, 4).ToArray());
}
return [.. picked];
}
/// <summary>A segment's <c>start_frame</c>/<c>end_frame</c> are frame indices; the present at that index (or the nearest) gives the seconds.</summary>
private static IReadOnlyList<SegmentSpan> MapSegments(IReadOnlyList<SegmentRow> segments, double[] times, uint[]? frameIndex)
private static List<SegmentSpan> MapSegments(IReadOnlyList<SegmentRow> segments, double[] times, uint[]? frameIndex)
{
if (times.Length == 0)
{
@@ -125,7 +230,11 @@ public sealed class SessionSeriesLoader
return string.Join(" · ", new[] { upscaler, resolution, fg }.Where(static x => x.Length > 0));
}
private static List<SensorSeries> DecodeSensors(IReadOnlyList<SensorBlob> sensors)
/// <summary>
/// Every sensor series against <c>t_ms</c> less <paramref name="offsetS"/> — the first present's place on the sensors'
/// clock, so they share the frames' axis (schema 0013) — and −1 dropped: a tick with no reading, never a zero.
/// </summary>
private static List<SensorSeries> DecodeSensors(IReadOnlyList<SensorBlob> sensors, double offsetS)
{
SensorBlob? clock = sensors.FirstOrDefault(static s => string.Equals(s.Series, "t_ms", StringComparison.Ordinal));
float[]? tMs = clock is null ? null : SeriesCodec.DecodeFloat32(clock.Data.ToArray());
@@ -147,7 +256,7 @@ public sealed class SessionSeriesLoader
continue; // SessionFinalizer.SensorMissing: a tick with no reading, never a zero
}
xs.Add(tMs is not null && i < tMs.Length ? tMs[i] / 1000.0 : i / Math.Max(blob.Hz, 0.001));
xs.Add((tMs is not null && i < tMs.Length ? tMs[i] / 1000.0 : i / Math.Max(blob.Hz, 0.001)) - offsetS);
ys.Add(values[i]);
}
+21 -2
View File
@@ -17,17 +17,23 @@ public partial class TrendChart : UserControl
public int DrawnPoints { get; private set; }
/// <summary>How many of <see cref="DrawnPoints"/> were drawn hollow (a part of their session).</summary>
public int HollowPoints { get; private set; }
public void Show(IReadOnlyList<TrendPoint> points, IReadOnlyList<HardwareChange> changes, string metricLabel)
{
ArgumentNullException.ThrowIfNull(points);
ArgumentNullException.ThrowIfNull(changes);
ScottPlot.Plot plot = Plot.Plot;
plot.Clear();
// The date axis REPLACES the bottom axis, so it goes first (beta.8): made after the theme and the label, it dropped
// both — an unlabelled axis in the default colours, unreadable in the dark theme.
plot.Axes.DateTimeTicksBottom();
ChartTheme.Apply(plot);
plot.XLabel(Strings.Trend_Axis_Date);
plot.YLabel(metricLabel);
plot.Axes.DateTimeTicksBottom();
DrawnPoints = points.Count;
HollowPoints = points.Count(static t => t.SettingsChangedMidSession);
if (points.Count > 0)
{
ChartPalette p = ChartTheme.Current;
@@ -37,7 +43,20 @@ public partial class TrendChart : UserControl
line.LineWidth = 2;
line.MarkerSize = 7;
line.LegendText = metricLabel;
foreach (HardwareChange change in changes)
// A point that describes part of its session (settings changed, or a steady state) is drawn hollow over its
// filled one: the line still passes through it, and it cannot be read as the session's own number.
TrendPoint[] partial = [.. points.Where(static t => t.SettingsChangedMidSession)];
if (partial.Length > 0)
{
double[] hx = [.. partial.Select(static t => t.At.LocalDateTime.ToOADate())];
double[] hy = [.. partial.Select(static t => t.Value)];
Scatter hollow = plot.Add.ScatterPoints(hx, hy, p.Data);
hollow.MarkerSize = 6;
hollow.MarkerShape = MarkerShape.FilledCircle;
}
foreach (HardwareChange change in TrendSeriesBuilder.MergedByDay(changes))
{
VerticalLine marker = plot.Add.VerticalLine(change.At.LocalDateTime.ToOADate(), 1, p.StutterPso, LinePattern.Dashed);
marker.LabelText = change.Text;
+21 -2
View File
@@ -3,8 +3,15 @@ namespace FrameLedger.App.Charts;
/// <summary>The Trend tab's selector (<c>08_UI</c> §Games › Trend).</summary>
public enum TrendMetric
{
/// <summary>Native FPS where frame generation was measured; Presented FPS where it was not (the row's headline, per <c>03_METRICS</c> Avg FPS).</summary>
Average,
/// <summary>
/// Presented FPS — every frame presented — on the sessions where no generated frame was counted (beta.8: "Average" mixed
/// it with Native in one line). A session that counted generated frames has none here: its presented rate includes them,
/// the single inflated number CLAUDE.md rule 6 forbids; it is on <see cref="NativeFps"/> and <see cref="Displayed"/>.
/// </summary>
PresentedFps,
/// <summary>Native FPS — the game's own frames — only where frame generation was measured (counted, or measured none).</summary>
NativeFps,
/// <summary>Displayed FPS — only sessions that measured frame generation have one.</summary>
Displayed,
@@ -33,4 +40,16 @@ public enum TrendMetric
/// of the session, so it is treated as a mid-session change: left out by default, drawn marked when those are included.
/// </summary>
FgFactor,
/// <summary>
/// The three below are beta.10's (<c>03_METRICS</c> §Display mode): the share of the session's observed time in a mode,
/// every session whatever its tier — the window is read out of process. Exclusive fullscreen and borderless have a point
/// only where the whole observed time could be told apart; a window that covered its monitor while nothing could ask the
/// swap chain counts as neither.
/// </summary>
DisplayExclusiveShare,
DisplayBorderlessShare,
DisplayWindowedShare,
}
@@ -2,15 +2,21 @@ using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using FrameLedger.App.Services;
using FrameLedger.Application.Persistence;
using FrameLedger.Domain.Display;
using FrameLedger.Domain.Sessions;
namespace FrameLedger.App.Charts;
/// <summary>
/// The Trend tab's data (FR-6.3, FR-6.4): one point per hooked session that has the metric, oldest first, with
/// the sessions that changed settings mid-session excluded unless asked for; and a marker wherever two
/// consecutive sessions' hardware snapshots differ in what a reader would want to know about.
/// The Trend tab's data (FR-6.3, FR-6.4): one point per session that has the metric, oldest first, with the points that
/// describe only part of their session excluded unless asked for; and a marker wherever two consecutive sessions'
/// hardware snapshots differ in what a reader would want to know about.
/// </summary>
/// <remarks>
/// <b>Which sessions (beta.8).</b> A frame-rate metric is the hooks' and comes from hooked sessions only; a machine metric
/// — temperatures, loads, power, memory — is the telemetry every session records, Tier 2 included, which the trend left
/// out until 2026-09-25 (a game never hooked had no trend at all).
/// </remarks>
[SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format string is a resource that follows the UI culture, which changes at runtime")]
public static class TrendSeriesBuilder
{
@@ -18,7 +24,7 @@ public static class TrendSeriesBuilder
{
ArgumentNullException.ThrowIfNull(rows);
var points = new List<TrendPoint>();
foreach (SessionRow row in rows.Where(static r => r.Tier == CaptureTier.Hooked).OrderBy(static r => r.StartedAt))
foreach (SessionRow row in rows.Where(r => Counts(r, metric)).OrderBy(static r => r.StartedAt))
{
bool partial = IsPartial(row, metric);
if (partial && !includeMidSessionChanges)
@@ -37,12 +43,30 @@ public static class TrendSeriesBuilder
}
/// <summary>How many sessions FR-6.4 leaves out at the default setting.</summary>
public static int ExcludedCount(IReadOnlyList<SessionRow> rows) => ExcludedCount(rows, TrendMetric.Average);
public static int ExcludedCount(IReadOnlyList<SessionRow> rows) => ExcludedCount(rows, TrendMetric.PresentedFps);
/// <summary>
/// Whether a session can have a point for <paramref name="metric"/>: a frame rate needs the hooks; the machine is every
/// session's, and so is the display mode (beta.10) — the window is read out of process whether or not anything was hooked.
/// </summary>
public static bool Counts(SessionRow row, TrendMetric metric)
{
ArgumentNullException.ThrowIfNull(row);
return row.Tier == CaptureTier.Hooked || IsMachineMetric(metric) || IsDisplayMetric(metric);
}
/// <summary>The display-mode shares (beta.10).</summary>
public static bool IsDisplayMetric(TrendMetric metric) =>
metric is TrendMetric.DisplayExclusiveShare or TrendMetric.DisplayBorderlessShare or TrendMetric.DisplayWindowedShare;
/// <summary>The metrics that are telemetry, recorded by every session whatever its tier.</summary>
public static bool IsMachineMetric(TrendMetric metric) => metric is TrendMetric.MaxGpuTemp or TrendMetric.AvgGpuLoad or TrendMetric.AvgGpuPower
or TrendMetric.AvgCpuLoad or TrendMetric.MaxCpuTemp or TrendMetric.AvgRam;
public static int ExcludedCount(IReadOnlyList<SessionRow> rows, TrendMetric metric)
{
ArgumentNullException.ThrowIfNull(rows);
return rows.Count(r => r.Tier == CaptureTier.Hooked && IsPartial(r, metric));
return rows.Count(r => Counts(r, metric) && IsPartial(r, metric) && ValueOf(r, metric) is not null);
}
/// <summary>
@@ -52,8 +76,18 @@ public static class TrendSeriesBuilder
public static bool IsPartial(SessionRow row, TrendMetric metric)
{
ArgumentNullException.ThrowIfNull(row);
// A display share is the whole session's by construction (beta.10): switching between fullscreen and a window resizes
// the swap chain, which is exactly what marks a session "settings changed" — the share is what that change was.
if (IsDisplayMetric(metric))
{
return false;
}
// A steady state (CLAUDE.md rule 6, 2026-09-17) is the factor's AND the Native / Displayed rates beside it: all three
// describe the state the session spent most of its generating time in, never the whole session (beta.8).
return row.SettingsChangedMidSession
|| (metric == TrendMetric.FgFactor && string.Equals(row.FgFactorScope, "steady", StringComparison.Ordinal));
|| (metric is TrendMetric.FgFactor or TrendMetric.NativeFps or TrendMetric.Displayed
&& string.Equals(row.FgFactorScope, "steady", StringComparison.Ordinal));
}
/// <summary>The metric's value on a row, or null when that row cannot have it (FR-4.9: never an estimate).</summary>
@@ -63,9 +97,11 @@ public static class TrendSeriesBuilder
FpsReadoutModel readout = FpsPresentation.FromRow(row);
return metric switch
{
TrendMetric.Average => readout.Kind switch
TrendMetric.NativeFps => readout.Kind is FpsReadoutKind.Generated or FpsReadoutKind.None ? readout.Native : null,
TrendMetric.PresentedFps => readout.Kind switch
{
FpsReadoutKind.Generated or FpsReadoutKind.None => readout.Native,
// A measured none: the presents are the application's frames, so the rate is both.
FpsReadoutKind.None => readout.Native,
FpsReadoutKind.Presented or FpsReadoutKind.IdentifiedUncounted => readout.Presented,
_ => null,
},
@@ -80,10 +116,38 @@ public static class TrendSeriesBuilder
TrendMetric.MaxCpuTemp => row.MaxCpuTemp,
TrendMetric.AvgRam => row.AvgRamMb,
TrendMetric.FgFactor => readout.Kind == FpsReadoutKind.Generated ? readout.Factor : null,
TrendMetric.DisplayExclusiveShare => DisplayShare(row, DisplayMode.ExclusiveFullscreen),
TrendMetric.DisplayBorderlessShare => DisplayShare(row, DisplayMode.Borderless),
TrendMetric.DisplayWindowedShare => DisplayShare(row, DisplayMode.Windowed),
_ => null,
};
}
/// <summary>
/// A mode's share of the session's observed time (0–100), or null: no display facts on the row, no window ever read, or —
/// for exclusive fullscreen and borderless — time the two could not be told apart, which would make either share a guess.
/// </summary>
private static double? DisplayShare(SessionRow row, DisplayMode mode)
{
if (DisplayText.Of(row) is not { ObservedMs: > 0 } display)
{
return null;
}
return mode is DisplayMode.ExclusiveFullscreen or DisplayMode.Borderless && !display.ExclusivityKnown ? null : display.SharePercent(mode);
}
/// <summary>
/// One marker per day that changed (beta.8): every difference found on that day in one label, line after line — two
/// labels at one position were drawn over each other.
/// </summary>
public static IReadOnlyList<HardwareChange> MergedByDay(IReadOnlyList<HardwareChange> changes)
{
ArgumentNullException.ThrowIfNull(changes);
return [.. changes.GroupBy(static c => c.At.LocalDateTime.Date)
.Select(static g => new HardwareChange(g.First().At, string.Join(Environment.NewLine, g.Select(static c => c.Text).Distinct(StringComparer.Ordinal))))];
}
/// <summary>Markers between consecutive sessions (oldest first) whose snapshots differ; <paramref name="snapshotOf"/> resolves a row's snapshot id.</summary>
public static IReadOnlyList<HardwareChange> Changes(IReadOnlyList<SessionRow> rows, Func<long, HardwareSnapshot?> snapshotOf)
{
@@ -0,0 +1,35 @@
<UserControl x:Class="FrameLedger.App.Dialogs.AgentAdminDialogContent"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
d:DataContext="{d:DesignInstance Type=vm:AgentAdminDialogViewModel}"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
MaxWidth="640">
<!--
The admin mode's disclosure (beta.10, D34; 19_SAFETY §Elevated targets), text from FrameLedger.Shared's
Safety_AdminMode_* only, versioned by AgentAdminDisclosure.Version. It states what the option adds, what it does not
change, how Windows asks, and the risk; every colour is a theme brush.
-->
<ScrollViewer MaxHeight="520" VerticalScrollBarVisibility="Auto">
<StackPanel>
<ui:TextBlock Text="{x:Static vm:AgentAdminDialogViewModel.Intro}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,14,0,0" Text="{x:Static vm:AgentAdminDialogViewModel.Adds}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" Text="{x:Static vm:AgentAdminDialogViewModel.Unchanged}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" Text="{x:Static vm:AgentAdminDialogViewModel.Prompt}" TextWrapping="Wrap" />
<Border Margin="0,14,0,0" Padding="12" CornerRadius="6" Background="{DynamicResource CardBackgroundFillColorDefaultBrush}">
<ui:TextBlock FontWeight="SemiBold" Text="{x:Static vm:AgentAdminDialogViewModel.Risk}" TextWrapping="Wrap" />
</Border>
<CheckBox x:Name="Acceptance"
Margin="0,18,0,0"
AutomationProperties.Name="{x:Static vm:AgentAdminDialogViewModel.AcceptText}"
Content="{x:Static vm:AgentAdminDialogViewModel.AcceptText}"
IsChecked="{Binding Accepted, Mode=TwoWay}" />
<ui:TextBlock Margin="0,12,0,0" HorizontalAlignment="Right" Appearance="Tertiary" Text="{x:Static vm:AgentAdminDialogViewModel.Version}" />
</StackPanel>
</ScrollViewer>
</UserControl>
@@ -0,0 +1,18 @@
using System.Windows.Controls;
using FrameLedger.App.ViewModels;
namespace FrameLedger.App.Dialogs;
/// <summary>The body of the admin mode's <c>ContentDialog</c>; the buttons are the dialog's own (<see cref="Services.AgentAdminPrompt"/>).</summary>
public partial class AgentAdminDialogContent : UserControl
{
public AgentAdminDialogContent(AgentAdminDialogViewModel viewModel)
{
ViewModel = viewModel ?? throw new ArgumentNullException(nameof(viewModel));
DataContext = viewModel;
InitializeComponent();
Loaded += (_, _) => Acceptance.Focus();
}
public AgentAdminDialogViewModel ViewModel { get; }
}
@@ -0,0 +1,37 @@
<UserControl x:Class="FrameLedger.App.Dialogs.AntiCheatExceptionDialogContent"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
d:DataContext="{d:DesignInstance Type=vm:AntiCheatExceptionDialogViewModel}"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
MaxWidth="640">
<!--
D33's disclosure (19_SAFETY §The user-mode exception), text from FrameLedger.Shared's Safety_Exception_* only,
versioned by AntiCheatExceptionDisclosure.Version. It states why the exception is offered, the risk, what is still
refused, how it ends, and that it turns nothing on; it recommends neither choice. Every colour is a theme brush.
-->
<ScrollViewer MaxHeight="520" VerticalScrollBarVisibility="Auto">
<StackPanel>
<ui:TextBlock Text="{Binding Intro}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,14,0,0" Text="{Binding Why}" TextWrapping="Wrap" />
<Border Margin="0,14,0,0" Padding="12" CornerRadius="6" Background="{DynamicResource CardBackgroundFillColorDefaultBrush}">
<ui:TextBlock FontWeight="SemiBold" Text="{Binding Risk}" TextWrapping="Wrap" />
</Border>
<ui:TextBlock Margin="0,14,0,0" Text="{Binding Still}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" Text="{x:Static vm:AntiCheatExceptionDialogViewModel.Ends}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" Text="{x:Static vm:AntiCheatExceptionDialogViewModel.Next}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,8,0,0" FontWeight="SemiBold" Text="{x:Static vm:AntiCheatExceptionDialogViewModel.Online}" TextWrapping="Wrap" />
<CheckBox x:Name="Acceptance"
Margin="0,18,0,0"
AutomationProperties.Name="{x:Static vm:AntiCheatExceptionDialogViewModel.AcceptText}"
Content="{x:Static vm:AntiCheatExceptionDialogViewModel.AcceptText}"
IsChecked="{Binding Accepted, Mode=TwoWay}" />
</StackPanel>
</ScrollViewer>
</UserControl>
@@ -0,0 +1,18 @@
using System.Windows.Controls;
using FrameLedger.App.ViewModels;
namespace FrameLedger.App.Dialogs;
/// <summary>The body of D33's <c>ContentDialog</c>; the buttons are the dialog's own (<see cref="Services.AntiCheatExceptionPrompt"/>).</summary>
public partial class AntiCheatExceptionDialogContent : UserControl
{
public AntiCheatExceptionDialogContent(AntiCheatExceptionDialogViewModel viewModel)
{
ViewModel = viewModel ?? throw new ArgumentNullException(nameof(viewModel));
DataContext = viewModel;
InitializeComponent();
Loaded += (_, _) => Acceptance.Focus();
}
public AntiCheatExceptionDialogViewModel ViewModel { get; }
}
@@ -1,43 +0,0 @@
<UserControl x:Class="FrameLedger.App.Dialogs.GuardBypassDialogContent"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
d:DataContext="{d:DesignInstance Type=vm:GuardBypassDialogViewModel}"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
MaxWidth="660">
<!--
The guard-bypass disclosure (owner decision 2026-09-21, 19_SAFETY §The user's bypass). Text from
FrameLedger.Shared's Safety_Bypass_* only. Order: what the switch is, what the guard found, what can happen, who
carries it, what is recorded, then the two acts. The risk and the liability paragraphs sit on the theme's
critical fill with primary text (a pair ContrastTests measures); every colour is a theme brush (16_WPFUI §Theming).
-->
<ScrollViewer MaxHeight="540" VerticalScrollBarVisibility="Auto">
<StackPanel>
<ui:TextBlock Text="{x:Static vm:GuardBypassDialogViewModel.Intro}" TextWrapping="Wrap" />
<ui:TextBlock Margin="0,12,0,0" FontWeight="SemiBold" Text="{Binding Found}" TextWrapping="Wrap" />
<Border Margin="0,14,0,0" Padding="12" CornerRadius="6" Background="{DynamicResource SystemFillColorCriticalBackgroundBrush}">
<ui:TextBlock Foreground="{DynamicResource TextFillColorPrimaryBrush}" Text="{x:Static vm:GuardBypassDialogViewModel.Risk}" TextWrapping="Wrap" />
</Border>
<Border Margin="0,8,0,0" Padding="12" CornerRadius="6" Background="{DynamicResource SystemFillColorCriticalBackgroundBrush}">
<ui:TextBlock Foreground="{DynamicResource TextFillColorPrimaryBrush}" FontWeight="SemiBold" Text="{x:Static vm:GuardBypassDialogViewModel.Liability}" TextWrapping="Wrap" />
</Border>
<ui:TextBlock Margin="0,12,0,0" Text="{x:Static vm:GuardBypassDialogViewModel.Recorded}" TextWrapping="Wrap" />
<CheckBox Margin="0,16,0,0" IsChecked="{Binding Acknowledged, Mode=TwoWay}"
AutomationProperties.Name="{x:Static vm:GuardBypassDialogViewModel.CheckboxText}">
<TextBlock Text="{x:Static vm:GuardBypassDialogViewModel.CheckboxText}" TextWrapping="Wrap" MaxWidth="600" />
</CheckBox>
<ui:TextBlock Margin="0,14,0,6" Appearance="Secondary" Text="{Binding TypeToConfirm}" TextWrapping="Wrap" />
<ui:TextBox AutomationProperties.Name="{Binding TypeToConfirm}"
Text="{Binding Typed, UpdateSourceTrigger=PropertyChanged}"
PlaceholderText="{x:Static vm:GuardBypassDialogViewModel.Phrase}" />
</StackPanel>
</ScrollViewer>
</UserControl>
@@ -1,16 +0,0 @@
using System.Windows.Controls;
using FrameLedger.App.ViewModels;
namespace FrameLedger.App.Dialogs;
public partial class GuardBypassDialogContent : UserControl
{
public GuardBypassDialogContent(GuardBypassDialogViewModel viewModel)
{
ViewModel = viewModel ?? throw new ArgumentNullException(nameof(viewModel));
DataContext = viewModel;
InitializeComponent();
}
public GuardBypassDialogViewModel ViewModel { get; }
}
@@ -45,6 +45,8 @@
<EmbeddedResource Include="..\..\legal\DISCLAIMER.md" LogicalName="legal/DISCLAIMER.md" />
<EmbeddedResource Include="..\..\legal\PRIVACY_POLICY.md" LogicalName="legal/PRIVACY_POLICY.md" />
<EmbeddedResource Include="..\..\LICENSE" LogicalName="LICENSE" />
<!-- beta.10 (D36): what the whole software cannot do, shown under Help > Limitations; information, not one of FR-11's accepted documents. -->
<EmbeddedResource Include="..\..\LIMITATIONS.md" LogicalName="LIMITATIONS.md" />
</ItemGroup>
<ItemGroup>
+1
View File
@@ -71,6 +71,7 @@
<MenuItem Header="{x:Static res:Strings.Menu_Help_CheckUpdates}" Command="{Binding ViewModel.CheckForUpdatesCommand}" />
<MenuItem Header="{x:Static res:Strings.Menu_Help_ReportBug}" Command="{Binding ViewModel.ReportBugCommand}" />
<MenuItem Header="{x:Static res:Strings.Menu_Help_Documentation}" Command="{Binding ViewModel.DocumentationCommand}" />
<MenuItem Header="{x:Static res:Strings.Menu_Help_Limitations}" Command="{Binding ViewModel.LimitationsCommand}" />
<Separator />
<MenuItem Header="{x:Static res:Strings.Menu_Help_About}" Command="{Binding ViewModel.AboutCommand}" />
</MenuItem>
+4 -1
View File
@@ -88,9 +88,12 @@
</ItemsControl.ItemsPanel>
<ItemsControl.ItemTemplate>
<DataTemplate DataType="{x:Type vm:CompareCell}">
<TextBlock Margin="4,0" Text="{Binding Text}" Foreground="{DynamicResource TextFillColorPrimaryBrush}">
<!-- The default foreground is the Style's, not a local value (beta.8): a local value outranks every
trigger, and the best cell was bold but never in the accent colour. -->
<TextBlock Margin="4,0" Text="{Binding Text}">
<TextBlock.Style>
<Style TargetType="TextBlock">
<Setter Property="Foreground" Value="{DynamicResource TextFillColorPrimaryBrush}" />
<Style.Triggers>
<DataTrigger Binding="{Binding IsBest}" Value="True">
<Setter Property="FontWeight" Value="Bold" />
+8 -2
View File
@@ -10,7 +10,8 @@
<StackPanel Style="{StaticResource PageRoot}">
<ui:TextBlock FontTypography="Title" Text="{x:Static vm:DashboardViewModel.Header}" />
<!-- 08_UI §Dashboard: the live capture card, fed by SessionStarted / SessionProgress / SessionCompleted. -->
<!-- 08_UI §Dashboard: the live capture card, fed by SessionStarted / SessionProgress / SessionHeld / SessionCompleted.
A session recorded without measuring (Tier 2) shows why, and no readout (2026-09-23). -->
<ui:Card Margin="0,16,0,0" HorizontalAlignment="Stretch">
<StackPanel>
<StackPanel Orientation="Horizontal">
@@ -26,7 +27,12 @@
<ui:TextBlock Appearance="Secondary" Text="{Binding ViewModel.Live.ElapsedText}" />
<ui:TextBlock Appearance="Secondary" Text="{x:Static vm:LiveCaptureViewModel.WaitingText}"
Visibility="{Binding ViewModel.Live.WaitingForFrames, Converter={StaticResource BoolToVis}}" />
<controls:FpsReadout Margin="0,8,0,0" Model="{Binding ViewModel.Live.Readout}" />
<StackPanel Margin="0,8,0,0" Visibility="{Binding ViewModel.Live.IsHeld, Converter={StaticResource BoolToVis}}">
<ui:TextBlock Text="{x:Static vm:LiveCaptureViewModel.HeldText}" TextWrapping="Wrap" />
<ui:TextBlock Appearance="Secondary" Text="{Binding ViewModel.Live.HeldReason}" TextWrapping="Wrap" />
</StackPanel>
<controls:FpsReadout Margin="0,8,0,0" Model="{Binding ViewModel.Live.Readout}"
Visibility="{Binding ViewModel.Live.IsHeld, Converter={StaticResource InverseBoolToVis}}" />
<WrapPanel Margin="0,8,0,0">
<ui:TextBlock Margin="0,0,16,0" Text="{Binding ViewModel.Live.ResolutionText}" />
<ui:TextBlock Margin="0,0,16,0" Text="{Binding ViewModel.Live.UpscalerText}" />
+103 -28
View File
@@ -30,6 +30,9 @@
<ui:TextBlock FontTypography="Title" Text="{Binding ViewModel.Name}" />
<ui:TextBlock Appearance="Secondary" Text="{Binding ViewModel.Subtitle}" />
<ui:TextBlock Appearance="Tertiary" TextTrimming="CharacterEllipsis" Text="{Binding ViewModel.ExecutableText}" ToolTip="{Binding ViewModel.ExecutableText}" />
<ui:InfoBar Margin="0,6,0,0" IsClosable="False" Severity="Warning"
IsOpen="{Binding ViewModel.ExecutableMissing, Mode=OneWay}"
Message="{Binding ViewModel.ExecutableMissingMessage}" />
<ui:TextBlock Appearance="Secondary" Text="{Binding ViewModel.LastSessionText}" />
<StackPanel Orientation="Horizontal" Margin="0,10,0,0">
<ui:TextBlock Appearance="Secondary" VerticalAlignment="Center" Margin="0,0,12,0" Text="{x:Static vm:GameDetailViewModel.LifetimeLabel}" />
@@ -106,33 +109,95 @@
</ui:Card>
</Grid>
<!-- hooking control (FR-2.1 / FR-2.2 / FR-2.5) -->
<ui:CardControl Margin="0,12,0,0" Header="{x:Static vm:GameDetailViewModel.HookingHeader}" Icon="{ui:SymbolIcon ShieldTask24}">
<!-- details (beta.8, schema 0011): what the game's files and its store say — what it runs as, its versions, what it ships -->
<ui:CardExpander Margin="0,12,0,0" IsExpanded="True" Icon="{ui:SymbolIcon Info24}"
Header="{x:Static vm:GameDetailViewModel.DetailsHeader}">
<ItemsControl ItemsSource="{Binding ViewModel.Details}">
<ItemsControl.ItemTemplate>
<DataTemplate DataType="{x:Type vm:GameDetailRow}">
<Grid Margin="0,0,0,6">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="180" />
<ColumnDefinition Width="*" />
</Grid.ColumnDefinitions>
<ui:TextBlock Grid.Column="0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding Label}" />
<ui:TextBlock Grid.Column="1" TextWrapping="Wrap" Text="{Binding Value}" />
</Grid>
</DataTemplate>
</ItemsControl.ItemTemplate>
</ItemsControl>
</ui:CardExpander>
<!-- recording switch (schema 0009, 2026-09-23): off, FrameLedger does not watch for this program at all -->
<ui:CardControl Margin="0,12,0,0" Header="{x:Static vm:GameDetailViewModel.RecordingHeader}" Icon="{ui:SymbolIcon Record24}">
<StackPanel Orientation="Horizontal">
<ui:TextBlock Appearance="Secondary" VerticalAlignment="Center" Margin="0,0,12,0" Text="{Binding ViewModel.HookStatusText}" />
<ui:ToggleSwitch AutomationProperties.Name="{x:Static vm:GameDetailViewModel.HookingHeader}"
IsChecked="{Binding ViewModel.HookEnabled, Mode=OneWay}"
IsEnabled="{Binding ViewModel.HookToggleEnabled}"
Command="{Binding ViewModel.ToggleHookingCommand}" />
<ui:TextBlock Appearance="Secondary" VerticalAlignment="Center" Margin="0,0,12,0" Text="{Binding ViewModel.RecordingStatusText}" />
<ui:ToggleSwitch AutomationProperties.Name="{x:Static vm:GameDetailViewModel.RecordingHeader}"
IsChecked="{Binding ViewModel.RecordSessions, Mode=OneWay}"
Command="{Binding ViewModel.ToggleRecordingCommand}" />
</StackPanel>
</ui:CardControl>
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.HookingBody}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.BlockedText}"
Visibility="{Binding ViewModel.BlockedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.UnverifiedText}"
Visibility="{Binding ViewModel.UnverifiedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" Text="{x:Static vm:GameDetailViewModel.BusyText}"
Visibility="{Binding ViewModel.Busy, Converter={StaticResource BoolToVis}}" />
<!-- the user's guard bypass (owner decision 2026-09-21, 19_SAFETY §The user's bypass): per game, OFF by default -->
<ui:CardControl Margin="0,12,0,0" Header="{x:Static vm:GameDetailViewModel.BypassLabel}" Icon="{ui:SymbolIcon ShieldError24}">
<ui:ToggleSwitch AutomationProperties.Name="{x:Static vm:GameDetailViewModel.BypassLabel}"
IsChecked="{Binding ViewModel.GuardBypassOn, Mode=OneWay}"
Command="{Binding ViewModel.ToggleGuardBypassCommand}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.RecordingBody}" />
<!-- anti-cheat found, shown IN PLACE of the hooking card while such cards are hidden (beta.8, ui.hide_anticheat_hooking) -->
<ui:CardControl Margin="0,12,0,0" Icon="{ui:SymbolIcon ShieldError24}"
Visibility="{Binding ViewModel.AntiCheatText, Converter={StaticResource NullToCollapsed}}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static vm:GameDetailViewModel.AntiCheatHeader}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.AntiCheatText}" />
</StackPanel>
</ui:CardControl.Header>
</ui:CardControl>
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.BypassBody}" />
<ui:InfoBar Margin="0,8,0,0" IsClosable="False" Severity="Error"
IsOpen="{Binding ViewModel.GuardBypassOn, Mode=OneWay}"
Message="{x:Static vm:GameDetailViewModel.BypassOnNotice}" />
<!-- D33 (owner decision 2026-09-26): the user-mode exception on a blocked game, its state the Agent's (19_SAFETY §The user-mode exception) -->
<ui:CardControl Margin="0,12,0,0" Icon="{ui:SymbolIcon ShieldTask24}"
Visibility="{Binding ViewModel.ExceptionCardVisible, Converter={StaticResource BoolToVis}}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static vm:GameDetailViewModel.ExceptionHeader}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionText}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionInForceText}"
Visibility="{Binding ViewModel.ExceptionInForceText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionSuspendedText}"
Visibility="{Binding ViewModel.ExceptionSuspendedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Appearance="Tertiary" TextWrapping="Wrap" Text="{Binding ViewModel.ExceptionLapseText}"
Visibility="{Binding ViewModel.ExceptionLapseText, Converter={StaticResource NullToCollapsed}}" />
</StackPanel>
</ui:CardControl.Header>
<StackPanel Orientation="Horizontal">
<ui:Button Appearance="Secondary"
Command="{Binding ViewModel.GrantExceptionCommand}"
Content="{x:Static vm:GameDetailViewModel.GrantExceptionText}"
Visibility="{Binding ViewModel.CanGrantException, Converter={StaticResource BoolToVis}}" />
<ui:Button Appearance="Secondary"
Command="{Binding ViewModel.WithdrawExceptionCommand}"
Content="{x:Static vm:GameDetailViewModel.WithdrawExceptionText}"
Visibility="{Binding ViewModel.CanWithdrawException, Converter={StaticResource BoolToVis}}" />
</StackPanel>
</ui:CardControl>
<!-- hooking control (FR-2.1 / FR-2.2 / FR-2.5) -->
<StackPanel Visibility="{Binding ViewModel.HookingSectionVisible, Converter={StaticResource BoolToVis}}">
<ui:CardControl Margin="0,12,0,0" Header="{x:Static vm:GameDetailViewModel.HookingHeader}" Icon="{ui:SymbolIcon ShieldTask24}">
<StackPanel Orientation="Horizontal">
<ui:TextBlock Appearance="Secondary" VerticalAlignment="Center" Margin="0,0,12,0" Text="{Binding ViewModel.HookStatusText}" />
<ui:ToggleSwitch AutomationProperties.Name="{x:Static vm:GameDetailViewModel.HookingHeader}"
IsChecked="{Binding ViewModel.HookEnabled, Mode=OneWay}"
IsEnabled="{Binding ViewModel.HookToggleEnabled}"
Command="{Binding ViewModel.ToggleHookingCommand}" />
</StackPanel>
</ui:CardControl>
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.HookingBody}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.BlockedText}"
Visibility="{Binding ViewModel.BlockedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.NotX64Text}"
Visibility="{Binding ViewModel.NotX64Text, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.UnverifiedText}"
Visibility="{Binding ViewModel.UnverifiedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Secondary" Text="{x:Static vm:GameDetailViewModel.BusyText}"
Visibility="{Binding ViewModel.Busy, Converter={StaticResource BoolToVis}}" />
</StackPanel>
<ui:InfoBar Margin="0,8,0,0" IsClosable="False" Severity="Warning"
IsOpen="{Binding ViewModel.AutoDisabledText, Converter={StaticResource NotNull}}"
Message="{Binding ViewModel.AutoDisabledText}">
@@ -191,6 +256,14 @@
<DataGridTextColumn Header="{x:Static res:Strings.Sessions_Col_Resolution}" Binding="{Binding ResolutionText}" />
<DataGridTextColumn Header="{x:Static res:Strings.Sessions_Col_GpuTemp}" Binding="{Binding GpuTempText}" />
<DataGridTextColumn Header="{x:Static res:Strings.Sessions_Col_Api}" Binding="{Binding ApiText}" />
<!-- beta.10: both tiers; the tooltip carries every share, the window, the back buffer and the source -->
<DataGridTemplateColumn Header="{x:Static res:Strings.Sessions_Col_Display}">
<DataGridTemplateColumn.CellTemplate>
<DataTemplate DataType="{x:Type vm:SessionItemViewModel}">
<TextBlock Text="{Binding DisplayModeText}" ToolTip="{Binding DisplayModeTooltip}" />
</DataTemplate>
</DataGridTemplateColumn.CellTemplate>
</DataGridTemplateColumn>
<DataGridTemplateColumn>
<DataGridTemplateColumn.CellTemplate>
<DataTemplate DataType="{x:Type vm:SessionItemViewModel}">
@@ -245,7 +318,7 @@
<StackPanel Margin="0,12,0,0">
<StackPanel Orientation="Horizontal">
<ui:TextBlock Appearance="Secondary" VerticalAlignment="Center" Margin="0,0,8,0" Text="{x:Static vm:GameDetailViewModel.TrendMetricLabel}" />
<ComboBox MinWidth="180" AutomationProperties.Name="{x:Static vm:GameDetailViewModel.TrendMetricLabel}" DisplayMemberPath="Label" ItemsSource="{x:Static vm:GameDetailViewModel.TrendMetrics}"
<ComboBox MinWidth="180" AutomationProperties.Name="{x:Static vm:GameDetailViewModel.TrendMetricLabel}" DisplayMemberPath="Label" ItemsSource="{Binding ViewModel.TrendMetrics}"
SelectedValue="{Binding ViewModel.TrendMetric, Mode=TwoWay}" SelectedValuePath="Value" />
<CheckBox Margin="16,0,0,0" VerticalAlignment="Center" Content="{x:Static vm:GameDetailViewModel.IncludeMidSessionText}"
IsChecked="{Binding ViewModel.IncludeMidSession}" />
@@ -253,16 +326,18 @@
<ui:TextBlock Margin="0,6,0,0" Appearance="Tertiary" Text="{Binding ViewModel.TrendExcludedText}"
Visibility="{Binding ViewModel.TrendExcludedText, Converter={StaticResource NullToCollapsed}}" />
<ui:TextBlock Margin="0,6,0,0" Appearance="Tertiary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.TrendAverageNote}" />
<ui:TextBlock Margin="0,12,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.TrendEmptyText}"
<ui:TextBlock Margin="0,6,0,0" Appearance="Tertiary" TextWrapping="Wrap" Text="{x:Static vm:GameDetailViewModel.TrendPartialNote}" />
<ui:TextBlock Margin="0,12,0,0" Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.TrendEmptyMessage}"
Visibility="{Binding ViewModel.TrendEmpty, Converter={StaticResource BoolToVis}}" />
<charts:TrendChart x:Name="Trend" Height="320" Visibility="{Binding ViewModel.TrendEmpty, Converter={StaticResource InverseBoolToVis}}" />
</StackPanel>
</TabItem>
<TabItem Header="{x:Static vm:GameDetailViewModel.TabSensors}">
<StackPanel Margin="0,12,0,0">
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.SelectedNote}"
Visibility="{Binding ViewModel.SelectedNote, Converter={StaticResource NullToCollapsed}}" />
<charts:SensorsChart x:Name="Sensors" Visibility="{Binding ViewModel.SelectedHasSeries, Converter={StaticResource BoolToVis}}" />
<!-- A session that was not hooked has its sensors (beta.8): the tab's own note and visibility, not the frames'. -->
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding ViewModel.SensorsNote}"
Visibility="{Binding ViewModel.SensorsNote, Converter={StaticResource NullToCollapsed}}" />
<charts:SensorsChart x:Name="Sensors" Visibility="{Binding ViewModel.SelectedHasSensors, Converter={StaticResource BoolToVis}}" />
</StackPanel>
</TabItem>
<TabItem Header="{x:Static vm:GameDetailViewModel.TabLatency}">
@@ -14,10 +14,16 @@ public partial class GameDetailPage : INavigableView<GameDetailViewModel>
InitializeComponent();
ViewModel.SelectionPresented += OnSelectionPresented;
ViewModel.TrendPresented += OnTrendPresented;
// The view model starts loading before this page exists, and a load that finished first raised its events to
// nobody: the Trend tab was blank on every first open (beta.8). Draw what it holds now; a later load redraws.
OnTrendPresented(this, EventArgs.Empty);
OnSelectionPresented(this, EventArgs.Empty);
Loaded += (_, _) => ViewModel.Attach();
Unloaded += (_, _) =>
{
ViewModel.SelectionPresented -= OnSelectionPresented;
ViewModel.TrendPresented -= OnTrendPresented;
ViewModel.Detach();
};
}
@@ -27,7 +33,7 @@ public partial class GameDetailPage : INavigableView<GameDetailViewModel>
{
Frametime.Show(ViewModel.SelectedSeries, displayed: false, sensors: false);
Distribution.Show(ViewModel.SelectedSeries);
Sensors.Show(ViewModel.SelectedSeries);
Sensors.Show(ViewModel.SelectedSensors);
Latency.Show(ViewModel.SelectedSeries, ViewModel.SelectedSession?.Row.LatencyAvgUs, ViewModel.SelectedSession?.Row.LatencyP95Us);
}
@@ -53,6 +53,81 @@
</StackPanel>
</ui:CardExpander>
<!-- beta.8 (owner request 2026-09-25): an anti-cheat game's page shows the finding instead of its Hooking card. -->
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon ShieldError24}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_HideAntiCheatHooking_Label}" />
<ui:TextBlock MaxWidth="520" HorizontalAlignment="Left" Appearance="Secondary" TextWrapping="Wrap"
Text="{x:Static res:Strings.Settings_HideAntiCheatHooking_Body}" />
</StackPanel>
</ui:CardControl.Header>
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_HideAntiCheatHooking_Label}"
IsChecked="{Binding ViewModel.HideAntiCheatHooking, Mode=TwoWay}" />
</ui:CardControl>
<!-- D33 (owner decision 2026-09-26): the user-mode anti-cheat exception — the option, off by default, and the games it concerns. -->
<ui:CardExpander Margin="0,8,0,0" IsExpanded="{Binding ViewModel.UserModeExceptions, Mode=OneWay}" Icon="{ui:SymbolIcon ShieldTask24}">
<ui:CardExpander.Header>
<Grid>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="Auto" />
</Grid.ColumnDefinitions>
<StackPanel Grid.Column="0">
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Exceptions_Label}" TextWrapping="Wrap" />
<ui:TextBlock MaxWidth="520" HorizontalAlignment="Left" Appearance="Secondary" TextWrapping="Wrap"
Text="{x:Static res:Strings.Settings_Exceptions_Body}" />
</StackPanel>
<ui:ToggleSwitch Grid.Column="1" Margin="12,0" AutomationProperties.Name="{x:Static res:Strings.Settings_Exceptions_Label}"
IsChecked="{Binding ViewModel.UserModeExceptions, Mode=TwoWay}" />
</Grid>
</ui:CardExpander.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Exceptions_Header}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static res:Strings.Settings_Exceptions_Suspended}"
Visibility="{Binding ViewModel.ExceptionsSuspended, Converter={StaticResource BoolToVis}}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{x:Static res:Strings.Settings_Exceptions_Checking}"
Visibility="{Binding ViewModel.ExceptionsChecking, Converter={StaticResource BoolToVis}}" />
<ui:TextBlock Appearance="Secondary" Text="{x:Static res:Strings.Settings_Exceptions_Empty}"
Visibility="{Binding ViewModel.ExceptionGames.Count, Converter={StaticResource ZeroToVisible}}" />
<ItemsControl ItemsSource="{Binding ViewModel.ExceptionGames}">
<ItemsControl.ItemTemplate>
<DataTemplate>
<Grid Margin="0,6">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="Auto" />
</Grid.ColumnDefinitions>
<StackPanel Grid.Column="0">
<ui:TextBlock FontTypography="BodyStrong" Text="{Binding Name}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding FindingText}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding SessionsText}" />
<ui:TextBlock Appearance="Secondary" TextWrapping="Wrap" Text="{Binding StateText}" />
<ui:TextBlock Appearance="Tertiary" TextWrapping="Wrap" Text="{Binding LapseText}"
Visibility="{Binding LapseText, Converter={StaticResource NullToCollapsed}}" />
</StackPanel>
<StackPanel Grid.Column="1" Margin="12,0,0,0" VerticalAlignment="Center" Orientation="Horizontal">
<ui:Button Appearance="Secondary"
Command="{Binding GrantCommand}"
Content="{x:Static res:Strings.Settings_Exceptions_Grant}"
Visibility="{Binding CanGrant, Converter={StaticResource BoolToVis}}" />
<ui:Button Appearance="Secondary"
Command="{Binding WithdrawCommand}"
Content="{x:Static res:Strings.Settings_Exceptions_Withdraw}"
Visibility="{Binding CanWithdraw, Converter={StaticResource BoolToVis}}" />
</StackPanel>
</Grid>
</DataTemplate>
</ItemsControl.ItemTemplate>
</ItemsControl>
<ui:Button Margin="0,8,0,0"
Appearance="Secondary"
Command="{Binding ViewModel.RefreshExceptionsCommand}"
Content="{x:Static res:Strings.Settings_Exceptions_Refresh}" />
</StackPanel>
</ui:CardExpander>
<ui:CardExpander Margin="0,8,0,0" Icon="{ui:SymbolIcon Layer24}">
<ui:CardExpander.Header>
<Grid>
@@ -149,6 +224,16 @@
</ui:CardExpander.Header>
<ui:TextBlock Appearance="Secondary" Text="{x:Static res:Strings.Settings_Agent_Elevation_Body}" TextWrapping="Wrap" />
</ui:CardExpander>
<!-- beta.10, the admin mode (D34): off by default; on shows the disclosure, and Windows asks at every Agent start. -->
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon Shield24}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Agent_RunElevated_Label}" />
<ui:TextBlock MaxWidth="560" HorizontalAlignment="Left" Appearance="Secondary" Text="{x:Static res:Strings.Settings_Agent_RunElevated_Body}" TextWrapping="Wrap" />
</StackPanel>
</ui:CardControl.Header>
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_Agent_RunElevated_Label}" IsChecked="{Binding ViewModel.RunElevated, Mode=TwoWay}" />
</ui:CardControl>
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon CalendarClock24}">
<ui:CardControl.Header>
<StackPanel>
@@ -213,6 +298,17 @@
</ui:CardControl.Header>
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_MinimizeToTray_Label}" IsChecked="{Binding ViewModel.MinimizeToTray, Mode=TwoWay}" />
</ui:CardControl>
<!-- beta.8 (owner request 2026-09-25): two decimals on every FPS figure. -->
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon NumberSymbol24}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_FpsDecimals_Label}" />
<ui:TextBlock MaxWidth="520" HorizontalAlignment="Left" Appearance="Secondary" TextWrapping="Wrap"
Text="{x:Static res:Strings.Settings_FpsDecimals_Body}" />
</StackPanel>
</ui:CardControl.Header>
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_FpsDecimals_Label}" IsChecked="{Binding ViewModel.FpsTwoDecimals, Mode=TwoWay}" />
</ui:CardControl>
<!--
Updates, logging, legal. The Privacy card — the `privacy.online_metadata` toggle — is not shown
@@ -0,0 +1,39 @@
using System.Windows.Data;
using FrameLedger.App.Dialogs;
using FrameLedger.App.ViewModels;
using Wpf.Ui;
using Wpf.Ui.Controls;
namespace FrameLedger.App.Services;
/// <summary>
/// The admin mode's disclosure in WPF UI, the same shape as D33's (<see cref="AntiCheatExceptionPrompt"/>): the primary button
/// is bound to the ticked acceptance and disabled until it is ticked; the close button keeps standard rights and is the
/// default, so Enter never turns the mode on.
/// </summary>
public sealed class AgentAdminPrompt : IAgentAdminPrompt
{
private readonly IContentDialogService _dialogs;
public AgentAdminPrompt(IContentDialogService dialogs) => _dialogs = dialogs ?? throw new ArgumentNullException(nameof(dialogs));
public async Task<bool> ShowAsync(CancellationToken ct = default)
{
var viewModel = new AgentAdminDialogViewModel();
var dialog = new ContentDialog
{
Title = AgentAdminDialogViewModel.Title,
Content = new AgentAdminDialogContent(viewModel),
PrimaryButtonText = AgentAdminDialogViewModel.TurnOnText,
CloseButtonText = AgentAdminDialogViewModel.CancelText,
DefaultButton = ContentDialogButton.Close,
IsPrimaryButtonEnabled = false,
DialogMaxWidth = 700,
};
_ = dialog.SetBinding(ContentDialog.IsPrimaryButtonEnabledProperty,
new Binding(nameof(AgentAdminDialogViewModel.Accepted)) { Source = viewModel, Mode = BindingMode.OneWay });
ContentDialogResult result = await _dialogs.ShowAsync(dialog, ct).ConfigureAwait(true);
return result == ContentDialogResult.Primary && viewModel.Accepted;
}
}
@@ -151,7 +151,8 @@ public sealed class AgentConnection : IAgentLink, IAsyncDisposable
running = _launcher.RunningAgent;
if (running is null)
{
Set(AgentConnectionState.Starting, null, null);
// The admin mode (beta.10): the start blocks while Windows' prompt waits for its answer, and the pill says why.
Set(_launcher.WillAskForElevation ? AgentConnectionState.Elevating : AgentConnectionState.Starting, null, null);
if (_launcher.TryStart())
{
Interlocked.Increment(ref _launches);
@@ -3,9 +3,15 @@ using Microsoft.Extensions.Hosting;
namespace FrameLedger.App.Services;
/// <summary>Runs <see cref="AgentConnection"/> for the life of the host.</summary>
internal sealed class AgentConnectionHostedService(AgentConnection connection) : BackgroundService
internal sealed class AgentConnectionHostedService(AgentConnection connection, LiveSessions sessions) : BackgroundService
{
protected override Task ExecuteAsync(CancellationToken stoppingToken) => connection.RunAsync(stoppingToken);
// The running-session view is built with this service, before the first round, so the first connect's status seeds
// it and no event after it is missed (2026-09-23).
protected override Task ExecuteAsync(CancellationToken stoppingToken)
{
GC.KeepAlive(sessions);
return connection.RunAsync(stoppingToken);
}
public override async Task StopAsync(CancellationToken cancellationToken)
{
@@ -17,4 +17,10 @@ public enum AgentConnectionState
/// <summary>No Agent executable is beside this one; nothing to start, rounds continue in case one appears.</summary>
Missing,
/// <summary>
/// The Agent is being started as administrator (beta.10, the admin mode): Windows' prompt is up, owned by this window or
/// flashing on the taskbar, and the round waits for its answer.
/// </summary>
Elevating,
}
+144 -7
View File
@@ -1,6 +1,7 @@
using System.ComponentModel;
using System.Diagnostics;
using System.IO;
using FrameLedger.Infrastructure.Persistence;
using FrameLedger.Infrastructure.Startup;
using Serilog;
@@ -8,14 +9,29 @@ namespace FrameLedger.App.Services;
/// <summary>Starts the Agent beside this executable, as its own process — it must outlive the App (background capture).</summary>
/// <remarks>
/// <para>
/// Never a second one (2026-09-17): <see cref="RunningAgent"/> probes the data folder's <see cref="AgentInstanceLock"/>,
/// and the last Agent this App started is watched until it exits, with its exit code logged — exit
/// <see cref="AgentInstanceLock.ExitHeldElsewhere"/> is an Agent that found the folder already claimed.
/// </para>
/// <para>
/// <b>The admin mode</b> (beta.10, owner decision D34). With <c>capture.run_elevated</c> on and this App a standard user's,
/// Windows is asked — a UAC prompt owned by the App's window — every time this App starts the Agent. Accepted: the Agent
/// starts as administrator for THIS user (<c>--for-user</c>). Declined: the Agent starts as a standard user and says so
/// (<c>--elevation declined</c>), and the answer is not asked again for that start. Answered with another account: that
/// account's Agent refuses to run (exit 11), and until this App restarts it starts the standard user's instead of asking
/// again. With the option off and this App elevated, the Agent starts with the desktop shell's token — the option is the
/// only thing that makes the Agent an administrator's. While a prompt is up the folder's <see cref="ElevationMarker"/> is
/// held, so the logon task's Agent does not prompt beside it.
/// </para>
/// </remarks>
public sealed class AgentLauncher : IAgentLauncher
{
private readonly string _dataDirectory;
private readonly Func<bool> _runElevated;
private readonly Func<nint> _ownerWindow;
private Task _lastStarted = Task.CompletedTask;
private volatile bool _otherAccountAnswered;
public AgentLauncher()
: this(UiPaths.DataDirectory)
@@ -23,8 +39,15 @@ public sealed class AgentLauncher : IAgentLauncher
}
/// <summary>A launcher that probes <paramref name="dataDirectory"/>'s claim — a test's folder, never the user's.</summary>
internal AgentLauncher(string dataDirectory) =>
internal AgentLauncher(string dataDirectory, Func<bool>? runElevated = null, Func<nint>? ownerWindow = null)
{
_dataDirectory = dataDirectory ?? throw new ArgumentNullException(nameof(dataDirectory));
_runElevated = runElevated ?? (() => RunElevatedSetting.Read(Path.Combine(_dataDirectory, LedgerPaths.DatabaseFileName)));
_ownerWindow = ownerWindow ?? (static () => 0);
}
/// <summary>The launcher the App composes: the user's folder, and the main window as the prompt's owner.</summary>
public static AgentLauncher ForApp(Func<nint> ownerWindow) => new(UiPaths.DataDirectory, ownerWindow: ownerWindow);
private static string AgentPath => Path.Combine(AppContext.BaseDirectory, "FrameLedger.Agent.exe");
@@ -33,9 +56,13 @@ public sealed class AgentLauncher : IAgentLauncher
/// <inheritdoc />
public string? RunningAgent =>
AgentInstanceLock.IsHeld(_dataDirectory) ? $"an Agent already holds {_dataDirectory}"
: ElevationMarker.IsHeld(_dataDirectory) ? "an Agent is being started as administrator (a UAC prompt may be waiting on the taskbar)"
: !_lastStarted.IsCompleted ? "the Agent this App started last is still starting"
: null;
/// <inheritdoc />
public bool WillAskForElevation => !Environment.IsPrivilegedProcess && !_otherAccountAnswered && _runElevated();
public bool TryStart()
{
if (!CanLaunch)
@@ -43,10 +70,88 @@ public sealed class AgentLauncher : IAgentLauncher
return false;
}
bool wanted = _runElevated();
if (wanted && !Environment.IsPrivilegedProcess)
{
return _otherAccountAnswered ? StartPlain("--serve --elevation " + AgentElevation.OtherAccount) : StartElevated();
}
return !wanted && Environment.IsPrivilegedProcess ? StartWithShellToken() : StartPlain("--serve");
}
/// <summary>The UAC prompt; declined or failed, the standard user's Agent, which says so.</summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Reliability", "CA2025:Ensure tasks using 'IDisposable' instances complete before the instances are disposed",
Justification = "the process and the marker are handed to the watch task, which disposes both; this method disposes neither after the handover")]
private bool StartElevated()
{
ElevationMarker? marker = ElevationMarker.TryAcquire(_dataDirectory);
if (marker is null)
{
// Someone else's prompt is up (the logon task's Agent): its answer starts the Agent; this round starts nothing.
Log.Information("agent: another start is asking for administrator rights; not asking twice");
return false;
}
Log.Information("agent: asking Windows to start the Agent as administrator (capture.run_elevated)");
Process? started = AgentElevation.Start(AgentPath, "--serve --for-user " + AgentElevation.CurrentUserSid(), _ownerWindow(), out string? refusal, out int? error);
if (started is null)
{
marker.Dispose();
Log.Information("agent: the administrator prompt was {Refusal} (error {Error}); starting the Agent as a standard user", refusal, error);
return StartPlain("--serve --elevation " + (refusal ?? AgentElevation.Failed));
}
Log.Information("agent: started {Path} as administrator (pid {Pid})", AgentPath, started.Id);
_lastStarted = WatchElevatedAsync(started, marker);
return true;
}
/// <summary>This App is elevated and the option is off: the Agent gets the desktop shell's token, as a double-click would.</summary>
private bool StartWithShellToken()
{
(int Pid, IDisposable Process)? started = UnelevatedProcess.Start(AgentPath, "--serve", AppContext.BaseDirectory,
new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase), out int error);
if (started is not { } s)
{
// No shell to take a standard user's token from: the Agent inherits this App's elevation, as before beta.10, and
// the Settings page says it runs elevated.
Log.Warning("agent: could not start the Agent as a standard user (error {Error}); it inherits this App's elevation", error);
return StartPlain("--serve");
}
Process? agent = Watchable(s);
if (agent is not null)
{
Log.Information("agent: started {Path} --serve (pid {Pid}) as a standard user; this App is elevated and the admin mode is off", AgentPath, s.Pid);
_lastStarted = WatchUntilExitAsync(agent);
}
return true;
}
/// <summary>The started Agent as a <see cref="Process"/>, taken while the start's own handle still holds its id; null when it is gone already.</summary>
private static Process? Watchable((int Pid, IDisposable Process) started)
{
using (started.Process)
{
try
{
return Process.GetProcessById(started.Pid);
}
catch (ArgumentException)
{
// Gone already; its exit code is lost with it, and the next round says whether an Agent answers.
return null;
}
}
}
private bool StartPlain(string arguments)
{
Process? started;
try
{
started = Process.Start(new ProcessStartInfo(AgentPath, "--serve")
started = Process.Start(new ProcessStartInfo(AgentPath, arguments)
{
UseShellExecute = false,
CreateNoWindow = true,
@@ -64,22 +169,54 @@ public sealed class AgentLauncher : IAgentLauncher
return false;
}
// An elevated App starts an elevated Agent: the token is inherited, and it is what 07_IPC §C's owner check is about.
Log.Information("agent: started {Path} --serve (pid {Pid}{Elevated})", AgentPath, started.Id,
// An elevated App starts an elevated Agent here only when the admin mode is on (the token is inherited) or when no
// standard user's token could be had; 07_IPC §C's owner check is what makes either reachable.
Log.Information("agent: started {Path} {Arguments} (pid {Pid}{Elevated})", AgentPath, arguments, started.Id,
Environment.IsPrivilegedProcess ? ", elevated like this App" : string.Empty);
_lastStarted = WatchUntilExitAsync(started);
return true;
}
private static async Task WatchUntilExitAsync(Process agent)
/// <summary>Holds the marker until the elevated Agent claims the folder or exits; exit 11 is remembered for this App's life.</summary>
private async Task WatchElevatedAsync(Process agent, ElevationMarker marker)
{
using (marker)
{
await AgentElevation.WaitForClaimAsync(agent, _dataDirectory, TimeSpan.FromMinutes(2)).ConfigureAwait(false);
}
int? code = await WaitForExitCodeAsync(agent).ConfigureAwait(false);
if (code == AgentElevation.ExitOtherAccount)
{
_otherAccountAnswered = true;
Log.Warning("agent: the administrator prompt was answered with another account, whose Agent refused to run; "
+ "until this App restarts the Agent starts as a standard user");
}
}
private static async Task WatchUntilExitAsync(Process agent) => await WaitForExitCodeAsync(agent).ConfigureAwait(false);
private static async Task<int?> WaitForExitCodeAsync(Process agent)
{
using (agent)
{
int pid = agent.Id;
await agent.WaitForExitAsync().ConfigureAwait(false);
int code = agent.ExitCode;
int? code;
try
{
code = agent.ExitCode;
}
catch (Exception ex) when (ex is InvalidOperationException or Win32Exception)
{
code = null;
}
Log.Information("agent: pid {Pid} exited {Code}{Meaning}", pid, code,
code == AgentInstanceLock.ExitHeldElsewhere ? " — another Agent already holds the data folder" : string.Empty);
code == AgentInstanceLock.ExitHeldElsewhere ? " — another Agent already holds the data folder"
: code == AgentElevation.ExitOtherAccount ? " — it ran as another account than this App's user"
: string.Empty);
return code;
}
}
}
@@ -13,6 +13,7 @@ public static class AgentStatusPresentation
AgentConnectionState.Starting => (Strings.Agent_State_Starting, ControlAppearance.Info),
AgentConnectionState.Offline => (Strings.Agent_State_Offline, ControlAppearance.Caution),
AgentConnectionState.Missing => (Strings.Agent_State_Missing, ControlAppearance.Danger),
AgentConnectionState.Elevating => (Strings.Agent_State_Elevating, ControlAppearance.Info),
_ => throw new ArgumentOutOfRangeException(nameof(state), state, "not a connection state"),
};
@@ -0,0 +1,4 @@
namespace FrameLedger.App.Services;
/// <summary>D33: what the exception's disclosure names — the game, the anti-cheat family and its signal, and the evidence.</summary>
public sealed record AntiCheatExceptionFacts(string GameName, string Family, string Signal, int Sessions);
@@ -0,0 +1,29 @@
namespace FrameLedger.App.Services;
/// <summary>D33: how a request to grant or withdraw one game's user-mode exception ended.</summary>
public enum AntiCheatExceptionOutcome
{
/// <summary>The Agent wrote the grant (<c>AntiCheatExceptionAck.granted = true</c>). Hooking is still off until FR-2.1.</summary>
Granted,
/// <summary>The exception is not in force any more (<c>granted = false</c> on a withdrawal).</summary>
Withdrawn,
/// <summary>The user closed the disclosure without accepting; nothing was sent.</summary>
Declined,
/// <summary>The Agent's own facts did not make the game eligible (<c>Refused</c>).</summary>
Refused,
/// <summary>The Agent grants against another version of the disclosure than this app shows; the dialog was not opened.</summary>
VersionMismatch,
/// <summary>The option is off in Settings (<c>Error ExceptionsOff</c>); nothing was granted.</summary>
OptionOff,
/// <summary>No connected Agent; nothing was sent.</summary>
AgentUnavailable,
/// <summary>The Agent answered and did not grant (a store outcome, an <c>Error</c>, a timeout); <c>Detail</c> says which.</summary>
Failed,
}
@@ -0,0 +1,41 @@
using System.Windows.Data;
using FrameLedger.App.Dialogs;
using FrameLedger.App.ViewModels;
using Wpf.Ui;
using Wpf.Ui.Controls;
namespace FrameLedger.App.Services;
/// <summary>
/// D33's disclosure in WPF UI, the same shape as FR-2.1's (<see cref="ConsentPrompt"/>): the primary button is bound to the
/// ticked acceptance and disabled until it is ticked; the close button keeps the game blocked and is the default, so Enter
/// never makes an exception.
/// </summary>
public sealed class AntiCheatExceptionPrompt : IAntiCheatExceptionPrompt
{
private readonly IContentDialogService _dialogs;
public AntiCheatExceptionPrompt(IContentDialogService dialogs) => _dialogs = dialogs ?? throw new ArgumentNullException(nameof(dialogs));
public async Task<bool> ShowAsync(AntiCheatExceptionFacts facts, CancellationToken ct = default)
{
var viewModel = new AntiCheatExceptionDialogViewModel(facts);
var dialog = new ContentDialog
{
Title = viewModel.Title,
Content = new AntiCheatExceptionDialogContent(viewModel),
PrimaryButtonText = AntiCheatExceptionDialogViewModel.GrantText,
CloseButtonText = AntiCheatExceptionDialogViewModel.CancelText,
// Enter keeps the game blocked; only a click on the (acceptance-gated) primary makes the exception.
DefaultButton = ContentDialogButton.Close,
IsPrimaryButtonEnabled = false,
DialogMaxWidth = 700,
};
_ = dialog.SetBinding(ContentDialog.IsPrimaryButtonEnabledProperty,
new Binding(nameof(AntiCheatExceptionDialogViewModel.Accepted)) { Source = viewModel, Mode = BindingMode.OneWay });
ContentDialogResult result = await _dialogs.ShowAsync(dialog, ct).ConfigureAwait(true);
// The binding is the gate on the button; this is the same rule read once more at the moment that matters.
return result == ContentDialogResult.Primary && viewModel.Accepted;
}
}
@@ -0,0 +1,46 @@
using System.Globalization;
using FrameLedger.Shared.Ipc;
namespace FrameLedger.App.Services;
/// <summary>D33: how an ask for a user-mode exception ended, and — for a refusal — what the Agent named.</summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public sealed record AntiCheatExceptionResult(AntiCheatExceptionOutcome Outcome, string? Detail = null, RefusedAck? Refusal = null)
{
public static AntiCheatExceptionResult Of(AntiCheatExceptionOutcome outcome) => new(outcome);
/// <summary>The outcome a user wanted: the exception made, or withdrawn.</summary>
public bool Succeeded => Outcome is AntiCheatExceptionOutcome.Granted or AntiCheatExceptionOutcome.Withdrawn;
/// <summary>What to tell the user about <paramref name="gameName"/>, or null when there is nothing to say (a declined disclosure).</summary>
public string? MessageFor(string gameName) => Outcome switch
{
AntiCheatExceptionOutcome.Granted => string.Format(CultureInfo.CurrentCulture, Strings.Exception_Result_Granted_Format, gameName),
AntiCheatExceptionOutcome.Withdrawn => string.Format(CultureInfo.CurrentCulture, Strings.Exception_Result_Withdrawn_Format, gameName),
AntiCheatExceptionOutcome.Refused => string.Format(CultureInfo.CurrentCulture, Strings.Exception_Result_Refused_Format, gameName,
RefusalText() ?? Detail ?? Strings.Common_NotAvailable),
AntiCheatExceptionOutcome.VersionMismatch => Shared.Strings.Safety_Exception_VersionMismatch,
AntiCheatExceptionOutcome.OptionOff => Shared.Strings.Safety_Exception_OptionOff,
AntiCheatExceptionOutcome.AgentUnavailable => Shared.Strings.Safety_Consent_AgentUnavailable,
AntiCheatExceptionOutcome.Failed => Detail ?? Strings.Common_NotAvailable,
_ => null,
};
/// <summary>Why no exception was made, in the user's language: the session count, the finding, or the block's kind.</summary>
public string? RefusalText()
{
if (Refusal is null)
{
return null;
}
return Refusal.Reason switch
{
"TooFewSessions" => string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_TooFew_Format, Refusal.Signal ?? "0"),
"BlockNotExceptionable" => Strings.Exception_State_NotAsked,
"PreScanFailed" or "RulesUnreadable" or "RulesMalformed" or "RulesIncomplete" => Strings.Exception_State_CouldNotVerify,
_ => string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_Refused_Format,
Refusal.Family ?? Formats.GuardReasonText(Refusal.Reason), Refusal.Signal ?? Strings.Common_NotAvailable),
};
}
}
@@ -0,0 +1,104 @@
using System.IO;
using FrameLedger.Infrastructure.Ipc;
using FrameLedger.Shared.Ipc;
using FrameLedger.Shared.Safety;
using Serilog;
namespace FrameLedger.App.Services;
/// <summary>
/// D33 (owner decision 2026-09-26) from the App's side: the version handshake (the dialog is not opened when the Agent
/// grants against other text), the disclosure, and the one message that may ask for a user-mode exception
/// (<c>SetAntiCheatException</c>). Like <see cref="HookingConsent"/> it asserts nothing: it sends the version it showed,
/// and the Agent re-checks the option, the block, a tolerant pre-scan of the file on disk and the session count, and
/// grants or refuses (<c>07_IPC</c> §The pipe is not a trust boundary).
/// </summary>
public sealed class AntiCheatExceptions
{
private readonly IAgentRequests _agent;
private readonly IAntiCheatExceptionPrompt _prompt;
public AntiCheatExceptions(IAgentRequests agent, IAntiCheatExceptionPrompt prompt)
{
_agent = agent ?? throw new ArgumentNullException(nameof(agent));
_prompt = prompt ?? throw new ArgumentNullException(nameof(prompt));
}
/// <summary>Show the disclosure for the game in <paramref name="facts"/> and, on its acceptance, ask the Agent for the exception.</summary>
public async Task<AntiCheatExceptionResult> GrantAsync(long gameId, AntiCheatExceptionFacts facts, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(facts);
HelloAck? hello = _agent.Hello;
if (hello is null || !_agent.IsConnected)
{
return AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable);
}
if (!string.Equals(hello.ExceptionDisclosureVersion, AntiCheatExceptionDisclosure.Version, StringComparison.Ordinal))
{
// Showing text the Agent would not grant against is a dialog whose button cannot mean what it says.
Log.Warning("exception: the Agent grants against {Theirs}, this app shows {Ours}; the dialog was not opened",
hello.ExceptionDisclosureVersion, AntiCheatExceptionDisclosure.Version);
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.VersionMismatch, hello.ExceptionDisclosureVersion);
}
if (!await _prompt.ShowAsync(facts, ct).ConfigureAwait(true))
{
return AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.Declined);
}
return await SendAsync(new SetAntiCheatExceptionRequest(gameId, Enabled: true, AntiCheatExceptionDisclosure.Version), ct).ConfigureAwait(true);
}
/// <summary>Withdraw the game's exception; no dialog — a withdrawal only takes hooking away.</summary>
public Task<AntiCheatExceptionResult> WithdrawAsync(long gameId, CancellationToken ct = default) =>
_agent.IsConnected
? SendAsync(new SetAntiCheatExceptionRequest(gameId, Enabled: false, null), ct)
: Task.FromResult(AntiCheatExceptionResult.Of(AntiCheatExceptionOutcome.AgentUnavailable));
private async Task<AntiCheatExceptionResult> SendAsync(SetAntiCheatExceptionRequest request, CancellationToken ct)
{
try
{
IpcEnvelope ack = await _agent.RequestAsync(IpcMessageType.SetAntiCheatException, request, ct).ConfigureAwait(true);
return Interpret(ack, request.Enabled);
}
catch (Exception ex) when (ex is IpcRequestException or TimeoutException or IOException or InvalidOperationException)
{
Log.Warning(ex, "exception: SetAntiCheatException(game {GameId}, {Enabled}) did not complete", request.GameId, request.Enabled);
string? code = (ex as IpcRequestException)?.Code;
AntiCheatExceptionOutcome outcome = code switch
{
IpcErrorCode.DisclosureVersionMismatch => AntiCheatExceptionOutcome.VersionMismatch,
IpcErrorCode.ExceptionsOff => AntiCheatExceptionOutcome.OptionOff,
_ => AntiCheatExceptionOutcome.Failed,
};
return new AntiCheatExceptionResult(outcome, code ?? ex.GetType().Name);
}
}
private static AntiCheatExceptionResult Interpret(IpcEnvelope ack, bool granting)
{
if (string.Equals(ack.Type, IpcMessageType.Refused, StringComparison.Ordinal))
{
RefusedAck? refused = IpcCodec.Payload<RefusedAck>(ack);
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.Refused, refused?.Reason, refused);
}
if (!string.Equals(ack.Type, IpcMessageType.AntiCheatExceptionAck, StringComparison.Ordinal))
{
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.Failed, "UnexpectedAck:" + ack.Type);
}
AntiCheatExceptionAck? answer = IpcCodec.Payload<AntiCheatExceptionAck>(ack);
if (answer is null)
{
return new AntiCheatExceptionResult(AntiCheatExceptionOutcome.Failed, "EmptyAck");
}
// A withdrawal of an exception that was not in force is still the state the user asked for.
return granting
? answer.Granted ? new(AntiCheatExceptionOutcome.Granted, answer.Outcome) : new(AntiCheatExceptionOutcome.Failed, answer.Outcome)
: answer.Granted ? new(AntiCheatExceptionOutcome.Failed, answer.Outcome) : new(AntiCheatExceptionOutcome.Withdrawn, answer.Outcome);
}
}
@@ -0,0 +1,40 @@
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
namespace FrameLedger.App.Services;
/// <summary>
/// <c>games.hook_blocked_reason</c> in the user's language (beta.8, 2026-09-25): which anti-cheat, and what of it the
/// guard found — a module in the game, a folder or file shipped with it, the title or its store id on the lists.
/// </summary>
/// <remarks>
/// The Agent stores a block as <c>Reason|Family|Signal</c> since 2026-09-25 (<c>SqliteGameConsentStore.BlockText</c>).
/// Rows written before then say <c>"Reason: Family Signal"</c>, which cannot be split back apart — family names and file
/// names both carry spaces — so those are shown as they were stored, which is what the page always showed.
/// </remarks>
[SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public static class BlockedReasonText
{
public static string Describe(string stored)
{
ArgumentNullException.ThrowIfNull(stored);
string[] parts = stored.Split('|');
if (parts.Length != 3)
{
return stored;
}
string format = parts[0] switch
{
"BlockedModule" => Strings.Blocked_Module_Format,
"AntiCheatDirectory" => Strings.Blocked_Directory_Format,
"AntiCheatFile" => Strings.Blocked_File_Format,
"BlockedExecutable" => Strings.Blocked_Executable_Format,
"BlockedStoreId" => Strings.Blocked_StoreId_Format,
_ => Strings.Blocked_Other_Format,
};
string family = parts[1].Length > 0 ? parts[1] : Strings.Common_NotAvailable;
string signal = parts[2].Length > 0 ? parts[2] : Strings.Common_NotAvailable;
return string.Format(CultureInfo.CurrentCulture, format, family, signal);
}
}
+167
View File
@@ -0,0 +1,167 @@
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Domain.Display;
namespace FrameLedger.App.Services;
/// <summary>
/// A session's display facts as the pages say them (beta.10, <c>03_METRICS</c> §Display mode): the mode that lasted longest
/// with its share, every mode's share, and the sizes and the source behind them. A mode is never named more certainly than
/// its source allows — a window that covered its monitor while nothing could ask the swap chain is "Fullscreen or
/// borderless", never either.
/// </summary>
[SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public static class DisplayText
{
/// <summary>The order the shares are said in: the fullscreen end first.</summary>
private static readonly DisplayMode[] _order =
[DisplayMode.ExclusiveFullscreen, DisplayMode.Borderless, DisplayMode.CoversScreen, DisplayMode.Windowed, DisplayMode.Minimized];
/// <summary>The row's display facts, or null for a row that has none (written before beta.10, or recovered from a crash file).</summary>
public static DisplaySummary? Of(SessionRow row) => SessionDisplayColumns.DisplayOf(row);
public static string ModeName(DisplayMode mode) => mode switch
{
DisplayMode.ExclusiveFullscreen => Strings.Display_Mode_Exclusive,
DisplayMode.Borderless => Strings.Display_Mode_Borderless,
DisplayMode.CoversScreen => Strings.Display_Mode_CoversScreen,
DisplayMode.Windowed => Strings.Display_Mode_Windowed,
DisplayMode.Minimized => Strings.Display_Mode_Minimized,
_ => Strings.Display_Mode_NoWindow,
};
/// <summary>
/// The mode that lasted longest and its share (<c>Borderless 92%</c>); "No window" when a window was never read; N/A for a
/// row without display facts.
/// </summary>
public static string Headline(DisplaySummary? display)
{
if (display is null)
{
return Strings.Common_NotAvailable;
}
return display.Dominant is { } mode
? Share(mode, display.SharePercent(mode))
: display.MinimizedMs > 0 ? Share(DisplayMode.Minimized, display.SharePercent(DisplayMode.Minimized)) : Strings.Display_Mode_NoWindow;
}
/// <summary>Every mode the session spent time in, fullscreen end first (<c>Exclusive fullscreen 8% · Borderless 92%</c>).</summary>
public static string Shares(DisplaySummary? display)
{
if (display is null)
{
return Strings.Common_NotAvailable;
}
string[] parts = [.. _order.Where(m => display.SharePercent(m) is > 0).Select(m => Share(m, display.SharePercent(m)))];
return parts.Length == 0 ? Strings.Display_Mode_NoWindow : string.Join(" · ", parts);
}
/// <summary>The window's client size in the mode that lasted longest, or N/A.</summary>
public static string Window(DisplaySummary? display) =>
display is { WindowWidth: > 0 and int w, WindowHeight: > 0 and int h } ? Size(w, h) : Strings.Common_NotAvailable;
/// <summary>The monitor the window was on, with its refresh rate when known, or N/A.</summary>
public static string Monitor(DisplaySummary? display) => display switch
{
{ MonitorWidth: > 0 and int w, MonitorHeight: > 0 and int h, MonitorHz: > 0 and int hz }
=> string.Format(CultureInfo.CurrentCulture, Strings.Display_SizeHz_Format, w, h, hz),
{ MonitorWidth: > 0 and int w, MonitorHeight: > 0 and int h } => Size(w, h),
_ => Strings.Common_NotAvailable,
};
/// <summary>
/// Everything the row says about the display, as one line for the session summary and the tooltips: the shares, the
/// changes, the window on its monitor, the back buffer and its swap effect, and what it all rested on. Null for a row
/// without display facts.
/// </summary>
public static string? Line(DisplaySummary? display)
{
if (display is null)
{
return null;
}
var parts = new List<string> { Shares(display) };
if (display.Changes > 0)
{
parts.Add(display.Changes == 1
? Strings.Display_Changes_One
: string.Format(CultureInfo.CurrentCulture, Strings.Display_Changes_Format, display.Changes));
}
if (display is { WindowWidth: > 0 and int ww, WindowHeight: > 0 and int wh })
{
parts.Add(display is { MonitorWidth: > 0 and int mw, MonitorHeight: > 0 and int mh }
? display.MonitorHz is > 0 and int hz
? string.Format(CultureInfo.CurrentCulture, Strings.Display_WindowOnMonitorHz_Format, ww, wh, mw, mh, hz)
: string.Format(CultureInfo.CurrentCulture, Strings.Display_WindowOnMonitor_Format, ww, wh, mw, mh)
: string.Format(CultureInfo.CurrentCulture, Strings.Display_Window_Format, ww, wh));
}
if (display is { BufferWidth: > 0 and uint bw, BufferHeight: > 0 and uint bh })
{
parts.Add(display.SwapEffect is { Length: > 0 } effect
? string.Format(CultureInfo.CurrentCulture, Strings.Display_BufferEffect_Format, bw, bh, effect)
: string.Format(CultureInfo.CurrentCulture, Strings.Display_Buffer_Format, bw, bh));
}
if (SourceText(display.Source) is { } source)
{
parts.Add(source);
}
return string.Format(CultureInfo.CurrentCulture, Strings.Display_Line_Format, string.Join(" · ", parts));
}
/// <summary>What the facts rested on, said with what it means for exclusive fullscreen; null when no window was read.</summary>
public static string? SourceText(string? source) => source switch
{
DisplaySource.SwapChain => Strings.Display_Source_SwapChain,
DisplaySource.OpenGl => Strings.Display_Source_OpenGl,
DisplaySource.Window => Strings.Display_Source_Window,
_ => null,
};
/// <summary>
/// The row's display facts for the CSV's <c># display:</c> line — InvariantCulture and the stored names, as every export
/// line is, so a file reads the same in every UI language.
/// </summary>
public static string ExportLine(DisplaySummary? display)
{
if (display is null)
{
return "N/A (not recorded: a session recorded before beta.10, or recovered from its crash file)";
}
CultureInfo inv = CultureInfo.InvariantCulture;
string Pair(int? w, int? h) => w is > 0 && h is > 0 ? w.Value.ToString(inv) + "x" + h.Value.ToString(inv) : "n/a";
string buffer = display is { BufferWidth: > 0 and uint bw, BufferHeight: > 0 and uint bh } ? bw.ToString(inv) + "x" + bh.ToString(inv) : "n/a";
string hz = display.MonitorHz is > 0 and int r ? "@" + r.ToString(inv) : string.Empty;
return string.Join("; ",
"exclusive_ms=" + display.ExclusiveMs.ToString(inv),
"borderless_ms=" + display.BorderlessMs.ToString(inv),
"covers_ms=" + display.CoversMs.ToString(inv),
"windowed_ms=" + display.WindowedMs.ToString(inv),
"minimized_ms=" + display.MinimizedMs.ToString(inv),
"nowindow_ms=" + display.NoWindowMs.ToString(inv),
"changes=" + display.Changes.ToString(inv),
"source=" + (display.Source ?? "n/a"),
"window=" + Pair(display.WindowWidth, display.WindowHeight),
"buffer=" + buffer,
"monitor=" + Pair(display.MonitorWidth, display.MonitorHeight) + hz);
}
/// <summary>A share as a person reads it: whole percent, and "&lt;1%" for time that was there but rounds to none.</summary>
internal static string Percent(double share) => share is > 0 and < 0.5
? "<1%"
: Math.Round(share, MidpointRounding.AwayFromZero).ToString("0", CultureInfo.CurrentCulture) + "%";
private static string Share(DisplayMode mode, double? share) =>
share is double s ? string.Format(CultureInfo.CurrentCulture, Strings.Display_Share_Format, ModeName(mode), Percent(s)) : ModeName(mode);
private static string Size(int w, int h) => string.Format(CultureInfo.CurrentCulture, Strings.Display_Size_Format, w, h);
}
@@ -0,0 +1,102 @@
using System.Globalization;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Persistence;
using FrameLedger.Domain.AntiCheat;
namespace FrameLedger.App.Services;
/// <summary>
/// D33 (owner decision 2026-09-26): a blocked game's user-mode exception as the App shows it — in force, eligible, being
/// checked, or why not — read from the Agent's columns (<see cref="GameRow.AcException"/>). The App decides nothing here:
/// every state is a reading of what the Agent wrote, and the grant itself is the Agent's to make.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime")]
public sealed record ExceptionView(ExceptionViewKind Kind, string Text, string? Family, string? Signal, int Sessions, string? LapseText)
{
/// <summary>An exception may be asked for now.</summary>
public bool CanGrant => Kind == ExceptionViewKind.Eligible;
/// <summary>An exception is on the row and may be withdrawn.</summary>
public bool CanWithdraw => Kind == ExceptionViewKind.Granted;
/// <summary>
/// The row's exception, or null for a row it says nothing about (not blocked). Granted first — a grant stays until the
/// Agent or the user ends it — then the block's kind, then the sweep's answer about THIS block.
/// </summary>
public static ExceptionView? Of(GameRow row)
{
ArgumentNullException.ThrowIfNull(row);
if (!row.BlockedByGuard)
{
return null;
}
AntiCheatExceptionState x = row.AcException;
StoredBlock? block = StoredBlock.Parse(row.HookBlockedReason);
string? lapse = x.LapsedReason is { } reason && x.LapsedAt is { } at
? string.Format(CultureInfo.CurrentCulture, Strings.Exception_Lapsed_Format, Formats.Date(at), LapseWords(reason))
: null;
if (x.IsGranted)
{
return new(ExceptionViewKind.Granted, string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_Granted_Format, Formats.Date(x.GrantedAt!.Value)),
x.Family, block?.Signal, x.Sessions, lapse);
}
if (block is not { IsExceptionable: true } b)
{
return new(ExceptionViewKind.NotEligible, Strings.Exception_State_NotAsked, block?.Family, block?.Signal, x.Sessions, lapse);
}
if (!string.Equals(x.CheckedBlock, row.HookBlockedReason, StringComparison.Ordinal))
{
return new(ExceptionViewKind.Checking, Strings.Exception_State_Checking, b.Family, b.Signal, x.Sessions, lapse);
}
return x.Eligible
? new(ExceptionViewKind.Eligible, Strings.Exception_State_Eligible, b.Family, b.Signal, x.Sessions, lapse)
: new(NotEligibleKind(x), WhyNot(b, x), b.Family, b.Signal, x.Sessions, lapse);
}
/// <summary>Why the last grant ended, in words.</summary>
public static string LapseWords(string reason) => reason switch
{
UserModeExceptionLapse.Withdrawn => Strings.Exception_Lapse_Withdrawn,
UserModeExceptionLapse.ExecutableChanged => Strings.Exception_Lapse_ExecutableChanged,
UserModeExceptionLapse.NoLongerEligible => Strings.Exception_Lapse_NoLongerEligible,
UserModeExceptionLapse.NewFinding => Strings.Exception_Lapse_NewFinding,
UserModeExceptionLapse.SafetyUnhook => Strings.Exception_Lapse_SafetyUnhook,
UserModeExceptionLapse.OverlayStopped => Strings.Exception_Lapse_OverlayStopped,
UserModeExceptionLapse.SessionCrashed => Strings.Exception_Lapse_SessionCrashed,
_ => reason,
};
/// <summary>The guard let the family through and only the evidence is short — the one "not yet" the Settings list shows.</summary>
private static ExceptionViewKind NotEligibleKind(AntiCheatExceptionState x) =>
StoredBlock.Parse(x.Verdict) is { Reason: AntiCheatRefusalReason.AllowedUnderUserModeException }
? ExceptionViewKind.TooFewSessions
: ExceptionViewKind.NotEligible;
private static string WhyNot(StoredBlock block, AntiCheatExceptionState x)
{
StoredBlock? verdict = StoredBlock.Parse(x.Verdict);
if (verdict is null)
{
return Strings.Exception_State_NotAsked;
}
if (verdict.Value.Reason == AntiCheatRefusalReason.AllowedUnderUserModeException)
{
return string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_TooFew_Format, x.Sessions);
}
if (!verdict.Value.IsExceptionable && verdict.Value.Family.Length == 0)
{
return Strings.Exception_State_CouldNotVerify;
}
// The same finding back means the guard does not honour this family: it is not user-mode throughout.
return string.Equals(verdict.Value.Family, block.Family, StringComparison.Ordinal)
? string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_NotUserMode_Format, block.Family)
: string.Format(CultureInfo.CurrentCulture, Strings.Exception_State_Refused_Format, verdict.Value.Family, verdict.Value.Signal);
}
}
@@ -0,0 +1,20 @@
namespace FrameLedger.App.Services;
/// <summary>D33: the states a blocked game's user-mode exception is shown in (<see cref="ExceptionView"/>).</summary>
public enum ExceptionViewKind
{
/// <summary>An exception is on the row.</summary>
Granted,
/// <summary>The Agent found the game eligible; no exception has been made.</summary>
Eligible,
/// <summary>The guard would let the family through, and the game has fewer than two successful hooked sessions.</summary>
TooFewSessions,
/// <summary>The Agent has not answered about this block yet (the option was just turned on, or the block changed).</summary>
Checking,
/// <summary>Not eligible, for the reason in the text.</summary>
NotEligible,
}
+300 -2
View File
@@ -1,5 +1,9 @@
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.IO;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Recording;
using FrameLedger.Domain.Detection;
using FrameLedger.Domain.Metrics;
using FrameLedger.Domain.Sessions;
@@ -13,9 +17,20 @@ namespace FrameLedger.App.Services;
[SuppressMessage("Performance", "CA1863:Use 'CompositeFormat'", Justification = "the format strings are resources that follow the UI culture, which changes at runtime; a cached CompositeFormat would pin the first culture")]
public static class Formats
{
public static string Fps(double? value) => value is double v ? Math.Round(v).ToString("0", CultureInfo.CurrentCulture) : Strings.Common_NotAvailable;
public static string Fps(double? value) => value is double v ? FpsNumber(v) : Strings.Common_NotAvailable;
public static string FpsOrDash(double? value) => value is double v ? Math.Round(v).ToString("0", CultureInfo.CurrentCulture) : Strings.Common_Dash;
public static string FpsOrDash(double? value) => value is double v ? FpsNumber(v) : Strings.Common_Dash;
/// <summary>
/// An FPS figure as <c>ui.fps_decimals</c> asks (beta.8): two decimals always ("62.40"), or a whole number. Rounded half
/// away from zero — 62.5 is 63, as a reader expects; <see cref="Math.Round(double)"/> alone rounds half to even (62).
/// </summary>
public static string FpsNumber(double value) => FpsNumber(value, FpsDecimals.Two);
/// <summary>The same with the choice given (tests, and anything that must not read the process-wide setting).</summary>
public static string FpsNumber(double value, bool twoDecimals) => twoDecimals
? Math.Round(value, 2, MidpointRounding.AwayFromZero).ToString("0.00", CultureInfo.CurrentCulture)
: Math.Round(value, MidpointRounding.AwayFromZero).ToString("0", CultureInfo.CurrentCulture);
/// <summary><c>1h 23m</c> above an hour, <c>4m 05s</c> below.</summary>
public static string Duration(double seconds)
@@ -129,6 +144,115 @@ public static class Formats
_ => Strings.Exit_Normal,
};
/// <summary>
/// The engine id as the engine's name (2026-09-23): a proper noun, the same in every language (the glossary rule
/// above). The ids are the rules file's; one this table does not know — a newer rule, or an engine the user typed —
/// passes through as it is, never blank.
/// </summary>
public static string Engine(string? id) => id switch
{
null => string.Empty,
"unity" => "Unity",
"unreal" => "Unreal Engine",
"rpgmaker_mv" => "RPG Maker MV/MZ",
"rpgmaker_rgss" => "RPG Maker XP/VX/VX Ace",
"re_engine" => "RE Engine",
"fromsoftware" => "FromSoftware",
"godot" => "Godot",
"gamemaker" => "GameMaker",
"renpy" => "Ren'Py",
"cryengine" => "CryEngine",
"source" => "Source",
_ => id,
};
/// <summary>What an executable runs as (<c>games.exe_machine</c>, beta.8), in the user's language.</summary>
public static string Architecture(string? id) => id switch
{
ExecutableArchitecture.X64 => Strings.Arch_X64,
ExecutableArchitecture.X86 => Strings.Arch_X86,
ExecutableArchitecture.Arm64 => Strings.Arch_Arm64,
ExecutableArchitecture.Arm => Strings.Arch_Arm,
ExecutableArchitecture.AnyCpu => Strings.Arch_AnyCpu,
ExecutableArchitecture.AnyCpu32 => Strings.Arch_AnyCpu32,
ExecutableArchitecture.Other => Strings.Arch_Other,
_ => Strings.Arch_Unknown,
};
/// <summary>
/// <c>games.game_version</c> said as what it is (beta.8): a store import writes a Steam build id or a GOG / Epic
/// version string, and a bare "20374416" in the subtitle said nothing. Labelled with the store when a store wrote it
/// (<paramref name="detected"/>); a version the user typed is shown as typed. Null when there is none.
/// </summary>
public static string? StoreVersion(string? platform, string? version, bool detected)
{
if (string.IsNullOrWhiteSpace(version))
{
return null;
}
string? format = !detected ? null : platform switch
{
"steam" => Strings.Store_Steam_Format,
"gog" => Strings.Store_Gog_Format,
"epic" => Strings.Store_Epic_Format,
_ => null,
};
return format is null ? version : string.Format(CultureInfo.CurrentCulture, format, version);
}
/// <summary>
/// Whether two file versions are the same four numbers — Streamline stamps its version STRING as <c>2,8,0,0</c> and
/// the fixed part reads <c>2.8.0.0</c>, which agree; a string with text after the numbers is read up to it. Null
/// when either has no number to compare (beta.8: the session summary's "another copy was loaded").
/// </summary>
public static bool? SameVersion(string? a, string? b)
{
int[]? x = VersionNumbers(a);
int[]? y = VersionNumbers(b);
if (x is null || y is null)
{
return null;
}
for (int i = 0; i < 4; i++)
{
if ((i < x.Length ? x[i] : 0) != (i < y.Length ? y[i] : 0))
{
return false;
}
}
return true;
}
private static int[]? VersionNumbers(string? text)
{
if (string.IsNullOrWhiteSpace(text))
{
return null;
}
List<int> parts = new(4);
foreach (string token in text.Split(['.', ','], StringSplitOptions.TrimEntries))
{
// "3.7.10.0 built by …": the numbers end at the first token that is not all digits.
string digits = new([.. token.TakeWhile(char.IsAsciiDigit)]);
if (digits.Length == 0 || !int.TryParse(digits, NumberStyles.None, CultureInfo.InvariantCulture, out int n))
{
break;
}
parts.Add(n);
if (parts.Count == 4 || digits.Length != token.Length)
{
break;
}
}
return parts.Count == 0 ? null : [.. parts];
}
/// <summary>The platform token as its store name.</summary>
public static string Platform(string? token) => token switch
{
@@ -138,4 +262,178 @@ public static class Formats
"itch" => "itch.io",
_ => string.Empty,
};
/// <summary>
/// Why a Tier-2 session measured nothing, from <c>capture_notes</c> (2026-09-22): hooking off, a block on the row,
/// the guard's refusal by family, a process that could not be opened, or the end reason by name.
/// </summary>
public static string Tier2Reason(string? captureNotes) => Tier2Reason(Application.Recording.CaptureNotes.Parse(captureNotes));
/// <summary>The same words for a session still running (2026-09-23): the hold its <c>SessionStarted</c> carried.</summary>
public static string Tier2HoldReason(Shared.Ipc.SessionHold hold)
{
ArgumentNullException.ThrowIfNull(hold);
return Tier2Reason(new Application.Recording.CaptureNotes(hold.Reason, hold.GuardReason, hold.Family, hold.Signal));
}
private static string Tier2Reason(Application.Recording.CaptureNotes n)
{
switch (n.End)
{
case null:
return string.Empty;
case "RefusedHookNotEnabled" when string.Equals(n.GuardReason, "PreviouslyBlocked", StringComparison.Ordinal) && n.GuardSignal is { Length: > 0 } blocked:
return string.Format(CultureInfo.CurrentCulture, Strings.Summary_Tier2_Why_Blocked_Format, BlockedReasonText.Describe(blocked));
case "RefusedHookNotEnabled":
return Strings.Summary_Tier2_Why_HookOff;
case "RefusedByGuard" or "SafetyUnhook" when n.GuardFamily is { Length: > 0 } family:
return string.Format(CultureInfo.CurrentCulture, Strings.Summary_Tier2_Why_Guard_Format, family, n.GuardSignal ?? Strings.Common_NotAvailable);
case "RefusedByGuard" when n.GuardReason is { Length: > 0 } reason:
// A refusal no family names (beta.8): the guard could not look, the game is 32-bit… — said as what it is,
// never "… was detected in this game", which read as a finding.
return GuardSentence(reason);
case "TargetUnreadable":
return Strings.Summary_Tier2_Why_Unreadable;
case "RefusedConsentMissing":
// Common after a store update (2026-09-23): the consent is about the executable that was enabled, and this is a newer one.
return Strings.Summary_Tier2_Why_ConsentChanged;
case "LaunchCannotStart" when n.LaunchError is { } error:
return string.Format(CultureInfo.CurrentCulture, Strings.Launch_Failed_Format, Strings.End_LaunchCannotStart, LaunchErrorText(error));
default:
return EndReasonText(n.End) ?? string.Format(CultureInfo.CurrentCulture, Strings.Summary_Tier2_Why_Other_Format, n.End);
}
}
/// <summary>
/// Why a session ended, in words, for every <see cref="SessionEndReason"/> (beta.8); null for a name this build does not
/// know. <c>Formats_EveryEndReasonHasItsOwnSentence</c> walks the enum so none falls through.
/// </summary>
public static string? EndReasonText(string? end) => end switch
{
nameof(SessionEndReason.Running) => Strings.End_Running,
nameof(SessionEndReason.TargetExited) => Strings.End_TargetExited,
nameof(SessionEndReason.SafetyUnhook) => Strings.End_SafetyUnhook,
nameof(SessionEndReason.SupervisionLost) => Strings.End_SupervisionLost,
nameof(SessionEndReason.WriterSelfDisabled) => Strings.End_WriterSelfDisabled,
nameof(SessionEndReason.WriterStoppedBlocklisted) => Strings.End_WriterStoppedBlocklisted,
nameof(SessionEndReason.WriterNeverInstalledHooks) => Strings.End_WriterNeverInstalledHooks,
nameof(SessionEndReason.RefusedHookNotEnabled) => Strings.End_RefusedHookNotEnabled,
nameof(SessionEndReason.RefusedConsentMissing) => Strings.End_RefusedConsentMissing,
nameof(SessionEndReason.RefusedPreviouslyBlocked) => Strings.End_RefusedPreviouslyBlocked,
nameof(SessionEndReason.RefusedByGuard) => Strings.End_RefusedByGuard,
nameof(SessionEndReason.PreScanCouldNotVerify) => Strings.End_PreScanCouldNotVerify,
nameof(SessionEndReason.TargetNotRunning) => Strings.End_TargetNotRunning,
nameof(SessionEndReason.TargetCannotBePinned) => Strings.End_TargetCannotBePinned,
nameof(SessionEndReason.ExecutableUnreadable) => Strings.End_ExecutableUnreadable,
nameof(SessionEndReason.SupervisionFaulted) => Strings.End_SupervisionFaulted,
nameof(SessionEndReason.TargetAmbiguous) => Strings.End_TargetAmbiguous,
nameof(SessionEndReason.AttachRefused) => Strings.End_AttachRefused,
nameof(SessionEndReason.LaunchCannotStart) => Strings.End_LaunchCannotStart,
nameof(SessionEndReason.LaunchTargetExited) => Strings.End_LaunchTargetExited,
nameof(SessionEndReason.LaunchNoPresentationRuntime) => Strings.End_LaunchNoPresentationRuntime,
nameof(SessionEndReason.RefusedKillSwitch) => Strings.End_RefusedKillSwitch,
nameof(SessionEndReason.KillSwitchEngaged) => Strings.End_KillSwitchEngaged,
nameof(SessionEndReason.StoppedByUser) => Strings.End_StoppedByUser,
nameof(SessionEndReason.TargetUnreadable) => Strings.End_TargetUnreadable,
_ => null,
};
/// <summary>
/// A guard refusal no anti-cheat family names, as a sentence (beta.8): "The anti-cheat guard did not hook this game: the
/// game is 32-bit…". Every refusal reason the native guard can give has its words; a name this build does not know is
/// named as it is.
/// </summary>
public static string GuardSentence(string reason) =>
string.Format(CultureInfo.CurrentCulture, Strings.Guard_Refused_Format, GuardReasonText(reason));
/// <summary>What a familyless guard reason means, as a clause.</summary>
public static string GuardReasonText(string reason) => reason switch
{
"ModuleScanFailed" => Strings.Guard_ModuleScanFailed,
"ProcessUnreadable" => Strings.Guard_ProcessUnreadable,
"ProcessTreeUnavailable" => Strings.Guard_ProcessTreeUnavailable,
"DriverScanFailed" => Strings.Guard_DriverScanFailed,
"ServiceQueryFailed" => Strings.Guard_ServiceQueryFailed,
"RulesUnreadable" => Strings.Guard_RulesUnreadable,
"RulesMalformed" => Strings.Guard_RulesMalformed,
"RulesIncomplete" => Strings.Guard_RulesIncomplete,
"PreScanFailed" => Strings.Guard_PreScanFailed,
"InjectionFailed" => Strings.Guard_InjectionFailed,
"TargetIsWow64" => Strings.Guard_TargetIsWow64,
"PayloadNotOurs" => Strings.Guard_PayloadNotOurs,
"HookNotEnabled" => Strings.Guard_HookNotEnabled,
"ConsentMissing" => Strings.Guard_ConsentMissing,
"PreviouslyBlocked" => Strings.Guard_PreviouslyBlocked,
"LaunchTargetExited" => Strings.Guard_LaunchTargetExited,
"LaunchNoPresentationRuntime" => Strings.Guard_LaunchNoPresentationRuntime,
"TargetIsVulkanLayered" => Strings.Guard_TargetIsVulkanLayered,
"SuspiciousUnsigned" => Strings.Guard_SuspiciousUnsigned,
_ => string.Format(CultureInfo.CurrentCulture, Strings.Guard_Other_Format, reason),
};
/// <summary>
/// How a session ended, in words (beta.8): a crash names its exception ("crashed (0xC0000005 access violation)"), an
/// exit code that is not one is an ordinary end with its code — End task's 1 said as what it is — and the other
/// statuses keep their words.
/// </summary>
public static string ExitText(ExitStatus status, CaptureNotes notes) => status switch
{
ExitStatus.Crashed => notes.ExitCode is { } code && ExitStatusMapper.IsExceptionCode(code)
? string.Format(CultureInfo.CurrentCulture, Strings.Exit_Crashed_Format, ExceptionName(code))
: Strings.Exit_CrashEvent,
ExitStatus.Normal => notes.ExitCode switch
{
null or 0 => Strings.Exit_EndedNormally,
1 => Strings.Exit_Code1,
{ } other => string.Format(CultureInfo.CurrentCulture, Strings.Exit_Code_Format, CodeText(other)),
},
_ => ExitStatusText(status),
};
/// <summary>The exception an exit code names, or the code in hex.</summary>
public static string ExceptionName(int code) => unchecked((uint)code) switch
{
0xC0000005 => Strings.Exit_Ex_AccessViolation,
0xC0000006 => Strings.Exit_Ex_InPageError,
0xC00000FD => Strings.Exit_Ex_StackOverflow,
0xC0000374 => Strings.Exit_Ex_HeapCorruption,
0xC0000409 => Strings.Exit_Ex_FailFast,
0xC0000142 => Strings.Exit_Ex_DllInit,
0xC0000135 => Strings.Exit_Ex_DllNotFound,
0xC000007B => Strings.Exit_Ex_BadImage,
0xE06D7363 => Strings.Exit_Ex_Cpp,
0xE0434352 => Strings.Exit_Ex_Clr,
0x80000003 => Strings.Exit_Ex_Breakpoint,
_ => CodeText(code),
};
/// <summary>An exit code as a person reads it: small ones in decimal, NTSTATUS-shaped ones in hex.</summary>
private static string CodeText(int code) =>
code is >= -255 and <= 65535 ? code.ToString(CultureInfo.CurrentCulture) : "0x" + unchecked((uint)code).ToString("X8", CultureInfo.InvariantCulture);
/// <summary>A launch's Win32 error in words (beta.8): the few a game launch meets, and the number otherwise.</summary>
public static string LaunchErrorText(int error) => error switch
{
2 => Strings.Launch_Error_2,
3 => Strings.Launch_Error_3,
5 => Strings.Launch_Error_5,
193 => Strings.Launch_Error_193,
740 => Strings.Launch_Error_740,
1400 => Strings.Launch_Error_1400,
_ => string.Format(CultureInfo.CurrentCulture, Strings.Launch_Error_Format, error),
};
/// <summary>
/// Why an executable is not where the row says (beta.8): a drive that is not connected — the owner's external drive
/// changes letter, 2026-09-22 — is said as that, and FrameLedger finds the game again when it is back; otherwise the
/// file itself is gone from its path.
/// </summary>
public static string ExecutableMissingText(string exePath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
string? root = Path.GetPathRoot(exePath);
return !string.IsNullOrEmpty(root) && !Directory.Exists(root)
? string.Format(CultureInfo.CurrentCulture, Strings.Exe_DriveMissing_Format, root)
: string.Format(CultureInfo.CurrentCulture, Strings.Exe_FileMissing_Format, exePath);
}
}
@@ -0,0 +1,18 @@
namespace FrameLedger.App.Services;
/// <summary>
/// <c>ui.fps_decimals</c> as the formatters read it (beta.8, owner request 2026-09-25): whether every FPS figure shows two
/// decimals ("62.40") or a whole number ("62"). One process-wide value like <see cref="LoggingLevel"/>: set from the settings
/// row at start and by the Settings page when it changes; a page shows it the next time it formats a number.
/// </summary>
public static class FpsDecimals
{
private static volatile bool _two;
/// <summary>True: two decimals, always ("62.40"); false: a whole number.</summary>
public static bool Two
{
get => _two;
set => _two = value;
}
}
@@ -70,6 +70,8 @@ public static class FpsPresentation
FpsReadoutModel m = FromRow(row);
return m.Kind switch
{
// A steady-state factor carries its share in the grid too (rule 6; beta.8 — the column was the one place it did not).
FpsReadoutKind.Generated when m.Factor is double f && m.SteadyShare is double share => string.Format(CultureInfo.CurrentCulture, "×{0:0.0} · {1:0}%", f, share * 100),
FpsReadoutKind.Generated when m.Factor is double f => string.Format(CultureInfo.CurrentCulture, "×{0:0.0}", f),
FpsReadoutKind.None => Strings.Common_Dash,
_ => Strings.Common_NotAvailable,
@@ -104,8 +106,15 @@ public static class FpsPresentation
};
}
public static string GeneratedLine(double? native, double? displayed, double factor) =>
string.Format(CultureInfo.CurrentCulture, Strings.Fps_Fg_Format, Formats.Fps(native), Formats.Fps(displayed), factor);
public static string GeneratedLine(double? native, double? displayed, double factor) => GeneratedLine(native, displayed, factor, steadyShare: null);
/// <summary>
/// <c>62 → 118 FPS (×1.9 FG)</c> — and a steady-state factor (CLAUDE.md rule 6, 2026-09-17) always with the share of the
/// session it covers, <c>(×1.9 FG · 75%)</c>, wherever the line appears (beta.8: the Average card and Compare dropped it).
/// </summary>
public static string GeneratedLine(double? native, double? displayed, double factor, double? steadyShare) => steadyShare is double share
? string.Format(CultureInfo.CurrentCulture, Strings.Fps_Fg_Steady_Format, Formats.Fps(native), Formats.Fps(displayed), factor, share * 100)
: string.Format(CultureInfo.CurrentCulture, Strings.Fps_Fg_Format, Formats.Fps(native), Formats.Fps(displayed), factor);
public static string PresentedLine(double? presented) => string.Format(CultureInfo.CurrentCulture, Strings.Fps_Presented_Format, Formats.Fps(presented));
@@ -49,7 +49,7 @@ public sealed record FpsReadoutModel
/// <summary>The one line, per the rule: <c>62 → 118 FPS (×1.9 FG)</c>, or <c>144 FPS</c>. Never a factor that was not counted.</summary>
public string Line => Kind switch
{
FpsReadoutKind.Generated when Factor is double f => FpsPresentation.GeneratedLine(Native, Displayed, f),
FpsReadoutKind.Generated when Factor is double f => FpsPresentation.GeneratedLine(Native, Displayed, f, SteadyShare),
FpsReadoutKind.None => FpsPresentation.PresentedLine(Native),
FpsReadoutKind.Presented or FpsReadoutKind.IdentifiedUncounted => FpsPresentation.PresentedLine(Presented),
_ => Strings.Common_NotAvailable,
+13 -1
View File
@@ -1,6 +1,8 @@
using System.IO;
using FrameLedger.Application.Import;
using FrameLedger.Application.Persistence;
using FrameLedger.Domain.Consent;
using FrameLedger.Infrastructure.Import;
using FrameLedger.Infrastructure.Io;
namespace FrameLedger.App.Services;
@@ -60,10 +62,14 @@ public sealed class GameLibrary
return null;
}
string name = Path.GetFileNameWithoutExtension(normalised);
// A generic executable (Game.exe) is named from the game's own title or its folder, not "Game" (2026-09-23).
string name = GameTitleGuess.Guess(normalised, () => RpgMakerTitle.TryRead(normalised));
return await _games.EnsureAsync(fingerprint.Value, name, ct).ConfigureAwait(false);
}
/// <summary>Whether the row's executable is where the row says (2026-09-22): the page's "not found" line, nothing else.</summary>
public static bool ExecutableExists(string normalisedExePath) => ExecutableIdentity.Read(normalisedExePath) is not null;
/// <summary>
/// Points the row at another executable; null when the file cannot be read, false when another row owns that path.
/// The caller revokes consent over the pipe FIRST, as removal does: the table write only downgrades.
@@ -83,6 +89,12 @@ public sealed class GameLibrary
public Task<bool> RemoveAsync(long gameId, bool keepSessions, CancellationToken ct = default) => _games.RemoveAsync(gameId, keepSessions, ct).AsTask();
/// <summary>
/// The entry's recording switch (schema 0009, 2026-09-23). The Agent reads the same table each tick, so nothing is
/// sent over the pipe: off, it stops watching for the program and stops a session of it that is running.
/// </summary>
public Task<bool> SetRecordingAsync(long gameId, bool record, CancellationToken ct = default) => _games.SetRecordingAsync(gameId, record, ct).AsTask();
public Task<bool> UpdateMetadataAsync(long gameId, GameMetadata metadata, CancellationToken ct = default) => _games.UpdateMetadataAsync(gameId, metadata, ct).AsTask();
/// <summary>The Dashboard's recent list: the last <paramref name="count"/> sessions across games, with their game names.</summary>
@@ -1,71 +0,0 @@
using System.IO;
using FrameLedger.Infrastructure.Ipc;
using FrameLedger.Shared.Ipc;
using FrameLedger.Shared.Safety;
using Serilog;
namespace FrameLedger.App.Services;
/// <summary>
/// The per-game guard bypass as the App performs it (owner decision 2026-09-21, <c>19_SAFETY</c> §The user's bypass):
/// show the disclosure, and only when it was accepted by both of its acts ask the Agent to record it. The App writes
/// nothing itself — the acknowledgement is stamped by the Agent, over the pipe, exactly as consent is — and the Agent
/// re-checks the disclosure version and the executable, because the pipe is not a trust boundary.
/// </summary>
/// <remarks>
/// There is no "all games" form of this and no setting that pre-accepts it: every game is its own dialog.
/// </remarks>
public sealed class GuardBypass
{
private readonly IAgentRequests _agent;
private readonly IGuardBypassPrompt _prompt;
public GuardBypass(IAgentRequests agent, IGuardBypassPrompt prompt)
{
_agent = agent ?? throw new ArgumentNullException(nameof(agent));
_prompt = prompt ?? throw new ArgumentNullException(nameof(prompt));
}
public async Task<GuardBypassResult> EnableAsync(long gameId, string gameName, string? finding, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(gameName);
if (!_agent.IsConnected)
{
return new GuardBypassResult(GuardBypassOutcome.AgentUnavailable);
}
if (!await _prompt.ShowAsync(gameName, finding, ct).ConfigureAwait(true))
{
return new GuardBypassResult(GuardBypassOutcome.Declined);
}
return await SendAsync(new SetGuardBypassRequest(gameId, Enabled: true, GuardBypassDisclosure.Version), GuardBypassOutcome.Enabled, ct).ConfigureAwait(true);
}
public Task<GuardBypassResult> DisableAsync(long gameId, CancellationToken ct = default) =>
_agent.IsConnected
? SendAsync(new SetGuardBypassRequest(gameId, Enabled: false, null), GuardBypassOutcome.Disabled, ct)
: Task.FromResult(new GuardBypassResult(GuardBypassOutcome.AgentUnavailable));
private async Task<GuardBypassResult> SendAsync(SetGuardBypassRequest request, GuardBypassOutcome onWritten, CancellationToken ct)
{
try
{
IpcEnvelope ack = await _agent.RequestAsync(IpcMessageType.SetGuardBypass, request, ct).ConfigureAwait(true);
if (!string.Equals(ack.Type, IpcMessageType.GuardBypassAck, StringComparison.Ordinal))
{
return new GuardBypassResult(GuardBypassOutcome.Failed, "UnexpectedAck:" + ack.Type);
}
GuardBypassAck? outcome = IpcCodec.Payload<GuardBypassAck>(ack);
return outcome is not null && outcome.Enabled == request.Enabled
? new GuardBypassResult(onWritten, outcome.Outcome)
: new GuardBypassResult(GuardBypassOutcome.Failed, outcome?.Outcome ?? "EmptyAck");
}
catch (Exception ex) when (ex is IpcRequestException or TimeoutException or IOException or InvalidOperationException)
{
Log.Warning(ex, "bypass: SetGuardBypass(game {GameId}, {Enabled}) did not complete", request.GameId, request.Enabled);
return new GuardBypassResult(GuardBypassOutcome.Failed, ex is IpcRequestException ipc ? ipc.Code ?? IpcMessageType.Error : ex.GetType().Name);
}
}
}
@@ -1,20 +0,0 @@
namespace FrameLedger.App.Services;
/// <summary>What happened when the user moved a game's guard-bypass switch (owner decision 2026-09-21).</summary>
public enum GuardBypassOutcome
{
/// <summary>The Agent recorded the acknowledgement: the bypass is on for this game.</summary>
Enabled,
/// <summary>The Agent withdrew it: the guard is a hard gate for this game again.</summary>
Disabled,
/// <summary>The disclosure was closed without both acts. Nothing was sent.</summary>
Declined,
/// <summary>No Agent to record it; nothing changed.</summary>
AgentUnavailable,
/// <summary>The Agent answered with something other than a written acknowledgement; <c>Detail</c> says what.</summary>
Failed,
}
@@ -1,41 +0,0 @@
using System.Windows.Data;
using FrameLedger.App.Dialogs;
using FrameLedger.App.ViewModels;
using Wpf.Ui;
using Wpf.Ui.Controls;
namespace FrameLedger.App.Services;
/// <summary>
/// <see cref="IGuardBypassPrompt"/> as a <c>ContentDialog</c>, the shape FR-2.1's consent dialog has and stricter: the
/// primary button is the Danger one, it is enabled only while the checkbox is ticked AND the phrase is typed, and Enter
/// keeps the guard on.
/// </summary>
public sealed class GuardBypassPrompt : IGuardBypassPrompt
{
private readonly IContentDialogService _dialogs;
public GuardBypassPrompt(IContentDialogService dialogs) => _dialogs = dialogs ?? throw new ArgumentNullException(nameof(dialogs));
public async Task<bool> ShowAsync(string gameName, string? finding, CancellationToken ct = default)
{
var viewModel = new GuardBypassDialogViewModel(gameName, finding);
var dialog = new ContentDialog
{
Title = viewModel.Title,
Content = new GuardBypassDialogContent(viewModel),
PrimaryButtonText = GuardBypassDialogViewModel.ConfirmText,
PrimaryButtonAppearance = ControlAppearance.Danger,
CloseButtonText = GuardBypassDialogViewModel.KeepGuardText,
// Enter keeps the guard on; only a click on the (doubly gated) primary overrules it.
DefaultButton = ContentDialogButton.Close,
IsPrimaryButtonEnabled = false,
DialogMaxWidth = 720,
};
_ = dialog.SetBinding(ContentDialog.IsPrimaryButtonEnabledProperty, new Binding(nameof(GuardBypassDialogViewModel.IsConfirmed)) { Source = viewModel, Mode = BindingMode.OneWay });
ContentDialogResult result = await _dialogs.ShowAsync(dialog, ct).ConfigureAwait(true);
// The binding is the gate on the button; this is the same rule read once more at the moment that matters.
return result == ContentDialogResult.Primary && viewModel.IsConfirmed;
}
}
@@ -1,6 +0,0 @@
using System.Runtime.InteropServices;
namespace FrameLedger.App.Services;
[StructLayout(LayoutKind.Auto)]
public readonly record struct GuardBypassResult(GuardBypassOutcome Outcome, string? Detail = null);
@@ -12,7 +12,7 @@ public enum HookingConsentOutcome
/// <summary>The user closed the dialog without the acknowledgement; nothing was sent.</summary>
Declined,
/// <summary>The Agent's pre-scan refused (<c>Refused</c>): a block is on the row. This dialog offers no way past it; the one override is the per-game guard bypass, with its own disclosure (<c>19_SAFETY</c> §The user's bypass, 2026-09-21).</summary>
/// <summary>The Agent's pre-scan refused (<c>Refused</c>): a block is on the row, and there is no way past it (<c>19_SAFETY</c> §What a finding does to the game).</summary>
Refused,
/// <summary>The Agent stamps against another version of the disclosure than this app shows; the dialog was not opened (D14).</summary>
@@ -21,9 +21,18 @@ public sealed record HookingConsentResult(HookingConsentOutcome Outcome, string?
return Shared.Strings.Safety_Refused_CouldNotVerify;
}
string? family = Refusal.Family ?? Refusal.Signal;
return family is null
? Shared.Strings.Safety_Refused_Unnamed
: string.Format(System.Globalization.CultureInfo.CurrentCulture, Shared.Strings.Safety_Refused_Named_Format, family, Refusal.Signal ?? Refusal.Reason);
// beta.8: the Agent refused because the executable cannot run as x64 — nothing was scanned (AgentCommandHandler.NotX64Reason).
if (string.Equals(Refusal.Reason, "ExecutableNotX64", StringComparison.Ordinal))
{
return string.Format(System.Globalization.CultureInfo.CurrentCulture, Strings.Hooking_NotX64_Format, Formats.Architecture(Refusal.Signal));
}
// A refusal no family names is said as what it is (beta.8), never as its signal "detected in this game".
if (Refusal.Family is null)
{
return string.IsNullOrEmpty(Refusal.Reason) ? Shared.Strings.Safety_Refused_Unnamed : Formats.GuardSentence(Refusal.Reason);
}
return string.Format(System.Globalization.CultureInfo.CurrentCulture, Shared.Strings.Safety_Refused_Named_Format, Refusal.Family, Refusal.Signal ?? Refusal.Reason);
}
}
@@ -0,0 +1,11 @@
namespace FrameLedger.App.Services;
/// <summary>
/// The admin mode's disclosure as a question (beta.10, owner decision D34): shows the versioned text and answers whether the
/// user understood and chose to have the Agent started as administrator. The WPF implementation is
/// <see cref="AgentAdminPrompt"/>; a test substitutes an answer.
/// </summary>
public interface IAgentAdminPrompt
{
Task<bool> ShowAsync(CancellationToken ct = default);
}
@@ -17,6 +17,12 @@ public interface IAgentLauncher
/// </summary>
string? RunningAgent { get; }
/// <summary>
/// Whether <see cref="TryStart"/> would show Windows' administrator prompt (beta.10, the admin mode on and this App a
/// standard user's) — the pill says so while the round waits for the answer. A launcher that never asks answers false.
/// </summary>
bool WillAskForElevation => false;
/// <summary>Start <c>FrameLedger.Agent.exe --serve</c>, detached; false when it could not be started.</summary>
bool TryStart();
}
@@ -22,4 +22,9 @@ public interface IAgentLink : IAgentRequests
/// apply asks the Agent to stop and must not have it restarted under the updater). Released on a failed apply.
/// </summary>
void SetLaunchHold(bool hold);
/// <summary>Skip the wait before the next connect round (the banner's Retry; the admin mode's restart, beta.10).</summary>
void RetryNow()
{
}
}
@@ -0,0 +1,11 @@
namespace FrameLedger.App.Services;
/// <summary>
/// D33's disclosure as a question: shows the versioned text for one game and answers whether the user accepted the risk
/// and chose to make the exception. The WPF implementation is <see cref="AntiCheatExceptionPrompt"/>; a test substitutes an
/// answer.
/// </summary>
public interface IAntiCheatExceptionPrompt
{
Task<bool> ShowAsync(AntiCheatExceptionFacts facts, CancellationToken ct = default);
}
@@ -1,15 +0,0 @@
namespace FrameLedger.App.Services;
/// <summary>
/// The guard-bypass disclosure (owner decision 2026-09-21, <c>19_SAFETY</c> §The user's bypass): true only when the user
/// ticked the acknowledgement AND typed the confirmation phrase AND pressed the primary button. A seam so the flow is
/// testable without a window.
/// </summary>
public interface IGuardBypassPrompt
{
/// <summary>Shows the disclosure for one game and answers whether both acts were performed.</summary>
/// <param name="gameName">The game the bypass is for; it applies to no other.</param>
/// <param name="finding">What the guard has recorded for this game (the row's block reason), or null when nothing yet.</param>
/// <param name="ct">Cancels the dialog; a cancelled disclosure is a declined one.</param>
Task<bool> ShowAsync(string gameName, string? finding, CancellationToken ct = default);
}
Loaded 100 of 452 files, more files were not shown because too many files have changed in this diff. Show more