Compare commits
1
Commits
main
...
beta12/pr6-docs
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
9406908c7f |
No files matched your search
@@ -1,9 +1,11 @@
|
||||
# Gate changes to the detection + anti-cheat rules (docs/13_CI_CD.md).
|
||||
#
|
||||
# The raw file on `main` IS the distribution endpoint (docs/05_DETECTION.md),
|
||||
# so there is nothing to publish — this workflow only gates correctness. That
|
||||
# also means a bad merge ships to every user on their next rules check, which
|
||||
# is why the anticheat block gets extra scrutiny here.
|
||||
# There is nothing to publish: no rules feed exists (docs/20_OPEN_QUESTIONS.md
|
||||
# §S20 feed half), so a rules change reaches users inside a release, seeded by
|
||||
# the Agent from the packaged copy. This header said the raw file on `main` was
|
||||
# the distribution endpoint until 2026-10-04. This workflow only gates
|
||||
# correctness, and the anticheat block still gets the extra scrutiny, because
|
||||
# whatever merges here ships in the next release.
|
||||
|
||||
name: Rules
|
||||
|
||||
|
||||
+20
-2
@@ -10,7 +10,8 @@ bumps for a database schema or IPC protocol break (`docs/11_UPDATER.md`).
|
||||
uses it as the GitHub release body. A missing or empty `## [x.y.z]` section is a **red
|
||||
release**, not an empty note — so cutting a release means moving the `[Unreleased]` entries
|
||||
under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, then tagging
|
||||
(`docs/13_CI_CD.md` §Branch & release policy).
|
||||
(`docs/13_CI_CD.md` §Branch & release policy). *(For a pre-release, `vX.Y.Z-beta.N`, `VERSION` already holds the
|
||||
numeric core and does not move; the heading is the full version — corrected 2026-10-04.)*
|
||||
|
||||
> **Built 2026-09-14 (P4 PR-5).** From 2026-08-06 until then this paragraph said the workflow
|
||||
> "will" exist and that a missing section "will mean an empty release note"; the second half
|
||||
@@ -103,8 +104,26 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
|
||||
history notes move to `docs/legal-drift-history.md`).
|
||||
- **Help ▸ Documentation is Help ▸ Online documentation**, and opens the README of the version you run.
|
||||
|
||||
### Removed
|
||||
|
||||
- **Settings ▸ Recording no longer shows "Record games launched outside FrameLedger".** Nothing ever read that switch —
|
||||
turning it off recorded every game anyway — and the App has no way to start a game itself, so "off" could only have
|
||||
meant recording nothing. Its stored value is kept, unread, until a launch path exists.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The Logs page's Warning and Error filters showed no line from the Agent.** The Agent's log starts each line with a
|
||||
date (Serilog's default form) and the filter read only the App's `[HH:mm:ss.fff LVL]` prefix; its test had fed App-form
|
||||
lines into the fake Agent log. Both forms are read now.
|
||||
- **The developer documentation is corrected in place** (owner decision D46): about a hundred statements across
|
||||
`docs/01`–`20`, `HANDOFF`, `CLAUDE.md` and `FORKING.md` that the code contradicted, each struck with a dated
|
||||
correction — among them a rules feed that does not exist (rules reach you with a release, as `LIMITATIONS.md` says),
|
||||
hooks that were never built, the in-game thread described as doing less than it does, a delta update package that was
|
||||
never published, the release steps for a pre-release, the Legal Gate's row count and the logging configuration. The
|
||||
rules file's own comment and the rules workflow's header made the feed claim too, and are corrected. `docs/README.md`
|
||||
is a new index for developers. Code comments that said what is not so (a sparkline, a flyout, a layer flag "false by
|
||||
construction", two self-test counts) are corrected with them.
|
||||
|
||||
- **The first start's summary said "there is no way to override that refusal"** although a per-game user-mode exception
|
||||
has existed since beta.9, and **"Nothing is sent anywhere"** although the update check is a request to GitHub; it now
|
||||
names the exception and the one request. The README's safety table still said an exception needed two earlier
|
||||
@@ -130,7 +149,6 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
|
||||
session opens no process (`04_CAPTURE`, `19_SAFETY`) now say what it opens, with which right, and why. The accuracy block
|
||||
and `LIMITATIONS.md` say what is measured now. `ITelemetryPoller`'s remark that the descriptor is read at finalize — it is
|
||||
read at session start — is corrected.
|
||||
|
||||
- **The native binaries' version block named the wrong licence.** Every DLL's `LegalCopyright` read
|
||||
`GPL-3.0-or-later` while `LICENSE`, the EULA, the README and the third-party notices all say GPL-3.0-only; it now reads
|
||||
`Copyright (C) 2026 poli0981. GPL-3.0-only with additional terms: see NOTICE`.
|
||||
|
||||
@@ -23,7 +23,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
5. **The hook must never crash the game.** Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (`17_HOOK_ENGINE` §Fault policy).
|
||||
6. **FPS display rule (product requirement):** wherever FPS is shown and Frame Generation is active, show *Native FPS*, *Displayed FPS*, and the FG factor together (`62 → 118 FPS (×1.9 FG)`). Never a single inflated number. See `docs/03_METRICS.md`.
|
||||
|
||||
> **Amended 2026-09-03 (owner decision).** When frame generation is *not measured* — `FL_MEASURED_FG` clear, which is every title on today's writer — the one number that may stand alone is **Presented FPS** (`presents / D`), with a mandatory qualifier from the **runtime census** (`FlWriterState.runtimeCensus`): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. **The census never produces `none`**: a statically linked FSR has no module to see, and a census-`none` there would be exactly the inflated number this rule forbids.
|
||||
> **Amended 2026-09-03 (owner decision).** When frame generation is *not measured* — `FL_MEASURED_FG` clear, ~~which is every title on today's writer~~ which is every title with no Streamline or FidelityFX hook live *(corrected 2026-10-04: the writer sets it since #103, 2026-09-03)* — the one number that may stand alone is **Presented FPS** (`presents / D`), with a mandatory qualifier from the **runtime census** (`FlWriterState.runtimeCensus`): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. **The census never produces `none`**: a statically linked FSR has no module to see, and a census-`none` there would be exactly the inflated number this rule forbids.
|
||||
>
|
||||
> **Amended 2026-09-05.** A counted `none` (`presents = application frames`) is **withheld** — Presented FPS with a third qualifier, "this number counts application frames; the Displayed rate is unknown" — on the one shape measured to produce a false `none`: Streamline ≥ 2.8.0 with `sl.dlss_g.dll` loaded (Dying Light: The Beast, five captures, DLSS FG ×4 per the owner). `docs/03_METRICS.md` §Frame Generation carries the key and why it is the Streamline plugin rather than `nvngx_dlssg.dll`; `20_OPEN_QUESTIONS` §H5 carries the session that keeps or withdraws it.
|
||||
>
|
||||
@@ -47,6 +47,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
| UI | WPF + WPF UI (`WPF-UI` pinned = 4.3.0) + CommunityToolkit.Mvvm — `docs/16_WPFUI_SYNTAX.md` |
|
||||
| App composition | .NET Generic Host + DI in `FrameLedger.App` |
|
||||
| Charts | ScottPlot 5 |
|
||||
| Markdown in the App | **Markdig** (BSD-2-Clause, pinned 1.4.0) → WPF `FlowDocument`, HTML off, no image fetched — the Legal Gate, the user guide, Help ▸ Limitations, the update notes, About (beta.12; row added 2026-10-04) |
|
||||
| GPU telemetry | **The game process's own memory since beta.12 (D43):** `FrameLedger.ProcessStats.dll` (C++, loaded by the Agent, never into a game) reads its dedicated/shared GPU memory from the `GPU Process Memory` counters and its working sets from `GetProcessMemoryInfo` — `18_GPU_VENDOR_APIS` §The game process's memory. Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
|
||||
| CPU/board sensors | LibreHardwareMonitorLib ≥ 0.9.6 (PawnIO) — **optional**, elevated only |
|
||||
| Tier-2 fallback | **There is none, and Tier 2 is not a measurement.** Owner decision 2026-08-28: the ladder is two rungs — hooked, or duration + sensors + the reason. ~~ETW-based, no injection~~; ~~Intel PresentMon console binary~~ dropped 2026-08-27 after §S31 retired it. Whether a shipped build ever regains a no-injection measurement is `docs/20_OPEN_QUESTIONS.md` §G |
|
||||
@@ -72,6 +73,10 @@ src/
|
||||
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe
|
||||
FrameLedger.VkLayer/ # C++20 Vulkan implicit layer DLL + manifest JSON
|
||||
FrameLedger.Shm/ # header-only: ring buffer + record layout, shared by native & C# (mirrored)
|
||||
FrameLedger.NvapiBridge/ # C++ DLL loaded by the Agent (never a game): NVAPI telemetry, NGX state (P2 PR-E2)
|
||||
FrameLedger.ProcessStats/ # C++ DLL loaded by the Agent (never a game): the game process's memory (beta.12, D43)
|
||||
tests/ tools/ third_party/ # ctest suites; probes, hook-harness, vendor stubs; vendored headers
|
||||
# (these five lines added 2026-10-04 — the list stopped at Shm)
|
||||
FrameLedger.Domain/ # entities, metric calculators — zero dependencies
|
||||
# (Metrics/ WRITTEN 2026-09-09, P2 PR-A: frame times,
|
||||
# percentiles, lows, stutter, the FG window and its
|
||||
@@ -90,7 +95,8 @@ src/
|
||||
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
|
||||
# reader, HeldProcessLivenessSource, TargetResolver (path only,
|
||||
# never a pid), ProcessLauncher, the module snapshot, the marker scan
|
||||
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + ShmRecord struct mirror
|
||||
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + the struct mirror (ShmLayout.cs;
|
||||
# it said "ShmRecord", a type that never existed, until 2026-10-04)
|
||||
FrameLedger.Agent/ # capture orchestrator: watcher, injector control, shm drain, recorder
|
||||
# BUILT 2026-09-10 (P2 PR-F): a Generic Host. `--serve` = watcher
|
||||
# (Application.Watch: ProcessWatcher, ProcessTree, DescendantElection,
|
||||
@@ -120,12 +126,18 @@ src/
|
||||
# is not what holds rule 1.
|
||||
tests/
|
||||
FrameLedger.Domain.Tests/ FrameLedger.Application.Tests/ FrameLedger.Infrastructure.Tests/
|
||||
FrameLedger.Agent.Tests/ FrameLedger.App.Tests/
|
||||
FrameLedger.CaptureHost.Tests/ # incl. the Category=Integration end-to-end case
|
||||
native/FrameLedger.Overlay.Tests/ # Catch2: ring buffer, record encode, fault policy
|
||||
tools/ # changelog-check, chokepoint-check, coverage-gate, gen-ac-floor,
|
||||
# hookinventory-check, license-check, package-closure-check,
|
||||
# rules-validate, vendor-exports, versioninfo-check,
|
||||
# vklayer-blastradius
|
||||
Shared/ fixtures/ # test helpers; the detection corpus and other fixtures
|
||||
~~native/FrameLedger.Overlay.Tests/~~ # never existed (corrected 2026-10-04): the native tests are
|
||||
# src/native/tests/ (ctest, mostly Catch2 — ring, guard, layout,
|
||||
# vklayer, unhook, rules budget, NVAPI bridge, process stats)
|
||||
tools/ # accuracy-check, changelog-check, chokepoint-check, coverage-gate,
|
||||
# gen-ac-floor, hookinventory-check, license-check, license-gather
|
||||
# (+ license-overrides/), notice-check, package-closure-check,
|
||||
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
|
||||
# versioninfo-check, vklayer-blastradius, fps-impact-runbook
|
||||
# (six names added 2026-10-04)
|
||||
# (PowerShell). This line used to name three, one of which
|
||||
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
|
||||
# resx-gen (the committed Strings.Designer.cs generator).
|
||||
@@ -133,6 +145,9 @@ tools/ # changelog-check, chokepoint-check, coverage-gat
|
||||
# fl-layout-dump -> struct offsets for the C# mirror test
|
||||
# hook-harness -> dummy D3D11 + D3D12 + Vulkan + OpenGL app
|
||||
# (--vulkan since #140, --opengl since #141)
|
||||
# fl-probe-* -> guard, hook profile, interposer, NVAPI, process
|
||||
# stats, signer, Vulkan layer; fl-baseline-probe;
|
||||
# vendor-stubs/ -> fixture DLLs with the vendors' export names
|
||||
rules/detection-rules.json # engine/platform/capability + anticheat blocklist
|
||||
guide/ # the user guide (beta.12, D44): eight short English pages for players, embedded in the
|
||||
# App (Help > User guide); README.md is its contents. docs/ is for developers.
|
||||
@@ -145,11 +160,11 @@ Dependency direction: `App/Agent → Application → Domain`; **`Application →
|
||||
|
||||
**C# —** `Nullable enable`, `TreatWarningsAsErrors`, `AnalysisLevel latest-all`, file-scoped namespaces, Roslynator + Meziantou + VS Threading analyzers, `dotnet format` clean. Async suffixed `Async`, `ConfigureAwait(false)` off the UI. All user-visible strings from `.resx`. Timestamps UTC (unix-ms in SQLite); QPC ticks only inside the capture pipeline.
|
||||
|
||||
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: `/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`).
|
||||
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: ~~`/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`)~~ CodeQL (`codeql.yml`, a required check); `/analyze` and clang-tidy are not configured *(corrected 2026-10-04)*.
|
||||
|
||||
**Licence header —** every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`) opens with two comment lines, `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` (beta.12, owner decision D45). GPLv3 §7 requires additional terms to be named in the source files, and `NOTICE` holds them — (b) preserve the notices, (c) mark modified versions, (e) no trademark rights in the name. `tools/notice-check.ps1` is a `build.ps1` gate; `-Fix` writes a missing header. `src/native/third_party/` is excluded.
|
||||
|
||||
**Struct mirroring —** `FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock` each exist twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by `tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
|
||||
**Struct mirroring —** ~~`FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock`~~ `FlShmHandshake`, `FlWriterState`, `FlControlBlock`, `FlDisplayState` (layout 4, beta.10), `FlFrameRecord` and `FlTolerance` (D33, beta.9) each exist twice *(corrected 2026-10-04)*: `src/native/FrameLedger.Shm/include/fl_shm.h` / `fl_tolerance.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by ~~`tools/fl-layout-dump`~~ `src/native/tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
|
||||
|
||||
It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReferences`), because offsets cannot see it: measured 2026-08-05, swapping the `fixed byte BuildId[32]` for this repo's own `[MarshalAs(ByValTStr)] string` idiom keeps `Marshal.SizeOf` at 64 and every offset correct while `Unsafe.SizeOf` collapses to **40** — a mirror that passes the obvious checks and cannot be read out of a memory-mapped view.
|
||||
|
||||
@@ -157,7 +172,7 @@ It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReference
|
||||
|
||||
The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` gives the Agent a build id of its own and `ShmHandshakeValidator` performs the refuse-to-attach comparison `07_IPC` specifies (§S23-1). **Its default is `NotEvaluated`, not `Ok`** — a result nobody produced has validated nothing, the same rule `AntiCheatVerdict` follows.
|
||||
|
||||
**Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. `tools/hook-harness` is a dummy **D3D11 + D3D12 + Vulkan + OpenGL** app used to exercise hooks without a real game — `--vulkan` since #140 and `--opengl` since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (`docs/12_BUILD.md` §Targets is the accurate list).
|
||||
**Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. ~~`tools/hook-harness`~~ `src/native/tools/hook-harness` (path corrected 2026-10-04) is a dummy **D3D11 + D3D12 + Vulkan + OpenGL** app used to exercise hooks without a real game — `--vulkan` since #140 and `--opengl` since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (`docs/12_BUILD.md` §Targets is the accurate list).
|
||||
|
||||
## Definition of done (per PR)
|
||||
|
||||
|
||||
+4
-3
@@ -60,12 +60,13 @@ share — and migrate — one database, and fight over the same pipe and shared
|
||||
| Product name, icon, title | the App's resources, `--packTitle` in `release.yml`, `Strings.resx` | NOTICE (c) and (e) |
|
||||
| Update feed | `VelopackUpdateClient.RepositoryUrl` (`src/FrameLedger.App/Update/VelopackUpdateClient.cs`) | otherwise your users are offered FrameLedger's releases, and FrameLedger's users yours |
|
||||
| Install folder | `--packId` in `release.yml` (today `FrameLedger.App`) | Velopack installs into `%LOCALAPPDATA%\<packId>` and **deletes that folder on uninstall** — never choose a packId that equals any data folder |
|
||||
| Data folder | `LedgerPaths` (`src/FrameLedger.Infrastructure/Persistence/LedgerPaths.cs`) and the other `%LOCALAPPDATA%\FrameLedger` paths (`DetectionRulesFile`, `VkLayerLaunchEnvironment`, the Overlay's log folder) | a newer schema migrates the database in place and an older build cannot open it again |
|
||||
| Data folder | `LedgerPaths` (`src/FrameLedger.Infrastructure/Persistence/LedgerPaths.cs`) and the other `%LOCALAPPDATA%\FrameLedger` paths (`DetectionRulesFile`, `VkLayerLaunchEnvironment`, the Overlay's log folder, and the guard's own `fl::guard::RulesFilePath` in `src/native/FrameLedger.Injector/src/fl_ac_rules.cpp`) | a newer schema migrates the database in place and an older build cannot open it again |
|
||||
| Agent pipe | `IpcProtocol.PipeName` (`src/FrameLedger.Shared/Ipc/IpcProtocol.cs`) | the App talks to whichever agent owns the pipe |
|
||||
| Shared memory and mutex names | `Local\FrameLedger.*` (the ring, the tolerance channel, `SingleInstance`, the agent's instance lock) — in C# and in `src/native` | two programs must not open each other's ring |
|
||||
| Vulkan layer | `VK_LAYER_FRAMELEDGER_overlay` and its `HKCU\SOFTWARE\Khronos\Vulkan\ImplicitLayers` registration | one implicit layer per name |
|
||||
| Vulkan layer | `VK_LAYER_FRAMELEDGER_overlay`, its `HKCU\SOFTWARE\Khronos\Vulkan\ImplicitLayers` registration, and its `FRAMELEDGER_ENABLE_VK_LAYER` / `DISABLE_FRAMELEDGER_VK_LAYER` variables (the manifest template in `src/native/FrameLedger.VkLayer/` and `VkLayerLaunchEnvironment`) | one implicit layer per name — and a fork that keeps the variables is switched on by every FrameLedger launch |
|
||||
| Start with Windows | `RunAtLogon.DefaultValueName` (`src/FrameLedger.Infrastructure/Startup/RunAtLogon.cs`) | one `HKCU\…\Run` value per name |
|
||||
| Logon task | `LogonTask` (the Agent's maintenance verbs) | one task per name |
|
||||
| Issue and help links | `IssueLink.Repository` (`src/FrameLedger.App/Services/IssueLink.cs`), the GitHub links in `LegalDocuments`, `LimitationsDocument`, `SettingsViewModel`, `.github/ISSUE_TEMPLATE/` | your users' reports belong in your tracker |
|
||||
| Issue and help links | `IssueLink.Repository` (`src/FrameLedger.App/Services/IssueLink.cs`) — `RepositoryLinks` builds every document link in the App from it and the source ref `release.yml` passes — plus the Releases link in `guide/01-install.md` and `.github/ISSUE_TEMPLATE/` | your users' reports belong in your tracker |
|
||||
| Who the documents name | `legal/EULA.md`, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md` name poli0981 as the Developer, with a contact | the person who distributes a build is the one its users deal with; review every claim they make, too — they describe FrameLedger's builds, not yours |
|
||||
| Version information | `FL_COMPANY_NAME` / `FL_PRODUCT_NAME` in `src/native/CMakeLists.txt`, and the `ProductName` that `tools/versioninfo-check.ps1` requires | anti-cheat vendors and users identify the DLLs loaded into games by it (`docs/19_SAFETY_AND_ANTICHEAT.md`); it must name your project |
|
||||
| Checksums | your own `SHA256SUMS.txt` | users verify what *you* built |
|
||||
|
||||
@@ -409,7 +409,7 @@ function Invoke-ProjectGates {
|
||||
Write-Step 'license-check'
|
||||
$licenseTool = Join-Path $repo 'tools/license-check.ps1'
|
||||
if (Test-Path $licenseTool) {
|
||||
# P4 PR-6: the NuGet half's generator proves itself first (fourteen cases, five that must be RED), then
|
||||
# P4 PR-6: the NuGet half's generator proves itself first (sixteen cases since beta.12, six that must be RED), then
|
||||
# license-check runs its live -Check over this build's restore output as its section 3.
|
||||
Invoke-Checked 'license-gather (self-test)' { & (Join-Path $repo 'tools/license-gather.ps1') -SelfTest }
|
||||
Invoke-Checked 'license-check' { & $licenseTool }
|
||||
|
||||
+14
-8
@@ -29,6 +29,12 @@
|
||||
└───────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
> **Corrected 2026-10-04 — the game-process box names hooks that were never built.** ~~NGX · XeSS ·
|
||||
> CreateStateObject · PSO hooks~~: NGX is licence-blocked, XeSS stops at the runtime census by licence, and
|
||||
> `CreateStateObject` and pipeline creation are unwritten rows of `17_HOOK_ENGINE` §Hook inventory. What the Overlay
|
||||
> does install: the DXGI present path, `wglSwapBuffers`, the Streamline and FidelityFX entry points, the two
|
||||
> `ID3D12GraphicsCommandList4` ray-tracing methods, and the `LoadLibraryExW` wake.
|
||||
|
||||
> `*` **`AntiCheatGuard` is a facade, not an implementation.** The guard is
|
||||
> native (`20_OPEN_QUESTIONS` §S13(a)); the box above is the P/Invoke wrapper
|
||||
> in `Infrastructure` that the Agent calls. Nothing managed parses rules or
|
||||
@@ -58,8 +64,8 @@
|
||||
|
||||
| Tier | Mechanism | Gets you | When used |
|
||||
|---|---|---|---|
|
||||
| **1** | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT/PT evidence, per-process VRAM, PSO stutter attribution, Reflex latency, present flags | Offline/single-player titles the user opted in |
|
||||
| **2** | None | **Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else** — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every measured field reads `N/A` (FR-4.9) | Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
|
||||
| **1** | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT ~~/PT~~ evidence, ~~per-process VRAM, PSO stutter attribution, Reflex latency,~~ present flags *(corrected 2026-10-04: path tracing, the in-game VRAM, PSO attribution and Reflex latency have no producer — `05_DETECTION` §Runtime facts)* | Offline/single-player titles the user opted in |
|
||||
| **2** | None | **Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else** — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every ~~measured~~ frame field reads `N/A` (FR-4.9) *(corrected 2026-10-04: two facts are measured from outside the game in both tiers — the display mode (beta.10) and the game process's memory (beta.12, D43))* | Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
|
||||
|
||||
Tier is recorded per session (`sessions.capture_tier`) and shown in the UI, because metric availability differs and comparing across tiers must be explicit.
|
||||
|
||||
@@ -91,7 +97,7 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
|
||||
- Agent idles at ~0% CPU: 1 Hz process poll. No capture machinery exists until a tracked game launches.
|
||||
- Session ends when the process tree exits, or on safety unhook, or on user stop.
|
||||
- The DLL is **not unloaded** from a live process after unhooking (threads may still be inside trampolines). It disables its hooks, stops writing, and goes dormant until the process exits. Documented, deliberate.
|
||||
- UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.
|
||||
- ~~UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.~~ *(Corrected 2026-10-04: closing the UI never stops the Agent. `Shutdown` is sent only for an update, by the uninstall hook and for the admin mode's restart; the background-capture setting was read by nothing, and its switch is gone since beta.12 — `06_DATA_MODEL` §Settings registry.)*
|
||||
- Single instance via named mutexes; the ring name is per-PID so multiple games can be captured simultaneously (rare but supported).
|
||||
|
||||
> **The single instance was specified here and not built until 2026-09-17**, and 0.1.0-beta.1 ran four Agents: an
|
||||
@@ -111,12 +117,12 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
|
||||
| Anti-cheat detected pre-injection | Refuse, explain which signal fired, offer Tier 2 |
|
||||
| Anti-cheat detected mid-session | Immediate clean unhook, `exit_status = unhooked_safety`, prominent notice |
|
||||
| Injection API fails (access denied, protected process) | Log, no retry loop, offer Tier 2 + "run Agent elevated" hint — elevation here is about *attaching to an elevated target*, not about reaching a tier; Tier 2 needs none |
|
||||
| Hook faults 3× | DLL self-disables, sets fault flag in handshake block, Agent finalizes session as `degraded` |
|
||||
| Hook faults 3× | DLL self-disables, sets ~~fault flag in handshake block~~ `FlWriterState.status` to `SELF_DISABLED` *(corrected 2026-10-04)*, Agent finalizes session as `degraded` |
|
||||
| Game crashes ≤ 60 s after injection, twice | Hooking auto-disabled for that game, Tier 2 takes over |
|
||||
| Ring overflow (Agent stalled) | Overwrite-oldest; dropped count published in the ring header → session flagged with a data-quality warning |
|
||||
| Ring overflow (Agent stalled) | Overwrite-oldest; ~~dropped count published in the ring header~~ the Agent counts drops from its own read index *(corrected 2026-10-04: the writer keeps no reader index and publishes no count — `04_CAPTURE` §Ring draining)* → session flagged with a data-quality warning |
|
||||
| Layout/version mismatch DLL ↔ Agent | Agent refuses to attach, tells user to restart the game after update |
|
||||
| Vendor API unavailable (no NVAPI etc.) | GPU telemetry degrades to `N/A`; frame metrics unaffected |
|
||||
| DB locked/corrupt | Integrity check + backup-and-recreate in Tools |
|
||||
| DB locked/corrupt | Integrity check + backup~~-and-recreate~~ in Tools ▸ Database maintenance *(corrected 2026-10-04: there is no recreate action)* |
|
||||
|
||||
## Data directory
|
||||
|
||||
@@ -127,9 +133,9 @@ ledger.db SQLite (WAL)
|
||||
rules\detection-rules.json engine/platform/feature + anticheat blocklist
|
||||
logs\ui-*.log, agent-*.log, overlay-<pid>-*.log (native log flushed at session end, never mid-frame)
|
||||
crashdumps\*.dmp
|
||||
breadcrumbs\<pid>.json pre-injection breadcrumb (19_SAFETY §Crash safety)
|
||||
breadcrumbs\<pid>.json (corrected 2026-10-04: never created — the breadcrumb is the .partial file's header and notes)
|
||||
tmp\<sessionGuid>.partial crash-safety flush of raw buffers, every 60 s (04_CAPTURE §Ring draining)
|
||||
covers\*.jpg
|
||||
covers\*.jpg (corrected 2026-10-04: never created — nothing writes games.cover_path)
|
||||
```
|
||||
|
||||
## Key design decisions (ADR)
|
||||
|
||||
+3
-3
@@ -30,7 +30,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-3.4 Track the process tree; capture the descendant that actually presents.
|
||||
- FR-3.5 Per-frame records for the whole session; telemetry at 1 Hz (configurable 0.5–2 s).
|
||||
- FR-3.6 Session ends on process-tree exit, safety unhook, or user stop. Sessions under the minimum length (default 30 s) are discarded.
|
||||
- FR-3.7 Crash detection: nonzero exit code or matching Application Error 1000 / WER 1001 events → `exit_status = crashed`.
|
||||
- FR-3.7 Crash detection: ~~nonzero exit code~~ an exception's exit code *(corrected 2026-10-04: since beta.8, `ExitStatusMapper.IsExceptionCode` — End task's exit code 1 is `normal`, the code kept in `capture_notes`; `04_CAPTURE` §Crash & exit classification)* or matching Application Error 1000 / WER 1001 events → `exit_status = crashed`.
|
||||
- FR-3.8 Post-session toast with summary + "View".
|
||||
- FR-3.9 Pause/resume capture globally from tray.
|
||||
|
||||
@@ -64,7 +64,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- 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-7.3 Rules ship as `detection-rules.json`, updatable independently of releases; **anticheat-block updates apply regardless of the user's rules auto-update preference.** *(Unmet — corrected 2026-10-04: there is no rules feed and no auto-update preference. Rules change only with a release: `RulesSeeder` installs them, Tools ▸ Update detection rules re-seeds them — `20_OPEN_QUESTIONS` §S20 feed half.)*
|
||||
|
||||
### FR-8 Tri-state flags
|
||||
- FR-8.1 `Yes / No / N/A` for Ray Tracing, Path Tracing, Ray Reconstruction, per session, with source (`measured | manual | inherited`).
|
||||
@@ -81,7 +81,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
> **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. **beta.11 (owner request 2026-10-03: no row without a control):** Delete all sessions (FR-1.7, a *Data* section); the elevation state is a line of the admin mode's own row, not a row of its own; the hook-enabled list shows only while a game has hooking on; the language row carries no separate note.
|
||||
Language (en/vi/ja), theme, start with Windows, minimize to tray, background capture, **global hooking kill switch**, min session length, telemetry interval, retention, Agent elevation (optional — explains what it unlocks), Vulkan layer registration state, update channel, ~~online metadata opt-in,~~ reopen legal documents *(corrected 2026-10-04: the opt-in has had no row since 2026-09-16 because no store request exists, and the background-capture switch — read by nothing — is gone since beta.12; `06_DATA_MODEL` §Settings registry)*. **beta.11 (owner request 2026-10-03: no row without a control):** Delete all sessions (FR-1.7, a *Data* section); the elevation state is a line of the admin mode's own row, not a row of its own; the hook-enabled list shows only while a game has hooking on; the language row carries no separate note.
|
||||
|
||||
### FR-11 Legal Gate
|
||||
First run blocks until the user accepts ~~EULA, GPLv3 notice, Disclaimer, Privacy Policy~~ the EULA, the Disclaimer and the Privacy Policy; **the GPLv3 is shown beside them for information and needs no acceptance** (GPLv3 §9 — "You are not required to accept this License in order to receive or run a copy of the Program"; changed beta.12, owner decision D45, `08_UI` §First-run flow). Re-shown when a document version increments. The injection risk is stated in the Disclaimer *and* repeated at per-game consent (FR-2.1) — once is not enough for something that can cost an account.
|
||||
|
||||
+14
-6
@@ -1,6 +1,6 @@
|
||||
# 03 — Metrics
|
||||
|
||||
**Single source of truth** for every number FrameLedger displays. ~~Implement in `FrameLedger.Domain.Metrics` with golden tests (`14_TESTING`).~~ **Implemented in `FrameLedger.Domain.Metrics` since 2026-09-09 (P2 PR-A), with the goldens `14_TESTING` names:** `FrameTimeSeries` (frame times from QPC, gaps excluded), `Percentile` (linear), `FrameStatistics` (median / lows / min / max / σ with the sufficiency guards), `RollingMedian` + `StutterDetector`, `FgWindow` + `FgRefusal` (the factor and every refusal, as facts — the English lives with the report), `UpscaleExtent`, `SegmentBuilder`, `RtVerdict` / `HdrVerdict` (the tri-states), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates`. They consume `FrameSample` and `WriterFacts` — Domain's own types, since Domain references nothing — and `Application.Metrics.FrameSampleMapper` is the one place a shared-memory record becomes one; the Domain enums are pinned to `FrameLedger.Shared`'s in both directions by `MetricEnumMirrorTests`. The frame-generation LADDER (rung 0 / 1 / 3 / 4 as a verdict, and the withheld `none`) is not yet a Domain type: it is still the capture host's prose in `MeasuredFacts`, and lands with the recorder that stores `fg_mode` (PR-D).
|
||||
**Single source of truth** for every number FrameLedger displays. ~~Implement in `FrameLedger.Domain.Metrics` with golden tests (`14_TESTING`).~~ **Implemented in `FrameLedger.Domain.Metrics` since 2026-09-09 (P2 PR-A), with the goldens `14_TESTING` names:** `FrameTimeSeries` (frame times from QPC, gaps excluded), `Percentile` (linear), `FrameStatistics` (median / lows / min / max / σ with the sufficiency guards), `RollingMedian` + `StutterDetector`, `FgWindow` + `FgRefusal` (the factor and every refusal, as facts — the English lives with the report), `UpscaleExtent`, `SegmentBuilder`, `RtVerdict` / `HdrVerdict` (the tri-states), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates`. They consume `FrameSample` and `WriterFacts` — Domain's own types, since Domain references nothing — and `Application.Metrics.FrameSampleMapper` is the one place a shared-memory record becomes one; the Domain enums are pinned to `FrameLedger.Shared`'s in both directions by `MetricEnumMirrorTests`. The frame-generation LADDER (rung 0 / 1 / 3 / 4 as a verdict, and the withheld `none`) ~~is not yet a Domain type: it is still the capture host's prose in `MeasuredFacts`, and lands with the recorder that stores `fg_mode` (PR-D).~~ *(Corrected 2026-10-04: it landed with PR-D on 2026-09-10 as `Application.Recording.FgLadder` — in Application, not Domain. The session row (`SessionAggregator`), the live card (`SessionProgressCalculator`) and the capture host's report all read it; `MeasuredFacts` keeps only the host's strings.)*
|
||||
|
||||
Every metric declares which **capture tier** it requires (`01_ARCHITECTURE` §Capture tiers). A Tier-2 session simply has `N/A` where Tier-1 data is missing — never a silently degraded estimate presented as fact.
|
||||
|
||||
@@ -428,8 +428,13 @@ F_app = Σ fgEvaluations (APPLICATION frames, counted at the
|
||||
> dividing them by presents dilutes each by the frame-generation factor — at ×4 a title that
|
||||
> path-traces every application frame reports 25%. Whoever writes the RT hooks must choose a
|
||||
> denominator and state it here.
|
||||
>
|
||||
> *(Settled 2026-08-20 with the RT hooks — §RT/PT/RR, "The denominator": `rt_frame_pct` is a share of presents
|
||||
> and says so, and the tri-state is unaffected. Marked here 2026-10-04.)*
|
||||
|
||||
`fgEvaluations` is recorded per present by the NGX/Streamline/FFX/XeSS FG hooks
|
||||
`fgEvaluations` is recorded per present by ~~the NGX/Streamline/FFX/XeSS FG hooks~~ the `slGetNewFrameToken`
|
||||
detour; where Streamline never issued a token, by the FidelityFX dispatches — new PREPARE `frameID`s, else UPSCALE
|
||||
dispatches, the FSR 3.0 host's included *(corrected 2026-10-04: NGX and XeSS have no hook)*
|
||||
(`17_HOOK_ENGINE` §Upscaling / frame generation). `fg_factor = F_disp / F_app`.
|
||||
|
||||
> **`fgEvaluations` counts EVALUATIONS, not generated frames — owner ruling, 2026-08-14 —
|
||||
@@ -512,7 +517,7 @@ carries the three shapes.
|
||||
|
||||
From the upscaler hooks we get, per frame:
|
||||
|
||||
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`) — from the API that was called, not from a DLL sitting on disk.
|
||||
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`; **`fsr`** since 2026-09-04 — FSR through the SDK 2.x upscaler DLL, version not named) — from the API that was called, not from a DLL sitting on disk. *(Corrected 2026-10-04: `fsr` was missing here; `fsr4` is reserved and no writer produces it.)*
|
||||
|
||||
> **`dlss_rr` is NOT a value of this field, and this line listed it until 2026-08-06.** Layout
|
||||
> v3 retired it and **reserved** the slot rather than reusing it, because it made Ray
|
||||
@@ -775,7 +780,7 @@ allocations. So dedicated is defined as Task Manager's column and is **never com
|
||||
`FlFrameRecord.vramUsedMb` stay reserved for that in-process figure.
|
||||
|
||||
**Aggregates** (schema 0018): dedicated avg / median / max, shared max, private working set avg / median / max, working
|
||||
set max, commit max, the process count, the sources (`counters,ex2,held,opened`), and every series' n / mean / median /
|
||||
set max, commit max, the process count, the sources (`counters,ex2,ex,held,opened`), and every series' n / mean / median /
|
||||
min / max in `sensor_stats_json` (§Sensor aggregates). MiB stored; shown in GB as Task Manager does (1 GB = 1024 MiB).
|
||||
|
||||
> **The paragraph below is the design that was never built, kept as it stood** (struck 2026-10-03: the Overlay never
|
||||
@@ -793,7 +798,10 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max` — and since bet
|
||||
series. Sensor timeline aligned to the frame timeline via the shared QPC epoch captured at session start. Fields with no
|
||||
data are `N/A`, never 0.
|
||||
|
||||
## Accuracy budget (shown in Help → About metrics)
|
||||
## Accuracy budget ~~(shown in Help → About metrics)~~
|
||||
|
||||
*(Corrected 2026-10-04: no such page exists. Users read these limits in `LIMITATIONS.md` (Help ▸ Limitations) and in
|
||||
`legal/ACCURACY.md`, which it links.)*
|
||||
|
||||
| Quantity | Tier 1 | Tier 2 |
|
||||
|---|---|---|
|
||||
@@ -828,7 +836,7 @@ Per-column sources, and what a *Tier-2* export does instead:
|
||||
| Column | Tier-1 source | Tier 2 |
|
||||
|---|---|---|
|
||||
| `frame_index`, `qpc_ms`, `frametime_ms` | `frametimes` blob + session `qpcEpoch` | ~~from CSV~~ — no Tier-2 CSV exists; a Tier-2 session exports no per-frame rows at all |
|
||||
| `native_or_generated` | `frame_flags` generated bit — set where `fgEvaluations == 0`, i.e. the presents that carried **no** application-frame evaluation. Inverted from the pre-2026-08-14 reading, and accurate to one frame per the note in §Frame Generation | `FrameType` (2.x) |
|
||||
| `native_or_generated` | `frame_flags` generated bit — set where `fgEvaluations == 0`, i.e. the presents that carried **no** application-frame evaluation. Inverted from the pre-2026-08-14 reading, and accurate to one frame per the note in §Frame Generation | ~~`FrameType` (2.x)~~ — no Tier-2 CSV *(corrected 2026-10-04)* |
|
||||
| `render_w/h`, `output_w/h` | `render_res` blob — **two `uint16` pairs per frame**, not one; `ResizeBuffers` is hooked precisely because output resolution changes mid-session | `N/A` |
|
||||
| `upscaler`, `upscaler_quality`, `fg_mode` | segment table, joined by frame index | `N/A` |
|
||||
| `rt_flags` | `rt_flags` blob, **one byte per frame** preserving all three bits (`asBuildObserved`, `dispatchObserved`, `psoCreatedEver`) — collapsing them to a single "rt-active" bit loses the inline-RayQuery distinction this project exists to measure. The third was `rtPsoAlive` until layout v3 renamed it: creation is observed at `CreateStateObject` and destruction is COM `Release`, which is not in the hook inventory and must not be added, so the bit latches and could only ever mean "created ever" | `N/A` |
|
||||
|
||||
+7
-6
@@ -22,6 +22,7 @@ public interface IFrameSource : IAsyncDisposable
|
||||
> {
|
||||
> FlWriterState WriterState { get; } FlShmHandshake Handshake { get; }
|
||||
> long TotalDropped { get; } long TotalGaps { get; }
|
||||
> FlDisplayState? DisplayState { get; } // region 4, beta.10 (added to this sketch 2026-10-04)
|
||||
> DrainResult Drain(Span<FlFrameRecord> into, IList<ulong> gapIndices);
|
||||
> void PublishGuardResult(uint completedEvaluations, bool unhookRequested);
|
||||
> void SetPaused(bool paused); void RequestLogFlush();
|
||||
@@ -131,7 +132,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~~ **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.**
|
||||
- Watchlist match on normalized full path (~~`GetFinalPathNameByHandle`~~ `File.ResolveLinkTarget` *(corrected 2026-10-04 — `ExecutableIdentity` says why)* — junctions/symlinks), ~~filename fallback with a stale-path warning badge~~ **and a file name alone never starts a session (2026-09-23, HANDOFF D25): it can only be the entry's own executable on a drive that changed its letter (the relocator's rule), or it is not in the library.**
|
||||
- Process tree assembled from ppid chains; the **capture target** is the descendant that actually presents. In launch mode we know it; in attach mode we wait for the first ring handshake. ~~or (Tier 2) elect the PID with the most presents in the first 10 s~~ — there is no Tier-2 present stream to elect from. Re-elect if the presenting PID dies while the tree lives (level-transition relaunches).
|
||||
|
||||
> **Built 2026-09-10 (P2 PR-F), in `Application.Watch` with one adapter.** `ToolhelpProcessSnapshotSource`
|
||||
@@ -179,7 +180,7 @@ which makes the notification more important than it was, not less.
|
||||
|
||||
## Launch mode vs attach mode
|
||||
|
||||
**Launch mode (preferred).** User starts the game from FrameLedger (or FrameLedger is set as the launch wrapper): `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
|
||||
**Launch mode (preferred).** User starts the game from FrameLedger ~~(or FrameLedger is set as the launch wrapper)~~ *(corrected 2026-10-04: no wrapper exists, and no App button sends `LaunchGame` yet — the pipe command has no caller; launch mode runs from the Agent's developer verb `--console launch --exe`)*: `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
|
||||
|
||||
> **An elevated Agent starts the game as a standard user (beta.10, the admin mode, D34).** `ProcessLauncher` checks its
|
||||
> own token: elevated, it starts the game with the desktop shell's token (`Infrastructure.Startup.UnelevatedProcess` —
|
||||
@@ -225,13 +226,13 @@ which makes the notification more important than it was, not less.
|
||||
|
||||
**Attach mode.** Game launched from Steam/GOG/Epic normally; watcher sees it, guard runs, inject. Feature hooks install late, so early-init facts may be missed; the Overlay compensates by re-reading state on the first `EvaluateFeature` call it does observe, and the session is flagged `late_attach = true` so the UI can note that startup-time settings may be incomplete.
|
||||
|
||||
Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).
|
||||
~~Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).~~ *(Corrected 2026-10-04: not built — there is no wrapper entry point and no UI text; a game started from Steam is recorded in attach mode. The parenthesis still holds: never modify a user's Steam config for them.)*
|
||||
|
||||
## The guard
|
||||
|
||||
The guard is **native** (`20_OPEN_QUESTIONS` §S13(a)) and the Agent reaches it through `IAntiCheatGuard`, a **thin P/Invoke facade over the single implementation** — never a second one. Two blocklist matchers that can disagree is a fail-open by construction: the day they diverge, one is wrong and nothing says which. Nothing managed parses rules or matches a blocklist, and a test asserts it (§S15 item 1).
|
||||
|
||||
The facade exposes exactly two operations, and neither hands out a clearance:
|
||||
The facade exposes ~~exactly two operations~~ four *(corrected 2026-10-04: `GuardedInjectWhenReadyAsync`, launch mode's waiting entry, and `PreScanGameAsync`, the advisory checks 3–4 behind FR-2.2 and the library pre-scan, joined the two below; since D33 each takes `toleratedFamily`, a family name the guard resolves itself)*, and none hands out a clearance:
|
||||
|
||||
- `GuardedInjectAsync(pid, payload)` — runs every pre-injection check and, only on a pass, injects. There is no overload that skips the checks and no way to supply evidence; the guard collects its own, so a caller can ask but only the guard answers (§S13(b)).
|
||||
- `EvaluateAsync(pid)` — the same checks with no injection, for the 30 s in-session re-scan. It cannot be used to pre-authorise anything: it takes no payload and returns no token, so acting on a pass means calling `GuardedInjectAsync`, which re-collects.
|
||||
@@ -316,7 +317,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
|
||||
> published at attach are counted separately as `RecordsBeforeAttach`; that is not
|
||||
> a stall and must not raise this warning.
|
||||
- **A torn record is a gap, not a skipped frame.** Silently dropping it merges two frame times into one double-length interval, i.e. fabricates a stutter. Record an explicit gap at that index; `03_METRICS` excludes gap-adjacent intervals from frame-time statistics.
|
||||
- Records go into an in-memory buffer (`ArrayPool<FlFrameRecord>` segments). Every 60 s, a crash-safety flush writes raw buffers to `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`.
|
||||
- Records go into an in-memory buffer (~~`ArrayPool<FlFrameRecord>` segments~~ a `List<FlFrameRecord>` — corrected 2026-10-04). Every 60 s, a crash-safety flush writes raw buffers to `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`.
|
||||
|
||||
## Threading model
|
||||
|
||||
@@ -349,7 +350,7 @@ the pipe's tasks touches the ring or the recorder, and the session loop never wa
|
||||
|
||||
## Telemetry poller
|
||||
|
||||
1 Hz on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) + optional CPU sample when the Agent is elevated and PawnIO is present. Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
|
||||
1 Hz (the session's `telemetry.interval_ms`, 500–2000 ms) on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) ~~+ optional CPU sample when the Agent is elevated and PawnIO is present~~ + *(corrected 2026-10-04)* the machine's reading on the same tick — CPU load and memory in use without elevation, CPU temperature only when elevated with PawnIO — and the game process's memory (beta.12, D43). Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
|
||||
|
||||
## Session recorder — state machine
|
||||
|
||||
|
||||
+14
-7
@@ -36,6 +36,10 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
> **2026-09-27 (beta.10):** the first row's *swap effect* has a writer since schema 0016 — region 4's `GetDesc`, stored
|
||||
> in `sessions.swap_effect` as a name (`flip_discard`, …) — and the display-mode row is new. **Present mode has none**,
|
||||
> and the block above did not list it: `sessions.present_mode` is null on every row, and the pages say N/A.
|
||||
>
|
||||
> **2026-10-04 (beta.12, D43):** the per-process VRAM row's *usage* is measured — not by `QueryVideoMemoryInfo` but
|
||||
> from outside the game, in both tiers, with the game's RAM beside it (`game_vram_*`, `game_ram_*`; `03_METRICS`
|
||||
> §Game process memory). The in-game figure, its budget and `vram_proc_*` stay unbuilt.
|
||||
|
||||
> **"present-count delta" is removed from the FG row, and it was not merely unreliable —
|
||||
> it was structurally zero.** `03_METRICS` §Frame Generation retired that rung on
|
||||
@@ -47,11 +51,11 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
> stale-by-not-being-touched failure this project keeps recording; `06_DATA_MODEL`'s
|
||||
> `fg_source` enum carried the same value and is corrected in the same pass.
|
||||
|
||||
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement. **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.
|
||||
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement. **The ~~one exception~~ exceptions** *(corrected 2026-10-04)* are how its window was shown (the display-mode row, beta.10) and the game process's memory (beta.12), which the Agent reads from outside the game in either tier.
|
||||
|
||||
## Static hints — rules engine
|
||||
|
||||
Rules are **data, not code**: `rules/detection-rules.json`, bundled and updatable from the repo (raw GitHub URL, ETag-cached; manual "Update detection rules" in Tools + weekly auto-check). Schema:
|
||||
Rules are **data, not code**: `rules/detection-rules.json`, bundled ~~and updatable from the repo (raw GitHub URL, ETag-cached; manual "Update detection rules" in Tools + weekly auto-check)~~ *(corrected 2026-10-04: nothing fetches. The rules ship with the build and `RulesSeeder` installs them in `%LOCALAPPDATA%\FrameLedger\rules\`; Tools ▸ Update detection rules re-seeds from the copy beside the binary and wakes the detection and anti-cheat sweeps. A rules change reaches users with a release — `20_OPEN_QUESTIONS` §S20 feed half)*. Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -64,7 +68,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.
|
||||
The `anticheat` block is the same file that feeds the hard guard in `19_SAFETY` — shipping it as updatable data is what lets a newly-protected game be blocked without waiting for an app release. ~~**Rules updates that touch the `anticheat` block are treated as security updates:** applied on next check regardless of the user's auto-update preference for other rules.~~ *(Corrected 2026-10-04: there is no feed and no auto-update preference, so today a newly-protected game waits for a release; the sentence is what a feed must do once built, §S20.)*
|
||||
|
||||
Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`, `sibling_glob`, **`path_contains`**, `pe_company_contains`, `pe_product_contains`, `strings_contains` (bounded 8 MB scan), `manifest_field`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`, 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).
|
||||
|
||||
@@ -88,7 +92,10 @@ Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`,
|
||||
|
||||
### Trust and staleness of the rules feed
|
||||
|
||||
`20_OPEN_QUESTIONS` §S4. The file is fetched over HTTPS from a raw GitHub URL.
|
||||
> **Specified, not built (corrected 2026-10-04):** there is no feed (§S20 feed half, §S4); these rules apply once one
|
||||
> exists. Today the seeder validates the packaged copy with the guard's parser and keeps `detection-rules.json.bak`.
|
||||
|
||||
`20_OPEN_QUESTIONS` §S4. The file ~~is~~ would be fetched over HTTPS from a raw GitHub URL.
|
||||
Three rules, because a gate whose data can silently go stale is a gate with an
|
||||
expiry date nobody sees:
|
||||
|
||||
@@ -144,7 +151,7 @@ Recorded as a residual risk, not as a solved problem.
|
||||
| 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 |
|
||||
| Ren'Py | `renpy/` dir **or** `*.rpa` | ~~`renpy/__init__` strings / `log.txt` first line~~ `N/A` *(corrected 2026-10-04: no extractor — `strings_regex` reads only the executable)* |
|
||||
| CryEngine | `CrySystem.dll` | FileVersion |
|
||||
| Source | `gameinfo.txt` + `bin/engine.dll` | `N/A` |
|
||||
| Unknown | fallback | — |
|
||||
@@ -245,7 +252,7 @@ wrote, where detection wrote it.
|
||||
|---|---|---|
|
||||
| Steam | `steam_api64.dll`/`steam_api.dll` sibling, or path contains `steamapps\common` | nearest `steamapps/appmanifest_<id>.acf` (walk up): `appid`, `name`, `buildid` → version |
|
||||
| GOG | `goggame-<id>.info` sibling, or `Galaxy64.dll` | `.info` JSON: `gameId`, `name`, `version` |
|
||||
| Epic | `EOSSDK-Win64-Shipping.dll`, or path under an Epic install | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
|
||||
| Epic | `EOSSDK-Win64-Shipping.dll`~~, or path under an Epic install~~ *(corrected 2026-10-04: the rule has no path signal)* | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
|
||||
| itch.io | `.itch\receipt.json.gz` | **`%APPDATA%\itch\db\butler.db`** (`install_locations` + `caves`, butler's `verdict` names the executable) since 2026-09-16, then the receipt JSON: title, id |
|
||||
| None/Manual | fallback | PE VersionInfo |
|
||||
|
||||
@@ -349,7 +356,7 @@ Three things this section previously implied that are not true, and are worth st
|
||||
|
||||
- **The UI answer is advisory.** It decides whether the toggle is *offered*; it does not gate injection. The same scan runs a second time inside the guard's chokepoint against a directory derived from the target's own pid, so "prevention beats interception" is a convenience, not the enforcement.
|
||||
- **A hit disables the toggle; "could not scan" must not.** The scan is tri-state. `Reason::kPreScanFailed` — directory absent, unlistable, past a bound, or behind a reparse point — is *neither* a hit nor a pass. It must surface as "could not verify", distinct from "anti-cheat found": disabling the toggle on it would be a false refusal with no appeal, and clearing it would be a fail-open.
|
||||
- **The token list is thin.** `directories` and `files` carry three tokens today. Widening needs verified names; a guessed token fails closed by never firing, which is a silent hole (`19_SAFETY` §Blocklist seed).
|
||||
- **The token list is thin.** `directories` and `files` ~~carry three tokens today~~ *(corrected 2026-10-04: rules 2026.10.1 carry 9 directory families (12 names) and 18 file families (55 names), and since 2026-09-25 any `*.sys` in the install tree is a finding by code, not data)*. Widening needs verified names; a guessed token fails closed by never firing, which is a silent hole (`19_SAFETY` §Blocklist seed).
|
||||
|
||||
## Caching & privacy constraints
|
||||
|
||||
|
||||
+38
-23
@@ -2,7 +2,7 @@
|
||||
|
||||
`%LOCALAPPDATA%\FrameLedger\ledger.db`. Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=5000`. `Microsoft.Data.Sqlite` + Dapper; all writes in explicit transactions.
|
||||
|
||||
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It is the one Agent write that deletes a `games` row; it never touches a consent column. **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself. **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. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself *(for Delete all sessions; FR-1.4's removal is the App's own cascade, above — corrected 2026-10-04)*. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; ~~never a `hook_*` column~~ **and two downgrades** *(corrected 2026-10-04)*: *Change executable* (2026-09-21, `GameLibrary.ChangeExecutableAsync`) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and *Remove game ▸ Delete sessions too* (FR-1.4) deletes the `games` row, cascading to its sessions, segments, blobs and annotations), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
|
||||
|
||||
## Schema (v2 — hook architecture)
|
||||
|
||||
@@ -123,15 +123,18 @@ CREATE TABLE games (
|
||||
> human's typed value as auto-detected is a lie they cannot see through; failing to
|
||||
> badge a detected value merely costs a badge on something they can still edit. The
|
||||
> rule it exists to support — *detection never overwrites a `user` field* — is in
|
||||
> `05_DETECTION` §Caching and is enforced by `StaticDetectionResult.ShouldWrite`,
|
||||
> which is tested even though nothing persists yet.
|
||||
> `05_DETECTION` §Caching and is enforced by ~~`StaticDetectionResult.ShouldWrite`,
|
||||
> which is tested even though nothing persists yet~~ `SqliteGameRepository.FieldProvenance.Resolve`
|
||||
> *(corrected 2026-10-04: applied per field since P4 PR-1, and it also fills an empty field that has no entry;
|
||||
> `ShouldWrite` keeps its tests but has no production caller)*.
|
||||
>
|
||||
> ~~No migration is written here. There is no SQLite layer at all, and §Migrations
|
||||
> forbids editing an applied script — so guessing the shape into `0001_init.sql`
|
||||
> before its consumers exist maximises the chance of baking in a wrong guess that
|
||||
> can only be appended to.~~ **Written 2026-09-09 (P2 PR-B), with its first consumer:** the
|
||||
> column exists in `0001_init.sql`; the writer (the detection cache, P4) and the reader (the
|
||||
> library card, P3) are still unbuilt, so it is decided, created, and empty.
|
||||
> column exists in `0001_init.sql`; ~~the writer (the detection cache, P4) and the reader (the
|
||||
> library card, P3) are still unbuilt, so it is decided, created, and empty~~ *(corrected 2026-10-04: written since
|
||||
> 2026-09-14 by the detection sweep, the store import and Edit…; read for the Edit dialog's badges and the game page)*.
|
||||
|
||||
> **The three hook-state columns have a consumer before they have a table, and two
|
||||
> fields it needs are not here.** Added 2026-08-06 with `IGameConsentStore`, whose
|
||||
@@ -142,7 +145,8 @@ CREATE TABLE games (
|
||||
> anything else — so a record could carry a consent time that nothing had ever
|
||||
> disclosed anything for. `ConsentProvenance`'s zero value means *no disclosure was
|
||||
> shown*, and it deliberately has **no FR-2.1 member**: that dialog needs reviewed
|
||||
> `Safety_*` wording in en/vi/ja and no `.resx` exists anywhere in this tree.
|
||||
> `Safety_*` wording in en/vi/ja and ~~no `.resx` exists anywhere in this tree~~ *(superseded: the dialog shipped in
|
||||
> P3 PR-4 as `ConsentDialog`, below — corrected 2026-10-04)*.
|
||||
> - **A disclosure/wording version.** `legal_acceptance` carries `(doc, version,
|
||||
> accepted_at)` while this column carries a timestamp alone, so nothing could mark
|
||||
> existing per-game consent stale when the reviewed wording changes. It is carried
|
||||
@@ -164,7 +168,10 @@ CREATE TABLE games (
|
||||
> shipped producer, still not FR-2.1, stamped by the Agent's clock; the store writes the NAME the
|
||||
> acknowledgement carries and refuses `NotRecorded`.
|
||||
>
|
||||
> **Still unanswered, and it is an owner decision rather than a coding one:** who
|
||||
> ~~**Still unanswered, and it is an owner decision rather than a coding one:**~~ **Answered by the owner on
|
||||
> 2026-09-22: nothing clears it** *(corrected 2026-10-04)*. A clean re-scan, *Change executable*, a re-import and a twin
|
||||
> merge all leave it, and the toggle stays disabled (`19_SAFETY` §What a finding does to the game); D33's exception
|
||||
> sits on top of the block and never clears it. The question as it stood: who
|
||||
> clears `hook_blocked_reason` when a re-scan comes back clean. `19_SAFETY` §A game
|
||||
> already enabled can become blocked later makes a non-null value mean "toggle
|
||||
> disabled" and makes re-enabling "a user action" — but if nothing clears the column
|
||||
@@ -217,7 +224,7 @@ CREATE TABLE sessions (
|
||||
sync_interval_mode TEXT, -- observed vsync behavior
|
||||
|
||||
-- upscaling / FG (measured at tier 1)
|
||||
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown
|
||||
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown, and fsr since 2026-09-04 (FL_UPSCALER_FSR_UNVERSIONED; added 2026-10-04)
|
||||
upscaler_quality TEXT,
|
||||
upscaler_sharpness INTEGER, -- percent; NULL when the API reports none
|
||||
render_w INTEGER, render_h INTEGER, -- dominant segment
|
||||
@@ -339,7 +346,7 @@ CREATE TABLE frame_blobs (
|
||||
-- stored only when either varies
|
||||
dispatch_rays BLOB, -- uint32[] : ray volume per frame, tier 1 only
|
||||
pso_created BLOB, -- uint16[] : compile COUNT per frame, not a flag
|
||||
vram_proc BLOB, -- uint32[] MB per frame; held 1 Hz sample, see 03_METRICS
|
||||
vram_proc BLOB, -- uint32[] MB per frame; never written (corrected 2026-10-04: the Overlay never produced vramUsedMb)
|
||||
latency_us BLOB, -- uint32[], tier 1 + Reflex only
|
||||
first_present_ms REAL -- schema 0013 (beta.8): the dominant stream's first present, ms from qpc_epoch —
|
||||
-- the sensors' zero (t_ms) against the frames'. NULL before; the charts then
|
||||
@@ -409,7 +416,7 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
|
||||
| `ui.hide_anticheat_hooking` | bool | `1` | | UI (beta.8, 2026-09-25): the game page of an entry the guard found anti-cheat in shows the finding in place of its Hooking card (`08_UI` §Game detail) |
|
||||
| `ui.fps_decimals` | bool | `0` | | UI (beta.8, 2026-09-25): every FPS figure with two decimals ("62.40") instead of a whole number |
|
||||
| `ui.library_view` | choice `grid`\|`list` | `grid` | | UI (beta.11, 2026-10-03): the Games library as a grid of cards that fills the width, or as a list; written by the page's own switch, no Settings row (`08_UI` §Games) |
|
||||
| `capture.background` | bool | `1` | | Agent |
|
||||
| `capture.background` | bool | `1` | | ~~Agent~~ nobody *(corrected 2026-10-04: no Agent code ever read it, so the watcher recorded every tracked game whatever it said; beta.12 removed its switch from Settings and reserved the key — `SettingsRegistry.CaptureBackground`)* |
|
||||
| `hooking.kill_switch` | bool | `0` | | Agent (FR-2.4, since P2 PR-F) |
|
||||
| `hooking.usermode_ac_exceptions` | bool | `0` | | Agent, at every session start and command (FR-2.8, D33, 2026-09-26): off suspends every user-mode exception without deleting any; on, the user still grants each eligible game |
|
||||
| `capture.run_elevated` | bool | `0` | | The App when it starts the Agent, and an Agent the logon task started — both BEFORE the Agent exists, through `Infrastructure.Startup.RunElevatedSetting` (one row, `PRAGMA query_only`, no version gate, anything but `1` is off) (D34, beta.10): on, Windows is asked for administrator rights at every Agent start (`01_ARCHITECTURE` ADR-9) |
|
||||
@@ -430,7 +437,7 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
|
||||
|
||||
## Blob encoding
|
||||
|
||||
`float32`/`uint16`/`uint32` little-endian arrays through `DeflateStream` (Optimal). One hour at 100 fps ≈ 360k frames ≈ 1.4 MB raw frametimes ≈ **≤ 0.7 MB stored**; flags compress far better; render-res only stored when it varies. Decode helpers in `Infrastructure.Blobs` with round-trip test
|
||||
`float32`/`uint16`/`uint32` little-endian arrays through `DeflateStream` (Optimal). One hour at 100 fps ≈ 360k frames ≈ 1.4 MB raw frametimes ≈ **≤ 0.7 MB stored**; flags compress far better; render-res only stored when it varies. Decode helpers in `Infrastructure.Blobs` with round-trip tests (NaN forbidden — assert).
|
||||
|
||||
> **Two rules the finalizer applies (2026-09-10, P2 PR-D).** `frametimes[i]` is the interval from the previous
|
||||
> record ON THE SAME SWAPCHAIN; the first record of a stream, and any record after a torn slot or an
|
||||
@@ -440,7 +447,7 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
|
||||
> 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).
|
||||
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.
|
||||
|
||||
## The `.partial` file
|
||||
|
||||
@@ -458,10 +465,11 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
|
||||
> | 1 `Header` | UTF-8 JSON: format version, `session_guid`, `started_at`, `qpc_epoch`/`qpc_frequency`, `game_id`, `snapshot_id`, exe path, pid, tier, mode, Overlay build id, telemetry descriptor, launch wait | on create — the breadcrumb `19_SAFETY` §Crash safety asks for before injection |
|
||||
> | 2 `Records` | `i64` first ordinal, then N raw `FlFrameRecord` (64 B each); a chunk that does not continue the sequence is refused | each flush |
|
||||
> | 3 `Gaps` | N × `i32` gap-before record indices | each flush |
|
||||
> | 4 `Sensors` | N × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null | each flush |
|
||||
> | 4 `Sensors` | N × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null | ~~each flush~~ read only since beta.12, so a beta.11 file still recovers *(corrected 2026-10-04)* |
|
||||
> | 5 `Tick` | drain/foreground ticks, dropped, gaps, guard ticks, wall clock, the raw `FlWriterState`; the last one wins | each flush |
|
||||
> | 6 `Note` | wall clock + UTF-8 text: a state transition | each transition |
|
||||
> | 7 `Touches` | N × `i64` QPC at which the host touched the target | each flush |
|
||||
> | 8 `SensorsWide` | the same samples under a 32-bit presence mask that carries the game process's memory (D43) | each flush, since beta.12 *(row added 2026-10-04)* |
|
||||
>
|
||||
> Recovery (`PartialRecovery`): a file whose guid is already a row is deleted (the finalize had landed);
|
||||
> one under the minimum session length is discarded; one with no readable header is dropped; the rest
|
||||
@@ -505,11 +513,6 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> columns on `session_annotations` and `games.removed_at`. `LedgerDatabaseTests` asserts one
|
||||
> `schema_migrations` row per script, so `LatestVersion` is 2.
|
||||
|
||||
> **`0002_annotation_overrides_and_removal.sql` (P3 PR-3, 2026-09-13) — the first append**, and the first
|
||||
> time the runner ran two scripts on a real file: `ALTER TABLE ADD COLUMN` only — the three override
|
||||
> columns on `session_annotations` and `games.removed_at`. `LedgerDatabaseTests` asserts one
|
||||
> `schema_migrations` row per script, so `LatestVersion` is 2.
|
||||
|
||||
> **`0003_fg_refusal.sql` (2026-09-14) — `sessions.fg_refusal`.** The owner's ledger held two hooked rows with
|
||||
> `fg_mode = 'dlssg'`, `fg_source = 'api'` and `fg_factor` NULL — the identity stood, the count refused — and
|
||||
> nothing recorded which refusal; every FG surface said N/A beside a detection that had succeeded. One
|
||||
@@ -543,6 +546,11 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The
|
||||
> data dropped is the override acknowledgements themselves, which is the decision. `LatestVersion` is 8.
|
||||
|
||||
> **`0009_record_sessions.sql` (2026-09-23, D29) — `games.record_sessions`** *(entry added 2026-10-04; it was
|
||||
> missing)*. FR-1.6's recording switch, `NOT NULL DEFAULT 1`; the App writes it, the Agent only reads it. Its one data
|
||||
> change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools` as of the
|
||||
> script). `LatestVersion` is 9; `LedgerDatabaseTests.ScriptNineAddsTheRecordingSwitchOffForSteamToolsOnly`.
|
||||
|
||||
> **`0010_prescan_key.sql` (2026-09-25) — `games.hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` /
|
||||
> `hook_prescan_exe_mtime_ms`.** The Agent pre-scans every library entry for anti-cheat since beta.8, and again
|
||||
> whenever the rules or the executable change, so it needs what each row was last scanned against — its own key, as
|
||||
@@ -568,6 +576,11 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> `FgPreset`, `FgMode` beside its masks (additive JSON fields; older rows lack them). `LatestVersion` is 12;
|
||||
> `LedgerDatabaseTests.ScriptTwelveAddsTheDriverProfileColumn`.
|
||||
|
||||
> **`0013_first_present.sql` (beta.8, 2026-09-25) — `frame_blobs.first_present_ms`** *(entry added 2026-10-04; it was
|
||||
> missing)*. The charted stream's first present, in milliseconds from `qpc_epoch`, written by the finalizer
|
||||
> (§Blob encoding); NULL before, and such a row's sensor overlay stays off rather than drawn out of step. `LatestVersion`
|
||||
> is 13; `LedgerDatabaseTests.ScriptThirteenAddsTheFirstPresentColumn`.
|
||||
|
||||
> **`0014_usermode_ac_exception.sql` (beta.9, 2026-09-26, owner decision D33) — the user-mode anti-cheat exception.**
|
||||
> Fourteen `games.ac_exception_*` columns in three groups — the Agent's eligibility answer about a blocked row and its
|
||||
> key, the user's grant, and how the last grant ended — and `sessions.ac_exception_family`, the family a HOOKED session
|
||||
@@ -659,14 +672,16 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> insert leaves no session row behind (`SqliteSessionRepositoryTests`).
|
||||
|
||||
**`0001_init.sql` creates the schema above directly.** There is no v1 → v2
|
||||
upgrade path, because there is no released v1: nothing has shipped, so no
|
||||
FrameLedger database exists anywhere in the world. Writing and testing a
|
||||
upgrade path, because there is no released v1: ~~nothing has shipped, so no
|
||||
FrameLedger database exists anywhere in the world~~ *(corrected 2026-10-04: eleven pre-releases shipped from
|
||||
0.1.0-beta.1 on 2026-09-16, and the appended scripts carry their ledgers forward; no schema older than 0001 ever
|
||||
shipped, so there is still no v1 → v2 path)*. Writing and testing a
|
||||
migration from a schema that never existed is work with no user on the other end
|
||||
of it. The `schema_migrations` machinery still ships from day one — it is what
|
||||
makes the *next* migration safe, and `11_UPDATER` §Versioning already requires
|
||||
migrations to cover every released `MAJOR-1`. That obligation begins at the first
|
||||
release, not before it.
|
||||
migrations to cover every released `MAJOR-1`. ~~That obligation begins at the first
|
||||
release, not before it.~~ It began with 0.1.0-beta.1.
|
||||
|
||||
## Hardware change markers (FR-6.3)
|
||||
|
||||
Snapshot captured per session, hashed, deduped. Trend queries join consecutive sessions' snapshots; differing fields emit a marker `{after_session_id, field, old, new}`. GPU driver version now comes from the vendor API (`18_GPU_VENDOR_APIS`) rather than WMI, which makes it accurate enough to be worth charting.
|
||||
Snapshot captured per session, hashed, deduped. Trend queries join consecutive sessions' snapshots; differing fields emit a marker `{after_session_id, field, old, new}`. GPU driver version now comes from ~~the vendor API (`18_GPU_VENDOR_APIS`)~~ DXGI's four-part user-mode driver version (`HardwareSnapshotSource`; corrected 2026-10-04) rather than WMI, which makes it accurate enough to be worth charting.
|
||||
+9
-5
@@ -1,12 +1,14 @@
|
||||
# 07 — IPC
|
||||
|
||||
Three channels, each chosen for its constraints:
|
||||
~~Three~~ Four channels, each chosen for its constraints *(corrected 2026-10-04: §D, the tolerance mapping, arrived
|
||||
in beta.9 without a row here)*:
|
||||
|
||||
| Channel | Between | Transport | Why |
|
||||
|---|---|---|---|
|
||||
| **A. Frame ring** | Overlay DLL → Agent | Shared memory, lock-free SPSC | Hot path: no syscall allowed |
|
||||
| **B. Control block** | Agent ↔ Overlay DLL | Same shared memory, atomics | Tiny, infrequent, must work even if the game is unresponsive |
|
||||
| **C. Command pipe** | UI ↔ Agent | Named pipe, JSON | Rich, versioned, human-debuggable |
|
||||
| **D. Tolerance mapping** | Agent → Overlay DLL, once, before injection | Its own shared memory, read-only to the Overlay | Must exist before the Overlay's loader detour does (§D, D33) |
|
||||
|
||||
## A + B — shared memory (`Local\FrameLedger.Ring.<pid>`)
|
||||
|
||||
@@ -380,13 +382,15 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
|
||||
makes an additive field safe.)*
|
||||
- A request the Agent cannot answer gets `Error { code, message }` with the request's `id`: `UnknownType`,
|
||||
`Malformed` (no `id` when the envelope itself could not be read), `ProtocolMismatch`, `HandlerFaulted`. The
|
||||
connection survives all four.
|
||||
connection survives all four. *(Added 2026-10-04: `SetHookEnabled` and `SetAntiCheatException` also answer
|
||||
`Error UnknownGame` — no row has that id — and `Error ExecutableUnreadable` — nothing scanned, stamped or granted;
|
||||
the App branches on the second.)*
|
||||
|
||||
### Messages
|
||||
|
||||
| Type | Dir | Payload / notes |
|
||||
|---|---|---|
|
||||
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, 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` |
|
||||
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, exceptionDisclosureVersion /* D33, 2026-09-26: the user-mode exception's disclosure this Agent grants against */, elevationOutcome /* beta.10, D34: the admin mode's answer at this start — granted, declined, other-account, failed — or null when nobody asked */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. ~~`vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered)~~ `vulkanLayerRegistered` is the HKCU implicit-layer registration as the Agent found it at start *(corrected 2026-10-04: since P3 PR-8b; true while `VkLayerReconciler` keeps the layer registered for a hook-enabled Vulkan game, P4 PR-2)* and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
|
||||
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` — and `activeSessions[]`, one `{ sessionGuid, gameId, gameName?, pid, tier, startedAt, hold? }` per running session. **`hold` added 2026-09-23, optional:** present on a session held unhooked (Tier 2), with the same words `SessionStarted.hold` carries; a session listed at tier 2 WITHOUT a `hold` has not attached yet — it is starting, not held. The App reads this list on every (re)connect (§Client behavior) |
|
||||
| `SetWatchlist` | UI→A | `{ entries: [{ gameId?, exePath }] }` — ~~full replace~~ **ensure, never remove** (built 2026-09-13, PR-1b): each entry's path is normalised by the Agent, its row ensured with hooking OFF when new, and the ack is `WatchlistAck { games: [{ gameId, exePath, name }], unreadable: [exePath] }`; `gameId` in a request is a hint and never trusted over the path. UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary). *Since the App writes `games` rows itself under `06_DATA_MODEL` §Writer ownership (HANDOFF §P3 D15), this is the pipe's way of adding a row, not the only one; the watcher reads the table at 1 Hz either way.* |
|
||||
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable` · `RecordingOff` (2026-09-23: the entry's recording switch is off, FR-1.6 — FrameLedger does not start what it will not record). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
|
||||
@@ -402,7 +406,7 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
|
||||
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct?, gameVramDedicatedMb?, gameRamPrivateMb? }` — how long it has run and the machine's sensors (and since beta.12 the game process's own memory, read from outside it — optional, an older client ignores them). **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
|
||||
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus?, gameVramDedicatedMb?, gameRamPrivateMb? }` (the last two added 2026-10-03, beta.12, optional: the game process's dedicated GPU memory and private working set, MiB, from the newest telemetry tick; `vramProcMb` stays reserved for the in-process figure and has no producer) — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
|
||||
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
|
||||
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` 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.)* |
|
||||
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch`, `PreScanCouldNotVerify` and, since 2026-09-21 (beta.4), `TargetUnreadable` — a protected process the Agent could not open (added 2026-10-04) — `PreScanCouldNotVerify` with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
|
||||
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
|
||||
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff }` — anti-cheat appeared mid-session; prominent UI notice; `hookingTurnedOff` as on `CaptureRefused`. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
|
||||
| `HookingTurnedOff` | A→UI | `{ gameId, gameName?, reason, family?, signal? }` — **since 2026-09-25 (beta.8):** the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) found anti-cheat in a game whose hooking the user had turned on, and turned it off. Not a session event — no session is running — so the UI's notice carries no "record without measuring" action, only Dismiss (`SafetyNoticeKind.HookingOff`). A finding on a game whose hooking was already off sends nothing: its page and its library card change, nothing the user switched on did. Additive: a client that does not know the type ignores it (§Versioning). |
|
||||
@@ -454,7 +458,7 @@ message, and that message always re-scans.
|
||||
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.
|
||||
- Connect with 250 ms × 8 backoff; on failure start the Agent, retry; then show an Agent status banner with ~~Repair~~ Retry *(corrected 2026-10-04)*.
|
||||
|
||||
> **Amended 2026-09-17: never a second Agent.** A round that ends without a connection starts one only when no
|
||||
> process holds the user's data folder (`AgentInstanceLock`, probed through `IAgentLauncher.RunningAgent`) and the
|
||||
|
||||
+25
-16
@@ -27,7 +27,8 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
|
||||
- **Help:** User guide (beta.12) · Check for updates · Report a bug… · ~~Documentation~~ Online documentation · Limitations · About FrameLedger (~~App / Developer / Third-party licenses tabs~~ — built beta.12 as *This app* / *Third-party licences* / *Legal documents*, below)
|
||||
|
||||
> **Help ▸ Limitations, beta.10 (D36):** `LIMITATIONS.md` as the build embeds it (`Services.LimitationsDocument`), in a
|
||||
> read-only, scrolling WPF UI `MessageBox` with *Open on GitHub*. It is information, not one of FR-11's documents:
|
||||
> ~~read-only, scrolling WPF UI `MessageBox` with *Open on GitHub*~~ window of its own since beta.12 (`Windows/DocumentWindow`,
|
||||
> rendered — below; corrected 2026-10-04). It is information, not one of FR-11's documents:
|
||||
> nothing is accepted or recorded, and the Disclaimer points at it.
|
||||
>
|
||||
> **Help ▸ User guide, beta.12 (D44).** `guide/` — eight short English pages for players (install, record a game, read
|
||||
@@ -168,7 +169,7 @@ Reusable control `FpsReadout` (custom control styled with WPF UI theme brushes):
|
||||
|
||||
## Tri-state feature chips (RT / PT / RR)
|
||||
|
||||
`TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header.
|
||||
`TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. ~~Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override~~ *(corrected 2026-10-04: the source is the chip's tooltip, and a click opens FR-8.3's dialog, `TriStateOverridePrompt` — no flyout exists)* (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header.
|
||||
|
||||
## Screens
|
||||
|
||||
@@ -187,10 +188,12 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> measured `renderW×H → outputW×H` with upscaler + quality, the RT chip, GPU/CPU temperature, ~~per-process VRAM~~
|
||||
> (corrected 2026-10-03: that line read the Overlay's per-present VRAM, which nothing produced, so it was always empty;
|
||||
> since beta.12 it is "This game: VRAM … · RAM …" from the newest telemetry tick, `GameMemoryText.Live`).
|
||||
> The sparkline is PR-6's. Recent = `ISessionRepository.ListRecentAsync(10)` with game names; a completed
|
||||
> ~~The sparkline is PR-6's.~~ Recent = `ISessionRepository.ListRecentAsync(10)` with game names; a completed
|
||||
> session reloads the lists (the row is in SQLite, `07_IPC` §Client behavior). Totals = the library's games,
|
||||
> `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. Capability badges and the Repair button are
|
||||
> PR-8's with the Agent section.
|
||||
> `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. ~~Capability badges and the Repair button are
|
||||
> PR-8's with the Agent section.~~ *(Corrected 2026-10-04: PR-6 and PR-8 shipped without them. No sparkline exists,
|
||||
> here or on the Games cards; the Agent card shows its facts as text, and the Vulkan layer state and the logon
|
||||
> task's Repair are on Settings.)*
|
||||
>
|
||||
> **Amended 2026-09-23: the card shows every running session, measured or not.** A session held unhooked
|
||||
> (Tier 2 — hooking off, refused, unreadable) shows its name, the T2 badge, the elapsed time and the
|
||||
@@ -235,7 +238,7 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
|
||||
> **Built 2026-09-14 (P3 PR-5): the grid, the detail page's header, the two rows, the hooking control and
|
||||
> the Sessions tab.** Grid: `ui:CardAction` cards with platform / engine / hooking badges, sessions, playtime,
|
||||
> last played (the sparkline is PR-6's); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's
|
||||
> last played (~~the sparkline is PR-6's~~ no sparkline was built — corrected 2026-10-04); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's
|
||||
> button, or an `.exe` dropped on the page (a `.lnk` needs the shell-link reader, later); FR-1.4 through
|
||||
> `Wpf.Ui.Controls.MessageBox` with **Keep sessions / Delete sessions too**, revoking consent over the pipe
|
||||
> FIRST when it was on. Detail: header (name, publisher · version · store · engine, last session's date and
|
||||
@@ -320,7 +323,7 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> is the newest session that read a driver profile, in the same words; no row where none did. Tests:
|
||||
> `NvidiaOverridesTests`, `GameDetailViewModelTests.TheDetailsCardNamesTheNvidiaAppsOverridesFromTheNewestSessionThatReadThem`.
|
||||
- Tabs (WPF `TabControl`, Fluent-styled):
|
||||
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. Multi-select → "Compare". Tier-2 rows render `—` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why.
|
||||
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. ~~Multi-select → "Compare".~~ (not built; Compare's own picker chooses) Tier-2 rows render ~~`—`~~ `N/A` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why *(corrected 2026-10-04: as built — `—` means a measured none, §FPS display rule)*.
|
||||
2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
|
||||
3. **Distribution** — FPS histogram + percentile curve of selected session(s).
|
||||
4. **Trend** — metric-over-date line (selector: Native avg / Displayed avg / 1% Low / 0.1% Low / max GPU temp), vertical **hardware-change markers** with tooltip "GPU driver 572.16 → 576.02" (FR-6.3).
|
||||
@@ -528,7 +531,9 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
|
||||
> (App / Agent) read with `FileShare.ReadWrite` — Serilog keeps it open — capped at the last 2 MB with the partial
|
||||
> first line dropped, refreshed every 2 s while the page is on screen (the page's Loaded/Unloaded start and stop
|
||||
> the timer) and never while paused; the level filter reads the `[HH:mm:ss.fff LVL]` prefix of 10_LOGGING's
|
||||
> template (continuation lines such as stack frames keep only under All); the search is a plain `ui:TextBox`, not
|
||||
> template ~~(continuation lines such as stack frames keep only under All)~~ — the App's; *(corrected 2026-10-04: the
|
||||
> Agent writes Serilog's default template, a date first, which the filter did not read, so Warning and Error showed no
|
||||
> Agent line; since beta.12 `LogTail.LevelOf` reads both)* — continuation lines such as stack frames keep only under All; the search is a plain `ui:TextBox`, not
|
||||
> an `AutoSuggestBox` — there is nothing to suggest. The view is a read-only `TextBox` in Consolas that scrolls to
|
||||
> the end on every refresh unless paused. "Export bug bundle" is 10_LOGGING's step 2 and nothing more (see there).
|
||||
> The status line says shown / total / file. Tests: `LogTailTests`, `LogsViewModelTests`, and the page renders in
|
||||
@@ -546,7 +551,7 @@ Sections per FR-10 using the WPF UI settings idiom: `ui:CardControl`/`ui:CardExp
|
||||
|
||||
**System (2026-09-21, FR "show the user's hardware"):** a card above Legal stating this PC as a session's hardware snapshot would record it right now — processor, graphics card, graphics driver, memory, Windows build, primary display — through the same `IHardwareSnapshotSource` the Agent stamps sessions with, read on the thread pool when the page opens, a field that could not be read as N/A, with **Copy** (the same lines as text) and a note that nothing is sent anywhere and what CPU temperature needs. Its own `SystemInfoViewModel`, not `SettingsViewModel`'s. The same snapshot is one tertiary line under the session summary's header (it was loaded for the export and shown nowhere), and `--diag` prints it; the bug bundle's `sysinfo.json` is deliberately NOT given it — its keys are the issue link's prefill.
|
||||
|
||||
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", background capture toggle. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
|
||||
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", ~~background capture toggle~~ *(removed in beta.12 — nothing read it; corrected 2026-10-04)*. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
|
||||
|
||||
> **The admin mode, beta.10 (owner decision D34; `01_ARCHITECTURE` ADR-9).** The Agent section has a switch, *Run the agent
|
||||
> as administrator* (`capture.run_elevated`, off by default). Turning it on opens a `ContentDialog`
|
||||
@@ -573,8 +578,10 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> `19_SAFETY_AND_ANTICHEAT.md` at the public repository in the user's browser (nothing is fetched).
|
||||
> **Recording:** minimum session length, sensor interval and raw-series retention as `ui:NumberBox`es bounded by
|
||||
> the registry; a value outside the range is refused in place (the previous value comes back, a warning names the
|
||||
> range, nothing is written); background capture as a toggle with the honest sentence (recorded, measured only if
|
||||
> hook-enabled and not Vulkan). **Agent:** the elevation state from `HelloAck.Elevated` with the paragraph above
|
||||
> range, nothing is written); ~~background capture as a toggle with the honest sentence (recorded, measured only if
|
||||
> hook-enabled and not Vulkan)~~ *(removed in beta.12, 2026-10-04: the toggle wrote `capture.background`, which no Agent
|
||||
> code read, so turning it off recorded every game anyway; with no way to start a game from the App, "off" could only
|
||||
> have meant recording nothing. The key is reserved — `06_DATA_MODEL` §Settings registry)*. **Agent:** the elevation state from `HelloAck.Elevated` with the paragraph above
|
||||
> (not required by any tier; unlocks CPU temperature through PawnIO and attaching to elevated games); the logon
|
||||
> task row says the scheduled task arrives with the tray build. **Window:** "Start FrameLedger with Windows" is
|
||||
> `Infrastructure.Startup.RunAtLogon` — this user's `HKCU\…\Run` value, quoted executable path, never HKLM —
|
||||
@@ -629,15 +636,16 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> the root `LICENSE` as the GPLv3 text, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md`, embedded at build so the
|
||||
> App shows the text this build was reviewed with; HTML authoring comments stripped; `{{RELEASE_DATE}}` left for
|
||||
> `release.yml`), a list on the left, the text in a read-only box (~~raw Markdown~~ rendered since beta.12), "View on GitHub" per document, **one Accept**
|
||||
> that writes four `legal_acceptance` rows with each document's own `**Version:**` line (`GPL-3.0-only` for the
|
||||
> licence), and Decline, which ends the host — the shell never appears. Closing the window without deciding is a
|
||||
> that writes ~~four~~ three `legal_acceptance` rows with each document's own `**Version:**` line ~~(`GPL-3.0-only` for the
|
||||
> licence)~~ *(corrected 2026-10-04: since beta.12, D45, the GPL is shown for information and gets no row; an older
|
||||
> `gpl` row is left as written)*, and Decline, which ends the host — the shell never appears. Closing the window without deciding is a
|
||||
> decline. **(2) Agent setup:** the honest paragraph (unelevated by default; elevation optional, unlocks CPU
|
||||
> temperature and elevated-game attach, required by no tier) and the facts from `HelloAck` as they arrive —
|
||||
> state, version, telemetry source, overlay build, CPU temperature, elevated — N/A until the Agent answers.
|
||||
> **(3) The explainer:** the consent dialog's own reviewed Tier 1 / Tier 2 paragraphs (`Safety_Consent_Hooked` /
|
||||
> `_NotHooked`, so the two screens cannot drift), that hooking stays off until enabled per game, and that the
|
||||
> Disclaimer states the risk. **(4)** ~~the import placeholder (P4)~~ **since P4 PR-4 (2026-09-14) a real pointer: the stores' libraries are imported from File ▸ Import library… once inside, every row hooking off** (the step itself stays text — the review dialog needs the shell's dialog host, which the first-run window has not). D8 unchanged: the gate is not a consent
|
||||
> precondition. Tests: `LegalDocumentsTests`, `FirstRunViewModelTests` (required on empty, one Accept = four
|
||||
> precondition. Tests: `LegalDocumentsTests`, `FirstRunViewModelTests` (required on empty, one Accept = ~~four~~ three
|
||||
> rows at the documents' versions, a moved version re-shows only that document, decline/close write nothing,
|
||||
> read-only records nothing, the Agent facts), the two steps rendered in `PagesLoadTests`.
|
||||
>
|
||||
@@ -684,8 +692,9 @@ which is why the handler is ours.
|
||||
- Every interactive control that shows no text of its own carries `AutomationProperties.Name` from `.resx` — the
|
||||
toggles and choice boxes on Settings, the hooking switch on a game's page, and the icon-only close button in the
|
||||
`InfoBar` template. A control *with* visible text needs nothing: its text is its name.
|
||||
- `PagesLoadTests`-style scan (`AccessibilityTests.EveryTextlessControlHasAName`): every `Button`, `ToggleSwitch`,
|
||||
`ToggleButton`, `CheckBox`, `ComboBox` and `HyperlinkButton` in the App's XAML either has content or a name. A new
|
||||
- `PagesLoadTests`-style scan (`AccessibilityTests.~~EveryTextlessControlHasAName~~ EveryInputThatShowsNoTextHasAnAutomationName`
|
||||
— corrected 2026-10-04): every `Button`, `ToggleButton`, `ToggleSwitch`, `CheckBox`, `RadioButton`, `ComboBox`,
|
||||
`TextBox`, `NumberBox`, `PasswordBox`, `Slider` and `HyperlinkButton` in the App's XAML either has content or a name. A new
|
||||
unnamed one is red.
|
||||
- Status lines that change after an action (the Database maintenance result) are `AutomationProperties.LiveSetting="Polite"`.
|
||||
|
||||
|
||||
+4
-4
@@ -14,10 +14,10 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
|
||||
## Mechanics
|
||||
|
||||
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` for error codes). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
|
||||
- XAML binding via `{x:Static res:Strings.Key}` plus a `LocalizeExtension` for the few dynamic cases.
|
||||
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` ~~for error codes~~ for the safety family, the `Safety_*` keys — corrected 2026-10-04). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
|
||||
- XAML binding via `{x:Static res:Strings.Key}` ~~plus a `LocalizeExtension` for the few dynamic cases~~ *(corrected 2026-10-04: no `LocalizeExtension` exists; text that varies is composed in the view model from `Strings.*`)*.
|
||||
- **Runtime switching:** setting change → set `CultureInfo.CurrentUICulture` + `Thread` defaults → re-create the main window shell (cheap; state preserved via VM). Persist in `settings`.
|
||||
- `SatelliteResourceLanguages` = `en;vi;ja` in the App csproj to keep publish size down.
|
||||
- `SatelliteResourceLanguages` = `en;vi;ja` in ~~the App csproj~~ `Directory.Build.props` (corrected 2026-10-04) to keep publish size down.
|
||||
|
||||
## Key conventions
|
||||
|
||||
@@ -34,7 +34,7 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
|
||||
- `en` written first, is authoritative.
|
||||
- `vi` authored by the maintainer.
|
||||
- `ja` machine-drafted, each entry marked with `<comment>review</comment>` until reviewed; the About dialog credits reviewers.
|
||||
- `ja` machine-drafted, each entry marked with `<comment>review</comment>` until reviewed; ~~the About dialog credits reviewers~~ *(corrected 2026-10-04: no screen credits reviewers yet, and no `ja` entry has been reviewed — owner-only)*.
|
||||
- CI check (`tools/resx-audit`): every key present in all three files; ~~missing → build warning list artifact~~ **missing is RED (2026-09-13)**: `tools/resx-audit.ps1` exists since P3 PR-2 as `build.ps1` step 15, self-test first (11 fixture cases, at least four must go red) then the live pass over every `Strings.resx` under `src/`. Per family it requires C#-identifier keys with non-empty neutral values, **exactly** the neutral key set in `vi` and `ja` (a missing key would fall back to English silently; an extra one is dead text), the `Safety_*` rule below, and a current `Strings.Designer.cs`. A tree with no family is red, not green — the gate must not be vacuous.
|
||||
|
||||
## Glossary (fixed translations)
|
||||
|
||||
@@ -4,8 +4,16 @@
|
||||
|
||||
- Sinks: rolling file per process — `logs/ui-.log`, `logs/agent-.log` (`rollingInterval: Day`, `retainedFileCountLimit: 7`, `fileSizeLimitBytes: 10 MB`, `rollOnFileSizeLimit: true`). Console sink in DEBUG builds. *(`ui-.log` is written since 2026-09-13, P3 PR-2, with `Process=ui` enriched and every unhandled path — Dispatcher, AppDomain, unobserved task — logged as Fatal/Error; ~~the crash dialog and minidump of §Crash handling are still P4's~~ — built 2026-09-15, P4 PR-9, §Crash handling's note.)*
|
||||
- Minimum level `Information` (`Debug` toggle in Settings → applies live via `LoggingLevelSwitch`).
|
||||
- Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).
|
||||
- ~~Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).~~
|
||||
- Template: `[{Timestamp:HH:mm:ss.fff} {Level:u3}] {SourceContext} {Message:lj} {Properties:j}{NewLine}{Exception}`.
|
||||
|
||||
> **Corrected 2026-10-04 — the four lines above are `ui-.log`'s configuration, not both processes'.** `agent-.log`
|
||||
> (`FrameLedger.Agent/Program.cs`, since 2026-09-10) is daily with **14** files kept and no size cap, writes Serilog's
|
||||
> **default** template — `2026-10-04 09:15:02.123 +07:00 [INF] …`, a date first — and its level is fixed at
|
||||
> Information with `Microsoft.*` at Warning: `log.debug` is the App's alone. Neither process has a console sink, and no
|
||||
> enricher exists beyond the App's `Process=ui`. The Logs page reads both shapes since beta.12 — until then its level
|
||||
> filter recognised only the App's `[HH:mm:ss.fff LVL]` prefix, so Warning and Error showed no Agent line at all
|
||||
> (`LogTail.LevelOf`, `LogTailTests.TheAgentsTemplateIsReadToo`).
|
||||
- **Never log:** full user paths outside `%LOCALAPPDATA%\FrameLedger` (redact to `<user>`), machine name, any exe arguments of games. ~~A `RedactingEnricher` enforces the path rule.~~ *(No such enricher was ever written: found 2026-09-15, checking `legal/PRIVACY_POLICY.md` §3's "logs are redacted (user directory paths removed) before bundling" against the bundle, which copied the logs verbatim. An enricher could not have kept the rule anyway: exception text and the Overlay's native log never pass through one, and the data directory itself sits under the user's profile, so every run logs a user name. The rule is enforced where a log leaves the machine instead: `App/Services/LogRedactor` over every log copy in the bug bundle, §Bug report flow step 2. The files in `logs\` keep their full paths; they leave the PC only if the user copies them.)*
|
||||
- Capture hot path logs nothing per-frame; counters summarized at finalize.
|
||||
|
||||
@@ -151,7 +159,7 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
|
||||
|
||||
## Diagnostics extras
|
||||
|
||||
- `Tools → Agent status…` shows the `HelloAck` capability set (telemetry source, overlay build id, Vulkan layer — ~~tier availability~~, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder) + last 20 Agent log lines.
|
||||
- `Tools → Agent status…` ~~shows the `HelloAck` capability set (telemetry source, overlay build id, Vulkan layer~~ — ~~tier availability~~, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder ~~) + last 20 Agent log lines~~. *(Corrected 2026-10-04: it opens the Dashboard's Agent card — state, version, telemetry source, overlay build id, elevated, running sessions. The Vulkan layer state is on Settings ▸ Capture and the Agent's log on the Logs page.)*
|
||||
- **Never include a game's own logs, saves, or config files** in a bug bundle, even when a crash looks game-related. We ship our logs only.
|
||||
- `--diag` CLI flag on the App prints environment + capability report to stdout (support requests).
|
||||
|
||||
@@ -162,8 +170,9 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
|
||||
> **Built 2026-09-14 (P3 PR-8a).** `App.OnStartup` sees `--diag` and runs `DiagAsync` instead of the host: no
|
||||
> window, no Agent, the ledger opened read-only for its schema version and the settings, then
|
||||
> `Services/DiagReport.Build` (app version, OS and bitness, runtime, locale, elevation, data and logs
|
||||
> directories, ledger schema or "could not open", whether `FrameLedger.Agent.exe` is beside the App, every
|
||||
> registry key's effective value) written to `logs/diag-<yyyyMMdd-HHmmss>.txt` **and** to stdout — the App is
|
||||
> directories, ledger schema or "could not open", whether `FrameLedger.Agent.exe` is beside the App, since
|
||||
> 2026-09-21 the machine as a session's hardware snapshot records it — CPU, GPU, driver, RAM, display — added to this
|
||||
> list 2026-10-04, and every registry key's effective value) written to `logs/diag-<yyyyMMdd-HHmmss>.txt` **and** to stdout — the App is
|
||||
> a WinExe with no console of its own, so stdout carries the report only when the caller attached one or piped
|
||||
> it (`FrameLedger.exe --diag | more` works; a double-click leaves the file). Exit 0, or 1 with a Fatal line in
|
||||
> `ui-*.log`. The Agent's `--diag` stays on its `NotImplementedFlags` list — 10_LOGGING names the flag as the
|
||||
|
||||
+9
-6
@@ -1,6 +1,6 @@
|
||||
# 11 — Updater
|
||||
|
||||
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. Stable channel only in v1.
|
||||
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. ~~Stable channel only in v1.~~ *(Corrected 2026-10-04: two channels since P4 PR-5 — `update.channel`, stable by default or beta, which adds pre-releases. Every release so far is a pre-release; see §Built, Channels.)*
|
||||
|
||||
## Flow
|
||||
|
||||
@@ -21,7 +21,7 @@ Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledg
|
||||
| Package hash mismatch | `Update_Err_Corrupt` | Auto-retry once, then dialog |
|
||||
| Unknown | `Update_Err_Unknown` + exception logged | "Report a bug" shortcut |
|
||||
|
||||
Detection-rules updates share this client, but the **`anticheat` block is fetched and applied on its own schedule regardless of the user's rules-update preference** (`05_DETECTION` FR-7.3) — a user who turned off rules updates must still receive new anti-cheat entries.
|
||||
~~Detection-rules updates share this client, but the **`anticheat` block is fetched and applied on its own schedule regardless of the user's rules-update preference** (`05_DETECTION` FR-7.3) — a user who turned off rules updates must still receive new anti-cheat entries.~~ *(Corrected 2026-10-04: there is no rules fetch and no rules-update preference. Tools ▸ Update detection rules re-reads the copy seeded from the install (`07_IPC`); FR-7.3 is unmet (`20_OPEN_QUESTIONS` §S20). The sentence is what a fetch must do once built.)*
|
||||
|
||||
All update HTTP goes through one `GitHubHttpClient` (also used by rules updates) with: UA `FrameLedger/{version}`, 10 s timeout, ETag cache in `settings`, single retry with jitter for transient failures.
|
||||
|
||||
@@ -29,7 +29,7 @@ All update HTTP goes through one `GitHubHttpClient` (also used by rules updates)
|
||||
|
||||
Binaries are not code-signed (project policy). Consequences and mitigations, documented in README and the update dialog footer:
|
||||
- SmartScreen warning on first run of a new version — expected; SHA-256 checksums (`SHA256SUMS.txt`) published with every release; CI prints them into release notes.
|
||||
- Velopack delta packages reduce download size; full package fallback automatic.
|
||||
- ~~Velopack delta packages reduce download size; full package fallback automatic.~~ *(Corrected 2026-10-04: no delta has been published — `release.yml` never puts the previous release in `out/release` before `vpk pack`, so every update downloads the full package; a delta needs a `vpk download github` step first.)*
|
||||
- Never bypass or suppress OS warnings programmatically.
|
||||
|
||||
## Versioning
|
||||
@@ -37,7 +37,7 @@ 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
|
||||
> zero is initial development). Schemas ~~0008–0015~~ 0008–0017 *(corrected 2026-10-04: 0016 shipped in beta.10 beside 0015, 0017 in beta.11; 0018 rides beta.12)* and the shared-memory layout 4 (2026-09-27, beta.10) each shipped in a
|
||||
> `0.1.0-beta.N`. What protects a user is not the number: the ledger migrates in place (`06_DATA_MODEL` §Migrations), and a
|
||||
> layout mismatch is refused at attach with "restart the game" (`07_IPC` §Protocol rules). The rule applies from `1.0.0`.
|
||||
|
||||
@@ -107,5 +107,8 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
- ~~Release notes are rendered as plain text, not Markdown.~~ Corrected 2026-10-03: rendered since beta.12 (Markdig; HTML off, no image fetched).
|
||||
|
||||
`UpdateServiceTests` (App.Tests/Update) cover the two skips, the channels, Deferred ↔ Ready, each error row, and
|
||||
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; a real feed has
|
||||
not been exercised — the first tag is the measurement (`13_CI_CD` §release.yml).
|
||||
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; ~~a real feed has
|
||||
not been exercised — the first tag is the measurement~~ *(corrected 2026-10-04: the feed has existed since
|
||||
v0.1.0-beta.1, 2026-09-16, and every release since carries `releases.win.json`; whether an installed copy has updated
|
||||
through it is not recorded here)*
|
||||
(`13_CI_CD` §release.yml).
|
||||
+20
-12
@@ -5,7 +5,7 @@ Mixed toolchain: .NET 10 for managed projects, MSVC for the native layer.
|
||||
## Prerequisites
|
||||
|
||||
- Windows 11 (dev), **.NET 10 SDK**, **Visual Studio 2026** with: .NET desktop development, **Desktop development with C++** (MSVC v143+, Windows 11 SDK ≥ 10.0.22621), C++ ATL not required.
|
||||
- **Vulkan SDK** (for the layer + validation layers during development).
|
||||
- **Vulkan SDK** (~~for the layer +~~ validation layers during development, and to run `tools/vklayer-blastradius.ps1`) *(corrected 2026-10-04: the layer builds against the vendored `third_party/vulkan-headers`; CI installs no SDK)*.
|
||||
- CMake ≥ 3.28 (native projects use CMake; consumed by the solution via a build target — see below).
|
||||
- Optional: PawnIO for CPU-temperature testing; an NVIDIA GPU for the NVAPI/Reflex paths (dev machine: RTX 5080). AMD/Intel telemetry paths need no SDK — if you have such hardware, testing L1/L2 coverage there is valuable.
|
||||
- **No admin needed for normal development.** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (CLAUDE.md §Dev mode records the same, and this line contradicted it in the present tense until 2026-08-05). When it exists it runs the whole app with a synthetic source and zero injection. Until then the no-injection development path is `hook-harness`, which needs no admin either.
|
||||
@@ -23,8 +23,9 @@ Targets:
|
||||
- `FrameLedger.Overlay` → `FrameLedger.Overlay.dll`
|
||||
- `FrameLedger.VkLayer` → `FrameLedger.VkLayer.dll` + `VkLayer_FRAMELEDGER_overlay.json`
|
||||
- `FrameLedger.Injector` → **static lib only.** There is no `FrameLedger.Injector.exe` and none ships (`20_OPEN_QUESTIONS` §S9, decided 2026-08-02). A standalone `LoadLibraryW` injector that users can run is a path into a game process that the guard does not stand in front of — a bypass, and a bad look for a project whose position is "we refuse where we are not welcome". The Agent links the static lib; the guard owns the chokepoint inside it (§S13(b)), so there is no callable entry point that skips the gate. Manual testing uses `hook-harness`, never a real game (§Debugging).
|
||||
- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other three shipped natives. ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too.
|
||||
- `FrameLedger.Overlay.Tests` → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too
|
||||
- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other ~~three~~ shipped natives (five in all since beta.12 — corrected 2026-10-04). ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too.
|
||||
- `FrameLedger.Guard` → `FrameLedger.Guard.dll` (the guard's C ABI over the Injector library, `src/native/FrameLedger.Injector/CMakeLists.txt`; loaded by the Agent) and `FrameLedger.ProcessStats` → `FrameLedger.ProcessStats.dll` (beta.12, D43: the game process's memory, read by the Agent from outside the game; probe `fl-probe-processstats`) *(both bullets added 2026-10-04; they were missing)*
|
||||
- ~~`FrameLedger.Overlay.Tests`~~ the ctest executables in `src/native/tests/` (`fl_ring_test`, `fl_guard_test`, `fl_vklayer_test`, … — corrected 2026-10-04: no target of that name has existed) → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too
|
||||
- `hook-harness` → the dummy **D3D11 + D3D12** app, WARP + composition swapchain so it runs headless on CI (`17_HOOK_ENGINE` §Test harness). D3D12 is device → command queue → swapchain, which is the acquisition asymmetry a D3D11-only fixture cannot exercise. ~~Vulkan and OpenGL modes to follow as those hooks land.~~ **`--vulkan --hold-presenting N` since 2026-09-06 (P1 item 3):** a real swapchain on a hidden window through the real loader, reached by `LoadLibraryW("vulkan-1.dll")` so only the vendored headers are needed and CI (no loader) still builds it; exit 77 = cannot run here, which the ctest reads as SKIP. **`--opengl --hold-presenting N` since the same day (P1 item 4):** a real context on a hidden window, `SwapBuffers`'d through gdi32 as a title does, on Microsoft's generic renderer — so it runs on CI.
|
||||
- `fl-probe-hookprofile` → build-profile probes for `/guard:cf` and `-D_HAS_EXCEPTIONS=0` (`20_OPEN_QUESTIONS` §H1/§H3)
|
||||
- `fl-probe-guard` → measures the Windows APIs the guard is built on, unelevated (`spike-notes.md` §1). Not the guard, and takes no injection rights.
|
||||
@@ -43,7 +44,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
|
||||
|
||||
**No AMD or Intel GPU *telemetry* SDK is vendored.** Those vendors' sensors are covered by LibreHardwareMonitor and the DXGI/PDH baseline (`18_GPU_VENDOR_APIS`). A build that pulls in Intel IGCL or AMD ADLX material is a licensing regression, not a feature — CI greps for it. **The AMD FidelityFX ffx-api headers (MIT by exception, tag v2.3.0) ARE vendored since 2026-09-04**, for the Overlay's upscaler hook and for types only — `fl_fidelityfx_headers` above, `18_GPU_VENDOR_APIS` §AMD for the licence reading, and `license-check.ps1` §2d for the per-file gate. Intel's XeSS SDK failed the checklist and nothing of it is here.
|
||||
|
||||
**VERSIONINFO is mandatory** on `FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`: real `CompanyName`, `ProductName=FrameLedger`, `FileDescription`, version. Identifiability is a requirement (`19_SAFETY`), and a CI check fails the build if the resource block is missing.
|
||||
**VERSIONINFO is mandatory** on ~~`FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`~~ every shipped native — the five `tools/versioninfo-check.ps1` lists (corrected 2026-10-04): real `CompanyName`, `ProductName=FrameLedger`, `FileDescription`, version. Identifiability is a requirement (`19_SAFETY`), and a CI check fails the build if the resource block is missing.
|
||||
|
||||
## Managed build & native integration
|
||||
|
||||
@@ -55,7 +56,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
|
||||
> **`RuntimeIdentifier` is NOT set here, and this bullet claimed it was until 2026-08-06.** The props file's own comment explains why: forcing a RID onto class libraries pulls RID-specific assets into their restore for no benefit, so each executable sets it — `FrameLedger.App`, `FrameLedger.Agent` and now `FrameLedger.CaptureHost`, plus its test project, which needs the same RID to reference a RID'd exe. A new project copying this document rather than the props file would have inherited nothing.
|
||||
- Nullable enable, ImplicitUsings enable, `TreatWarningsAsErrors=true`, `AnalysisLevel=latest-all`, deterministic, `ContinuousIntegrationBuild` on CI.
|
||||
- `Directory.Packages.props`: central package management, all versions pinned (including `WPF-UI` = 4.3.0 exactly — `16_WPFUI_SYNTAX` §Version hygiene).
|
||||
- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project.
|
||||
- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole), and since beta.12 `/FrameLedger.ProcessStats.targets` (the game-memory reader, D43; it also warns rather than fails — an absent reader reads N/A; added 2026-10-04). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project.
|
||||
|
||||
> **This bullet was wrong in four ways and is corrected 2026-08-04.** It named a copy of `FrameLedger.Injector.exe`, which §S9 closed and which line 25 above says does not exist, 24 lines earlier in the same document. It attributed the copying to a build target in `FrameLedger.Infrastructure.csproj`, which contains no `<Target>` at all. It said the copies happen there, when the guard DLL was deliberately moved out to a `.targets` file so it would stop flowing to every referencing project (§S18 blocker 3). And it credited the solution with an ordering the solution cannot express.
|
||||
- **Struct mirror check — ✅ built 2026-08-05.** `ShmLayoutMirrorTests` runs `tools/fl-layout-dump`, reads its JSON, and asserts size plus every field offset against the C# `[StructLayout]` mirrors in `FrameLedger.Shared` — in **both directions**, so a field on either side alone fails. It also asserts blittability, which offsets cannot see. The `struct-mirror` gate reads the run's `.trx` and fails when that test class did not execute, so deleting the test is red as well as breaking it. Struct drift between the two layers is the most dangerous silent bug in this architecture; the build now genuinely catches it.
|
||||
@@ -64,10 +65,15 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
|
||||
|
||||
## Debugging
|
||||
|
||||
Launch profiles:
|
||||
- **"UI + Mock"** — `FL_MOCK=1`, no Agent, no injection. Default for UI work.
|
||||
- **"UI + Agent"** — both managed processes, real capture against `hook-harness`.
|
||||
- **"Harness + Overlay"** — starts `hook-harness` under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.
|
||||
~~Launch profiles:~~
|
||||
- ~~**"UI + Mock"** — `FL_MOCK=1`, no Agent, no injection. Default for UI work.~~
|
||||
- ~~**"UI + Agent"** — both managed processes, real capture against `hook-harness`.~~
|
||||
- ~~**"Harness + Overlay"** — starts `hook-harness` under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.~~
|
||||
|
||||
*(Corrected 2026-10-04: none of these is committed, and "UI + Mock" needs `FL_MOCK`, which §Prerequisites says is not
|
||||
implemented. What exists: `FrameLedger.exe` starts `FrameLedger.Agent.exe --serve` beside itself. To capture against the
|
||||
harness, run `hook-harness.exe --real --hold-presenting N`, then the Agent's `--console --data-dir <scratch>` verbs
|
||||
`consent grant --exe` and `capture --exe`, as `AgentEndToEndTests` does — never against your own data folder.)*
|
||||
|
||||
**Toolchain gotchas, both hit on a real machine and both handled by `build.ps1`:**
|
||||
|
||||
@@ -174,7 +180,7 @@ assumed to.
|
||||
cmake --build --preset x64-release
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -o out/app
|
||||
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
```
|
||||
|
||||
> **Run by `release.yml` since 2026-09-14 (P4 PR-5)** — `13_CI_CD` §release.yml carries the steps around it
|
||||
@@ -225,7 +231,7 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
|
||||
the repository, and it is deliberate: the effective date of a legal document is
|
||||
the date it ships, which is not knowable at authoring time. `release.yml` (**built 2026-09-14**, P4 PR-5 — the step runs before the
|
||||
build, because the App embeds `legal/*.md`)
|
||||
substitutes it with the tag date when packaging, and `ci.yml` fails the build if
|
||||
substitutes it with ~~the tag date~~ the run's UTC date (corrected 2026-10-04) when packaging, and `ci.yml` fails the build if
|
||||
**any other** `{{` token appears in `README.md` or `legal/*.md` (`13_CI_CD.md`
|
||||
§ci.yml). Everything else — repository URL, slug, developer identity, contact
|
||||
address — is resolved in the source files, because an unsubstituted token in a
|
||||
@@ -243,7 +249,9 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
|
||||
4. `dotnet restore` + build (warnings as errors)
|
||||
5. `dotnet format --verify-no-changes`
|
||||
6. `dotnet test --logger trx` — including `ShmLayoutMirrorTests`; with no switches it also runs the
|
||||
`Category=Integration` classes, which CI excludes
|
||||
`Category=Integration` classes, ~~which CI excludes~~ which CI runs too *(corrected 2026-10-04: `ci.yml` and
|
||||
`release.yml` call `./build.ps1 check` with no switches since 2026-09-06, as the paragraph after this list says;
|
||||
only `-SkipIntegration`, which nobody passes, leaves them out, loudly)*
|
||||
7. `tools/coverage-gate.ps1` — reads this run's cobertura reports; self-arming, and armed today for
|
||||
`FrameLedger.Domain` and `FrameLedger.Application`
|
||||
8. `tools/rules-validate.ps1` (schema + `anticheat` block sanity — a malformed or empty blocklist is a safety bug)
|
||||
|
||||
+12
-11
@@ -6,7 +6,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
|
||||
## Workflows (`.github/workflows/`)
|
||||
|
||||
### `ci.yml` — push to `main` + all PRs · **repo-local**
|
||||
### `ci.yml` — push to `main` + all PRs + `workflow_dispatch` (added 2026-10-04) · **repo-local**
|
||||
- `runs-on: windows-latest`, .NET SDK pinned by `global.json` via `actions/setup-dotnet`, MSVC via `ilammy/msvc-dev-cmd`, NuGet cached.
|
||||
- Single step of substance: **`./build.ps1 check`** — the same script, with the same switches (none), a developer runs before pushing. The gate list lives in `12_BUILD` §Local quality gate, **once**, rather than being restated here where it goes stale.
|
||||
- ~~**`-SkipIntegration` is the one place local and CI deliberately differ**~~ — **gone since 2026-09-06.** From 2026-08-05 CI passed it for a measured reason: §S16 puts the injecting process's ancestors in the scan set, a .NET test host loads `System.Security.Cryptography.ProtectedData.dll`, and the guard's `protect` fragment refused our own harness (§S19(b)). The signer half now verifies that module's embedded signature offline and reads `O=Microsoft Corporation` on the compiled-in bound, so the `Category=Integration` cases run here — **nine** when this was written, **20 across six classes** as of 2026-09-13 (Agent 6, CaptureHost 7, Infrastructure 7); count them with `grep -rl 'Category", "Integration' tests` rather than trusting either number — and a green CI IS evidence for the managed drain and the capture host's end-to-end behaviour. The switch remains in `build.ps1`, loud, for a developer who must.
|
||||
@@ -81,8 +81,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
> `ShmLayoutMirrorTests` did not execute. `12_BUILD` carried the identical stale sentence and is
|
||||
> corrected with it; restating the gate list in two documents is what let one of them rot.
|
||||
- **Licence guard:** `tools/license-check` fails the build if a vendored dependency is missing its licence copy, or if Intel IGCL / AMD ADLX headers appear anywhere in the tree (`docs/18_GPU_VENDOR_APIS.md` §Vendor SDKs we deliberately do not use), or — since P4 PR-6 — if `legal/licenses/nuget/` is not what `tools/license-gather.ps1` writes for the NuGet packages this build ships. A Dependabot bump therefore goes red until someone re-runs the script and commits the texts, which is the point: the new version's licence is read by a person before it ships. Licensing regressions are silent and hard to unwind later — catch them at PR time.
|
||||
- **Placeholder guard:** fails if any `{{` token survives in `README.md` or `legal/*.md`. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
|
||||
- `permissions: contents: read`.
|
||||
- **Placeholder guard:** fails if any `{{` token survives in `README.md` or `legal/*.md` *(other than `{{RELEASE_DATE}}`, which `release.yml` substitutes — added 2026-10-04)*. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
|
||||
- ~~`permissions: contents: read`.~~ `permissions: contents: read, pull-requests: read` — the second for the Changelog step's list of a pull request's files, read-only *(corrected 2026-10-04)*.
|
||||
|
||||
### `codeql.yml` — push, PR, weekly cron · **repo-local**
|
||||
|
||||
@@ -132,8 +132,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
- **The identical gate** — `./build.ps1 check`, native first, every tool including `versioninfo-check` against
|
||||
`VERSION`. A release never skips it.
|
||||
- `dotnet publish` App + Agent, self-contained + ReadyToRun, `-p:Version=<tag>`, into one `out/app`.
|
||||
- **The published tree asserted by name**: `FrameLedger.exe`, `FrameLedger.Agent.exe`, the four shipped natives
|
||||
`versioninfo-check` lists, `rules/detection-rules.json`; `FrameLedger.CaptureHost.exe` absent (`12_BUILD`:
|
||||
- **The published tree asserted by name**: `FrameLedger.exe`, `FrameLedger.Agent.exe`, the ~~four~~ five shipped natives
|
||||
`versioninfo-check` lists (`FrameLedger.ProcessStats.dll` since beta.12 — corrected 2026-10-04), `rules/detection-rules.json`; `FrameLedger.CaptureHost.exe` absent (`12_BUILD`:
|
||||
exactly two roots — `package-closure-check` proves it statically, this reads the directory); `versioninfo-check`
|
||||
run again over `out/app`, because a `.targets`-staged DLL that failed to copy is a warning to `dotnet publish`.
|
||||
- `vpk pack --packId FrameLedger.App` (the `vpk` tool pinned to the library's 1.2.0) with the release notes;
|
||||
@@ -148,8 +148,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
- ~~Optional final step: submit installer hash to VirusTotal~~ — not built; an upload of the installer to a third
|
||||
party is a decision the owner makes, not a step a workflow adds quietly.
|
||||
|
||||
### `rules-publish.yml` — on change to `rules/detection-rules.json` in `main`
|
||||
- Runs `tools/rules-validate` and fails on anti-cheat removals. The raw file on `main` **is** the distribution endpoint (05_DETECTION), so this workflow only gates correctness.
|
||||
### `rules-publish.yml` — ~~on change to `rules/detection-rules.json` in `main`~~ on a PR or push to `main` touching the rules file, its schema, `rules-validate.ps1` or this workflow (corrected 2026-10-04)
|
||||
- Runs `tools/rules-validate` and fails on anti-cheat removals. ~~The raw file on `main` **is** the distribution endpoint (05_DETECTION), so this workflow only gates correctness.~~ *(Corrected 2026-10-04: there is no feed — §S20's feed half is deferred and nothing in `src` fetches. A rules change reaches users only inside a release, seeded by the Agent from the packaged copy; this workflow only gates correctness.)*
|
||||
|
||||
> **There is no `rulesVersion` bump check, and this line used to claim one.**
|
||||
> `rules-validate.ps1` checks the field's *format* and nothing compares it
|
||||
@@ -173,7 +173,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
> evaluator through the real probe. Both halves run on the same PR; only the
|
||||
> coverage half fires on a rules-only change, which is why the two are
|
||||
> described separately rather than as one gate.
|
||||
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix.
|
||||
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix. *(Added 2026-10-04: the PR-only removal step fails the job on any removal, a shrunk per-title list or an added trusted signer, whatever the body says — the justification is for the reviewer, and the job stays red.)*
|
||||
- `permissions: contents: read`.
|
||||
|
||||
## Dependabot (`.github/dependabot.yml`)
|
||||
@@ -195,7 +195,7 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
## Branch & release policy
|
||||
|
||||
- `main` protected: CI + CodeQL required, linear history, no direct pushes.
|
||||
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
|
||||
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) *(corrected 2026-10-04: for a pre-release tag `vX.Y.Z-beta.N`, do not bump `VERSION` — it already holds the numeric core the gate compares, and it read `0.1.0` through eleven betas; the section is `## [X.Y.Z-beta.N] - date`, the full version. Bump `VERSION` only when the numeric core moves)* → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
|
||||
- Pre-releases: `vX.Y.Z-beta.N` tags mark the GitHub release as pre-release; the App's `stable` channel ignores them and its `beta` channel (Settings ▸ Updates, `update.channel`) includes them — built with P4 PR-5, so ~~explicit beta channel is v2 backlog~~ is struck. The managed assemblies carry the full tag version; the native VERSIONINFO blocks carry the numeric core (`12_BUILD` §Version).
|
||||
|
||||
## Repo hygiene checklist
|
||||
@@ -215,7 +215,8 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
|
||||
**GitHub settings — the owner's (`HANDOFF` §Owner-only):**
|
||||
|
||||
- [ ] Branch protection as §Branch & release policy states; `Rules / validate` as a required check (§S23-2, after its skip-shim)
|
||||
- [x] Branch protection as §Branch & release policy states *(marked 2026-10-04, read from the API: required checks `check`, `analyze (csharp, none)` and `analyze (cpp, manual)`; linear history; a pull request required; force pushes off; enforced for admins)*
|
||||
- [ ] `Rules / validate` as a required check (§S23-2, after its skip-shim)
|
||||
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
|
||||
- [ ] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves
|
||||
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
|
||||
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
|
||||
+4
-4
@@ -6,9 +6,9 @@ Managed: xUnit.net v3 4.x (the `xunit.v3.mtp-off` variant since 2026-09-21 — `
|
||||
|
||||
The anti-cheat guard is the one component where a bug can cost someone an account. It gets the most rigorous treatment in the codebase:
|
||||
|
||||
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. ~~Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).~~ **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.
|
||||
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. ~~Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).~~ **Landed long since** — `ctest` runs ~~31~~ 32 native suites on every gate (`fl_process_stats` since beta.12 — corrected 2026-10-04) (`fl_guard` alone is ~100 s); the sentence was left in the future tense until 2026-09-21.
|
||||
|
||||
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set. **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.
|
||||
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. ~~Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set.~~ *(Corrected 2026-10-04: both have data since 2026-09-25 — Ricochet a driver and services, VAC per-title lists of Steam ids and executables, which `rules_budget_test.cpp` matches back to "Valve VAC".)* **Since 2026-09-25** the fixture is generated from the shipped seed (`rules_budget_test.cpp`: every entry's every value matches its own family in its own group, which also catches a row an earlier prefix shadows), and Ricochet's fixture asserts its data; VAC's still asserts that no family entry fakes it.
|
||||
- **A finding turns the game's hooking off (2026-09-22), and the proofs are about WHICH findings.** `AntiCheatVerdictTests` pins `IsFindingAboutTheGame` per reason (in the game: yes; machine-wide driver or service, heuristics, failed scans, the latch: no) and that a finding without a family is not one; `CaptureSessionTests` that a start-time `BlockedModule` writes the block, keeps the consent stamp and says `HookingTurnedOff`, that a `BlockedDriver` refuses the session and leaves the row alone, and that the 30 s re-scan's finding writes the same block; `RecordedSessionEventsTests` and `SafetyNoticesTests` that the flag travels to the notice. The override of 2026-09-21 had its own proofs for one day; they went with it, and `NoSecondMatcherTests` counts the port's four methods again.
|
||||
- **Fail-closed proofs:** malformed `detection-rules.json`, missing `anticheat` block, unreadable target process, `EnumProcessModulesEx` failure, partial module list → **all must refuse injection**, never allow. Each is a named test.
|
||||
- **Measured error paths that must be named tests** (`spike-notes.md` §1): `ERROR_PARTIAL_COPY (299)` from a suspended target, `ERROR_ACCESS_DENIED (5)` from a protected one, a driver-list parse whose paths are not native paths, and a service query returning `ACCESS_DENIED` — the last of which **cannot be produced on real services by a standard user**, so it exists only as a fake. Every one means REFUSE.
|
||||
@@ -21,7 +21,7 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
- **Ring buffer:** SPSC correctness under a hammering writer thread; seqlock torn-read detection; wrap and overwrite-oldest semantics; power-of-two capacity assumptions. Include the **one-full-lap case**: a reader stalled exactly `capacity` records must not validate a different frame as unchanged (this is what the never-reset `seq` counter defends, `07_IPC` §Protocol rules).
|
||||
- **Drop accounting:** the reader-side computation (`writeIndex - readIndex > capacity`) reports the right count and resumes at the right index. The writer has no drop counter to test — by design.
|
||||
- **Torn records produce gap markers,** not silently shortened streams; a golden test asserts the gap does not appear as a stutter.
|
||||
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all three header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`) — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
|
||||
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all ~~three~~ four header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`, and `FlDisplayState` since layout 4, beta.10) — plus D33's `FlTolerance`, mirrored the same way *(corrected 2026-10-04)* — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
|
||||
- **Fault policy:** injected SEH faults in a fake hook body → counter increments, original still called, self-disable at 3.
|
||||
- **Hook index verification, by behaviour.** A vtable slot carries no identity, so "check that slot 8 *is* `Present`" is not a question the runtime can answer — the earlier wording here required something unimplementable. What is answerable: patch the slot, call the method, see whether the detour ran (`17_HOOK_ENGINE` §Getting vtable addresses; proved for slots 8, 13 and 22 in `spike-notes.md` §H4). Runs headless on CI via WARP and `CreateSwapChainForComposition`. A deliberate mismatch aborts installation instead of patching.
|
||||
- **Every probe must be shown to fail.** A probe that ends in an unconditional assertion is green by construction and its ctest is decorative — `fl_proxy_swapchain` shipped in exactly that state. Before a probe counts as a regression net, break the thing it watches and watch it go red.
|
||||
@@ -131,7 +131,7 @@ that it was checked against anything.
|
||||
| Mode | launch mode · attach mode · mid-session settings change |
|
||||
| Safety | game with anti-cheat → toggle disabled · simulated late AC load → unhook · double-crash → auto-disable |
|
||||
| Tier | forced Tier 2 (records duration, available sensors and the reason — and nothing else) · Tier 1 → Tier 2 degradation notice |
|
||||
| Update | Velopack delta; update deferred while a game is hooked (FR-12) — *a delta needs a previous release, so this row is reachable from the second release, not the first* |
|
||||
| Update | Velopack delta; update deferred while a game is hooked (FR-12) — *a delta needs a previous release, so this row is reachable from the second release, not the first* *(corrected 2026-10-04: no release has carried a delta — `release.yml` never fetches the previous release before `vpk pack`, `11_UPDATER` §Built — so the update leg is a full package)* |
|
||||
|
||||
## Release smoke
|
||||
|
||||
|
||||
+16
-8
@@ -151,7 +151,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> the hard gate, against NFR-10 — but the evidence changed, and the consequence is
|
||||
> live: the drain tests are skipped in CI until it is fixed.
|
||||
|
||||
0. **The guard.** Module + driver enumeration, blocklist matching, fail-closed behaviour on every error path. **Moved from item 8**: items 1 and 6 below inject into real games, and CLAUDE.md rule 2 plus P1's own "it ships before the first real injection, not after" both forbid that ordering. **◐ Every documented check now has a call site; one half of one check does not.** `EvaluateImpl` runs checks 1, 2, 2b, 3 (executable half) and 4 — five, not four, because 2b (`services`) is the only tier ever measured firing on real anti-cheat and every count that says "four" omits it. The guard is built (`FrameLedger.Injector`, native per §S13(a)), owns the chokepoint, and its fail-closed matrix is Catch2-driven. The injection primitive landed after it, in that order. Reached from managed code through one P/Invoke facade — never a second matcher (§S15). Evidence: `spike-notes.md` §1; §S7, §S8, §S16 closed.
|
||||
0. **The guard.** Module + driver enumeration, blocklist matching, fail-closed behaviour on every error path. **Moved from item 8**: items 1 and 6 below inject into real games, and CLAUDE.md rule 2 plus P1's own "it ships before the first real injection, not after" both forbid that ordering. ~~**◐ Every documented check now has a call site; one half of one check does not.**~~ **Every documented check has a call site since 2026-09-25 (§S14) — corrected 2026-10-04.** `EvaluateImpl` runs checks 1, 2, 2b, 3 (executable half) and 4 — five, not four, because 2b (`services`) is the only tier ever measured firing on real anti-cheat and every count that says "four" omits it. The guard is built (`FrameLedger.Injector`, native per §S13(a)), owns the chokepoint, and its fail-closed matrix is Catch2-driven. The injection primitive landed after it, in that order. Reached from managed code through one P/Invoke facade — never a second matcher (§S15). Evidence: `spike-notes.md` §1; §S7, §S8, §S16 closed.
|
||||
|
||||
> **This line said ✅ DONE, and it was wrong in a way worth recording.**
|
||||
> `19_SAFETY` specifies four pre-injection checks. **Check 4** (the static
|
||||
@@ -174,6 +174,12 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> > deleted: it is the third place that had to be corrected for one PR, and the
|
||||
> > count is the point.
|
||||
> >
|
||||
> > *(Corrected 2026-10-04: the paragraphs below were overtaken on 2026-09-25 — both halves of check 3 are wired
|
||||
> > and seeded. `CheckBlockedStoreId` reads Steam's `appmanifest_*.acf` and GOG's `goggame-*.info` through a
|
||||
> > guard-owned seam; an install no store names is not refused, unreadable store metadata is; Epic has no reader.
|
||||
> > Rules 2026.10.1 list 33 executables and 33 Steam ids, floored. The owner question about a permanently
|
||||
> > uncallable sub-check is moot.)*
|
||||
> >
|
||||
> > **This item stays ◐, on a different and narrower reason.** Check 3's
|
||||
> > **store-id half** has no call site and cannot be given one: nothing produces
|
||||
> > a `store_id` — the platform metadata extractors are unbuilt, which is the
|
||||
@@ -186,7 +192,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> > uncallable is an owner decision, not a coding one. And unchanged either way:
|
||||
> > `blockedExecutables` **ships empty**, so check 3 refuses nothing today. What
|
||||
> > #52 changed is that populating it would now do something.
|
||||
1. **Vulkan layer passthrough.** Minimal implicit layer registered under `HKCU`, with the opt-in checks that keep it passthrough for non-enabled processes. **Moved from item 7**: a passthrough bug loads FrameLedger into every Vulkan process on the machine, which is the highest blast radius in the spike. **◐ Gates done, interception not started.** `enable_environment` measured against loader 1.4.357, blast radius verified, in-layer blocklist self-scan built and proven both directions. `vkQueuePresentKHR` is **not** hooked — that is P1, and §S2's in-layer supervision check lands with it.
|
||||
1. **Vulkan layer passthrough.** Minimal implicit layer registered under `HKCU`, with the opt-in checks that keep it passthrough for non-enabled processes. **Moved from item 7**: a passthrough bug loads FrameLedger into every Vulkan process on the machine, which is the highest blast radius in the spike. **◐ Gates done, ~~interception not started~~.** `enable_environment` measured against loader 1.4.357, blast radius verified, in-layer blocklist self-scan built and proven both directions. ~~`vkQueuePresentKHR` is **not** hooked — that is P1, and §S2's in-layer supervision check lands with it.~~ *(Corrected 2026-10-04: landed 2026-09-06, P1 item 3 — present and swapchain interception plus §S2's in-layer supervision, ctests `fl_vklayer_real` and `fl_vklayer_supervision`. The ray-tracing and pipeline entries are still unbuilt.)*
|
||||
2. **Hook viability.** `hook-harness` (D3D11 + D3D12) + MinHook: dummy-device vtable probe, verify present indices at runtime, install/uninstall cleanly, measure per-present cost. Confirm `/MT` DLL loads into a real (offline, non-AC) game without incident. **✅ DONE.** Vtable indices proved by behaviour (§H4), unhook proved not to clobber a later hooker (§H7), per-present cost measured at 8.4 ns against a 1,000 ns budget — and **the `/MT` DLL is now loaded into a real title**: Lies of P, attach mode, guard passing, module verified present by re-enumeration, game still rendering afterwards (`spike-notes.md` §7).
|
||||
|
||||
> **Attach mode only when this ran.** Launch mode was blocked by §S18 — the
|
||||
@@ -224,7 +230,9 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> (Steam `.acf`, GOG `.info`, Epic `.item`) — every platform rule is
|
||||
> `sibling_glob`/`path_contains`, so identification is unaffected but
|
||||
> **`store_id` is null for every title**. No SQLite, so nothing is persisted
|
||||
> and `field_provenance` is decided-but-unimplemented (P2). The engine and
|
||||
> and `field_provenance` is decided-but-unimplemented (P2). *(Overtaken — corrected 2026-10-04: the store import
|
||||
> writes `store_id` since P4 PR-4, the guard reads the stores' metadata for check 3 since 2026-09-25, and
|
||||
> `field_provenance` is written since 2026-09-14.)* The engine and
|
||||
> platform fixture families are **P4 library metadata shipped early** under
|
||||
> P0's name.
|
||||
>
|
||||
@@ -264,7 +272,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
8. **Telemetry layering.** Fill the `18_GPU_VENDOR_APIS` capability matrix on real hardware:
|
||||
- L1 baseline (DXGI + PDH counters) working vendor-neutrally; decide whether the `D3DKMT` perf-data probe is stable enough on Win 10 **and** Win 11 to keep. **🅓 Deferred to Win 11 only, 2026-08-05** — one machine, and it is Win 11. Win 10 22H2 stays a supported floor and is explicitly unmeasured; the deferral holds only for as long as the probe stays non-load-bearing, which `18_GPU_VENDOR_APIS` §L1 now states as the condition rather than as advice.
|
||||
- L2: which fields LibreHardwareMonitor actually returns per vendor, and **whether GPU sensors work unelevated without PawnIO** — this decides whether the default unelevated Agent has temperatures. **◐ NVIDIA measured 2026-09-03: yes (§M5 row R1), eight fields unelevated, `LhmTelemetrySource` written.** AMD / Intel remain 🅓 (§R5/§R6).
|
||||
- L3: NVAPI linked from vendored MIT headers; Reflex latency, throttle reasons, per-domain utilisation.
|
||||
- L3: NVAPI linked from vendored MIT headers; Reflex latency, throttle reasons, per-domain utilisation. *(Status added 2026-10-04: built 2026-09-10, P2 PR-E2, as `FrameLedger.NvapiBridge.dll` — throttle reasons and utilisation; Reflex latency has no producer.)*
|
||||
- ~~**Licence confirmations:** LHM free of MPL-2.0 Exhibit B; NVAPI SPDX blocks intact~~ — **done before P0 began, both clear** (`spike-notes.md` §0). `tools/license-check` is in place and proven to fail on a planted violation.
|
||||
|
||||
*(The former items 7 "Vulkan layer" and 8 "Guard prototype" are now items 1 and 0. §R1/§R2 are folded in, not pending.)*
|
||||
@@ -313,14 +321,14 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
## P2 — Capture pipeline (1 week)
|
||||
Agent: watcher, tier selection, injection orchestration, shm drain, telemetry poller (NVAPI first), session recorder, segments, `.partial` recovery, ~~Tier-2 `EtwFrameSource` retained as fallback.~~ **There is nothing to retain: Tier 2 has no mechanism as of 2026-08-27** (§G). `EtwFrameSource` is a port with no adapter, and P2 should not be planned as though writing one were scoped. SQLite v2 schema + migrations. Domain metric calculators + golden tests. **Milestone: first real hooked session persisted with measured upscaler/RT data.** *Technical half reached 2026-09-10 (P2 PR-F): the shipped `FrameLedger.Agent.exe --console capture` against `hook-harness` ends as one hooked `sessions` row, in the merge gate (`AgentEndToEndTests`). **P2's code is complete as of PR-G (2026-09-10)** — kill-and-recover is in the gate too (`PartialRecoveryEndToEndTests`) and `tools/fps-impact-runbook.ps1` exists. What P2 still owes is two MEASUREMENTS, not code: the real-title milestone read against the game's own menus, and the ≤ 0.5 % FPS-impact run. Both are the owner's; `spike-notes` §14 holds their slots and the exact commands. **The milestone's row half exists as of 2026-09-16** — the shipped Agent's Lies of P session with `fsr3`, 1506×848 → 2560×1440, FG ×2.04 and `rt = no` (`spike-notes` §14.1); the menu column is still the owner's, as is the FPS-impact run.*
|
||||
|
||||
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; the owner's merges of the stack are the remaining act)**
|
||||
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). *Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*
|
||||
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; ~~the owner's merges of the stack are the remaining act~~ merged 2026-09-13/14, #152–#165)**
|
||||
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). ~~*Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*~~ *(Struck 2026-10-04: false since PR-2 — the App shell, the en/vi/ja `.resx`, `Shared/Ipc`.)*
|
||||
|
||||
## P4 — Detection & product polish (1 week)
|
||||
~~Static rules engine + `detection-rules.json` (engines, platforms, capabilities, **anticheat blocklist**) + validator + fixtures~~ **landed 2026-09-14 (P4 PR-1: the engine existed since P0; the Agent's `DetectionSweep` is its first caller, `ApplyDetectionAsync` its first writer — HANDOFF §P4)**; ~~store auto-import~~ **landed 2026-09-14 (P4 PR-4)**; ~~capability-vs-measured UI separation~~ **(PR-1: the Supports row reads the sweep's flags)**; ~~i18n en/vi/ja; Legal Gate;~~ ~~Velopack + updater (with the hooked-session deferral)~~ **landed 2026-09-14 (P4 PR-5 — the deferral is `UpdateService`'s shape, not a flag)**; ~~bug bundle incl. overlay logs~~ **landed (overlay logs since P3 PR-8a; 2026-09-15, P4 PR-9: the crash dialog, the minidump in both processes and the dump as the bundle's opt-in — `10_LOGGING` built notes)**; ~~tray + toasts; Settings;~~ ~~DB maintenance~~ **landed 2026-09-15 (P4 PR-7: the sweep is the Agent's over `SweepRetention`; integrity, backup and compaction in the App)**; ~~accessibility pass~~ **landed 2026-09-15 (P4 PR-8: `08_UI` §Accessibility written first — Ctrl+1…5, Esc on every dialog, an automation name on every textless input, theme colours only — each held by `AccessibilityTests`)**; ~~the scheduled task (`--install-task`)~~ (P3 PR-8b) and ~~the Velopack install hooks~~ **(PR-5: the uninstall hook; install registers nothing, by design — `12_BUILD` §The Vulkan layer is not registered at install time)**. *(The struck items moved to P3 on 2026-09-13 — see §P3.)*
|
||||
|
||||
## P5 — Ship (3–4 days)
|
||||
CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 — ~~untested by a tag yet~~ **ran on the first tag 2026-09-16** (`13_CI_CD` §release.yml: cancelled by a test hang once, green on the re-run); **rehearsable without one since 2026-09-16**, `13_CI_CD` §release.yml's dry run); CodeQL (C# + C++); Dependabot; CHANGELOG; README with the P0 accuracy comparison — **which is not a percentage, and this line used to send its author looking for one**. The decision is recorded under item 3 and in `spike-notes.md` §8: the baseline can answer **none** of item 4's four runtime questions, so the defensible claim is *"the baseline cannot answer four of these five questions at all"*, not *"N% more accurate"*. Overhead + tier cross-validation measurements; release smoke on clean VMs; ~~`v0.1.0-beta.1`~~ **tagged and published 2026-09-16** (pre-release, unsigned, `SHA256SUMS.txt` beside the assets). What P5 still owes: the clean-VM smoke (`14_TESTING` §Release smoke — Win 10 22H2 is unmeasured), the overhead run (`spike-notes` §14.3), and the README's accuracy comparison sentence.
|
||||
CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 — ~~untested by a tag yet~~ **ran on the first tag 2026-09-16** (`13_CI_CD` §release.yml: cancelled by a test hang once, green on the re-run); **rehearsable without one since 2026-09-16**, `13_CI_CD` §release.yml's dry run); CodeQL (C# + C++); Dependabot; CHANGELOG; README with the P0 accuracy comparison — **which is not a percentage, and this line used to send its author looking for one**. The decision is recorded under item 3 and in `spike-notes.md` §8: the baseline can answer **none** of item 4's four runtime questions, so the defensible claim is *"the baseline cannot answer four of these five questions at all"*, not *"N% more accurate"*. Overhead + tier cross-validation measurements; release smoke on clean VMs; ~~`v0.1.0-beta.1`~~ **tagged and published 2026-09-16** — eleven pre-releases through `0.1.0-beta.11` (2026-10-03), added 2026-10-04 — (pre-release, unsigned, `SHA256SUMS.txt` beside the assets). What P5 still owes: the clean-VM smoke (`14_TESTING` §Release smoke — Win 10 22H2 is unmeasured), the overhead run (`spike-notes` §14.3), and the README's accuracy comparison sentence.
|
||||
|
||||
**Total ≈ 5.5–6.5 weeks full-time** — roughly 1.5–2 weeks more than the ETW design, which is the honest price of the accuracy.
|
||||
|
||||
@@ -339,7 +347,7 @@ CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 —
|
||||
- Microsoft Store / Game Pass titles (packaged-app injection constraints)
|
||||
- AFK segmentation via `GetLastInputInfo`
|
||||
- GPU frame time via timestamp queries (needs care: injecting queries into the game's command lists is more invasive than anything in v1 — needs its own risk review)
|
||||
- Beta update channel; ARM64
|
||||
- ~~Beta update channel;~~ ARM64 *(struck 2026-10-04: the beta channel shipped with P4 PR-5 — `update.channel`, Settings ▸ Updates; `13_CI_CD` §Branch & release policy)*
|
||||
|
||||
## Permanently out of scope
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ Mandatory conventions for all XAML/C# in `FrameLedger.App`. WPF UI = lepoco's Fl
|
||||
| Package (NuGet id) | Pin | Notes |
|
||||
|---|---|---|
|
||||
| `WPF-UI` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net10.0-windows10.0.22621.0` TFM (`12_BUILD` §Managed build; this row said `19041` until 2026-09-21, which is no TFM this repository ever built — `Directory.Build.props` has been `22621` with a 19045 floor throughout) |
|
||||
| `WPF-UI.Abstractions` | transitive | Navigation abstractions (`INavigationViewPageProvider`) |
|
||||
| `WPF-UI.Abstractions` | ~~transitive~~ **= 4.3.0**, referenced directly (corrected 2026-10-04) | Navigation abstractions (`INavigationViewPageProvider`) |
|
||||
| `WPF-UI.DependencyInjection` | match `WPF-UI` | DI glue (`services.AddNavigationViewPageProvider()`); verify exact id/version at scaffold |
|
||||
| `WPF-UI.Tray` | **not used** | Tray stays on H.NotifyIcon.Wpf (CLAUDE.md stack table) |
|
||||
|
||||
@@ -81,7 +81,7 @@ Theme rules:
|
||||
<RowDefinition Height="*"/> <!-- NavigationView -->
|
||||
</Grid.RowDefinitions>
|
||||
|
||||
<ui:TitleBar Grid.Row="0" Title="FrameLedger" Icon="pack://application:,,,/Assets/icon.ico" />
|
||||
<ui:TitleBar Grid.Row="0" Title="FrameLedger" /> <!-- no Icon: no icon file exists yet (corrected 2026-10-04) -->
|
||||
|
||||
<Menu Grid.Row="1"> <!-- classic menu, Fluent-restyled automatically --> </Menu>
|
||||
|
||||
@@ -103,7 +103,7 @@ Theme rules:
|
||||
</ui:NavigationView>
|
||||
|
||||
<ui:SnackbarPresenter x:Name="SnackbarPresenter" Grid.Row="2" VerticalAlignment="Bottom" />
|
||||
<ContentPresenter x:Name="DialogHost" Grid.Row="2" /> <!-- ContentDialogService host -->
|
||||
<ui:ContentDialogHost x:Name="DialogHost" Grid.Row="2" /> <!-- §Dialogs; a ContentPresenter stood here until 2026-10-04 -->
|
||||
</Grid>
|
||||
</ui:FluentWindow>
|
||||
```
|
||||
@@ -152,7 +152,7 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `
|
||||
styles (`Styles/FrameLedger.xaml`), or the `Pill` style with a `SystemFillColor*BackgroundBrush` and an explicit text
|
||||
brush; `ContrastTests` refuses all five (`08_UI` §Contrast).
|
||||
- Do **not** set `Background` on `FluentWindow` (kills Mica). Page backgrounds transparent by default.
|
||||
- Exception to the no-hex rule: the chart palette — defined once per theme in `Styles/ChartPalette.xaml` (two dictionaries), never inline.
|
||||
- Exception to the no-hex rule: the chart palette — defined once per theme in ~~`Styles/ChartPalette.xaml` (two dictionaries)~~ `Styles/ChartPalette.Dark.xaml` and `ChartPalette.Light.xaml` (corrected 2026-10-04), never inline.
|
||||
|
||||
## FlowDocument (rendered documents, beta.12)
|
||||
|
||||
@@ -191,7 +191,7 @@ var box = new Wpf.Ui.Controls.MessageBox
|
||||
var result = await box.ShowDialogAsync(); // Wpf.Ui.Controls.MessageBoxResult.Primary
|
||||
```
|
||||
|
||||
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` and ban the System one (BannedSymbols/analyzer note).
|
||||
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` ~~and ban the System one (BannedSymbols/analyzer note)~~ *(corrected 2026-10-04: nothing bans it. Three paths use the Win32 box on purpose — the crash dialog, the startup-failure dialog and the uninstall question — because they run when the shell's dialog host cannot be trusted. Use the WPF UI one everywhere else.)*
|
||||
- Rich in-flow dialogs: `IContentDialogService` (host wired in MainWindow — a `ui:ContentDialogHost`, since 4.3.0 marks `SetDialogHost(ContentPresenter)` obsolete).
|
||||
- Transient in-app: `ISnackbarService.Show(title, message, ControlAppearance.Success, new SymbolIcon(SymbolRegular.Checkmark24), TimeSpan.FromSeconds(4))`.
|
||||
- System/tray notifications: H.NotifyIcon only (08_UI §Notifications policy).
|
||||
|
||||
+37
-20
@@ -22,7 +22,7 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
|
||||
> ⚠ The CFG result was measured with **strict mode off**. A host that enables CFG strict mode does not auto-validate dynamically generated code and could still `__fastfail`. Rare, but real, and not something the fault policy can catch — see §Fault policy and `20_OPEN_QUESTIONS` §H8.
|
||||
- No STL container that allocates in a hook path. `std::atomic` and fixed arrays are fine.
|
||||
- VERSIONINFO populated (`ProductName=FrameLedger`, real company/version) — being identifiable is required by `19_SAFETY`.
|
||||
- Exports: `FlGetBuildId()`, `FlRequestUnhook()`, `FlGetStatus()`. Real names, no ordinal-only tricks.
|
||||
- Exports: `FlGetLayoutVersion()` (added to this line 2026-10-04), `FlGetBuildId()`, `FlRequestUnhook()`, `FlGetStatus()`. Real names, no ordinal-only tricks.
|
||||
|
||||
## DLL entry
|
||||
|
||||
@@ -82,7 +82,7 @@ void** vtbl = *reinterpret_cast<void***>(dummySwapChain);
|
||||
MH_CreateHook(vtbl[kPresentIndex], &Hook_Present, reinterpret_cast<void**>(&Orig_Present));
|
||||
```
|
||||
|
||||
Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapChain1`, `ResizeBuffers = 13`) live in `HookIndices.h`.
|
||||
Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapChain1`, `ResizeBuffers = 13`) live in ~~`HookIndices.h`~~ `FrameLedger.Overlay/include/fl_dxgi_vtable.h`, shared with the harness; the D3D12 command-list slots in `fl_d3d12_vtable.h` (corrected 2026-10-04: no `HookIndices.h` exists).
|
||||
|
||||
> ⚠ **"Verified at runtime against the dummy object" is not implementable, and
|
||||
> must not be reintroduced.** A vtable slot holds a bare function pointer: no
|
||||
@@ -112,15 +112,18 @@ Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapCha
|
||||
> restore-only-if-unchanged rule matters, since another overlay may have
|
||||
> patched the same shared slot after us.
|
||||
|
||||
Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards); use MinHook inline hooks for flat C exports (`wglSwapBuffers`, NGX/FFX/XeSS entry points).
|
||||
~~Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards);~~ *(corrected 2026-10-04: the Overlay swaps no vtable entry. It reads the slot off a throwaway object and MinHooks the function it points at, so one patch covers every instance (§Ray tracing); §Compare-and-restore explains why the swap is not the cleaner uninstall.)* Use MinHook inline hooks for flat C exports too (`wglSwapBuffers`, the Streamline and FidelityFX entry points ~~, NGX/FFX/XeSS~~ — NGX and XeSS have none).
|
||||
|
||||
## Hook inventory
|
||||
|
||||
Every hook must be listed here with a purpose. Anything not on this list is not allowed to exist (`19_SAFETY` review checklist).
|
||||
|
||||
> **This table is a SPECIFICATION. As of 2026-09-04 the Overlay installs TWELVE DETOURS —
|
||||
> **This table is a SPECIFICATION. ~~As of 2026-09-04 the Overlay installs TWELVE DETOURS —
|
||||
> the eight of 2026-09-03 plus four `ffxDispatch` trampolines, one per AMD module a game
|
||||
> calls — and the FidelityFX row below is the ninth ✅.** The counts differed until 2026-09-03, because a
|
||||
> calls — and the FidelityFX row below is the ninth ✅.~~** *(Corrected 2026-10-04: as of 2026-09-06 it installs up
|
||||
> to SIXTEEN — the nine `FL_HOOK_INVENTORY` rows (four Streamline including `slSetTagForFrame`, four `ffxDispatch`,
|
||||
> `ffxFsr3ContextDispatchUpscale`), the three DXGI slots, the two `ID3D12GraphicsCommandList4` methods,
|
||||
> `wglSwapBuffers` and `LoadLibraryExW`; four hooks landed without this banner moving.)* The counts differed until 2026-09-03, because a
|
||||
> row is a *capability* and a detour is a *patch*, and the FG-count row rode on the
|
||||
> evaluate detour; it has its own now, `sl.interposer.dll!slGetNewFrameToken`. The AMD row
|
||||
> is the opposite shape — **one row-family, four modules, four patches from one
|
||||
@@ -161,12 +164,12 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
> so a shipped hook missing from here is invisible to every gate. Flip the row **and this
|
||||
> banner** in the same PR that builds a hook.
|
||||
|
||||
### The one system-module detour — a hook, and the asymmetry stated
|
||||
### ~~The one system-module detour~~ The two system exports patched by name — a hook, and the asymmetry stated *(heading corrected 2026-10-04: `wglSwapBuffers` above is the other)*
|
||||
|
||||
| Hook | Purpose |
|
||||
|---|---|
|
||||
| ✅ `opengl32.dll!wglSwapBuffers` (2026-09-06, P1 item 4) | The OpenGL present hook (§Presentation). A system module, not a vendor one, so — like the row below — it is deliberately **not** in `FL_HOOK_INVENTORY` and `hookinventory-check` does not cover it; listed here so the table above and these two rows together are the whole inventory |
|
||||
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **It is the only hook on a system module, and it is deliberately not in `FL_HOOK_INVENTORY`:** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
|
||||
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **~~It is the only hook on a system module, and~~ Like `wglSwapBuffers` above it, it is deliberately not in `FL_HOOK_INVENTORY` (corrected 2026-10-04):** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
|
||||
|
||||
### Watchdog observations — not hooks, and listed here so nobody mistakes them for one
|
||||
|
||||
@@ -194,7 +197,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
| ✅ Streamline: `slSetTag` — **and, since 2026-09-05, every tag's TYPE** (`slTagCensus`; a HUD-less / UI tag marks the present `FL_FG_DLSS_G`, rule 4: the same argument) | The **global** resource tags, where a title states the size of the buffer it is upscaling *from*: `kBufferTypeScalingInputColor`'s extent → `renderW/H` — **or, since 2026-09-05, the size the tagged `sl::Resource` declares when the extent is zero** (`TagSize` in `fl_sl_inputs.h`, shared by all three tag routes; GUID-checked; a Resource declaring no size is still the honest unknown). **Built 2026-08-15** (`FL_HOOK_UPSCALER_PARAMS`), and it is an ALTERNATIVE to the local tags in `slEvaluateFeature`'s `inputs`, not a layer over them — `sl_core_api.h:258` says global and local tags "do NOT interact", so a title using one yields nothing from the other and both are read. Published only on a frame where an evaluation was also seen, because a tag is viewport state that outlives any one frame. This row was MISSING from this table while the hook shipped, which is the gap the banner above now names |
|
||||
| ✅ Streamline: `slSetTagForFrame` — **and every tag's TYPE, as above** | The same global tags through **Streamline 2.8's frame-based entry point**, which deprecates `slSetTag`: `(const FrameToken&, const ViewportHandle&, const ResourceTag*, uint32_t, CommandBuffer*)` — the token first, then exactly `slSetTag`'s list, handed to the same tag walk. **Built 2026-09-04** (`FL_HOOK_UPSCALER_PARAMS`, its own trampoline; the family is now **published when whole** — once every tag export the loaded interposer has is patched — because publishing on the first row entitled records the second was not yet producing, 38 of 41 on the fixture: the ffx leaves' #110 defect again, fixed the same way). Measured need: Dying Light: The Beast (SL 2.8.0) published `Dlss` identity on every batch and the params bit on none across three captures, because a 2.8 title that tags per frame never calls the deprecated export. The token is not read; the frame count stays with `slGetNewFrameToken`. The installer picks this detour by SYMBOL (`kSymbolSlSetTagForFrame`, bound to the row by `static_assert`), not by family, since the two rows share a family bit and differ in signature |
|
||||
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither) + one COUNT; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00 |
|
||||
| XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute` | `outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG |
|
||||
| ~~XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute`~~ **Closed at the census by licence, 2026-09-04** (`20_OPEN_QUESTIONS` §Scope decisions, `18_GPU_VENDOR_APIS` §Intel XeSS SDK): no hook on any `libxess*.dll` export *(corrected 2026-10-04)* | ~~`outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG~~ |
|
||||
| ✅ **Application frames per present** (`fgEvaluations`) — **`sl.interposer.dll!slGetNewFrameToken` since 2026-09-03** | Native vs Displayed frame counts at Tier 1 — see `03_METRICS` §Frame Generation. **The producer is the frame-token export**: Streamline hands a title one token per application frame and the title must ask; the detour counts distinct tokens between two presents (pointer changes, nothing dereferenced), `FL_HOOK_FG_EVALUATIONS` is its family, and it installs on every Streamline 2 title including the ones that evaluate nothing through `slEvaluateFeature`. Rule 4: the out-parameter of an API we hooked. Premise and its gate in `03_METRICS`; pre-committed table in `20_OPEN_QUESTIONS` §S31. *The row as it stood before:* ~~NGX/SL/FFX/XeSS FG feature evaluations per present. **Built 2026-08-15 for Streamline, and MEASURED TO YIELD NOTHING ON THAT ROUTE**~~ — `slEvaluateFeature(kFeatureDLSS_G)` is never called by Cyberpunk 2077 (0 across ~14,000 batches, four FG settings), so this row installs, is honest, and counts zero; see `docs/HANDOFF.md` item 3. Built on the detour that was already there: `kFeatureDLSS_G` contributes to a saturating COUNT in the same word the feature bits live in (`fl_sl_seen.h`) rather than to a bit, because a bit collapses several evaluations between two presents into one — and under multi-frame generation that is the common case, not the edge. The row's family is therefore compound (`FL_HOOK_UPSCALER_IDENTITY \| FL_HOOK_FG_EVALUATIONS`), pinned by a `static_assert` because `hookinventory-check` reads that column as an opaque identifier. **Counts EVALUATIONS, not generated frames** — the 2026-08-14 owner ruling; the multiplier lives in `sl::DLSSGOptions`, which is only reachable by the route §2b refused. ~~Non-NVIDIA FG vendors are **deferred with a written rationale**: `amd_fidelityfx_framegeneration_dx12.dll` 3.1.5 exports only the five generic `ffx*` entry points, identical to five sibling modules, so identity is in the arguments and we have no headers~~ — **AMD has a producer since 2026-09-04** (the FidelityFX row above: the PREPARE dispatch's `frameID`, or the UPSCALE count on a title that never prepares, feeds `fgEvaluations` when Streamline has never issued a token); Intel stays at the census (`20_OPEN_QUESTIONS` §Scope decisions, by licence); the FSR 3.0 host DLL's UPSCALE (`ffxFsr3ContextDispatchUpscale`, since 2026-09-05) counts like an ffx-api UPSCALE when neither Streamline nor a PREPARE has spoken |
|
||||
|
||||
> `GetFrameStatistics().PresentCount` is **not** in this inventory and must not be
|
||||
@@ -359,7 +362,9 @@ Vulkan gets an **implicit layer** (`FrameLedger.VkLayer`), not injection — it
|
||||
DLL**, and it compares the variable's **value**, so a stray
|
||||
`FRAMELEDGER_ENABLE_VK_LAYER=0` does not enable us. **This makes Vulkan
|
||||
Tier 1 launch-mode-only** — the Agent sets the variable when it starts an
|
||||
opted-in game, so a Vulkan title launched from Steam or GOG is not hooked.
|
||||
opted-in game, so a Vulkan title launched from Steam or GOG is not ~~hooked~~ observed by the layer *(corrected
|
||||
2026-10-04: attach mode has no Vulkan rule, so such a title gets the Overlay injected like a D3D one, and what its
|
||||
DXGI hooks record there is unverified; `kTargetIsVulkanLayered` applies to launch mode only)*.
|
||||
It is a *loading* gate, not a security gate: anything running as the user can
|
||||
set the variable.
|
||||
|
||||
@@ -487,7 +492,9 @@ struct alignas(64) FlFrameRecord { // 64 bytes exactly, static_assert'd
|
||||
uint8_t fgEvaluations; // @43 FG feature evaluations observed this frame
|
||||
uint32_t vramUsedMb; // @44 MiB, matching vramBudgetMb
|
||||
uint32_t reflexLatencyUs; // @48 0 = unavailable
|
||||
uint32_t reserved; // @52 must be zero
|
||||
uint8_t dxgiUnseen; // @52 DXGI-counted presents the hook did not see (2026-09-05; this listing
|
||||
// showed a uint32 reserved here until 2026-10-04)
|
||||
uint8_t reserved[3]; // @53..55 must be zero
|
||||
uint32_t seq; // @56 seqlock counter (see 07_IPC §Protocol rules)
|
||||
uint32_t swapchainId; // @60 which swapchain this present came through; 0 = unidentified
|
||||
};
|
||||
@@ -525,8 +532,9 @@ Field notes — each of these was a defect in an earlier revision:
|
||||
uncomputable from a pinned counter. `rays_per_pixel` divides this by output
|
||||
pixels.
|
||||
- **`maxTraceRecursionDepth`** is the second of the four stated inputs to
|
||||
`pt_confidence`. It is read at `CreateStateObject` (§Hook inventory) but
|
||||
previously had no transport to the Agent and no column to land in.
|
||||
`pt_confidence`. It ~~is~~ would be read at `CreateStateObject` (§Hook inventory) but
|
||||
previously had no transport to the Agent and no column to land in. *(Corrected 2026-10-04: `CreateStateObject` is
|
||||
not hooked, so nothing writes it yet.)*
|
||||
- **`_pad0` and `_pad1` were explicit holes and are now carrying data.** Both were
|
||||
named only so every offset could be asserted; spending them costs nothing,
|
||||
because both bytes ranges were already inside the record and already written
|
||||
@@ -561,14 +569,15 @@ Field notes — each of these was a defect in an earlier revision:
|
||||
- **SPSC lock-free ring**, capacity a power of two (default 8192 records = 512 KB), overwrite-oldest.
|
||||
- Writer/reader seqlock protocol, including the rule that the payload write must
|
||||
**exclude** the `seq` field and that `seq` is never reset: `07_IPC` §Protocol rules.
|
||||
- Header: three separate 64-byte lines before the ring — `FlShmHandshake` (write-once),
|
||||
- Header: ~~three~~ **four** separate 64-byte lines before the ring *(corrected 2026-10-04: since layout 4, 2026-09-27,
|
||||
beta.10, `FlDisplayState` at 0xC0 — Overlay-written at most every 500 ms; the ring starts at 0x100)* — `FlShmHandshake` (write-once),
|
||||
`FlWriterState` (Overlay-written: `writeIndex`, `status`, `apiMask`, `faultCount`),
|
||||
and `FlControlBlock` (**Agent**-written: `pauseRequested`, `unhookRequested`,
|
||||
`overlayEnabled`, `guardTicks`). The control flags are *not* in the Overlay's
|
||||
header — they are written by the other process, and mixing them into an
|
||||
Overlay-written line reintroduces exactly the false sharing the split exists to
|
||||
prevent. Layout is normative in `07_IPC` §A + B.
|
||||
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present.
|
||||
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present. *(Added 2026-10-04: the summary leaves out the per-present `IDXGISwapChain::GetLastPresentCount` call (§H5, the `dxgiUnseen` count) and the display sample every 500 ms at most (region 4).)*
|
||||
- Per-frame mutable state (current upscaler, render res, dispatch counts) lives in a small struct updated by the feature hooks and *read* by the present hook; counters reset at present.
|
||||
|
||||
## The watchdog thread — the only thread we add to the game
|
||||
@@ -577,6 +586,11 @@ One thread, started on the init thread *after* the hooks are installed, sleeping
|
||||
`1000 ms` at a time. It evaluates `unhookRequested` and the `guardTicks` deadline,
|
||||
calls `StopObserving` when either fires, and **exits** once stopped.
|
||||
|
||||
> **Corrected 2026-10-04 — this describes the thread as it was first written.** Since the lazy installers landed
|
||||
> (`slEvaluateFeature`, 2026-08-09) the loop also installs feature hooks, runs the runtime census, publishes counters,
|
||||
> appends the native log, and stops on the loader detour's early-stop family; it waits on that detour's wake event with
|
||||
> a 1000 ms timeout rather than sleeping. `legal/DISCLAIMER.md` §2 says so to users since beta.12 (Disclaimer 2.10).
|
||||
|
||||
**Why it exists.** Both stops used to be evaluated only on the present path, and
|
||||
`MayObserve` is reachable only from `RecordPresent`, which is reachable only from
|
||||
the two present hooks. In a process that had stopped presenting — hung,
|
||||
@@ -600,9 +614,12 @@ we do not own; the re-scan it would have run allocates ~1.15 MB transiently; and
|
||||
it would have called `NtQuerySystemInformation` and probed the SCM from inside a
|
||||
game, which is the behavioural signature of anti-analysis code (CLAUDE.md rule 3).
|
||||
None applies to the Overlay, which is loaded by documented `LoadLibraryW` and is
|
||||
never `FreeLibrary`'d from a live process. **This thread enumerates nothing,
|
||||
never `FreeLibrary`'d from a live process. ~~**This thread enumerates nothing,
|
||||
probes nothing and allocates nothing** — it reads two `uint32`s from our own
|
||||
mapping and sleeps. That distinction is the whole justification and must survive
|
||||
mapping and sleeps.~~ *(Corrected 2026-10-04: it enumerates no process, module list or service — the rule-3 line, which
|
||||
holds — but it asks the loader for fixed module names, allocates through MinHook and, for ray tracing, creates one
|
||||
command allocator and list on the game's own D3D12 device, and writes the log file. The justification below is
|
||||
restated for that scope: what it must never start doing is scanning.)* That distinction is the whole justification and must survive
|
||||
any future change: a watchdog that starts scanning is a different object under
|
||||
rule 3.
|
||||
|
||||
@@ -645,7 +662,7 @@ Every hook body is wrapped:
|
||||
> against the injected Overlay in ctest `fl_guard` `[log]`, where every patch reads `UNHOOK_RESTORED`
|
||||
> because the harness is alone in its process.
|
||||
|
||||
`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status. **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
|
||||
~~`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status.~~ *(Corrected 2026-10-04: both reach `StopObserving` — compare-and-restore per patch as the note above says, then the status; there is no `MH_ALL_HOOKS`, no vtable entry and no ring flush. The watchdog flushes the native log on its way out.)* **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
|
||||
|
||||
### Compare-and-restore, never unconditional restore
|
||||
|
||||
@@ -714,7 +731,7 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
|
||||
|
||||
## Test harness
|
||||
|
||||
`src/native/tools/hook-harness` — a minimal D3D11 app that presents at a controlled rate. It lets CI and local dev exercise hook paths with **no game and no anti-cheat surface at all** (`14_TESTING`).
|
||||
`src/native/tools/hook-harness` — a ~~minimal D3D11~~ D3D11/D3D12 app (plus `--vulkan` / `--opengl` modes — corrected 2026-10-04) that presents at a controlled rate. It lets CI and local dev exercise hook paths with **no game and no anti-cheat surface at all** (`14_TESTING`).
|
||||
|
||||
Two choices make it run on a hosted CI runner, which is what made vtable-index
|
||||
verification a dev-machine-only affair before:
|
||||
@@ -722,8 +739,8 @@ verification a dev-machine-only affair before:
|
||||
- **WARP** (`D3D_DRIVER_TYPE_WARP`) — a software rasteriser, so no adapter is required.
|
||||
- **`CreateSwapChainForComposition`** — no `HWND`, so no dependency on a window station or an interactive session.
|
||||
|
||||
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**, **`--vulkan --hold-presenting N`** (P1 item 3, real loader, exit 77 = cannot run here) and **`--opengl --hold-presenting N`** (P1 item 4, gdi32 `SwapBuffers` on a hidden window, Microsoft's generic renderer — runs on CI).
|
||||
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**, **`--vulkan --hold-presenting N`** (P1 item 3, real loader, exit 77 = cannot run here) and **`--opengl --hold-presenting N`** (P1 item 4, gdi32 `SwapBuffers` on a hidden window, Microsoft's generic renderer — runs on CI). *(Added 2026-10-04, each with its own ctest: `--probe-d3d12-vtable`, `--probe-dxr`, `--probe-dxr-inputs`, `--probe-upscaler-resolve`, `--probe-sl-abi`, `--probe-ffx-resolve`, `--probe-sl-inputs`, `--probe-sl-seen`, `--probe-dxgi-count`; and the `--hold-presenting-*` injection fixtures with `--load` / `--load-after-ms`.)*
|
||||
|
||||
> **Every present here used to carry `DXGI_PRESENT_TEST`, which submits nothing.** Measured: 500 of them leave `GetLastPresentCount` at 0 while 37 real presents move it by 37. "N presents → N records" was therefore satisfiable only by a writer counting non-frames. `--real` issues real presents; the test-present path is kept as a named mode because it is what an alt-tabbed title actually runs.
|
||||
|
||||
Still to add as the hook layer grows: Vulkan devices, RT PSO creation and ray dispatch, stub upscaler exports with the real vendor names, a PSO-compile spike generator, and a fault-injecting hook body for the self-disable path (`14_TESTING` §Integration tests).
|
||||
Still to add as the hook layer grows: ~~Vulkan devices, RT PSO creation and ray dispatch, stub upscaler exports with the real vendor names,~~ *(the struck three exist — corrected 2026-10-04)* a PSO-compile spike generator, and a fault-injecting hook body for the self-disable path (`14_TESTING` §Integration tests).
|
||||
@@ -33,7 +33,7 @@ public interface IGpuTelemetrySource : IDisposable
|
||||
Implementations compose rather than compete:
|
||||
|
||||
- `BaselineTelemetrySource` (L1) — always constructed.
|
||||
- `LhmTelemetrySource` (L2) — constructed when LHM initialises.
|
||||
- `LhmTelemetrySource` (L2) — ~~constructed when LHM initialises~~ always constructed; a `Computer` that will not open disables the layer for the session (corrected 2026-10-04).
|
||||
- `NvapiTelemetrySource` (L3) — ~~constructed only on NVIDIA hardware~~ **always constructed since 2026-09-10 (P2 PR-E2)** and disables itself when the bridge DLL or the NVIDIA driver is absent, so the composite's descriptor simply omits `nvapi` and no caller has to know the vendor before composing.
|
||||
- `CompositeTelemetrySource` merges them with a fixed precedence per field (**L3 > L2 > L1**) and records which layer supplied each value.
|
||||
|
||||
@@ -52,8 +52,12 @@ Implementations compose rather than compete:
|
||||
> `LayerOf(field)` answers per field. It also applies the two-fault rule one level up — a layer
|
||||
> whose `TryRead` throws (which the port forbids) is excluded on the second throw, the others
|
||||
> untouched. (3) Identity is its own record, `GpuAdapterIdentity` (name, LUID, ids, memory sizes,
|
||||
> user-mode driver version), read once per session from DXGI; the Agent hands the handshake's
|
||||
> `adapterLuid` to `SelectAdapter` so samples describe the adapter the game presented on. Every
|
||||
> user-mode driver version), read once per session from DXGI; ~~the Agent hands the handshake's
|
||||
> `adapterLuid` to `SelectAdapter` so samples describe the adapter the game presented on.~~ *(Corrected 2026-10-04:
|
||||
> nothing calls `SelectAdapter` outside tests. L1 stays on the first hardware adapter in DXGI's high-performance order,
|
||||
> as `HardwareSnapshotSource` does, and the handshake's `adapterLuid` is read by no managed code — so on a
|
||||
> multi-adapter machine L1 can describe an adapter the game did not present on. The game's own memory, D43, is
|
||||
> summed over every adapter and is not affected.)* Every
|
||||
> poller sample is stamped with QPC (`TelemetrySample.QpcTicks`), the ring's clock, and
|
||||
> `QpcClockTests` pins `Stopwatch` / `TimeProvider.GetTimestamp` to the real counter.
|
||||
|
||||
@@ -86,7 +90,7 @@ guard's and the NVAPI bridge's), never into a game — reads one process's memor
|
||||
|
||||
## L1 — baseline (no licence, all vendors)
|
||||
|
||||
- **DXGI:** `IDXGIFactory6::EnumAdapterByGpuPreference` → adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes. ~~`IDXGIAdapter3::QueryVideoMemoryInfo` for adapter-wide usage/budget.~~ **Measured wrong, 2026-09-09:** `DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsage` is the *calling process's* usage by the structure's own definition — which is exactly why the Overlay reads it inside the game for `vram_proc` — and from the Agent it read **0 bytes** beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (`DxgiAdapters`, the first CsWin32 consumer in the tree).
|
||||
- **DXGI:** `IDXGIFactory6::EnumAdapterByGpuPreference` → adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes. ~~`IDXGIAdapter3::QueryVideoMemoryInfo` for adapter-wide usage/budget.~~ **Measured wrong, 2026-09-09:** `DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsage` is the *calling process's* usage by the structure's own definition ~~— which is exactly why the Overlay reads it inside the game for `vram_proc` —~~ *(corrected 2026-10-04: the Overlay never read it, and `vram_proc` was never produced — §The game process's memory)* and from the Agent it read **0 bytes** beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (`DxgiAdapters`, the first CsWin32 consumer in the tree).
|
||||
- **PDH performance counters** — the same source Task Manager uses, fully documented, vendor-neutral:
|
||||
- `\GPU Engine(*)\Utilization Percentage` (sum per engine type: 3D, Compute, Copy, VideoDecode)
|
||||
- `\GPU Adapter Memory(*)\Dedicated Usage`
|
||||
@@ -133,7 +137,7 @@ L1 gives no temperatures on its own (unless the D3DKMT probe pans out). That is
|
||||
|
||||
`LibreHardwareMonitorLib` ≥ 0.9.6, consumed as an **unmodified NuGet package**. It already implements per-vendor GPU sensor access internally — which means the vendor-interop licensing problem is one LHM has solved upstream, under a licence that works for us. That is the entire reason this layer exists.
|
||||
|
||||
- `Computer` opened with `IsGpuEnabled` always; `IsCpuEnabled` + `IsMemoryEnabled` only when the Agent is elevated and PawnIO is available.
|
||||
- `Computer` opened with `IsGpuEnabled` always; ~~`IsCpuEnabled` + `IsMemoryEnabled` only when the Agent is elevated and PawnIO is available~~ nothing else, ever — the CPU temperature uses a separate `Computer` (below) (corrected 2026-10-04).
|
||||
- Poll on a dedicated thread: `computer.Accept(updateVisitor)` then read mapped sensors. Never faster than 500 ms; default 1000 ms.
|
||||
- Sensor mapping by `SensorType` + name heuristics per vendor (`GPU Core`, `GPU Hot Spot`, `GPU Memory`, `GPU Package Power`, …), kept in `SensorMap.cs` with unit tests against captured sensor-tree fixtures.
|
||||
- **P0 verification items:** (a) which fields LHM actually returns per vendor on real hardware — fill the capability matrix below — **NVIDIA filled 2026-09-03, AMD/Intel deferred (§R5/§R6)**; (b) ~~whether GPU-only usage works **without** elevation and without PawnIO (expected yes, since GPU sensors go through user-mode vendor paths, but confirm — it determines whether the default unelevated Agent has temperatures at all)~~ — **confirmed 2026-09-03, §M5 row R1**: eight fields unelevated, the same eight elevated, PawnIO never opened; (c) ~~confirm LHM's sources are not marked with MPL-2.0 Exhibit B~~ — **done, 2026-08-02: clear.** No source file applies the notice; the only repository hit is the `LICENSE` template itself, and every file we depend on carries the permissive Exhibit A. Method and evidence in `docs/spike-notes.md` §0. Re-check on every version bump, and check *source headers*, never the LICENSE file — MPL-2.0's own text contains Exhibit B as a template, so grepping the licence finds it in every MPL project ever published.
|
||||
@@ -146,7 +150,7 @@ CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, an
|
||||
> attribution above mean nothing for "how busy was the CPU". Two unprivileged Win32 calls, no process opened:
|
||||
> `GetSystemTimes` (busy = (kernel + user) − idle over the interval; kernel INCLUDES idle in that API; the first tick has
|
||||
> no interval and is null) and `GlobalMemoryStatusEx` (physical memory in use). **CPU temperature is the one privileged
|
||||
> reading**: `LhmCpuTemperatureReader.TryOpen` opens a SEPARATE `Computer` (CPU group only — L2's stays GPU-only and
|
||||
> reading**: `LhmCpuTemperatureReader.TryOpen` opens a SEPARATE `Computer` (~~CPU group only~~ CPU and memory groups, GPU off — corrected 2026-10-04 — L2's stays GPU-only and
|
||||
> unelevated by design, so the unprivileged layer's behaviour never depends on privilege) only when the process is
|
||||
> elevated AND `PawnIo.IsInstalled`; it takes the package sensor (`CPU Package`, `Core (Tctl/Tdie)`) and falls back to the
|
||||
> hottest core. **Unmeasured on real hardware**: exercised against a fake `ILhmComputer` only; the first elevated run
|
||||
|
||||
@@ -217,8 +217,10 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> `NtQuerySystemInformation` is a documented-as-unsupported API and its
|
||||
> `RTL_PROCESS_MODULE_INFORMATION` layout is version-sensitive; the struct
|
||||
> offsets must be asserted, not assumed. Treat a parse failure as *refuse*,
|
||||
> never as *clean*. `20_OPEN_QUESTIONS` §S7 tracks the remaining work.
|
||||
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, updatable independently of app releases (`05_DETECTION` §Rules updates).
|
||||
> never as *clean*. ~~`20_OPEN_QUESTIONS` §S7 tracks the remaining work.~~ *(Corrected 2026-10-04: done —
|
||||
> `fl_guard_sources.cpp` asserts the layout and refuses a parse that yields non-native paths; §S7, closed, is about
|
||||
> handle rights and WOW64.)*
|
||||
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, ~~updatable independently of app releases (`05_DETECTION` §Rules updates)~~ shipped with each release; there is no rules-update path yet *(corrected 2026-10-04: `20_OPEN_QUESTIONS` §S20 feed half; `05_DETECTION` §Trust and staleness of the rules feed)*.
|
||||
|
||||
> **Both halves are wired and seeded since 2026-09-25** (owner: "as many and as strict as possible"; rules
|
||||
> `2026.09.4`). The block below is the history it replaces, kept for the reasoning.
|
||||
@@ -316,7 +318,7 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> nothing produced either.
|
||||
>
|
||||
> **It runs inside the chokepoint**, as the last of the four checks in
|
||||
> `EvaluateImpl`. `FlStaticPreScan` also exports it for FR-2.2's pre-launch
|
||||
> `EvaluateImpl`. ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` (since 2026-09-25 — corrected 2026-10-04) also exports it for FR-2.2's pre-launch
|
||||
> question, but that export is **advisory**: it gates nothing, and a caller who
|
||||
> never asks it — or ignores the answer — changes nothing about what injection
|
||||
> allows.
|
||||
@@ -325,9 +327,11 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> could. Since 2026-08-04 `FrameLedger.Guard.dll` ships beside the **Agent
|
||||
> only** (`FrameLedger.Guard.targets`, §S18 blocker 3), so `FrameLedger.App`
|
||||
> has no `FlStaticPreScan` call site and no DLL to load. FR-2.2's advisory
|
||||
> answer reaches the UI through the Agent over IPC (`07_IPC`) when that exists.
|
||||
> answer reaches the UI through the Agent over IPC (`07_IPC`) ~~when that exists.
|
||||
> Recorded rather than quietly reworded: an advisory export with no consumer is
|
||||
> a claim about the product that is not true yet.
|
||||
> a claim about the product that is not true yet.~~ *(corrected 2026-10-04: it does — the Agent's
|
||||
> `SetHookEnabled` answer carries it since P3, `HookEnabledAck.Prescan`, and the library sweep's
|
||||
> `hook_prescan_state` since beta.8 is shown on the game's page)*.
|
||||
>
|
||||
> **Which directory.** The **install root**, resolved by walking up from the
|
||||
> executable to a known platform boundary (`steamapps\common\<X>` and
|
||||
@@ -351,7 +355,8 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> **What it does not cover.** Beyond the above, the residual is an anti-cheat
|
||||
> SDK sitting on disk whose service is not installed and whose module is not
|
||||
> loaded; checks 1, 2 and 2b already cover the rest. And today the `directories` + `files`
|
||||
> groups carry only three tokens between them, so "check 4 ran" is a much
|
||||
> groups carry ~~only three tokens~~ 67 tokens between them since 2026-09-25, plus any `.sys` by code *(corrected
|
||||
> 2026-10-04; documented names, not measured ones)*, so "check 4 ran" is a much
|
||||
> narrower statement than "this game ships no anti-cheat". Widening it needs
|
||||
> **verified** file and directory names — the seed table below deliberately
|
||||
> carries "no data yet" rows rather than guesses, because a wrong token fails
|
||||
@@ -502,8 +507,9 @@ says so, including that a ban can arrive days later and that FrameLedger cannot
|
||||
- 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
|
||||
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain,
|
||||
FredaikisAntiCheat and Roblox Hyperion *(Hyperion added 2026-10-04: its rows are one module and one file; its only title
|
||||
is on the executable list, so it is never excepted in practice)*; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
|
||||
other family carry a driver or a service and are never excepted;
|
||||
- no `*.sys` anywhere in the install tree — the kernel-driver rule (D30) is never excepted, whichever family a driver
|
||||
belongs to (so *Aniimo*, which unpacks `NEPKernel.sys` beside `NEP2.dll` on its first run, stays blocked);
|
||||
@@ -725,7 +731,8 @@ normative documentation. Write tokens here exactly as the data must hold them.
|
||||
|
||||
The "no data yet" rows are deliberately kept rather than deleted. An admitted
|
||||
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.
|
||||
2026-09-25 (~~below~~ above); ~~VAC's stays until its per-title route exists~~ VAC's became per-title lists the same day,
|
||||
13 Steam ids and 8 executables *(corrected 2026-10-04)*.
|
||||
|
||||
> **Expanded 2026-09-25 (owner: "as many anti-cheats and as strict as possible").** Eleven families became
|
||||
> twenty-two and 19 entries became 74: EA AntiCheat, Activision Ricochet, NetEase Anti-Cheat, NetEase Yidun, Nexon
|
||||
@@ -772,7 +779,7 @@ gap is reviewable; a deleted row is invisible. ~~Activision Ricochet's was one o
|
||||
> *every* title, which is how a user ends up hunting for the override that
|
||||
> CLAUDE.md rule 2 says does not exist.
|
||||
|
||||
The list is data, versioned in `detection-rules.json`, expandable without a release. Unknown-but-suspicious modules (filename containing one of the `nameFragments` — today `anticheat`, `antitamper`, `guard`, `protect` — plus unsigned-by-known-vendor) produce a **warn-and-refuse** with a "report this to us" link rather than silently allowing.
|
||||
The list is data, versioned in `detection-rules.json`, expandable without ~~a release~~ a code change, still delivered by a release (§S20 feed half — corrected 2026-10-04). Unknown-but-suspicious modules (filename containing one of the `nameFragments` — today `anticheat`, `antitamper`, `guard`, `protect` — plus unsigned-by-known-vendor) produce a **warn-and-refuse** with a "report this to us" link rather than silently allowing.
|
||||
|
||||
> **Three corrections to that sentence, all recorded in §S19; one is now closed.**
|
||||
> It listed four fragments while the data carried five (`gameguard` was missing
|
||||
@@ -897,7 +904,7 @@ injected or layered**.
|
||||
> stop). Modules loaded **before** the Overlay attached are the pre-injection scan's, as always. The
|
||||
> detour supplements the poll; it replaces nothing (§S6's own ruling).
|
||||
|
||||
> **This sentence used to say the hook "already exists and is currently unused", which was false.** Corrected 2026-08-04: the Overlay installs no hooks at all — `dllmain.cpp` exports one function and nothing in the tree calls `MH_CreateHook` outside a probe. §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
|
||||
> **This sentence used to say the hook "already exists and is currently unused", which was false.** Corrected 2026-08-04: the Overlay installs no hooks at all — `dllmain.cpp` exports one function and nothing in the tree calls `MH_CreateHook` outside a probe. *(Overtaken 2026-09-06: P1 installed the hooks and the `LoadLibraryExW` detour above; the Overlay exports four functions. Marked 2026-10-04.)* §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
|
||||
|
||||
### Elevated / protected targets
|
||||
|
||||
@@ -1057,20 +1064,22 @@ game's executable** (path, size or mtime). If it now matches:
|
||||
§games), so this needs no schema change, and a non-null value already means
|
||||
"toggle disabled in the UI".
|
||||
3. `hook_consent_at` is **preserved**. The user did consent; the block is not a
|
||||
withdrawal of consent and must not silently require them to consent again if
|
||||
the title is later cleared.
|
||||
withdrawal of consent and must not silently require them to consent again ~~if
|
||||
the title is later cleared~~ *(corrected 2026-10-04: nothing clears a block since D22; the stamp is kept for the
|
||||
record and for a D33 exception)*.
|
||||
4. The UI shows a persistent notice, not a transient toast — the user needs to
|
||||
understand why a game they enabled stopped being captured at Tier 1.
|
||||
|
||||
A rules update that *removes* a match does **not** re-enable hooking on its own.
|
||||
A rules update that *removes* a match does **not** re-enable hooking ~~on its own.
|
||||
Turning it back on is a user action, because re-enabling silently would mean the
|
||||
rules feed can switch injection on for a game without anyone looking.
|
||||
rules feed can switch injection on for a game without anyone looking.~~ — nothing does *(corrected 2026-10-04: the block
|
||||
outlives a rules change, a game update and *Change executable*; §What a finding does to the game)*.
|
||||
|
||||
## Crash & stability safety
|
||||
|
||||
- Two crashes of the same game within 60 s of injection ⇒ hooking auto-disabled for that game, UI explains, Tier-2 takes over. Recorded in `games.hook_autodisabled_reason`. *"Crash" here is any abnormal end: since beta.8 a session whose exit code is not an exception's (End task's 1) is `normal` on its row, and this policy still counts it inside the window — a hang our hook caused, ended by the user, is the case it exists for. The row's reason says "ended abnormally twice within 60 s of injection" (`04_CAPTURE` §Crash & exit classification).*
|
||||
- The Overlay DLL self-disables after 3 faults in hook bodies (`17_HOOK_ENGINE` §Fault policy) and reports it.
|
||||
- Every hooked session writes a breadcrumb file before injection; if the game process dies before the first frame record arrives, the next run is recorded as suspect.
|
||||
- Every hooked session writes a breadcrumb file before injection~~; if the game process dies before the first frame record arrives, the next run is recorded as suspect~~ *(corrected 2026-10-04: no "suspect" mark exists; the breadcrumb is the `.partial` file, and an early death counts toward the two-within-60-s auto-disable above)*.
|
||||
|
||||
> **"Cautious mode" is deferred to v1.1 (`20_OPEN_QUESTIONS` §S12).** It was
|
||||
> described as "hooks installed, overlay drawing disabled" — but **v1 draws no
|
||||
|
||||
+25
-20
@@ -58,7 +58,7 @@ Rules for this document:
|
||||
| — | **D3D9 is not a Tier-1 API in v1.** The Overlay is x64-only; an x64 DLL cannot load into a 32-bit process, and D3D9 titles are almost entirely 32-bit | **The consequence hardened on 2026-08-28 without a word of this row changing**, which is why it is called out: that catalogue used to be "Tier 2", meaning frame times without injection. Tier 2 now measures nothing, so those titles are **unmeasurable in v1**. The VN / JRPG / older-indie catalogue is Tier 2. Reversing this means a second 32-bit Overlay **and** injector, doubling the native build matrix and adding a second struct-mirror surface. Revisit only with evidence that users care more about those titles than about the maintenance cost |
|
||||
| — | **`ci.yml` is repo-local**, not a caller stub | The ops repo's `reusable-desktop-csharp.yml` runs `dotnet` directly with no native pre-step input, and `12_BUILD` requires CI and local to run the same script |
|
||||
| — | **No `v1 → v2` migration** | Nothing shipped, so no such database exists. `0001_init.sql` creates the current schema |
|
||||
| — | ~~**Multi-process titles are refused as `TargetAmbiguous` in v1**~~ — **the Chromium case is RESOLVED the same day (2026-09-03), by the vendor's own label** | Chromium-based runtimes — NW.js, Electron, RPG Maker MV/MZ, a large share of the VN catalogue — run several processes from ONE image path (browser, renderer, GPU), and *Flower in Us* refused as `TargetAmbiguous`. The presenting process is Chromium's GPU process, which owns no window, so "the one with the window" and "the parent" were both wrong picks. **What resolves it:** Chromium marks that process with `--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — **served by the kernel, no `ReadProcessMemory`, no PEB walk, `PROCESS_QUERY_LIMITED_INFORMATION` only**, which is the rule-4 line `HeldProcessHandle` already draws — and resolves only when **exactly one** readable candidate carries the flag as a whole argument. Two GPU processes (two instances), none, or any unreadable candidate still refuse. §S27 is untouched: consent is keyed on the path, every candidate is that path, the guard scans the pid chosen, and `--pid` stays forbidden. **Measured the same evening, and the first rule did not fire:** *Flower in Us* runs **six** processes — browser, `crashpad-handler`, three `utility`, `renderer` — and **no `--type=gpu-process` at all**. NW.js runs the GPU **in-process, in the browser**, which is the one process Chromium leaves untyped. Second rule added: exactly one untyped candidate, every other candidate typed, no GPU process ⇒ the browser is the target; two untyped candidates are two instances and refuse. The refusal line now prints the tree (`browser=1, renderer=1, utility=3, …`) so the next unknown shape is data rather than a bare `TargetAmbiguous`. **Still unmeasured:** whether the Overlay loads and sees presents inside that browser process |
|
||||
| — | ~~**Multi-process titles are refused as `TargetAmbiguous` in v1**~~ — **the Chromium case is RESOLVED the same day (2026-09-03), by the vendor's own label** | Chromium-based runtimes — NW.js, Electron, RPG Maker MV/MZ, a large share of the VN catalogue — run several processes from ONE image path (browser, renderer, GPU), and *Flower in Us* refused as `TargetAmbiguous`. The presenting process is Chromium's GPU process, which owns no window, so "the one with the window" and "the parent" were both wrong picks. **What resolves it:** Chromium marks that process with `--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — **served by the kernel, no `ReadProcessMemory`, no PEB walk, `PROCESS_QUERY_LIMITED_INFORMATION` only**, which is the rule-4 line `HeldProcessHandle` already draws — and resolves only when **exactly one** readable candidate carries the flag as a whole argument. Two GPU processes (two instances), none, or any unreadable candidate still refuse. §S27 is untouched: consent is keyed on the path, every candidate is that path, the guard scans the pid chosen, and `--pid` stays forbidden. **Measured the same evening, and the first rule did not fire:** *Flower in Us* runs **six** processes — browser, `crashpad-handler`, three `utility`, `renderer` — and **no `--type=gpu-process` at all**. NW.js runs the GPU **in-process, in the browser**, which is the one process Chromium leaves untyped. Second rule added: exactly one untyped candidate, every other candidate typed, no GPU process ⇒ the browser is the target; two untyped candidates are two instances and refuse. The refusal line now prints the tree (`browser=1, renderer=1, utility=3, …`) so the next unknown shape is data rather than a bare `TargetAmbiguous`. ~~**Still unmeasured:**~~ **Measured 2026-09-04** (`spike-notes` §9, run 3): the Overlay loads and sees presents inside that browser process — Flower in Us resolved, injected, captured, 3,587 records over three swap chains *(corrected 2026-10-04)* |
|
||||
| — | **Intel XeSS / XeFG identity is closed at the census — no hook on any `libxess*.dll` export** (decided 2026-09-04, delegated by the owner) | The XeSS SDK failed `18_GPU_VENDOR_APIS` §Checklist (Intel Simplified Software License: binary-only grant, no reverse engineering, termination; headers forbid copying), so no declaration may be vendored or re-declared. The signature-free counter that seemed to survive that — an assembly thunk on a named export — still inline-patches Intel's code inside the game process, which the same licence forbids as *modification*; it would also be the only entry outside `FL_HOOK_GUARD` and a second build language, for identity alone. An Intel title therefore reports upscaler `NOT_REPORTED` and, with `libxess_fg.dll` in the census, Presented FPS under rule 6's *"MAY include generated frames"* qualifier — honest, and the same answer NGX-direct got. **Reversal condition:** Intel relicenses the headers so the checklist clears; then §H11's AMD route applies to Intel verbatim |
|
||||
| — | **A title whose upscaler or frame generation is compiled into its executable is Presented FPS + the census's qualifier, in attach mode, and that is the ceiling for IDENTITY** (recorded 2026-09-04; **two such titles found the same night — Rune Factory, and Black Myth: Wukong for its upscaling, which ships and loads the 1.1.x monolith and never dispatches to it**) | No module for the census, no export for the inventory: nothing by name. What survives static linking is behaviour on interfaces we hook — the FSR3 frame-generation proxy swapchain at *creation* (launch mode only, §S1 deferred) and queue-side cadence with no vendor name on it. ~~**No installed title has this shape**~~ — **Rune Factory: Guardians of Azuma has it**: `amd_fidelityfx_dx12.dll` ships beside the executable and is never loaded (the census has no AMD module), FSR frame generation is on, and the report read `59.99 → 119.95 (×2 FG)`, *technology not identified* — because on a UE5 title **Streamline's frame token is requested whether or not NVIDIA's features are the ones running**, so the application-frame COUNT survives static linking even though the identity cannot. The ceiling is therefore lower than this row first said: the trio with an unidentified technology, not Presented FPS alone (§H11's run table). Identity for such a title stays out of reach by name |
|
||||
| — | ~~**Tier 2 requires an elevated Agent**~~ | **CLOSED 2026-08-28 by the two-rung ladder.** The requirement came from Windows restricting ETW trace sessions; there is no ETW rung, so **no capture tier needs elevation**. Elevation is optional everywhere and buys exactly two things (CPU temperatures via PawnIO, attaching to elevated targets — ADR-9). An unelevated Agent whose Tier-1 attempt fails lands on Tier 2, which is what every unhooked session lands on regardless of privilege |
|
||||
@@ -101,7 +101,7 @@ or it becomes the next stale status claim this file exists to record.
|
||||
| S3, S5, S7, S8, S9, S10, S11, S15, S16, S17, S18, S21, S22 | ✅ **resolved** | Thirteen. Reasoning kept in place rather than deleted |
|
||||
| **S25, S26** | ✅ **resolved 2026-08-05** | The two runtime stops unreachable in a non-presenting process; occlusion probes recorded as frames |
|
||||
| **S28** | ✅ **resolved 2026-08-05** | The guard's entry points share process-wide statics; a concurrent call cleared the blocklist mid-match and every check fell through to `Allow`. Reproduced by CI, not argued |
|
||||
| **S27** | ✅ **resolved, and restated 2026-08-06** | The chokepoint is the anti-cheat gate, not the consent gate. It was closed by *not building* a capture host; item 1 built one, and the ✅ survives on the clause that was always load-bearing — **no injecting entry point on any SHIPPED binary**. `FrameLedger.CaptureHost` is unpublished, and `tools/package-closure-check.ps1` makes that a gate rather than a fact about today's csproj. `HookRequest` is get-only behind one factory, so this entry's own rejected synthesis no longer compiles |
|
||||
| **S27** | ✅ **resolved, and restated 2026-08-06** | The chokepoint is the anti-cheat gate, not the consent gate. It was closed by *not building* a capture host; item 1 built one, and ~~the ✅ survives on the clause that was always load-bearing — **no injecting entry point on any SHIPPED binary**. `FrameLedger.CaptureHost` is unpublished, and `tools/package-closure-check.ps1` makes that a gate rather than a fact about today's csproj.~~ *(Corrected 2026-10-04: ✅ restated 2026-09-10 in the entry below — the shipped Agent injects by design, and the four properties in the entry hold rule 1; `package-closure-check` keeps its meaning for the CaptureHost only.)* `HookRequest` is get-only behind one factory, so this entry's own rejected synthesis no longer compiles |
|
||||
| S12 | 🅓 **deferred, rationale written** | Cautious mode → v1.1; it disabled nothing in v1. *(Marked ✅ until 2026-08-27 — same disposition, different glyph.)* |
|
||||
| **S1** | ◐ **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 |
|
||||
@@ -110,13 +110,13 @@ or it becomes the next stale status claim this file exists to record.
|
||||
| **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 |
|
||||
| **S4 signing** | 🅓 **deferred to P4, rationale written 2026-09-06** | Signing is a property of the feed and there is no feed (§S20); every rules file today shipped inside a release whose checksum attests it. The P4 decision (compiled-in key, detached signature, fail-closed) is written in the entry |
|
||||
| **S4 signing** | 🅓 **deferred ~~to P4~~, unscheduled — P4 closed without it (corrected 2026-10-04); rationale written 2026-09-06** | Signing is a property of the feed and there is no feed (§S20); every rules file today shipped inside a release whose checksum attests it. The P4 decision (compiled-in key, detached signature, fail-closed) is written in the entry |
|
||||
| **S6** | ✅ **built 2026-09-06 (P1 item 1)** | The detour on `kernelbase!LoadLibraryExW` stops the Overlay from inside on an exact-floor MODULE match, within one present or one watchdog iteration, and wakes the lazy installers within milliseconds for an inventoried module; measured against the real Overlay in ctest `fl_guard` `[loader]`/`[S6]`. Exact names only — fragment and signer stay the host's 30 s scan, so the disclosure does not change |
|
||||
| **S19(a)** | ✅ **resolved 2026-08-05** | `gameguard` could never fire — `guard` subsumed it. Removed; `rules-validate` now fails when any fragment contains another, so the class cannot return. Zero coverage lost: nProtect has its own named module family |
|
||||
| **S19(c)** | ✅ **resolved 2026-09-06** | The fields are constants the schema pins and the guard never reads, because the policy is code by CLAUDE.md rule 2 and `19_SAFETY`; `rules-validate` now proves the schema rejects `action: "allow"` and `signerField: "CN"` (canary 3), so the data cannot say otherwise |
|
||||
| **S19(d) residual** | ✅ **resolved 2026-08-05** | A second canary, **derived from the shipped document** rather than hand-written, carries `nameFragments: []` and must be rejected. The entry's stated consequence was overstated and is corrected in place: the generated floor would not have disappeared, `gen-ac-floor.ps1` hard-errors and the native build fails — what was unguarded is the *schema* half |
|
||||
| **S20 feed half** | 🅓 **deferred to P4, rationale written 2026-09-06** | **FR-7.3 stays unmet and written as unmet**: the fetch needs a shipped Agent, §S4's signing and the privacy policy's rows, all P4; until then a rules edit ships with the next release, checksum-attested |
|
||||
| **S23-3** | 🅓 **deferred to P3, rationale written 2026-09-06** | `08_UI`'s refusal notice is wrong in the commonest case; the requirement reaches `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI — a string with no view would read as done |
|
||||
| **S20 feed half** | 🅓 **deferred ~~to P4~~, unscheduled — P4 closed without it (corrected 2026-10-04); rationale written 2026-09-06** | **FR-7.3 stays unmet and written as unmet**: the fetch needs a shipped Agent, §S4's signing and the privacy policy's rows, all P4; until then a rules edit ships with the next release, checksum-attested |
|
||||
| **S23-3** | ~~🅓 **deferred to P3, rationale written 2026-09-06**~~ 🔴 **open: P3 shipped the refusal UI without it** *(corrected 2026-10-04: a machine-wide `BlockedService` / `BlockedDriver` notice still reads "… was detected in this game", `SafetyNotices.RefusalText`)* | `08_UI`'s refusal notice is wrong in the commonest case; the requirement reaches `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI — a string with no view would read as done |
|
||||
| **S23-5** | ✅ **resolved 2026-08-05** | Closed the way §S23-4 closed the same class — by **removing** the restatement, not correcting it — and `rules-validate` now fails when any `$comment` enumerates checks again. The rule's own first version was scoped to the wrong object and could not fire; it now walks every `$comment` and fails if it finds none |
|
||||
| **S23-6** | ✅ **closed 2026-09-06** | `license-check` binds `THIRD_PARTY_NOTICES` bidirectionally, and the accuracy blocks are now ONE text — `legal/ACCURACY.md`, embedded verbatim in `README.md` and `DISCLAIMER.md` §4, gated by `tools/accuracy-check.ps1` (self-tested both directions). Truth stays a human's job; drift between copies no longer is |
|
||||
| **S23-2** | 🚫 **owner only — no PR can close it** | `Rules / validate` is **not** a required status check on `main`. **Re-verified against the live branch protection 2026-08-05**, not repeated from the entry: `required_status_checks.contexts` is exactly `["check", "analyze (csharp, none)", "analyze (cpp, manual)"]` (`strict: true`, `enforce_admins: true`, `required_linear_history: true`). The `validate` job is path-filtered and `pull_request`-only, so a red removal check does not block the merge button. **The gate that exists to make the anti-cheat blocklist un-removable is advisory.** This is a branch-protection setting |
|
||||
@@ -1495,7 +1495,7 @@ there is no way to point the layer at a different rules file (§S3), so without
|
||||
it the test silently skipped on any machine that had not run the product — and a
|
||||
ctest that always skips is a gate that cannot fail.
|
||||
|
||||
### ◐ Part three: mid-session guard inside a layered process — decided, half built
|
||||
### ~~◐~~ ✅ Part three: mid-session guard inside a layered process — decided, ~~half built~~ built 2026-09-06 (heading corrected 2026-10-04)
|
||||
|
||||
> #### ✅ Built 2026-09-06 (P1 item 3), in the PR that added the present hook — as the deferral below said it would be
|
||||
>
|
||||
@@ -1557,7 +1557,8 @@ the layer already has — every uncertainty resolves to inert.
|
||||
> file and exits. What is built and tested is the *counting discipline*: the tick
|
||||
> counts evaluations rather than seconds. What is not built is the supervision.
|
||||
> A reader ticking this off as delivered would then find `07_IPC` §Supervision
|
||||
> loss unimplementable, which is exactly what happened.
|
||||
> loss unimplementable, which is exactly what happened. *(Overtaken in P2: `ShmRingReader` publishes the tick from
|
||||
> `GuardSupervisor`, which `CaptureSession` runs on every Tier-1 session. Marked 2026-10-04.)*
|
||||
|
||||
**✅ The Agent half's counting discipline is built and proven.** `GuardSupervisor`
|
||||
(`FrameLedger.Application`) computes what will become `guardTicks`, and the load-bearing property
|
||||
@@ -2668,19 +2669,21 @@ disproved:
|
||||
which used to claim a bump check that does not exist.
|
||||
- **`trustedSigners` is the one allow-widening field a foreign file still
|
||||
controls.** Deliberately not floored, because flooring an allowlist has the
|
||||
wrong polarity. Inert today — `IsTrustedSigner` has no production call site
|
||||
while §S19(b) is deferred — and **live the moment the signer half is wired**,
|
||||
wrong polarity. ~~Inert today — `IsTrustedSigner` has no production call site
|
||||
while §S19(b) is deferred — and~~ **live the moment the signer half is wired** *(corrected 2026-10-04: wired since
|
||||
§S19(b), 2026-09-06, and bounded by `IsCompiledTrustedSigner`)*,
|
||||
which makes gating it a prerequisite of §S19(b) rather than of this item.
|
||||
- **This is what arms the Vulkan layer's self-scan for the first time.** `layer.cpp`
|
||||
§S2's second half could only ever answer "inert" while the file never existed.
|
||||
It is now reachable, on a machine where the file is present. The layer still
|
||||
It is now reachable, on a machine where the file is present. ~~The layer still
|
||||
intercepts nothing (`vkQueuePresentKHR` is P1), so nothing observable changes
|
||||
yet — recorded here so it is not discovered as a surprise when the present hook
|
||||
lands.
|
||||
lands.~~ *(Corrected 2026-10-04: `vkQueuePresentKHR` is intercepted since 2026-09-06, §S2 part three.)*
|
||||
- **A seed replacement is a rules update in FR-2.3's sense**, and the obligation
|
||||
attached to that event — re-run the pre-scan, force-disable a game that has
|
||||
started matching — is unimplemented. There is no `games` table yet, so there is
|
||||
nothing to write; named here so whoever builds persistence has an anchor.
|
||||
started matching — ~~is unimplemented. There is no `games` table yet, so there is
|
||||
nothing to write; named here so whoever builds persistence has an anchor.~~ *(corrected 2026-10-04: built —
|
||||
`UpdateRules` wakes `AntiCheatPreScanSweep`, beta.8, keyed per rules version by schema 0010.)*
|
||||
|
||||
### S21 ✅ · The hard gate's data source was caller-nameable, and its completeness floor never read the values — **closed**
|
||||
|
||||
@@ -3080,7 +3083,7 @@ required contexts are exactly `check`, `analyze (csharp, none)` and
|
||||
the gate that exists to make the anti-cheat blocklist un-removable is advisory.
|
||||
Fixing it is a branch-protection change, i.e. the owner's, not a code change.
|
||||
|
||||
**3. 🅓 Deferred to P3, rationale written 2026-09-06 — `08_UI` describes a refusal notice that is wrong in the commonest case.** *(The requirement below must reach `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI, and not before: there is no UI to be wrong in yet, and a `.resx` string with no view is the kind of fix that reads as done. The spike log carries the measurement; this line is the reminder.)* It
|
||||
**3. ~~🅓 Deferred to P3, rationale written 2026-09-06~~ 🔴 Open — P3 built the refusal UI without it (corrected 2026-10-04: `SafetyNotices.RefusalText` formats every named refusal as "… was detected in this game", so the measured case below still reads wrong) — `08_UI` describes a refusal notice that is wrong in the commonest case.** *(The requirement below must reach `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI, and not before: there is no UI to be wrong in yet, and a `.resx` string with no view is the kind of fix that reads as done. The spike log carries the measurement; this line is the reminder.)* It
|
||||
promises "the specific signal named in plain language". Measured (`spike-notes`
|
||||
§13): while any Easy Anti-Cheat title is running, **every** target — including a
|
||||
freshly spawned, unrelated process — refuses with `BlockedService` naming
|
||||
@@ -3968,7 +3971,7 @@ make us miss the present.
|
||||
Needs a real Streamline/DLSS-G title, ideally with RTSS and the Steam overlay
|
||||
also active (`spike-notes.md` §Environment — that machine already has both).
|
||||
|
||||
### H6 · D3D12 command-list hooks count recorded, not executed, work
|
||||
### H6 ✅ · D3D12 command-list hooks count recorded, not executed, work — **answered 2026-08-20 with the RT hooks** *(marked 2026-10-04: per-present atomics drained once per present; the unit is "recorded between two presents", `03_METRICS` §RT)*
|
||||
|
||||
`DispatchRays`, `BuildRaytracingAccelerationStructure` and pipeline creation are
|
||||
recorded into command lists, possibly on many threads, possibly re-executed or
|
||||
@@ -4356,8 +4359,8 @@ 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~~ **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` |
|
||||
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open *(corrected 2026-10-04: built in P3 PR-8b — `LogonTask` behind both flags, and start-with-Windows as the HKCU Run value)*. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) ~~elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator~~ **closed 2026-09-27 (beta.10, owner decision D34): chosen** — `capture.run_elevated`, a UAC prompt at every Agent start, the logon task's Agent asking through its own prompt, and with the option off an administrator's App starts the Agent with the shell's token (`01_ARCHITECTURE` ADR-9). "How elevation is requested and persisted" is that: requested by the prompt, persisted as one settings row and never as a task's run level | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
|
||||
| **Session identity** | ~~`sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`.~~ **`sessions.session_guid` (UNIQUE) exists since 2026-09-09 (P2 PR-B), with `qpc_epoch` / `qpc_frequency` beside it.** ~~Still open: the `.partial` file format is undefined, and it is the crash-recovery artifact — PR-D's, pre-committed in HANDOFF §P2 (CRC-framed append-only chunks, the valid prefix wins)~~ **Built 2026-09-10 (P2 PR-D): `06_DATA_MODEL` §The `.partial` file, `PartialSessionFile` + `PartialRecovery`, killed at every byte in the merge gate.** ~~What stays open here is the pipe's use of the guid (P3)~~ *(built in P3 PR-1/1b: the session events and `StopSession` carry `SessionGuid` — corrected 2026-10-04)* | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
|
||||
| ~~**Settings registry**~~ | ~~The `settings` table is key/value with no key list, defaults, types, or validation — and no message for the UI to push a changed setting to the Agent.~~ **Decided 2026-09-13 (HANDOFF §P3 decision D16)**: the key list with defaults and ranges, and *no* push message — the Agent re-reads its keys at each session start. **Built the same day (P3 PR-3):** `06_DATA_MODEL` §Settings registry (12 keys), `Application.Settings.SettingsRegistry` + `RegisteredSettings` (validating writes, tolerant reads), `SettingsRecorderPolicy` resolving `capture.min_session_s` / `telemetry.interval_ms` / `retention.raw_sessions_per_game` at each session start. **Row closed** | `06_DATA_MODEL`, FR-10 |
|
||||
| **Error taxonomy** | `07_IPC` lists `CaptureError` codes; no canonical mapping to resx keys and user-facing text, though `09_I18N` requires safety strings to be reviewed as legal text | `07_IPC`, `09_I18N` |
|
||||
| ~~**Threading model**~~ | ~~Which component owns which thread, UI-thread rules, and how the 1 Hz telemetry poller, 10 Hz drain and pipe reader interact~~ **Answered 2026-09-09 (P2 PR-C): `04_CAPTURE` §Threading model** — four threads, one owner per shared object, the pipe reader named as one more producer. This row was not struck when the section was written; struck 2026-09-13. What is still unspecified is the UI thread's own rules, which is `08_UI`'s in P3 | `04_CAPTURE`, `18_GPU_VENDOR_APIS` |
|
||||
@@ -4377,7 +4380,9 @@ the guard is **item 0**, the Vulkan passthrough test is **item 1**, the two
|
||||
licence checks were run first and came back clear (`spike-notes.md` §0), and
|
||||
P0's exit criteria no longer import P2 work — the FPS-impact measurement moves
|
||||
to the end of P1, while the harness-level per-present cost (no game, no Agent,
|
||||
no drain) stays in P0. Items 5–9 below are still open.
|
||||
no drain) stays in P0. ~~Items 5–9 below are still open.~~ *(Corrected 2026-10-04: 5 and 6 are deferred, 🅓 below; 7
|
||||
is moot — `ci.yml` has gated every PR since bootstrap; 8 is history, P1 having closed; 9 stays open — no `ja` string has
|
||||
been reviewed, an owner-only item.)*
|
||||
5. **P0 item 5 asks for an AFMF decision on an RTX 5080.** AFMF is AMD driver
|
||||
-side. Reword to "validate on NVIDIA; record AFMF as untested", per the
|
||||
precedent `14_TESTING` already sets for absent hardware.
|
||||
@@ -4429,9 +4434,9 @@ no drain) stays in P0. Items 5–9 below are still open.
|
||||
|
||||
| Named where | Artifact | State |
|
||||
|---|---|---|
|
||||
| `12_BUILD:139`, `13_CI_CD:11`, `09_I18N:28`, `CLAUDE.md:66` | `tools/resx-audit` | Absent. **Honestly handled** — `build.ps1:309` skips it loudly with a reason, and no `.resx` files exist yet |
|
||||
| `12_BUILD:139`, `13_CI_CD:11`, `09_I18N:28`, `CLAUDE.md:66` | `tools/resx-audit` | ~~Absent. **Honestly handled** — `build.ps1:309` skips it loudly with a reason, and no `.resx` files exist yet~~ **✅ Built 2026-09-13 (P3 PR-2)**, a `build.ps1` step (marked 2026-10-04) |
|
||||
| `12_BUILD:136`, `13_CI_CD:11` | the managed **struct-mirror** test | ~~Absent. Nothing under `tests/` references `FlFrameRecord`.~~ **✅ Built in #47** — `ShmLayout.cs` + `ShmLayoutMirrorTests`, driven by `fl-layout-dump`'s JSON rather than a transcribed table, asserting blittability as well as offsets, and walking the field list in both directions. `build.ps1`'s gate now reads the run's `.trx` and fails when the class did not execute, so **deleting the test is red too** — it used to `Test-Path` a source file |
|
||||
| `13_CI_CD:21`, `12_BUILD:121`, `CHANGELOG:9` | `.github/workflows/release.yml` | Absent. `CHANGELOG`'s header instructs an author to write for a consumer that does not exist |
|
||||
| `13_CI_CD:21`, `12_BUILD:121`, `CHANGELOG:9` | `.github/workflows/release.yml` | ~~Absent. `CHANGELOG`'s header instructs an author to write for a consumer that does not exist~~ **✅ Built 2026-09-14 (P4 PR-5)**; it published beta.1 through beta.11 (marked 2026-10-04) |
|
||||
| `12_BUILD` §Local quality gate | gates omitted from the list | ~~**Three documents give three different counts, which is the finding.** `build.ps1` has **15** `Write-Step` calls as of 2026-08-05 (14 before this PR's `changelog-check`); `12_BUILD` lists 10; this row said 13.~~ **Corrected 2026-08-06: `build.ps1` has 17 `Write-Step` calls** (`package-closure` added two), and `12_BUILD`'s list is rewritten to 16 numbered entries — the difference is that `Invoke-Native`'s three steps run under one heading there. `13_CI_CD` no longer restates the list at all; it points at `12_BUILD`, because restating it in two places is what let one of them rot. **Nothing still derives the list from the script**, so the drift is slowed rather than stopped, and this row remains open for that reason. **And it drifted again, exactly as predicted — re-counted 2026-08-28.** `hookinventory-check` had reached `build.ps1` and never reached the list; `frametype-oracle` had reached both and then been deleted with PresentMon, so the two errors happened to cancel and the *totals* matched while the *membership* did not — the same coincidence §S24's own recount was caught by. The list is rebuilt to **17 entries against 17 `Write-Step` calls, in script order** (re-deriving the order caught a second defect: two adjacent entries had been transposed relative to the script). **The row still does not close.** Aligning by hand is what was done in 2026-08-06 and again here; it lasts until the next gate lands. The fix is a gate that reads the `Write-Step` names out of `build.ps1` and fails when the list disagrees — until it exists, re-count rather than trusting the number |
|
||||
|
||||
The struct-mirror row is the one that matters. `CLAUDE.md` §Struct mirroring
|
||||
|
||||
+9
-7
@@ -1,6 +1,6 @@
|
||||
# HANDOFF — read this first, then stop reading it
|
||||
|
||||
The one file a new session opens to pick up P0. It carries **sequencing, decisions
|
||||
The one file a new session opens to pick up ~~P0~~ work (corrected 2026-10-04). It carries **sequencing, decisions
|
||||
and traps**. It deliberately carries **no status**.
|
||||
|
||||
> ## The rule this file lives under
|
||||
@@ -43,8 +43,9 @@ with §S2's in-layer supervision. **P1 item 1 — the `LoadLibrary` detour — l
|
||||
`04_CAPTURE` §Launch mode); item 3, the Vulkan layer to `vkQueuePresentKHR` with §S2's in-layer
|
||||
supervision, landed the same day (§S2 ✅; `17_HOOK_ENGINE` §Vulkan); item 4 — compare-and-restore per
|
||||
inline patch, the native log, `wglSwapBuffers` — landed the same day too, and D3D9 is struck per §Scope.
|
||||
P1's core is done; what stays ⏳ is the feature rows `15_ROADMAP` §P1 now lists, and P2 (the Agent, the
|
||||
recorder, SQLite) is next.** The ~~three~~ ~~two~~ one P1-deferred S-item (~~S6~~, ~~S2 part three~~, and
|
||||
P1's core is done; what stays ⏳ is the feature rows `15_ROADMAP` §P1 now lists, ~~and P2 (the Agent, the
|
||||
recorder, SQLite) is next~~.** *(Corrected 2026-10-04: P2–P4 closed 2026-09-10/14/15; later work is the dated train
|
||||
sections from §0.1.0-beta.3 on.)* The ~~three~~ ~~two~~ one P1-deferred S-item (~~S6~~, ~~S2 part three~~, and
|
||||
the hand-run blast-radius script behind S29(d)) are the reminders. The text below is
|
||||
P0's history and stays as it stood.
|
||||
|
||||
@@ -1215,7 +1216,7 @@ election are **F** and **G**; the ⏳ feature rows in `17_HOOK_ENGINE` §Hook in
|
||||
their columns (`hdr_flag`, `pt_confidence`, `pso_stutter_pct`, `vram_proc*`, `latency_*`) are an
|
||||
honest NULL in P2's schema, never a 0.
|
||||
|
||||
## P4 — **START HERE** (2026-09-14: P3 is code-complete; the stack awaits the owner's merges) — **code-complete 2026-09-15 with PR-9**: every item below is struck; what follows is `15_ROADMAP` §P5 and §Owner-only
|
||||
## P4 — ~~**START HERE**~~ (2026-09-14: P3 is code-complete; ~~the stack awaits the owner's merges~~) — **code-complete 2026-09-15 with PR-9**: every item below is struck; what follows is `15_ROADMAP` §P5 and §Owner-only *(struck 2026-10-04: merged 2026-09-14/15; the live head is the newest dated train section below, and §Owner-only)*
|
||||
|
||||
P3's slices are all struck below. What is left of P3 is not code: the owner merges #154 → #155 → #156 → #158 →
|
||||
#159 → #160 → #161 → #162 → #163 → PR-9 in order (squash; after each merge the next branch is rebased
|
||||
@@ -1872,7 +1873,7 @@ deferred with a written rationale.
|
||||
way. Corrected in place.
|
||||
- **`README:14`'s RayQuery claim is not a rule-7 contradiction**, which an audit
|
||||
asserted. `03_METRICS:128` says AS-build hooking is what makes inline RayQuery
|
||||
detectable *at all*. The real contradiction is between CLAUDE.md rule 7 and
|
||||
detectable *at all* (line numbers as of 2026-08; both passages have since moved — noted 2026-10-04). The real contradiction is between CLAUDE.md rule 7 and
|
||||
`03_METRICS` — recorded as §S29(f).
|
||||
|
||||
---
|
||||
@@ -1904,8 +1905,9 @@ diagnosis*.
|
||||
flag** — and that fix did not fire, because **NW.js has no GPU process**: the GPU runs
|
||||
in-process in the browser, the one process Chromium leaves untyped. Second rule: one
|
||||
untyped candidate among typed siblings is the browser and the target. **Read the tree before
|
||||
guessing the rule** — the refusal line prints it now. Whether the Overlay can load inside
|
||||
that browser process is the next thing the title measures.
|
||||
guessing the rule** — the refusal line prints it now. ~~Whether the Overlay can load inside
|
||||
that browser process is the next thing the title measures.~~ *(Measured 2026-09-04, `spike-notes` §9 run 3: it
|
||||
loads and captures — marked 2026-10-04.)*
|
||||
- **A TITLE ASKS STREAMLINE FOR A FRAME TOKEN SEVERAL TIMES PER FRAME AND GETS A DIFFERENT
|
||||
OBJECT EACH TIME.** Cyberpunk 2077: 3 to 4.6 requests per application frame, distinct pointers,
|
||||
same index. A count keyed on the pointer reads the request rate and the `off` leg comes out
|
||||
|
||||
@@ -4,6 +4,9 @@
|
||||
measurement notes, and reviewed by the project's owner before it was published. It lists what happened on one machine;
|
||||
it promises nothing about any other.*
|
||||
|
||||
*(Not re-read for 0.1.0-beta.11 or 0.1.0-beta.12 — noted 2026-10-04. Refreshing it needs a new copy of the database and
|
||||
the owner's review; sessions since 2026-09-27, and the game-memory figures beta.12 adds, are not here.)*
|
||||
|
||||
**The machine.** Every row below was run on one PC: an NVIDIA GeForce RTX 5080 (the only graphics card), an Intel Core
|
||||
i7-14700KF, 32 GB of DDR5, Windows 11 (Insider builds 26300 → 29648) and a 2560×1440, 240 Hz monitor. **No AMD or Intel
|
||||
graphics card and no second machine has been tested**, and **no real Vulkan or OpenGL game has been measured** — every
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# FrameLedger developer documentation
|
||||
|
||||
This folder is for people who build, change or review FrameLedger. **If you only want to use it, read the
|
||||
[user guide](../guide/README.md) instead** — it is also in the app, under Help ▸ User guide.
|
||||
|
||||
## Where to start
|
||||
|
||||
| You want to… | Read |
|
||||
|---|---|
|
||||
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (D1…D46) and the traps that each cost a cycle. It carries no status on purpose |
|
||||
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
|
||||
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
|
||||
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE) |
|
||||
|
||||
**Status lives in four places, and nowhere else** — check a status claim against the code before you plan on it:
|
||||
|
||||
| Question | File |
|
||||
|---|---|
|
||||
| What is unresolved, and what does it block? | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) |
|
||||
| What was measured, on what machine? | [`spike-notes.md`](spike-notes.md) |
|
||||
| Which phase is where? | [`15_ROADMAP.md`](15_ROADMAP.md) |
|
||||
| What landed, in which release? | [`../CHANGELOG.md`](../CHANGELOG.md) |
|
||||
|
||||
What the software promises users is the accuracy block in [`../legal/ACCURACY.md`](../legal/ACCURACY.md), copied
|
||||
verbatim into the README and the Disclaimer and bound to its source by `tools/accuracy-check.ps1`.
|
||||
|
||||
## Reading order
|
||||
|
||||
1. [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) — the guard, the refusal list, what will not be built. It
|
||||
constrains everything else.
|
||||
2. [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) — processes, the injection flow, lifecycles, the ADRs.
|
||||
3. [`02_SPEC.md`](02_SPEC.md) — the FR / NFR ids used everywhere.
|
||||
4. [`03_METRICS.md`](03_METRICS.md) — the metric math; the source of truth for every number shown.
|
||||
5. [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) — the C++ hook layer inside the game.
|
||||
6. [`04_CAPTURE.md`](04_CAPTURE.md) — capture orchestration on the Agent's side.
|
||||
7. [`05_DETECTION.md`](05_DETECTION.md) — engine, upscaler, frame-generation and ray-tracing facts.
|
||||
8. [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) — layered telemetry, the game process's memory, vendor-SDK licence rules.
|
||||
9. [`06_DATA_MODEL.md`](06_DATA_MODEL.md) · [`07_IPC.md`](07_IPC.md) · [`08_UI.md`](08_UI.md) ·
|
||||
[`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md)
|
||||
10. The rest: [`09_I18N.md`](09_I18N.md), [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md),
|
||||
[`11_UPDATER.md`](11_UPDATER.md), [`12_BUILD.md`](12_BUILD.md), [`13_CI_CD.md`](13_CI_CD.md),
|
||||
[`14_TESTING.md`](14_TESTING.md), [`15_ROADMAP.md`](15_ROADMAP.md).
|
||||
|
||||
**Before you write native or capture code, read [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md):** its S-series items
|
||||
are safety items, and something listed there as unresolved should not be built the way an older document describes it.
|
||||
|
||||
## Every document, in one line
|
||||
|
||||
| Document | What it is for |
|
||||
|---|---|
|
||||
| [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) | The processes (App, Agent, Overlay, Vulkan layer), how injection flows, the architecture decisions |
|
||||
| [`02_SPEC.md`](02_SPEC.md) | Functional and non-functional requirements, by id |
|
||||
| [`03_METRICS.md`](03_METRICS.md) | How every number is computed: frame times, lows, stutter, frame generation, display mode, the game's memory, sensor statistics, the export schema |
|
||||
| [`04_CAPTURE.md`](04_CAPTURE.md) | The Agent's capture loop, the tiers, finalizing and recovery, the threading model |
|
||||
| [`05_DETECTION.md`](05_DETECTION.md) | Detecting engines, platforms and capabilities; the detection rules |
|
||||
| [`06_DATA_MODEL.md`](06_DATA_MODEL.md) | The SQLite schema, every migration, who writes what, retention |
|
||||
| [`07_IPC.md`](07_IPC.md) | The shared-memory ring between the game and the Agent, and the named pipe between the Agent and the App |
|
||||
| [`08_UI.md`](08_UI.md) | Every screen of the App, as specified and as built |
|
||||
| [`09_I18N.md`](09_I18N.md) | English / Vietnamese / Japanese strings, the glossary, the safety-string review rule |
|
||||
| [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md) | Logs in every process, the bug-report bundle, redaction |
|
||||
| [`11_UPDATER.md`](11_UPDATER.md) | Velopack updates from GitHub Releases, and when an update may apply |
|
||||
| [`12_BUILD.md`](12_BUILD.md) | The toolchain, the build, the quality gate step by step, publishing and packaging |
|
||||
| [`13_CI_CD.md`](13_CI_CD.md) | The CI and release workflows |
|
||||
| [`14_TESTING.md`](14_TESTING.md) | The test strategy, hook overhead, the hardware matrix |
|
||||
| [`15_ROADMAP.md`](15_ROADMAP.md) | The phases and where each stands |
|
||||
| [`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md) | WPF UI (lepoco) rules, theming, rendered documents, gotchas |
|
||||
| [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) | The hooks inside the game: inventory, fault policy, the ring writer, Vulkan |
|
||||
| [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) | Telemetry layers (DXGI/PDH, LibreHardwareMonitor, NVAPI), the game process's memory, licences |
|
||||
| [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) | The anti-cheat guard, what a finding does, the user-mode exception, what will never be built |
|
||||
| [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) | Every unresolved question, defect and measurement, with its status marker |
|
||||
| [`HANDOFF.md`](HANDOFF.md) | Sequencing, the owner's decisions, traps |
|
||||
| [`spike-notes.md`](spike-notes.md) | What was measured, how, on which machine, and what each result decided |
|
||||
| [`LIST_GAME_TESTED.md`](LIST_GAME_TESTED.md) | The real games FrameLedger has been run with, and what each session measured (changes need the owner's review) |
|
||||
| [`legal-drift-history.md`](legal-drift-history.md) | How the legal documents once drifted from the software, and the maintainers' notes moved out of them |
|
||||
| [`vendor-exports.json`](vendor-exports.json) | The vendor DLL exports the hooks are allowed to bind, checked by `tools/vendor-exports` |
|
||||
|
||||
## Beside this folder
|
||||
|
||||
- [`../guide/`](../guide/README.md) — the user guide (players, English).
|
||||
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
|
||||
texts, the trademark note.
|
||||
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
|
||||
- [`../rules/detection-rules.json`](../rules/detection-rules.json) — engine, platform and capability signatures and the
|
||||
anti-cheat blocklist, validated by `tools/rules-validate.ps1`.
|
||||
@@ -1,13 +1,14 @@
|
||||
{
|
||||
"$comment": [
|
||||
"Rules are DATA, not code (docs/05_DETECTION.md). This file ships with the",
|
||||
"app and is updatable from the repository independently of releases.",
|
||||
"app. It is NOT fetched: there is no rules feed (docs/20_OPEN_QUESTIONS.md",
|
||||
"§S20 feed half), so a change here reaches users with a release, seeded by",
|
||||
"the Agent from the copy beside it. (This comment said otherwise until",
|
||||
"2026-10-04.)",
|
||||
"",
|
||||
"The `anticheat` block is what feeds the hard gate in",
|
||||
"docs/19_SAFETY_AND_ANTICHEAT.md. Updates to it are treated as security",
|
||||
"updates: applied on the next check regardless of the user's auto-update",
|
||||
"preference for other rules. Removing an entry is a safety change and needs",
|
||||
"the same review as a security fix (docs/13_CI_CD.md §rules-publish).",
|
||||
"docs/19_SAFETY_AND_ANTICHEAT.md. Removing an entry is a safety change and",
|
||||
"needs the same review as a security fix (docs/13_CI_CD.md §rules-publish).",
|
||||
"",
|
||||
"Shape is fixed by rules/detection-rules.schema.json (JSON Schema 2020-12),",
|
||||
"which closes docs/20_OPEN_QUESTIONS.md §S5. Constraints a schema cannot",
|
||||
@@ -15,10 +16,11 @@
|
||||
"compilability, case-insensitive duplicate values — stay imperative in",
|
||||
"tools/rules-validate.ps1.",
|
||||
"",
|
||||
"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.",
|
||||
"Every family docs/19_SAFETY §Blocklist seed names is represented since",
|
||||
"2026-09-25: Valve VAC through blockedStoreIds and blockedExecutables (VAC",
|
||||
"runs inside Steam, so no file of the game's own names it), and Activision",
|
||||
"Ricochet through its driver and services from Activision's own support",
|
||||
"pages.",
|
||||
"",
|
||||
"PRE-INJECTION CHECK 3 MATCHED NOTHING until 2026-09-25, because",
|
||||
"`blockedExecutables` and `blockedStoreIds` were both empty. The owner seeded",
|
||||
|
||||
@@ -9,7 +9,8 @@ namespace FrameLedger.App.Controls;
|
||||
|
||||
/// <summary>
|
||||
/// <c>08_UI</c> §Tri-state feature chips: Yes = filled accent, No = outlined, N/A = dashed outline with muted text;
|
||||
/// the source (measured / manual / inherited) is the tooltip. The override flyout (FR-8.3) is PR-6's.
|
||||
/// the source (measured / manual / inherited) is the tooltip. A click opens FR-8.3's override dialog
|
||||
/// (<c>TriStateOverridePrompt</c>); this said a flyout, which was never built.
|
||||
/// </summary>
|
||||
public sealed class TriStateChip : Control
|
||||
{
|
||||
|
||||
@@ -206,15 +206,9 @@
|
||||
SpinButtonPlacementMode="Inline"
|
||||
Value="{Binding ViewModel.RetentionRawSessions, Mode=TwoWay}" />
|
||||
</ui:CardControl>
|
||||
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon Eye24}">
|
||||
<ui:CardControl.Header>
|
||||
<StackPanel>
|
||||
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Background_Label}" />
|
||||
<ui:TextBlock MaxWidth="560" HorizontalAlignment="Left" Appearance="Secondary" Text="{x:Static res:Strings.Settings_Background_Body}" TextWrapping="Wrap" />
|
||||
</StackPanel>
|
||||
</ui:CardControl.Header>
|
||||
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_Background_Label}" IsChecked="{Binding ViewModel.BackgroundCapture, Mode=TwoWay}" />
|
||||
</ui:CardControl>
|
||||
<!-- beta.12: "Record games launched outside FrameLedger" stood here; nothing read it (capture.background,
|
||||
06_DATA_MODEL §Settings registry), and with no way to start a game from the App "off" could only have
|
||||
meant recording nothing. Removed until a launch path exists. -->
|
||||
|
||||
<!-- beta.11 (owner request 2026-10-03: no row without a control): Data - Delete all sessions (D40). -->
|
||||
<ui:TextBlock FontTypography="Subtitle" Margin="0,20,0,8" Text="{x:Static res:Strings.Settings_Data_Header}" />
|
||||
|
||||
@@ -69,22 +69,48 @@ public sealed class LogTail
|
||||
return [.. result];
|
||||
}
|
||||
|
||||
/// <summary>The three-letter level of a line under the template <c>[HH:mm:ss.fff LVL]</c>, or null for a continuation line.</summary>
|
||||
/// <summary>
|
||||
/// The three-letter level of a line, or null for a continuation line. Two templates: the App's
|
||||
/// <c>[HH:mm:ss.fff LVL] …</c>, and the Agent's — Serilog's default, <c>yyyy-MM-dd HH:mm:ss.fff zzz [LVL] …</c>.
|
||||
/// Until 2026-10-04 only the first was read, so the Warning and Error filters showed no Agent line at all.
|
||||
/// </summary>
|
||||
public static string? LevelOf(string line)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(line);
|
||||
if (line.Length < 18 || line[0] != '[')
|
||||
if (line.Length >= 18 && line[0] == '[')
|
||||
{
|
||||
return null;
|
||||
int close = line.IndexOf(']', StringComparison.Ordinal);
|
||||
return close >= 5 ? Known(line[(close - 3)..close]) : null;
|
||||
}
|
||||
|
||||
int close = line.IndexOf(']', StringComparison.Ordinal);
|
||||
if (close < 5)
|
||||
// Serilog's default: "2026-10-04 09:15:02.123 +07:00 [WRN] …" — the timestamp's own shape, then the zone, then the
|
||||
// level in brackets. Anything else that merely starts with a date is not a level line.
|
||||
if (line.Length >= 30 && IsTimestamp(line))
|
||||
{
|
||||
return null;
|
||||
int open = line.IndexOf(" [", 23, StringComparison.Ordinal);
|
||||
if (open is >= 23 and <= 32 && open + 6 <= line.Length && line[open + 5] == ']')
|
||||
{
|
||||
return Known(line.Substring(open + 2, 3));
|
||||
}
|
||||
}
|
||||
|
||||
string level = line[(close - 3)..close];
|
||||
return level is "VRB" or "DBG" or "INF" or "WRN" or "ERR" or "FTL" ? level : null;
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary><c>yyyy-MM-dd HH:mm:ss.fff</c> at the start of the line.</summary>
|
||||
private static bool IsTimestamp(string line)
|
||||
{
|
||||
const string shape = "dddd-dd-dd dd:dd:dd.ddd";
|
||||
for (int i = 0; i < shape.Length; i++)
|
||||
{
|
||||
if (shape[i] == 'd' ? !char.IsAsciiDigit(line[i]) : line[i] != shape[i])
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static string? Known(string level) => level is "VRB" or "DBG" or "INF" or "WRN" or "ERR" or "FTL" ? level : null;
|
||||
}
|
||||
Generated
-6
@@ -748,8 +748,6 @@ public static class Strings
|
||||
nameof(Settings_Applied),
|
||||
nameof(Settings_AutoCheck_Body),
|
||||
nameof(Settings_AutoCheck_Label),
|
||||
nameof(Settings_Background_Body),
|
||||
nameof(Settings_Background_Label),
|
||||
nameof(Settings_Capture_Header),
|
||||
nameof(Settings_Channel_Beta),
|
||||
nameof(Settings_Channel_Stable),
|
||||
@@ -2422,10 +2420,6 @@ public static class Strings
|
||||
|
||||
public static string Settings_AutoCheck_Label => ResourceManager.GetString(nameof(Settings_AutoCheck_Label), Culture) ?? nameof(Settings_AutoCheck_Label);
|
||||
|
||||
public static string Settings_Background_Body => ResourceManager.GetString(nameof(Settings_Background_Body), Culture) ?? nameof(Settings_Background_Body);
|
||||
|
||||
public static string Settings_Background_Label => ResourceManager.GetString(nameof(Settings_Background_Label), Culture) ?? nameof(Settings_Background_Label);
|
||||
|
||||
public static string Settings_Capture_Header => ResourceManager.GetString(nameof(Settings_Capture_Header), Culture) ?? nameof(Settings_Capture_Header);
|
||||
|
||||
public static string Settings_Channel_Beta => ResourceManager.GetString(nameof(Settings_Channel_Beta), Culture) ?? nameof(Settings_Channel_Beta);
|
||||
|
||||
@@ -1913,14 +1913,6 @@
|
||||
<value>適用しました。キャプチャエージェントは次回のセッション開始時に読み込みます。</value>
|
||||
<comment>review</comment>
|
||||
</data>
|
||||
<data name="Settings_Background_Body" xml:space="preserve">
|
||||
<value>キャプチャエージェントは追跡中のゲームを監視します。自身が起動していないゲームも記録され、フックが有効で Vulkan タイトルでない場合のみ実測されます。</value>
|
||||
<comment>review</comment>
|
||||
</data>
|
||||
<data name="Settings_Background_Label" xml:space="preserve">
|
||||
<value>FrameLedger 外から起動したゲームを記録</value>
|
||||
<comment>review</comment>
|
||||
</data>
|
||||
<data name="Settings_Capture_Header" xml:space="preserve">
|
||||
<value>キャプチャ</value>
|
||||
<comment>review</comment>
|
||||
|
||||
@@ -1440,12 +1440,6 @@
|
||||
<data name="Settings_Applied" xml:space="preserve">
|
||||
<value>Applied. The capture agent reads it at the next session start.</value>
|
||||
</data>
|
||||
<data name="Settings_Background_Body" xml:space="preserve">
|
||||
<value>The capture agent watches for tracked games; a game it did not launch is recorded, and measured only if hooking is on for it and it is not a Vulkan title.</value>
|
||||
</data>
|
||||
<data name="Settings_Background_Label" xml:space="preserve">
|
||||
<value>Record games launched outside FrameLedger</value>
|
||||
</data>
|
||||
<data name="Settings_Capture_Header" xml:space="preserve">
|
||||
<value>Capture</value>
|
||||
</data>
|
||||
|
||||
@@ -1435,12 +1435,6 @@
|
||||
<data name="Settings_Applied" xml:space="preserve">
|
||||
<value>Đã áp dụng. Capture agent đọc ở lần bắt đầu phiên kế tiếp.</value>
|
||||
</data>
|
||||
<data name="Settings_Background_Body" xml:space="preserve">
|
||||
<value>Capture agent theo dõi các game đã thêm; game không do nó khởi chạy vẫn được ghi, và chỉ đo nếu game đó bật hooking và không phải game Vulkan.</value>
|
||||
</data>
|
||||
<data name="Settings_Background_Label" xml:space="preserve">
|
||||
<value>Ghi game khởi chạy ngoài FrameLedger</value>
|
||||
</data>
|
||||
<data name="Settings_Capture_Header" xml:space="preserve">
|
||||
<value>Thu thập</value>
|
||||
</data>
|
||||
|
||||
@@ -12,7 +12,8 @@ namespace FrameLedger.App.ViewModels;
|
||||
/// <summary>
|
||||
/// The Dashboard's live capture card (<c>08_UI</c> §Dashboard), fed by <c>SessionStarted</c> / <c>SessionProgress</c> /
|
||||
/// <c>SessionHeld</c> / <c>SessionCompleted</c>. Tier 1 shows measured settings as facts; the readout follows the FPS
|
||||
/// display rule at 1 Hz, qualifier included. The sparkline is PR-6's.
|
||||
/// display rule at 1 Hz, qualifier included, and since beta.12 the game's own memory. There is no sparkline: this said it
|
||||
/// was PR-6's, and PR-6 shipped without one (<c>08_UI</c> §Dashboard).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <b>A session that is not measured is shown too (2026-09-23).</b> Its name, its tier, how long it has run, the machine's
|
||||
|
||||
@@ -79,9 +79,6 @@ public sealed partial class SettingsViewModel : ObservableObject
|
||||
[ObservableProperty]
|
||||
private int _retentionRawSessions;
|
||||
|
||||
[ObservableProperty]
|
||||
private bool _backgroundCapture;
|
||||
|
||||
[ObservableProperty]
|
||||
private bool _startWithWindows;
|
||||
|
||||
@@ -359,8 +356,6 @@ public sealed partial class SettingsViewModel : ObservableObject
|
||||
|
||||
partial void OnRetentionRawSessionsChanged(int oldValue, int newValue) => PersistNumber(SettingsRegistry.RetentionRawSessionsPerGame, Strings.Settings_Retention_Label, oldValue, newValue, v => RetentionRawSessions = v);
|
||||
|
||||
partial void OnBackgroundCaptureChanged(bool value) => Persist(SettingsRegistry.CaptureBackground, value);
|
||||
|
||||
partial void OnHideAntiCheatHookingChanged(bool value) => Persist(SettingsRegistry.UiHideAntiCheatHooking, value);
|
||||
|
||||
/// <summary>D33: the option is one settings row the Agent reads at every session start and command; the list follows it.</summary>
|
||||
@@ -497,7 +492,6 @@ public sealed partial class SettingsViewModel : ObservableObject
|
||||
MinSessionSeconds = await _settings.GetIntegerAsync(SettingsRegistry.CaptureMinSessionSeconds).ConfigureAwait(true);
|
||||
TelemetryIntervalMs = await _settings.GetIntegerAsync(SettingsRegistry.TelemetryIntervalMs).ConfigureAwait(true);
|
||||
RetentionRawSessions = await _settings.GetIntegerAsync(SettingsRegistry.RetentionRawSessionsPerGame).ConfigureAwait(true);
|
||||
BackgroundCapture = await _settings.GetBooleanAsync(SettingsRegistry.CaptureBackground).ConfigureAwait(true);
|
||||
MinimizeToTray = await _settings.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true);
|
||||
HideAntiCheatHooking = await _settings.GetBooleanAsync(SettingsRegistry.UiHideAntiCheatHooking).ConfigureAwait(true);
|
||||
UserModeExceptions = await _settings.GetBooleanAsync(SettingsRegistry.HookingUserModeExceptions).ConfigureAwait(true);
|
||||
|
||||
@@ -274,6 +274,10 @@ public sealed class SessionFinalizer
|
||||
private SensorBlob Blob(string series, IReadOnlyList<TelemetrySample> sensors, Func<TelemetrySample, float> value) => new()
|
||||
{
|
||||
Series = series,
|
||||
|
||||
// Nominal: the poller ticks once a second by default (TelemetryPollerOptions). The t_ms series stored beside every
|
||||
// series carries each tick's real time, and that is what the App draws against; Hz is only its fallback for a row
|
||||
// written without t_ms (06_DATA_MODEL §sensor_blobs).
|
||||
Hz = 1,
|
||||
Codec = _codec.Tag,
|
||||
Data = _codec.EncodeFloat32([.. sensors.Select(value)]),
|
||||
|
||||
@@ -78,13 +78,19 @@ public static class SettingsRegistry
|
||||
Choices = ["grid", "list"],
|
||||
};
|
||||
|
||||
/// <summary>Whether the Agent's watcher records tracked games that the App did not launch (FR-3.1/FR-3.3).</summary>
|
||||
/// <summary>
|
||||
/// Whether the Agent's watcher records tracked games that the App did not launch (FR-3.1/FR-3.3). <b>Reserved since
|
||||
/// beta.12:</b> the App showed a switch for it ("Record games launched outside FrameLedger") and no Agent code ever read
|
||||
/// it, so turning it off recorded every game anyway; and the App has no way to start a game, so "off" could only have
|
||||
/// meant recording nothing. The switch is gone and the key stays, read by nobody, until a launch path exists
|
||||
/// (<c>06_DATA_MODEL</c> §Settings registry).
|
||||
/// </summary>
|
||||
public static readonly SettingDefinition CaptureBackground = new()
|
||||
{
|
||||
Key = "capture.background",
|
||||
Kind = SettingKind.Boolean,
|
||||
Default = "1",
|
||||
AgentReads = true,
|
||||
AgentReads = false,
|
||||
};
|
||||
|
||||
/// <summary>FR-2.4. The one key that existed before the registry (P2 PR-F, <c>SettingsKillSwitch</c>): exactly "1" is engaged.</summary>
|
||||
|
||||
@@ -9,9 +9,12 @@ using FrameLedger.Domain.Sessions;
|
||||
namespace FrameLedger.Infrastructure.Persistence;
|
||||
|
||||
/// <summary>
|
||||
/// The <c>sessions</c> row's column map, GENERATED from one table so the INSERT, the parameter bag and the
|
||||
/// reader cannot drift from each other. Regenerate with <c>gen_session_repo.py</c> (in the PR that adds a
|
||||
/// column) rather than editing by hand; the chunking is the analyzer's 60-line method limit, nothing more.
|
||||
/// The <c>sessions</c> row's column map: the INSERT, the parameter bag and the reader, side by side so they cannot drift
|
||||
/// from each other unnoticed. It was first generated from one table by a script that was never committed — the
|
||||
/// <c>gen_session_repo.py</c> this comment named until 2026-10-04 is not in the repository — and has been edited by hand
|
||||
/// since (schema 0018 added <c>Parameters5</c> / <c>Read5</c>). What keeps the three in step is
|
||||
/// <c>SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn</c>, which writes a row with every column set and
|
||||
/// reads it back. The chunking is the analyzer's 60-line method limit, nothing more.
|
||||
/// </summary>
|
||||
internal static class SessionRowColumns
|
||||
{
|
||||
|
||||
@@ -129,8 +129,9 @@ public sealed record HelloRequest(string AppVersion, int Protocol);
|
||||
|
||||
/// <summary>
|
||||
/// <c>HelloAck</c>: what this Agent is. <c>etwAvailable</c> from the original table is gone with the ETW tier
|
||||
/// (2026-08-28); <c>VulkanLayerRegistered</c> is false by construction today — the layer is handed to a launched
|
||||
/// process through <c>VK_ADD_IMPLICIT_LAYER_PATH</c>, never registered machine-wide (P1 item 3).
|
||||
/// (2026-08-28). <c>VulkanLayerRegistered</c> is the HKCU implicit-layer registration as the Agent found it at start
|
||||
/// (P3 PR-8b, <c>AgentIdentityFactory</c>), true while <c>VkLayerReconciler</c> keeps the layer registered for a
|
||||
/// hook-enabled Vulkan game (P4 PR-2) — it said "false by construction" until 2026-10-04.
|
||||
/// <c>DisclosureVersion</c> (P3 PR-4, D14) is the FR-2.1 text this Agent stamps against; the App refuses to open
|
||||
/// the consent dialog when it differs from its own <c>SafetyDisclosure.Version</c>. <c>ExceptionDisclosureVersion</c>
|
||||
/// (D33) is the same rule for the user-mode exception's disclosure (<c>AntiCheatExceptionDisclosure.Version</c>).
|
||||
|
||||
@@ -25,7 +25,7 @@ public sealed class LogTailTests : IDisposable
|
||||
|
||||
Write("ui-20260901.log", "[00:00:00.000 INF] old\n", DateTime.UtcNow.AddDays(-2));
|
||||
Write("ui-20260914.log", "[00:00:00.000 INF] new\n", DateTime.UtcNow);
|
||||
Write("agent-20260914.log", "[00:00:00.000 INF] agent\n", DateTime.UtcNow);
|
||||
Write("agent-20260914.log", "2026-09-14 00:00:00.000 +07:00 [INF] agent\n", DateTime.UtcNow);
|
||||
|
||||
Path.GetFileName(tail.NewestFile(LogSource.Ui)).Should().Be("ui-20260914.log");
|
||||
Path.GetFileName(tail.NewestFile(LogSource.Agent)).Should().Be("agent-20260914.log");
|
||||
@@ -74,6 +74,32 @@ public sealed class LogTailTests : IDisposable
|
||||
LogTail.LevelOf("[12:00:00.000 INF] x").Should().Be("INF");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The Agent writes Serilog's default template — a date, then the level in brackets — and until 2026-10-04 the filter
|
||||
/// read only the App's, so Warning and above showed no Agent line at all (this class's fake agent log was written in
|
||||
/// the App's template, which is how that went unseen).
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void TheAgentsTemplateIsReadToo()
|
||||
{
|
||||
string[] agent =
|
||||
[
|
||||
"2026-10-04 09:15:02.123 +07:00 [INF] watcher: started",
|
||||
"2026-10-04 09:15:03.456 +07:00 [WRN] guard: refused Game.exe",
|
||||
"System.InvalidOperationException: boom",
|
||||
" at Some.Stack()",
|
||||
"2026-10-04 09:15:04.789 -05:00 [ERR] recorder: finalize failed",
|
||||
"2026-10-04 is not a log line [WRN]",
|
||||
];
|
||||
|
||||
LogTail.LevelOf(agent[0]).Should().Be("INF");
|
||||
LogTail.LevelOf(agent[1]).Should().Be("WRN");
|
||||
LogTail.LevelOf(agent[2]).Should().BeNull();
|
||||
LogTail.LevelOf(agent[5]).Should().BeNull("a bracket that is not the level's place is not a level");
|
||||
LogTail.Filter(agent, LogLevelFilter.WarningAndAbove, null).Should().Equal(agent[1], agent[4]);
|
||||
LogTail.Filter(agent, LogLevelFilter.ErrorAndAbove, null).Should().Equal(agent[4]);
|
||||
}
|
||||
|
||||
private void Write(string name, string text, DateTime mtimeUtc)
|
||||
{
|
||||
string path = Path.Combine(_dir, name);
|
||||
|
||||
@@ -222,7 +222,6 @@ public sealed class SettingsViewModelTests
|
||||
h.Vm.MinSessionSeconds.Should().Be(30);
|
||||
h.Vm.TelemetryIntervalMs.Should().Be(1000);
|
||||
h.Vm.RetentionRawSessions.Should().Be(20);
|
||||
h.Vm.BackgroundCapture.Should().BeTrue();
|
||||
h.Vm.UpdateChannel.Should().Be("stable");
|
||||
h.Vm.LogDebug.Should().BeFalse();
|
||||
h.Vm.KillSwitchState.Should().Be(Strings.Settings_KillSwitch_Off);
|
||||
|
||||
@@ -54,7 +54,8 @@ public sealed class SettingsRegistryTests
|
||||
string[] agent = [.. SettingsRegistry.All.Where(static d => d.AgentReads).Select(static d => d.Key)];
|
||||
// hooking.usermode_ac_exceptions joined on 2026-09-26 (D33): the user-mode exception's option, off by default.
|
||||
// capture.run_elevated joined on 2026-09-27 (D34): the admin mode, read before the Agent exists.
|
||||
agent.Should().BeEquivalentTo(["capture.background", "hooking.kill_switch", "hooking.usermode_ac_exceptions", "capture.run_elevated",
|
||||
// capture.background left in beta.12: it was listed here and no Agent code ever read it; the key is reserved.
|
||||
agent.Should().BeEquivalentTo(["hooking.kill_switch", "hooking.usermode_ac_exceptions", "capture.run_elevated",
|
||||
"capture.min_session_s", "telemetry.interval_ms", "retention.raw_sessions_per_game"]);
|
||||
agent.Should().OnlyContain(static k => k.StartsWith("hooking.", StringComparison.Ordinal) || k.StartsWith("capture.", StringComparison.Ordinal)
|
||||
|| k.StartsWith("telemetry.", StringComparison.Ordinal) || k.StartsWith("retention.", StringComparison.Ordinal));
|
||||
|
||||
@@ -44,8 +44,8 @@
|
||||
|
||||
TWO INVOCATIONS, AND BOTH ARE WIRED IN build.ps1.
|
||||
|
||||
-SelfTest exercises the LOGIC against temp fixtures, five cases of which two
|
||||
must come back RED. The live pass (no switch, the DEFAULT parameter set)
|
||||
-SelfTest exercises the LOGIC against temp fixtures, five cases of which four
|
||||
must come back RED (corrected 2026-10-04: this said two). The live pass (no switch, the DEFAULT parameter set)
|
||||
resolves this repository. Running only the self-test would be a gate that
|
||||
never looks at the repository — the exact defect it exists to prevent, and
|
||||
the shape tools/changelog-check.ps1 has for a reason that does not apply
|
||||
|
||||
Reference in new issue
Block a user