Compare commits
188
Commits
No files matched your search
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"version": 1,
|
||||
"isRoot": true,
|
||||
"tools": {
|
||||
"dotnet-sonarscanner": {
|
||||
"version": "12.0.0",
|
||||
"commands": [
|
||||
"dotnet-sonarscanner"
|
||||
],
|
||||
"rollForward": false
|
||||
}
|
||||
}
|
||||
}
|
||||
+257
@@ -59,6 +59,102 @@ dotnet_diagnostic.MA0011.severity = warning
|
||||
# and GenerateDocumentationFile is on for the shipping ones.
|
||||
dotnet_diagnostic.CS1591.severity = suggestion
|
||||
|
||||
# --- ReSharper inspections: what Qodana reads (docs/13_CI_CD.md §Qodana, D93 and D100) ---
|
||||
# Qodana's linters run ReSharper's engine - Qodana for .NET since 2026-11-11, the Community linter before it - and the
|
||||
# engine reads these keys; so does Rider or ReSharper in the editor, which is why they are here and not in
|
||||
# qodana.yaml: the same list everywhere. An inspection is off only where it argues with a choice this project made;
|
||||
# each line says which. Everything else it reports is fixed. (What is NOT ReSharper's - a whole severity, the
|
||||
# IntelliJ platform's Markdown and XML inspections, JetBrains' security rules - has no key here and is in qodana.yaml.)
|
||||
[*.{cs,xaml}]
|
||||
# The compiler's missing-XML-comment warning, already a suggestion above (CS1591): InspectCode reports suggestions.
|
||||
resharper_c_sharp_warnings_cs1591_highlighting = none
|
||||
# Naming is this file's rule and the .NET analyzers'. ReSharper's own scheme would rename product names and units
|
||||
# (OpenGL -> OpenGl, XeSS -> XeSs, Presents5s -> Presents5S) and every Chart_* resource key.
|
||||
resharper_inconsistent_naming_highlighting = none
|
||||
# `x is long v` / `x is > 0 and int v` is how this code unwraps a nullable AND names its type; `{ } v` or `var v`
|
||||
# hides it, against csharp_style_var_for_built_in_types above.
|
||||
resharper_convert_type_check_pattern_to_null_check_highlighting = none
|
||||
resharper_pattern_always_matches_highlighting = none
|
||||
# A code-behind class names its base so that the type reads whole without the half XAML generates.
|
||||
resharper_redundant_extends_list_entry_highlighting = none
|
||||
# An argument that repeats a default says which value the call relies on.
|
||||
resharper_redundant_argument_default_value_highlighting = none
|
||||
# `partial void OnXChanged(T value)`: the signature is CommunityToolkit.Mvvm's generator's, used or not.
|
||||
resharper_unused_parameter_in_partial_method_highlighting = none
|
||||
# Exception messages and log lines are English by design (docs/09_I18N.md); what a user reads comes from .resx,
|
||||
# and tools/resx-audit.ps1 gates that.
|
||||
resharper_localizable_element_highlighting = none
|
||||
# WPF UI's styles (DefaultImageStyle ...) arrive with ui:ControlsDictionary at run time, from a package's compiled
|
||||
# resources the inspection does not read. A key that does not exist fails PagesLoadTests.
|
||||
resharper_xaml_static_resource_not_resolved_highlighting = none
|
||||
# Proposals, not findings - ReSharper's suggestions for a style this project did not take. Its style is this file,
|
||||
# `dotnet format` and the analyzers the build treats as errors.
|
||||
resharper_convert_to_primary_constructor_highlighting = none
|
||||
resharper_merge_into_pattern_highlighting = none
|
||||
resharper_merge_conditional_expression_highlighting = none
|
||||
resharper_use_object_or_collection_initializer_highlighting = none
|
||||
resharper_use_utf8_string_literal_highlighting = none
|
||||
resharper_redundant_explicit_params_array_creation_highlighting = none
|
||||
resharper_arrange_object_creation_when_type_evident_highlighting = none
|
||||
resharper_convert_to_using_declaration_highlighting = none
|
||||
resharper_convert_closure_to_method_group_highlighting = none
|
||||
resharper_redundant_type_declaration_body_highlighting = none
|
||||
resharper_replace_with_field_keyword_highlighting = none
|
||||
resharper_replace_conditional_expression_with_null_coalescing_highlighting = none
|
||||
resharper_append_to_collection_expression_highlighting = none
|
||||
resharper_use_collection_expression_highlighting = none
|
||||
resharper_use_with_expression_to_copy_struct_highlighting = none
|
||||
resharper_convert_to_auto_property_highlighting = none
|
||||
resharper_convert_to_static_class_highlighting = none
|
||||
resharper_use_index_from_end_expression_highlighting = none
|
||||
# A notice for code moving to C# 14, which this code was written in.
|
||||
resharper_c_sharp14_overload_resolution_with_span_breaking_change_highlighting = none
|
||||
# `await using` needs ConfigureAwait(false) on the disposable under CA2007, which reads worse than the `using` it
|
||||
# replaces; the streams these name are closed synchronously on purpose.
|
||||
resharper_use_await_using_highlighting = none
|
||||
# A member's accessibility is what its type offers, not a count of today's callers.
|
||||
resharper_member_can_be_private_global_highlighting = none
|
||||
resharper_member_can_be_private_local_highlighting = none
|
||||
resharper_property_can_be_made_init_only_global_highlighting = none
|
||||
resharper_property_can_be_made_init_only_local_highlighting = none
|
||||
resharper_auto_property_can_be_made_get_only_global_highlighting = none
|
||||
resharper_auto_property_can_be_made_get_only_local_highlighting = none
|
||||
# "Never used" across the solution is not what decides for a member other code can reach: an enum's values mirror
|
||||
# the native layout and the stored columns, an exception type carries the constructors CA1032 asks for, a row or a
|
||||
# message is read by Dapper and System.Text.Json, an interface states a contract. The private kind (.Local) stays on.
|
||||
resharper_unused_member_global_highlighting = none
|
||||
resharper_unused_type_global_highlighting = none
|
||||
resharper_unused_auto_property_accessor_global_highlighting = none
|
||||
resharper_unused_member_in_super_global_highlighting = none
|
||||
resharper_unused_method_return_value_global_highlighting = none
|
||||
resharper_unused_parameter_global_highlighting = none
|
||||
resharper_class_never_instantiated_global_highlighting = none
|
||||
resharper_event_never_subscribed_to_global_highlighting = none
|
||||
|
||||
# The compiler's nullable analysis is the gate (warnings are errors). These three go further and call a guard
|
||||
# redundant because an annotation promises non-null - where a dependency property, a JSON document or a WPF event
|
||||
# hands over null all the same.
|
||||
resharper_null_coalescing_condition_is_always_not_null_according_to_api_contract_highlighting = none
|
||||
resharper_conditional_access_qualifier_is_non_nullable_according_to_api_contract_highlighting = none
|
||||
resharper_condition_is_always_true_or_false_according_to_nullable_api_contract_highlighting = none
|
||||
# A record's positional property is part of its equality and of what it prints, read by name or not.
|
||||
resharper_not_accessed_positional_property_global_highlighting = none
|
||||
resharper_not_accessed_positional_property_local_highlighting = none
|
||||
# Every one compares a value with the one it was copied from (max == r) or with an exact sentinel (scale == 1.0).
|
||||
resharper_compare_of_floats_by_equality_operator_highlighting = none
|
||||
# A nested record may name a property as the type that holds it names a helper; the compiler tells them apart.
|
||||
resharper_member_hides_static_from_outer_class_highlighting = none
|
||||
# `default: break;` is how a switch over a kind says that the rest is left alone on purpose.
|
||||
resharper_redundant_empty_switch_section_highlighting = none
|
||||
# A binding path through a null yields no value, and the template shows nothing: that is the design.
|
||||
resharper_xaml_possible_null_reference_exception_highlighting = none
|
||||
|
||||
[*.resx]
|
||||
# A vi or ja value that equals the English one is deliberate: product and technology names, units and format strings
|
||||
# are not translated, and a ja safety string is the English verbatim until a reviewer signs it (docs/09_I18N.md;
|
||||
# tools/resx-audit.ps1 holds that rule). 271 results on Qodana for .NET's first run.
|
||||
resharper_overridden_with_same_value_highlighting = none
|
||||
|
||||
[src/FrameLedger.App/**.cs]
|
||||
# WPF codegen constraints, not style choices. The generated App.g.cs and
|
||||
# *.g.cs partials declare these types public, so making them internal is a
|
||||
@@ -72,3 +168,164 @@ dotnet_diagnostic.MA0049.severity = none # type name matches containing names
|
||||
[tests/**/*.cs]
|
||||
dotnet_diagnostic.CA1707.severity = none # underscores in test method names
|
||||
dotnet_diagnostic.CA2007.severity = none
|
||||
# A test's assertion lambda runs inside the `using` scope it captures from - and reads a variable the test changes
|
||||
# on purpose - and a test's `using var x = new T { ... }` leaks nothing a test process keeps.
|
||||
resharper_access_to_disposed_closure_highlighting = none
|
||||
resharper_access_to_modified_closure_highlighting = none
|
||||
resharper_using_statement_resource_initialization_highlighting = none
|
||||
# A test that dereferences a null fails, which is what it is for.
|
||||
resharper_assign_null_to_not_null_attribute_highlighting = none
|
||||
resharper_possible_null_reference_exception_highlighting = none
|
||||
# A test double keeps the shape of what it stands for: an accessor nothing reads, a collection only filled, a result
|
||||
# only some tests look at, a value an arrange step sets before the lambda that reads it runs.
|
||||
resharper_unused_auto_property_accessor_local_highlighting = none
|
||||
resharper_collection_never_queried_local_highlighting = none
|
||||
resharper_collection_never_updated_local_highlighting = none
|
||||
resharper_unused_method_return_value_local_highlighting = none
|
||||
resharper_redundant_assignment_highlighting = none
|
||||
resharper_return_type_can_be_not_nullable_highlighting = none
|
||||
|
||||
# --- ReSharper C++ inspections: what Qodana's native report reads (docs/13_CI_CD.md §Qodana, D99 and D100) ---
|
||||
# The native report runs ReSharper's C++ engine, and with it the clang-tidy checks and clang diagnostics that engine
|
||||
# bundles (the keys that say clang_tidy). The native code is built by MSVC alone, with /W4 /WX; what clang says about
|
||||
# code it never compiles is read here as advice. An inspection is off only where it argues with a choice this project
|
||||
# made, and each line says which; everything else the report found was fixed.
|
||||
[src/native/**.{cpp,h,inl}]
|
||||
# Where the compiler pads a struct. Information, not a fault: the layouts that matter are asserted (static_assert on
|
||||
# sizes and offsets in fl_shm.h, and the mirror test against fl-layout-dump).
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_padded_highlighting = none
|
||||
# MSVC's own keywords - __try/__except (rule 5's guard around every hook body), __declspec, __stdcall. This code is
|
||||
# built by MSVC and by nothing else.
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_language_extension_token_highlighting = none
|
||||
# A function looked up by name - GetProcAddress, vkGetInstanceProcAddr, a vtable slot - comes back as a pointer to
|
||||
# another function type and is cast to its real one: that is the API. Through void* is how the cast says it is meant.
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_cast_function_type_strict_highlighting = none
|
||||
resharper_cpp_clang_tidy_bugprone_casting_through_void_highlighting = none
|
||||
# Memory read as something else - a COM object as its vtable, a relay's bytes as an address - says reinterpret_cast,
|
||||
# also where static_cast from void* would compile.
|
||||
resharper_cpp_reinterpret_cast_from_void_ptr_highlighting = none
|
||||
# It proposes std::cmp_less for a comparison whose sides differ in sign. The comparisons it found cast one side
|
||||
# explicitly, and the compiler's own sign warnings (C4018, C4388, C4389) are errors in this build.
|
||||
resharper_cpp_clang_tidy_modernize_use_integer_sign_comparison_highlighting = none
|
||||
# A `default:` under a switch that names every enumerator is deliberate: a value outside the enumeration - a corrupt
|
||||
# one, a future one - takes the refusing arm instead of falling out of the switch.
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_covered_switch_default_highlighting = none
|
||||
# "Not eliding copy on return": a verdict returned from a const local is copied. It is a few words wide.
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_nrvo_highlighting = none
|
||||
# A type that owns a handle deletes its copies or declares none; the moves are then not generated either, which is
|
||||
# what is wanted. Four more `= delete` lines would say nothing the destructor did not.
|
||||
resharper_cpp_clang_tidy_cppcoreguidelines_special_member_functions_highlighting = none
|
||||
# An enumeration zero-initialised (`D3D_FEATURE_LEVEL got{}`) is an out parameter cleared before the call that fills it.
|
||||
resharper_cpp_clang_tidy_bugprone_invalid_enum_default_initialization_highlighting = none
|
||||
# An enumeration's width is part of a layout or of the atomic word it is stored in, not a size to be minimised.
|
||||
resharper_cpp_clang_tidy_performance_enum_size_highlighting = none
|
||||
# "Possibly unused #include": a file that calls std::memset includes <cstring>, also when <windows.h> already brought
|
||||
# it in. What it reported was of that kind, or a header named again inside a conditional block, but for two that
|
||||
# nothing used; those were removed.
|
||||
resharper_cpp_unused_include_directive_highlighting = none
|
||||
# A function another file calls by a declaration of its own (the harness's Hold* functions), an entry point the
|
||||
# loader calls by name (DllMain), a placeholder a target links: "can be made static" reads one file.
|
||||
resharper_cpp_use_internal_linkage_highlighting = none
|
||||
# "Can be made const": a parameter or a method through which the code acts on a device, a ring or a handle is not
|
||||
# const because the type system would allow it; and a local that is already const gains nothing from constexpr - for a
|
||||
# std::string it would hold only while the text fits the small-string buffer.
|
||||
resharper_cpp_parameter_may_be_const_ptr_or_ref_highlighting = none
|
||||
resharper_cpp_member_function_may_be_const_highlighting = none
|
||||
resharper_cpp_variable_can_be_made_constexpr_highlighting = none
|
||||
# THE ENGINE MISREADS THESE. (1) `std::atomic_ref<T>{x}.fetch_or(bit)` is reported as an expression without side
|
||||
# effects; the side effect is the call. (2) A Win32, D3D12 or ffx-api structure is zero-initialised and then filled
|
||||
# field by field - the reserved fields must stay zero - and is handed to the API by its address or its header's: the
|
||||
# engine reports the initialiser as always rewritten and the fields as assigned and never used. (3) A test of a
|
||||
# constexpr function (`Check(F(a) == b && G(a) == c, ...)`) has the engine evaluate it and call one side redundant.
|
||||
resharper_cpp_expression_without_side_effects_highlighting = none
|
||||
resharper_cpp_initialized_value_is_always_rewritten_highlighting = none
|
||||
resharper_cpp_assigned_value_is_never_used_highlighting = none
|
||||
resharper_cpp_redundant_boolean_expression_argument_highlighting = none
|
||||
# Proposals to restate working code in a newer idiom - a range-for, std::ranges, any_of, starts_with, std::min, a raw
|
||||
# string, an if with an initialiser, emplace_back. The native code is written to be read beside the hook path: an
|
||||
# index and a plain loop, the same in the guard, its tests and the probes.
|
||||
resharper_cpp_clang_tidy_modernize_loop_convert_highlighting = none
|
||||
resharper_cpp_clang_tidy_modernize_use_ranges_highlighting = none
|
||||
resharper_cpp_use_range_algorithm_highlighting = none
|
||||
resharper_cpp_clang_tidy_readability_use_anyofallof_highlighting = none
|
||||
resharper_cpp_clang_tidy_modernize_use_starts_ends_with_highlighting = none
|
||||
resharper_cpp_clang_tidy_readability_use_std_min_max_highlighting = none
|
||||
resharper_cpp_clang_tidy_modernize_raw_string_literal_highlighting = none
|
||||
resharper_cpp_clang_tidy_modernize_use_emplace_highlighting = none
|
||||
resharper_cpp_clang_tidy_modernize_return_braced_init_list_highlighting = none
|
||||
resharper_cpp_use_associative_contains_highlighting = none
|
||||
resharper_cpp_too_wide_scope_highlighting = none
|
||||
resharper_cpp_if_can_be_replaced_by_constexpr_if_highlighting = none
|
||||
|
||||
# A structure Windows defines and this SDK's headers do not give (RTL_PROCESS_MODULE_INFORMATION,
|
||||
# PROCESS_MEMORY_COUNTERS_EX2), and a test's stand-in for a Vulkan dispatchable object, are declared field for field:
|
||||
# the fields nothing names are what puts the others at their offsets.
|
||||
[src/native/{FrameLedger.Injector/src/fl_guard_sources.cpp,FrameLedger.ProcessStats/src/fl_process_stats.cpp,tools/fl-probe-guard/main.cpp,tests/vklayer_test.cpp}]
|
||||
resharper_cpp_declarator_never_used_highlighting = none
|
||||
|
||||
# fl::patch::Install takes its hook engine as a template parameter and calls Create / Enable / Disable on it. The
|
||||
# test's two stand-in engines are used that way and no other, which ReSharper's "never used" does not follow through a
|
||||
# dependent call: six reports, one per member (Qodana, 2026-11-12). The members are the test.
|
||||
[src/native/tests/unhook_inline_test.cpp]
|
||||
resharper_cpp_declarator_never_used_highlighting = none
|
||||
|
||||
# The linter's compiler, not the build's: NVAPI's header makes NvU32 `unsigned int` under clang and `unsigned long`
|
||||
# under MSVC, which is the compiler that builds this probe - and `%lu` is right for it.
|
||||
[src/native/tools/fl-probe-nvapi/main.cpp]
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_format_highlighting = none
|
||||
|
||||
# --- the probes, the harness and the tests ---
|
||||
[src/native/{tools,tests}/**.{cpp,h}]
|
||||
# printf, fprintf, fputs, fclose: a probe prints what it found and a test prints why it failed; neither has anything
|
||||
# to do about a failed write to its own console.
|
||||
resharper_cpp_clang_tidy_cert_err33_c_highlighting = none
|
||||
# atoi on the harness's own arguments, which its tests write: a number that does not parse is 0, and the run that
|
||||
# asked for it fails on its own assertion.
|
||||
resharper_cpp_clang_tidy_bugprone_unchecked_string_to_number_conversion_highlighting = none
|
||||
# A printf-shaped helper (`Note(fmt, ...)`): the attribute clang proposes is not MSVC's, and a parameter pack would
|
||||
# be a second implementation of printf.
|
||||
resharper_cpp_clang_tidy_modernize_avoid_variadic_functions_highlighting = none
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_missing_format_attribute_highlighting = none
|
||||
# `&pointer` handed to an API that takes `void*` (ReadProcessMemory, a memcpy of a vtable slot, a Streamline array of
|
||||
# constants): the conversion is the call's own.
|
||||
resharper_cpp_clang_tidy_bugprone_multi_level_implicit_pointer_conversion_highlighting = none
|
||||
# A test builds a handle or an address from a number, on purpose: a fake one, or one read from another process.
|
||||
resharper_cpp_clang_tidy_performance_no_int_to_ptr_highlighting = none
|
||||
# A macro that pastes its argument into a name (FL_DEV(vkGetDeviceQueue)) cannot put it in parentheses.
|
||||
resharper_cpp_clang_tidy_bugprone_macro_parentheses_highlighting = none
|
||||
# A test's fixture: a global with a std::string in it, a memcpy into a byte buffer that is not a string, two strings
|
||||
# added in an assertion's message.
|
||||
resharper_cpp_clang_tidy_bugprone_throwing_static_initialization_highlighting = none
|
||||
resharper_cpp_clang_tidy_bugprone_not_null_terminated_result_highlighting = none
|
||||
resharper_cpp_clang_tidy_performance_inefficient_string_concatenation_highlighting = none
|
||||
# layout_test checks facts the compiler already knows - a constant's length, a bit-field's range - at run time, so
|
||||
# that a failure prints which one: the branch that cannot be taken is the test passing.
|
||||
resharper_cpp_unreachable_code_highlighting = none
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_unreachable_code_highlighting = none
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_tautological_value_range_compare_highlighting = none
|
||||
|
||||
# --- CODE LOADED INTO A GAME: the Overlay, the Vulkan layer, the shared-memory headers ---
|
||||
# D100: here only a defect is fixed, in a pull request of its own with the hook's overhead measured (rule 5,
|
||||
# 14_TESTING §Hook overhead). The report found none. What it did say about these files, each kept as it is:
|
||||
[src/native/{FrameLedger.Overlay,FrameLedger.VkLayer,FrameLedger.Shm}/**.{cpp,h,inl}]
|
||||
# Arms with the same body are different cases, each with its own comment saying why it reads as it does.
|
||||
resharper_cpp_clang_tidy_bugprone_branch_clone_highlighting = none
|
||||
# MinHook's MH_ALL_HOOKS is NULL, by its header.
|
||||
resharper_cpp_zero_constant_can_be_replaced_with_nullptr_highlighting = none
|
||||
# Kept on purpose, each with its reason beside it in dllmain.cpp: a retired enumerator whose bit must not be reused;
|
||||
# slSetTag, deprecated by a header whose replacement no measured module exports.
|
||||
resharper_cpp_enumerator_never_used_highlighting = none
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_deprecated_declarations_highlighting = none
|
||||
|
||||
# DEAD CODE, FOUND AND NOT REMOVED: nothing calls dllmain.cpp's LogNoteW. D100 changes code loaded into a game for
|
||||
# a defect only, so taking it out is the owner's to order (HANDOFF, the native report's section) and not this
|
||||
# report's to do. Until then this one file is not read for an unused function. Remove this section with it.
|
||||
[src/native/FrameLedger.Overlay/src/dllmain.cpp]
|
||||
resharper_cpp_declarator_never_used_highlighting = none
|
||||
resharper_cpp_clang_tidy_clang_diagnostic_unused_function_highlighting = none
|
||||
|
||||
# The guard's rule matcher, which the Overlay compiles too. ResolveTolerance clears its out parameter with memset, as
|
||||
# ResetRules does: a Tolerance is flags with default member initialisers, which is all "non-trivially default
|
||||
# constructible" means here, and zero is what those initialisers say.
|
||||
[src/native/FrameLedger.Injector/{src/fl_ac_rules.cpp,include/fl_ac_rules.h}]
|
||||
resharper_cpp_clang_tidy_bugprone_raw_memory_call_on_non_trivial_type_highlighting = none
|
||||
@@ -0,0 +1,100 @@
|
||||
# ACCESSIBILITY.md (beta.35, D88) sends every accessibility barrier here. It is its own form rather than part of the bug
|
||||
# report because a barrier needs different facts: what the reporter uses to read or operate the screen, and how far it
|
||||
# stops them. Nothing here asks about the reporter themself.
|
||||
name: Accessibility problem
|
||||
description: Something in FrameLedger cannot be reached, read or seen — with the keyboard, a screen reader, a contrast theme, Magnifier or another aid
|
||||
labels: [accessibility]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thank you for telling us. **You never need to tell us anything about yourself or a disability** — what you use
|
||||
and what happened is enough. Screenshots and recordings help but are optional.
|
||||
|
||||
If FrameLedger refused to hook a game, stopped measuring or turned hooking off **without your knowing** — a
|
||||
safety notice you could not perceive — say so below: it is a safety problem too, and it is handled first.
|
||||
|
||||
What FrameLedger aims for and what it cannot do yet: [ACCESSIBILITY.md](https://github.com/poli0981/frameledger/blob/main/ACCESSIBILITY.md).
|
||||
|
||||
- type: textarea
|
||||
id: task
|
||||
attributes:
|
||||
label: What were you trying to do?
|
||||
placeholder: 'e.g. switch hooking on for a game, read a session''s frame rate, answer the terms window'
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: what-happened
|
||||
attributes:
|
||||
label: What happened instead?
|
||||
description: What you heard, saw or could not do — and what you expected.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: steps
|
||||
attributes:
|
||||
label: How to get there
|
||||
placeholder: |
|
||||
1. Open Games (Ctrl+2)
|
||||
2. Tab to …
|
||||
3. …
|
||||
|
||||
- type: input
|
||||
id: app-version
|
||||
attributes:
|
||||
label: FrameLedger version
|
||||
description: Help ▸ About
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: os
|
||||
attributes:
|
||||
label: Windows version
|
||||
placeholder: 'Windows 11 26100.2314'
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: aid
|
||||
attributes:
|
||||
label: What do you use?
|
||||
multiple: true
|
||||
options:
|
||||
- Keyboard only
|
||||
- Narrator
|
||||
- NVDA
|
||||
- JAWS
|
||||
- Windows Magnifier
|
||||
- A Windows contrast theme
|
||||
- Voice Access or other speech input
|
||||
- Display scaling or a large text size
|
||||
- Something else (say below)
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: aid-version
|
||||
attributes:
|
||||
label: Its version, if you know it
|
||||
placeholder: 'e.g. NVDA 2026.1'
|
||||
|
||||
- type: dropdown
|
||||
id: severity
|
||||
attributes:
|
||||
label: How much does it stop you?
|
||||
description: Optional — the maintainer sets it when reading the report (ACCESSIBILITY.md, How serious it is).
|
||||
options:
|
||||
- Not sure
|
||||
- Critical — I cannot do the task at all
|
||||
- Serious — only with great difficulty or a workaround
|
||||
- Moderate — it is tiring or inconsistent
|
||||
- Minor — it barely gets in the way
|
||||
|
||||
- type: textarea
|
||||
id: more
|
||||
attributes:
|
||||
label: Anything else
|
||||
description: A screenshot, a recording, or a diagnostic file from Help ▸ Report a bug (built on your PC; you choose what to attach).
|
||||
@@ -1,5 +1,16 @@
|
||||
# Central package management makes NuGet PRs single-file diffs
|
||||
# (docs/12_BUILD.md, docs/13_CI_CD.md).
|
||||
#
|
||||
# The nuget entry also covers .config/dotnet-tools.json (the SonarScanner for
|
||||
# .NET, since 2026-10-25). No dotnet-sdk entry, on purpose: global.json is a
|
||||
# floor (11.0.100 since beta.37, D94) with rollForward latestFeature, so every
|
||||
# machine and the CI runner already build with the newest 11.0 SDK they have;
|
||||
# raising the floor is a decision, not an update (docs/12_BUILD.md).
|
||||
#
|
||||
# COOLDOWN (2026-10-25): a version update waits seven days after a release is
|
||||
# published, so a release that is pulled or found compromised in its first
|
||||
# week never reaches a pull request here. Security updates do not wait — the
|
||||
# option does not apply to them.
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: nuget
|
||||
@@ -7,6 +18,8 @@ updates:
|
||||
schedule:
|
||||
interval: weekly
|
||||
open-pull-requests-limit: 5
|
||||
cooldown:
|
||||
default-days: 7
|
||||
groups:
|
||||
minor-and-patch:
|
||||
update-types: [minor, patch]
|
||||
@@ -21,7 +34,14 @@ updates:
|
||||
- dependency-name: FluentAssertions
|
||||
update-types: [version-update:semver-major]
|
||||
|
||||
# One pull request a week for the actions' minor and patch releases; a new
|
||||
# major still comes alone, because it is the one that changes inputs.
|
||||
- package-ecosystem: github-actions
|
||||
directory: /
|
||||
schedule:
|
||||
interval: weekly
|
||||
cooldown:
|
||||
default-days: 7
|
||||
groups:
|
||||
actions-minor-and-patch:
|
||||
update-types: [minor, patch]
|
||||
@@ -30,6 +30,18 @@ review questions from `docs/19_SAFETY_AND_ANTICHEAT.md` §Review checklist.
|
||||
|
||||
**Measured overhead:** <!-- e.g. "0.31 µs/present, game Avg FPS delta -0.2%" -->
|
||||
|
||||
## User-interface changes only
|
||||
|
||||
Skip this section if the PR does not change what the App shows. Otherwise — `ACCESSIBILITY.md` §For contributors,
|
||||
`docs/08_UI.md` §Accessibility:
|
||||
|
||||
- [ ] Every control that shows no text of its own has a name, from `.resx` in `en`, `vi` and `ja`
|
||||
- [ ] Colours come from the theme only, and nothing is shown by colour alone
|
||||
- [ ] Everything new can be reached and used with the keyboard, in reading order, and Esc leaves a new dialog
|
||||
- [ ] `ACCESSIBILITY.md` (and `LIMITATIONS.md`) changed in this PR if what works or what does not moved
|
||||
|
||||
**Checked by hand:** <!-- e.g. "Tab through the new card with the mouse unplugged; Narrator reads its name and value" -->
|
||||
|
||||
## Safety-string changes only
|
||||
|
||||
- [ ] `Safety_*` resx keys have human-reviewed `ja` (never machine-drafted — `docs/09_I18N.md`)
|
||||
@@ -38,4 +50,6 @@ review questions from `docs/19_SAFETY_AND_ANTICHEAT.md` §Review checklist.
|
||||
## Notes for the reviewer
|
||||
|
||||
<!-- Anything that would be hard to see from the diff. If you resolved an item
|
||||
in docs/20_OPEN_QUESTIONS.md, say which one and delete it from that file. -->
|
||||
in docs/20_OPEN_QUESTIONS.md, say which one, mark it resolved in §S24, and move
|
||||
the entry verbatim to docs/open-questions/closed-*.md with its row in the table
|
||||
at the end of its series (beta.24, D66). -->
|
||||
+156
-11
@@ -9,23 +9,29 @@
|
||||
#
|
||||
# So this workflow does exactly one thing of substance: ./build.ps1 check.
|
||||
# Anything CI checks that local does not is a way for the two to disagree.
|
||||
#
|
||||
# Since 2026-10-25 (owner decision D68) a second job, `sonarcloud`, hands that
|
||||
# run's coverage to SonarCloud and analyses the tree there. It is not the gate
|
||||
# and not a required check: it builds again in a build of its own, and a
|
||||
# SonarCloud outage or a failed quality gate is a red job beside a green
|
||||
# `check`, never a blocked merge (docs/13_CI_CD.md §SonarCloud).
|
||||
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
# `alpha` since 2026-10-31 (D73, docs/13_CI_CD.md §The alpha line): the same source on the .NET that line is
|
||||
# trying, whose merges and syncs from main need the same gate under its own global.json.
|
||||
branches: [main, alpha]
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
|
||||
# Permissions do not inherit into reusable workflows, and defaults are broader
|
||||
# than this job needs either way (docs/13_CI_CD.md).
|
||||
permissions:
|
||||
contents: read
|
||||
# For the Changelog step below only: listing a pull request's changed files is
|
||||
# the Pull Requests API, and an explicit `permissions:` block grants nothing it
|
||||
# does not name. Read-only, and the job writes nothing back.
|
||||
pull-requests: read
|
||||
# than this job needs either way (docs/13_CI_CD.md). Since the second job
|
||||
# (2026-10-25) they are granted per job and the workflow grants none: a grant at
|
||||
# this level reaches every job, so `sonarcloud` would have held `check`'s
|
||||
# pull-requests read for nothing (SonarCloud githubactions:S8264).
|
||||
permissions: {}
|
||||
|
||||
concurrency:
|
||||
group: ci-${{ github.ref }}
|
||||
@@ -35,6 +41,12 @@ jobs:
|
||||
check:
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 40
|
||||
permissions:
|
||||
contents: read
|
||||
# For the Changelog step below only: listing a pull request's changed files is
|
||||
# the Pull Requests API, and an explicit `permissions:` block grants nothing it
|
||||
# does not name. Read-only, and the job writes nothing back.
|
||||
pull-requests: read
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
@@ -47,7 +59,7 @@ jobs:
|
||||
global-json-file: global.json
|
||||
|
||||
- name: Set up MSVC (x64)
|
||||
uses: ilammy/msvc-dev-cmd@v1
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
@@ -166,8 +178,11 @@ jobs:
|
||||
Write-Host ("vulkaninfo.exe on PATH: {0}" -f ($(if ($cmd) { $cmd.Source } else { 'no' })))
|
||||
Write-Host ("HKLM:\SOFTWARE\Khronos\Vulkan\Drivers present: {0}" -f (Test-Path 'HKLM:\SOFTWARE\Khronos\Vulkan\Drivers'))
|
||||
|
||||
# Not for a pull request into `alpha` (D73): what the alpha line changes is written in its release's own file on
|
||||
# main (docs/changelog/x.y.z-alpha.N.md), and an [Unreleased] entry on the alpha branch would collide with main's
|
||||
# at every sync.
|
||||
- name: Changelog
|
||||
if: github.event_name == 'pull_request'
|
||||
if: github.event_name == 'pull_request' && github.base_ref != 'alpha'
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
@@ -178,11 +193,141 @@ jobs:
|
||||
if ($LASTEXITCODE -ne 0) { throw "could not list the pull request's changed files" }
|
||||
./tools/changelog-check.ps1 -ChangedFiles @($files)
|
||||
|
||||
# Cobertura for a person reading it, OpenCover for the sonarcloud job below
|
||||
# (build.ps1 writes both from the one test run since 2026-10-25).
|
||||
- name: Upload coverage
|
||||
if: always()
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: coverage
|
||||
path: '**/TestResults/**/coverage.cobertura.xml'
|
||||
path: |
|
||||
**/TestResults/**/coverage.cobertura.xml
|
||||
**/TestResults/**/coverage.opencover.xml
|
||||
if-no-files-found: warn
|
||||
retention-days: 14
|
||||
|
||||
# SonarCloud, analysed from CI (owner decision D68, 2026-10-25; docs/13_CI_CD.md
|
||||
# §SonarCloud). A job of its own, after `check`, for two reasons:
|
||||
#
|
||||
# - The scanner instruments the build it wraps and turns TreatWarningsAsErrors
|
||||
# off in it (SonarQube.Integration.targets), so it cannot wrap the gate's
|
||||
# build without weakening the gate. It gets a build of its own here.
|
||||
# - It is advisory. `main`'s required contexts stay `check` and the two
|
||||
# `analyze` jobs; a failed quality gate or a SonarCloud outage turns this job
|
||||
# red and blocks nothing.
|
||||
#
|
||||
# It takes the gate's coverage (the `coverage` artifact) rather than running
|
||||
# the tests a second time, and CMake's compilation database for the C++.
|
||||
# Settings: SonarQube.Analysis.xml. The scanner: .config/dotnet-tools.json.
|
||||
sonarcloud:
|
||||
needs: check
|
||||
# A pull request from this repository, or main. SONAR_TOKEN reaches neither a
|
||||
# fork's pull request nor Dependabot's, and the scanner cannot start without
|
||||
# it. Any other branch is refused by the organisation's plan - "Organization
|
||||
# is not allowed to access data from non main branches", measured on a
|
||||
# workflow_dispatch run of a feature branch, 2026-10-25 - so a dispatch on
|
||||
# one runs `check` alone. The same plan is why a pull request INTO `alpha`
|
||||
# (D73) and a push to it run `check` alone: SonarCloud analyses main's line.
|
||||
if: >-
|
||||
(github.event_name == 'pull_request' &&
|
||||
github.base_ref != 'alpha' &&
|
||||
github.event.pull_request.head.repo.full_name == github.repository &&
|
||||
github.event.pull_request.user.login != 'dependabot[bot]') ||
|
||||
(github.event_name != 'pull_request' && github.ref == 'refs/heads/main')
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 40
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
# Blame for the new-code period, and the tags for the version.
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Set up .NET
|
||||
uses: actions/setup-dotnet@v6
|
||||
with:
|
||||
global-json-file: global.json
|
||||
|
||||
# The analysis of the C++ runs the compiler of the compilation database.
|
||||
- name: Set up MSVC (x64)
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
- name: Cache NuGet
|
||||
uses: actions/cache@v6
|
||||
with:
|
||||
path: ~/.nuget/packages
|
||||
key: nuget-${{ runner.os }}-${{ hashFiles('**/Directory.Packages.props', 'global.json') }}
|
||||
restore-keys: nuget-${{ runner.os }}-
|
||||
|
||||
# The JRE the scanner provisions, and SonarCloud's analysers.
|
||||
- name: Cache SonarCloud
|
||||
uses: actions/cache@v6
|
||||
with:
|
||||
path: ~/.sonar/cache
|
||||
key: sonar-${{ runner.os }}-${{ hashFiles('.config/dotnet-tools.json') }}
|
||||
restore-keys: sonar-${{ runner.os }}-
|
||||
|
||||
# tests/<project>/TestResults/<guid>/coverage.opencover.xml, as `check` wrote
|
||||
# them. Same workspace path on every hosted Windows runner, so the reports'
|
||||
# absolute paths name these sources.
|
||||
- name: Download the gate's coverage
|
||||
uses: actions/download-artifact@v8
|
||||
with:
|
||||
name: coverage
|
||||
|
||||
# Configure only, plus the one header the build generates: the analysis
|
||||
# reads the sources with the flags and defines CMake gives each one, and
|
||||
# needs nothing built. FetchContent's sources land in build/, excluded.
|
||||
#
|
||||
# CMAKE_CXX_SCAN_FOR_MODULES=OFF: with C++20 and Ninja, CMake (3.28 on)
|
||||
# scans every source for modules and gives each compile command an
|
||||
# `@<object>.modmap` response file that only the BUILD writes, and the
|
||||
# C/C++ analyser stops on a response file it cannot open ("unexpanded
|
||||
# response file", the first run, 2026-10-25). Nothing here uses a module.
|
||||
- name: Native compilation database
|
||||
shell: pwsh
|
||||
working-directory: src/native
|
||||
run: |
|
||||
cmake --preset x64-release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_SCAN_FOR_MODULES=OFF
|
||||
if ($LASTEXITCODE -ne 0) { throw 'cmake configure failed' }
|
||||
cmake --build --preset x64-release --target fl_ac_floor_gen
|
||||
if ($LASTEXITCODE -ne 0) { throw 'generating the blocklist floor failed' }
|
||||
|
||||
# The version is the newest release tag the commit descends from, so the
|
||||
# project's new-code period ("previous version") is everything since the
|
||||
# last release.
|
||||
- name: Begin the analysis
|
||||
shell: pwsh
|
||||
env:
|
||||
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
dotnet tool restore
|
||||
if ($LASTEXITCODE -ne 0) { throw 'dotnet tool restore failed' }
|
||||
$tag = git describe --tags --abbrev=0 --match 'v*' 2>$null
|
||||
$version = if ($LASTEXITCODE -eq 0 -and $tag) { $tag.Substring(1) } else { (Get-Content VERSION -Raw).Trim() }
|
||||
Write-Host "sonar.projectVersion: $version"
|
||||
dotnet tool run dotnet-sonarscanner begin /k:poli0981_frameledger /o:poli0981 /v:$version `
|
||||
/s:"$PWD\SonarQube.Analysis.xml" /d:sonar.token=$env:SONAR_TOKEN
|
||||
if ($LASTEXITCODE -ne 0) { throw 'the scanner did not begin' }
|
||||
|
||||
# Platform: see build.ps1's Clear-VcxprojPlatform (the MSVC step exports
|
||||
# Platform=x64, which MSBuild reads as a solution platform).
|
||||
- name: Build for the analysis
|
||||
shell: pwsh
|
||||
run: |
|
||||
Remove-Item Env:Platform -ErrorAction SilentlyContinue
|
||||
dotnet build FrameLedger.slnx -c Release
|
||||
if ($LASTEXITCODE -ne 0) { throw 'the analysis build failed' }
|
||||
|
||||
- name: End the analysis
|
||||
shell: pwsh
|
||||
env:
|
||||
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
|
||||
run: |
|
||||
dotnet tool run dotnet-sonarscanner end /d:sonar.token=$env:SONAR_TOKEN
|
||||
if ($LASTEXITCODE -ne 0) { throw 'the analysis failed, or its quality gate did' }
|
||||
@@ -7,9 +7,20 @@
|
||||
# Repo-local for now. The ops repo has codeql-mixed.yml, but C++ needs manual
|
||||
# build mode driven by the CMake preset, and that input surface has not been
|
||||
# verified. Switch to a caller stub once it has.
|
||||
#
|
||||
# AND the workflows themselves, since 2026-10-25: CodeQL's `actions` language
|
||||
# reads .github/workflows for injection from event data, untrusted checkouts
|
||||
# and over-broad tokens — the same class of finding SonarCloud raised once
|
||||
# (githubactions:S7631, wiki.yml, beta.26). Its context, `analyze (actions,
|
||||
# none)`, is not one of main's required checks.
|
||||
|
||||
name: CodeQL
|
||||
|
||||
# `workflow_dispatch` since 2026-11-11 (beta.37): on a pull request the C# analysis
|
||||
# is an OVERLAY - it extracts the changed files on top of the database cached from
|
||||
# `main` - so it cannot show what the extractor makes of the whole source, or of a
|
||||
# construct it has not met (the move to .NET 11, a C# 15 feature). A dispatch on a
|
||||
# branch is a full analysis of that branch (docs/13_CI_CD.md §C# 15 and the analyses).
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
@@ -17,11 +28,20 @@ on:
|
||||
branches: [main]
|
||||
schedule:
|
||||
- cron: '27 4 * * 1'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
security-events: write
|
||||
|
||||
# A new push to a pull request replaces its run. A push to main and the weekly
|
||||
# scan each get a group of their own (the run id), so none of them is ever
|
||||
# cancelled or left pending behind another, and the default branch's alerts
|
||||
# always come from a finished analysis.
|
||||
concurrency:
|
||||
group: codeql-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
analyze:
|
||||
runs-on: windows-latest
|
||||
@@ -35,6 +55,8 @@ jobs:
|
||||
build-mode: none
|
||||
- language: cpp
|
||||
build-mode: manual
|
||||
- language: actions
|
||||
build-mode: none
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
@@ -47,7 +69,7 @@ jobs:
|
||||
|
||||
- name: Set up MSVC (x64)
|
||||
if: matrix.language == 'cpp'
|
||||
uses: ilammy/msvc-dev-cmd@v1
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
|
||||
@@ -0,0 +1,178 @@
|
||||
# Qodana (owner decisions D93, 2026-11-10, and D99, 2026-11-11; docs/13_CI_CD.md §Qodana).
|
||||
#
|
||||
# JetBrains' template for the Qodana Scan action, changed where FrameLedger differs
|
||||
# and each change said here:
|
||||
#
|
||||
# - The linter is Qodana for .NET (Rider's engine) in NATIVE mode, on a Windows
|
||||
# runner: the projects target Windows, and the linter then builds and loads them
|
||||
# with the SDK this job installs from global.json - no container, and no
|
||||
# EnableWindowsTargeting. qodana.yaml names the linter and the mode; nothing is
|
||||
# passed as an action argument. (Until beta.37 this was the Community linter in a
|
||||
# Linux container, the one Linux job this repository had.)
|
||||
# - The action is pinned to a commit, as every action that is not GitHub's own is
|
||||
# here.
|
||||
# - Permissions are the ones the job uses: it reads the repository, writes a check
|
||||
# run with the annotations and one comment on the pull request. The template's
|
||||
# `contents: write` is for pushing quick-fixes, which this job never does.
|
||||
# - A workflow of its own, as JetBrains advises, and ADVISORY: `main`'s required
|
||||
# contexts stay `check` and the two `analyze` jobs. A problem Qodana finds, a
|
||||
# Qodana Cloud outage or a lapsed licence is a red job beside a green `check`,
|
||||
# never a blocked merge.
|
||||
# - Two jobs, two reports (D99): `managed` reads the solution - the C#, the XAML and
|
||||
# what Rider's plugins read around it - and reports to the Qodana Cloud project
|
||||
# `frameledger`; `native` reads the C++ of src/native through a Visual Studio
|
||||
# solution CMake generates for it, with settings of its own (qodana-native.yaml),
|
||||
# and reports to `frameledger-cpp`. Neither reads what the other does. The pull
|
||||
# request's comment and annotations are the managed job's alone.
|
||||
# - `main` only: the `alpha` branch is main's source under another release line
|
||||
# (docs/13_CI_CD.md §The alpha line), and main's is what is analysed.
|
||||
|
||||
name: Qodana
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
permissions: {}
|
||||
|
||||
concurrency:
|
||||
group: qodana-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
managed:
|
||||
name: Qodana (managed)
|
||||
# A pull request from this repository, or a push or a dispatch. QODANA_TOKEN
|
||||
# reaches neither a fork's pull request nor Dependabot's, and their token cannot
|
||||
# write the check run or the comment.
|
||||
if: >-
|
||||
github.event_name != 'pull_request' ||
|
||||
(github.event.pull_request.head.repo.full_name == github.repository &&
|
||||
github.event.pull_request.user.login != 'dependabot[bot]')
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 60
|
||||
permissions:
|
||||
contents: read
|
||||
checks: write
|
||||
pull-requests: write
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
# The pull request's own commit, not its merge commit (empty on a push or
|
||||
# a dispatch, which then check out the commit that started them).
|
||||
ref: ${{ github.event.pull_request.head.sha }}
|
||||
# A full history is required for pull request analysis.
|
||||
fetch-depth: 0
|
||||
|
||||
# Native mode runs the linter in this job's environment, so the SDK it loads
|
||||
# the projects with is this one. No MSVC step here on purpose: it exports
|
||||
# Platform=x64, which MSBuild reads as a solution platform (build.ps1's
|
||||
# Clear-VcxprojPlatform).
|
||||
- name: Set up .NET
|
||||
uses: actions/setup-dotnet@v6
|
||||
with:
|
||||
global-json-file: global.json
|
||||
|
||||
# Restored only: `check` saves this cache, under the same key.
|
||||
- name: Restore the NuGet cache
|
||||
uses: actions/cache/restore@v6
|
||||
with:
|
||||
path: ~/.nuget/packages
|
||||
key: nuget-${{ runner.os }}-${{ hashFiles('**/Directory.Packages.props', 'global.json') }}
|
||||
restore-keys: nuget-${{ runner.os }}-
|
||||
|
||||
# Built before it is inspected: a build that fails is then one red step with
|
||||
# the compiler's own message, not a report of thousands of unresolved symbols.
|
||||
# The native DLLs are absent here, so the .targets that copy them warn and the
|
||||
# build goes on, as on a fresh clone.
|
||||
- name: Build what the linter loads
|
||||
shell: pwsh
|
||||
run: |
|
||||
dotnet build FrameLedger.slnx -c Release
|
||||
if ($LASTEXITCODE -ne 0) { throw 'the build failed' }
|
||||
|
||||
# pr-mode false: the whole solution every time, so a pull request and `main`
|
||||
# are judged by the same list. upload-result: the SARIF and the linter's log
|
||||
# as an artifact of the run, for a reader with no Qodana Cloud account.
|
||||
# Caches are saved from `main` only (a pull request reads them), under keys of
|
||||
# this job's own: one per branch would crowd the repository's cache quota,
|
||||
# which NuGet's share.
|
||||
- name: Qodana Scan
|
||||
uses: JetBrains/qodana-action@3e8d76ff0e0241618abd808682f426afe84bab3f # v2026.2.2
|
||||
with:
|
||||
pr-mode: false
|
||||
upload-result: true
|
||||
artifact-name: qodana-report
|
||||
cache-default-branch-only: true
|
||||
primary-cache-key: qodana-managed-${{ github.ref_name }}-${{ github.sha }}
|
||||
additional-cache-key: qodana-managed-main
|
||||
env:
|
||||
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
|
||||
QODANA_ENDPOINT: 'https://qodana.cloud'
|
||||
|
||||
native:
|
||||
name: Qodana (native)
|
||||
# The same condition as `managed`, for the same reason: QODANA_TOKEN_NATIVE
|
||||
# reaches neither a fork's pull request nor Dependabot's.
|
||||
if: >-
|
||||
github.event_name != 'pull_request' ||
|
||||
(github.event.pull_request.head.repo.full_name == github.repository &&
|
||||
github.event.pull_request.user.login != 'dependabot[bot]')
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 60
|
||||
# No annotations and no comment from this job (below), so it writes nothing.
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
ref: ${{ github.event.pull_request.head.sha }}
|
||||
fetch-depth: 0
|
||||
|
||||
# global.json sits above the solution, and the linter resolves it.
|
||||
- name: Set up .NET
|
||||
uses: actions/setup-dotnet@v6
|
||||
with:
|
||||
global-json-file: global.json
|
||||
|
||||
# The Visual Studio generator finds the toolset itself: no MSVC step. Configure
|
||||
# fetches MinHook, Catch2 and jsmn into the build tree, as the gate's does.
|
||||
- name: Generate the solution and the one generated header
|
||||
shell: pwsh
|
||||
working-directory: src/native
|
||||
run: |
|
||||
cmake --version
|
||||
cmake --preset x64-vs-analysis
|
||||
if ($LASTEXITCODE -ne 0) { throw 'cmake configure failed' }
|
||||
cmake --build --preset x64-vs-analysis --target fl_ac_floor_gen
|
||||
if ($LASTEXITCODE -ne 0) { throw 'generating the blocklist floor failed' }
|
||||
if (-not (Test-Path ../../build/native/x64-vs-analysis/FrameLedgerNative.slnx)) {
|
||||
Get-ChildItem ../../build/native/x64-vs-analysis -Filter 'FrameLedgerNative.*' | ForEach-Object { Write-Host $_.Name }
|
||||
throw 'CMake did not write FrameLedgerNative.slnx (qodana-native.yaml names it)'
|
||||
}
|
||||
|
||||
# A report of its own: its own settings file, results folder, artifact, cache
|
||||
# keys and Qodana Cloud project. The pull request's comment and annotations are
|
||||
# the managed job's; a second job of the same linter would overwrite them.
|
||||
- name: Qodana Scan
|
||||
uses: JetBrains/qodana-action@3e8d76ff0e0241618abd808682f426afe84bab3f # v2026.2.2
|
||||
with:
|
||||
args: --config qodana-native.yaml
|
||||
results-dir: ${{ runner.temp }}/qodana-native/results
|
||||
cache-dir: ${{ runner.temp }}/qodana-native/caches
|
||||
pr-mode: false
|
||||
upload-result: true
|
||||
artifact-name: qodana-report-native
|
||||
cache-default-branch-only: true
|
||||
primary-cache-key: qodana-native-${{ github.ref_name }}-${{ github.sha }}
|
||||
additional-cache-key: qodana-native-main
|
||||
post-pr-comment: false
|
||||
use-annotations: false
|
||||
env:
|
||||
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN_NATIVE }}
|
||||
QODANA_ENDPOINT: 'https://qodana.cloud'
|
||||
+109
-12
@@ -22,6 +22,13 @@
|
||||
# -p:Version; the native blocks keep the numeric core (CMake's project() accepts
|
||||
# nothing else).
|
||||
#
|
||||
# THE ALPHA LINE (2026-10-31, owner decisions D73-D76; 12_BUILD §The alpha line): the
|
||||
# RELEASE_LINE file says `alpha` on the long-lived `alpha` branch, where the same source
|
||||
# builds on the .NET the line is trying. Its tags are `vX.Y.Z-alpha.N` and nothing else, no other
|
||||
# line may carry one, and its packages go to Velopack's `alpha` channel
|
||||
# (releases.alpha.json) - which no beta reads, as no alpha reads releases.win.json
|
||||
# (11_UPDATER §Channels). The version gate below enforces all three.
|
||||
#
|
||||
# A DRY RUN (2026-09-16, P5 prep): `workflow_dispatch` with a version runs every
|
||||
# step below — the gate, the publish, the tree assertion, vpk, the checksums — and
|
||||
# uploads the result as a workflow artifact, but creates no tag and no Release.
|
||||
@@ -60,13 +67,18 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
# The SDK global.json names builds everything. The .NET 10 line beside it is for `vpk` (the Pack step): 1.2.161
|
||||
# ships net8.0, net9.0 and net10.0 builds and none that rolls forward to another major, so on a machine with
|
||||
# .NET 11 alone the tool would not start. The alphas were packed under an 11 SDK because the hosted image
|
||||
# happened to carry a .NET 10 runtime; this states the dependency (2026-11-11, beta.37, D94).
|
||||
- name: Set up .NET
|
||||
uses: actions/setup-dotnet@v6
|
||||
with:
|
||||
global-json-file: global.json
|
||||
dotnet-version: 10.0.x
|
||||
|
||||
- name: Set up MSVC (x64)
|
||||
uses: ilammy/msvc-dev-cmd@v1
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
@@ -101,6 +113,14 @@ jobs:
|
||||
$pre = if ($m.Groups[2].Success) { 'true' } else { 'false' }
|
||||
$file = (Get-Content VERSION -Raw).Trim()
|
||||
if ($core -ne $file) { throw "tag $tag has numeric core $core but VERSION says $file — bump VERSION in the same commit as the changelog section, then tag" }
|
||||
# D73: the release line this commit builds (Directory.Build.props refuses any other value too) and the tags it may
|
||||
# carry - an alpha's on the alpha line only, and nothing else there.
|
||||
$line = (Get-Content RELEASE_LINE -Raw).Trim()
|
||||
if ($line -cnotin @('main', 'alpha')) { throw "RELEASE_LINE says '$line'; it must be main or alpha" }
|
||||
$suffix = $m.Groups[2].Value
|
||||
if ($line -eq 'alpha' -and $suffix -cnotmatch '^-alpha\.\d+$') { throw "this commit is on the alpha line (RELEASE_LINE); its tag must be vX.Y.Z-alpha.N, not $tag" }
|
||||
if ($line -ne 'alpha' -and $suffix -match 'alpha') { throw "tag $tag names an alpha, but RELEASE_LINE says '$line': an alpha is tagged on the alpha branch, nowhere else" }
|
||||
$channel = if ($line -eq 'alpha') { 'alpha' } else { 'win' }
|
||||
New-Item -ItemType Directory -Force out | Out-Null
|
||||
./tools/release-notes.ps1 -Version $full -OutFile out/notes.md
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
@@ -113,8 +133,25 @@ jobs:
|
||||
}
|
||||
"version=$full" >> $env:GITHUB_OUTPUT
|
||||
"prerelease=$pre" >> $env:GITHUB_OUTPUT
|
||||
"channel=$channel" >> $env:GITHUB_OUTPUT
|
||||
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
|
||||
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
|
||||
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre; line: $line; Velopack channel: $channel)"
|
||||
|
||||
# The Overlay's build id is `git describe --dirty` at CMake's configure
|
||||
# (src/native/FrameLedger.Shm/CMakeLists.txt), and the next step edits tracked
|
||||
# files: every release until beta.18 shipped "<tag>-dirty". So the id is read
|
||||
# here, from the clean checkout, and handed to CMake through the environment;
|
||||
# buildid-check reads it back out of the published binaries.
|
||||
- name: Build id (the clean checkout)
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$id = "$(git describe --always --dirty --abbrev=12)".Trim()
|
||||
if ($LASTEXITCODE -ne 0 -or -not $id) { throw 'git describe failed' }
|
||||
if ($id.EndsWith('-dirty')) { throw "the checkout is dirty before the release has touched it: $id" }
|
||||
if ($id.Length -gt 31) { throw "build id '$id' is $($id.Length) characters; FlShmHandshake::buildId holds 31" }
|
||||
"FL_BUILD_ID=$id" >> $env:GITHUB_ENV
|
||||
Write-Host "FL_BUILD_ID = $id"
|
||||
|
||||
# 12_BUILD §Release-time token substitution: the effective date of a legal
|
||||
# document is the date it ships. The only placeholder that survives into the
|
||||
@@ -149,9 +186,14 @@ jobs:
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$v = '${{ steps.version.outputs.version }}'
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
|
||||
# beta.12: the App's links into the repository open the documents of THIS release (Services/RepositoryLinks.cs):
|
||||
# the tag, or for a rehearsal - which has no tag - the commit it was built from.
|
||||
$ref = if ('${{ steps.version.outputs.dry_run }}' -eq 'true') { '${{ github.sha }}' } else { "v$v" }
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -p:FrameLedgerSourceRef=$ref -o out/app
|
||||
if ($LASTEXITCODE -ne 0) { throw 'App publish failed' }
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
|
||||
# beta.14 (D50): the same ref for the Agent - Directory.Build.props stamps it on every assembly, and both
|
||||
# publishes build the same libraries into this one folder.
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -p:FrameLedgerSourceRef=$ref -o out/app
|
||||
if ($LASTEXITCODE -ne 0) { throw 'Agent publish failed' }
|
||||
|
||||
# A self-contained package redistributes the .NET runtime, and its licence and
|
||||
@@ -178,7 +220,7 @@ jobs:
|
||||
}
|
||||
Get-ChildItem $dest | ForEach-Object { Write-Host (" {0,-64} {1,8:N0}" -f $_.Name, $_.Length) }
|
||||
|
||||
# What ships is what matters: the two entry points and the four shipped native
|
||||
# What ships is what matters: the two entry points and the five shipped native
|
||||
# binaries (versioninfo-check's list) must be in the tree, and the unshipped
|
||||
# capture host must not be (package-closure-check proves it statically; this
|
||||
# reads the directory).
|
||||
@@ -186,14 +228,18 @@ jobs:
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'rules/detection-rules.json',
|
||||
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
|
||||
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'FrameLedger.ProcessStats.dll', 'rules/detection-rules.json',
|
||||
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/NOTICE.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
|
||||
$missing = @($required | Where-Object { -not (Test-Path (Join-Path out/app $_)) })
|
||||
if ($missing.Count -gt 0) { throw "out/app is missing: $($missing -join ', ')" }
|
||||
if (Test-Path out/app/FrameLedger.CaptureHost.exe) { throw 'out/app contains the unshipped capture host (12_BUILD: exactly two roots)' }
|
||||
if (@(Get-ChildItem out/app/licenses/dotnet -File -ErrorAction SilentlyContinue).Count -lt 2) { throw 'out/app/licenses/dotnet holds fewer than two files -- the runtime licence step did not run' }
|
||||
./tools/versioninfo-check.ps1 -BuildDir out/app
|
||||
# beta.14 (D50): the managed half too - the eight managed binaries, carrying the tag's full version.
|
||||
./tools/versioninfo-check.ps1 -BuildDir out/app -ManagedDir out/app -ExpectedProductVersion '${{ steps.version.outputs.version }}'
|
||||
if ($LASTEXITCODE -ne 0) { throw 'versioninfo-check over the published tree' }
|
||||
# beta.18: the native binaries carry the build id read from the clean checkout, exactly - never "<tag>-dirty".
|
||||
./tools/buildid-check.ps1 -BuildDir out/app -Expected $env:FL_BUILD_ID
|
||||
if ($LASTEXITCODE -ne 0) { throw 'buildid-check over the published tree' }
|
||||
$size = (Get-ChildItem out/app -Recurse -File | Measure-Object Length -Sum).Sum / 1MB
|
||||
Write-Host ("published tree: {0:N0} MB" -f $size)
|
||||
|
||||
@@ -207,17 +253,66 @@ jobs:
|
||||
# ledger.db, logs, the layer manifest). The same id would put the install inside
|
||||
# the ledger's folder and have the uninstaller remove every session without the
|
||||
# question 12_BUILD promises. The title the user sees is still "FrameLedger".
|
||||
# A DELTA (beta.13): vpk pack diffs against the newest full package already in --outputDir, and until beta.13 that
|
||||
# directory was always empty - so no release carried a delta and every update downloaded the whole package
|
||||
# (11_UPDATER §Built). The previous release is downloaded first; what THIS pack produced is assets.win.json, and only
|
||||
# that is kept: the previous full package moves out (not uploaded, not checksummed) and the feed lists this build
|
||||
# alone, as `vpk upload github` would write it. No previous release, or a download that fails, is a full-only
|
||||
# release - said as a warning, not a stop, because it is exactly what every release before this one was.
|
||||
- name: Pack (Velopack)
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
dotnet tool install -g vpk --version 1.2.0
|
||||
dotnet tool install -g vpk --version 1.2.161
|
||||
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
|
||||
$v = '${{ steps.version.outputs.version }}'
|
||||
vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
# D73: `win` (Velopack's default on Windows) for the main line, `alpha` for the alpha line - each release's feed
|
||||
# and the previous release its delta is made from are its own line's. The main line's pack keeps its exact
|
||||
# command (no --channel), so a beta is packed as every beta before the alpha line existed.
|
||||
$channel = '${{ steps.version.outputs.channel }}'
|
||||
New-Item -ItemType Directory out/release -Force | Out-Null
|
||||
vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel $channel --pre --token $env:GH_TOKEN --outputDir out/release
|
||||
if ($LASTEXITCODE -ne 0) { Write-Host '::warning::the previous release could not be downloaded - this release carries a full package only' }
|
||||
Write-Host 'previous release:'
|
||||
Get-ChildItem out/release -File | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
|
||||
$pack = @('pack', '--packId', 'FrameLedger.App', '--packVersion', $v, '--packDir', 'out/app', '--mainExe', 'FrameLedger.exe', '--packTitle', 'FrameLedger', '--packAuthors', 'FrameLedger', '--releaseNotes', 'out/notes.md', '--outputDir', 'out/release')
|
||||
if ($channel -ne 'win') { $pack += @('--channel', $channel) }
|
||||
vpk @pack
|
||||
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
|
||||
|
||||
$assets = "assets.$channel.json"
|
||||
$index = "releases.$channel.json"
|
||||
$legacyName = if ($channel -eq 'win') { 'RELEASES' } else { "RELEASES-$channel" }
|
||||
$built = @((Get-Content "out/release/$assets" -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
|
||||
if ($built.Count -eq 0) { throw "vpk pack wrote no $assets entries" }
|
||||
$keep = $built + @($index, $assets, $legacyName)
|
||||
New-Item -ItemType Directory out/previous -Force | Out-Null
|
||||
Get-ChildItem out/release -File | Where-Object { $keep -notcontains $_.Name } | Move-Item -Destination out/previous
|
||||
$feed = Get-Content "out/release/$index" -Raw | ConvertFrom-Json
|
||||
$feed.Assets = @($feed.Assets | Where-Object { $built -contains $_.FileName })
|
||||
if ($feed.Assets.Count -eq 0) { throw 'the feed lists none of this build''s packages' }
|
||||
[System.IO.File]::WriteAllText((Join-Path $PWD "out/release/$index"), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
|
||||
if (Test-Path "out/release/$legacyName") {
|
||||
$legacy = @(Get-Content "out/release/$legacyName" | Where-Object { $built -contains ($_ -split ' ')[1] })
|
||||
[System.IO.File]::WriteAllLines((Join-Path $PWD "out/release/$legacyName"), [string[]]$legacy, [System.Text.UTF8Encoding]::new($false))
|
||||
}
|
||||
|
||||
Write-Host 'this release:'
|
||||
Get-ChildItem out/release | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
|
||||
if (-not (Test-Path out/release/FrameLedger.App-win-Setup.exe)) { throw 'vpk did not produce FrameLedger.App-win-Setup.exe (README §Install names it)' }
|
||||
Write-Host ('feed: ' + (($feed.Assets | ForEach-Object { '{0} {1} {2}' -f $_.Type, $_.Version, $_.FileName }) -join '; '))
|
||||
$setup = "FrameLedger.App-$channel-Setup.exe"
|
||||
if (-not (Test-Path "out/release/$setup")) { throw "vpk did not produce $setup (README §Install names the beta's, guide/11-alpha-builds.md the alpha's)" }
|
||||
# The delta is the one this pack listed, not a name built here: Velopack puts a non-default channel in its packages'
|
||||
# names (FrameLedger.App-<v>-alpha-full.nupkg - measured on the 0.1.0-alpha.1 rehearsal, 2026-10-31), so the name
|
||||
# this step built for the default channel would have failed the second alpha.
|
||||
$delta = @($built | Where-Object { $_ -like '*-delta.nupkg' })
|
||||
if (Get-ChildItem out/previous -Filter '*-full.nupkg' -ErrorAction SilentlyContinue) {
|
||||
if ($delta.Count -ne 1) { throw "the previous full package was downloaded, but vpk produced no delta ($assets lists: $($built -join ', '))" }
|
||||
} else {
|
||||
Write-Host '::warning::no previous full package - this release carries no delta'
|
||||
}
|
||||
|
||||
- name: Checksums
|
||||
shell: pwsh
|
||||
@@ -240,7 +335,9 @@ jobs:
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$v = '${{ steps.version.outputs.version }}'
|
||||
$ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', "FrameLedger $v", '--notes-file', 'out/notes.md', '--verify-tag')
|
||||
# An alpha says what it is in the list of releases too, not only in its notes (D74).
|
||||
$title = if ('${{ steps.version.outputs.channel }}' -eq 'alpha') { "FrameLedger $v (experimental alpha)" } else { "FrameLedger $v" }
|
||||
$ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', $title, '--notes-file', 'out/notes.md', '--verify-tag')
|
||||
if ('${{ steps.version.outputs.prerelease }}' -eq 'true') { $ghArgs += '--prerelease' }
|
||||
$ghArgs += Get-ChildItem out/release -File | ForEach-Object { $_.FullName }
|
||||
gh @ghArgs
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
# The GitHub Wiki is a copy of the repository's own pages (D53/D54, the owner, 2026-10-07): wiki/ (Home, the sidebar,
|
||||
# the developer pages) and guide/ (the user guide, which is the End-user part) with LIMITATIONS.md and ACCESSIBILITY.md, assembled and checked
|
||||
# by tools/wiki-build.ps1 - the check build.ps1 runs as `wiki-check`. A page edited on the Wiki tab is overwritten here;
|
||||
# edit wiki/ or guide/ instead (docs/13_CI_CD.md §wiki.yml).
|
||||
#
|
||||
# Separate from release.yml on purpose. The release stays as it was and its dry run stays a pure rehearsal; a wiki that
|
||||
# fails to publish is a red run of its own, re-run on its own, never a red release. A step after `gh release create`
|
||||
# could never be re-run at all: the release would already exist.
|
||||
#
|
||||
# A release that release.yml creates with GITHUB_TOKEN fires no `release` event for other workflows. `workflow_run` does
|
||||
# fire - the Release run itself was started by the owner's tag push - and it runs THIS file as it is on main, so the job
|
||||
# checks out the commit the release was built from (head_sha) and links the repository's files at the tag (head_branch).
|
||||
|
||||
name: Wiki
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [Release]
|
||||
types: [completed]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
ref:
|
||||
description: 'Branch, tag or commit to build the wiki from; repository files are linked at this ref'
|
||||
required: true
|
||||
default: main
|
||||
type: string
|
||||
publish:
|
||||
description: 'Publish to the Wiki tab (off: build, check and upload the pages only)'
|
||||
required: true
|
||||
default: false
|
||||
type: boolean
|
||||
|
||||
# The repository's default token is read-only; pushing to <repo>.wiki.git needs contents: write.
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
group: wiki
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
wiki:
|
||||
# A rehearsal of release.yml (workflow_dispatch) never publishes the wiki: only a run started by a pushed v* tag
|
||||
# that succeeded - in THIS repository. A fork cannot start this repository's Release run (it runs on a tag push or by
|
||||
# hand), so the head checked out below is always the owner's; the repository check says so in the condition rather
|
||||
# than leaving it to release.yml's triggers (SonarCloud githubactions:S7631, beta.26).
|
||||
# Nor does an alpha's release (D73, 2026-10-31): the wiki shows the newest beta, and an alpha's tag is on the `alpha`
|
||||
# branch, whose guide is the beta's it was cut from - publishing it would only move the wiki's links off main's line.
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
(github.event.workflow_run.conclusion == 'success' &&
|
||||
github.event.workflow_run.event == 'push' &&
|
||||
github.event.workflow_run.head_repository.full_name == github.repository &&
|
||||
startsWith(github.event.workflow_run.head_branch, 'v') &&
|
||||
!contains(github.event.workflow_run.head_branch, '-alpha.'))
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 10
|
||||
env:
|
||||
# Values reach the scripts through the environment only, never pasted into them.
|
||||
WIKI_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_branch }}
|
||||
WIKI_PUBLISH: ${{ github.event_name == 'workflow_run' || inputs.publish }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_sha }}
|
||||
persist-credentials: false
|
||||
|
||||
- name: Build and check the wiki
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
./tools/wiki-build.ps1 -Ref $env:WIKI_REF -Out out/wiki
|
||||
if ($LASTEXITCODE -ne 0) { throw 'wiki-build failed' }
|
||||
|
||||
- name: Upload the pages
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: wiki-${{ github.run_id }}
|
||||
path: out/wiki/**
|
||||
if-no-files-found: error
|
||||
retention-days: 14
|
||||
|
||||
- name: Publish to the Wiki tab
|
||||
if: env.WIKI_PUBLISH == 'true'
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
gh auth setup-git
|
||||
if ($LASTEXITCODE -ne 0) { throw 'gh auth setup-git failed' }
|
||||
git clone --depth 1 "https://github.com/$env:GITHUB_REPOSITORY.wiki.git" wiki-repo
|
||||
if ($LASTEXITCODE -ne 0) { throw 'cloning the wiki failed - it must have one page created on github.com first' }
|
||||
Get-ChildItem wiki-repo -Force | Where-Object Name -ne '.git' | Remove-Item -Recurse -Force
|
||||
Copy-Item out/wiki/* wiki-repo -Recurse
|
||||
Set-Location wiki-repo
|
||||
git add -A
|
||||
git diff --cached --quiet
|
||||
if ($LASTEXITCODE -eq 0) { Write-Host "The wiki already shows $env:WIKI_REF; nothing to publish."; exit 0 }
|
||||
git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' commit -q -m "wiki: $env:WIKI_REF"
|
||||
if ($LASTEXITCODE -ne 0) { throw 'commit failed' }
|
||||
# The wiki repository's branch is master (git ls-remote, 2026-10-07).
|
||||
git push origin HEAD:master
|
||||
if ($LASTEXITCODE -ne 0) { throw 'push failed' }
|
||||
Write-Host "Published the wiki at $env:WIKI_REF"
|
||||
@@ -0,0 +1,171 @@
|
||||
# Accessibility
|
||||
|
||||
FrameLedger should be usable by everyone who plays games on a Windows PC — with a keyboard alone, with a screen reader,
|
||||
with a Windows contrast theme or Magnifier, and without telling colours apart. This page says what FrameLedger aims
|
||||
for, what works today, how that was checked, what does not work yet and what to do instead, and how to tell us about a
|
||||
barrier. It is written for the person who has just met one; the details for developers are in
|
||||
[`docs/08_UI.md`](docs/08_UI.md#accessibility).
|
||||
|
||||
FrameLedger is a desktop program: its own window, its dialogs, its document windows, the icon by the clock and the
|
||||
notices Windows shows for it. It draws nothing inside a game, so it cannot make a game itself any easier to use.
|
||||
|
||||
*Beta software: this page describes version 0.1.0-beta.45. In the app: Help ▸ Accessibility.*
|
||||
|
||||
## What FrameLedger aims for
|
||||
|
||||
- **WCAG 2.2 at level AA**, applied to desktop software as W3C's
|
||||
[WCAG2ICT](https://www.w3.org/TR/wcag2ict-22/) guidance explains. This is a goal that guides the work, not a claim:
|
||||
no formal evaluation has been made, and FrameLedger does not say it conforms to any standard.
|
||||
- **Every task can be done with the keyboard alone.**
|
||||
- **A screen reader can read every control and every value**, in the language FrameLedger is shown in, and hears what
|
||||
changes — a notice, a result.
|
||||
- **Text and controls keep their contrast** in the light and the dark theme and under Windows contrast themes, and
|
||||
**colour is never the only way something is shown.**
|
||||
- **Everything stays sharp at any display scale**, and when the window moves between screens.
|
||||
|
||||
## What works today
|
||||
|
||||
### The keyboard
|
||||
|
||||
| Keys | What they do |
|
||||
|---|---|
|
||||
| **Ctrl+1** … **Ctrl+5** (also with the numeric keypad) | Open Dashboard, Games, Compare, Logs and Settings, and move the keyboard into that page; a screen reader hears its title. **Ctrl+6** opens Advanced the same way while Advanced metrics is switched on, and does nothing while it is off. |
|
||||
| **Alt** or **F10**, then the arrow keys and **Enter** | Move to the menus. **Alt** with a menu's underlined letter opens it (*File*, *Tools*, *Help* in English). |
|
||||
| **Tab** and **Shift+Tab** | Move through a page or a dialog in reading order. |
|
||||
| The **arrow keys**, **Home**, **End**, **Page Up**, **Page Down** | Move inside a list or a table — a game's sessions, the games list, the Compare list, the import checklist. |
|
||||
| **Enter** or **Space** | Press the button, switch or box that has the focus. **Enter** on a game in the list opens its page. |
|
||||
| **Esc** | Closes a dialog the way its **Close** or **Cancel** button does: nothing is changed. A dialog that has no Close button waits for an answer, and the terms window has its own **Decline** and **Accept**. |
|
||||
| **Enter** in the hooking warning | Switches hooking on once the phrase is typed exactly; before that it does nothing. |
|
||||
| On a chart: the **arrow keys**, **Ctrl** with an arrow, **A** | Tab reaches every chart. The arrows move its view, Ctrl with an arrow zooms, A shows all of it again (so does a double-click); the page around it stays put. |
|
||||
|
||||
The same keys are in the user guide, [The screens](guide/07-screens.md#keyboard-and-mouse).
|
||||
|
||||
### Screen readers
|
||||
|
||||
- **Every page, menu, dialog and setting can be reached and used with Narrator.** The owner checked this on
|
||||
2026-11-09, keyboard only with the mouse disconnected, on 0.1.0-beta.34 and 0.1.0-alpha.3, and found no fault.
|
||||
- **Every page has headings**: its title is a heading of the first level, each section one of the second, so a screen
|
||||
reader's heading keys move from section to section.
|
||||
- **Every chart says what it is and where its numbers are written as text**, and which keys move it.
|
||||
- **Every button, switch and box that shows no text of its own has a name**, from the same translations as the screen.
|
||||
- **Lists, drop-down options and table cells are read by the words they show**, and a button repeated on each row names
|
||||
its row — *Open: 11/9/2026 14:03*, *Play: Cyberpunk 2077*, *Turn off: Cyberpunk 2077*.
|
||||
- **The frame-rate readout says the game's own frames, the displayed frames and the frame-generation factor together**
|
||||
(*Native 62 FPS, displayed 118 FPS, frame generation ×1.9*) — never the larger number alone; a ray-tracing chip says its
|
||||
value and where it came from (*Ray Tracing: Yes, measured*).
|
||||
- **What appears is said as it appears**: a safety notice (hooking refused, measuring stopped, hooking turned off), the
|
||||
capture agent going away and coming back, an update's steps, a short message at the bottom of the window, a notice on a
|
||||
game's page and a result of **Tools ▸ Database maintenance** — in the words shown, while FrameLedger's window is the
|
||||
active one. While a game has the screen nothing interrupts it; the notice stays in the window, and Windows' own
|
||||
notifications from the icon by the clock are read by the screen reader itself.
|
||||
- **The notices above the page can be read where they are shown**, and the button that answers one says which notice it
|
||||
answers.
|
||||
- **Tab goes from control to control**: pictures, lists and the rows of Settings are not stops of their own.
|
||||
- **Dialogs say they are dialogs**, keep the focus inside them until they close, and then give it back to the control
|
||||
that opened them. A message box opens over FrameLedger's window, never behind it.
|
||||
|
||||
### Seeing the screen
|
||||
|
||||
- **Light, dark, or the same as Windows** (Settings ▸ Theme). FrameLedger takes every colour from the theme, and every
|
||||
text is measured against what is painted under it, in both themes.
|
||||
- **Windows contrast themes** (Settings ▸ Accessibility ▸ Contrast themes) — Aquatic, Desert, Dusk, Night sky, or one
|
||||
whose colours you changed: every colour in the window becomes one of the theme's, whatever Settings ▸ Theme says, as
|
||||
soon as you turn one on, edit it or turn it off. The charts draw in its colours too, their lines and marks still told
|
||||
apart by pattern, and Settings ▸ Theme says a contrast theme is in use.
|
||||
- **The colour a game's picture lends its page** is used only as far as every text on it still reads, and never under a
|
||||
contrast theme.
|
||||
- **Windows display scaling** at any size, on every screen; **Magnifier** (Windows logo key + Plus) works as with any
|
||||
program.
|
||||
- Labels such as *Hooking on* and *Not installed*, and the ray-tracing chips, always carry their words; a chip that reads
|
||||
*N/A* is also drawn with a dashed edge.
|
||||
- **No chart tells two series apart by colour alone**: its lines are solid, dashed or dotted, its points circles,
|
||||
triangles or squares, its shaded stretches striped or dotted.
|
||||
|
||||
### Languages
|
||||
|
||||
FrameLedger is shown in English, Vietnamese or Japanese (Settings ▸ Language), and the names a screen reader reads come
|
||||
from the same translations. The documents — the user guide, this page, the legal texts — are in English.
|
||||
|
||||
## How it is checked
|
||||
|
||||
- **On every build**, by the project's own tests: what a screen reader is given for every page, window and dialog —
|
||||
every place Tab stops has a name, no list or table item is read by its program name, no text is hidden from a screen
|
||||
reader inside a control, no two buttons in a list share a name; each thing that appears is said once, in its words;
|
||||
every page has one first-level heading and every section title a level; no chart tells two series apart by colour
|
||||
alone; a chart's keys move it and stay its own; every control that shows no text has a name; no colour is written
|
||||
into a screen; every text reads against its background in both themes and after a theme switch, and under Windows'
|
||||
four contrast themes and two edited ones is drawn in the theme's own colours at 4.5:1 or better; **Esc** closes the
|
||||
open dialog without an answer, and a dialog gives the focus back; **Ctrl+1** … **Ctrl+5** open the pages in their
|
||||
order and move the keyboard into them, and **Ctrl+6** the Advanced page only while its option is on; a page slides in only while Windows' animation effects are on; the program
|
||||
declares it follows each screen's scaling.
|
||||
- **By hand**: the owner's pass of 2026-11-09 above, repeated for each release that changes a screen.
|
||||
- **Not tested yet**: NVDA, JAWS, Voice Access, touch, Windows 10, and other people's PCs. They should work through the
|
||||
same Windows interface Narrator uses, but nobody has checked. Contrast themes are checked by the tests above and have
|
||||
not yet been looked at on a screen.
|
||||
|
||||
## Known limitations
|
||||
|
||||
Each one with what to do instead. A barrier that is not on this list is worth reporting.
|
||||
|
||||
- **The Advanced page's "This PC" does not announce its readings as they change.** They change every second; a
|
||||
screen reader reads the table when you move through it, and each row says its reading, its value and the time it
|
||||
was read at.
|
||||
- **A chart's points cannot be read one by one.** A screen reader hears the chart's name and where its numbers are:
|
||||
a session's figures and *Statistics per series* in its summary, the table under the Compare chart, the Sessions table
|
||||
and the list of changes under a trend chart, and **File ▸ Export ▸ Session CSV** or **Session JSON**.
|
||||
- **In the user guide and the other documents the app shows, headings are read as ordinary text**: Windows' document
|
||||
view gives them no heading role. Their links and their order work as on any page.
|
||||
- **The short messages at the bottom of the window close after four seconds**, and cannot be read again once closed. A
|
||||
screen reader is told each one as it appears.
|
||||
- **Windows' text size setting** (Settings ▸ Accessibility ▸ Text size) **is not followed.** Use display scaling
|
||||
(Settings ▸ System ▸ Display ▸ Scale) or Magnifier.
|
||||
- **Pausing capture is only in the menu of the icon by the clock.**
|
||||
- **The windows Windows itself shows** — choosing a file, the administrator prompt — are Windows', not FrameLedger's.
|
||||
|
||||
## Report an accessibility problem
|
||||
|
||||
1. Open an issue with the
|
||||
[Accessibility problem form](https://github.com/poli0981/frameledger/issues/new?template=accessibility.yml).
|
||||
2. Say what you were trying to do and what happened instead; your FrameLedger version (Help ▸ About) and your Windows
|
||||
version; and what you use — the keyboard alone, Narrator, NVDA, JAWS, Magnifier, a contrast theme — with its version.
|
||||
The steps to get there help, and so does a screenshot or a recording, but neither is required. **You never need to
|
||||
tell us anything about yourself or a disability.**
|
||||
3. If you want to attach details from your PC, **Help ▸ Report a bug** builds them into a file on your PC and shows you
|
||||
what is inside first; nothing is uploaded by itself.
|
||||
|
||||
**A safety notice you could not perceive** — hooking refused, measuring stopped or hooking turned off, without your
|
||||
knowing — is a safety problem as well: say so in the report, and it is handled first.
|
||||
|
||||
### How serious it is
|
||||
|
||||
You do not have to choose; the maintainer sets it when reading the report.
|
||||
|
||||
| Severity | What it means | For example |
|
||||
|---|---|---|
|
||||
| **Critical** | A task cannot be done at all. | Hooking cannot be switched off with the keyboard; the terms window or the hooking warning cannot be answered; a safety notice cannot be read. |
|
||||
| **Serious** | It can be done only with great difficulty or a workaround. | A value can be read only by exporting the session. |
|
||||
| **Moderate** | It is tiring or inconsistent. | A name that differs from what the screen shows; an extra stop for Tab. |
|
||||
| **Minor** | It barely gets in the way. | A tooltip the keyboard cannot reach, when its words are shown elsewhere too. |
|
||||
|
||||
### What happens next
|
||||
|
||||
FrameLedger has one maintainer, so there are no promised times. Every report is read and answered, without doubting what
|
||||
you describe. Critical problems come before other work; a workaround, when there is one, is written on the issue; the
|
||||
fix ships in a release, and the issue is closed once you say it works for you — or when a fix has been out for a while
|
||||
and nobody has answered.
|
||||
|
||||
## Who looks after this
|
||||
|
||||
The project's owner, poli0981, keeps this page and the checks behind it, and reviews both for each release that changes
|
||||
a screen. A change to FrameLedger that moves anything on this page changes the page in the same pull request.
|
||||
|
||||
## For contributors
|
||||
|
||||
A change to the App keeps what the tests above hold: a name, from the translations in all three languages, for every
|
||||
control that shows no text; colours only from the theme. Say in the pull request what you checked with the keyboard
|
||||
and with Narrator. The rules and the checks are in [`docs/08_UI.md`](docs/08_UI.md#accessibility) and
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
## Feedback
|
||||
|
||||
To improve this page, open an issue or a pull request. A barrier goes through the form above, so that it is not lost.
|
||||
+87
-5204
File diff suppressed because it is too large.
Load diff
@@ -16,19 +16,24 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
> **Amended 2026-09-22 (owner decision): the override of 2026-09-21 is withdrawn, and the sentence above is the rule again.** For one day (releases `0.1.0-beta.3` and `beta.4`) a per-game override existed. The owner withdrew it: no entry point, no message, no column (schema 0008 drops 0007's five), no string. Do not add one in any form.
|
||||
>
|
||||
> **A finding turns the game's hooking off** (`19_SAFETY` §What a finding does to the game). An anti-cheat named in the game itself — its process, its title lists, its folder — is written to the row exactly as the pre-scan always wrote it (`hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`), and since 2026-09-22 also when the guard finds it at a session's start or at the 30 s re-scan (`AntiCheatVerdict.IsFindingAboutTheGame`). A machine-wide driver or service refuses that session only. The notice, the game's page, the session's notes and the Agent's log all say it happened. Nothing clears the block, as before.
|
||||
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
|
||||
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree *(within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder)*, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
|
||||
> **Amended 2026-10-03 (owner decision D38): the evidence moved from before the grant to its trial.** "≥ 2 successful Tier-1 sessions" above could never be met by a game blocked at add time — since beta.8 that is every blocked game — nor after a ledger reset. Asked with that, the owner chose: a grant needs no session; the first two hooked sessions under it are a trial, and any end during the trial (a crash, a safety unhook, a floor stop, a new finding, or a stored hooked session with no frames or an abnormal exit) ends the exception **for good** (`games.ac_exception_trial_failed_at`, schema 0017, never cleared). Every other condition above is unchanged, and so is the last sentence.
|
||||
3. **Never implement evasion.** No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented `LoadLibraryW`. The DLL keeps its real name, real exports, and version info. A performance tool must be *visible* to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle.
|
||||
4. **Never read or write game memory outside our own hooks.** We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
|
||||
|
||||
> **Amended 2026-11-13 (owner decision D132): a driver's read-only getter, with the device of the swap chain we hook.** Asked with this rule quoted, the owner ruled that calling NVIDIA's two latency getters (`NvAPI_D3D_GetLatency`, `NvAPI_D3D_GetSleepStatus`) with the device behind a swap chain the Overlay hooks is inside this rule: it reads the driver's report, not game memory, and writes nothing. **Nothing shipped does it yet**: a spike on `hook-harness` and a stub comes first (`spike-notes` §31), and a release that carries it needs the owner's go on that result. Getters only, never a setter, a marker or a sleep, and never a call that loads `nvapi64.dll` into a game.
|
||||
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.
|
||||
>
|
||||
> **Amended 2026-09-06 (Leg 0 landed): narrowed, not withdrawn.** `sl.dlss_g.dll` is a startup-time load on that title (frame generation off, census unchanged, twice), and the same morning's ×4 capture measured the discriminator the gate lacked: the 2.8.0 pacer's generated presents are DXGI presents on the hooked chain (§H5 row P1-DXGI), counted through `dxgiUnseen` into `Native 70.52 → Displayed 282.08 (×4 FG)`. So a counted `none` beside a READ `IDXGISwapChain::GetLastPresentCount` with zero unseen is `none`, printed with DXGI's agreement; it is withheld only when the counter was not read.
|
||||
>
|
||||
> **Amended 2026-09-17 (owner decision): the steady state.** A session whose frame-generation state changed (menus, loading, a settings change) has no session-wide factor — averaging ×1 menus with ×4 gameplay is the inflated-or-deflated single number this rule forbids — but it is no longer left with none: *Native → Displayed (×N FG)* is shown for the state the session spent most of its generating time in, **always with the share of the session it covers** (`62 → 118 FPS (×1.9 FG · 75%)`), never as a session average (`docs/03_METRICS.md` §The steady state).
|
||||
>
|
||||
> **Amended 2026-10-19 (owner decision D62): the mix.** Beside the steady state, the session summary lists every frame-generation state the session held — each with its own *Native → Displayed*, its factor and its share of the presenting time (`×4.0 frame generation · 35.33% · 70 → 282 FPS`) — then the time with no frame generation and the time no state claims. Every row is one state's own numbers; nothing is averaged across states, and a state's factor never appears without its rates (`docs/03_METRICS.md` §The mix).
|
||||
7. **RT / PT / RR are tri-state** (`Yes` / `No` / `N/A`) with manual override. They are now *measured*, not guessed — but where measurement is genuinely impossible, the honest answer is still `N/A`. Never fabricate `Yes`.
|
||||
|
||||
> **Amended 2026-08-20 with the PR that wrote the hooks, per the owner ruling of 2026-08-14.** This rule named *"inline RayQuery without DXIL scan"* as one of the impossible cases, and that conflated two questions. **Whether rays are being traced is measurable** — `BuildRaytracingAccelerationStructure` is called by RayQuery titles and by `DispatchRays` titles alike, which is why both hooks exist and why the `No` branch requires the AS-build hook to have been *installed*. What needs a DXIL scan is **classifying the technique as RayQuery**, and that stays `N/A`. So the impossible cases are: naming the technique, and path-tracing classification, which has no API-level signature at all (`03_METRICS` §RT/PT/RR — a confidence score that may only ever *suggest*).
|
||||
@@ -39,14 +44,15 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
|
||||
| Concern | Choice |
|
||||
|---|---|
|
||||
| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md` |
|
||||
| Managed runtime | .NET 11 (STS, pinned via `global.json`: the 11.0 SDK band) and C# 15 since 0.1.0-beta.37 (owner decisions D94 and D96, 2026-11-11; .NET 10 and C# 14 until beta.36), TFM `net11.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (NFR-8 as D95 amended it: Windows 11 is the supported platform; Windows 10 22H2 is not blocked, and is neither tested nor supported), x64 only — `docs/12_BUILD.md` §The main line's .NET. No preview feature (`runtime-async`, the updated memory-safety rules). **No C# 15 construct is used yet** — collection expression arguments, `closed`, `union`, labeled jumps: a construct is used only where the build, CodeQL and Qodana all read it, and Qodana's engine reads none of the four (`docs/13_CI_CD.md` §C# 15 and the analyses). .NET 11's API is used freely. **The `alpha` branch** (D73–D76, 2026-10-31) builds a released beta's source to try a newer .NET; it rests since 0.1.0-alpha.4 (D98) and then differs from main in `RELEASE_LINE` alone — `docs/12_BUILD.md` §The alpha line |
|
||||
| Native | **C++20, MSVC v143+, `/MT` static CRT, `/GS`, `/guard:cf`, no RTTI, no C++ exceptions in hook paths** |
|
||||
| Hooking | **MinHook** (BSD-2-Clause) for inline hooks; direct vtable-entry swap for COM interfaces |
|
||||
| Vulkan | **Implicit Vulkan layer** (`VK_LAYER_FRAMELEDGER_overlay`), not hooking — `17_HOOK_ENGINE` §Vulkan |
|
||||
| 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 |
|
||||
| GPU telemetry | 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 |
|
||||
| Markdown in the App | **Markdig** (BSD-2-Clause, pinned ~~1.4.0~~ 1.5.0 since beta.31 — 1.4.2 in beta.30) → WPF `FlowDocument`, HTML off, no image fetched — the Legal Gate, the user guide, Help ▸ Limitations, Help ▸ Accessibility (beta.35, D88), 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 |
|
||||
| Storage | SQLite via Microsoft.Data.Sqlite + Dapper (no EF) |
|
||||
@@ -61,14 +67,31 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
|
||||
```
|
||||
FrameLedger.slnx # XML solution format (SDK default since .NET 10)
|
||||
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
|
||||
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
|
||||
LIMITATIONS.md ACCESSIBILITY.md # what the software cannot do; the accessibility statement (D36, D88)
|
||||
global.json # pins the SDK band — see 12_BUILD
|
||||
RELEASE_LINE # `main`, or `alpha` on the alpha branch (D73, 2026-10-31) — 12_BUILD §The alpha line
|
||||
build.ps1 # the quality gate; CI runs this identical script
|
||||
SonarQube.Analysis.xml # SonarCloud's settings for ci.yml's sonarcloud job (D68, 2026-10-25; it replaced
|
||||
.config/dotnet-tools.json # .sonarcloud.properties) and the scanner it runs — 13_CI_CD §SonarCloud
|
||||
qodana-native.yaml # the same for the native job: the C++ of src/native, through the Visual Studio solution
|
||||
# CMake writes for it (preset x64-vs-analysis), a report of its own (D99)
|
||||
qodana.yaml # Qodana's settings for the managed job of .github/workflows/qodana.yml (D93; Qodana for
|
||||
# .NET on the Ultimate licence since 2026-11-11, D99): the linter, the solution, a gate
|
||||
# of zero problems, and what is switched off that .editorconfig has no key for —
|
||||
# ReSharper's inspections are .editorconfig's resharper_* keys (D100) — 13_CI_CD §Qodana
|
||||
src/
|
||||
native/
|
||||
FrameLedger.Overlay/ # C++20 DLL injected into the game (hooks + ring writer + optional overlay)
|
||||
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe
|
||||
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe; also builds
|
||||
# FrameLedger.Guard.dll, the guard's C ABI the Agent loads (line added 2026-10-14)
|
||||
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 three 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
|
||||
@@ -82,12 +105,42 @@ src/
|
||||
# composes it from, SessionEndReason, the census/NGX/marker facts;
|
||||
# and Recording/ since 2026-09-10 (PR-D): SessionRecorder,
|
||||
# SessionAggregator + FgLadder, SessionFinalizer, the .partial
|
||||
# writer and PartialRecovery, ExitStatusMapper, the crash policy
|
||||
# writer and PartialRecovery, ExitStatusMapper, the crash policy;
|
||||
# and Advanced/ since 2026-11-11 (D101): AdvancedMetricCatalog, the one
|
||||
# list "Advanced metrics" reads - what is read, and what is not with the
|
||||
# reason (18_GPU_VENDOR_APIS §Advanced metrics) - and the value model
|
||||
# (AdvancedValue / AdvancedFact / AdvancedReading / AdvancedSnapshot) and
|
||||
# the port IAdvancedHardware. Infrastructure implements it: AdvancedHardwareHub
|
||||
# (one reader for the Agent, on its own thread, only while held - D107) over
|
||||
# NvapiAdvancedReader (the bridge's ABI 3) and LhmAdvancedReader (LhmGroups:
|
||||
# the card; as administrator with PawnIO the processor, memory and board -
|
||||
# never storage, D103). The Agent composes it since the switch, `telemetry.advanced`
|
||||
# (PR-5, 2026-11-11: off by default; on, a session holds the hub), and
|
||||
# Ipc/AdvancedMachineResponder answers GetAdvancedMachine from the hub's last
|
||||
# snapshot - each request is the page's hold on it (PR-6, D107). Recording/
|
||||
# AdvancedSessionBuilder stores what a session's samples carried (schema 0023:
|
||||
# machine_profiles + session_advanced, adv.* series with NaN for a gap, D102).
|
||||
# Train B (0.1.0-beta.40, D111): Capture/InGameAdvancedSampler turns the shared
|
||||
# memory's region 5 - what a hooked game told DLSS and FSR, read by the Overlay
|
||||
# only while the session asks (ICaptureObserver.WantsInGameAdvanced) - into session
|
||||
# facts and two adv.* series; reach `Game` in the catalog; no schema change.
|
||||
# Since 0.1.0-beta.43 also what the game tells Streamline each frame and how it
|
||||
# configures FSR frame generation, from two calls hooked only once Advanced has been
|
||||
# asked for; AdvancedInGameCall says of each: read, never called, or not hooked.
|
||||
# Since 0.1.0-beta.44 also what Streamline answers when the game asks about a
|
||||
# feature (its version, what it requires), from two more calls hooked the same
|
||||
# way; ~~a game asks while it starts, so "never called" is the usual answer there~~
|
||||
# (the games run since ask again later, and are read).
|
||||
# Since 0.1.0-beta.45 also whether Streamline says a feature is supported and
|
||||
# loaded, the game switching it, its resources allocated and freed and Streamline
|
||||
# shut down, from six more calls hooked the same way (D130); slInit is not hooked
|
||||
# and its entry says why (AdvancedReach.BeforeAttach, D129).
|
||||
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
|
||||
# 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,
|
||||
@@ -104,7 +157,11 @@ src/
|
||||
# is built as of 2026-09-14 (PR-5 Games/Dashboard, PR-6 summary +
|
||||
# charts, PR-7 trend/compare, PR-8a Settings/safety notices/Logs/
|
||||
# --diag, PR-8b tray + the Agent's maintenance flags, PR-9 first run
|
||||
# + Legal Gate FR-11); Strings.resx en/vi/ja
|
||||
# + Legal Gate FR-11); Strings.resx en/vi/ja. The Advanced page
|
||||
# (2026-11-11, D101/D105: Pages/AdvancedPage, there and on Ctrl+6 only
|
||||
# while `telemetry.advanced` is on - 08_UI §Advanced). `--data-dir <copy>`
|
||||
# (beta.15, D52) = a VIEWER: no Agent started or contacted,
|
||||
# nothing on the PC changed, the profile's own folder refused
|
||||
FrameLedger.CaptureHost/ # UNSHIPPED, and since P2 PR-C (2026-09-09) a THIN SHELL: verbs,
|
||||
# the operator disclosure, the report consumer, and the composition
|
||||
# of Application.Capture.CaptureSession over Infrastructure's
|
||||
@@ -117,12 +174,28 @@ 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,
|
||||
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate),
|
||||
# buildid-check (beta.18: the release's build id in the shipped natives),
|
||||
# docs-split-check (beta.24, D66: CHANGELOG/HANDOFF and their parts agree),
|
||||
# agent-cost (D110, 2026-11-11: a developer tool, not a gate - what the shipped
|
||||
# Agent costs per second of session, Advanced metrics off and on),
|
||||
# nvapi-readonly-check (D108, 2026-11-11: every NVAPI call of the bridge is on
|
||||
# nvapi-allowed-calls.txt, and none there writes or identifies),
|
||||
# overlay-fields-check (D116, 2026-11-12: every member of a vendor's struct the
|
||||
# Overlay reads for Advanced metrics is in fl_adv_fields.h and on
|
||||
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere)
|
||||
# (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).
|
||||
@@ -130,19 +203,31 @@ 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.
|
||||
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
|
||||
# and the guide is the wiki's End-user part)
|
||||
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
|
||||
# publishes them with guide/, LIMITATIONS.md and ACCESSIBILITY.md to the Wiki tab at a release;
|
||||
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
|
||||
docs/ legal/ legal/licenses/
|
||||
```
|
||||
|
||||
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **Two facades since 2026-09-10:** `NativeAntiCheatGuard` (required — absent throws) and `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself), both by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why a third facade claims a name there rather than setting its own.
|
||||
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **~~Two~~ Three facades since ~~2026-09-10~~ 2026-10-03:** `NativeAntiCheatGuard` (required — absent throws), `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself) and, since beta.12 (D43), `NativeProcessStats` (optional — the game process's own memory, read from outside the game; absent reads N/A), all by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why the third facade claims a name there rather than setting its own.
|
||||
|
||||
## Coding conventions
|
||||
|
||||
**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# —** `Nullable enable`, `TreatWarningsAsErrors`, `AnalysisLevel latest-all`, file-scoped namespaces, Roslynator + Meziantou + VS Threading analyzers, `dotnet format` clean. Qodana reads the C# and the XAML in an advisory workflow of its own, with a gate of zero problems *(since 2026-11-10, D93; Qodana for .NET on the Ultimate licence since 2026-11-11, D99 — `13_CI_CD` §Qodana)*: fix what it reports, or switch the inspection off with the reason on the line above, **in the place the engine that raised it reads** *(D100)* — one of ReSharper's (C#, XAML, `.resx`, the C++) in `.editorconfig`; what has no key there (the hints as a severity, the Markdown and XML inspections, the files JetBrains' security rules were read in) in `qodana.yaml` — never anywhere else, never without a reason. A new file that starts a process fails `ProcessStartSitesTests`, and Qodana's security rule reports it: read what it starts and where the path and the arguments come from, then list it in the test, in `qodana.yaml` and in `13_CI_CD` §Qodana. 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)*. SonarCloud analyses the C++ too, from CMake's compilation database, in `ci.yml`'s advisory `sonarcloud` job *(since 2026-10-25, D68 — `13_CI_CD` §SonarCloud)*. Qodana reads it as well, in a report of its own *(since 2026-11-11, D99: ReSharper's C++ inspections and the clang-tidy checks they run, advisory, a gate of zero — `13_CI_CD` §Qodana)*: fix what it reports, or switch the inspection off in `.editorconfig` with the reason above it; **in code loaded into a game only a defect is fixed**, in a pull request of its own with the overhead measured *(D100)*.
|
||||
|
||||
**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.
|
||||
**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`~~ `FlShmHandshake`, `FlWriterState`, `FlControlBlock`, `FlDisplayState` (layout 4, beta.10), `FlAdvancedState` (layout 5, 2026-11-11, Advanced metrics train B), `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.
|
||||
|
||||
@@ -150,7 +235,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)
|
||||
|
||||
@@ -158,6 +243,8 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
|
||||
- Hook-path changes state measured overhead in the PR body (`14_TESTING` §Hook overhead).
|
||||
- Any new hook is listed in `17_HOOK_ENGINE` §Hook inventory and justified against rule 4.
|
||||
- New user-visible strings exist in `en`, `vi`, `ja`.
|
||||
- A change to what the App shows keeps `ACCESSIBILITY.md` §For contributors (names, theme colours, nothing by colour alone,
|
||||
keyboard reach) and updates that page when it moves what works or what does not (D88).
|
||||
- Any deviation from a doc updates that doc in the same PR.
|
||||
|
||||
## Reading order
|
||||
@@ -165,7 +252,10 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
|
||||
0. **`docs/HANDOFF.md` — what to do next and in what order.** It carries sequencing,
|
||||
decisions that live in no other file, and the traps that cost a cycle each. It
|
||||
deliberately carries **no status**: it points at the four files that do. Start there
|
||||
if you are picking up work; start at 1 if you are learning the system.
|
||||
if you are picking up work; start at 1 if you are learning the system. *(Since beta.24, D66, the history of every
|
||||
train, the passed owner-only items and the traps live in `docs/handoff/`; HANDOFF.md's §How this file is split and
|
||||
§Decisions index resolve every old citation. CHANGELOG.md likewise keeps `[Unreleased]` and links each release's
|
||||
file under `docs/changelog/`.)*
|
||||
1. `docs/19_SAFETY_AND_ANTICHEAT.md` — the guard, the refusal list, what we will not build
|
||||
2. `docs/01_ARCHITECTURE.md` — processes, injection flow, lifecycle
|
||||
3. `docs/02_SPEC.md` — FR/NFR ids used everywhere
|
||||
@@ -176,8 +266,16 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
|
||||
8. `docs/18_GPU_VENDOR_APIS.md` — layered GPU telemetry (DXGI/PDH · LHM · NVAPI) + vendor-SDK licence rules
|
||||
9. `docs/06_DATA_MODEL.md` · `docs/07_IPC.md` · `docs/08_UI.md` · `docs/16_WPFUI_SYNTAX.md`
|
||||
10. Remaining (`09`–`15`).
|
||||
11. **`LIMITATIONS.md`** (repository root; shown in the App under Help ▸ Limitations) — what the WHOLE software cannot
|
||||
do, in the user's words, each item linked to its details. When a change moves a limit, the page changes in the same
|
||||
PR (D36, 2026-09-27). **`ACCESSIBILITY.md`** (repository root; Help ▸ Accessibility) — the accessibility statement:
|
||||
WCAG 2.2 AA through WCAG2ICT as a goal, never a claim; what works with the keyboard, a screen reader and contrast
|
||||
themes, what does not, how a barrier is reported (D88, 2026-11-09); `docs/08_UI.md` §Accessibility holds its checks.
|
||||
**`docs/LIST_GAME_TESTED.md`** — the real games FrameLedger has been run with and what each
|
||||
session measured, from a copy of the owner's ledger and the repository's own evidence (D35).
|
||||
|
||||
**Before writing native or capture code, read `docs/20_OPEN_QUESTIONS.md`.** It
|
||||
**Before writing native or capture code, read `docs/20_OPEN_QUESTIONS.md`** (its open entries; since beta.24 the
|
||||
resolved ones are in `docs/open-questions/`, a table at the end of each series lists them). It
|
||||
lists the defects and gaps that survived the doc audit — things the other
|
||||
documents cannot answer because they need an empirical result or a decision. The
|
||||
S-series items are safety items and block the first real injection. If you are
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Code of conduct
|
||||
|
||||
FrameLedger adopts the **[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)**
|
||||
(© Contributor Covenant contributors, licensed CC BY 4.0) as its code of conduct, for everyone who takes part in the
|
||||
project — in issues, pull requests, discussions and any other project space.
|
||||
|
||||
In short: be respectful and welcoming, criticise ideas rather than people, and do not harass, insult or demean anyone.
|
||||
The full text linked above is the code; this summary does not replace it.
|
||||
|
||||
## Reporting
|
||||
|
||||
Report behaviour that breaks the code to the maintainer at **contact@poli0981.dev**. Reports are read in confidence,
|
||||
and the maintainer decides on the response in line with the Covenant's enforcement guidelines — from a private note to
|
||||
a ban from the project's spaces.
|
||||
@@ -0,0 +1,88 @@
|
||||
# Contributing to FrameLedger
|
||||
|
||||
Thank you for looking. FrameLedger is a small project with strict rules, because it loads code into games and a mistake
|
||||
can cost a user their account. This page says how to build it, what a change has to bring with it, what will not be
|
||||
merged, and under what licence your contribution is accepted.
|
||||
|
||||
## Before you start
|
||||
|
||||
- **Read `CLAUDE.md`'s *Non-negotiable rules* and `docs/19_SAFETY_AND_ANTICHEAT.md` first.** They constrain everything
|
||||
that touches a game.
|
||||
- **Open an issue before anything larger than a fix**, so the approach can be agreed before the work is done.
|
||||
- **A game with anti-cheat that FrameLedger fails to detect** is a safety bug: use the *Safety gap* issue form.
|
||||
- **A vulnerability in FrameLedger itself** goes the private route in `SECURITY.md`, never a public issue.
|
||||
- **Something that cannot be reached, read or seen** — with the keyboard, a screen reader, a contrast theme — uses the
|
||||
*Accessibility problem* form; `ACCESSIBILITY.md` says what the App aims for.
|
||||
- Everyone who takes part follows the `CODE_OF_CONDUCT.md`.
|
||||
|
||||
## Building
|
||||
|
||||
You need Windows 11 (x64), Visual Studio 2022 or later with the C++ workload (MSVC v143 or later), CMake 3.28 or later,
|
||||
PowerShell 7, and the .NET SDK that `global.json` pins — .NET 11 since 0.1.0-beta.37, which Microsoft does not support
|
||||
on Windows 10 Home or Pro. Then:
|
||||
|
||||
```powershell
|
||||
./build.ps1 check
|
||||
```
|
||||
|
||||
That is the whole quality gate, and continuous integration runs the identical script: the native build and its tests,
|
||||
`clang-format`, the managed build with warnings as errors, `dotnet format`, every test project, and the repository's own
|
||||
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
|
||||
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
|
||||
|
||||
Documentation lives in three places: `guide/` for players (shown in the app and on the wiki), `wiki/` for the wiki's own
|
||||
pages, and `docs/` for developers. A change a player would notice updates `guide/`; a change to how the code is put
|
||||
together updates `docs/` — and the `wiki/` page that summarises it, if that page now says something else.
|
||||
`./build.ps1 check` builds the wiki and fails on a link that leads nowhere.
|
||||
|
||||
Never point a build of your own at the data FrameLedger records into (`%LOCALAPPDATA%\FrameLedger`): a newer build
|
||||
migrates the database, and the released one cannot read it back. To look at real data, copy the folder and start
|
||||
`FrameLedger.exe --data-dir <copy>` — a viewer that starts no Agent and changes nothing on the PC (`docs/12_BUILD.md`
|
||||
§Debugging says how to copy it safely).
|
||||
|
||||
## What a pull request brings with it
|
||||
|
||||
The definition of done is the one in `CLAUDE.md`:
|
||||
|
||||
- it builds without warnings (C# and C++), the tests are green, and `dotnet format` and `clang-format` are clean;
|
||||
- a change to the hook path states its measured overhead in the PR (`docs/14_TESTING.md` §Hook overhead);
|
||||
- a new hook is listed in `docs/17_HOOK_ENGINE.md` §Hook inventory and justified against rule 4;
|
||||
- every new user-visible string exists in `en`, `vi` and `ja` (`docs/09_I18N.md`);
|
||||
- a change to what the App shows keeps `ACCESSIBILITY.md` §For contributors — a name for every control that shows no
|
||||
text, theme colours only, nothing shown by colour alone, everything reachable by keyboard — and says in the PR what was
|
||||
checked with the keyboard and Narrator; if it moves what works or what does not, `ACCESSIBILITY.md` changes with it;
|
||||
- a change that makes a document wrong updates that document in the same PR;
|
||||
- a change under `src/` adds an entry under `## [Unreleased]` in `CHANGELOG.md`;
|
||||
- every new source file carries the licence header — `./tools/notice-check.ps1 -Fix` writes it. A file you wrote
|
||||
yourself may name you in its second line instead, in the same form:
|
||||
`Copyright (C) <year> <your name> - additional terms under GPLv3 section 7: see NOTICE`.
|
||||
|
||||
The pull-request template lists the safety checks for changes to the capture layer, and the accessibility checks for
|
||||
changes to the user interface.
|
||||
|
||||
## What will not be merged
|
||||
|
||||
Whatever its other merits, a change that
|
||||
|
||||
- adds any way to override, weaken or skip the anti-cheat guard (rule 2);
|
||||
- makes FrameLedger harder to detect — manual mapping, header erasure, thread hiding, unlinking modules, obfuscation,
|
||||
renamed binaries (rules 3 and 9);
|
||||
- reads or writes game memory outside the hooked calls (rule 4), or makes a hook able to crash a game (rule 5);
|
||||
- adds telemetry, analytics or any network request beyond the ones `legal/PRIVACY_POLICY.md` lists (rule 8);
|
||||
- turns injection on for a game the user did not individually enable (rule 1).
|
||||
|
||||
## Licensing of contributions
|
||||
|
||||
FrameLedger is licensed under the GNU GPL, version 3 only, with the additional terms in `NOTICE`. **By opening a pull
|
||||
request you confirm that you have the right to submit the change, and you license it under GPL-3.0-only, with the
|
||||
additional terms in `NOTICE` (GPLv3 §7 (b), (c) and (e)) applying to it as they apply to the rest of FrameLedger's own
|
||||
material.** There is no contributor licence agreement and no copyright assignment: you keep the copyright in your
|
||||
contribution. Code from elsewhere must come with a licence compatible with GPL-3.0-only and be listed in
|
||||
`legal/THIRD_PARTY_NOTICES.md`.
|
||||
|
||||
Changes written with AI assistance are welcome on the same terms — you are responsible for what you submit, as for any
|
||||
other change.
|
||||
|
||||
## Questions
|
||||
|
||||
Open an issue, or write to contact@poli0981.dev.
|
||||
+74
-6
@@ -8,12 +8,14 @@
|
||||
- TargetFramework's platform version selects which Windows API
|
||||
projections are available to compile against.
|
||||
- SupportedOSPlatformVersion is the floor CA1416 enforces.
|
||||
NFR-8 requires Windows 10 22H2 = build 19045. Letting the supported version
|
||||
default to the TFM's 19041 would silently accept installs three releases
|
||||
below the stated floor.
|
||||
NFR-8 names Windows 10 22H2 = build 19045 as the oldest Windows the code is
|
||||
held to (since 2026-11-11, D95: not blocked there, and neither tested nor
|
||||
supported - Microsoft supports .NET 11 on Windows 11). Letting the supported
|
||||
version default to the TFM's 19041 would silently accept installs three
|
||||
releases below that floor.
|
||||
|
||||
A bare `net10.0-windows` is wrong for a different reason: it resolves to
|
||||
net10.0-windows7.0, and CA1416 would then error on Mica, MiniDumpWriteDump
|
||||
A bare `net11.0-windows` is wrong for a different reason: it resolves to
|
||||
net11.0-windows7.0, and CA1416 would then error on Mica, MiniDumpWriteDump
|
||||
and IDXGIAdapter3::QueryVideoMemoryInfo — every Windows-10-era API this
|
||||
application is built on.
|
||||
|
||||
@@ -25,7 +27,9 @@
|
||||
nothing and CA1416 still enforces the 19045 floor at the API level.
|
||||
-->
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
|
||||
<!-- .NET 11 since 0.1.0-beta.37 (owner decision D94, 2026-11-11; docs/12_BUILD.md). net10.0 until then, and
|
||||
net11.0 on the alpha branch from 2026-10-31. -->
|
||||
<TargetFramework>net11.0-windows10.0.22621.0</TargetFramework>
|
||||
<SupportedOSPlatformVersion>10.0.19045.0</SupportedOSPlatformVersion>
|
||||
|
||||
<!-- x64 only (CLAUDE.md pinned stack, NFR-8). Previously asserted in prose
|
||||
@@ -67,8 +71,72 @@
|
||||
<FrameLedgerVersionFile>$(MSBuildThisFileDirectory)VERSION</FrameLedgerVersionFile>
|
||||
<Version Condition="'$(Version)' == '' And Exists('$(FrameLedgerVersionFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerVersionFile)').Trim())</Version>
|
||||
<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
|
||||
|
||||
<!-- D73 (2026-10-31): the RELEASE LINE, from the RELEASE_LINE file beside VERSION - `main`, the betas and releases on
|
||||
the .NET that global.json pins, or `alpha`, a beta's source built to try a newer .NET from the long-lived `alpha`
|
||||
branch, where this file and global.json are two of the few lines that differ while it does (docs/12_BUILD.md
|
||||
§The alpha line).
|
||||
Not a property a command line sets: the file is the one source, release.yml refuses a tag that disagrees with it,
|
||||
and the target below refuses a value that is neither line. Every assembly carries it (the ItemGroup below), and
|
||||
Shared.BuildLine reads it at run time. -->
|
||||
<FrameLedgerReleaseLineFile>$(MSBuildThisFileDirectory)RELEASE_LINE</FrameLedgerReleaseLineFile>
|
||||
<FlReleaseLine Condition="Exists('$(FrameLedgerReleaseLineFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerReleaseLineFile)').Trim())</FlReleaseLine>
|
||||
|
||||
<!-- D98 (2026-11-11): THE ALPHA LINE RESTS - the betas build on the same .NET as the newest alpha (0.1.0-alpha.4,
|
||||
.NET 11.0.0), so no alpha is cut until a newer .NET is tried. An alpha built while this says true tells its user
|
||||
that the line is paused and to install the beta: a resting alpha gets no update, its anti-cheat list included
|
||||
(Shared.AlphaLine, App/Services/AlphaTexts). Stamped on both lines, read by an alpha alone. When the `alpha`
|
||||
branch starts trying a newer .NET it sets this to false there - one more line of its switch (docs/12_BUILD.md
|
||||
§The alpha line). -->
|
||||
<FlAlphaLineRests>true</FlAlphaLineRests>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<AssemblyMetadata Include="FrameLedger.ReleaseLine" Value="$(FlReleaseLine)" />
|
||||
<AssemblyMetadata Include="FrameLedger.AlphaLineRests" Value="$(FlAlphaLineRests)" />
|
||||
</ItemGroup>
|
||||
|
||||
<Target Name="FrameLedgerReleaseLineCheck" BeforeTargets="BeforeBuild" Condition="'$(FlReleaseLine)' != 'main' And '$(FlReleaseLine)' != 'alpha'">
|
||||
<Error Text="RELEASE_LINE at the repository root must say 'main' or 'alpha', and it says '$(FlReleaseLine)' (docs/12_BUILD.md §The alpha line)" />
|
||||
</Target>
|
||||
|
||||
<!-- The NuGet audit (2026-10-25, docs/13_CI_CD.md §Dependabot and the NuGet audit): every restore checks the WHOLE
|
||||
package graph, transitive packages included, against the advisory database, at every severity. These were the
|
||||
SDK's defaults for net10.0, written down so that a later SDK's defaults cannot move them. With
|
||||
TreatWarningsAsErrors, a vulnerable package is NU1901-NU1904 and the restore - and so the gate - is red, which
|
||||
is what happened with SQLitePCLRaw 2.1.11 (Directory.Packages.props). -->
|
||||
<PropertyGroup>
|
||||
<NuGetAudit>true</NuGetAudit>
|
||||
<NuGetAuditMode>all</NuGetAuditMode>
|
||||
<NuGetAuditLevel>low</NuGetAuditLevel>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- beta.14 (D50): every managed binary names the product and who wrote it, as the native ones always have
|
||||
(19_SAFETY: a binary says plainly what it is). Explorer's Properties > Details and Task Manager read these. Until
|
||||
beta.14 the SDK's defaults stood: the Agent's Company and Product read "FrameLedger.Agent", each library's its own
|
||||
assembly name, and no managed binary carried a copyright. The copyright is the native FL_COPYRIGHT
|
||||
(src/native/CMakeLists.txt) word for word: tools/versioninfo-check.ps1 reads both from the built binaries and is
|
||||
red when they differ. The file description is the AssemblyTitle - an entry point sets its own, a library keeps its
|
||||
assembly name - and the Description is the Comments field, the native blocks' sentence for a library. The SDK
|
||||
stamps RepositoryUrl into every assembly as AssemblyMetadata; it is the App's IssueLink.Repository, and the App's
|
||||
AssemblyIdentityTests holds the two equal (a fork changes both - FORKING.md). -->
|
||||
<PropertyGroup>
|
||||
<Company>FrameLedger</Company>
|
||||
<Product>FrameLedger</Product>
|
||||
<Authors>poli0981</Authors>
|
||||
<Copyright>Copyright (C) 2026 poli0981. GPL-3.0-only with additional terms: see NOTICE</Copyright>
|
||||
<Description>Performance measurement tool. Identifies itself deliberately; see https://github.com/poli0981/frameledger</Description>
|
||||
<RepositoryUrl>https://github.com/poli0981/frameledger</RepositoryUrl>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- beta.12: the source a build was made from - release.yml passes the tag (a rehearsal, its commit); a local build has
|
||||
none. The App's links into the repository open THIS version's documents with it (Services/RepositoryLinks.cs).
|
||||
Every assembly since beta.14 (D50), not the App's alone: the two publishes build the same libraries into one
|
||||
out/app, and release.yml passes the same ref to both. -->
|
||||
<ItemGroup Condition="'$(FrameLedgerSourceRef)' != ''">
|
||||
<AssemblyMetadata Include="FrameLedgerSourceRef" Value="$(FrameLedgerSourceRef)" />
|
||||
</ItemGroup>
|
||||
|
||||
<!-- Test projects: documentation comments are noise, and xUnit's own
|
||||
analyzers already cover what matters there. -->
|
||||
<PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
|
||||
|
||||
+43
-26
@@ -3,7 +3,11 @@
|
||||
<!--
|
||||
Central package management (docs/12_BUILD.md). Every version is pinned here
|
||||
and nowhere else, which also makes Dependabot PRs single-file diffs.
|
||||
All versions verified against nuget.org on 2026-08-02; re-verified and bumped 2026-09-21.
|
||||
All versions verified against nuget.org on 2026-08-02; re-verified and bumped 2026-09-21; bumped again
|
||||
2026-10-25 (beta.29 PR-2) with the updates Dependabot had never proposed (docs/13_CI_CD.md §Dependabot and
|
||||
the NuGet audit), and 2026-10-26 (beta.30 PR-3): Velopack and Markdig, the SQLitePCLRaw pin dropped; and again
|
||||
2026-10-26 (beta.31, the owner's request): the .NET 10.0.14 servicing packages and the updates beta.30 had left;
|
||||
and 2026-11-11 (beta.37, D94): the three packages serviced with the runtime follow it to .NET 11.0.0.
|
||||
-->
|
||||
<PropertyGroup>
|
||||
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
|
||||
@@ -25,10 +29,19 @@
|
||||
<PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.2" />
|
||||
<PackageVersion Include="ScottPlot.WPF" Version="5.1.59" />
|
||||
<PackageVersion Include="H.NotifyIcon.Wpf" Version="2.4.1" />
|
||||
<!--
|
||||
Markdig (Alexandre Mutel): Markdown rendered in the App (beta.12, owner request 4) - the Legal Gate, Help,
|
||||
About and the user guide show their documents rendered, not as raw text. BSD-2-Clause, no dependency on
|
||||
net10.0. The package ships no licence file, so its text is a reviewed override
|
||||
(tools/license-overrides/Markdig.txt). HTML is disabled in the pipeline (App/Markdown/MarkdownRenderer.cs).
|
||||
-->
|
||||
<PackageVersion Include="Markdig" Version="1.5.0" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Hosting and logging">
|
||||
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.12" />
|
||||
<!-- The three packages serviced with the runtime follow it: this one, Microsoft.Data.Sqlite and
|
||||
System.Diagnostics.EventLog (docs/12_BUILD.md). -->
|
||||
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="11.0.0" />
|
||||
<PackageVersion Include="Serilog" Version="4.4.0" />
|
||||
<PackageVersion Include="Serilog.Extensions.Hosting" Version="10.0.0" />
|
||||
<PackageVersion Include="Serilog.Sinks.Console" Version="6.1.1" />
|
||||
@@ -37,44 +50,42 @@
|
||||
|
||||
<ItemGroup Label="Storage">
|
||||
<!-- No EF: Dapper over Microsoft.Data.Sqlite (CLAUDE.md pinned stack). -->
|
||||
<PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.12" />
|
||||
<PackageVersion Include="Dapper" Version="2.1.86" />
|
||||
<PackageVersion Include="Microsoft.Data.Sqlite" Version="11.0.0" />
|
||||
<PackageVersion Include="Dapper" Version="2.1.89" />
|
||||
<!--
|
||||
Transitive pin, not a direct dependency.
|
||||
|
||||
Microsoft.Data.Sqlite 10.0.10 resolves SQLitePCLRaw.lib.e_sqlite3 2.1.11,
|
||||
which carries GHSA-2m69-gcr7-jv3q (high severity, vulnerable range
|
||||
<= 2.1.11) via its bundled SQLite. With TreatWarningsAsErrors that is
|
||||
NU1903 and the build fails — correctly. Pinning the bundle forward to the
|
||||
3.x line pulls a patched native library.
|
||||
|
||||
CentralPackageTransitivePinningEnabled is what makes this work from here.
|
||||
Revisit when Microsoft.Data.Sqlite ships a build that resolves a patched
|
||||
version on its own, and drop this pin rather than carrying it forever.
|
||||
No transitive pin on SQLitePCLRaw since beta.30 (2026-10-26). From the scaffold (2026-08-02) to beta.29 this held
|
||||
SQLitePCLRaw.bundle_e_sqlite3 at 3.0.5: Microsoft.Data.Sqlite 10.0.10 resolved SQLitePCLRaw.lib.e_sqlite3 2.1.11,
|
||||
which carries GHSA-2m69-gcr7-jv3q (vulnerable range <= 2.1.11) through its bundled SQLite, NU1903 under
|
||||
TreatWarningsAsErrors. Its own comment said to drop it once Microsoft.Data.Sqlite resolved a patched version on
|
||||
its own; 10.0.13 declares SQLitePCLRaw 2.1.13, and the pin had become a conflict NuGet does not report - it put a
|
||||
package built against the 2.x line on SQLitePCLRaw's 3.x line. The NuGet audit (Directory.Build.props) still
|
||||
turns a vulnerable SQLite red (docs/13_CI_CD.md §Dependabot and the NuGet audit).
|
||||
Since beta.37 (2026-11-11): Microsoft.Data.Sqlite 11 declares SQLitePCLRaw 3.0.5 itself - the 3.x line, built for
|
||||
it this time, whose engine is SourceGear's SQLite package; still no pin here. The alphas shipped that graph from
|
||||
2026-10-31.
|
||||
-->
|
||||
<PackageVersion Include="SQLitePCLRaw.bundle_e_sqlite3" Version="3.0.5" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Interop, telemetry and packaging">
|
||||
<PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.333" />
|
||||
<PackageVersion Include="Velopack" Version="1.2.0" />
|
||||
<PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.367" />
|
||||
<PackageVersion Include="Velopack" Version="1.2.161" />
|
||||
<!-- MPL-2.0. docs/18_GPU_VENDOR_APIS.md §L2 requires >= 0.9.6, and
|
||||
legal/THIRD_PARTY_NOTICES.md has a release-gate check that no
|
||||
depended-upon file carries MPL-2.0 Exhibit B. Consume UNMODIFIED. -->
|
||||
<PackageVersion Include="LibreHardwareMonitorLib" Version="0.9.6" />
|
||||
<!-- The crash witness (04_CAPTURE §Crash & exit classification): Application log events 1000/1001. In-box
|
||||
for WPF apps, a package for a class library on the Windows TFM. Microsoft, MIT. -->
|
||||
<PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.12" />
|
||||
<PackageVersion Include="System.Diagnostics.EventLog" Version="11.0.0" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Analyzers (build-time only)">
|
||||
<PackageVersion Include="Roslynator.Analyzers" Version="5.0.0" />
|
||||
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.266" />
|
||||
<PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="18.7.23" />
|
||||
<PackageVersion Include="Roslynator.Analyzers" Version="5.0.1" />
|
||||
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.319" />
|
||||
<PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="18.12.1" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Testing">
|
||||
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.10.1" />
|
||||
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.11.0" />
|
||||
<!--
|
||||
xUnit.net v3, 4.x line (2026-09-21). 4.0 made Microsoft Testing Platform v2 the default of the plain
|
||||
`xunit.v3` package and dropped MTP v1. build.ps1's gates are VSTest-shaped on purpose - the
|
||||
@@ -82,8 +93,8 @@
|
||||
so the projects reference the SAME 4.x framework through its `mtp-off` variant, the one xunit publishes
|
||||
for exactly this. Moving to MTP v2 is a build.ps1 change, not a version bump; do them together or not at all.
|
||||
-->
|
||||
<PackageVersion Include="xunit.v3.mtp-off" Version="4.0.1" />
|
||||
<PackageVersion Include="xunit.runner.visualstudio" Version="4.0.0" />
|
||||
<PackageVersion Include="xunit.v3.mtp-off" Version="4.0.2" />
|
||||
<PackageVersion Include="xunit.runner.visualstudio" Version="4.0.1" />
|
||||
<!--
|
||||
FluentAssertions is pinned to the 7.x line ON PURPOSE, and must not be
|
||||
bumped to 8.x without redoing the licence analysis.
|
||||
@@ -102,7 +113,13 @@
|
||||
-->
|
||||
<PackageVersion Include="FluentAssertions" Version="[7.2.2]" />
|
||||
<PackageVersion Include="NSubstitute" Version="6.2.0" />
|
||||
<PackageVersion Include="coverlet.collector" Version="10.0.1" />
|
||||
<!--
|
||||
10.1.0 not taken on 2026-10-25: the tracker it injects into each instrumented assembly declares a constant,
|
||||
ModuleTrackerRegistryKey, whose value reflection cannot read ("Literal value was not found"), and
|
||||
NoSecondMatcherTests reads every string constant in Application, Domain and Infrastructure. Taken in beta.31
|
||||
(2026-10-26): that test now leaves out the types coverlet adds (namespace Coverlet.*), which are not ours.
|
||||
-->
|
||||
<PackageVersion Include="coverlet.collector" Version="10.1.0" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
# Forking and redistributing FrameLedger
|
||||
|
||||
This page is for anyone who clones or forks FrameLedger — and above all for anyone who **gives builds of a modified
|
||||
FrameLedger to other people**. It says what the licence lets you do, what it asks of you when you distribute, and the
|
||||
practical things a fork has to change so that its users and FrameLedger's users do not get each other's updates, data
|
||||
or blame. It is written to be useful, not as legal advice; the texts that decide are `LICENSE` (the GNU GPL, version 3)
|
||||
and `NOTICE`.
|
||||
|
||||
## What the licence lets you do
|
||||
|
||||
FrameLedger is free software under the **GNU General Public License, version 3 only** (`GPL-3.0-only`). You may run it
|
||||
for any purpose, study and change its source, and share copies — changed or not — free of charge or for a fee. You do
|
||||
not need anyone's permission, and you do not have to accept the licence just to run the program (GPLv3 §9).
|
||||
|
||||
## What it asks when you distribute a build
|
||||
|
||||
"Distribute" here is the GPL's *convey*: giving a copy to someone else, including publishing an installer. Running
|
||||
FrameLedger yourself, or changing it for yourself, asks nothing of you.
|
||||
|
||||
- **The source goes with the build.** Whoever receives your binaries must be able to get the complete source code
|
||||
that builds them, under the same licence (GPLv3 §6) — the C++ and C# sources, the build scripts (`build.ps1`,
|
||||
`src/native/CMakeLists.txt`, the workflows) and everything else needed to rebuild them. Publishing the exact source
|
||||
tree at the tag you built from, next to the release, is the simplest way. An installer such as the Velopack
|
||||
`Setup.exe` counts as a binary.
|
||||
- **Keep the notices.** Ship `LICENSE`, `NOTICE` and the third-party licences with every copy. The release workflow
|
||||
already does this: the App's publish step copies them into `licenses\` beside the executables (`licenses\NOTICE.txt`,
|
||||
`licenses\FrameLedger-GPL-3.0.txt`, `licenses\THIRD_PARTY_NOTICES.md`, `licenses\nuget\`), and
|
||||
`.github/workflows/release.yml` refuses a published tree without them. Do not remove the copyright and licence
|
||||
headers from the source files.
|
||||
- **Say that it is changed.** A modified version must carry prominent notices that you modified it, and when
|
||||
(GPLv3 §5(a)).
|
||||
- **Add no restrictions.** You may not impose terms that take away the rights the GPL gives your users (GPLv3 §10) —
|
||||
an end-user agreement that forbids what the GPL permits is not allowed. FrameLedger's own EULA says that nothing in
|
||||
it limits those rights.
|
||||
|
||||
### The additional terms in `NOTICE`
|
||||
|
||||
FrameLedger's own material is licensed with three additional terms of the kinds GPLv3 §7 permits. In short:
|
||||
|
||||
- **(b)** keep the copyright line and the attribution *"Based on FrameLedger by poli0981 —
|
||||
https://github.com/poli0981/frameledger"* in your build's Appropriate Legal Notices (FrameLedger shows them under
|
||||
Help ▸ About);
|
||||
- **(c)** do not name a modified version "FrameLedger" alone, say in its notices and documentation that it is modified
|
||||
and by whom, and do not present its builds, installers or update feed as the original project's;
|
||||
- **(e)** no rights are granted in the name "FrameLedger" or the project's logo and icon, beyond saying truthfully
|
||||
where your work comes from ("based on FrameLedger", "a fork of FrameLedger").
|
||||
|
||||
`NOTICE` has the exact wording. These terms cover material written by FrameLedger's developer; how far they reach
|
||||
depends on the copyright in that material — parts of FrameLedger were written with AI assistance under the developer's
|
||||
direction. If the difference matters to you, ask a lawyer, not this page.
|
||||
|
||||
## What a fork that ships builds has to change
|
||||
|
||||
FrameLedger installs into the user's profile, keeps one database there, runs a background agent and registers a few
|
||||
system-wide names. A fork that keeps them **collides with an installed FrameLedger**: the two would update each other,
|
||||
share — and migrate — one database, and fight over the same pipe and shared memory. Change all of these together:
|
||||
|
||||
| What | Where | Why |
|
||||
|---|---|---|
|
||||
| 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, 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`, 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`) — `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` / `FL_COPYRIGHT` in `src/native/CMakeLists.txt`; `Company` / `Product` / `Authors` / `Copyright` / `Description` / `RepositoryUrl` in `Directory.Build.props` and the `AssemblyTitle` / `Description` of the App's and the Agent's csproj (since beta.14); and the names `tools/versioninfo-check.ps1` and the two `AssemblyIdentityTests` require | anti-cheat vendors and users identify the DLLs loaded into games and the processes beside them by it (`docs/19_SAFETY_AND_ANTICHEAT.md`); it must name your project, and the copyright line must be one line on every binary — the check compares them |
|
||||
| Checksums | your own `SHA256SUMS.txt` | users verify what *you* built |
|
||||
|
||||
The detection rules and the anti-cheat blocklist (`rules/detection-rules.json`) ship with each build; keeping them
|
||||
current for your users becomes your job.
|
||||
|
||||
## What we ask, and cannot require
|
||||
|
||||
The GPL does not allow adding restrictions, so the following is a request, not a condition. FrameLedger is built
|
||||
around a few rules (`CLAUDE.md`, *Non-negotiable rules*), and the reason is the people who use it:
|
||||
|
||||
- the anti-cheat guard is a hard gate with no override switch;
|
||||
- injection is opt-in, per game, and never automatic;
|
||||
- nothing is hidden from security software — no manual mapping, no header erasure, no renamed or obfuscated binaries;
|
||||
- the game's memory is never read or written outside the hooked calls;
|
||||
- no telemetry and no silent network requests.
|
||||
|
||||
A build that drops any of these can get its users' accounts banned. It is not FrameLedger, must not say it is
|
||||
(NOTICE (c)), and the original developer is not responsible for it.
|
||||
|
||||
## See also
|
||||
|
||||
`NOTICE` · `LICENSE` · `CONTRIBUTING.md` (if you would rather send your change upstream) ·
|
||||
`legal/TRADEMARKS.md` · `legal/THIRD_PARTY_NOTICES.md` · `docs/12_BUILD.md` (building from source)
|
||||
@@ -49,6 +49,8 @@
|
||||
-->
|
||||
<ItemGroup Condition="'$(IsTestProject)' == 'true'">
|
||||
<Compile Include="$(MSBuildThisFileDirectory)tests\Shared\HarnessOverlayLogSweep.cs" Link="Shared\HarnessOverlayLogSweep.cs" />
|
||||
<!-- When a started harness is really up (beta.27): the injection tests wait for its own "presenting" line. -->
|
||||
<Compile Include="$(MSBuildThisFileDirectory)tests\Shared\HarnessReady.cs" Link="Shared\HarnessReady.cs" />
|
||||
</ItemGroup>
|
||||
|
||||
<!--
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
<Project>
|
||||
|
||||
<!--
|
||||
Ships FrameLedger.ProcessStats.dll beside the importing project's output (beta.12, owner decision D43).
|
||||
|
||||
The third P/Invoke facade after the guard's and the NVAPI bridge's (docs/18_GPU_VENDOR_APIS.md §L1, the game
|
||||
process's memory): NativeProcessStats loads it BY ABSOLUTE PATH from AppContext.BaseDirectory and never falls back
|
||||
to a search, so it has to actually be there. Read-only, and NEVER loaded into a game — the Agent (and the unshipped
|
||||
capture host) load it into their own process for the 1 Hz read of a game's dedicated/shared GPU memory (the
|
||||
GPU Process Memory counters) and its working sets (GetProcessMemoryInfo).
|
||||
|
||||
Imported by the same three projects as the bridge: FrameLedger.Agent, FrameLedger.CaptureHost and
|
||||
FrameLedger.Infrastructure.Tests (the mirror test and the real read P/Invoke into the real DLL).
|
||||
|
||||
Warn rather than fail when absent, as the bridge does: an absent reader is a missing measurement (every game-memory
|
||||
field reads N/A), not a safety hole.
|
||||
-->
|
||||
<PropertyGroup>
|
||||
<FlProcessStatsOutDir>$(MSBuildThisFileDirectory)build\native\x64-release\FrameLedger.ProcessStats\</FlProcessStatsOutDir>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<None Include="$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll" Condition="Exists('$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll')">
|
||||
<Link>FrameLedger.ProcessStats.dll</Link>
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</None>
|
||||
</ItemGroup>
|
||||
|
||||
<Target Name="FlWarnOnMissingProcessStats" AfterTargets="Build"
|
||||
Condition="!Exists('$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll')">
|
||||
<Warning Text="FrameLedger.ProcessStats.dll was not found at $(FlProcessStatsOutDir). Run build.ps1 native first; the game's memory will read N/A." />
|
||||
</Target>
|
||||
|
||||
</Project>
|
||||
+390
@@ -0,0 +1,390 @@
|
||||
# What FrameLedger cannot do
|
||||
|
||||
FrameLedger measures a game by loading a small component into it — only for a game you added and switched
|
||||
hooking on for — and reading the graphics calls the game makes. That is why it can tell the real render
|
||||
resolution, the upscaler, frame generation and ray tracing apart. It is also where its limits come from. This
|
||||
page lists them in plain words; each item links to the document that has the details.
|
||||
|
||||
*Beta software: this page describes version 0.1.0-beta.45.*
|
||||
|
||||
## Games it will not measure
|
||||
|
||||
- **Games with anti-cheat.** FrameLedger looks for anti-cheat before it touches a game and refuses when it
|
||||
finds one — there is no switch that overrides this. The one exception is an anti-cheat that runs entirely
|
||||
inside the game (no driver, no service), which you can allow per game after a warning; its first two
|
||||
sessions are a trial, and one that does not go well ends the exception for good. A ban is still possible and
|
||||
may come days later. Kernel anti-cheat is never allowed.
|
||||
([Safety](docs/19_SAFETY_AND_ANTICHEAT.md))
|
||||
- **Anti-cheat FrameLedger does not know about.** The list of anti-cheat products is FrameLedger's own and
|
||||
can be incomplete. A game protected by something unknown may be hooked; that is a risk to your account
|
||||
that you take by switching hooking on.
|
||||
- **32-bit games and Direct3D 9 games.** Only 64-bit Direct3D 11, Direct3D 12 and OpenGL games are measured
|
||||
from their own calls; a 32-bit or Direct3D 9 game is recorded without measurement.
|
||||
- **Vulkan games, unless FrameLedger starts them.** A Vulkan game is measured only when FrameLedger launches it
|
||||
with its Vulkan layer switched on — **Play** set to *Start directly* does; one started another way is not observed by
|
||||
the layer.
|
||||
- **Games that run as administrator,** unless you turn on *Run the agent as administrator* in Settings
|
||||
(off by default; Windows asks every time the agent starts). **A process Windows protects** stays closed
|
||||
either way.
|
||||
- **Vulkan games that run as administrator.** Windows' Vulkan loader does not load FrameLedger's Vulkan
|
||||
layer into an elevated game, so admin mode does not help there.
|
||||
- **A game that was already running when FrameLedger was updated** — restart the game once.
|
||||
- **Games you did not switch hooking on for.** Adding a game only records its sessions; measuring it is a
|
||||
separate, per-game choice with its own warning.
|
||||
|
||||
## What an unmeasured session contains
|
||||
|
||||
When a game is not measured — any of the reasons above — its session still records **how long it ran, the
|
||||
machine's sensors (GPU temperature, load, power; CPU load; memory), how much memory the game itself used (read from
|
||||
Windows, outside the game) and why nothing was measured.** Every
|
||||
frame-rate, upscaler, frame-generation and ray-tracing value reads **N/A**, never 0. How the game's window was
|
||||
shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
|
||||
|
||||
## When a game crashed
|
||||
|
||||
- A session reads **crashed** when the game ended with an exception's code, when Windows logged a crash report of it,
|
||||
or — since 0.1.0-beta.14 — when it started its engine's crash reporter (Unreal's, CD PROJEKT RED's, Capcom's,
|
||||
BugSplat's) and exited within a minute. A game that handles its own crash quietly, starts no reporter and leaves no
|
||||
crash report reads **ended normally**, with its exit code.
|
||||
- A crash reporter is seen from a once-a-second look at running programs: one that opens and closes faster can be
|
||||
missed, and one started in the game's first 10 seconds is not counted (it could be a monitor that starts with the
|
||||
game). Unity's crash handler and Chromium's `crashpad_handler` start with every game that has them, so their presence
|
||||
says nothing. Sessions recorded before 0.1.0-beta.14 keep how they were stored — a few of them may read *crashed*
|
||||
because Windows logged a memory report about the game. ([details](docs/04_CAPTURE.md))
|
||||
- **A game that faults while it is closing can read *ended normally* in a session measured from inside the game.**
|
||||
FrameLedger looks for Windows' crash report when it saves the session, and for such a session that is before
|
||||
Windows has written it; the same fault in a session that was not measured from inside reads *crashed*. Seen on one
|
||||
game whose graphics-driver library faults at every exit, measured or not (2026-11-12), and on a second whose
|
||||
Steam crash handler faults at every measured exit. Not changed yet.
|
||||
|
||||
## Frame rate and frame generation
|
||||
|
||||
- **One inflated number is never shown.** When frame generation is measured, the page shows the game's own
|
||||
frames and the displayed frames together (`62 → 118 FPS (×1.9 FG)`). When it cannot be measured, the page
|
||||
shows **Presented FPS** with a sentence saying whether generated frames could be included.
|
||||
- **Frame generation done by the driver outside the game** (AMD Fluid Motion Frames, NVIDIA Smooth Motion)
|
||||
is not visible to FrameLedger; the rates shown are what the game presented.
|
||||
- Frame generation is counted on **Direct3D games** only. DLSS Frame Generation and FSR frame generation are
|
||||
named from the calls the game makes; any other generator is shown only as *active*, never named, and where
|
||||
the generated frames cannot be counted the page shows Presented FPS with a note instead of a factor.
|
||||
- **A session whose frame generation changed** (menus, loading, a settings change) shows the factor of the
|
||||
state it spent most of its time in, with the share of the session it covers — never an average of the two.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
- **The mix of frame-generation states** in a session's summary (since 0.1.0-beta.24) is read over five-second
|
||||
windows: frame generation that changes faster than that — the NVIDIA App's *Dynamic* mode can — reads partly as
|
||||
*Not classified*: a window in which the multiplier stepped reads between two whole multipliers and, since
|
||||
0.1.0-beta.27, is never a state of its own. A state shorter than 10 seconds is not listed. A stretch the game
|
||||
presents with almost no frame
|
||||
count of its own — shaders compiling at start, a loading screen, a menu drawn outside frame generation — reads as
|
||||
*Not classified* too. The
|
||||
multiplier chosen in a game's own menu is not read; the measured factor is its evidence. How the NVIDIA App's
|
||||
*Dynamic* ceiling and *Max refresh rate* target are stored by the driver is read from NVIDIA's own setting names,
|
||||
and has been checked against the App on one game. Sessions recorded before 0.1.0-beta.24 have no mix.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
- **Time below 30, 60 FPS and below the refresh rate** (since 0.1.0-beta.14) leaves out the small wobble of a game
|
||||
held at its limit: a frame counts as below 60 when it took 10 % longer than 1/60 s, or when the frames around it ran
|
||||
2 % slower. So a game running steadily just under the line — 59 FPS against 60 — reads partly as at it. Time below
|
||||
the refresh rate needs the monitor's rate, which a session saved after a crash does not have.
|
||||
- **VSync and tearing** (since 0.1.0-beta.14) are what the game *asked* for on each frame; the graphics driver or a
|
||||
variable-refresh display can override it, and FrameLedger cannot see which won. OpenGL and Vulkan games do not say,
|
||||
and read N/A. ([Metrics](docs/03_METRICS.md))
|
||||
|
||||
## Upscaling and ray tracing
|
||||
|
||||
- **The render scale chart** (since 0.1.0-beta.14) is drawn only where the render resolution was measured — the
|
||||
same games as *Render → output resolution* in the accuracy statement; elsewhere it says it was not measured.
|
||||
- The upscaler is read from the game's calls: DLSS and NIS through NVIDIA Streamline, and FSR through AMD's
|
||||
FidelityFX libraries. **Intel XeSS is not read** (its licence forbids it), FSR 2 and upscalers built into the
|
||||
game are not identified — Cyberpunk 2077's FSR 2.1 is one: its sessions say "unknown" beside a measured render
|
||||
size — and Vulkan and OpenGL games read N/A. A game that sends FSR upscaling through two unrelated libraries in
|
||||
one run is counted from the first alone (none is known). Where no hook saw DLSS but the NVIDIA driver
|
||||
reports it, the page says it is the driver's report.
|
||||
- **The quality mode** (Quality, Balanced, DLAA, …) is shown only when it is known: the NVIDIA App's override
|
||||
where the NVIDIA driver reports it applied (marked *· NVIDIA App*, since 0.1.0-beta.24), or the mode the game
|
||||
passed to a call FrameLedger reads. For FSR through AMD's FidelityFX libraries (since 0.1.0-beta.25) that is the
|
||||
mode whose render size the game asked AMD's library for and then rendered at — checked on a test program, not yet
|
||||
on a real game; a game at a dynamic resolution, one that sizes its frames without asking, and a game FrameLedger
|
||||
joined after it asked show none. For DLSS it is the options a Streamline game passes, which no game has done yet.
|
||||
The mode chosen in a game's own menu is not readable for DLSS without Streamline, and is not inferred from the
|
||||
render scale. How the driver numbers DLAA in
|
||||
its report is NVIDIA's documented value, not yet seen on a real game. The render resolution is N/A where the
|
||||
game's own calls do not carry it (DLSS without Streamline, for one). Sessions recorded before 0.1.0-beta.27 kept
|
||||
the NVIDIA driver's answer from after the game had closed, which never says DLSS ran: on a game no hook names, they
|
||||
show neither the driver's report nor the NVIDIA App's mode. ([Metrics](docs/03_METRICS.md))
|
||||
- **Which DLSS ran** (since 0.1.0-beta.24) is named only from what the session showed: the model preset the NVIDIA
|
||||
driver reports (L or M: DLSS 4.5; J or K: DLSS 4), a measured multi-frame factor (×5 or ×6: DLSS 4.5; ×3 or ×4:
|
||||
DLSS 4), the NVIDIA App's *Dynamic* frame generation that the driver reports applied (DLSS 4.5, whatever multiplier
|
||||
it chose — since 0.1.0-beta.34), or a library whose major version names one (2.x, 3.x). A *Fixed* ×5 or ×6 set in
|
||||
the App names DLSS 4.5 only when the frames show it. A 310 library with no such evidence shows its
|
||||
version only. **DLSS 5**
|
||||
(since 0.1.0-beta.34) is named where the game was seen running its neural rendering through Streamline, with the share
|
||||
of rendered frames; its library loaded and nothing seen reads *runtime loaded* — *not seen running* only where the
|
||||
Overlay looked. A game that runs neural rendering outside Streamline is not seen. Where each
|
||||
library was loaded from is read from its folder, for sessions recorded since 0.1.0-beta.24.
|
||||
- **Ray tracing** is *Yes*, *No* or *N/A* — measured from the game's ray-tracing calls on Direct3D 12, and
|
||||
N/A where FrameLedger could not look. **Path tracing is never stated as a fact**: there is no API signal
|
||||
for it. You can correct any of these by hand, and your correction is labelled as yours.
|
||||
- HDR output, NVIDIA Reflex latency, the video-memory budget Windows gives a game, and shader-compilation
|
||||
stutter are **not measured yet** — they read N/A. ([Accuracy](legal/ACCURACY.md))
|
||||
|
||||
## The game's memory
|
||||
|
||||
- **What is shown is what Task Manager's Details tab shows** for the game's process — *Dedicated GPU memory*,
|
||||
*Shared GPU memory* and *Memory* (the private working set) — read from Windows once a second, from outside
|
||||
the game. FrameLedger never looks inside the game's memory to get it.
|
||||
- **One process.** A measured game is its own process; for a game that is not measured, every process running
|
||||
the game's executable is added together. Launchers, crash reporters and other helper programs are not counted.
|
||||
- **The private working set needs a recent Windows**: Windows 10 22H2 or Windows 11 with the September 2023
|
||||
update or later. Without it the working set is shown instead, labelled as such.
|
||||
- A game that has not created anything on the graphics card yet (its first second, a launcher screen) reads
|
||||
N/A for video memory. AMD and Intel graphics cards have not been tested.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
|
||||
## Display mode (full-screen, borderless, windowed)
|
||||
|
||||
- **Exclusive full-screen is known only for a measured Direct3D (DXGI) game** — the game's own swap chain
|
||||
says so. For OpenGL, Vulkan and unmeasured games, a window covering the screen reads *Fullscreen or
|
||||
borderless*, never either one.
|
||||
- **What Windows does behind the game is not visible:** a game in exclusive full-screen may still be shown
|
||||
through Windows' compositor ("fullscreen optimizations"), and a game's menu may call a borderless window
|
||||
"Fullscreen". FrameLedger reports what the game asked for.
|
||||
- The mode is sampled ten times a second in a measured session and once a second in an unmeasured one; very
|
||||
short switches can be missed. A session recovered after a crash, and every session recorded before
|
||||
beta.10, read N/A. Some sessions recorded before 0.1.0-beta.27 of a game in exclusive full-screen show no window or
|
||||
monitor size: the game's last moments, after its window had closed, replaced them.
|
||||
([Display mode](docs/03_METRICS.md#display-mode--both-tiers-beta10))
|
||||
|
||||
## Engine version
|
||||
|
||||
- The exact version is read for **Unreal Engine 4 and 5** games, from the game's executable file on disk.
|
||||
A studio can remove or rename what it is read from; then the page says the version was not found.
|
||||
**Unreal Engine 3 and older are not recognised.**
|
||||
- Since beta.19 also **Unity**, **Godot** and **RPG Maker** (MV, MZ, XP, VX, VX Ace): from the engine's own files —
|
||||
Unity's player library or data file, Godot's data pack, RPG Maker's core script or the runtime library its `Game.ini`
|
||||
names. A Unity game whose data file is encrypted shows the version without its release letter (`2019.4.40`, not
|
||||
`2019.4.40f1`); an XP, VX or VX Ace game shows its runtime library's number, which is not the editor's.
|
||||
**RPG Maker 2000 and 2003 are not recognised.**
|
||||
- Since beta.20 also **Ren'Py**: from the engine's own version file (`renpy/vc_version.py`); a Ren'Py game whose engine
|
||||
names no version there shows none. Other engines show a version only where their files state one.
|
||||
([Detection](docs/05_DETECTION.md))
|
||||
|
||||
## Sensors
|
||||
|
||||
- GPU temperature, load, power and memory are best supported on **NVIDIA** GPUs. **AMD and Intel GPUs have
|
||||
not been tested** on real hardware yet.
|
||||
- **On a PC with more than one graphics card**, the GPU figures follow the card the game draws on once a Direct3D game
|
||||
has shown its first frame; before that, in an unmeasured session, and for OpenGL or Vulkan games they describe the
|
||||
first card Windows lists, and with two cards of one brand the temperature and load come from that brand's first card.
|
||||
The session's hardware details always name the first card. None of this has been tested on a machine with two cards.
|
||||
([Telemetry](docs/18_GPU_VENDOR_APIS.md))
|
||||
- **CPU temperature** needs *Run the agent as administrator* and the separately installed PawnIO driver, and
|
||||
has not been verified on real hardware yet. CPU load is the time the processor was busy — not Task
|
||||
Manager's "utility" figure, which can exceed 100%. ([Telemetry](docs/18_GPU_VENDOR_APIS.md))
|
||||
- **Advanced metrics** (since 0.1.0-beta.39; Settings ▸ Recording, off by default) stores more of what the graphics
|
||||
driver and the sensors report with each session. Its limits:
|
||||
- **A session recorded while it was off is not filled in later**, and switching it on applies from the next session.
|
||||
- **What a game tells DLSS and FSR** (since 0.1.0-beta.40) is kept only for a game FrameLedger measures from
|
||||
inside, and only where the game hands it over in a call FrameLedger intercepts. **Most games set their DLSS
|
||||
options through a call it cannot see and show nothing**; the FSR rows need FSR 3.1 or later through AMD's own
|
||||
library. The session says which it was — nothing seen, or not measured inside the game — and neither means the
|
||||
game uses no upscaler. They are the game's words, not a check of what the upscaler did; the field of view is a
|
||||
lowest and highest value, never a line over time; FSR's memory is a point where the game asked, so most sessions
|
||||
have none. FSR's upscaling values have been read from real games; **the DLSS options have not been confirmed on
|
||||
one yet.**
|
||||
- **What a game tells Streamline each frame, and how it configures FSR frame generation** (since 0.1.0-beta.43)
|
||||
are read from two calls FrameLedger hooks **only once a session with Advanced metrics on has started in that
|
||||
game** — a session recorded with the option off puts neither hook in. Streamline's values are those of **the
|
||||
first viewport that called**: a game with several (split screen, a picture-in-picture view) shows one, and the
|
||||
count of calls covers all. The frame-generation rows are **what the game asked for** — a game that asks for
|
||||
generation and gets none still reads "on", and the session's summary is where what was generated is measured. A
|
||||
setting the game changed during the session reads "on and off". The session's line says, for each of the two,
|
||||
whether it was read, hooked and never called by the game, or not hooked (the game did not load the library).
|
||||
Streamline 1.x is not read. Streamline's values have been read from three real games and the frame-generation
|
||||
configuration from one (2026-11-12); **a configuration that reaches FSR through AMD's 2.3 loader has not been
|
||||
read from a real game yet.** **A game may give a value in a unit of its own**: Cyberpunk 2077 gives Streamline
|
||||
its field of view in degrees where NVIDIA's header says radians. A field of view too large to be radians is
|
||||
shown as the game gave it, with a line saying so, and is never converted (since 0.1.0-beta.44; a session
|
||||
recorded before keeps the line it was stored with, which labels the degrees as radians). The count of resets is
|
||||
the number of calls in which the game said so — menus and loading screens raise it.
|
||||
- **Which version each Streamline feature is, and what it requires** (since 0.1.0-beta.44) are Streamline's
|
||||
answers to two questions a game asks while it starts — and, in the games run so far, again later. FrameLedger
|
||||
hooks the two calls only once a session with Advanced metrics on has started in that game. **A game that asks
|
||||
only at its start shows nothing here**, and the session's line then says the call was hooked and the game did
|
||||
not ask again; the four Unreal Engine games run on 2026-11-12 asked again and were read, and Cyberpunk 2077
|
||||
asked again for the requirements and not for the versions. A second session of a game that kept running keeps
|
||||
what the first one read. The rows are Streamline's answer as the game received it — the versions
|
||||
of Windows and of the driver are the ones Streamline found — not FrameLedger's own check of the PC. Twelve
|
||||
features are kept; a thirteenth is not. The lists the answer points to (the buffers, the Vulkan extensions) are
|
||||
never read, so the rows give how many buffers a feature needs and not which. **The version Streamline gives for
|
||||
a feature can differ from the file in the game's folder** — three games answered 2.14.16 for DLSS frame
|
||||
generation while shipping an older plugin; which file that newer one is was not looked into. The games run so
|
||||
far do not ask Streamline about DLSS upscaling unless they upscale through it, so a game can list frame
|
||||
generation here and no upscaler.
|
||||
- **Whether each Streamline feature is supported and loaded, and what the game did with it** (since
|
||||
0.1.0-beta.45) come from six more calls, hooked the same way — only once a session with Advanced metrics on has
|
||||
started in that game. **What the game did before that is not seen**: a feature it switched on while it started
|
||||
has no "switched" row, and resources it allocated then are not counted. The counts are **calls the game made**,
|
||||
not resources, and each stops at fifteen (shown as `≥ 15`); they and the switching start again with each
|
||||
session, while the two answers are kept from an earlier session of a game that kept running. "Supported" is
|
||||
Streamline's answer for the graphics card the game asked about; which card that was is never read, so on a PC
|
||||
with two cards the row does not say. A refusal is shown by NVIDIA's own name for it
|
||||
(`eErrorFeatureNotSupported`), and it is the game that was refused, not FrameLedger. None of this says a
|
||||
feature ran or drew anything. **Read on five games on 2026-11-13**: each asked whether its features are
|
||||
supported, three asked whether they are loaded, two switched features off and on, one freed a feature's
|
||||
resources once and one shut Streamline down once. **None allocated a feature's resources after FrameLedger was
|
||||
in it**, so that row has not been seen in a real game.
|
||||
- **What a game started Streamline with is not read, and will not be**: the game makes that call once, before
|
||||
FrameLedger can be inside it — also when FrameLedger starts the game itself. The Advanced page lists the entry
|
||||
with that reason.
|
||||
- **The driver's own figures** — the card's firmware and architecture, its memory in detail, what a display can do
|
||||
with HDR and variable refresh, the driver's settings for the game — exist on **NVIDIA** cards only. On other cards
|
||||
they read N/A; the card's sensors (fans, voltages, loads) are read on every brand, and none has been tested on an
|
||||
AMD or Intel card.
|
||||
- **The sensors are read every five seconds**, NVIDIA's figures every second; between two readings a sensor has no
|
||||
value, and its last one is not repeated.
|
||||
- **The processor's, the memory's and the motherboard's sensors** need *Run the agent as administrator* and the
|
||||
separately installed PawnIO driver, and **have never been read on real hardware**. Without them they read N/A
|
||||
with the reason.
|
||||
- **A drive's temperature is not read at all**: the sensor library cannot list drives without touching removable
|
||||
ones. Power supplies, fan controllers and batteries are not read either.
|
||||
- **No serial number and no display identification data (EDID) is read**, so two PCs with the same parts look the
|
||||
same.
|
||||
- **None of these readings has been checked against another tool**, and they are **not in an export or a bug
|
||||
report**.
|
||||
- **The Advanced page's "This PC" is read only while that page is open** (or a game is being recorded), is not
|
||||
stored, and keeps five minutes of each reading in memory. A reading with more than eight parts — every
|
||||
processor core — is drawn as its lowest, average and highest; the table lists each part.
|
||||
- **A session's chart needs its per-second series**, which are kept for the newest sessions of each game only
|
||||
(Settings ▸ Recording); an older session keeps its statistics.
|
||||
|
||||
([Telemetry](docs/18_GPU_VENDOR_APIS.md#advanced-metrics-owner-decisions-d101d108-2026-11-11))
|
||||
- **Whether the graphics card was held back by its power limit or by heat** (since 0.1.0-beta.14) is known only on
|
||||
NVIDIA cards, and only as it was at each once-a-second reading. On other cards it reads N/A.
|
||||
- **Frames per watt** (since 0.1.0-beta.14) counts the game's own frames — never generated ones — against the graphics
|
||||
card's power alone, not the processor's or the whole PC's. It reads N/A where the game's own frame rate is not known.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
|
||||
## Running the agent as administrator
|
||||
|
||||
Off by default. When on, **Windows asks every time the agent starts** and names an unknown publisher, because
|
||||
FrameLedger is not signed. It lets FrameLedger open games that run as administrator and read the CPU
|
||||
temperature — with Advanced metrics on, also the processor's, the memory's and the motherboard's sensors — where
|
||||
PawnIO is installed; it does not bypass anti-cheat, does not open protected processes, and does not make games you
|
||||
start from FrameLedger run as administrator. **The risk:** FrameLedger is installed in your user folder, so a
|
||||
program running under your account could replace its files and would then run as administrator the next time
|
||||
you accept the prompt. Turn it on only if you trust everything that runs under your account.
|
||||
([Architecture, ADR-9](docs/01_ARCHITECTURE.md))
|
||||
|
||||
## Platform and what has been tested
|
||||
|
||||
- **Windows 11, 64-bit only.** FrameLedger is built on .NET 11 since 0.1.0-beta.37, which Microsoft supports on
|
||||
Windows 11 and, on Windows 10, only in its LTSC and IoT editions. **Windows 10 22H2 Home and Pro are not blocked,
|
||||
not tested and not supported**: FrameLedger may run there, and nobody has checked that it does
|
||||
([Build](docs/12_BUILD.md)).
|
||||
- **It does not start at all on a processor without SSE4.2 and POPCNT** — .NET 11's requirement, which every
|
||||
processor Windows 11 accepts meets. On such a PC an update from 0.1.0-beta.36 or older installs and then does not
|
||||
start; installing 0.1.0-beta.36 again brings FrameLedger back, with your data as it was.
|
||||
- The games FrameLedger has actually been run with, and what was measured on each, are listed in
|
||||
[LIST_GAME_TESTED.md](docs/LIST_GAME_TESTED.md). Everything was measured on one machine (an NVIDIA
|
||||
GeForce RTX 5080 with an Intel Core i7-14700KF on Windows 11); other hardware is untested.
|
||||
- **One real Vulkan game has been measured** (Everhex Demo, 2026-10-13) **and no OpenGL game**, beyond FrameLedger's
|
||||
own test program.
|
||||
- There is **no in-game overlay**; everything is shown in the FrameLedger window.
|
||||
- **FrameLedger does not tell whether a game is safe to run.** It reads a game's files to find its engine and its
|
||||
anti-cheat, never to judge it, and recording or measuring a game vouches for nothing. Four itch.io downloads this
|
||||
project once used as examples turned out to carry malware ([details](docs/spike-notes.md)).
|
||||
|
||||
## Accessibility
|
||||
|
||||
What works with the keyboard alone, a screen reader, a contrast theme or Magnifier, what does not yet, and how to report
|
||||
a barrier is on its own page: [Accessibility](ACCESSIBILITY.md) (in the app: Help ▸ Accessibility). The largest limits:
|
||||
|
||||
- **A chart's points cannot be read one by one.** A screen reader hears its name and where its numbers are written —
|
||||
the session's figures, the tables, **File ▸ Export**; its keys move it.
|
||||
- **Windows' text size setting is not followed** — use display scaling or Magnifier.
|
||||
|
||||
## Play
|
||||
|
||||
- **Through GOG GALAXY or itch, you finish in their app.** GOG GALAXY runs the game as its own shortcuts do, and the
|
||||
itch app asks which copy to launch. The Epic Games Launcher's link is the one its own shortcuts carry, and has not
|
||||
been tried on a real Epic game yet.
|
||||
- **FrameLedger never starts a game as administrator.** *Start directly* does not start a game that asks for it — start
|
||||
that one from its store or its own shortcut — nor a game whose recording is off: FrameLedger starts only what it
|
||||
records. While FrameLedger itself runs as administrator, Play starts every game directly, with your standard rights.
|
||||
- **Some games will not start directly** (seen on two Steam games, 2026-10-19 and 20). Lies of P, started by *Start
|
||||
directly*, hands itself to Steam within seconds — since 0.1.0-beta.27 the game Steam then starts is recorded —, and
|
||||
Clair Obscur: Expedition 33 closes within seconds, with or without FrameLedger's hook. Each such start ends a
|
||||
measured session early, which the crash safety counts: two turn hooking off for the game — and since
|
||||
0.1.0-beta.44 the count starts again each time you switch hooking back on (before, one more such end was enough
|
||||
once a game had been switched off). Start such a game through
|
||||
its store (Settings ▸ Games ▸ *Play button*); the notice after Play says when a Steam game may hand itself to Steam.
|
||||
([details](docs/spike-notes/23-owner-runs-2026-10-20.md))
|
||||
|
||||
## Xbox app and Microsoft Store games
|
||||
|
||||
- **Only games built on Microsoft's GDK** (since 0.1.0-beta.33) — what the Xbox app and the Microsoft Store install into
|
||||
a games folder you chose, PC Game Pass games included — are found by **Import library**. An older Store app (UWP) is
|
||||
not listed, and a game Windows has not installed for you, such as one left behind on a drive, is not offered.
|
||||
([details](docs/spike-notes/25-xbox-gdk.md))
|
||||
- **Their executables cannot be read by other programs** — Windows refuses it to anything outside the game's own
|
||||
package — so FrameLedger shows no Unreal Engine version and no *Runs as* for them, and says what it could not read
|
||||
rather than guessing. A Unity game's version still reads, from its player library.
|
||||
- **The anti-cheat list's per-game entries know Steam ids only.** An Xbox copy of a game listed there by its Steam id is
|
||||
checked like any other game — its files, its executables, the anti-cheat drivers and services on your PC — but not
|
||||
by that entry. ([Safety](docs/19_SAFETY_AND_ANTICHEAT.md), [open question](docs/20_OPEN_QUESTIONS.md))
|
||||
- **Play starts them through Windows, in either Play mode** — as their Start-menu tile does — because Windows starts
|
||||
such a game only through its package: *Start directly* cannot start one, so it is recorded once it appears, a few
|
||||
seconds after its start, and the first frames before then are not measured. ([Play](docs/08_UI.md),
|
||||
[capture](docs/04_CAPTURE.md))
|
||||
- **An older Store app (UWP), and a game Windows runs under code protection the hook cannot live under** — only
|
||||
Microsoft-signed code, no generated code, strict stack or control-flow protection — **is never hooked**: its session
|
||||
keeps its duration, your PC's sensors and the reason. Measuring a game from the Xbox app with the Vulkan graphics API
|
||||
has not been tried. ([Safety](docs/19_SAFETY_AND_ANTICHEAT.md), [open question](docs/20_OPEN_QUESTIONS.md))
|
||||
|
||||
## Game artwork
|
||||
|
||||
- **Only the Steam and GOG GALAXY apps keep pictures FrameLedger can show** (since 0.1.0-beta.23) — **and, since
|
||||
0.1.0-beta.33, an Xbox game ships its own**: its square logo and its splash image, shown from its own folder. A game's
|
||||
page shows the cover and banner those apps keep on your PC for a game they installed, read where they keep them —
|
||||
nothing is downloaded or copied. A game from itch, the Epic Games Launcher or another store, or one whose `.exe` is
|
||||
outside a store's own folder, shows a picture only once you choose one (**Edit… ▸ Choose image…**). A GOG picture needs
|
||||
Windows' WebP support, which Windows 11 and most Windows 10 installs have. ([Game page](docs/08_UI.md))
|
||||
- The pictures belong to the games' owners; FrameLedger ships none ([names and trademarks](legal/TRADEMARKS.md)).
|
||||
|
||||
## Your data
|
||||
|
||||
- Everything stays on your computer (`%LOCALAPPDATA%\FrameLedger`). FrameLedger sends no telemetry; its only
|
||||
network requests are the update check and the update download, both to GitHub, and the check can be switched
|
||||
off. The anti-cheat list and the detection rules ship with each version — **a newer list reaches you only with
|
||||
the next update.** ([Privacy policy](legal/PRIVACY_POLICY.md))
|
||||
- Per-frame data is kept for the **last 20 sessions of each game** (configurable); older sessions keep their
|
||||
summaries.
|
||||
- A newer version upgrades the database in place, and an **older version cannot open it again** — there is
|
||||
no downgrade.
|
||||
|
||||
## Installation
|
||||
|
||||
FrameLedger's programs are **not code-signed**: Windows SmartScreen may warn when you install it, and the
|
||||
administrator prompt names an unknown publisher. Each release publishes SHA-256 checksums you can compare.
|
||||
|
||||
**An update waits while a game FrameLedger measured is still running.** The part of FrameLedger loaded into a game stays
|
||||
loaded until the game exits, and Windows will not let the update replace it; *Restart to update* says which file is held
|
||||
until you close that game ([details](docs/11_UPDATER.md)). Copies older than 0.1.0-beta.14 look only for stable
|
||||
releases unless you choose *Beta* in Settings ▸ Updates, and apply a downloaded update the next time they start.
|
||||
|
||||
## Alpha builds
|
||||
|
||||
*Only for an alpha — a version ending in `-alpha.N`, an experimental build on a new .NET
|
||||
([Alpha builds](guide/11-alpha-builds.md)).*
|
||||
|
||||
- **It is built to try a newer .NET — at times one Microsoft has not finished** — and has not been tested the way a
|
||||
beta is: everything on this page applies to it, and so can problems no beta has shown
|
||||
([Alpha notice](legal/ALPHA_NOTICE.md)).
|
||||
- **The alphas are paused since 0.1.0-alpha.4, and a paused alpha gets no updates** — the list of anti-cheat software
|
||||
it refuses included, which arrives only inside an update. The betas run on the same .NET 11 since 0.1.0-beta.37:
|
||||
install the latest beta over the alpha. Once ten betas have followed 0.1.0-alpha.4, an older alpha no longer finds
|
||||
it as an update ([Updater](docs/11_UPDATER.md)).
|
||||
- **It shares the beta's data folder.** It copies the database into `backups` before it first opens it, and does not
|
||||
open it if the copy cannot be made; the newest three copies are kept and older ones it made are deleted.
|
||||
- **It updates only to newer alphas**, and its update channel is locked; going back to the beta means installing the
|
||||
beta over it.
|
||||
@@ -0,0 +1,45 @@
|
||||
FrameLedger
|
||||
Copyright (C) 2026 poli0981 <contact@poli0981.dev>
|
||||
|
||||
FrameLedger is free software: you can redistribute it and/or modify it under the terms of the
|
||||
GNU General Public License as published by the Free Software Foundation, version 3 of the
|
||||
License only (GPL-3.0-only).
|
||||
|
||||
FrameLedger is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
|
||||
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||
See the GNU General Public License for more details. Its full text is in the file LICENSE
|
||||
and at <https://www.gnu.org/licenses/gpl-3.0.html>.
|
||||
|
||||
|
||||
ADDITIONAL TERMS UNDER SECTION 7 OF THE GNU GENERAL PUBLIC LICENSE, VERSION 3
|
||||
|
||||
These terms apply to the material in this repository authored by poli0981. They do not
|
||||
apply to third-party components, which keep their own licences (legal/THIRD_PARTY_NOTICES.md).
|
||||
Every first-party source file points here with the line
|
||||
"Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE".
|
||||
|
||||
(b) Preservation of notices. You must preserve this notice, the copyright line above, and
|
||||
the attribution "Based on FrameLedger by poli0981 - https://github.com/poli0981/frameledger"
|
||||
in the Appropriate Legal Notices displayed by any work that contains this material
|
||||
(in FrameLedger itself: Help > About).
|
||||
|
||||
(c) Marking of modified versions. A modified version you convey must be marked in
|
||||
reasonable ways as different from the original version: it must not be named
|
||||
"FrameLedger" alone, it must say in its Appropriate Legal Notices and in its
|
||||
documentation that it is modified and by whom, and it must not present its builds,
|
||||
installers or update feed as those of the original project.
|
||||
|
||||
(e) Trademarks. These terms grant no rights under trademark law to use the name
|
||||
"FrameLedger", or the project's logo and icon, beyond describing the origin of a work
|
||||
truthfully (for example "based on FrameLedger").
|
||||
|
||||
Section 7 of the GPL permits additional terms of the kinds its paragraphs (a) to (f) list;
|
||||
the three above are of the kinds named in paragraphs (b), (c) and (e).
|
||||
|
||||
|
||||
SEE ALSO
|
||||
|
||||
FORKING.md what a redistributor of a modified version is asked to change
|
||||
legal/TRADEMARKS.md third-party names and marks
|
||||
legal/THIRD_PARTY_NOTICES.md the third-party components and their licences
|
||||
LICENSE the GNU General Public License, version 3
|
||||
@@ -4,10 +4,17 @@
|
||||
|
||||
> No telemetry. No accounts. All data stays on your machine.
|
||||
|
||||
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
|
||||
anti-cheat, and look after your data, a page each, then every screen, every setting and what to do when something goes
|
||||
wrong. What FrameLedger cannot do is on one page: [Limitations](LIMITATIONS.md). How it works with the keyboard alone, a
|
||||
screen reader or a contrast theme, and how to report a barrier: [Accessibility](ACCESSIBILITY.md). All three are in the
|
||||
app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and on the project's
|
||||
[wiki](https://github.com/poli0981/frameledger/wiki) with the developer pages.
|
||||
|
||||
<!-- accuracy-block:begin -->
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-09-26.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.8`** (2026-09-25), an unsigned installer built from that tag with its
|
||||
> checksums published beside it. The source holds the desktop app
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
|
||||
> **beta is `0.1.0-beta.45`** (2026-11-12), an unsigned installer built from that tag with its
|
||||
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
|
||||
> (library, store import, charts, settings) and the background Agent, which records a session when a
|
||||
> game in the library runs (unless you switched its recording off), injects only into games you enabled
|
||||
> and only past the safety guard, and
|
||||
@@ -15,8 +22,9 @@
|
||||
>
|
||||
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
|
||||
> OpenGL titles FrameLedger injects into. Vulkan titles are measured only when FrameLedger itself
|
||||
> starts the game with its Vulkan layer enabled, which today only the Agent's command-line launch
|
||||
> does. A Vulkan title started any other way is not observed by the layer; FrameLedger injects its
|
||||
> starts the game with its Vulkan layer enabled, which the Play button set to *Start directly* (since
|
||||
> beta.21) and the Agent's command-line launch do. A Vulkan title started any other way is not
|
||||
> observed by the layer; FrameLedger injects its
|
||||
> Direct3D component into it instead, and what that records on a Vulkan title has not been
|
||||
> verified. Direct3D 9 and every 32-bit title are not measured.
|
||||
> - **Which upscaler is running:** measured from the API a Direct3D title calls — DLSS or NIS through
|
||||
@@ -29,9 +37,17 @@
|
||||
> was measured. Intel XeSS is **not** read (its SDK licence
|
||||
> forbids it), and neither is an upscaler compiled into the game: those read `N/A`, or "Unknown
|
||||
> upscaler" when another vendor's hook ran in the game. Vulkan and OpenGL titles read `N/A`.
|
||||
> - **Quality preset:** not reported on any title measured. The one route this software may use — the
|
||||
> DLSS options a Streamline title passes with its per-frame call — has not been seen on a real
|
||||
> title, and AMD's per-frame call carries no preset.
|
||||
> - **Quality mode:** shown only when it is known. When the NVIDIA App overrides DLSS Super Resolution for
|
||||
> the game and the NVIDIA driver reports that the override applied in the session, the override's mode is
|
||||
> shown and marked as the NVIDIA App's. Otherwise the mode the game itself passed: the DLSS options a
|
||||
> Streamline title passes with its per-frame call (not yet seen on a real title), or, for FSR through
|
||||
> AMD's FidelityFX libraries, the mode whose render size the game asked for and then rendered at. In
|
||||
> every other case — FSR at a dynamic resolution among them — no mode is shown.
|
||||
> - **DLSS version:** the version of each DLSS library the game loaded and whether it came from the game or from
|
||||
> the NVIDIA driver; "DLSS 4" or "DLSS 4.5" only when the session shows it (the model preset the driver reports,
|
||||
> a measured multi-frame factor, or the NVIDIA App's Dynamic frame generation that the driver reports applied);
|
||||
> "DLSS 5" only when the game was seen running its neural rendering, otherwise "runtime loaded" when its library was
|
||||
> loaded.
|
||||
> - **Render → output resolution:** measured where the vendor's own per-frame call carries the render
|
||||
> size (AMD FidelityFX dispatches, and Streamline titles whose resource tags state it); `N/A` where it
|
||||
> does not: DLSS titles that bypass Streamline, Streamline titles whose tags carry no size, and Vulkan
|
||||
@@ -43,23 +59,76 @@
|
||||
> (menus, loading screens, a settings change), no session-wide factor is shown: the factor, Native and
|
||||
> Displayed are those of the state that held longest — five-second windows whose ratios agree within
|
||||
> 10 %, covering at least 10 s and 10 % of the time the game was presenting — and are always shown with
|
||||
> the share of the session they cover; with no such state, the reason is shown instead. DLSS-G and FSR
|
||||
> FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled into the game)
|
||||
> is shown only as active with the technology not identified, and is never named. Where a technology is
|
||||
> named but its frames could not be counted, or frame generation is not measured, the software shows
|
||||
> **Presented FPS** with a note on what it may include — never a Native figure. Where generated frames
|
||||
> were counted, the lows, median and stutter are taken over application frames only.
|
||||
> the share of the session they cover; with no such state, the reason is shown instead. The session
|
||||
> summary lists each state it held, with its share of the time and its own Native → Displayed rates.
|
||||
> DLSS-G and FSR FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled
|
||||
> into the game) is shown only as active with the technology not identified, and is never named. Where a
|
||||
> technology is named but its frames could not be counted, or frame generation is not measured, the
|
||||
> software shows **Presented FPS** with a note on what it may include — never a Native figure. Where generated
|
||||
> frames were counted, the lows, median and stutter are taken over application frames only.
|
||||
> - **Ray tracing:** Yes/No measured on Direct3D 12 from ray-dispatch and acceleration-structure-build
|
||||
> calls; the technique and path tracing are `N/A`, and so is ray tracing on other APIs.
|
||||
> - **Display mode:** how each game's window was shown — exclusive full-screen, borderless, windowed or
|
||||
> minimised — as a share of the session, with the window's size and the monitor's, in every session.
|
||||
> Exclusive full-screen is known only for Direct3D titles FrameLedger injects into, from the game's own
|
||||
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
|
||||
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
|
||||
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
|
||||
> player library or its data file — without the release letter where only the library's number is readable),
|
||||
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
|
||||
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
|
||||
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
|
||||
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
|
||||
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
|
||||
> once a second from Windows' own counters, from outside the game, in every session: a game
|
||||
> FrameLedger injects into through the handle it already holds, any other by opening it briefly with
|
||||
> the least access Windows offers (and adding up every process running its executable). Shown with
|
||||
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
|
||||
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
|
||||
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
|
||||
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
|
||||
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
|
||||
> measured from frame times.
|
||||
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
|
||||
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
|
||||
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
|
||||
> differs from the next; for Direct3D titles, how many frames asked to wait for the display and how many allowed
|
||||
> tearing — what the game asked, not what the driver did; the graphics card's clock speeds, fan speed and memory
|
||||
> temperature in every session, and, on NVIDIA cards only, how much of the time its power limit or its temperature held
|
||||
> it back, read once a second; and frames per watt — the game's own frames per second for each watt the graphics card
|
||||
> drew, never counting generated frames, `N/A` where the game's own frame rate is not known.
|
||||
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
|
||||
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
|
||||
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
|
||||
> administrator with PawnIO installed, and that reading has not yet been checked on real hardware;
|
||||
> everywhere else it is `N/A`.
|
||||
> administrator — an option, off by default, for which Windows asks at every start of the Agent — with
|
||||
> PawnIO installed, and that reading has not yet been checked on real hardware; everywhere else it is `N/A`.
|
||||
> - **Advanced metrics (since beta.39; off unless you switch it on in Settings):** with it on, a session also stores
|
||||
> what the graphics driver and the sensor library report about the hardware — the graphics card's memory, load,
|
||||
> clocks, fans, voltages and power in detail, what a display can do, the driver's settings for the game — as they
|
||||
> report it: NVIDIA's figures once a second, the sensor library's every five seconds. None of these readings has
|
||||
> been checked against another tool. The processor's, the memory's and the motherboard's need the Agent as
|
||||
> administrator with PawnIO and have never been read on real hardware; a drive's temperature is not read. The
|
||||
> Advanced page shows them as they were stored, and what the PC reads at the moment only while that page is open.
|
||||
> - **What a game tells its upscaler (since beta.40; only with Advanced metrics on, only for a game measured from
|
||||
> inside):** the output size, presets and exposure a game hands DLSS, and the sharpening, jitter, exposure, depth
|
||||
> range, field-of-view range, flags and frame time it hands FSR, are read from the arguments of the calls
|
||||
> FrameLedger intercepts and shown as the game stated them — not checked against what the upscaler did. Most games
|
||||
> set their DLSS options through a call that cannot be intercepted and show none; the FSR values need FSR 3.1 or
|
||||
> later through AMD's own library. Since beta.43 also what a game tells NVIDIA Streamline about each frame (jitter,
|
||||
> motion-vector scale, depth range, field-of-view range, how often it reset the upscaler's history — for the first
|
||||
> viewport that called, where a game has several) and how it configures FSR frame generation (the settings it asked
|
||||
> for, not whether frames were generated). Since beta.44 also what Streamline answers when a game asks about a
|
||||
> feature — its version, and what it requires (graphics APIs, V-Sync, GPU scheduling, Windows and driver versions):
|
||||
> Streamline's answer as the game received it, not a check of the PC. A game that asks only while it starts has
|
||||
> none and the session says so; the Unreal Engine games run so far ask again later, and were read. Since beta.45
|
||||
> also whether Streamline says each feature is supported and whether it is loaded, and what the game did with it
|
||||
> after FrameLedger attached — switched it on or off, allocated and freed its resources (counted to fifteen), shut
|
||||
> Streamline down: calls the game made, not a statement that a feature ran or produced anything. FSR's upscaling
|
||||
> values, Streamline's constants (seven games), its answers about a feature (seven games), the
|
||||
> frame-generation configuration (one game) and five of beta.45's six calls (five games) have been read from
|
||||
> real games; no game run so far allocated a feature's resources after FrameLedger attached, and the DLSS
|
||||
> options have not been confirmed on one yet. A game may give a value in a unit of its own: one gives
|
||||
> Streamline its field of view in degrees, and it is shown as given.
|
||||
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
|
||||
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
|
||||
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
|
||||
@@ -70,8 +139,8 @@
|
||||
> game in the library, before injection, at a session's start or by the 30 s re-check; the game's page says so,
|
||||
> and nothing turns it back on for that executable — except a user-mode exception you make yourself, per game,
|
||||
> in Settings (off by default): only where the only finding is one anti-cheat that runs entirely in user mode, with
|
||||
> no driver file in the game's folder, on a game already measured successfully at least twice. The guard still
|
||||
> runs every check under it and ends it on anything new; a ban remains possible.
|
||||
> no driver file in the game's folder. Its first two sessions are a trial, and one that does not go well ends it
|
||||
> for good. The guard still runs every check under it and ends it on anything new; a ban remains possible.
|
||||
>
|
||||
> Where a value is not measured it reads `N/A`, with two exceptions: FPS then shows Presented FPS with a
|
||||
> note on what it may include, and ray-tracing flags may show a value you set yourself, labelled as
|
||||
@@ -90,11 +159,11 @@ Most tools tell you your frame rate. FrameLedger tells you **what produced that
|
||||
- **Which upscaler is running** — DLSS / FSR, read from the API the game calls, not guessed from files on disk. Intel XeSS is not read: its SDK licence forbids it.
|
||||
- **Frame Generation, measured** — native and generated frames counted separately. Shown as `62 → 118 FPS (×1.9 FG)` when both are counted, and as a qualified Presented FPS when they are not — never as one inflated number.
|
||||
- **Ray tracing, actually detected** — including inline ray tracing (DXR 1.1 `RayQuery`), which frame-counting tools miss entirely.
|
||||
- **Per-process VRAM** and whether the driver was exceeding its budget (a real stutter explanation).
|
||||
- **The game's own VRAM and RAM** — Task Manager's figures for the game's process, read from outside the game in every session, with mean, median and peak (since beta.12). ~~and whether the driver was exceeding its budget~~ — the video-memory budget is not measured yet.
|
||||
- **Shader-compilation stutter attribution** — which frame spikes were pipeline compiles.
|
||||
- **PC latency** when the game uses Reflex.
|
||||
|
||||
Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distributions, stutter metrics, CPU/GPU temperatures, session history, cross-session comparison, and Steam/GOG/Epic/itch.io library import. UI in **English / Tiếng Việt / 日本語**.
|
||||
Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distributions, stutter metrics, CPU/GPU temperatures, session history, cross-session comparison, and Steam/GOG/Epic/itch.io/Xbox library import. UI in **English / Tiếng Việt / 日本語**.
|
||||
|
||||
## How it works — and the trade-off, stated plainly
|
||||
|
||||
@@ -107,7 +176,7 @@ FrameLedger is built to keep that risk small and to be honest about it:
|
||||
| Safeguard | |
|
||||
|---|---|
|
||||
| **Off by default** | Injection is disabled for every game until you enable it individually, after a consent prompt |
|
||||
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>**One narrow exception since beta.9 (owner decision D33):** per game, after its own disclosure and only while a Settings option (off by default) is on, a game whose only finding is one anti-cheat that runs entirely in user mode — no driver file in its folder, on no title list — and that FrameLedger has measured successfully at least twice may be hooked under a user-mode exception. The guard still runs every check under it, refuses anything else it finds, and ends it on anything new; a ban remains possible (`legal/DISCLAIMER.md` §2A).<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
|
||||
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>**One narrow exception since beta.9 (owner decisions D33, D38):** per game, after its own disclosure and only while a Settings option (off by default) is on, a game whose only finding is one anti-cheat that runs entirely in user mode — no driver file in its folder, on no title list — may be hooked under a user-mode exception. ~~and that FrameLedger has measured successfully at least twice~~ *(corrected 2026-10-03: since beta.11, D38, a grant needs no earlier session; its first two hooked sessions are a trial, and one that does not go well ends it for good.)* The guard still runs every check under it, refuses anything else it finds, and ends it on anything new; a ban remains possible (`legal/DISCLAIMER.md` §2A).<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
|
||||
| **No evasion, ever** | FrameLedger does not hide, rename, obfuscate, or disguise itself. It keeps its real name, real exports, and version info. It is meant to be plainly visible to any security software that looks. This is an architectural rule, not a setting |
|
||||
| **Read-only** | It never reads or writes game memory, never modifies game behavior, never touches saves or input, and never changes GPU clocks, fans, or power limits |
|
||||
| **Always a way out** | FrameLedger refuses rather than pushes through. When the guard finds anti-cheat, or the hook fails, or you have not enabled a game, it **stops** — and records the session anyway: start, end, duration, whatever hardware sensors your machine provides, and the reason there is nothing else. Every measured value reads `N/A`; it never estimates one.<br><br>**The way out is that it does not inject, not that it measures another way.** An earlier version of this row promised a no-injection measurement mode. It was designed around Intel PresentMon, that was dropped on 2026-08-27 after measurement, and no replacement was chosen — so **frame times require hooking**. Said in this row rather than a footnote because the row is in the SAFETY table, and a reader deciding whether to enable a game needs the real alternative, not a comfortable one |
|
||||
@@ -119,32 +188,24 @@ FrameLedger is built to keep that risk small and to be honest about it:
|
||||
| Tier | How | What you get |
|
||||
|---|---|---|
|
||||
| **1** | Injected hooks (opt-in, per game) | Everything above |
|
||||
| **2** | None — nothing is injected | **Session duration, whatever hardware telemetry your machine can provide, and why there is nothing else** (which check refused, or that the hook failed, was not enabled, or the game is 32-bit). On NVIDIA that telemetry is measured to be GPU temperature, load, power, clocks, VRAM in use and fan speed, with no elevation; AMD and Intel are untested. Everything else reads `N/A` |
|
||||
| **2** | None — nothing is injected | **Session duration, whatever hardware telemetry your machine can provide, the game's own memory use (read from Windows, outside the game; since beta.12), and why there is nothing else** (which check refused, or that the hook failed, was not enabled, or the game is 32-bit). On NVIDIA that telemetry is measured to be GPU temperature, load, power, clocks, VRAM in use and fan speed, with no elevation; AMD and Intel are untested. Everything else reads `N/A` |
|
||||
|
||||
The tier is recorded on every session and shown in the UI. Metrics unavailable at a session's tier read `N/A` — FrameLedger never substitutes an estimate for a measurement.
|
||||
|
||||
> **This ladder used to have three rungs and a middle one that measured frame times without injecting.** It was to be built on Intel PresentMon; that was dropped on 2026-08-27 after measurement, and no replacement was chosen. **So frame times, FPS and the lows are now Tier-1-only.** Said plainly because the previous README promised them without injection, and a reader who remembers that would otherwise assume it still holds.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Component | Runs as | Role |
|
||||
|---|---|---|
|
||||
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
|
||||
| `FrameLedger.Agent.exe` | Standard user (elevation optional) | Injection control, safety guard, data collection, GPU telemetry, storage |
|
||||
| `FrameLedger.Overlay.dll` | Inside the game | C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks |
|
||||
| `FrameLedger.VkLayer.dll` | Inside the game | Vulkan implicit layer (Vulkan titles use this instead of injection) |
|
||||
|
||||
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (not read yet — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Windows 10 (22H2) or Windows 11, 64-bit
|
||||
- Windows 11, 64-bit. Windows 10 (22H2) is not blocked, but FrameLedger is built on .NET 11 since 0.1.0-beta.37, which Microsoft does not support on Windows 10 Home or Pro, and FrameLedger has never been tested there
|
||||
- A processor with SSE4.2 and POPCNT — any that Windows 11 accepts. Without them FrameLedger does not start
|
||||
- A 64-bit DirectX 11/12 or OpenGL game, or a Vulkan game FrameLedger starts, for hooked (Tier-1) capture. **32-bit games — including most DirectX 9 titles — cannot be measured at all**: the component FrameLedger loads is x64 and an x64 DLL cannot enter a 32-bit process. Such a title records duration and hardware telemetry and nothing else. *(This line previously said "supported at Tier 2 only", which meant frame times without injection. That tier no longer exists.)*
|
||||
- Optional: [PawnIO](https://pawnio.eu/) for CPU temperature, read only when the Agent runs as administrator (since 0.1.0-beta.3; not yet checked on real hardware). CPU load, memory in use and all GPU telemetry work without it
|
||||
|
||||
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (~~not read yet~~ read with PawnIO, not yet checked on real hardware — see the block above), and attaching to games that themselves run elevated. ~~and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.~~ — there is no ETW fallback to rely on. **Since beta.10 it is a choice in Settings** — *Run the agent as administrator*, off by default: Windows asks every time the agent starts, games you start from FrameLedger still run as you, and `LIMITATIONS.md` says what it does not change.
|
||||
|
||||
## Install
|
||||
|
||||
> **The latest pre-release is `v0.1.0-beta.8` (2026-09-25); before it `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
|
||||
> **The latest beta is `v0.1.0-beta.45` (2026-11-12); before it `v0.1.0-beta.44` (2026-11-12), `v0.1.0-beta.43` (2026-11-12), `v0.1.0-beta.42` (2026-11-12), `v0.1.0-beta.41` (2026-11-12), `v0.1.0-beta.40` (2026-11-12), `v0.1.0-beta.39` (2026-11-11), `v0.1.0-beta.38` (2026-11-11), `v0.1.0-beta.37` (2026-11-11), `v0.1.0-beta.36` (2026-11-10), `v0.1.0-beta.35` (2026-11-09), `v0.1.0-beta.34` (2026-11-06), `v0.1.0-beta.33` (2026-11-03), `v0.1.0-beta.32` (2026-10-31), `v0.1.0-beta.31` (2026-10-26), `v0.1.0-beta.30` (2026-10-26), `v0.1.0-beta.29` (2026-10-25), `v0.1.0-beta.28` (2026-10-20), `v0.1.0-beta.27` (2026-10-20), `v0.1.0-beta.26` (2026-10-19), `v0.1.0-beta.25` (2026-10-19), `v0.1.0-beta.24` (2026-10-19), `v0.1.0-beta.23` (2026-10-14), `v0.1.0-beta.22` (2026-10-13), `v0.1.0-beta.21` (2026-10-13), `v0.1.0-beta.20` (2026-10-12), `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read the notes of the one you install — `CHANGELOG.md` links each release's own file under `docs/changelog/` — for what it measures, what it does not yet, and how to update, before installing. A source build is `docs/12_BUILD.md`.
|
||||
|
||||
1. Download the latest `FrameLedger.App-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases). It installs into `%LOCALAPPDATA%\FrameLedger.App`; your data stays in `%LOCALAPPDATA%\FrameLedger`, and uninstalling asks before touching it.
|
||||
2. SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then **More info → Run anyway**.
|
||||
@@ -156,13 +217,7 @@ Everything lives locally in `%LOCALAPPDATA%\FrameLedger`. The only network calls
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0-only. See `LICENSE`. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
|
||||
|
||||
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
|
||||
|
||||
## Documentation
|
||||
|
||||
Developer/AI-facing docs in [`docs/`](docs/). Start with `CLAUDE.md`, then `docs/19_SAFETY_AND_ANTICHEAT.md` (which constrains everything else), then `docs/01_ARCHITECTURE.md`.
|
||||
GPL-3.0-only (see `LICENSE`), with the additional terms in [`NOTICE`](NOTICE) that GPLv3 section 7 permits: keep the copyright line and the attribution, mark a changed version as changed and do not call it "FrameLedger" alone, and no trademark rights in the name ([`legal/TRADEMARKS.md`](legal/TRADEMARKS.md)). In the app: Help ▸ About. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
|
||||
|
||||
## Reporting a safety gap
|
||||
|
||||
@@ -170,6 +225,34 @@ If you find a game with anti-cheat that FrameLedger fails to detect, please open
|
||||
|
||||
**How fast a fix can reach you, stated accurately.** Blocklist entries are data rather than code, so a fix is a one-line change here. But the software has **no rules-update path yet**: it installs the blocklist that shipped with your build and never fetches another (`docs/20_OPEN_QUESTIONS.md` §S20, feed half). Until that exists, a blocklist fix reaches you **only when you install a new release**. This paragraph previously said the opposite, and the sentence it said it in was a response-time promise attached to a security-priority commitment.
|
||||
|
||||
## For developers and forks
|
||||
|
||||
FrameLedger is GPL-3.0-only free software, and you are welcome to build it, change it and redistribute it.
|
||||
|
||||
- **Build it:** [`docs/12_BUILD.md`](docs/12_BUILD.md) — `./build.ps1 check` is the whole quality gate, the same one CI runs.
|
||||
- **Contribute:** [`CONTRIBUTING.md`](CONTRIBUTING.md) — the definition of done, what will not be merged, and that a
|
||||
contribution is licensed GPL-3.0-only with the [`NOTICE`](NOTICE) terms (no CLA). Conduct:
|
||||
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reports: [`SECURITY.md`](SECURITY.md). Accessibility — the goal,
|
||||
the checks and how a barrier is reported: [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
|
||||
- **Fork or redistribute:** [`FORKING.md`](FORKING.md) — what the GPL asks of anyone who distributes builds, and the names
|
||||
a fork must change so it does not share FrameLedger's update feed, install folder, data, pipe or Vulkan layer.
|
||||
- **Find your way around:** the [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages are short, and each
|
||||
links to the document it summarises ([`wiki/`](wiki/) is their source).
|
||||
- **Read the design:** the developer documentation is in [`docs/`](docs/). Start with [`CLAUDE.md`](CLAUDE.md), then
|
||||
[`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) — which constrains everything else — then
|
||||
[`docs/01_ARCHITECTURE.md`](docs/01_ARCHITECTURE.md).
|
||||
|
||||
### Architecture
|
||||
|
||||
| Component | Runs as | Role |
|
||||
|---|---|---|
|
||||
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
|
||||
| `FrameLedger.Agent.exe` | Standard user — as administrator only when you turn that on in Settings, and Windows asks at every start (beta.10) | Injection control, safety guard, data collection, GPU telemetry, storage |
|
||||
| `FrameLedger.Overlay.dll` | Inside the game | C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks |
|
||||
| `FrameLedger.VkLayer.dll` | Inside the game | Vulkan implicit layer (Vulkan titles use this instead of injection) |
|
||||
|
||||
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
|
||||
|
||||
---
|
||||
|
||||
**Status:** pre-release (beta). Eight tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
|
||||
**Status:** pre-release (beta). Twenty-three tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
|
||||
@@ -0,0 +1 @@
|
||||
main
|
||||
+16
-2
@@ -37,8 +37,22 @@ check. The grant is a record in your own database, like the consent stamp; what
|
||||
decides itself which family it may let through. So these are security reports too: the guard letting through a family
|
||||
that has a driver, a service or a `.sys` in the floor or the rules; an exception applying to a game with a kernel
|
||||
driver in its folder, on a title list, or with a second anti-cheat; the Agent writing a grant on a pipe message
|
||||
without its own tolerant pre-scan and session count; an exception that survives a new finding, a crash or safety stop
|
||||
under it, or a changed executable; and the Overlay tolerating a family the guard did not.
|
||||
without its own tolerant pre-scan; an exception that survives a new finding, a crash or safety stop under it, or a
|
||||
changed executable; since 0.1.0-beta.11 (D38), an exception that survives a session during its two-session trial that
|
||||
did not go well, and any grant written for a game whose earlier exception failed its trial; and the Overlay tolerating
|
||||
a family the guard did not.
|
||||
|
||||
## Running the agent as administrator
|
||||
|
||||
Since 0.1.0-beta.10 the capture agent can run as administrator — an option, off by default (owner decision D34,
|
||||
`docs/01_ARCHITECTURE.md` ADR-9) — and Windows asks at every start of the agent. The residual risk is stated to the user
|
||||
rather than solved: FrameLedger installs per user and unsigned, so a program running under the same account could replace
|
||||
its files and be run as administrator when the user next accepts the prompt. What IS a security report: any way the
|
||||
agent becomes administrator WITHOUT that prompt (a task, a service, an inherited token the option did not choose); a game
|
||||
or any other program that an elevated agent starts with its own token instead of the desktop shell's; any privilege the
|
||||
agent enables (none is — `tools/chokepoint-check.ps1` forbids the enablers under `src/`); an elevated agent that runs for
|
||||
another account than the one that asked; and a named object an elevated agent creates that the same user's unelevated
|
||||
processes can no longer open, or that another user can.
|
||||
|
||||
## A safety gap — a game with anti-cheat that FrameLedger fails to detect
|
||||
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!--
|
||||
SonarCloud, analysed from CI since 2026-10-25 (docs/13_CI_CD.md §SonarCloud, owner decision D68): ci.yml's
|
||||
`sonarcloud` job passes this file to the SonarScanner for .NET's begin step (/s:). It replaces
|
||||
.sonarcloud.properties, which only Automatic Analysis read (D67). The project key, the organisation, the version
|
||||
and the token are given on the command line; everything that does not change from one run to the next is here.
|
||||
-->
|
||||
<SonarQubeAnalysisProperties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonarsource.com/msbuild/integration/2015/1">
|
||||
|
||||
<Property Name="sonar.host.url">https://sonarcloud.io</Property>
|
||||
|
||||
<!--
|
||||
What is not FrameLedger's code, or not code at all:
|
||||
- src/native/third_party: the vendored SDK headers (NVAPI, Streamline, FidelityFX, Vulkan-Headers), consumed
|
||||
unmodified (each folder's README says so and license-check holds it).
|
||||
- Strings.Designer.cs: generated by tools/resx-gen.ps1.
|
||||
- dxr_raygen_dxil.h: a compiled shader as a byte array, generated.
|
||||
- vendor-stubs: test fixtures that carry the vendors' export names and signatures on purpose.
|
||||
- tests/fixtures: the detection corpus (empty marker binaries and expected JSON).
|
||||
- legal/licenses, docs/vendor-exports.json: licence texts and a generated export list.
|
||||
- Migrations: SQLite scripts, which a SQL analyser reads as another dialect.
|
||||
And, since the scanner reads the whole checkout for the languages it finds outside the projects (PowerShell,
|
||||
YAML, JSON), what a build writes into it: the native build tree with the sources CMake fetched into it, out/,
|
||||
every project's bin/ and obj/, and the test results the coverage comes from.
|
||||
-->
|
||||
<Property Name="sonar.exclusions">src/native/third_party/**,**/Strings.Designer.cs,src/native/tools/hook-harness/dxr_raygen_dxil.h,src/native/tools/vendor-stubs/**,tests/fixtures/**,legal/licenses/**,docs/vendor-exports.json,src/FrameLedger.Infrastructure/Persistence/Migrations/**,build/**,out/**,**/bin/**,**/obj/**,**/TestResults/**</Property>
|
||||
|
||||
<!--
|
||||
Tests repeat their arrange steps on purpose; duplication there is not a defect.
|
||||
HookFamilies.cs is the Domain's mirror of FlHookFamily (ShmLayout.cs): Domain references nothing, so the enum is
|
||||
written twice by design and MetricEnumMirrorTests fails when the two differ. Six members added at once
|
||||
(0.1.0-beta.45) were 39 duplicated lines of 1,063 new ones, 3.7 % against the gate's 3 %, and failed it on the
|
||||
release's commit with no issue open. The mirror is left out of the detection; FlHookFamily itself is not.
|
||||
-->
|
||||
<Property Name="sonar.cpd.exclusions">tests/**,src/native/tests/**,src/FrameLedger.Domain/Metrics/HookFamilies.cs</Property>
|
||||
|
||||
<Property Name="sonar.sourceEncoding">UTF-8</Property>
|
||||
|
||||
<!--
|
||||
The native code: CMake's compilation database for the x64-release preset, which the job configures before the
|
||||
begin step. The sources reach the analysis through FrameLedger.Infrastructure.csproj's FlNativeSource items,
|
||||
because the scanner analyses only files an MSBuild project names. Reported against C++20, the standard
|
||||
src/native/CMakeLists.txt sets.
|
||||
-->
|
||||
<Property Name="sonar.cfamily.compile-commands">build/native/x64-release/compile_commands.json</Property>
|
||||
<Property Name="sonar.cfamily.reportingCppStandardOverride">c++20</Property>
|
||||
|
||||
<!--
|
||||
The gate's coverage: build.ps1 writes OpenCover beside the Cobertura that tools/coverage-gate.ps1 reads, one
|
||||
report per test project in TestResults/<guid>/. The second copy the trx logger keeps under In/ is not matched.
|
||||
-->
|
||||
<Property Name="sonar.cs.opencover.reportsPaths">tests/*/TestResults/*/coverage.opencover.xml</Property>
|
||||
|
||||
<!--
|
||||
Coverage is measured for the C# only. SonarCloud counts the executable lines of a file no report covers as
|
||||
uncovered - the first analysis read build.ps1's 232 lines to cover, every one uncovered, and failed the gate on the
|
||||
two a pull request changed - so the PowerShell tools (tested by their own -SelfTest cases, which no coverage tool
|
||||
reads) and the native code (Catch2 suites and the injection tests, with no coverage collector) are left out of the
|
||||
coverage figures. They are analysed for issues as everything else is.
|
||||
-->
|
||||
<Property Name="sonar.coverage.exclusions">**/*.ps1,**/*.psm1,src/native/**</Property>
|
||||
|
||||
<!--
|
||||
Roslynator, Meziantou, the VS threading analyzers and the .NET analyzers already gate the build (warnings as
|
||||
errors); what they report at a lower severity is the project's choice. Only SonarCloud's own rules are imported.
|
||||
-->
|
||||
<Property Name="sonar.cs.roslyn.ignoreIssues">true</Property>
|
||||
|
||||
<!--
|
||||
Two rules this project breaks by design everywhere they apply (the triage of 2026-10-19 in docs/13_CI_CD.md
|
||||
accepted every instance):
|
||||
- S8417, sequentially consistent atomics: the SPSC ring and the hook counters use explicit acquire/release and
|
||||
relaxed orders on purpose (07_IPC); sequential consistency would add fences on the per-present path. The rule
|
||||
key's repository is a wildcard because a header is indexed as C and a source file as C++.
|
||||
- csharpsquid:S6640, unsafe code: interop with the native layer and the shared-memory mirror, confined to
|
||||
Infrastructure and Shared (CLAUDE.md: the native layer is reachable only through Infrastructure).
|
||||
-->
|
||||
<Property Name="sonar.issue.ignore.multicriteria">atomics,unsafeInfrastructure,unsafeShared</Property>
|
||||
<Property Name="sonar.issue.ignore.multicriteria.atomics.ruleKey">*:S8417</Property>
|
||||
<Property Name="sonar.issue.ignore.multicriteria.atomics.resourceKey">src/native/**/*</Property>
|
||||
<Property Name="sonar.issue.ignore.multicriteria.unsafeInfrastructure.ruleKey">csharpsquid:S6640</Property>
|
||||
<Property Name="sonar.issue.ignore.multicriteria.unsafeInfrastructure.resourceKey">src/FrameLedger.Infrastructure/**/*</Property>
|
||||
<Property Name="sonar.issue.ignore.multicriteria.unsafeShared.ruleKey">csharpsquid:S6640</Property>
|
||||
<Property Name="sonar.issue.ignore.multicriteria.unsafeShared.resourceKey">src/FrameLedger.Shared/**/*</Property>
|
||||
|
||||
<!-- The end step waits for the quality gate, so a failed gate is a red job, not a check nobody opens. -->
|
||||
<Property Name="sonar.qualitygate.wait">true</Property>
|
||||
<Property Name="sonar.qualitygate.timeout">600</Property>
|
||||
|
||||
</SonarQubeAnalysisProperties>
|
||||
@@ -1,3 +1,6 @@
|
||||
# SPDX-License-Identifier: GPL-3.0-only
|
||||
# Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
#Requires -Version 7.0
|
||||
<#
|
||||
.SYNOPSIS
|
||||
@@ -282,8 +285,11 @@ function Invoke-Managed([bool]$FixFormat) {
|
||||
# the hosted runner); the mini dump goes to TestResults beside the trx.
|
||||
# --blame-hang did NOT stop the deadlocked xUnit v3 executable it was added for (measured 2026-09-17); the
|
||||
# wall-clock limit of Invoke-TestsWithin is what bounds a hang now. The suite takes 4-5 minutes on the runner.
|
||||
$testArgs = @('test', "`"$solution`"", '-c', $Configuration, '--no-build', '--collect:"XPlat Code Coverage"',
|
||||
'--logger', 'trx;LogFileName=results.trx')
|
||||
#
|
||||
# Two coverage formats from the one run (2026-10-25, D68): Cobertura for the coverage gate below, OpenCover for
|
||||
# SonarCloud, whose C# importer reads no Cobertura. ci.yml's sonarcloud job takes them from this run's artifact.
|
||||
$testArgs = @('test', "`"$solution`"", '-c', $Configuration, '--no-build',
|
||||
'--collect:"XPlat Code Coverage;Format=cobertura,opencover"', '--logger', 'trx;LogFileName=results.trx')
|
||||
if ($SkipIntegration) {
|
||||
Skip-Gate 'integration tests' 'the guard refuses a .NET test host that loads a `protect`-matching module (20_OPEN_QUESTIONS §S19(b)) — run ./build.ps1 check with no switches to include them'
|
||||
Invoke-TestsWithin 25 ($testArgs + @('--filter', 'Category!=Integration'))
|
||||
@@ -317,13 +323,27 @@ function Invoke-ProjectGates {
|
||||
# Being plainly identifiable to anti-cheat is a requirement, not packaging
|
||||
# polish (docs/19_SAFETY_AND_ANTICHEAT.md). Reads the built binary, because
|
||||
# what ships is what an anti-cheat vendor sees.
|
||||
#
|
||||
# beta.14 (D50): BOTH HALVES. The rules prove themselves first (ten cases,
|
||||
# nine RED, each for its own reason), then the live pass reads the native five
|
||||
# and the managed eight from the App's and the Agent's build output, whose
|
||||
# ProductVersion is the VERSION file's here (release.yml passes the tag's).
|
||||
# Under -SkipNative the managed half still runs.
|
||||
Write-Step 'versioninfo-check'
|
||||
$versionTool = Join-Path $repo 'tools/versioninfo-check.ps1'
|
||||
if ((Test-Path $versionTool) -and -not $SkipNative) {
|
||||
Invoke-Checked 'versioninfo-check' { & $versionTool -BuildDir (Join-Path $repo "build/native/x64-$($Configuration.ToLower())") }
|
||||
}
|
||||
elseif ($SkipNative) {
|
||||
Skip-Gate 'versioninfo-check' 'native build skipped, so there is no binary to inspect'
|
||||
if (Test-Path $versionTool) {
|
||||
Invoke-Checked 'versioninfo-check (self-test)' { & $versionTool -SelfTest }
|
||||
$managedDirs = @('FrameLedger.App', 'FrameLedger.Agent' | ForEach-Object { Join-Path $repo "src/$_/bin/$Configuration" })
|
||||
$productVersion = (Get-Content (Join-Path $repo 'VERSION') -Raw).Trim()
|
||||
if ($SkipNative) {
|
||||
Invoke-Checked 'versioninfo-check (managed)' { & $versionTool -ManagedOnly -ManagedDir $managedDirs -ExpectedProductVersion $productVersion }
|
||||
Skip-Gate 'versioninfo-check (native)' 'native build skipped, so there is no binary to inspect'
|
||||
}
|
||||
else {
|
||||
Invoke-Checked 'versioninfo-check' {
|
||||
& $versionTool -BuildDir (Join-Path $repo "build/native/x64-$($Configuration.ToLower())") -ManagedDir $managedDirs -ExpectedProductVersion $productVersion
|
||||
}
|
||||
}
|
||||
}
|
||||
else {
|
||||
Skip-Gate 'versioninfo-check' 'tools/versioninfo-check.ps1 not implemented yet'
|
||||
@@ -406,7 +426,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 }
|
||||
@@ -439,6 +459,51 @@ function Invoke-ProjectGates {
|
||||
Skip-Gate 'accuracy-check' 'tools/accuracy-check.ps1 not implemented yet'
|
||||
}
|
||||
|
||||
# beta.12 (D45): GPLv3 section 7 wants additional terms named "in the relevant source files", so every
|
||||
# first-party source file opens with the SPDX line and the NOTICE pointer. Self-test first (seven cases, both
|
||||
# directions), then the live pass over the tracked tree; ./tools/notice-check.ps1 -Fix writes a missing header.
|
||||
Write-Step 'notice-check'
|
||||
$noticeTool = Join-Path $repo 'tools/notice-check.ps1'
|
||||
Invoke-Checked 'notice-check (self-test)' { & $noticeTool -SelfTest }
|
||||
Invoke-Checked 'notice-check' { & $noticeTool -RepoRoot $repo }
|
||||
|
||||
# beta.17 (D53/D54): the GitHub Wiki is built from wiki/, guide/, LIMITATIONS.md and (beta.35) ACCESSIBILITY.md, and wiki.yml publishes it when a
|
||||
# release is made. A link or a section that leads nowhere, a page nothing leads to, a sidebar out of the guide's
|
||||
# order, a path that names nothing or a version written into a page is red here, not on the published wiki.
|
||||
# Self-test first (nine cases, both directions), then the live assembly into a temporary folder.
|
||||
Write-Step 'wiki-check'
|
||||
$wikiTool = Join-Path $repo 'tools/wiki-build.ps1'
|
||||
Invoke-Checked 'wiki-check (self-test)' { & $wikiTool -RepoRoot $repo -SelfTest }
|
||||
Invoke-Checked 'wiki-check' { & $wikiTool -RepoRoot $repo -Check }
|
||||
|
||||
# beta.24 (D66): CHANGELOG.md and docs/HANDOFF.md keep their paths as the index of their parts under docs/changelog/
|
||||
# and docs/handoff/. A released section left in CHANGELOG.md, a release file whose heading is not its name or that
|
||||
# links relatively, or an index and its files that do not name each other both ways is red here.
|
||||
# 2026-11-11 (D108): "the bridge never calls a setter" was a sentence in docs/18 a reviewer checked by reading one
|
||||
# file. With Advanced metrics the bridge calls forty-four NVAPI entry points, and the header declares a setter beside
|
||||
# almost every getter: each call is held to tools/nvapi-allowed-calls.txt, in both directions, and a writer or a
|
||||
# reader of an identifier (D104) is red even when the list names it. Text only - it runs with or without the native
|
||||
# build.
|
||||
Write-Step 'nvapi-readonly-check'
|
||||
$nvapiTool = Join-Path $repo 'tools/nvapi-readonly-check.ps1'
|
||||
Invoke-Checked 'nvapi-readonly-check (self-test)' { & $nvapiTool -SelfTest }
|
||||
Invoke-Checked 'nvapi-readonly-check' { & $nvapiTool -RepoRoot $repo }
|
||||
|
||||
# 2026-11-12 (D116): the same for the code loaded into a game. Advanced metrics, train B, reads more members of
|
||||
# the vendors' structs than the frame record ever needed, and the same structs hold where the player's camera is.
|
||||
# Every such read is in one header, each member on tools/overlay-allowed-fields.txt in both directions; a camera's
|
||||
# position, axes and matrices are named nowhere in the Overlay or the Vulkan layer, whatever the list says. Text
|
||||
# only.
|
||||
Write-Step 'overlay-fields-check'
|
||||
$fieldsTool = Join-Path $repo 'tools/overlay-fields-check.ps1'
|
||||
Invoke-Checked 'overlay-fields-check (self-test)' { & $fieldsTool -SelfTest }
|
||||
Invoke-Checked 'overlay-fields-check' { & $fieldsTool -RepoRoot $repo }
|
||||
|
||||
Write-Step 'docs-split-check'
|
||||
$splitTool = Join-Path $repo 'tools/docs-split-check.ps1'
|
||||
Invoke-Checked 'docs-split-check (self-test)' { & $splitTool -SelfTest }
|
||||
Invoke-Checked 'docs-split-check' { & $splitTool -RepoRoot $repo }
|
||||
|
||||
Write-Step 'changelog-check'
|
||||
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
|
||||
if (Test-Path $changelogTool) {
|
||||
@@ -454,6 +519,12 @@ function Invoke-ProjectGates {
|
||||
Write-Step 'release-notes'
|
||||
Invoke-Checked 'release-notes (self-test)' { & (Join-Path $repo 'tools/release-notes.ps1') -SelfTest }
|
||||
|
||||
# beta.18: the build id a release hands CMake (read from the clean checkout before the date substitution edits
|
||||
# legal/*.md) is read back out of the published native binaries by release.yml. Self-test only here — the live
|
||||
# pass needs that id, which only a release has (12_BUILD §Release-time token substitution).
|
||||
Write-Step 'buildid-check'
|
||||
Invoke-Checked 'buildid-check (self-test)' { & (Join-Path $repo 'tools/buildid-check.ps1') -SelfTest }
|
||||
|
||||
# 09_I18N's gate, built with the first .resx family (P3 PR-2, 2026-09-13): every key in en/vi/ja, ja
|
||||
# Safety_* marked for human review, the generated accessor current. Self-test first (at least four
|
||||
# cases must go red), then the live pass; a tree with no family is red, not skipped.
|
||||
|
||||
+42
-9
@@ -23,11 +23,18 @@
|
||||
│ ├ upscaler hooks: NGX · Streamline · FFX · XeSS │
|
||||
│ ├ RT hooks: CreateStateObject · DispatchRays · BuildRaytracingAS │
|
||||
│ ├ PSO hooks: pipeline creation (stutter attribution) │
|
||||
│ ├ per-process VRAM: IDXGIAdapter3::QueryVideoMemoryInfo │
|
||||
│ ├ (per-process VRAM via QueryVideoMemoryInfo: never built — D43 reads │
|
||||
│ │ the game's memory from outside, in the Agent's ProcessStats.dll) │
|
||||
│ └ ring writer (allocation-free, lock-free, SEH-guarded) │
|
||||
└───────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
> **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
|
||||
@@ -57,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.
|
||||
|
||||
@@ -90,8 +97,13 @@ 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).
|
||||
- **An alpha build's `--serve` waits for the Alpha notice (D74, 2026-10-31):** it reads `legal_acceptance` after opening the
|
||||
ledger and, until the App's Legal Gate has recorded the notice at the version the build carries (`Shared.AlphaNotice`),
|
||||
logs why and exits **8** — the logon task or the admin mode's prompt can start it before the App ever showed the notice.
|
||||
The App holds its own start of the Agent while the gate is open and starts it at the Accept; the maintenance verbs
|
||||
(`--register-vklayer`, `--install-task` and their reverses) are not held. The main line serves as before.
|
||||
|
||||
> **The single instance was specified here and not built until 2026-09-17**, and 0.1.0-beta.1 ran four Agents: an
|
||||
> App started as administrator was refused by the pipe of the Agent already serving (`07_IPC` §C, amended the same
|
||||
@@ -110,12 +122,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
|
||||
|
||||
@@ -126,11 +138,18 @@ 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\game-<id>-<ms>.png the images users chose for their games (beta.23, D60) — ~~covers\*.jpg, never created~~;
|
||||
a store app's own artwork is shown from where that app keeps it, never copied here
|
||||
backups\ledger-before-<v>.db an alpha build's copy of ledger.db before it first opened it, newest three (D73,
|
||||
2026-10-31; 06_DATA_MODEL §Migrations) — the alpha shares this folder with the beta
|
||||
```
|
||||
|
||||
*(beta.15, D52: `FrameLedger.exe --data-dir <folder>` reads a COPY of this folder instead — a viewer that starts and
|
||||
contacts no Agent and changes nothing on the PC, with its own `logs\` and `crashdumps\` beside the copy; `08_UI` §Shell.
|
||||
The profile's own folder is refused there.)*
|
||||
|
||||
## Key design decisions (ADR)
|
||||
|
||||
- **ADR-1 (superseded):** ~~Passive ETW only; injection out of scope.~~ Replaced by ADR-7.
|
||||
@@ -142,3 +161,17 @@ covers\*.jpg
|
||||
- **ADR-7 (2026-07, core change):** **Capture moves to in-process graphics-API hooking**, C++20 DLL + MinHook, with a Vulkan implicit layer for Vulkan. Rationale: passive detection of DLSS/upscaling/frame-generation/RT state showed large errors against real games; those states are only knowable at the API boundary. Trade-offs accepted: anti-cheat exposure (mitigated by the hard guard in `19_SAFETY`, offline titles only), crash risk in the host process (mitigated by SEH guards + fault policy + auto-disable), a second toolchain in the build, and per-API maintenance as vendors change SDKs. Scope limited to titles the user explicitly opts in.
|
||||
- **ADR-8:** **No evasion, ever** (`19_SAFETY` §What we will never build). This is an architectural constraint, not a preference — it defines what "correct" means for this codebase.
|
||||
- **ADR-9:** Elevation demoted from required to optional; the Agent runs as a standard user by default.
|
||||
**Chosen, not inherited, since beta.10 (owner decision D34, 2026-09-27):** Settings ▸ Capture agent ▸ *Run the agent as
|
||||
administrator* (`capture.run_elevated`, off by default, a versioned disclosure — `agent-admin-dialog/2` *(`/1` until 2026-11-11, when Advanced metrics widened what the option adds — D101)* — before it turns
|
||||
on). With it on, **Windows is asked every time the Agent starts** — a UAC prompt owned by the App's window when the App
|
||||
starts it, flashing on the taskbar when the logon task does — and there is no silent path: no "highest privileges" task,
|
||||
no service. The elevated Agent is started for one user (`--serve --for-user <SID>`) and refuses to run as another
|
||||
account (exit 11: a standard user answered with an administrator's password, and that account's `%LOCALAPPDATA%` is not
|
||||
this user's ledger); a declined prompt leaves a standard user's Agent that says so (`--elevation declined`,
|
||||
`HelloAck.ElevationOutcome`). With it off, an App started as administrator starts the Agent with the desktop shell's
|
||||
token. **A game an elevated Agent starts gets the shell's token too** (`Infrastructure.Startup.UnelevatedProcess`) —
|
||||
`LaunchGame` reaches the Agent over a pipe any process of the user may open, so an elevated launch would be a silent
|
||||
elevation — and nothing enables a privilege (`TokenPrivileges` reads them; `tools/chokepoint-check.ps1` forbids the
|
||||
enablers under `src/`). It buys what it always did: attaching to a game that runs as administrator, and the CPU
|
||||
temperature with PawnIO. It does not open a process an anti-cheat driver protects (D21), and a Vulkan game that runs as
|
||||
administrator stays unmeasured — the Khronos loader ignores the HKCU implicit layers for an elevated process.
|
||||
+33
-17
@@ -6,10 +6,13 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
|
||||
### FR-1 Game library
|
||||
- FR-1.1 Add game by picking an `.exe`, or drag-dropping an exe/shortcut.
|
||||
- FR-1.2 Auto-import from Steam, GOG Galaxy, Epic, itch.io with a review checklist. **Import never enables hooking for anything.**
|
||||
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable.
|
||||
- FR-1.2 Auto-import from Steam, GOG Galaxy, Epic, itch.io with a review checklist — and, since beta.33 (D79), the Xbox app and the Microsoft Store (GDK titles: each drive's `.GamingRoot` folders and each game's package files, `05_DETECTION` §Platform signatures & metadata). **Import never enables hooking for anything.**
|
||||
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable. *(The cover is built since beta.23, D60: the user's own image, else the Steam or GOG GALAXY app's artwork on this PC — `08_UI` §Games; since beta.33 also the square logo and splash image an Xbox game ships in its own package folder.)*
|
||||
- FR-1.4 Remove game (asks whether to keep or delete its sessions).
|
||||
- FR-1.5 "Supports" row shows shipped-capability hints (DLSS/FSR/XeSS/FG) — visually distinct from measured per-session values (`05_DETECTION` §Capability hints).
|
||||
- FR-1.7 Delete all sessions (beta.11, owner decision D40): of one game from its page, or of every game from Settings ▸ Data, after a confirmation that says how many — with their frame and sensor series and notes; the library, the settings and every consent stay. The Agent deletes them (the rows are its, `06_DATA_MODEL` §Writer ownership) and refuses while a session it would delete under is being recorded.
|
||||
- FR-1.8 Uninstalled games leave the library by themselves (beta.19, owner decision D55, amending D41): an entry whose executable has been gone for ten minutes — its drive connected and the folder it was installed in still there, so an unplugged or re-lettered drive never counts, and neither does a folder Windows will not list (`ExecutablePresenceProbeTests`) — and that has no session (stored, being recorded or waiting to be recovered) is removed by the Agent, behind Settings ▸ Data ▸ *Remove uninstalled games* (on by default). Never an entry carrying an anti-cheat block, an exception or a failed-trial mark (FR-2.2, rule 2). The App is told (`GameRemoved`).
|
||||
- FR-1.9 Play (beta.21, owner decision D59): a game's page and each library entry start the game — through the app of the store whose own records name its folder (Steam, the Epic Games Launcher, GOG GALAXY, itch), or by the agent's launch mode (FR-3.2), as Settings ▸ Games says; never as administrator, and never in a viewer (`08_UI` §Games). *(beta.33, D80: a game the Xbox app or the Microsoft Store installed starts through Windows in either mode — its package activated as its Start-menu tile does — and never by the agent's launch mode, which cannot start it in its package.)*
|
||||
- FR-1.6 Recording switch per entry (2026-09-23, HANDOFF D29): off, the program is not watched at all — no session, no measurement, no injection — and a session of it that is running stops. On by default; entries an old import made for Steam's own tools start with it off. The library card says "Not recorded".
|
||||
|
||||
### FR-2 Hooking consent & control (new, safety-critical — see `19_SAFETY`)
|
||||
@@ -18,18 +21,18 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-2.3 The runtime guard refuses injection and refuses to continue a session when anti-cheat is detected. **No override exists anywhere in the UI, config, or CLI.** *(Since 2026-09-26 one narrow, evidence-bound exception exists — FR-2.8. It is not an override: the guard still runs every check and decides itself which anti-cheat family it may let through.)*
|
||||
- FR-2.4 Global "disable all hooking" kill switch in Settings; also honored by the Vulkan layer.
|
||||
- FR-2.7 (owner decision 2026-09-22; it was a per-game override for one day, withdrawn) A finding about a game — anti-cheat named in its process, on its title lists or in its folder — turns hooking off for that game wherever the guard makes it: at the pre-scan, at a session's start, at the 30 s re-scan, or (since 2026-09-25) at the Agent's pre-scan of the library. The row carries the reason, the game's page and the notice say so, and nothing overrides it (`19_SAFETY` §What a finding does to the game).
|
||||
- FR-2.8 (owner decision D33, 2026-09-26) **The user-mode anti-cheat exception.** A Settings option, off by default, lets the user grant a per-game exception to a game whose only anti-cheat findings are ONE family that is user-mode throughout (no driver, service or `.sys` in the floor or the rules), whose install tree holds no `.sys`, which is on no title list, and which FrameLedger has measured hooked at least twice (successful Tier-1 sessions). The Agent computes that eligibility itself; the user grants each game through a versioned disclosure that states the ban risk; hooking is then turned on through FR-2.1's dialog as ever. Machine-wide drivers and services, title lists, kernel drivers in the game folder, the fuzzy tier, a scan that could not finish, an unreadable process, a 32-bit game, the kill switch and Vulkan are never excepted. A new finding, a crash / safety unhook / Overlay stop under it, or a changed executable ends it; the option off suspends it; the block itself is never cleared and stays shown (FR-2.2). Sessions under it are marked with the family (`19_SAFETY` §The user-mode exception).
|
||||
- FR-2.8 (owner decision D33, 2026-09-26) **The user-mode anti-cheat exception.** A Settings option, off by default, lets the user grant a per-game exception to a game whose only anti-cheat findings are ONE family that is user-mode throughout (no driver, service or `.sys` in the floor or the rules), whose install tree holds no `.sys`, which is on no title list, ~~and which FrameLedger has measured hooked at least twice (successful Tier-1 sessions)~~ and no exception of which ever ended during its trial (D38, 2026-10-03: a grant needs no session; its first two hooked sessions are a trial, and an end during the trial — any end below, or a stored hooked session with no frames or an abnormal exit — ends it for good, `games.ac_exception_trial_failed_at`). The Agent computes that eligibility itself; the user grants each game through a versioned disclosure that states the ban risk; hooking is then turned on through FR-2.1's dialog as ever. Machine-wide drivers and services, title lists, kernel drivers in the game folder, the fuzzy tier, a scan that could not finish, an unreadable process, a 32-bit game, the kill switch and Vulkan are never excepted. A new finding, a crash / safety unhook / Overlay stop under it, or a changed executable ends it; the option off suspends it; the block itself is never cleared and stays shown (FR-2.2). Sessions under it are marked with the family (`19_SAFETY` §The user-mode exception).
|
||||
- FR-2.5 Repeated crashes shortly after injection auto-disable hooking for that game, with an explanation and a manual re-enable path.
|
||||
- FR-2.6 Users can always see, per session, which tier produced the data.
|
||||
|
||||
### FR-3 Session capture
|
||||
- FR-3.1 Watcher detects tracked exe launches (1 Hz) and captures automatically at the highest permitted tier.
|
||||
- FR-3.2 Launch mode: start the game from FrameLedger for suspended-launch injection (catches startup-time upscaler init).
|
||||
- FR-3.2 Launch mode: start the game from FrameLedger for suspended-launch injection (catches startup-time upscaler init). *(The App reaches it since beta.21: Play set to Start directly sends `LaunchGame` — FR-1.9.)*
|
||||
- FR-3.3 Attach mode for games launched externally; sessions flagged `late_attach`.
|
||||
- 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.
|
||||
|
||||
@@ -38,9 +41,9 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-4.2 **Native vs Displayed FPS + FG factor**, always shown together (`62 → 118 FPS (×1.9 FG)`).
|
||||
- FR-4.3 *(Tier 1)* Measured upscaler identity, quality preset, render resolution, output resolution, upscale ratio; mid-session changes captured as segments.
|
||||
- FR-4.4 *(Tier 1)* Measured RT activity (`rt_frame_pct`, `rays_per_pixel`, RT PSO count); RR from the NGX feature; PT as a confidence-scored suggestion only.
|
||||
- FR-4.5 *(Tier 1)* Per-process VRAM usage/budget and budget-exceeded percentage.
|
||||
- FR-4.5 *(Tier 1)* Per-process VRAM usage/budget and budget-exceeded percentage. *(beta.12, owner decision D43: the **usage** half is met for **both tiers** from outside the game — the game process's dedicated and shared GPU memory, Task Manager's columns — with its private working set, working set and commit beside it, mean / median / peak (`03_METRICS` §Game process memory). The budget and its exceeded percentage stay unmeasured, `20_OPEN_QUESTIONS` §M11.)*
|
||||
- FR-4.6 *(Tier 1)* PSO-compilation stutter attribution; *(Tier 1 + Reflex)* PC latency avg/p95.
|
||||
- FR-4.7 Telemetry aggregates: CPU/GPU temp, hotspot, loads, power, throttle %, RAM.
|
||||
- FR-4.7 Telemetry aggregates: CPU/GPU temp, hotspot, loads, power, throttle %, RAM. *(beta.12: every stored series also has its median and minimum, in `sensor_stats_json`.)*
|
||||
- FR-4.8 Sufficiency guards: 0.1% Low needs ≥ 10,000 app frames, 1% Low ≥ 1,000; else `N/A`.
|
||||
- FR-4.9 Any metric unavailable at the session's tier renders `N/A` — never an estimate presented as measurement.
|
||||
|
||||
@@ -50,18 +53,22 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-5.3 Charts handle ≥ 500k points via min/max decimation; zoom/pan; PNG export.
|
||||
- FR-5.4 Native/Displayed toggle wherever FG data exists.
|
||||
- FR-5.5 Stutter markers annotated with cause when known (`PSO compile`, `VRAM budget exceeded`).
|
||||
- FR-5.6 *(owner decision D101, 2026-11-11)* **Advanced metrics**: an option, off by default, and a page of its own that shows what the vendor interfaces make available — NVAPI, LibreHardwareMonitor through PawnIO, and in later releases Streamline and FidelityFX inside the game — each value under what it belongs to, the PC or one session, and each value that is not read listed with the reason. Off means nothing more is read or stored. `18_GPU_VENDOR_APIS` §Advanced metrics is the design and the inventory. *(Not built: the catalog exists, nothing reads it yet.)*
|
||||
|
||||
### FR-6 History & comparison
|
||||
- FR-6.1 Sessions table per game: date, duration, tier badge, Native, Displayed, FG×, lows, resolution + upscaler, RT/PT/RR chips, crash badge, tags.
|
||||
- FR-6.2 Compare 2–5 sessions; **mixed-tier comparisons require explicit acknowledgement** and are marked on the chart.
|
||||
- FR-6.3 Hardware snapshot per session; trend charts mark changes ("GPU driver 572.16 → 576.02").
|
||||
- FR-6.3 Hardware snapshot per session; trend charts mark changes ("GPU driver 572.16 → 576.02") — since beta.30 a
|
||||
numbered badge per day that changed, its changes listed under the chart (owner decision D70).
|
||||
- FR-6.6 Charts across a game's sessions (beta.11, owner decision D39): the Sessions tab opens with an overview of every hooked session's rate and lows (Presented FPS, or Native and Displayed where frame generation was measured; 1% and 0.1% lows), a click selecting the session; and the Trend draws more metrics beside the selected one, two units at most (the second against the right axis).
|
||||
- FR-6.4 Sessions with mid-session settings changes are excluded from trends by default, with a toggle.
|
||||
- FR-6.5 Session tags and notes.
|
||||
|
||||
### FR-7 Detection
|
||||
- FR-7.1 Static: engine, engine version, store platform, store id, publisher, game version (`05_DETECTION`).
|
||||
- FR-7.2 Runtime: API, present mode, swap effect, HDR, upscaler, FG, RT — all Tier 1, all measured.
|
||||
- FR-7.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.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.** *(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`).
|
||||
@@ -74,10 +81,14 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-9.3 Chart PNG.
|
||||
|
||||
### FR-10 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.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 *(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. 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.
|
||||
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.
|
||||
|
||||
### FR-12 Updates
|
||||
Velopack against GitHub Releases; silent startup check, manual check in Help; error dialogs mapped per `11_UPDATER`. **Updates never apply while a game is hooked** — deferred to session end (the DLL on disk must not change under a running game).
|
||||
@@ -94,7 +105,7 @@ Draw live FPS/frametime/upscaler info inside the game. Only for games already ho
|
||||
## Non-functional requirements
|
||||
|
||||
- **NFR-1 Game-side overhead:** ≤ 1 µs per present, ≤ 8 MB resident, measured game FPS impact ≤ 0.5% vs uninstrumented.
|
||||
- **NFR-2 Agent overhead:** ≤ 1% of one core during capture, ≤ 150 MB working set, ~0% idle.
|
||||
- **NFR-2 Agent overhead:** ~~≤ 1% of one core during capture~~ **≤ 2.5 % of one core during capture** *(owner decision D117, 2026-11-11: the 1 % had never been measured; measured in a real Agent it is 1.93 % with Advanced metrics off and 2.04 % with it on — `20_OPEN_QUESTIONS` §M16, `tools/agent-cost.ps1` — nearly all of it the once-a-second read of the graphics card's sensors, which stays)*, ≤ 150 MB working set *(measured: 113 MiB off, 119 MiB on)*, ~0% idle. *(D101, 2026-11-11: the limits hold with Advanced metrics on — FR-5.6. Its reads run on a thread of their own, the slow ones seldom, and with no game running only while its page is open (D107), so "~0% idle" is not spent on it. Measured on the development PC in a session that is not hooked; a hooked session, an elevated Agent with PawnIO's groups and a real game are the owner's run, `HANDOFF` §Owner-only.)*
|
||||
- **NFR-3 Stability:** faults **originating in our own hook bodies** are contained by `FL_HOOK_GUARD`, counted, and self-disable the Overlay after 3 occurrences; the safety-unhook path completes within one frame. The Overlay adds no allocation, lock, syscall or logging to the present path.
|
||||
|
||||
> This deliberately does **not** say "must never crash a game" (`20_OPEN_QUESTIONS` §H8). SEH containment cannot reliably catch stack overflow, cannot intercept `__fastfail` — and `-D_HAS_EXCEPTIONS=0` converts a would-be STL throw into exactly that (`spike-notes.md` §H3) — and does not help when the game installs a vectored exception handler that runs first. An absolute promise the mechanism cannot support does not belong in a requirement, and must stay out of user-facing text: the Disclaimer already says injection carries risk, and that wording is the honest one.
|
||||
@@ -102,8 +113,13 @@ Draw live FPS/frametime/upscaler info inside the game. Only for games already ho
|
||||
- **NFR-5 Storage:** raw series ≤ 3 MB per hour compressed; 50 games × 50 sessions ≤ 500 MB at default retention.
|
||||
- **NFR-6 Accuracy:** per `03_METRICS` §Accuracy budget, stated per tier.
|
||||
- **NFR-7 Resilience:** power loss loses at most the last 60 s of raw data; DB never corrupts (WAL + transactions); Agent restart recovers `.partial` sessions as `interrupted`.
|
||||
- **NFR-8 OS support:** Windows 10 22H2+ and Windows 11, x64. No ARM64 in v1.
|
||||
- **NFR-9 Accessibility:** full keyboard navigation, adequate contrast in both Fluent themes, Per-Monitor V2 DPI awareness. *(What each clause means for this app, and the check that holds it: `08_UI` §Accessibility, P4 PR-8.)*
|
||||
- **NFR-8 OS support:** ~~Windows 10 22H2+ and Windows 11, x64.~~ **Windows 11, x64** — the Windows that Microsoft
|
||||
supports .NET 11 on, which FrameLedger is built on since 0.1.0-beta.37. **Windows 10 22H2 is not blocked** (the code
|
||||
is still held to it: `SupportedOSPlatformVersion` 10.0.19045.0, CA1416) **and is neither tested nor supported**
|
||||
there; a processor needs SSE4.2 and POPCNT (x86-64-v2), without which .NET 11 does not start. No ARM64 in v1.
|
||||
*(Amended 2026-11-11, owner decisions D94 and D95 — `12_BUILD` §The main line's .NET. Windows 10 was never tested
|
||||
on any version: `ACCESSIBILITY.md`, `08_UI` §Accessibility.)*
|
||||
- **NFR-9 Accessibility:** full keyboard navigation, adequate contrast in both Fluent themes, Per-Monitor V2 DPI awareness. *(What each clause means for this app, and the check that holds it: `08_UI` §Accessibility, P4 PR-8.)* *(Widened 2026-11-09, beta.35, owner decisions D88–D91: and a screen reader reads every control and value and is told what changes; Windows contrast themes are followed; nothing is shown by colour alone. The goal behind all of it is WCAG 2.2 AA as W3C's WCAG2ICT applies it to desktop software — a goal, not a conformance claim — stated to users in `ACCESSIBILITY.md`.)*
|
||||
- **NFR-10 Offline-first:** everything except updates and opt-in metadata works with zero connectivity.
|
||||
- **NFR-11 Auditability:** the entire set of hooks is enumerable in `17_HOOK_ENGINE` §Hook inventory and matches the code; a reviewer must be able to verify in minutes that nothing reads game memory.
|
||||
|
||||
@@ -111,4 +127,4 @@ Draw live FPS/frametime/upscaler info inside the game. Only for games already ho
|
||||
|
||||
**Permanently:** any evasion technique (`19_SAFETY`); reading/writing game memory; kernel drivers; hardware control (overclocking, fan curves, power limits — `18_GPU_VENDOR_APIS` is read-only); online/competitive titles.
|
||||
|
||||
**v1:** Microsoft Store/UWP/Game Pass titles (packaged-app injection constraints); macOS/Linux; cloud sync; benchmark automation; ARM64. **Tier-1 capture of 32-bit games, including most Direct3D 9 titles** — the Overlay is x64-only and an x64 DLL cannot be loaded into a 32-bit process; those titles are Tier 2, which since 2026-08-28 means **not measured at all** — duration, sensors and the reason (`17_HOOK_ENGINE` §Build profile, `20_OPEN_QUESTIONS` §Scope).
|
||||
**v1:** ~~Microsoft Store/UWP/Game Pass titles (packaged-app injection constraints)~~ *(narrowed 2026-11-03, beta.33, owner decisions D78–D80: Microsoft Store, Xbox app and PC Game Pass titles built on the GDK — full-trust packages — are in scope; what "the constraints" are was measured in `spike-notes` §25. UWP apps, which run in an app container, stay out: refused with a reason of their own)*; macOS/Linux; cloud sync; benchmark automation; ARM64. **Tier-1 capture of 32-bit games, including most Direct3D 9 titles** — the Overlay is x64-only and an x64 DLL cannot be loaded into a 32-bit process; those titles are Tier 2, which since 2026-08-28 means **not measured at all** — duration, sensors and the reason (`17_HOOK_ENGINE` §Build profile, `20_OPEN_QUESTIONS` §Scope).
|
||||
+339
-14
@@ -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.
|
||||
|
||||
@@ -38,6 +38,9 @@ Let `D` = session duration (first → last present), `F_app` = frames the *game*
|
||||
| **Stutter time %** | `Σ ft_app[stutter] / Σ ft_app × 100` | 1 |
|
||||
| **PC latency** | mean/p95 of `reflexLatencyUs` when Reflex reports it | **1 only** |
|
||||
| **PSO stutter %** | share of stutter frames with `psoCreatedThisFrame > 0` | **1 only** |
|
||||
| **Time below 30 / 60 FPS** (beta.14) | share of `Σ ft_app` in frames that count as below X — `ft > 1.10 × 1000/X`, or the nine-frame rolling median `> 1.02 × 1000/X` (§Pacing) | 1 |
|
||||
| **Time below refresh** (beta.14) | the same over **presents**, X = `display_monitor_hz` — the display's rate, so over what the display received | 1 |
|
||||
| **Frame to frame** (beta.14) | mean `\|ft_app[k] − ft_app[k−1]\|` over neighbouring intervals, ms | 1 |
|
||||
|
||||
**Percentile method:** sort ascending, linear interpolation between closest ranks (NumPy `linear` / Excel `PERCENTILE`). Document it, test it — tools differ and users will compare numbers.
|
||||
|
||||
@@ -90,6 +93,41 @@ toward the session's data-quality warnings.
|
||||
|
||||
**Sufficiency guards (FR-4.8):** 0.1% Low needs ≥ 10,000 application frames, 1% Low ≥ 1,000; otherwise `N/A`.
|
||||
|
||||
## Pacing (beta.14, D49)
|
||||
|
||||
**Time below 30 / 60 FPS and below the refresh rate** are shares of the measured time — `Σ ft (counted) / Σ ft` — so a long
|
||||
hitch weighs what a player sits through, not one frame among many. **Frame to frame** is the mean change from one frame
|
||||
time to the next over neighbouring intervals (`FrameTimeSeries.FollowsBreak`: a pair with an interval left out between —
|
||||
a gap, a pause — is not a pair); it is low when pacing is even whatever the rate.
|
||||
|
||||
**Which frames count as below X — and why not "longer than 1000 / X".** The present-to-present interval of a game held
|
||||
at X jitters around `1000 / X` by a few tenths of a millisecond, half of it on the long side. Measured on a copy of the
|
||||
owner's ledger (2026-10-06): a GIRLS' FRONTLINE 2 session capped at 60 (median 16.63 ms, 296,380 frames) reads **50.0 %**
|
||||
of its time "below 60" under the plain rule, and a rolling mean does not help — the local average of a game held at 60
|
||||
sits on the threshold. So a frame counts when **it is itself more than 10 % longer** than `1000 / X` (a long frame, never
|
||||
jitter) **or the median of the nine frames around it** (`RollingMedian`, the stutter rule's centered window and edges) **is
|
||||
more than 2 % longer** (a rate that stays below X). The same session reads 9.6 % (its time below 30 alone is 4.7 %); with
|
||||
a 0.4 ms jitter a steady 58 FPS reads 93 %, a steady 60.2 reads 0.7 %, and a 100 ms hitch counts its own 100 ms and no
|
||||
neighbour's. **The cost, stated:** a rate less than 2 % under X (58.8–60 FPS for 60) reads partly as at X — a steady 59
|
||||
reads 40 %. `Domain.Metrics.FramePacing`; `FramePacingTests` pins each of these.
|
||||
|
||||
**Which series.** 30, 60 and frame to frame are over `ft_app` — application frames where generated frames were counted
|
||||
(rule 6: generated frames do not make a game run at 60), the presents otherwise, labelled `(presented)` as every
|
||||
present-only statistic is. **The refresh share is over the presents**, generated ones included: it is the display's rate,
|
||||
and what matters there is what the display received — a ×4 frame-generation session on a 240 Hz display reads near 0 %,
|
||||
and over its application frames it would read 100 % whatever the pacing. It needs `display_monitor_hz` (the display
|
||||
tally's, §Display mode): a session recovered from its crash file has none, and reads N/A. **Sufficiency:** the 1 % low's
|
||||
1,000 frames; below it every value is N/A.
|
||||
|
||||
## Sync — what the presents asked for (beta.14, D49)
|
||||
|
||||
`vsync_present_pct` is the share of the dominant stream's presents with a sync interval of one or more (the game asked
|
||||
to wait for the display), `tearing_allowed_pct` the share with `DXGI_PRESENT_ALLOW_TEARING`. Both arguments were in every
|
||||
Direct3D record since P1 (`FL_MEASURED_PRESENT_ARGS`) and read by nothing; `sessions.sync_interval_mode` (0001) gets its
|
||||
first writer with them — `on` (every present), `off` (none), `mixed`. **Asked, not obtained:** a driver setting or a
|
||||
variable-refresh display can override the request, and nothing in the process says which won. OpenGL's
|
||||
`wglSwapBuffers` and Vulkan's `vkQueuePresentKHR` carry neither argument: N/A, never 0 %. Tier 1 only.
|
||||
|
||||
## Frame Generation — ground truth (Tier 1)
|
||||
|
||||
This is the metric the rewrite exists for. Resolution ladder, highest confidence first; the winning rung is stored in `fg_source`:
|
||||
@@ -428,8 +466,83 @@ 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
|
||||
> ### The mix — owner decision 2026-10-19 (D62)
|
||||
>
|
||||
> **The steady state names one state; a session can hold several.** A player who tries ×2, ×3 and ×4 in one session,
|
||||
> or whose NVIDIA App runs frame generation as *Dynamic*, got the longest state alone. Since beta.24 **every** state is
|
||||
> stored beside it: `Domain.Metrics.FgMix`, over the same five-second windows the steady state is read over (one cut,
|
||||
> `FgSlices.Cut`), from where `FgWindow` starts (the claimed suffix).
|
||||
>
|
||||
> **The rule.** Each window is classified by its own `presents ÷ tokens`: **active** (≥ 1.5, with ≥ 8 samples and
|
||||
> tokens), **no frame generation** (≤ 1.05, with ≥ 8 samples and tokens — and only where a counted `none` is allowed:
|
||||
> not on the shape `FgLadder.WithholdNone` withholds, §Frame Generation), else **not classified** (too few samples, no
|
||||
> tokens, the band between 1.05 and 1.5, or a withheld `none`). The active windows are grouped by repeating the steady
|
||||
> state's own extraction on what is left — the ±10 % cluster holding the most time, pooled, redrawn once — until no
|
||||
> cluster remains; a cluster under **10 s** returns its windows to *not classified*. A state's factor, Native and
|
||||
> Displayed are its own (Σ presents ÷ Σ tokens over its windows; each rate over its own seconds); a row's share is its
|
||||
> seconds over every window's, so the rows sum to 100 % and the longest state's share is `fg_steady_share` when the
|
||||
> session has one. Rows: the states by rising factor, then *no frame generation*, then *not classified*. **Never an
|
||||
> average across states** (CLAUDE.md rule 6), and ×5 and ×6 are 20 % apart and never pool.
|
||||
>
|
||||
> **Amended 2026-10-19 (beta.26): a window needs application frames, and a ratio frame generation can produce.**
|
||||
> "≥ 8 samples and tokens" was built as eight presents and ONE token, and the owner's Silent Hill 2 session listed a
|
||||
> ×1336.0 state — the session's first ten seconds, the game compiling its shaders, presented with one token per window
|
||||
> (`spike-notes` §22); the DLSS line cited it. A window is now read only with ≥ 8 presents AND ≥ 8 application frames (`FgSlices.Slice.IsReadable`, both
|
||||
> active and *no frame generation*), and is active only up to **×8** (`FgWindow.GenerationCeiling`: no shipping
|
||||
> technology generates more than five frames per application frame, DLSS 4.5's ×6); every other window is *not
|
||||
> classified*. The steady state reads the same windows, so it can no longer pick such a stretch either. A session-wide
|
||||
> or live ratio that held above ×8 is refused as **`beyond_generation`** (after uniformity: a session that changed
|
||||
> state stays `non_uniform` and keeps its steady state and its mix). **A stored mix is read by today's rule**
|
||||
> (`FgMixRecord.Parse`): a row above ×8, or whose windows averaged fewer than eight application frames, joins the
|
||||
> not-classified time — so the session stored with the ×1336.0 row reads ×2.0, ×3.0, ×6.1, no frame generation and
|
||||
> 30 s not classified, and its shares still add up.
|
||||
>
|
||||
> **Amended 2026-10-20 (beta.27): a state is near a whole multiplier.** Every frame generation that ships multiplies by
|
||||
> a whole number — ×2 for FSR, XeSS and DLSS 3, up to ×4 for DLSS 4, up to ×6 for DLSS 4.5 — and its windows read near
|
||||
> one: 1.98, 3.01, 6.06. The owner's Silent Hill 2 session of 2026-10-20 under the NVIDIA App's *Dynamic* mode listed
|
||||
> a **×2.52** state for 12.8 s: windows in which the multiplier stepped between ×2 and ×3 read ×2.21–×2.70 — at 135 s,
|
||||
> 251 application frames followed by one generated frame and 270 by two — and three of them pooled into a state nobody
|
||||
> held (`spike-notes` §23). A window is now active only within **10 %** of a whole multiplier of two or more
|
||||
> (`FgWindow.IsNearWholeMultiplier`: ×1.8–×2.2, ×2.7–×3.3, … ×5.4–×6.6); a window between two is *not classified*, and
|
||||
> the steady state reads the same windows. A stored mix is read by the same rule (`FgMixRecord.Parse`): that session
|
||||
> reads ×2.0 27.30 %, ×3.0 62.41 %, no frame generation 2.93 % and 7.36 % not classified. Of the 70 sessions in the
|
||||
> owner's ledger copy it was the only stored row between two multipliers.
|
||||
>
|
||||
> **When there is a mix.** Only where the session's frame generation was named (`Named` / `ActiveUnidentified`) and the
|
||||
> session-wide count either stood or was refused as `NonUniform` / `AmbiguousBand` — a change of state is exactly what a
|
||||
> mix describes. Every other refusal (not counted, unattributed, interleaved streams, either saturation, no
|
||||
> evaluations, too short, no batches, and since beta.26 a ratio beyond any frame generation) gets none — slicing does not make a refused record set trustworthy, the steady
|
||||
> state's rule — and so does a session in which no state formed.
|
||||
>
|
||||
> **Stored, never replayed.** `sessions.fg_mix` (schema 0020) holds the rows as JSON (`FgMixRecord`), written by the
|
||||
> recorder's aggregation beside the steady state. A session recorded before has none and is not rebuilt: `frame_blobs`
|
||||
> keep one Generated bit per frame and lose the presents only DXGI counted, so a mix rebuilt from them would be wrong on
|
||||
> exactly the titles that need one. The summary says so in one line for a session that counted frame generation and has
|
||||
> no mix.
|
||||
>
|
||||
> **What it shows, and what it cannot.** The summary's block (`08_UI` §Session summary): a bar of the shares, then a
|
||||
> row per state — `×4.0 frame generation · 35.33% · 70 → 282 FPS · 2m 05s` —, *No frame generation* with its one rate,
|
||||
> *Not classified* with its time; shown when the mix has two rows or more (one state throughout is the readout's own
|
||||
> number). Frame generation that changes faster than the five-second windows — the NVIDIA App's *Dynamic* mode can —
|
||||
> reads partly as *not classified* rather than as a factor nobody held. Above the rows, how frame generation was SET:
|
||||
> the NVIDIA App's Frame Generation Mode from the driver profile stored with the session (*Dynamic, up to ×6, target:
|
||||
> max refresh rate*; *Fixed ×4*), or that the profile sets none — the game's own menu chose
|
||||
> (`NvidiaOverrides.FrameGenerationContext`). That line is configuration, never one of the rows. The multiplier chosen
|
||||
> in a game's menu is not read — it reaches the runtime through `sl::DLSSGOptions`, the route `HANDOFF` §2b refused —
|
||||
> so the measured row is its evidence. The dynamic ceiling (`NGX_DLSSG_DYNAMIC_MULTI_FRAME_COUNT_MAX`) is decoded as
|
||||
> `NGX_DLSSG_MULTI_FRAME_COUNT` is (frames generated per rendered frame) and the automatic target as "max refresh
|
||||
> rate"; NVIDIA's header names neither, and owner-only item 20(a) checks both against the App. *(2026-11-06, beta.34:
|
||||
> the ceiling's decode held on the owner's Phantom Blade Zero — a ceiling of 5 held states up to ×6.0, a ceiling of 2
|
||||
> nothing above ×3.0 — `spike-notes` §26. And the context line is no longer the only place the Dynamic mode shows: the
|
||||
> DLSS line names DLSS 4.5 where the driver reports Dynamic applied, D83, `05_DETECTION` §DLSS generation.)*
|
||||
|
||||
`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 —
|
||||
@@ -507,12 +620,34 @@ carries the three shapes.
|
||||
> or memory, CLAUDE.md rule 4) and the driver's own per-process override report in full (`ngx_driver_words`: preset,
|
||||
> mode, ratio beside the masks). Both are shown as what the driver was set to do and what it says it did — "NVIDIA
|
||||
> profile …: DLSS override (preset K, Quality)" — and neither changes a measured value, a rung of the upscaler ladder or
|
||||
> the frame-generation factor: those stay what the hooks saw. A profile override the hooks contradict is two true
|
||||
> statements about different things, and the page shows both.
|
||||
> the frame-generation factor: those stay what the hooks saw. ~~A profile override the hooks contradict is two true
|
||||
> statements about different things, and the page shows both.~~ *(Struck 2026-10-19 for the quality mode only — the
|
||||
> amendment below; render size, ratio and the frame-generation factor are unchanged.)*
|
||||
>
|
||||
> **Amended 2026-10-19 (owner decision D63): the override is the standard for the quality MODE — when the driver
|
||||
> confirms it applied.** The owner, shown the note above: an NVIDIA App override is what the game ran at, so it is the
|
||||
> mode a session states. `Application.Recording.QualityResolver`, read at display time from what every session already
|
||||
> stores (`ngx_driver_words` since P2, `driver_profile` since beta.8 — so a session recorded before reads alike): when
|
||||
> DLSS super resolution ran (a hook named it, or the driver reports the feature created and evaluated) and the driver's
|
||||
> per-process report says the override applied (`ENABLED` with `PERF_MODE`, `SR_DLAA_MODE` or `SCALING_RATIO`), the mode
|
||||
> is the profile's `NGX_DLSS_SR_MODE` (documented: 0 Performance, 1 Balanced, 2 Quality, 4 DLAA, 5 Ultra Performance,
|
||||
> 6 a custom ratio with `NGX_DLSS_SR_OVERRIDE_SCALING_RATIO`), checked against the report's `performanceMode`; DLAA from
|
||||
> its bit. **The report is in NGX's own numbering, not the profile's** — measured on the owner's ledger: Silent Hill 2
|
||||
> (2026-10-13) under the App's *Ultra Performance* (profile 5) was reported as **3**, NGX's Ultra Performance, where the
|
||||
> profile's 3 is "the game's own" (Expedition 33's Quality was 2 in both). When the two disagree, or the report alone
|
||||
> carries a value that does not settle, the session reads as overridden with no mode — never the game's own value,
|
||||
> which the override replaced. Otherwise the mode the game passed to a hooked call (the Streamline byte); otherwise
|
||||
> none. Every surface says it the same way (`Formats.UpscalerOf`): *DLSS (driver-reported) Quality · NVIDIA App*,
|
||||
> *DLSS · NVIDIA App override*, *DLSS Quality*. The live card names what the report settles by itself
|
||||
> (`upscalerQualityOverride`, `07_IPC`). Nothing infers a mode from the render scale (`HANDOFF` §7a). Silent Hill 2's
|
||||
> own session reads no mode: its word lacks `CREATED | EVALUATE`, so no super resolution ran that the driver saw.
|
||||
> *(Corrected 2026-10-20: it lacked them because the word stored had been read after the game closed — §The
|
||||
> driver-reported rung. A session recorded from beta.27 keeps them; one recorded before, on a title no hook names, never
|
||||
> reads the override's mode.)*
|
||||
|
||||
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
|
||||
@@ -529,6 +664,41 @@ From the upscaler hooks we get, per frame:
|
||||
> `eOff` and anything past `eCount` never reach a row). The ffx-api dispatch carries no quality and XeSS has no hook,
|
||||
> so there is nothing of theirs to name. A value the table does not know is shown as stored. It names the MEASURED
|
||||
> byte only — a label derived from the render/output ratio is `HANDOFF` §7a's owner decision, still not taken.
|
||||
> *(Corrected 2026-10-19, beta.25: the ffx-api dispatch still carries no quality, and FSR's mode now comes from the
|
||||
> vendor's own query — the next note. XeSS still has no hook.)*
|
||||
|
||||
> **A second producer since beta.25 (2026-10-19, owner decision D65): FSR's mode, from the vendor's own query.**
|
||||
> `FfxApiUpscaleQualityMode` is an input to `ffxQuery`, which a title calls before it sizes its targets — "what
|
||||
> render size (`…GETRENDERRESOLUTIONFROMQUALITYMODE`) or ratio (`…GETUPSCALERATIOFROMQUALITYMODE`) does this mode
|
||||
> give at this display size?" — never to the per-frame dispatch, which carries the size alone. The Overlay hooks
|
||||
> `ffxQuery` on the four modules it hooks `ffxDispatch` on (`17_HOOK_ENGINE` §Hook inventory), keeps each answer the
|
||||
> vendor returned (one slot per mode), and an UPSCALE dispatch whose `renderSize` (and `upscaleSize`, where the title
|
||||
> states it) fits exactly ONE kept answer — a size answer exactly, a ratio answer within one pixel of
|
||||
> `display / ratio`, the vendor truncating and an engine perhaps rounding — publishes `0x10 + mode`: 16 Native AA ·
|
||||
> 17 Quality · 18 Balanced · 19 Performance · 20 Ultra Performance (offset so FSR's Native AA, 0, can never be read
|
||||
> as Streamline's `eOff`). No fit, two fits, or no query seen → `0xFF`. **A session, its segments and the live card
|
||||
> read one rule (`Domain.Metrics.QualityByte`)**: the most common told byte, and for FSR none when any FSR record
|
||||
> was rendered at a size no FSR-named record has. A dynamic resolution still matches an answer at the top of its
|
||||
> range, so the plain modal would name a mode the session mostly did not render at; `legal/ACCURACY.md` promises
|
||||
> none ("FSR at a dynamic resolution among them — no mode is shown"). A "not told" record at a named size — a
|
||||
> present that drained a frame-generation PREPARE alone, a frame before the title asked — is not that evidence. A
|
||||
> title that sizes its targets without asking, or asked before the Overlay was loaded, reads none: the honest
|
||||
> answer, not a gap. `Domain.Metrics.UpscalerNames` decodes the byte for the `fsr`, `fsr3` and `fsr4` tokens.
|
||||
> Measured on the hook harness with the vendor stub answering as the SDK documents (`fl_guard` "FSR's quality
|
||||
> mode", by size through the SDK 2.x loader and by ratio through the 1.1.x monolith); a real title is owner-only
|
||||
> item 21 (Lies of P at Quality, then Performance).
|
||||
- **One technology's name, quality and size** *(2026-11-12, owner decision D120)*. A session's — and a segment's —
|
||||
upscaler is **the technology named on the most samples of the dominant stream** (a tie goes to the lower value, as
|
||||
the quality byte's does), not the first one any record names. While a session names one technology, its quality
|
||||
and render size are read from the whole stream as before: under frame generation the name sits on one present in
|
||||
N. When it names **more than one**, the quality and the size are read **only from the samples that name the
|
||||
chosen one**, a quality byte of the other family is withheld (`UpscalerChoice.QualityFor`), and the session is
|
||||
marked "settings changed during session". The session this was found on (Dying Light: The Beast, 81 seconds:
|
||||
DLSS evaluated for most of it, an FSR dispatch for a few seconds) had been stored as "DLSS" with FSR's Balanced
|
||||
byte and FSR's render size — three true readings of two technologies under one name. What the chosen technology
|
||||
did not say stays N/A (rule 7). `Domain.Metrics.UpscalerChoice`; the live card still names the first technology
|
||||
the session saw (`FgLadder.UpscalerIdentity`), which for a session in progress is a different question and was
|
||||
not changed.
|
||||
- Resolution changes mid-session (user changed settings, or dynamic resolution scaling) produce **segments**: the session stores a segment list `(startFrame, renderW/H, outputW/H, upscaler, quality)`. Aggregates report the dominant segment plus a "settings changed during session" flag — averaging across a settings change is the classic way benchmark numbers become meaningless.
|
||||
|
||||
> **Two segmentation axes exist, they compose in ONE order, and neither document said so until
|
||||
@@ -571,7 +741,9 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`.
|
||||
>
|
||||
> **What it may claim: the vendor and the feature, attributed to the driver.** What it may NOT claim,
|
||||
> each one measured: a quality (`performanceMode` / `renderPreset` are populated only under an
|
||||
> NVIDIA-app override and are then the OVERRIDE's values), a ratio or render size (`scalingRatio` is
|
||||
> NVIDIA-app override and are then the OVERRIDE's values — *which is why, since 2026-10-19 (D63), the
|
||||
> override's mode IS the session's mode where the report says it applied: §Upscaling's amendment above*),
|
||||
> a ratio or render size (`scalingRatio` is
|
||||
> 0 even under the override), a frame-generation multiplier (`FG_MODE` / `FG_MULTI_FRAME` stay clear
|
||||
> and `frameGenerationCount` is 0 at ×4 — it is the override target). **Corrected the same day, on the
|
||||
> loop's own readings:** the FG word DOES follow DLSS-G once the feature exists — `CREATED | EVALUATE`
|
||||
@@ -596,6 +768,22 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`.
|
||||
> same word through `SessionProgress.upscalerDriverReported` (`07_IPC`). Segments carry no driver word: the driver's
|
||||
> bookkeeping is per process, not per settings change. **Nothing native changed and no NGX hook was added**: the
|
||||
> licence bar in `20_OPEN_QUESTIONS` stands.
|
||||
>
|
||||
> **Corrected 2026-10-20 (beta.27): every stored word had lost the rung.** The loop asked the driver once more after its
|
||||
> last drain — on a session that ended because the game closed, after the game had gone — and that answer, the last,
|
||||
> was the state (`NgxDriverState`: "the last ANSWERED reading is the state"). The driver still answers for the pid,
|
||||
> with `CREATED | EVALUATE` cleared: Expedition 33 read `0x8067F` while it ran (2026-09-06) and its stored sessions
|
||||
> `0x8007F`, the same word without the two bits. Of the 14 sessions in the owner's ledger copy in which the driver
|
||||
> answered, none kept them — so no stored session reads *DLSS (driver-reported)*, and none on an NGX-direct title under
|
||||
> an NVIDIA App override reads its mode (D63). Since beta.27 the driver is not asked once the game has gone, and the
|
||||
> two bits stand once a reading carried them: a game releasing its features on its way out no longer unsays them, and
|
||||
> every other bit is still the last reading's. Sessions recorded before keep what they stored (`spike-notes` §23).
|
||||
|
||||
**The render scale over time (beta.14, D49).** The session summary draws `100 × √(render pixels / output pixels)` — the
|
||||
per-axis scale, `100 / upscale_ratio` — as steps over the session: from the `render_res` blob where the resolution
|
||||
varied (the finalizer stores it only then), a flat line at the row's extent where it did not, and a sentence where the
|
||||
upscaler's parameters were never measured (`App.Charts.RenderScaleSeries`). The Trend and Compare read the row's
|
||||
`upscale_ratio`, the dominant extent.
|
||||
|
||||
## RT / PT / RR — evidence-based tri-state
|
||||
|
||||
@@ -681,15 +869,147 @@ Derived extras (Tier 1): `rays_per_pixel` (mean dispatch volume ÷ output pixels
|
||||
> 2026-08-20 `maxTraceRecursionDepth` has no producer: `CreateStateObject` is a separate PR,
|
||||
> and `pt_confidence` reads it, which is one of the reasons Path Tracing is still `N/A`.
|
||||
|
||||
## Per-process VRAM (Tier 1)
|
||||
## Display mode — both tiers (beta.10)
|
||||
|
||||
`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).
|
||||
**Owner request, 2026-09-27:** "detect the game's window size and whether it runs full-screen, borderless or windowed,
|
||||
and how much of the time". Schema 0016 (`06_DATA_MODEL`), shared-memory region 4 (`07_IPC`, layout 4), the Agent's
|
||||
`Application.Capture.DisplaySampler`, Domain's `Display.DisplayModeClassifier` and `Display.DisplayTally`.
|
||||
|
||||
**Two witnesses, and neither reads the game.**
|
||||
|
||||
1. *The swap chain's own answer* — Tier 1, DXGI only. The Overlay asks `IDXGISwapChain::GetFullscreenState` and `GetDesc`
|
||||
on the chain the game passed to `Present`, at most twice a second per chain, and publishes the chain with the largest
|
||||
back buffer in region 4: its window, back buffer, swap effect, and whether it is exclusive (`17_HOOK_ENGINE` §Hook
|
||||
inventory — polled, not a `SetFullscreenState` hook). OpenGL publishes its window and client area with no exclusive
|
||||
answer; the Vulkan layer publishes nothing yet.
|
||||
2. *The window from outside* — both tiers. The Agent asks user32 about the game's top-level window: minimised or not, the
|
||||
client area in screen coordinates, the monitor it is on and that monitor's refresh rate — per-monitor DPI aware while it
|
||||
asks, because the Agent runs DPI-unaware and Windows would otherwise scale another process's coordinates
|
||||
(`Infrastructure.Display.WindowGeometryProbe`). The window is the one region 4 names when it still belongs to the game
|
||||
(a handle is reused once its window is gone), else the largest visible, uncloaked, non-tool top-level window of any
|
||||
process running the game's executable — found by image path in the watcher's snapshot for a Tier-2 session that never
|
||||
opened the process. This is the focus sample's class of question: CLAUDE.md rule 4 is about game memory, and no handle
|
||||
to the game's process is opened for it.
|
||||
|
||||
**The ladder, per sample** (`DisplayModeClassifier`):
|
||||
|
||||
| Mode | When | Column (ms) |
|
||||
|---|---|---|
|
||||
| No window | no window could be read and the chain did not say exclusive | `display_nowindow_ms` — outside every share |
|
||||
| Minimized | the window is minimised | `display_minimized_ms` |
|
||||
| Exclusive fullscreen | a region-4 sample under 2 s old in which the swap chain SAID exclusive | `display_exclusive_ms` |
|
||||
| Borderless | the client area covers its monitor (±1 px each edge) and the chain said not exclusive | `display_borderless_ms` |
|
||||
| Fullscreen or borderless | the client area covers its monitor and nothing could say which — OpenGL, Vulkan, every Tier-2 session | `display_covers_ms` |
|
||||
| Windowed | anything else | `display_windowed_ms` |
|
||||
|
||||
**Time, not ticks.** A sample stands for the wall time until the next: every drain tick (100 ms) hooked, every hold tick
|
||||
(1 s) at Tier 2 — so the two add up in one unit, milliseconds. An interval that ends on a paused tick is dropped, which
|
||||
excludes a pause to within one tick at each edge, as the frame series' gap does. A mode's **share** is its milliseconds
|
||||
over the observed time (every mode but *No window*). `display_changes` counts samples whose mode differs from the one
|
||||
before, no-window samples skipped. The sizes — `display_window_*` (client area), `display_buffer_*` (back buffer),
|
||||
`display_monitor_*` and `display_monitor_hz` — are the ones seen in the mode that lasted longest *(corrected 2026-10-20,
|
||||
beta.27: the last ones a sample of that mode SAW — a game leaving exclusive fullscreen closes its window while its swap
|
||||
chain's last word is under 2 s old, and those last samples, exclusive with no window, had replaced every size: two Lies
|
||||
of P and three Dark Souls III sessions stored none. A mode no sample of which saw its window keeps the back buffer
|
||||
alone)*; `display_source` is the
|
||||
strongest witness any sample had (`swapchain` > `opengl` > `window`). `sessions.swap_effect`, a column since 0001 with no
|
||||
writer, is written from region 4.
|
||||
|
||||
**What it cannot say** (the user-facing list is `LIMITATIONS.md`):
|
||||
|
||||
- *Exclusive* is what the game asked DXGI for. Windows may still present such a game through the compositor ("fullscreen
|
||||
optimizations"), and a flip-model borderless window may be promoted to independent flip; neither is visible without a
|
||||
trace session, which FrameLedger does not have (`20_OPEN_QUESTIONS` §G).
|
||||
- A game's menu may call a borderless window "Fullscreen"; the swap chain's answer is what is reported.
|
||||
- A minimised game issues only occlusion probes, which the hook drops before sampling: a region-4 sample older than 2 s
|
||||
keeps its window and loses its exclusive bits.
|
||||
- Tier 2, OpenGL and Vulkan can never tell exclusive from borderless. Their covering time is *Fullscreen or borderless*,
|
||||
and the trend draws no exclusive or borderless point for a session with any of it.
|
||||
- A session recovered from its `.partial` file has no display facts — the tally is not in the crash file — and reads
|
||||
N/A. The focus pair, which the partial carries, is the precedent this does not follow.
|
||||
|
||||
**A side effect of region 4's poll (layout 4).** `GetDesc` every 500 ms also refreshes the chain's output size, which
|
||||
catches a `ResizeBuffers1` the hook inventory does not have: a title that resizes through it now splits its segments at the
|
||||
change and reads "settings changed mid-session" (FR-6.4), which is what it was.
|
||||
|
||||
**Where it is shown** (`08_UI`): the session summary's Display card and line, the game page's last measured session and
|
||||
its Sessions column, three Trend metrics — *Exclusive fullscreen share %*, *Borderless share %*, *Windowed share %*, every
|
||||
tier, and a mode switch is not a mid-session change for them (switching resizes the swap chain; the share is what that
|
||||
switch was) — three Compare rows, never ranked, and the CSV's `# display:` line (§Export schema) and the JSON's aggregates.
|
||||
|
||||
## Game process memory — both tiers (beta.12, owner decision D43)
|
||||
|
||||
**What is measured since 2026-10-03:** the game process's own memory, read from OUTSIDE the game once a second by the
|
||||
Agent through `FrameLedger.ProcessStats.dll` (`18_GPU_VENDOR_APIS` §The game process's memory) — never from the game's
|
||||
memory (CLAUDE.md rule 4):
|
||||
|
||||
| Figure | Source | What it is |
|
||||
|---|---|---|
|
||||
| **Dedicated GPU memory** (`game_vram_dedicated`) | PDH `\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated Usage`, every instance naming the pid summed | the number Task Manager's Details tab shows under that name |
|
||||
| Shared GPU memory (`game_vram_shared`) | the same counter set's `Shared Usage` | system memory the GPU uses on the game's behalf |
|
||||
| **Memory — private working set** (`game_ram_private`) | `GetProcessMemoryInfo`, `PROCESS_MEMORY_COUNTERS_EX2.PrivateWorkingSetSize` | Task Manager's "Memory" column; N/A on a Windows that predates EX2 (Windows 10 22H2 / 11 22H2 without the September 2023 update) |
|
||||
| Working set (`game_ram_ws`) | `WorkingSetSize` | the whole working set, shared pages included; what the card falls back to where the private working set is N/A |
|
||||
| Commit (`game_commit`) | `PrivateUsage` | private memory committed, resident or not |
|
||||
|
||||
**Which process.** A hooked session — and any session refused after the loop pinned the process — reads the pinned pid
|
||||
through the handle the session already holds (`SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION`). An unpinned Tier-2 hold
|
||||
(hooking off, blocked, unresolved, cannot pin) reads **every process running the game's executable** in the watcher's
|
||||
snapshot, each opened for the read with `PROCESS_QUERY_LIMITED_INFORMATION` and closed after it, and SUMS them; a process
|
||||
whose creation time is not the snapshot's (a reused pid), or that refuses even that right, is left out of both halves.
|
||||
`game_memory_processes` says how many were summed. Child processes of another executable (a launcher, a crash handler, a
|
||||
web view) are not counted.
|
||||
|
||||
**Dedicated is not the DXGI budget model's "local usage".** dwm.exe read 858 MB dedicated against 310 MB local at an idle
|
||||
desktop, and a test process holding a buffer read 4.5 MiB more dedicated than its own `QueryVideoMemoryInfo(LOCAL)` at
|
||||
both 8 MiB and 512 MiB (`spike-notes` §16, M3) — a constant per-device amount, not one that grows with the game's
|
||||
allocations. So dedicated is defined as Task Manager's column and is **never compared with a budget**: the budget and
|
||||
`budget_exceeded_pct` stay unmeasured (`20_OPEN_QUESTIONS` §M11), and `vram_proc_*` / `vram_budget_exceeded_pct` /
|
||||
`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,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
|
||||
> called `QueryVideoMemoryInfo` — `dllmain.cpp` lists `FL_MEASURED_VRAM` as unproduced, §H10 never settled where in the
|
||||
> game to call it — and D43 chose the outside read instead).
|
||||
|
||||
~~`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).~~
|
||||
|
||||
## Sensor aggregates
|
||||
|
||||
Per session over 1 Hz samples: `avg` (mean of non-null), `max`. 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.
|
||||
Per session over 1 Hz samples: `avg` (mean of non-null), `max` — and since beta.12 the `median` (the linear-interpolation
|
||||
50th percentile: the middle sample of an odd count, the mean of the two middle ones of an even count) and the `min`
|
||||
(`Domain.Metrics.SeriesAggregates`). Every stored series' n / mean / median / min / max is written once at finalize to
|
||||
`sessions.sensor_stats_json`, so the summary's statistics read stored values and outlive a retention sweep of the raw
|
||||
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)
|
||||
**The card's clocks and limits (beta.14, D49), both tiers.** The core and memory clock (MHz), the fan (RPM) and the
|
||||
memory temperature were in the samples before (L2 reads them, L3 too) and stored nowhere; they are series now
|
||||
(`gpu_core_clock`, `gpu_mem_clock`, `gpu_fan`, `gpu_mem_temp`) with `avg_gpu_core_clock_mhz`, `avg_gpu_mem_clock_mhz`,
|
||||
`avg_gpu_fan_rpm` and `max_gpu_mem_temp`. **What held the card back** is NVAPI's perf-decrease reasons
|
||||
(`GpuSample.ThrottleReasons`, L3 only): `gpu_power_limit` / `gpu_thermal_limit` read 100 on a tick whose reasons include
|
||||
the power limit (`0x2`) / thermal slowdown (`0x1`) and 0 on one whose reasons do not, so their mean — `power_limit_pct`,
|
||||
`thermal_limit_pct` — is the share of ticks held back. A card no layer reports reasons for (every card but NVIDIA's) has
|
||||
no answer: N/A, never "not limited". `throttle_pct` (any reason) is unchanged.
|
||||
|
||||
## Efficiency (beta.14, D49)
|
||||
|
||||
`app_frames_per_joule` = the application frame rate ÷ the card's average board power — FPS per watt, frames per joule.
|
||||
**Never the displayed rate** (rule 6): a generated frame costs the card a fraction of a rendered one, and counting it would
|
||||
sell frame generation as efficiency. The application rate is known when frame generation was counted over the session
|
||||
(Native FPS; a counted `none` makes it the presented rate), or when no frame-generation runtime was loaded
|
||||
(`presented_qualifier = no_fg_runtime`). **Null** for `census_not_run`, `fg_runtime_loaded` and `none_withheld`, for a
|
||||
session whose generation changed state (its steady state covers a share of the session, and the power is the whole
|
||||
session's), without a power reading, and at Tier 2 (no frames). The power is the **graphics card's** — not the
|
||||
processor's, not the whole PC's — averaged over the session's sensor ticks. `Domain.Metrics.EnergyEfficiency`,
|
||||
`SessionAggregator.ApplyEfficiency`.
|
||||
|
||||
## 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 |
|
||||
|---|---|---|
|
||||
@@ -698,9 +1018,14 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline
|
||||
| Upscaler + render resolution | **exact** (vendor API arguments) | not available |
|
||||
| RT active | measured per frame | not available |
|
||||
| Path tracing | heuristic, confidence-scored, never asserted | not available |
|
||||
| Per-process VRAM | exact | not available |
|
||||
| ~~Per-process VRAM~~ Game process memory (beta.12) | ~~exact~~ dedicated / shared GPU memory as Task Manager counts it — a known 512 MiB allocation read +512.0 MiB (`spike-notes` §16); private working set equal to Windows' own counter; read from outside the game | ~~not available~~ the same, from outside; an unpinned hold sums the executable's processes |
|
||||
| PC latency | as reported by Reflex | not available |
|
||||
| Display mode (beta.10) | per 100 ms sample: exclusive fullscreen as the swap chain answers it (DXGI; OpenGL and Vulkan cannot say), borderless, windowed, minimised; the window's size from user32 | per 1 s sample, from the window alone: windowed, minimised, or *fullscreen or borderless* — never split |
|
||||
| GPU temp / load / power | vendor API accuracy, ±1 s sampling | same |
|
||||
| GPU clocks / fan / memory temperature (beta.14) | vendor API accuracy, ±1 s sampling | same |
|
||||
| GPU power / thermal limit (beta.14) | NVAPI's perf-decrease reasons once a second — a limit that came and went between two ticks is not seen; NVIDIA only, N/A on every other card | same |
|
||||
| Time below 30 / 60 / refresh (beta.14) | from the frame times above, with the margins of §Pacing — a rate less than 2 % under the threshold reads partly as at it | **not available** |
|
||||
| Efficiency (beta.14) | the application rate's accuracy over the board-power sensor's; N/A wherever the application rate is not known | **not available** |
|
||||
| CPU temperature | sensor-inherent ±1–2 °C, needs LHM + PawnIO + elevation. **Read since 2026-09-21** (`Telemetry.LhmCpuTemperatureReader`: the package sensor, else the hottest core) and **unmeasured on real hardware** — no elevated run with PawnIO has been taken (`20_OPEN_QUESTIONS` §CPU) | same |
|
||||
| CPU load | **time busy over elapsed, every logical processor** (`GetSystemTimes`, 1 Hz, unprivileged; since 2026-09-21). Not Task Manager's "utility", which is frequency-scaled and exceeds 100 under turbo — the two are different numbers and this one is stated as what it is. Null on a session's first tick (no interval yet), never 0 | same |
|
||||
| System memory in use | physical memory in use machine-wide, MiB (`GlobalMemoryStatusEx`, 1 Hz, unprivileged; since 2026-09-21). The machine's, not the game's | same |
|
||||
@@ -723,13 +1048,13 @@ 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` |
|
||||
| `dispatch_rays` | `dispatch_rays` blob (`uint32[]`, the volume) | `N/A` |
|
||||
| `pso_created` | `pso_created` blob (`uint16[]`, the **count**, not a flag) | `N/A` |
|
||||
| `vram_mb` | `vram_proc` per-frame blob. Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so | `N/A` |
|
||||
| `vram_mb` | `vram_proc` per-frame blob. ~~Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so~~ **Corrected 2026-10-03: the Overlay never produced it, so the column has always been empty.** It stays in the list — the schema is fixed — and the header's note says so; the game's memory is the `# game_memory:` header line (beta.12, §Game process memory) | `N/A` |
|
||||
| `reflex_latency_us` | `latency_us` blob; **finalize must write it** | `N/A` |
|
||||
|
||||
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, hardware snapshot, segment list, the tri-state flags with their sources, and the note that `vram_mb` is 1 Hz-sampled. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
|
||||
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, swap effect, **the display line** (beta.10: `# display:` with each mode's milliseconds, the changes, the source and the window / back buffer / monitor sizes, or `N/A` for a session recorded before — §Display mode; a mode is the session's, not a frame's, so it is not a column), hardware snapshot, segment list, the tri-state flags with their sources, ~~and the note that `vram_mb` is 1 Hz-sampled~~ **the game's memory** (beta.12: `# game_memory:` with the dedicated GPU memory's mean / median / max, the shared max, the private working set's mean / median / max, the working set's and the commit's max — MiB, invariant — the process count and the sources, or `N/A` for a session recorded before or one where nothing answered; the session's figure, read once a second, so a header line like the display's), and the note that `vram_mb` is the in-game figure this build does not produce. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
|
||||
+74
-15
@@ -22,9 +22,13 @@ 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();
|
||||
> FlAdvancedState? AdvancedState { get; } void SetAdvancedRequested(bool requested); // region 5, train B (2026-11-12): the
|
||||
> // word is written either way as the ring is attached, before the first guard result; the region is read only by
|
||||
> // a session whose observer WantsInGameAdvanced, and carried on CaptureProgress.InGameAdvanced
|
||||
> }
|
||||
> public sealed class CaptureSession(...) // the loop: gate → inject → attach → drain, until something ends it
|
||||
> {
|
||||
@@ -38,7 +42,9 @@ public interface IFrameSource : IAsyncDisposable
|
||||
> with `FlGuardBuildId`), `ITargetLivenessSource` (`HeldProcessLivenessSource`, §S29(e)),
|
||||
> `ITargetResolver` (`TargetResolver`, path only — never a pid), `IProcessLauncher`
|
||||
> (`ProcessLauncher`, launch mode), `IRuntimeModuleSnapshot`, `INgxDriverProbe`,
|
||||
> `IExecutableMarkerScan`. `ShmRingReader` itself gains no interface and no second consumer
|
||||
> ~~`IExecutableMarkerScan`~~ — **corrected 2026-09-27:** the marker scan is the recorder's, not the loop's; the loop's
|
||||
> later ports are `IKillSwitch` (FR-2.4), `ICapturePauseSource`, `IUserModeExceptionSwitch` and
|
||||
> `IOverlayToleranceChannel` (D33) and `IDisplayProbe` (beta.10). `ShmRingReader` itself gains no interface and no second consumer
|
||||
> (`NoSecondRingReaderTests`). A **pure move**: the loop's ordering rules, its tests and the
|
||||
> capture host's report are byte-for-byte what they were; the host is now a thin shell that
|
||||
> composes the same objects. What the table below used to call `HookedFrameSource` is this.
|
||||
@@ -84,7 +90,11 @@ it still holds.
|
||||
> watcher's own 1 Hz snapshot** (`ITargetResolver.IsRunning` over `LatestProcessSnapshot`, 2026-09-23; a process
|
||||
> whose path could not be read still counts by its name; the console verbs, where nothing polls, keep the name
|
||||
> list) when it never opened the process — by name, another game's `Game.exe` held an RPG Maker game's session
|
||||
> open. Nothing about the hold touches the target, and no process is opened for it. **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
|
||||
> open. Nothing about the hold touches the target, and no process is opened for it. *(Corrected 2026-10-03, beta.12, D43:
|
||||
the hold now reads the game's own memory, once a second, by opening each process running the executable with
|
||||
`PROCESS_QUERY_LIMITED_INFORMATION` for the read and closing it after — the right the watcher's own snapshot already uses
|
||||
on every process each second; nothing is held, nothing is injected, and the memory's contents are never read. Its video
|
||||
memory comes from performance counters that need no handle at all; `03_METRICS` §Game process memory.)* **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
|
||||
> first, and a row whose hooking is off — merely added, blocked by a finding, auto-disabled — goes straight to
|
||||
> the hold with `RefusedHookNotEnabled` (its verdict is the row's block when it has one, `PreviouslyBlocked`).
|
||||
> The resolver used to run first, and a hooking-off utility that runs elevated (Borderless Gaming, imported from
|
||||
@@ -125,7 +135,8 @@ 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.**
|
||||
- **One spelling of the exe path for the whole capture path (beta.33).** The watcher keys a game on the kernel's image name (`QueryFullProcessImageName`), and `TargetResolver`, which re-finds the game just before the guard, read the loader's (`Process.MainModule`) until beta.33: for a game started through a junction — a package Windows activates from `C:\Program Files\WindowsApps\<package>`, a junction to the game's own folder — the two could differ, and the session would end `TargetNotRunning` about a game the watcher had just matched. Both read `Infrastructure.Io.ProcessImagePath` now; the resolver still opens a candidate with the guard's own rights (`PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_VM_READ`), so a process an anti-cheat driver closes stays `TargetUnreadable` (D21). `spike-notes` §25 measured the two spellings equal on the owner's eleven Xbox titles; one reader keeps them equal by construction (`TargetResolverTests`).
|
||||
- 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`
|
||||
@@ -147,7 +158,18 @@ which makes the notification more important than it was, not less.
|
||||
> row's path with its drive letter changed (an RPG Maker `Game.exe` has the same bytes in every game); and the
|
||||
> running-session table is keyed by the executable's path, so a re-imported or merged entry's new id cannot start a
|
||||
> second session for the same executable. The launch election registers its session there too, and skips a child the
|
||||
> watcher already records. **Behaviour change:** a game whose folder moved (not its drive letter) records nothing until
|
||||
> watcher already records. *(beta.15, 2026-10-06:)* a process turned away by that rule — "one at a time" — was never
|
||||
> recorded, because the watcher reports a pid once: **a game started again while its last session was still finalizing**
|
||||
> (the driver profile, a crash reporter waited for, the transaction — seconds) got no session at all. The orchestrator
|
||||
> now remembers the newest such process per executable and starts its session when the running one ends, if that one
|
||||
> ended on its own (not cancelled with the host), the process is the same (pid and start time) and it is then the
|
||||
> executable's ONLY process — a helper of a game still running has the game beside it and stays turned away, as before
|
||||
> (`CaptureOrchestratorTests`: the restart recorded, the helper not, a process that left meanwhile not). *(beta.27,
|
||||
> 2026-10-20:)* a launch never said it had ended on its own, so after **Play** ▸ *Start directly* nothing turned away
|
||||
> while it ran was ever recorded — Lies of P hands itself to Steam within seconds, and twice on 2026-10-19 the game
|
||||
> Steam started went unrecorded (`spike-notes` §23). A launch now says so, with the processes it and its election
|
||||
> recorded: the one it started appears to the watcher after the launch began and is turned away like any other, and a
|
||||
> launch the user stopped does not start again on it. **Behaviour change:** a game whose folder moved (not its drive letter) records nothing until
|
||||
> *Change executable* points its entry at the new file. `ProcessTree` reads ppid chains with the one rule that defeats pid
|
||||
> reuse: a child that started before its parent is not its child. `DescendantElection` picks the newest-started
|
||||
> descendant whose image is tracked — a launcher's consent does not extend to what it spawns, so the elected image
|
||||
@@ -173,7 +195,14 @@ 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`. Since beta.21 one does: **Play** set to *Start directly* — D59, `08_UI` §Games)*: `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
|
||||
|
||||
> **An elevated Agent starts the game as a standard user (beta.10, the admin mode, D34).** `ProcessLauncher` checks its
|
||||
> own token: elevated, it starts the game with the desktop shell's token (`Infrastructure.Startup.UnelevatedProcess` —
|
||||
> `GetShellWindow`'s process, its token duplicated, `CreateProcessWithTokenW`, the same explicit environment the kill
|
||||
> switch decides), pins it from the start's own handle, and never falls back to its own token: with no shell the launch
|
||||
> fails with `Launch_Error_1400`. `LaunchGame` is a pipe command any process of the user can send; an elevated launch would
|
||||
> be an elevation without a prompt.
|
||||
|
||||
> **Built 2026-09-06 (P1 item 2) as "inject late", which is the only shape §S1 left possible, and the
|
||||
> sentence above is kept as the intent it does not quite describe.** A `CREATE_SUSPENDED` target has
|
||||
@@ -194,6 +223,11 @@ which makes the notification more important than it was, not less.
|
||||
> that spawns the real game and quits lands on the first, and re-electing the descendant is the Agent's
|
||||
> (P2, §Process watcher) — **built 2026-09-10 (PR-F)**: the Agent's `--console launch` hands either
|
||||
> answer to `DescendantElection` and runs an attach-mode session against the newest tracked descendant.
|
||||
> *(Corrected 2026-10-06, beta.15: **it never ran until beta.15.** The refused outcome carried no `TargetPid`, and
|
||||
> `CaptureOrchestrator.ElectAfterLaunchAsync` returned at `TargetPid == 0` — before its own `election:` log line — on every
|
||||
> launch since #150; the orchestrator's tests built the outcome by hand, pid included, so nothing saw it. The refused
|
||||
> outcome carries the launcher's pid and exit code now (`CaptureSessionLaunchTests` pins it), and an outcome without
|
||||
> one is logged rather than silent. A real launcher run is still owed: HANDOFF, owner-only.)*
|
||||
> **The host never terminates what it launched**: any refusal after the start
|
||||
> leaves the title running unhooked, which is Tier 2.
|
||||
>
|
||||
@@ -212,13 +246,15 @@ 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).
|
||||
> **A game the Xbox app or the Microsoft Store installed is always attach mode (beta.33, D80).** Windows starts it through its package — **Play** runs `explorer.exe shell:AppsFolder\<AUMID>` in either mode — and started by its path it is never the game in its package (`spike-notes` §25: `CreateProcess` of the launch executable makes Windows activate the package itself, so the game is not the launcher's descendant; of an Unreal shipping executable, the game runs outside its package). So `LaunchGame` for an executable whose install root is a GDK package root answers `PackagedGame` and starts nothing (`OrchestratorOptions.IsPackaged` = `GdkPackageFiles.IsInPackage`), the watcher records the game when it appears, and the session is `late_attach`: §25 measured an Unreal title's D3D device 2.4–3.7 s after its process, a Unity title's 0.1–1.2 s, so what ran before the hook is in `dxgiPresentsBeforeHook`. The Vulkan layer's switch (`FRAMELEDGER_ENABLE_VK_LAYER=1`) is set only by `ProcessLauncher`, so a Vulkan GDK title cannot get it (`20_OPEN_QUESTIONS` §G).
|
||||
|
||||
~~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.
|
||||
@@ -291,6 +327,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
|
||||
> **The PAIR, because zero is not a finding.** A process owning no top-level window at all — `hook-harness` presents to a composition swapchain and has none — is unfocused on every tick of every run. Reporting that as focus loss would fire on every integration run and teach the reader to ignore the line, which is the could-not-look/looked-and-found-nothing collision `FlRtTier` and `upscalerQuality` already exist to avoid.
|
||||
>
|
||||
> **It is attribution, never the guard.** What refuses a mixed window is `FgWindow.BatchRefusal`, computed from the records alone, so a caller that never wires focus still cannot publish an averaged ratio. Focus is what lets the report name the cause.
|
||||
- **Each drain tick also samples the display mode (beta.10)** — `Application.Capture.DisplaySampler` on the same tick as focus: shared-memory region 4 (the presenting chain's window, back buffer, swap effect and exclusive state, as the Overlay last asked them) and the window's geometry from outside (`IDisplayProbe`, `Infrastructure.Display.WindowGeometryProbe`), classified and added up by the time each sample stood for; a paused tick drops the interval it ends. The last sample is closed before the last drain, and the tally rides out on `CaptureOutcome.Display`. **The Tier-2 hold samples too**, once per hold tick (1 s): the window only — by the pinned pid when the loop holds one, else by every process running the executable in the watcher's snapshot (`ITargetResolver.PidsOf`, image path only — never a name), still opening nothing. The recorder writes the tally on the row's skeleton, so both tiers store it (`03_METRICS` §Display mode, `06_DATA_MODEL` 0016).
|
||||
- **Dropped records are computed here, not read from the header.** The Overlay has no reader index and cannot know whether a slot it overwrites was consumed. The Agent owns the read index, so it owns the accounting: when `writeIndex - readIndex > capacity`, add the excess to the session's data-quality counter and resume at `writeIndex - capacity`. A non-zero value means the Agent stalled for over ~16 s — log it, surface it as a session warning, never silently accept it.
|
||||
|
||||
> **That sentence is true only because the read index is seeded from the writer at
|
||||
@@ -302,7 +339,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
|
||||
|
||||
@@ -311,7 +348,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
|
||||
|
||||
| Thread | Cadence | Owns | Touches |
|
||||
|---|---|---|---|
|
||||
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground per tick, drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
|
||||
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground and the display mode per tick (beta.10), drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
|
||||
| **Telemetry** (`fl-telemetry`, `TelemetryPoller`, one per session) | 1 Hz, never faster than 500 ms | Its own `ConcurrentQueue` of `TelemetrySample` | Reads the composite source only; L2 has a thread of its own inside the library, and the composite is read from this thread and no other |
|
||||
| **Watcher** (built 2026-09-10, PR-F: `CaptureOrchestrator.RunAsync` on a `PeriodicTimer(1 s)`) | 1 Hz process snapshot | The watcher's events and the running-session table — ~~`PollOnceAsync` is their only writer; there is no `Channel`, because there is no second consumer~~ **since 2026-09-13 (P3 PR-1b) the table has one lock**: `PollOnceAsync` on the timer, `LaunchAsync` and `StopSession` from the pipe's tasks (HANDOFF §P3 D12 as built — two commands do not justify a channel); the sessions themselves never take it | The `games` rows (one read per poll) and never the ring; each session it starts runs on its own task |
|
||||
| **Finalize** (PR-D) | Once, on the session loop's task | The one SQLite connection, behind a `SemaphoreSlim(1)` | `ApplicationStopping` cancels the loop; finalize gets a grace window, then the `.partial` stays for recovery |
|
||||
@@ -335,7 +372,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
|
||||
|
||||
@@ -394,7 +431,8 @@ because a layer cannot leave a running game's loader chain.
|
||||
> - **Recovery never throws.** A file it cannot finalize is set aside as `<guid>.partial.failed` (never retried, kept for
|
||||
> a bug report) and reported `Failed`; the next file is recovered, and the watcher starts either way.
|
||||
> - The Agent's host logs through Serilog since the same day: a background service that stops the host is now in
|
||||
> `agent-*.log`, where before it was in no file at all.
|
||||
> `agent-*.log`, where before it was in no file at all. *(Since beta.37, on .NET 11, that service's exception also
|
||||
> ends the Agent through its crash report instead of an exit 0 — `10_LOGGING` §Crash handling.)*
|
||||
|
||||
> **Built 2026-09-10 (P2 PR-D): `Application.Recording`.** The state machine above is the intent; what
|
||||
> runs is one class per box. `SessionRecorder` owns a session end to end — the row's identity and time
|
||||
@@ -422,8 +460,29 @@ because a layer cannot leave a running game's loader chain.
|
||||
## Crash & exit classification
|
||||
|
||||
- Normal: presenting PID exit code 0 — **and since beta.8 any exit code that is not an exception's** (End task and taskkill leave 1; a program's own error exit; Ctrl+C's `0xC000013A`), kept in `capture_notes` and said as what it is.
|
||||
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
|
||||
- `unhooked_safety`: the guard fired mid-session.
|
||||
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record ~~naming the exe~~ **that is a crash report of this game** within `[start, end + 30 s]`, **or** (beta.14) an engine's crash reporter the game started before it left.
|
||||
|
||||
> **Corrected 2026-10-05 (beta.14, the crash-reporter question): the event-log witness was too broad, and one engine's
|
||||
> crashes had no witness at all.** A record counted when any of its strings *contained* the executable's name: on the
|
||||
> owner's machine a WER 1001 `RADAR_PRE_LEAK_64` — Windows' memory-leak detector — named `witcher3.exe` and a session
|
||||
> that ended with exit code 0 was stored `crashed` (2026-10-04, read from a copy of the ledger and the event log); a hang
|
||||
> report, another program whose name contains this one's, or a crash of a same-image child would have done the same.
|
||||
> `CrashEventMatcher` now takes a 1000 from `Application Error` only when its application name equals the executable's,
|
||||
> its path (when given) is the executable's and its process id is the session's, and a 1001 from `Windows Error
|
||||
> Reporting` only when it is a crash report (`APPCRASH`, `BEX`, `BEX64`, `CLR20r3`, `MoAppCrash`, `MoBEX`) whose first
|
||||
> parameter is the executable's name. And Unreal handles its own crash — it starts `CrashReportClient.exe` and exits
|
||||
> with code 3, no exception code and no event — so it read `normal`. The watcher's once-a-second snapshots now record
|
||||
> every **on-crash** reporter a process starts (`Watch.CrashReporterCatalog`: Unreal's `CrashReportClient.exe`,
|
||||
> REDengine's `CrashReporter.exe`, RE Engine's `CrashReport.exe`, BugSplat's `BsSndRpt(64).exe`) with its parent by pid,
|
||||
> image and start (`CrashReporterWitness` — a pid reused by a later process is not the parent); the recorder asks at the
|
||||
> end, after two more polls when the game just left. It counts (`CrashReporterRule`) when it started at least 10 s after
|
||||
> the game and the game left within 60 s of it: `crashed`, with `crash_reporter=<image>` in the notes. A reporter whose
|
||||
> game kept running is a note (`crash_reporter_seen=`). **Always-on handlers never count** — Unity's
|
||||
> `UnityCrashHandler64.exe` and `crashpad_handler.exe` start with their game. No process is opened for any of this.
|
||||
> Sessions stored before beta.14 keep their status.
|
||||
- `unhooked_safety`: the guard fired mid-session. *(Since beta.14, D48: a re-scan that refused only because it could not
|
||||
read the game's tree, concluded after the game itself had exited, is the game's exit instead — `normal` or `crashed` by
|
||||
its exit code — with `scan_at_exit=<reason>` in `capture_notes`; `19_SAFETY` §During a session.)*
|
||||
- `degraded`: Overlay self-disabled after faults, or ring layout mismatch mid-session.
|
||||
- `interrupted`: Agent died mid-session; recovered from `.partial` on next start.
|
||||
- A **user stop** (FR-3.6; `StopSession` over the pipe, P3 PR-1b) is `normal`: the loop ends as `SessionEndReason.StoppedByUser` at its next tick, drains once more and finalizes; the target keeps running, unhooked from here. It is the session's own stop token, not the host's cancellation — the latter leaves a `.partial`.
|
||||
@@ -458,7 +517,7 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
|
||||
|
||||
## Live progress
|
||||
|
||||
`SessionProgress` at 1 Hz to the UI (`07_IPC`): rolling 5 s Native FPS, Displayed FPS, FG factor, current render→output resolution, upscaler + quality, RT active flag, GPU/CPU temp, per-process VRAM, elapsed. Suppressed when no UI client is connected. This is what makes the Dashboard live card genuinely useful — it is showing *measured* settings, not guesses.
|
||||
`SessionProgress` at 1 Hz to the UI (`07_IPC`): rolling 5 s Native FPS, Displayed FPS, FG factor, current render→output resolution, upscaler + quality, RT active flag, GPU/CPU temp, ~~per-process VRAM~~ the game process's dedicated GPU memory and private working set (beta.12, from the newest telemetry tick — `SessionHeld` carries the same two for a held session), elapsed. Suppressed when no UI client is connected. This is what makes the Dashboard live card genuinely useful — it is showing *measured* settings, not guesses.
|
||||
|
||||
> **Built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D13): `Application.Ipc.SessionProgressCalculator`**, over the last 5 s of the
|
||||
> ring's records through the same calculators the row uses — `FrameTimeSeries` for the presented rate, `FgWindow` + the FG ladder for
|
||||
@@ -481,7 +540,7 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
|
||||
|---|---|
|
||||
| Game process, per present | ≤ 1 µs; no syscall, no allocation, no lock, no logging (`17_HOOK_ENGINE`) |
|
||||
| Game process, resident | ≤ 8 MB (DLL + ring) |
|
||||
| Agent, during capture | ≤ 1% of one core average, ≤ 150 MB working set |
|
||||
| Agent, during capture | ~~≤ 1%~~ ≤ 2.5 % of one core average *(NFR-2 as D117 amended it, 2026-11-11: measured 1.93 %, `20_OPEN_QUESTIONS` §M16)*, ≤ 150 MB working set |
|
||||
| Agent, idle | ~0% (1 Hz process poll only) |
|
||||
| Measured game FPS impact | ≤ 0.5% vs uninstrumented, verified per release (`14_TESTING` §Hook overhead) |
|
||||
|
||||
|
||||
+261
-23
@@ -18,7 +18,7 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
| Graphics API + swapchain format, buffer count, swap effect, flags | `CreateSwapChain*` / present hooks |
|
||||
| Present mode (flip / blt / independent flip) | swapchain desc + `presentFlags` + `syncInterval` |
|
||||
| HDR output | `SetColorSpace1` |
|
||||
| Upscaler identity + quality preset | NGX / Streamline / FFX / XeSS create+evaluate calls — **or, when no hook saw one, the NVIDIA driver's per-process NGX word, out of process and attributed (`03_METRICS` §Upscaling, the driver-reported rung, 2026-09-06): identity only, never the preset** |
|
||||
| Upscaler identity + quality preset | NGX / Streamline / FFX / XeSS create+evaluate calls — **or, when no hook saw one, the NVIDIA driver's per-process NGX word, out of process and attributed (`03_METRICS` §Upscaling, the driver-reported rung, 2026-09-06): identity only, never the game's preset** — since beta.24 (D63) an NVIDIA App override's mode, where that report says the override applied, is the session's quality mode, marked as the App's (`QualityResolver`) — and since beta.25 (D65) FSR's mode where the title asked FidelityFX's `ffxQuery` for the size it then dispatched, none at a dynamic resolution (`03_METRICS` §Upscaling) |
|
||||
| Render resolution vs output resolution (incl. mid-session changes) | upscaler parameter reads + `ResizeBuffers` |
|
||||
| Frame Generation mode + factor | NGX/SL/FFX FG feature evaluation, then cadence — **Tier 1 only**. ~~then (Tier 2 only) PresentMon `FrameType`~~ retired (§S31 row P2), and Tier 2 no longer produces frames to run cadence over either |
|
||||
| Ray Tracing active | AS builds + `DispatchRays` (both, to catch inline RayQuery) |
|
||||
@@ -26,11 +26,20 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
| Reflex on + PC latency | NVAPI Reflex hooks |
|
||||
| Per-process VRAM | `QueryVideoMemoryInfo` |
|
||||
| PSO compilation events | pipeline-creation hooks |
|
||||
| Display mode — exclusive fullscreen / borderless / windowed / minimised, with the window, back buffer and monitor (beta.10) | `GetFullscreenState` + `GetDesc` polled on the presenting chain (≤ 2 Hz, shared-memory region 4), and the window's geometry read by the Agent **out of process** — so this row is **both tiers**: a Tier-2 session has the window alone, and never splits exclusive from borderless (`03_METRICS` §Display mode) |
|
||||
|
||||
> **Not built, 2026-09-15:** four rows above have no writer yet — HDR output, Reflex and PC latency, per-process
|
||||
> VRAM, and PSO compilation events. The Overlay never sets their measured bits, so every calculator over them
|
||||
> returns nothing and the columns stay null; `legal/ACCURACY.md` lists them as not measured. This table is the
|
||||
> design; the block is the state.
|
||||
>
|
||||
> **2026-09-27 (beta.10):** the first row's *swap effect* has a writer since schema 0016 — region 4's `GetDesc`, stored
|
||||
> in `sessions.swap_effect` as a name (`flip_discard`, …) — and the display-mode row is new. **Present mode has none**,
|
||||
> and the block above did not list it: `sessions.present_mode` is null on every row, and the pages say N/A.
|
||||
>
|
||||
> **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
|
||||
@@ -42,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.
|
||||
~~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
|
||||
{
|
||||
@@ -59,9 +68,9 @@ 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`.
|
||||
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`, and since beta.33 **`root_file`** — an exact file name directly in the install root, answered from that one folder's own listing (`GameFileSnapshot.RootFiles`), so a deep walk that ran short makes its miss no less certain; a root that could not be listed makes it `Unknown`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`, and since 2026-09-27 **`unreal_build`** (no parameter; decided in code, §Engine version). A regex extractor must capture exactly **one** group — the evaluator returns the first — and `rules-validate.ps1` refuses any other count and any pattern that does not compile (both promised by the rules file's `$comment` and enforced by nothing until beta.10).
|
||||
|
||||
> `path_contains` and `strings_regex` were in the shipped data and the schema
|
||||
> and missing from this list; the schema's own `$comment` said so and nobody had
|
||||
@@ -83,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:
|
||||
|
||||
@@ -131,15 +143,15 @@ Recorded as a residual risk, not as a solved problem.
|
||||
|
||||
| Engine | Signals | Version |
|
||||
|---|---|---|
|
||||
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | FileVersion of `UnityPlayer.dll` |
|
||||
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)` |
|
||||
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
|
||||
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | `unity_build` (since 2026-10-12, §Engine version — Unity, Godot, RPG Maker): the player library's ProductVersion, the data file's header, the library's numeric version. ~~FileVersion of `UnityPlayer.dll`~~ — the string as it is, `2022.3.39.5118735`, the build number where the release letter belongs |
|
||||
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | `unreal_build` (since 2026-09-27, §Engine version): the shipping executable's numeric file version and the engine's branch name inside it. ~~ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)`~~ — two capture groups, of which the evaluator returns the first, so every Unreal version it ever stored was a bare `4` or `5` |
|
||||
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | `godot_build` (since 2026-10-12): a data pack's header, beside the executable or appended to it. ~~strings regex `Godot Engine v(\d+\.\d+[\.\d]*)`~~ — the string sits 57–78 MB into a real export, past the 8 MiB scan, so it never read one |
|
||||
| GameMaker | `data.win` | `N/A` |
|
||||
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `N/A` — the `.js` header needs a `from` that `strings_regex` lacks |
|
||||
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `N/A` — one rule, the variant unnamed |
|
||||
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `rpgmaker_build` (since 2026-10-12): the core script's header, which also names the maker (MZ or MV). ~~`N/A` — the `.js` header needs a `from` that `strings_regex` lacks~~ |
|
||||
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `rpgmaker_build` (since 2026-10-12): the RGSS library `Game.ini` names — its generation names the maker (XP, VX, VX Ace), its version is the library's. ~~`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 | — |
|
||||
@@ -188,17 +200,137 @@ Order matters (first match wins). Engine is user-overridable.
|
||||
|
||||
Everything else in the table is in the data and has a fixture; `rules-validate.ps1` fails if a rule id has no fixture directory, or a fixture no rule.
|
||||
|
||||
### Engine version — Unreal Engine (beta.10, 2026-09-27, schema 0015)
|
||||
|
||||
The owner asked for "the exact Unreal Engine version (3.0, 4.5, 5.1 …) on the game's page". What was shipped could not
|
||||
give one: the rule read only the executable's `ProductVersion` string, which most shipping executables leave empty, and
|
||||
its regex had two capture groups, so the one answer it could give was `4` or `5`. **Measured before anything was written,
|
||||
read-only, on the owner's ten Unreal titles** (`spike-notes` §Unreal Engine versions):
|
||||
|
||||
| Title | Numeric file version | Version strings / company | Branch name in the bytes | Read as |
|
||||
|---|---|---|---|---|
|
||||
| Black Myth: Wukong | 5.0.0.0 | none | `++UE5+Release-5.0` (290 MB into `.code`; `.rdata` 8 KB) | 5.0.0 |
|
||||
| Cronos: The New Dawn (demo) | 1.2.0.0 | the studio's | none | — |
|
||||
| Clair Obscur: Expedition 33 | 5.4.4.0 | none | none | 5.4.4 (file version) |
|
||||
| Hell Is Us | 5.5.4.0 | `UE5-CL-0` / Nacon | none (the studio's own branch) | 5.5.4 (file version) |
|
||||
| Lies of P | 4.27.2.0 | none | none | 4.27.2 (file version) |
|
||||
| Martha Is Dead | 4.27.0.0 | none | `++UE4+Release-4.27` (`.rdata`) | 4.27.0 |
|
||||
| Rune Factory: Guardians of Azuma | 1.0.3.0 | none | none | — |
|
||||
| SILENT HILL 2 | 1.0.0.5 | the studio's | `++UE5+Release-5.1` (`.rdata`) | 5.1 |
|
||||
| UMIGARI | 5.5.4.0 | `++UE5+Release-5.5-CL-40574608` / Epic Games, Inc. | (in the strings) | 5.5.4 |
|
||||
| AbyssMemory | 4.26.1.0 | none | `++UE4+Release-4.26` (`.rdata`) | 4.26.1 |
|
||||
|
||||
**Two witnesses, each wrong in its own way.** The numeric file version (`VS_FIXEDFILEINFO`) is the engine's
|
||||
MAJOR.MINOR.PATCH unless the studio replaced it (Cronos, SILENT HILL 2, Rune Factory); the branch name the engine compiles
|
||||
in (a UTF-16 string) names the release line and no patch, and is missing wherever a studio renamed its branch or the
|
||||
executable is packed. `Domain.Detection.UnrealVersion.Decide` takes them in order: **(1)** both, agreeing on MAJOR.MINOR →
|
||||
the file's MAJOR.MINOR.PATCH (`unreal_branch_file`); **(2)** a branch name alone → MAJOR.MINOR (`unreal_branch`); **(3)**
|
||||
no branch name, and a file version that reads as an engine's (4.0–4.27, 5.0–5.9, patch ≤ 20) where nothing says the studio
|
||||
replaced it — no version strings, a string naming the same `UE4`/`UE5`, or Epic's company name → MAJOR.MINOR.PATCH
|
||||
(`unreal_file_version`); **(4)** anything else → no version. The third rung is the weakest (a studio could number its own
|
||||
game 4.2 and ship no strings), which is why `games.engine_version_source` keeps the rung and the game page says it.
|
||||
|
||||
**Where it is read.** `StaticGameDetector` makes a second read for the one engine that matched — never the probe for every
|
||||
game in the library: `GameFileProbe.ReadUnrealBuildAsync` picks the row's own executable when it is the shipping build
|
||||
(`*-Win64-Shipping.exe`, `*-WinGDK-Shipping.exe`), else the largest shipping executable the walk listed (a row pointing at
|
||||
the launcher stub at the install root), and `UnrealBuildReader` reads its version resource and — unless the version strings
|
||||
already name the branch — scans its `.rdata` section for the branch name: 15–39 MB in nine of the ten titles. An `.rdata`
|
||||
under 1 MiB (Black Myth's protector merged its constants elsewhere) sends the scan over the whole file, bounded at 1 GiB and
|
||||
stopping at the first chunk that names a release line. Chunks are 4 MB with an overlap, so a name cut by a chunk's edge is
|
||||
read whole and never as the digits that fitted; cancellation is observed between chunks. Measured through the shipped
|
||||
reader on the same ten files: every row above as tabled, 16 ms to 1.1 s each and 7.5 s for Black Myth, on the owner's USB
|
||||
drive — once per executable, because the detection key (rules version + size + mtime) changes only when the file does.
|
||||
|
||||
**What it is not.** UE3 titles are not detected as Unreal at all (the rule's signals are UE4/5's layout) and have no
|
||||
numbered release lines to report. A version the user typed is never overwritten and carries no witness. Rules
|
||||
`2026.09.6` change the key, so every library entry is read again once; schema 0015 removes the bare `4`/`5` the old rule
|
||||
wrote, where detection wrote it.
|
||||
|
||||
### Engine version — Unity, Godot, RPG Maker (beta.19, 2026-10-12, rules 2026.10.2)
|
||||
|
||||
The owner asked for the version of RPG Maker, Unity and Godot games ("if possible"). What the rules gave: Unity's
|
||||
`pe_file_version` stored `UnityPlayer.dll`'s FileVersion string as it is (`2022.3.39.5118735`, the build number where the
|
||||
release letter belongs); Godot's `strings_regex` scanned the executable's first 8 MiB, and in both Godot exports on the
|
||||
owner's disk the `Godot Engine v…` string sits 57–78 MB in, so it never read one; both RPG Maker rules had `version: null`.
|
||||
**Measured before anything was written, read-only, on 23 installs** (`spike-notes` §17), and decided in code as Unreal's
|
||||
is — three extractor types that take no parameter (`unity_build`, `godot_build`, `rpgmaker_build`; the schema's enum),
|
||||
one second read by `StaticGameDetector` for the engine that matched, a decider in `Domain.Detection` and the witness in
|
||||
`games.engine_version_source`:
|
||||
|
||||
| Engine | Witness, strongest first | Source id | On the owner's disk |
|
||||
|---|---|---|---|
|
||||
| Unity | `UnityPlayer.dll`'s ProductVersion is an editor version (`2022.3.39f1 (4e1b…)` → `2022.3.39f1`) | `unity_player` | 13 of 15 |
|
||||
| | the header of `<Game>_Data\globalgamemanagers` (first 256 bytes) names one | `unity_data` | A Space for the Unbound, 2019.4.1f1 |
|
||||
| | the library's numeric file version, MAJOR.MINOR.PATCH and no release letter — Unity's own binary, so the engine's, only shorter | `unity_player_file` | GIRLS' FRONTLINE 2 (data file encrypted), 2019.4.40 |
|
||||
| Godot | the 20-byte header of the data pack beside the executable (`<exe>.pck`, else the only `.pck` there): `GDPC`, format, MAJOR, MINOR, PATCH | `godot_pck` | both: 4.2.2, 4.4.1 |
|
||||
| | the same header of a pack appended to the executable, found through its 12-byte trailer (size + `GDPC`) | `godot_pck_embedded` | none (synthetic files only) |
|
||||
| | the executable's ProductVersion while its ProductName is still `Godot Engine` (a project that set its own carries the game's: 衔蝶 `0.1.0.3`) | `godot_exe` | — |
|
||||
| RPG Maker MV/MZ | line 2 of the core script: `js/rmmz_core.js` → MZ, `www/js/rpg_core.js` or `js/rpg_core.js` → MV (first 4 KiB) | `rpgmaker_mz_core`, `rpgmaker_mv_core` | MZ 1.10.0; MV 1.6.2, 1.6.2, 1.6.1 |
|
||||
| RPG Maker XP/VX/VX Ace | the RGSS library `Game.ini`'s `Library=` names: RGSS1 → XP, RGSS2 → VX, RGSS3 → VX Ace; its numeric version when it is its generation's, else the one its name carries (`RGSS301` → 3.0.1) | `rgss1_library`, `rgss2_library`, `rgss3_library` | VX Ace 3.0.1, twice |
|
||||
|
||||
A Godot version leaves out a zero patch, as Godot names its releases (4.3, 4.2.2). The App names the maker from the
|
||||
witness — the two RPG Maker rules each cover several makers — and says that an RGSS number is the runtime library's, not
|
||||
the editor's: *RPG Maker MZ 1.10.0*, *RPG Maker VX Ace (RGSS 3.0.1)* (`Formats.Engine(id, source)`,
|
||||
`Formats.EngineWithVersion`); the game page's *Engine version* row says what each version was read from, and *Not found in
|
||||
the game's files* once the sweep has read a row of these engines and found none.
|
||||
|
||||
**Where it is read.** Beside the row's executable first: `UnityPlayer.dll` (else the shallowest one the walk listed) and
|
||||
`<exe>_Data` (else a `*_Data` beside that player); `<exe>.pck`. RPG Maker's files are looked for beside the executable and
|
||||
up to two folders above it, as `RpgMakerTitle` already looked for a title — a launcher-fronted game keeps its runtime in
|
||||
a subfolder (A Doll's Locket's `css\`, HELLO, HELLO WORLD!'s `swiftshader\` — *both "launchers" are malware, D57,
|
||||
`spike-notes.md` §20*); a `Library=` that points outside the ini's
|
||||
folder is named and not read. Version resources and at most a few kilobytes of any file; the whole detection of one entry
|
||||
measured 24 ms to 4.1 s on the owner's USB drive, nearly all of it the install's walk, once per executable and rules
|
||||
version. The Privacy Policy says so since 2.8 (§4).
|
||||
|
||||
**What it is not.** RPG Maker 2000/2003 is not detected at all (no install to measure, no rule). XP and VX libraries are
|
||||
read by the VX Ace rule's reader unmeasured. A Unity build older than 2019 keeps its player in the executable (no
|
||||
`UnityPlayer.dll`): its data file's header is the only witness. Rules `2026.10.2` change the detection key, so every
|
||||
library entry is read again once; a Unity row keeps the old raw string only if none of its witnesses can be read now.
|
||||
|
||||
### Engine version — Ren'Py (beta.20, 2026-10-12, rules 2026.10.3)
|
||||
|
||||
The owner asked for the version of Ren'Py games once beta.19's were on screen. The `renpy` rule had no version extractor
|
||||
(`version: null`). Ren'Py ships its engine as Python beside the game's launcher, and `renpy/vc_version.py` names its
|
||||
release — `version = '8.5.0.25111603'`, beside `branch`, `nightly`, `official` and `version_name`. Measured 2026-10-12 on
|
||||
the owner's one Ren'Py install, Bound Between Desks (Steam): 109 bytes, and the game's own `log.txt` printed
|
||||
`Ren'Py 8.5.0.25111603` at its last start; the launcher carries no version resource (`spike-notes` §18).
|
||||
|
||||
**What is read and how it is decided.** `renpy_build` (`RenPyBuildReader`): the first 4 KiB of `renpy/vc_version.py`
|
||||
beside the row's executable, its `version` line only (`version_name` is not it). `RenPyVersion.Decide` keeps
|
||||
MAJOR.MINOR.PATCH — Ren'Py names its releases by those three; the fourth is the build — and records `renpy_vc_version`.
|
||||
The page says *Ren'Py 8.5.0* and that it was read from the engine's version file; a Ren'Py row whose file names no
|
||||
version says *Not found in the game's files*. Through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`)
|
||||
Bound Between Desks read `8.5.0` in 79 ms, and the Unity, Godot and RPG Maker installs read as before. The Privacy
|
||||
Policy names the file since 2.9 (§4). Rules `2026.10.3` change the detection key, so every library entry is read again
|
||||
once.
|
||||
|
||||
**What it is not.** Nothing else is guessed from: a Ren'Py game whose `vc_version.py` names no version, or that ships its
|
||||
engine compiled only, reads as not found. One Ren'Py install was measured.
|
||||
|
||||
### Platform signatures & metadata
|
||||
|
||||
| Platform | Signals | Metadata |
|
||||
|---|---|---|
|
||||
| Xbox *(beta.33, D79; first in the array)* | **both** `MicrosoftGame.config` and `appxmanifest.xml` directly in the install root (`root_file`, `all`): a GDK package root. First because a GDK build can ship Steam's DLL — every FINAL FANTASY Pixel Remaster from the Xbox app carries `Plugins\x86_64\steam_api64.dll` (`spike-notes` §25) — and a `root_file` miss is never `Unknown` for want of a deep walk, so a large Steam install behind it still reads *steam* | each drive's `.GamingRoot` → `<games folder>\<Game>\Content\`: `MicrosoftGame.config` (Identity, ShellVisuals, ExecutableList, StoreId) and `appxmanifest.xml` (the Application id); the package family name and its registration from Windows (`PackageFamilyNameFromId`, `GetPackagesByPackageFamily`) |
|
||||
| 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 |
|
||||
|
||||
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf` except `SteamLibrarySource.KnownTools` (2026-09-22: Steamworks Common Redistributables, Borderless Gaming, Wallpaper Engine, SteamVR, the Proton and Steam Linux Runtime entries, Blender — tools Steam's manifests do not distinguish from games, and which became library rows the watcher recorded); GOG via `HKLM\SOFTWARE\WOW6432Node\GOG.com\Games\*`; Epic via `Manifests\*.item`; itch by receipt scan. Import presents a review checklist; nothing is launched, nothing is hooked on import.
|
||||
> **The stores' artwork on this PC (beta.23, owner decision D60).** A game's page shows the cover and banner the Steam and
|
||||
> GOG GALAXY apps already keep — Steam's `appcache\librarycache\<appid>\` (files flat or in hash-named folders), GOG
|
||||
> GALAXY's `webcache\<user>\gog\<productId>\` — found for the store whose own records own the game's folder
|
||||
> (`StoreRecords.Owning`, as Play finds it). `Infrastructure.Art.SteamArtCache` and `GogArtCache` read them; nothing is
|
||||
> downloaded, so the *(opt-in)* online lookup in the publisher/version order below still does not exist. Epic, itch and
|
||||
> other stores keep no image files: their games show the image the user chooses, or none. The detail: `08_UI` §Games ›
|
||||
> Game detail, *The header's cover*. *(beta.33: an Xbox game ships its own — `Infrastructure.Art.XboxArtCache` reads the
|
||||
> `Square480x480Logo` (else `Square150x150Logo`) and the `SplashScreenImage` its `MicrosoftGame.config` names, inside
|
||||
> the package root only, as a square cover and the banner; `IStoreArtCache.Find` takes the owning record rather than the
|
||||
> id, because those pictures live in the install folder.)*
|
||||
|
||||
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf` except `SteamLibrarySource.KnownTools` (2026-09-22: Steamworks Common Redistributables, Borderless Gaming, Wallpaper Engine, SteamVR, the Proton and Steam Linux Runtime entries, Blender — tools Steam's manifests do not distinguish from games, and which became library rows the watcher recorded); GOG via `HKLM\SOFTWARE\WOW6432Node\GOG.com\Games\*`; Epic via `Manifests\*.item`; itch by receipt scan; *(beta.33)* Xbox by each drive's `.GamingRoot` and each game's package files. Import presents a review checklist; nothing is launched, nothing is hooked on import.
|
||||
|
||||
> **Built 2026-09-14 (P4 PR-4).** `Application.Import.LibraryImporter` over four `IStoreLibrarySource` adapters in
|
||||
> `Infrastructure.Import` — `SteamLibrarySource` (`libraryfolders.vdf` + `appmanifest_*.acf` through
|
||||
@@ -235,7 +367,52 @@ Everything else in the table is in the data and has a fixture; `rules-validate.p
|
||||
> is fetched (CLAUDE.md rule 8's "opt-in store metadata" is the online lookup, which does not exist). First-run
|
||||
> step 4 now points at File ▸ Import library… rather than saying "later build".
|
||||
|
||||
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days. *(Since beta.8 the PE versions are stored beside the store's rather than instead of it — §What the files say about themselves; the page labels a store's value with its store, "Steam build 20374416".)*
|
||||
> **beta.33 (owner decisions D78/D79, `spike-notes` §25): the Xbox app's and the Microsoft Store's games.**
|
||||
> `XboxLibrarySource` reads each ready fixed or removable drive's `.GamingRoot` (`GamingRoots`: `RGBX`, a count, UTF-16
|
||||
> folder names relative to the drive), lists the `<games folder>\<Game>\Content\` folders that are GDK package roots
|
||||
> (`GdkPackageFiles`: `MicrosoftGame.config` beside `appxmanifest.xml`, read with DTDs prohibited and a 1 MB cap), and
|
||||
> keeps those whose package Windows says is installed for this user (`PackageFamilyNameFromId`, then
|
||||
> `GetPackagesByPackageFamily`). The record: the store id is the package family name, the install directory is `Content`
|
||||
> (the spelling the game's own process reports — never the `C:\Program Files\WindowsApps` junction, whose name carries
|
||||
> the version), the launch key is the AUMID `<family name>!<Application Id>` that Play activates, the version is the
|
||||
> package's. It names no executable, so `ExecutableLocator` ranks: the WinGDK or Win64 shipping binary over the stub the
|
||||
> package launches, the Unity player over its crash handler, never `gamelaunchhelper.exe` (a runtime helper since
|
||||
> beta.33), with the folder above `Content` as the install's name. **What cannot be read:** every game `.exe` under
|
||||
> `Content` refuses `FILE_READ_DATA` to a process outside its package, so its PE header, version resource, imports and
|
||||
> strings are not read — the architecture reads `unknown` (never "not x64", so nothing is turned off for it), no Unreal
|
||||
> version is shown, and the Unity version still reads, from `UnityPlayer.dll`. A UWP app has no `MicrosoftGame.config`
|
||||
> and is not listed (D78).
|
||||
|
||||
> **beta.19 (owner report 2026-10-12): a store's own pick can be a helper, and a launcher is not the game.** The owner's
|
||||
> A Doll's Locket - Remake (itch 5085165, RPG Maker MZ) was imported as `Dolls Locket\notification_helper.exe` — NW.js's
|
||||
> toast helper. The pick was **butler's verdict**, taken as is: butler stores a *filtered* verdict (the shallowest
|
||||
> candidates, minus those whose manifest asks for elevation) and does not rank what is left, and on that install the
|
||||
> 213 MB `DollsLocket.exe` launcher asks for administrator while the NW.js runtime sits a level deeper in `css\`, so the
|
||||
> helper was the whole verdict (read from the owner's `butler.db`, read-only). *(Corrected 2026-10-13, owner decision
|
||||
> D57: that "launcher" — the same 213 MB program HELLO, HELLO WORLD!, City of Bones and Träumerei put in front of their
|
||||
> runtime — is malware: it ships a registry file that switches off Windows' script scanning and adds Microsoft Defender
|
||||
> exclusions (`spike-notes.md` §20). Do not run it. The admin-mode sentence below is withdrawn; the three changes stand
|
||||
> as rules about helpers and NW.js layouts, and the import still takes a store's own pick when it is not a helper.)*
|
||||
> Three changes:
|
||||
> **(1)** a verdict candidate whose whole name is a runtime helper (`ExecutableLocator.RuntimeHelperNames`:
|
||||
> `notification_helper`, `crashpad_handler`, `UnityCrashHandler64/32`, `CrashReportClient`, NW.js's `nwjc` and
|
||||
> `chromedriver`) or that sits in a Unity plugin folder is skipped, and with nothing left the locator guesses and the
|
||||
> review marks the row *guessed* — whole names, because the locator's fragments are inside real games' names (`node` in
|
||||
> *Nodebuster*) and a store's pick is overruled only when it cannot be the game; the locator's `HelperFragments` gain the
|
||||
> same three NW.js names. **(2)** The locator ranks **an executable beside `nw.dll` + `package.json`** — the `rpgmaker_mv`
|
||||
> rule's own signal — as an NW.js runtime (owner decision D56), below the Unity and Unreal layouts (an NW.js folder can
|
||||
> be a tool shipped beside such a game) and above a name match (the launcher in front of the runtime is named after the
|
||||
> install): the install's guess is `css\Game.exe`, the process that draws, as D28 pointed HELLO, HELLO WORLD!'s entry at
|
||||
> its runtime by hand. ~~That runtime starts elevated (its launcher asks for administrator), so it is measured with the
|
||||
> admin mode on (D34).~~ *(Withdrawn 2026-10-13, D57: it starts elevated because the malware in front of it asks for
|
||||
> administrator.)* **(3)** Discovery matches a store title to an entry by **platform + store id** as well as by
|
||||
> path: the entry an earlier import made at another executable is "already in the library" (the log names its path),
|
||||
> so a corrected guess never adds the same game a second time — that entry is re-pointed with Change executable…, and
|
||||
> nothing rewrites it by itself (D25/D27). Tests: `ExecutableLocatorTests.AnNwjsRuntimeBeatsTheLauncherNamedAfterTheInstallAndItsHelpersAreDropped`,
|
||||
> `StoreLibrarySourcesTests.ItchSkipsAVerdictCandidateThatIsARuntimeHelper` (the verdict as stored),
|
||||
> `LibraryImporterTests.AStoreTitleAlreadyInTheLibraryAtAnotherExecutableIsNotOfferedAgain`.
|
||||
|
||||
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` ~~→ *(opt-in)* Steam `appdetails` lookup, cached 7 days~~ *(never built — FrameLedger makes no request to a store, `privacy.online_metadata` is reserved, and a game's artwork (beta.23, D60) is read from the store app's own files on the disk; struck 2026-10-14)*. *(Since beta.8 the PE versions are stored beside the store's rather than instead of it — §What the files say about themselves; the page labels a store's value with its store, "Steam build 20374416".)*
|
||||
|
||||
## Capability hints (explicitly labelled as such)
|
||||
|
||||
@@ -283,22 +460,83 @@ detection (`DetectionWrite`, `games.exe_machine` / `exe_file_version` / `exe_pro
|
||||
"FSR 2.2" number: the DLL's version is the SDK's, and no table of that mapping has been measured.
|
||||
|
||||
**Shipped is not loaded.** `library_versions` is what the game folder holds. What the process loaded is
|
||||
`sessions.runtime_modules` (Tier 1), and the two differ exactly when something else supplied the DLL — the NVIDIA
|
||||
App's DLSS override loads the driver's `nvngx_dlss.dll` from the driver store under the same name. The session
|
||||
summary prints the loaded list and names such a difference ("the game ships 3.7.10.0: another copy was loaded");
|
||||
it does not claim who loaded it.
|
||||
`sessions.runtime_modules` (Tier 1), and the two differ exactly when something else supplied the DLL. ~~— the NVIDIA
|
||||
App's DLSS override loads the driver's `nvngx_dlss.dll` from the driver store under the same name.~~ *(Struck
|
||||
2026-10-19: unmeasured, and the one measurement says otherwise — the owner's Silent Hill 2 session ran ×6 frame
|
||||
generation through the NVIDIA App's override and no module with a census name was loaded. Since beta.24 every module
|
||||
under `%ProgramData%\NVIDIA\NGX` is recorded whatever its name, with its folder class — §DLSS generation below —, and
|
||||
owner-only item 20(c) records what the override loads.)* *(Measured 2026-10-19, `spike-notes` §22: under the
|
||||
override, Silent Hill 2 loaded `160_E658700.bin` 310.9.16.0 and `1B0_E658703.dll` 2.14.16.0 from the NGX folder —
|
||||
names no census lists; which feature each serves is not established.)* The session summary prints the loaded list and names such a
|
||||
difference ("the game ships 3.7.10.0: another copy was loaded"); since beta.24 the DLSS line says where each DLSS
|
||||
library was loaded from (the game, the graphics driver, Windows) — by folder, never who put it there.
|
||||
|
||||
## DLSS generation — evidence-bound (beta.24, owner decision D64)
|
||||
|
||||
**What a session can say about which DLSS ran, and nothing more.** `Domain.Detection.DlssGeneration` names a
|
||||
generation only from something the session observed, strongest first; `App.Services.DlssText` prints it with what it
|
||||
rests on, every DLSS library's version and folder class (`sessions.runtime_module_sources`, schema 0021 — the class,
|
||||
never the path), and the super-resolution preset the driver reports applied:
|
||||
|
||||
| Evidence (strongest first) | Label | Where it comes from |
|
||||
|---|---|---|
|
||||
| Super-resolution render preset **L or M** that the NVIDIA driver reports applied, in a session where super resolution ran | DLSS 4.5 (2nd-gen transformer) | `ngx_driver_words` — the SR word's `PRESET` bit and `renderPreset`; presets L/M arrived with DLL 310.5.0 (NVIDIA's DLSS 4.5 release, driver 591.74) |
|
||||
| A DLSS Frame Generation state measured at **×5 or more** | DLSS 4.5 (Dynamic / 6× multi-frame generation) | `fg_mix` / `fg_factor` with `fg_mode = dlssg` |
|
||||
| The NVIDIA App's **Dynamic** frame generation — set in the game's profile and reported applied by the driver — in a session where DLSS Frame Generation was identified *(beta.34, owner decision D83)* | DLSS 4.5 (Dynamic multi frame generation, set in the NVIDIA App) | `driver_profile`'s `NGX_DLSSG_MODE` = 4 (dynamic), `ngx_driver_words`' FG word with `FG_MODE` (bit 13), `fg_mode = dlssg` |
|
||||
| Preset **J or K** reported applied | DLSS 4 (transformer) | as above |
|
||||
| A DLSS Frame Generation state at **×3 or ×4** | DLSS 4 (multi-frame generation) | as above |
|
||||
| `nvngx_dlss.dll` **2.x** | DLSS 2 | `runtime_modules` |
|
||||
| `nvngx_dlss.dll` **3.x**, or `nvngx_dlssg.dll` **1.x–3.x** | DLSS 3 | `runtime_modules` |
|
||||
| A **310.x** library alone, a CNN preset (A–F), ×2 | *no label* — the versions are shown | DLSS 4 and 4.5 ship the same major number; the preset is what names the model |
|
||||
| ~~`nvngx_dlssnr.dll` loaded~~ | ~~"DLSS 5 runtime loaded" — never a generation of these features~~ | ~~the module name is community-sourced until owner-only item 20(d) sees it load~~ *(replaced 2026-11-06 by the two rows below, D84)* |
|
||||
| DLSS 5's neural rendering **evaluated** — `kFeatureDLSS_NR` (Streamline 2.14) on some of the frames the game rendered through Streamline, seen by an Overlay that decodes it *(beta.34, owner decision D84)* | DLSS 5 (neural rendering on N % of rendered frames) — **heads the table** | `dlss_nr_pct` (schema 0022), from `FL_FEAT_SL_NEURAL_RENDERING` under `FL_HOOK_SL_NEURAL_RENDERING` |
|
||||
| `nvngx_dlssnr.dll` loaded, neural rendering not seen evaluated | "DLSS 5 runtime loaded" — and "…, not seen running" where an Overlay that decodes it drained Streamline batches and none carried it (0 %); never a generation | `runtime_modules` (the name seen on Hogwarts Legacy, 2026-11-06) and `dlss_nr_pct` |
|
||||
|
||||
**Amended 2026-11-06 (beta.34, owner decision D83): Dynamic is DLSS 4.5's.** The NVIDIA App's *Dynamic* frame
|
||||
generation and its ×6 mode exist only in DLSS 4.5, so a session the driver reports running Dynamic is DLSS 4.5 whatever
|
||||
multiplier the mode chose: the owner's Phantom Blade Zero under *Dynamic, up to ×3* held ×2.0 and ×3.0 — nine hooked sessions
|
||||
from 2026-11-03 to 11-05 — and read *DLSS 4 (a ×3.0 frame-generation state)* until then. The row needs all three: the
|
||||
profile's Dynamic (`NGX_DLSSG_MODE` = 4, NVIDIA's own name for the value), the driver's report that its frame-generation
|
||||
override applied in the game's process (the FG word's `FG_MODE` bit), and DLSS Frame Generation identified in the session
|
||||
(`fg_mode = dlssg`; its factor need not have been counted) —
|
||||
a profile set to Dynamic that the driver never applied is a setting, not evidence. The driver's own mode number is not
|
||||
read: it answers 3 under Dynamic and 1 under *Fixed* on every stored session (`spike-notes` §26), and NVIDIA's header
|
||||
names neither. A *Fixed* ×5 or ×6 is not this row — Witcher 3 under the App's Fixed ×6 still presented ×2.0 — and
|
||||
names DLSS 4.5 only where a state is measured at ×5 or more, which ranks above it.
|
||||
|
||||
Never a default preset inferred from a version: what a DLL "would" run by default is the game's and the driver's to
|
||||
decide. A preset the driver applied to a super resolution it never saw created and evaluated names the model of
|
||||
nothing and is not used (the owner's Silent Hill 2 session: preset L applied, no SR feature created — its label is
|
||||
the ×6.0 state's). **Sources:** NVAPI's `NV_NGX_DLSS_OVERRIDE_GET_STATE_PARAMS_V1` (the vendored
|
||||
`src/native/third_party/nvapi/nvapi.h`); presets L/M with DLL 310.5.0 — PCGH's DLSS 4.5 test and NVIDIA's driver
|
||||
591.74 release notes; DLSS 4.5's Dynamic MFG and 6× — NVIDIA's announcement (driver 595, RTX 50); DLSS 5 — NVIDIA's
|
||||
GTC 2026 announcement and its 2026-09-03 launch; ~~`nvngx_dlssnr.dll` — community reports only~~ `nvngx_dlssnr.dll` —
|
||||
loaded by the owner's Hogwarts Legacy with Neural Rendering on, 310.9.16.0 from the game's folder (2026-11-06,
|
||||
`spike-notes` §26), beside its Streamline plugin `sl.dlss_nr.dll`; `kFeatureDLSS_NR = 1004` — Streamline `v2.14.16`'s
|
||||
public `sl_core_types.h` (re-vendored for it, `src/native/third_party/streamline/README.md`).
|
||||
|
||||
**Amended 2026-11-06 (beta.34, owner decision D84): DLSS 5 is named where it ran.** Until then a session could say only
|
||||
that DLSS 5's runtime was LOADED — and Hogwarts Legacy, Neural Rendering on, loaded it. The Overlay's
|
||||
`slEvaluateFeature` detour now decodes `kFeatureDLSS_NR` into its own per-frame fact (`FL_FEAT_SL_NEURAL_RENDERING`,
|
||||
the feature byte's last bit, under the condition every Streamline fact shares) and publishes
|
||||
`FL_HOOK_SL_NEURAL_RENDERING` with the detour; the Agent stores the share of Streamline batches that carried it
|
||||
(`dlss_nr_pct`) **only from a writer that published that family** — an older Overlay drains the same batches and never
|
||||
sets the bit, and its silence must not read as 0 %. Above every other row because DLSS 5 is named for that feature as
|
||||
DLSS 4.5 is for its own: the session's super resolution, ray reconstruction and frame generation are the libraries the
|
||||
line lists after it. Whether the game routes neural rendering through `slEvaluateFeature` at all is owner-only item
|
||||
30(a)'s run; a title that does not reads *runtime loaded*, never *not running*.
|
||||
|
||||
## Anti-cheat pre-scan (static)
|
||||
|
||||
Before a game is ever launched with hooking enabled, the static scan checks for anti-cheat SDKs shipped alongside it (`EasyAntiCheat/` directory, BattlEye binaries, EOS anti-cheat components, etc.). A hit **disables the hooking toggle for that game entirely** in the UI, with an explanation — the user cannot enable it, so the guard never even has to fire at launch. Prevention beats interception.
|
||||
|
||||
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` since 2026-09-25, which takes the executable, resolves the install root itself and runs check 3 as well). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1).
|
||||
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` since 2026-09-25, which takes the executable, resolves the install root itself and runs check 3 as well). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1). **It walks two folders since 2026-10-13:** the install root and, when the executable lives below it, the executable's own folder — each three levels deep. The root alone missed Wuthering Waves' `Client\Binaries\Win64\AntiCheatExpert\`, which sits beside the executable and four levels under the root (`19_SAFETY` §Pre-injection checks, item 4; `spike-notes.md` §19).
|
||||
|
||||
Three things this section previously implied that are not true, and are worth stating:
|
||||
|
||||
- **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).
|
||||
- **A hit disables the toggle; "could not scan" must not.** The scan is tri-state. `Reason::kPreScanFailed` — directory absent, unlistable, past the entry bound, or behind a reparse point — is *neither* a hit nor a pass. *("Past a bound" until 2026-10-13: the depth bound is a reach, not a refusal — a folder at the last level is named and never opened, and the walk still reads as complete.)* 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~~ *(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
|
||||
|
||||
@@ -320,7 +558,7 @@ Three things this section previously implied that are not true, and are worth st
|
||||
> the user's and stays; a `detected` entry is refreshed; **an empty field with no entry has nothing to protect
|
||||
> and is filled and badged `detected`** — without that clause a freshly added game could never receive an
|
||||
> engine at all, since `EnsureAsync` writes no provenance. A null detected value erases nothing.
|
||||
> `capability_flags` is written whole every run (a JSON array of the rule ids — `dlss`, `dlss_g`, `dlss_rr`,
|
||||
> `capability_flags` is written whole every run (a JSON array of the rule ids — `dlss`, `dlss_g`, `dlss_rr`, `dlss_nr` (beta.34),
|
||||
> `streamline`, `fsr`, `xess`, `xefg`) because the Supports row has no user-edit surface and a stale "Supports
|
||||
> DLSS-G" after the DLL left is the confusion §Capability hints exists to prevent.
|
||||
- Strings scans bounded to 8 MB, local only.
|
||||
|
||||
+288
-34
@@ -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. **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`, *(since schema 0023, 2026-11-11)* `machine_profiles` and `session_advanced`, 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 was the one Agent write that deletes a `games` row until beta.19; it never touches a consent column. **And since beta.19 (2026-10-12, D55) the Agent removes an entry whose game is no longer installed** (`IGamePrune`, `SqliteGamePrune`, asked by the detection sweep through `UninstalledEntryPrune`): one `DELETE` that holds every stored condition in the same statement — the same row at the same path, `removed_at` NULL, no session stored (`NOT EXISTS` on `sessions` — nothing cascades), no `hook_blocked_reason`, `hook_prescan_state` not `blocked`, no `ac_exception_at` and no `ac_exception_trial_failed_at` — behind `retention.remove_uninstalled_games`; a block, a grant and D38's mark are never removed with their entry (`19_SAFETY` §What a finding does to the game, *What clears it*). **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 excepLine truncated
|
||||
|
||||
## Schema (v2 — hook architecture)
|
||||
|
||||
@@ -43,11 +43,21 @@ CREATE TABLE games (
|
||||
exe_path TEXT NOT NULL UNIQUE, -- where the executable lives; rewritten by ExecutableRelocator when the
|
||||
-- SAME bytes (exe_size_bytes, exe_mtime_ms) turn up under another drive
|
||||
-- letter (2026-09-22), and by Change executable for a DIFFERENT binary
|
||||
platform TEXT NOT NULL DEFAULT 'none', -- steam|gog|epic|itch|none
|
||||
platform TEXT NOT NULL DEFAULT 'none', -- steam|gog|epic|itch|xbox|none (xbox since beta.33, D79; no CHECK constraint, so no migration)
|
||||
store_id TEXT,
|
||||
engine TEXT, engine_version TEXT,
|
||||
-- (schema 0015, ALTERed last) engine_version_source TEXT: where engine_version came from — a
|
||||
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version; since beta.19
|
||||
-- unity_player | unity_data | unity_player_file | godot_pck | godot_pck_embedded | godot_exe | rpgmaker_mz_core |
|
||||
-- rpgmaker_mv_core | rgss1_library | rgss2_library | rgss3_library — the RPG Maker ids also name the maker; since
|
||||
-- beta.20 renpy_vc_version; or the
|
||||
-- rule's extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
|
||||
publisher TEXT, game_version TEXT,
|
||||
cover_path TEXT, notes TEXT,
|
||||
cover_path TEXT, notes TEXT, -- cover_path: written since beta.23 (D60) — the image the user chose, as
|
||||
-- covers\game-<id>-<unix ms>.png relative to the data folder (a PNG copy
|
||||
-- <= 1200 px); followed only when it is one of those names under covers\
|
||||
-- and never through a junction or a symbolic link (a viewer's copy could
|
||||
-- name a share); NULL = the store app's own artwork
|
||||
removed_at INTEGER, -- schema 0002 (P3 PR-3): FR-1.4 "remove, keep sessions" — the row stays
|
||||
-- (sessions.game_id is NOT NULL, ON DELETE CASCADE) but leaves the
|
||||
-- library; a later launch of the same exe restores it (removed_at = NULL)
|
||||
@@ -66,7 +76,7 @@ CREATE TABLE games (
|
||||
-- schema 0014 (2026-09-26, D33): the user-mode anti-cheat exception, a layer OVER hook_blocked_reason, never its clearing
|
||||
ac_exception_eligible INTEGER NOT NULL DEFAULT 0, -- the Agent's sweep: the exception may be granted now
|
||||
ac_exception_verdict TEXT, -- its tolerant pre-scan, Reason|Family|Signal; NULL = nothing asked
|
||||
ac_exception_sessions INTEGER NOT NULL DEFAULT 0, -- successful Tier-1 sessions counted
|
||||
ac_exception_sessions INTEGER NOT NULL DEFAULT 0, -- D38: successful sessions under the grant in force (its trial)
|
||||
ac_exception_checked_rules_version TEXT, -- the key the verdict was reached under: rules, executable size and
|
||||
ac_exception_checked_exe_size_bytes INTEGER, -- mtime, and the block text itself
|
||||
ac_exception_checked_exe_mtime_ms INTEGER,
|
||||
@@ -78,7 +88,9 @@ CREATE TABLE games (
|
||||
ac_exception_exe_mtime_ms INTEGER,
|
||||
ac_exception_lapsed_at INTEGER, -- when and why the last grant ended (UserModeExceptionLapse:
|
||||
ac_exception_lapsed_reason TEXT, -- Withdrawn|ExecutableChanged|NoLongerEligible|NewFinding|
|
||||
-- SafetyUnhook|OverlayStopped|SessionCrashed)
|
||||
-- SafetyUnhook|OverlayStopped|SessionCrashed|TrialFailed)
|
||||
-- schema 0017 (2026-10-03, D38): an exception of this game ended during its trial — for good; never cleared
|
||||
ac_exception_trial_failed_at INTEGER,
|
||||
hook_autodisabled_reason TEXT, -- set after repeated crashes
|
||||
hook_crash_count INTEGER NOT NULL DEFAULT 0,
|
||||
capability_flags TEXT, -- JSON: what the game SHIPS — never a measurement. Since P4 PR-1 (2026-09-14) a JSON
|
||||
@@ -118,15 +130,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
|
||||
@@ -137,7 +152,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
|
||||
@@ -159,7 +175,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
|
||||
@@ -185,7 +204,9 @@ CREATE TABLE sessions (
|
||||
started_at INTEGER NOT NULL, ended_at INTEGER NOT NULL, duration_s REAL NOT NULL,
|
||||
|
||||
capture_tier INTEGER NOT NULL, -- 1 = hooked, 2 = not hooked; CHECK (capture_tier IN (1,2))
|
||||
capture_notes TEXT, -- why tier degraded, late_attach, etc.
|
||||
capture_notes TEXT, -- why tier degraded, late_attach, etc.; beta.14 adds crash_reporter= /
|
||||
-- crash_reporter_seen= (an engine's crash reporter the game started) and
|
||||
-- scan_at_exit= (D48: a re-scan that could not read as the game exited)
|
||||
late_attach INTEGER NOT NULL DEFAULT 0,
|
||||
telemetry_source TEXT, -- composite descriptor, e.g. 'l1+lhm+nvapi' (18_GPU_VENDOR_APIS)
|
||||
overlay_build_id TEXT, -- native DLL build that produced this data
|
||||
@@ -209,11 +230,13 @@ CREATE TABLE sessions (
|
||||
-- presentation
|
||||
api TEXT, present_mode TEXT, swap_effect TEXT,
|
||||
hdr_flag TEXT NOT NULL DEFAULT 'na', hdr_source TEXT, -- tri-state, like rt/rr beside it
|
||||
sync_interval_mode TEXT, -- observed vsync behavior
|
||||
sync_interval_mode TEXT, -- observed vsync behavior: on|off|mixed — first written in beta.14 (0019's
|
||||
-- §Sync), NULL where no present carried its arguments (OpenGL, Vulkan, Tier 2)
|
||||
|
||||
-- upscaling / FG (measured at tier 1)
|
||||
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown
|
||||
upscaler_quality TEXT,
|
||||
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, -- the hooked byte, invariant: dlss 1-6 (sl::DLSSMode); fsr/fsr3 16-20 =
|
||||
-- 0x10 + FfxApiUpscaleQualityMode since beta.25 (D65); NULL when none told
|
||||
upscaler_sharpness INTEGER, -- percent; NULL when the API reports none
|
||||
render_w INTEGER, render_h INTEGER, -- dominant segment
|
||||
output_w INTEGER, output_h INTEGER,
|
||||
@@ -229,7 +252,8 @@ CREATE TABLE sessions (
|
||||
fg_source TEXT, -- api|cadence|manual (`etw` removed 2026-08-28: no producer, no tier)
|
||||
fg_factor REAL,
|
||||
-- schema 0003 (2026-09-14): why fg_factor is NULL while fg_mode names a technology — FgRefusalKind as
|
||||
-- Vocabulary.FgRefusal spells it (not_counted, no_evaluations, non_uniform, dxgi_saturated, …). NULL when a
|
||||
-- Vocabulary.FgRefusal spells it (not_counted, no_evaluations, non_uniform, dxgi_saturated, …; beyond_generation
|
||||
-- since beta.26: a ratio above FgWindow.GenerationCeiling that held throughout). NULL when a
|
||||
-- factor stands or the writer predates the column. A REASON for the UI, never an input to fg_mode or a number.
|
||||
fg_refusal TEXT,
|
||||
-- FlWriterState.runtimeCensus, raw (FlRuntimeCensus bits). Which vendor runtime modules
|
||||
@@ -271,7 +295,54 @@ CREATE TABLE sessions (
|
||||
avg_cpu_temp REAL, max_cpu_temp REAL,
|
||||
avg_gpu_temp REAL, max_gpu_temp REAL, max_gpu_hotspot REAL,
|
||||
avg_gpu_load REAL, avg_cpu_load REAL, avg_ram_mb REAL,
|
||||
avg_gpu_power_w REAL, throttle_pct REAL
|
||||
avg_gpu_power_w REAL, throttle_pct REAL,
|
||||
|
||||
-- schema 0018 (2026-10-03, beta.12, D43): the game process's own memory, read from outside it, both tiers
|
||||
-- (03_METRICS §Game process memory), MiB; and every sensor series' n/mean/median/min/max as JSON
|
||||
game_vram_dedicated_avg_mb REAL, game_vram_dedicated_median_mb REAL, game_vram_dedicated_max_mb REAL,
|
||||
game_vram_shared_max_mb REAL,
|
||||
game_ram_private_avg_mb REAL, game_ram_private_median_mb REAL, game_ram_private_max_mb REAL,
|
||||
game_ram_ws_max_mb REAL, game_commit_max_mb REAL,
|
||||
game_memory_processes INTEGER, -- processes summed: 1 pinned, every process of the executable for a held one
|
||||
game_memory_source TEXT, -- counters,ex2,ex,held,opened — the reads that answered
|
||||
sensor_stats_json TEXT, -- {"gpu_temp":{"N":…,"Mean":…,"Median":…,"Min":…,"Max":…}, …}
|
||||
|
||||
-- schema 0019 (2026-10-06, beta.14, D49): pacing (hooked), the present arguments (Direct3D), the card's clocks and limits
|
||||
-- (both tiers) and efficiency (hooked) — 03_METRICS §Pacing, §Sync, §Sensor aggregates, §Efficiency
|
||||
time_below_30_pct REAL, time_below_60_pct REAL,
|
||||
time_below_refresh_pct REAL, -- over presents, at display_monitor_hz; NULL without a rate
|
||||
frametime_delta_mean_ms REAL, -- mean |ft[k] - ft[k-1]| over neighbouring intervals
|
||||
vsync_present_pct REAL, tearing_allowed_pct REAL, -- shares of the presents that carried their arguments
|
||||
avg_gpu_core_clock_mhz REAL, avg_gpu_mem_clock_mhz REAL, avg_gpu_fan_rpm REAL, max_gpu_mem_temp REAL,
|
||||
power_limit_pct REAL, thermal_limit_pct REAL, -- shares of the ticks that carried reasons: NVIDIA (L3) only
|
||||
app_frames_per_joule REAL, -- application FPS / average GPU board power; never displayed frames (rule 6)
|
||||
|
||||
-- schema 0021 (2026-10-19, beta.24, D64): each loaded runtime module's folder class — 05_DETECTION §DLSS generation
|
||||
runtime_module_sources TEXT, -- {"nvngx_dlss.dll":"graphics_driver", …}: game | graphics_driver | windows; never a path
|
||||
|
||||
-- schema 0022 (2026-11-06, beta.34, D84): DLSS 5's neural rendering — 05_DETECTION §DLSS generation
|
||||
dlss_nr_pct REAL, -- 0–100 of the Streamline batches that evaluated kFeatureDLSS_NR; NULL = nothing could tell
|
||||
|
||||
-- schema 0020 (2026-10-19, beta.24, D62): every frame-generation state the session held — 03_METRICS §The mix
|
||||
fg_mix TEXT, -- {"Rows":[{"Kind":"generated","Factor":4.0,"NativeFps":…,"DisplayedFps":…,
|
||||
-- "Seconds":…,"Share":…,"Windows":…}, …]}: states by rising factor, then
|
||||
-- "none", then "unclassified"; NULL with no state, and before 0020
|
||||
|
||||
-- schema 0016 (2026-09-27, beta.10): the display mode, both tiers (03_METRICS §Display mode). Milliseconds per mode,
|
||||
-- each sample standing for the time until the next (100 ms hooked, 1 s at Tier 2), a pause not counted; nowindow is
|
||||
-- outside every share. NULL before, on a session recovered from its .partial file, and where the loop never sampled —
|
||||
-- N/A, never 0. Written on the recorder's SKELETON: a Tier-2 session never reaches the aggregator.
|
||||
display_exclusive_ms INTEGER, -- the swap chain SAID exclusive (DXGI only)
|
||||
display_borderless_ms INTEGER, -- covers its monitor, the chain said not exclusive
|
||||
display_windowed_ms INTEGER,
|
||||
display_covers_ms INTEGER, -- covers its monitor and nothing could say which ("fullscreen or borderless")
|
||||
display_minimized_ms INTEGER,
|
||||
display_nowindow_ms INTEGER, -- no window could be read
|
||||
display_changes INTEGER, -- mode changes between samples
|
||||
display_source TEXT, -- swapchain | opengl | window: the strongest witness any sample had
|
||||
display_window_w INTEGER, display_window_h INTEGER, -- client area, in the mode that lasted longest (the last seen, beta.27)
|
||||
display_buffer_w INTEGER, display_buffer_h INTEGER, -- the swap chain's back buffer, same mode
|
||||
display_monitor_w INTEGER, display_monitor_h INTEGER, display_monitor_hz INTEGER
|
||||
);
|
||||
CREATE INDEX ix_sessions_game_started ON sessions(game_id, started_at DESC);
|
||||
|
||||
@@ -308,7 +379,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
|
||||
@@ -322,6 +393,15 @@ CREATE TABLE sensor_blobs (
|
||||
-- schema 0008 (2026-09-22) DROPPED them with the feature (19_SAFETY §What a finding does to the game). Sessions that
|
||||
-- ran under it keep "guard-bypass=" in capture_notes.
|
||||
series TEXT NOT NULL, -- cpu_temp|gpu_temp|gpu_hotspot|gpu_load|gpu_power|vram_proc|vram_adapter|cpu_load|ram_mb
|
||||
-- (vram_proc was listed here from 0001 and never written); since schema 0018 (beta.12,
|
||||
-- D43) also game_vram_dedicated|game_vram_shared|game_ram_private|game_ram_ws|game_commit,
|
||||
-- MiB — the game process's own memory (Application.Recording.SensorSeriesCatalog); since
|
||||
-- beta.14 (D49) also gpu_core_clock|gpu_mem_clock (MHz), gpu_fan (RPM), gpu_mem_temp (°C)
|
||||
-- and gpu_power_limit|gpu_thermal_limit (100 or 0 per tick, NVIDIA only) — a series name
|
||||
-- needs no migration
|
||||
-- since schema 0023 (2026-11-11, D102) also the ADVANCED series, every one under a name
|
||||
-- that starts with `adv.` (Application.Advanced.AdvancedMetricCatalog): NaN, not -1,
|
||||
-- for a tick with no reading, and read by FindAdvancedSensorsAsync only
|
||||
-- cpu_load / ram_mb / cpu_temp and sessions.avg_cpu_load, avg_cpu_temp, max_cpu_temp,
|
||||
-- avg_ram_mb were in schema 0001 with NO producer until 2026-09-21 (Telemetry.SystemTelemetrySource
|
||||
-- on the poller's tick). Rows before that date hold NULL, which is what they measured; no migration.
|
||||
@@ -346,11 +426,17 @@ CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
|
||||
CREATE TABLE legal_acceptance (doc TEXT PRIMARY KEY, version TEXT NOT NULL, accepted_at INTEGER NOT NULL);
|
||||
```
|
||||
|
||||
> **Written since 2026-09-14 (P3 PR-9).** `doc` is one of `eula` / `gpl` / `disclaimer` / `privacy`
|
||||
> **Written since 2026-09-14 (P3 PR-9).** `doc` is one of `eula` / `gpl` / `disclaimer` / `privacy` *(and `alpha` since
|
||||
> 2026-10-31, D74: the Alpha notice, written by an alpha build's gate only and read by an alpha's Agent before it serves;
|
||||
> a beta never reads that row)*
|
||||
> (`App.Services.LegalDocuments.Keys`); `version` is the document's own `**Version:**` line as embedded in the
|
||||
> App at build (`GPL-3.0-only` for the licence text) — the App is the only writer, one row per document per
|
||||
> Accept, re-recorded when the embedded version differs from the row's. `20_OPEN_QUESTIONS` §G "Legal doc
|
||||
> versioning" closes on that.
|
||||
>
|
||||
> **Three rows since beta.12 (D45).** The GPL is shown for information and needs no acceptance (GPLv3 §9), so Accept
|
||||
> writes `eula`, `disclaimer` and `privacy` only, and the gate is not held open for `gpl`. A `gpl` row an earlier
|
||||
> version wrote stays, unread (`LegalGate`).
|
||||
|
||||
## Settings registry
|
||||
|
||||
@@ -370,13 +456,21 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
|
||||
| `ui.minimize_to_tray` | bool | `0` | | UI (PR-8) |
|
||||
| `ui.hide_anticheat_hooking` | bool | `1` | | UI (beta.8, 2026-09-25): the game page of an entry the guard found anti-cheat in shows the finding in place of its Hooking card (`08_UI` §Game detail) |
|
||||
| `ui.fps_decimals` | bool | `0` | | UI (beta.8, 2026-09-25): every FPS figure with two decimals ("62.40") instead of a whole number |
|
||||
| `capture.background` | bool | `1` | | Agent |
|
||||
| `ui.hide_scrollbars` | bool | `0` | | UI (beta.14, 2026-10-05): no scroll bar drawn anywhere; every scroller still scrolls with the wheel, the keyboard and touch (`App.Services.ScrollBarHiding`, `08_UI` §Settings) |
|
||||
| `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) |
|
||||
| `ui.game_art` | bool | `1` | | UI (beta.23, owner decision D60): a game's page shows its artwork — the image the user chose, else what the Steam or GOG GALAXY app keeps on this PC; nothing is downloaded. Settings ▸ Games (`08_UI` §Games) |
|
||||
| `ui.game_art_tint` | bool | `1` | | UI (beta.23, owner decision D61): the page's header band takes the artwork's colour, at the strongest opacity that keeps its text readable. Settings ▸ Games |
|
||||
| `ui.play_mode` | choice `store`\|`direct` | `store` | | UI (beta.21, owner decision D59): what Play does — `store` hands the game to the app of the store whose own records name its folder, and the agent starts it where none does; `direct` has the agent start it (`LaunchGame`, launch mode). Settings ▸ Games (`08_UI` §Games) |
|
||||
| `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`. Since beta.21 the App can start a game (Play), and the key stays reserved: a game Play starts is recorded as any other start)* |
|
||||
| `hooking.kill_switch` | bool | `0` | | Agent (FR-2.4, since P2 PR-F) |
|
||||
| `hooking.usermode_ac_exceptions` | bool | `0` | | Agent, at every session start and command (FR-2.8, D33, 2026-09-26): off suspends every user-mode exception without deleting any; on, the user still grants each eligible game |
|
||||
| `capture.run_elevated` | bool | `0` | | The App when it starts the Agent, and an Agent the logon task started — both BEFORE the Agent exists, through `Infrastructure.Startup.RunElevatedSetting` (one row, `PRAGMA query_only`, no version gate, anything but `1` is off) (D34, beta.10): on, Windows is asked for administrator rights at every Agent start (`01_ARCHITECTURE` ADR-9) |
|
||||
| `capture.min_session_s` | int | `30` | 5–600 | Agent, per session (FR-3.6) |
|
||||
| `telemetry.interval_ms` | int | `1000` | 500–2000 | Agent, per session (FR-3.5) |
|
||||
| `telemetry.advanced` | bool | `0` | | Agent, per session (FR-5.6, owner decision D101, 2026-11-11): **Advanced metrics**. On, a session holds the Agent's shared reader and stores its `adv.*` series and its `session_advanced` row (schema 0023); off — and any row that is not exactly `1` — nothing more is read or stored, and a session recorded while off has no row. Settings ▸ Recording (`18_GPU_VENDOR_APIS` §The switch) |
|
||||
| `retention.raw_sessions_per_game` | int | `20` | 0–10000; **0 = unlimited** | Agent, per session (§Retention) |
|
||||
| `update.channel` | choice | `stable` | `stable` · `beta` | UI (P4 PR-5 reads it: `beta` = GitHub pre-releases too) |
|
||||
| `retention.remove_uninstalled_games` | bool | `1` | | Agent, at every detection sweep (beta.19, D55, FR-1.8): on, an entry whose executable has been gone for ten minutes — its drive connected, the folder it was installed in still there — and that has no session and no anti-cheat block or exception is removed; off, it stays and reads *Not installed* (D41's behaviour) |
|
||||
| `update.channel` | choice | ~~`stable`~~ `auto` (beta.14, D47) | `auto` · `stable` · `beta` | UI (P4 PR-5 reads it: `beta` = GitHub pre-releases too; `auto` follows the running copy, a pre-release asking for pre-releases — `11_UPDATER` §The update audit) |
|
||||
| `update.auto_check` | bool | `1` | | UI (P4 PR-5: the startup silent check, `11_UPDATER` §Flow "if enabled") |
|
||||
| `privacy.online_metadata` | bool | `0` | | *reserved* — no consumer and, since 2026-09-16, no toggle on Settings either: the store request it would enable has no code (CLAUDE.md rule 8), and PRIVACY_POLICY 2.2 removed the row that described it |
|
||||
| `log.debug` | bool | `0` | | UI |
|
||||
@@ -390,7 +484,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
|
||||
@@ -400,7 +494,19 @@ 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 advanced series are the exception, and say so by their name (schema 0023, owner decision D102).** A series
|
||||
> whose name starts with `adv.` stores **NaN** for a tick with no reading: a motherboard's −12 V rail is negative, so
|
||||
> −1 cannot mark a gap, and most of its ticks are gaps — the sensor library is read every fifth. They go through a
|
||||
> second encoder, `ISeriesCodec.EncodeSparseFloat32`, which allows NaN and still refuses an infinity; **the rule
|
||||
> above is not relaxed**: `EncodeFloat32` throws on a NaN as before, because a frame time has no gaps. Both decode
|
||||
> with `DecodeFloat32`. `ISessionRepository.FindSensorsAsync` — what every summary, chart and export reads — leaves
|
||||
> the `adv.` rows out (`series NOT LIKE 'adv.%'`), since those readers drop every negative value as "no reading";
|
||||
> `FindAdvancedSensorsAsync` returns them with `t_ms` first. One session stores at most 256 of them
|
||||
> (`AdvancedSessionBuilder.MaxSeries`); what is beyond is counted in its directory, not stored.
|
||||
> **Size, measured 2026-11-11** on values shaped like the dev box's reader (17 series with a reading every tick, 41
|
||||
> with one every fifth): one hour is 816 KiB raw and **189 KiB stored** — well inside NFR-5's 3 MB an hour.
|
||||
|
||||
## The `.partial` file
|
||||
|
||||
@@ -418,10 +524,21 @@ 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)* |
|
||||
> | 9 `SensorsAdvanced` | the advanced readings of the samples of the type-8 chunk before it (D101): `u16` names, then per name `u16` bytes and UTF-8; `u32` samples, then per sample `i64` QPC, `u16` readings and per reading `u16` name, `f64` value. Each chunk carries its own names, so it reads without any earlier chunk | each flush **in which a sample carries any** — with Advanced metrics off, never; the file is then byte for byte what it was (2026-11-11) |
|
||||
> | 10 `AdvancedContext` | UTF-8 JSON (`AdvancedJson.OfContext`): the PC's facts, the session's, its series' directory, each source's state; the last one wins | the first flush after the recorder set it, and again only when it changed (2026-11-11) |
|
||||
>
|
||||
> **A chunk of a type the reader does not know is skipped, not the end of the file (owner decision D106,
|
||||
> 2026-11-11).** Its length and checksum have been verified by then, so it is a whole chunk a newer build wrote.
|
||||
> Until that day `_ => false` ended the read there, and a build one release older lost everything after the first
|
||||
> new chunk — the price types 9 and 10 would have charged a beta.38 reading a beta.39 file. A chunk of a KNOWN type
|
||||
> that does not parse still ends the read: that is a torn or a wrong file, not a newer one.
|
||||
> (`PartialSessionFileAdvancedTests`: an unknown type between two known ones; the same with its checksum broken;
|
||||
> a kill at every byte offset of a file that holds both new types.)
|
||||
>
|
||||
> 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
|
||||
@@ -458,12 +575,17 @@ Default: raw blobs for the **last 20 sessions per game** (configurable N or unli
|
||||
|
||||
## Migrations
|
||||
|
||||
Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied at startup by whichever process opens the DB first, guarded by `schema_migrations` + a named mutex. Never edit an applied script; only append.
|
||||
> **The alpha's copy before it opens the ledger (D73, 2026-10-31).** An alpha build shares this file with the beta, so
|
||||
> before it first opens it — the App or the Agent, whichever comes first — `LedgerDatabase.OpenAsync(backupFirst:)`
|
||||
> copies it whole with SQLite's online backup into `backups\ledger-before-<version>.db` beside it
|
||||
> (`Infrastructure.Persistence.LedgerBackup`), once per alpha version, under a lock of its own
|
||||
> (`Local\FrameLedger.Ledger.Backup.<hash of the path>`, waited on for five minutes — the migration lock gives a waiter
|
||||
> 30 s). The newest three copies are kept and only files so named are deleted. A copy that cannot be made — no room, the
|
||||
> folder unwritable — throws `LedgerBackupException` and the ledger is not opened: the App says so in its start-failure
|
||||
> dialog, the Agent exits 7 (*ledger refused*) with the reason in its log. The main line passes no request and copies
|
||||
> nothing; a viewer (D52) reads a copy and makes none. Every case is `LedgerBackupTests`', in scratch folders.
|
||||
|
||||
> **`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.
|
||||
Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied at startup by whichever process opens the DB first, guarded by `schema_migrations` + a named mutex. Never edit an applied script; only append.
|
||||
|
||||
> **`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
|
||||
@@ -503,6 +625,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
|
||||
@@ -528,6 +655,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
|
||||
@@ -539,6 +671,126 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> the eligibility. The grant and the eligibility are each bound in SQL to the block they were reached about. `LatestVersion`
|
||||
> is 14; `LedgerDatabaseTests.ScriptFourteenAddsTheExceptionColumnsAndChangesNoRow`.
|
||||
|
||||
> **`0015_engine_version_source.sql` (beta.10, 2026-09-27) — where an engine version came from.** `games.engine_version_source`
|
||||
> (`05_DETECTION` §Engine version): the witness an Unreal version rests on, or the rule's extractor type for every other
|
||||
> engine; written by `ApplyDetectionAsync` only where the run's version was taken (a `user` field keeps none), cleared by a
|
||||
> user's edit of the version (`UpdateMetadataAsync`). The script's one data change removes the bare `4` / `5` the old
|
||||
> Unreal rule wrote (a two-group regex returning its first group) — **only where `field_provenance` says `detected`**: a
|
||||
> value the user typed, one with no badge (which reads as the user's) and one whose provenance does not parse stay as they
|
||||
> were, and the last does not fail the migration (`CASE WHEN json_valid(…)`, since SQLite promises no order for `AND`).
|
||||
> `LatestVersion` is 15; `LedgerDatabaseTests.ScriptFifteenAddsTheWitnessAndRemovesOnlyTheOldRulesDetectedDigit`.
|
||||
|
||||
> **`0016_display_mode.sql` (beta.10, 2026-09-27) — how the game was shown.** Fifteen `sessions.display_*` columns
|
||||
> (`03_METRICS` §Display mode): milliseconds in each mode, the changes, the witness, and the window / back buffer / monitor
|
||||
> sizes in the mode that lasted longest. ADD COLUMN only, no data change: a session recorded before reads N/A. Written by
|
||||
> the recorder on the row's skeleton (`Recording.SessionDisplayColumns.WithDisplay`), so a Tier-2 session — which never
|
||||
> reaches the aggregator — has them too; `sessions.swap_effect`, a column since 0001, gets its first writer from the same
|
||||
> facts. `SessionRowColumns` is hand-edited (its generator is not in the repository) and reads by name. `LatestVersion` is
|
||||
> 16; `LedgerDatabaseTests.ScriptSixteenAddsTheDisplayColumnsAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`.
|
||||
|
||||
> **`0017_exception_trial.sql` (beta.11, 2026-10-03, owner decision D38) — the exception's trial.** One column,
|
||||
> `games.ac_exception_trial_failed_at`: when an exception of the game ended during its trial (`19_SAFETY` §The user-mode
|
||||
> exception), NULL when none did. ADD COLUMN only, no data change: a grant made under D33 stays in force and carries no
|
||||
> mark. Written by the Agent's revoke only (`IGameConsentStore.RevokeAntiCheatExceptionAsync(…, trialFailed)`), set once
|
||||
> (`COALESCE`), cleared by nothing — not by `ChangeExecutableAsync`, which does not name it — and carried by a twin merge
|
||||
> (the earlier of two). The store applies it in SQL: no eligibility is written as eligible and no grant is written over
|
||||
> it. `ac_exception_sessions` (0014) changes meaning without a script: since D38 it is the trial's progress under the grant
|
||||
> in force, which the sweep rewrites on its first pass. `LatestVersion` is 17;
|
||||
> `LedgerDatabaseTests.ScriptSeventeenAddsTheTrialMarkAndChangesNoRow`,
|
||||
> `SqliteGameConsentStoreTests.AnEndDuringTheTrialMarksTheGameAndNothingClearsIt`,
|
||||
> `SqliteGameMergeTests.AFailedExceptionTrialOnEitherTwinMarksTheSurvivor`.
|
||||
|
||||
> **`0018_game_memory.sql` (beta.12, 2026-10-03, owner decision D43) — the game process's own memory.** Twelve
|
||||
> columns, ADD COLUMN only: `game_vram_dedicated_{avg,median,max}_mb`, `game_vram_shared_max_mb`,
|
||||
> `game_ram_private_{avg,median,max}_mb`, `game_ram_ws_max_mb`, `game_commit_max_mb`, `game_memory_processes`,
|
||||
> `game_memory_source` and `sensor_stats_json`. Written by the recorder's aggregation for both tiers
|
||||
> (`SessionAggregator.WithSensorAggregates`); a session before it reads N/A. **Not `vram_proc_*`**: those name the
|
||||
> in-process DXGI figure compared with a budget (a different quantity, `03_METRICS` §Game process memory) and stay
|
||||
> reserved. The `.partial` gains chunk type 8 (`SensorsWide`, a 32-bit mask with the game fields); type 4 is still read,
|
||||
> so a beta.11 crash file recovers. `LatestVersion` is 18; `LedgerDatabaseTests.ScriptEighteenAddsTheGameMemoryColumnsAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`,
|
||||
> `PartialSessionFileTests.TheGameMemoryRoundTripsAndANarrowSensorsChunkFromBeta11StillReads`.
|
||||
|
||||
> **`0019_pacing_sync_gpu_limits.sql` (beta.14, 2026-10-06, owner decision D49) — pacing, sync, the card, efficiency.**
|
||||
> Thirteen REAL columns, ADD COLUMN only: `time_below_{30,60,refresh}_pct`, `frametime_delta_mean_ms`,
|
||||
> `vsync_present_pct`, `tearing_allowed_pct`, `avg_gpu_{core,mem}_clock_mhz`, `avg_gpu_fan_rpm`, `max_gpu_mem_temp`,
|
||||
> `power_limit_pct`, `thermal_limit_pct`, `app_frames_per_joule`. Written by the recorder's aggregation
|
||||
> (`SessionAggregator.ApplyPacing` / `ApplySync` / `ApplyEfficiency` for a hooked session, `WithSensorAggregates` for the
|
||||
> card on both tiers); `sync_interval_mode` (0001) gets its first writer beside them. A session before it reads N/A — no
|
||||
> value is computed after the fact. The `.partial` needs no change: the six new sensor series are fields every sample
|
||||
> already carried. `LatestVersion` is 19; `LedgerDatabaseTests.ScriptNineteenAddsThePacingAndCardColumnsAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`. **A beta.13 cannot open a ledger beta.14 migrated.**
|
||||
|
||||
> **`0020_fg_mix.sql` (beta.24, 2026-10-19, owner decision D62) — every frame-generation state a session held.** One
|
||||
> TEXT column, ADD COLUMN only: `fg_mix`, `Application.Recording.FgMixRecord`'s JSON of `Domain.Metrics.FgMix` — each
|
||||
> state's pooled factor, its own Native and Displayed rates, its seconds, its share of the presenting time and its
|
||||
> five-second windows; then the time with no frame generation and the time no state claims (`03_METRICS` §The mix).
|
||||
> Written by the recorder's aggregation (`SessionAggregator.ApplyFg`, beside the steady state) for a hooked session whose
|
||||
> frame generation was named and whose count stood or was refused only as `non_uniform` / `ambiguous_band`; NULL
|
||||
> otherwise. A session before it has none and is **never rebuilt** from its `frame_blobs` (one Generated bit per frame,
|
||||
> the DXGI-counted presents lost). The `.partial` needs no change: a recovered session is aggregated from its records
|
||||
> like any other. **Read by today's rule since beta.26:** `FgMixRecord.Parse` folds a stored state no window of the build
|
||||
> would form (above ×8, or under eight application frames a window) into the not-classified time — beta.24 and beta.25
|
||||
> stored one (`spike-notes` §22). `LatestVersion` is 20; `LedgerDatabaseTests.ScriptTwentyAddsTheFgMixColumnAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`. **A beta.23 cannot open a ledger beta.24 migrated.**
|
||||
|
||||
> **`0021_runtime_module_sources.sql` (beta.24, 2026-10-19, owner decision D64) — where each loaded module lived.** One
|
||||
> TEXT column, ADD COLUMN only: `runtime_module_sources`, `{file: class}` beside `runtime_modules` — `game`,
|
||||
> `graphics_driver` (Windows' driver store or `%ProgramData%\NVIDIA`) or `windows`, from the path the module snapshot
|
||||
> read (`Application.Capture.RuntimeModuleSources`). The class is stored; **the path never is** (Privacy Policy 2.12).
|
||||
> Since the same release the snapshot also records every module under `%ProgramData%\NVIDIA\NGX` whatever its name.
|
||||
> Written by the recorder's aggregation (`SessionAggregator.ApplyWitnesses`); NULL before, and on a session recovered
|
||||
> from its crash file (which carries no module list). `LatestVersion` is 21;
|
||||
> `LedgerDatabaseTests.ScriptTwentyOneAddsTheModuleSourcesColumnAndAnEarlierSessionHasNone`, the repository round trip.
|
||||
|
||||
> **`0023_advanced_metrics.sql` (2026-11-11, owner decisions D101 and D102) — what Advanced metrics stores.** Two
|
||||
> tables and **no column on `sessions`** — the first `CREATE TABLE` since 0001. Every read of a `sessions` row, the
|
||||
> JSON export and the bug bundle carry the whole row, and a driver profile does not belong in a bug bundle.
|
||||
> `machine_profiles(id, hash UNIQUE, facts_json, captured_at)` holds the facts of the PC, one row per distinct set
|
||||
> (`hash` = SHA-256 of `facts_json`); it stands beside `hardware_snapshots`, not in it, because that table's hash
|
||||
> feeds the trend's hardware-change markers and a set of facts that exists only while an option is on would raise a
|
||||
> marker each time the option is switched. `session_advanced(session_id PRIMARY KEY → sessions ON DELETE CASCADE,
|
||||
> machine_profile_id → machine_profiles, facts_json, stats_json, series_json)` holds one row per session **recorded
|
||||
> with the option on**: its facts and each source's state, the statistics of its advanced series (the form of
|
||||
> `sensor_stats_json`), and the directory of the series that are members of a family. **A session recorded with the
|
||||
> option off has no row** — that absence is how the App says "the option was off when this was recorded" rather than
|
||||
> "nothing answered" — and is never given one. The JSON is `Application.Advanced.AdvancedJson`'s (camel case, nulls
|
||||
> left out, a status by its name); writing is strict, reading is tolerant, and **only a fact whose catalog entry is
|
||||
> read may be written** (`AdvancedJson.Storable`), so no identifier reaches either table (D104). **Since
|
||||
> 0.1.0-beta.40 (train B) the same row holds what the game told its upscaler** — the session facts of the entries
|
||||
> whose reach is `Game`, after the driver's, and `sources.inGame` (`Reading`, `NothingSeen`, `NotHooked`; absent in
|
||||
> a row beta.39 wrote, which reads as "not said") — and its two series are `adv.ffx.upscale.frame_time_delta` and
|
||||
> `adv.ffx.memory_usage` in `sensor_blobs`. **Since 0.1.0-beta.43** `sources` may also hold `streamlineConstants`
|
||||
> and `fsrFrameGeneration` (`Read`, `NeverCalled`, `NotHooked`; `Application.Advanced.AdvancedInGameCall`) — what
|
||||
> became, in that session, of the two calls hooked only for Advanced metrics; both absent in a row written before,
|
||||
> and in a session not measured inside the game. **Since 0.1.0-beta.44** also `streamlineFeatureVersion` and
|
||||
> `streamlineFeatureRequirements`, the same three values for the two questions a game asks Streamline about a
|
||||
> feature — where `NeverCalled` is the usual one, a game asking while it starts — and the facts
|
||||
> `sl.feature.versions` and `sl.feature.requirements`, rows named `<feature> · <member>` in the vendor's words.
|
||||
> **Since 0.1.0-beta.45** six more keys, the same three values each — `streamlineFeatureSupported`,
|
||||
> `streamlineFeatureLoaded`, `streamlineSetFeatureLoaded`, `streamlineAllocateResources`, `streamlineFreeResources`,
|
||||
> `streamlineShutdown`, absent in every row written before — and the facts `sl.feature.support` and
|
||||
> `sl.feature.lifecycle`, rows named `<feature> · <call>` (`slShutdown` alone for the shutdowns); a count that
|
||||
> reached its ceiling is the text `≥ 15`. No column and no script: schema 23 as it was. A session deleted
|
||||
> takes its row with it; a profile no session points to is left, as a hardware snapshot is; the retention sweep
|
||||
> removes a session's `adv.` series with its other raw series and keeps its row. Written by the Agent only, in the
|
||||
> session's own transaction (`SqliteSessionRepository.InsertAdvancedAsync`). `LatestVersion` is 23;
|
||||
> `LedgerDatabaseTests.ScriptTwentyThreeCreatesTheTwoAdvancedTablesAndAnEarlierSessionHasNoRow` (whose helper now
|
||||
> undoes a script's `CREATE TABLE` and `CREATE INDEX` as well as its `ADD COLUMN`), the repository's four cases.
|
||||
> **Nothing produces a row yet**: the option that switches the reader on is the next pull request's.
|
||||
> **A beta.38 cannot open a ledger a later build migrated.**
|
||||
|
||||
> **`0022_dlss_nr.sql` (beta.34, 2026-11-06, owner decision D84) — DLSS 5's neural rendering, measured.** One REAL column,
|
||||
> ADD COLUMN only: `dlss_nr_pct`, the share (0–100) of the presents that drained a Streamline evaluation on which the game
|
||||
> evaluated `kFeatureDLSS_NR` (`Domain.Metrics.NeuralRendering`). Written by the recorder's aggregation
|
||||
> (`SessionAggregator.ApplyRt`) **only when the writer published `FL_HOOK_SL_NEURAL_RENDERING`** — an Overlay older than
|
||||
> the script drains the same batches and never sets the bit, so its NULL is "could not tell", never 0. NULL before, and
|
||||
> never rebuilt (`frame_blobs` keep no feature byte); a session recovered from its crash file is re-aggregated from its
|
||||
> raw records and keeps it. `LatestVersion` is 22;
|
||||
> `LedgerDatabaseTests.ScriptTwentyTwoAddsTheNeuralRenderingColumnAndAnEarlierSessionHasNone`, the repository round trip.
|
||||
> **A beta.33 or alpha.2 cannot open a ledger beta.34 migrated** (the alpha keeps its copy first, D73).
|
||||
|
||||
> **Every open used to migrate, and one that should not have did — 2026-09-16.** The Agent's `--console sessions`,
|
||||
> a verb that prints, was run against the owner's ledger while the file on disk was at schema 2 and applied 0003 and
|
||||
> 0004 to it. `LedgerDatabase.OpenReadOnlyAsync` exists since that day: an existing file, `PRAGMA query_only`, no
|
||||
@@ -578,14 +830,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.
|
||||
+158
-16
@@ -1,24 +1,30 @@
|
||||
# 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>`)
|
||||
|
||||
Created by the Overlay on init, opened by the Agent. Name is deliberately plain and identifiable (`19_SAFETY` — no obfuscated object names).
|
||||
|
||||
Layout — **four regions, each exactly one 64-byte cache line before the ring**:
|
||||
Layout — **~~four~~ ~~five~~ six regions** (layout 4 since 2026-09-27, beta.10: region 4 is new and the ring moved
|
||||
from `0xC0` to `0x100`; **layout 5 since 2026-11-11**, Advanced metrics train B: region 5 is new — twenty-three cache
|
||||
lines, where the four before it are one each — and the ring moved from `0x100` to `0x6C0`):
|
||||
|
||||
```
|
||||
[0x0000] FlShmHandshake 64 B write-once by the Overlay at init
|
||||
[0x0040] FlWriterState 64 B Overlay-written (writeIndex touched every present)
|
||||
[0x0080] FlControlBlock 64 B Agent-written
|
||||
[0x00C0] FlFrameRecord[capacity] (64 B each, power-of-two capacity)
|
||||
[0x00C0] FlDisplayState 64 B Overlay-written, at most every 500 ms per chain (layout 4)
|
||||
[0x0100] FlAdvancedState 1472 B Overlay-written by its watchdog, once a second, only while the Agent asks (layout 5)
|
||||
[0x06C0] FlFrameRecord[capacity] (64 B each, power-of-two capacity)
|
||||
```
|
||||
|
||||
The header is split in two on purpose. The immutable handshake and the
|
||||
@@ -49,24 +55,133 @@ struct alignas(64) FlWriterState { // Overlay-written
|
||||
uint32_t rtStateObjectsCreated; // @32 session count, published at 1 Hz
|
||||
uint32_t rasterPsoCreated; // @36 session count, published at 1 Hz
|
||||
uint32_t runtimeCensus; // @40 FlRuntimeCensus bits; watchdog-published, OR-only (2026-09-03, took reserved[0])
|
||||
uint32_t reserved[5]; // @44..63 must be zero; reserved for additive fields
|
||||
uint32_t slTagCensus; // @44 FlSlTagType bits per route (2026-09-05)
|
||||
uint32_t dxgiPresentsUnseen; // @48 presents DXGI counted beyond the hooked ones (2026-09-05, saturating)
|
||||
uint32_t dxgiPresentSamples; // @52 hooked presents on which that counter was read
|
||||
uint16_t loaderSignals; // @56 the LoadLibrary detour's installed bit + wake count (2026-09-06)
|
||||
uint16_t earlyStopFamily; // @58 1-based floor family index of an early stop; 0 = none (2026-09-06)
|
||||
uint32_t dxgiPresentsBeforeHook; // @60 presents before the first hooked one (2026-09-06) -- the LAST word:
|
||||
// no slack left, so layout 4 added a region rather than a field
|
||||
};
|
||||
|
||||
> **This block showed `reserved[5]` at @44 until 2026-09-27** — five words the header had spent by 2026-09-06
|
||||
> (`slTagCensus`, the two DXGI counters, the loader words, `dxgiPresentsBeforeHook`). `fl_shm.h` is normative and the
|
||||
> mirror test reads the header, so nothing broke; a reader of this page was told there was room where there was none.
|
||||
|
||||
struct alignas(64) FlControlBlock { // Agent-written
|
||||
uint32_t pauseRequested; // @0
|
||||
uint32_t unhookRequested; // @4 19_SAFETY: set when the guard fires mid-session
|
||||
uint32_t overlayEnabled; // @8 in-game overlay draw toggle (v1.1)
|
||||
uint32_t guardTicks; // @12 completed guard evaluations, NOT a timer
|
||||
uint32_t logFlushRequested; // @16 a COUNTER: bumped by the Agent at session end; the watchdog flushes the native log on a change (17_HOOK_ENGINE §Native logging, 2026-09-06)
|
||||
uint32_t reserved[11]; // @20..63 must be zero
|
||||
uint32_t advancedRequested; // @20 0, or this session's request for Advanced metrics (D111): non-zero, new to this ring; written at attach, either way
|
||||
uint32_t reserved[10]; // @24..63 must be zero
|
||||
};
|
||||
|
||||
struct alignas(64) FlDisplayState { // Overlay-written (layout 4, 2026-09-27, beta.10)
|
||||
uint32_t seq; // @0 seqlock: odd while a writer is inside; the writer CASes and SKIPS if taken
|
||||
uint32_t flags; // @4 FlDisplayFlags: SAMPLED | EXCLUSIVE_KNOWN | EXCLUSIVE | OPENGL
|
||||
uint64_t hwnd; // @8 OutputWindow (DXGI) or WindowFromDC (OpenGL); 0 = a composition chain
|
||||
uint32_t bufferWidth; // @16 the back buffer (DXGI) / client area (OpenGL)
|
||||
uint32_t bufferHeight; // @20
|
||||
uint32_t swapEffect; // @24 DXGI_SWAP_EFFECT + 1 (DISCARD is 0); 0 = not read
|
||||
uint32_t swapFlags; // @28 DXGI_SWAP_CHAIN_DESC.Flags
|
||||
uint32_t chainId; // @32 the FlFrameRecord.swapchainId described
|
||||
uint32_t samples; // @36 samples published (wraps)
|
||||
uint64_t sampleQpc; // @40 QPC of the last sample
|
||||
uint32_t reserved[4]; // @48..63 must be zero
|
||||
};
|
||||
|
||||
static_assert(sizeof(FlShmHandshake) == 64);
|
||||
static_assert(sizeof(FlWriterState) == 64);
|
||||
static_assert(sizeof(FlControlBlock) == 64);
|
||||
static_assert(FL_SHM_RING_OFFSET == 0xC0 && FL_SHM_RING_OFFSET % 64 == 0);
|
||||
static_assert(sizeof(FlDisplayState) == 64);
|
||||
static_assert(sizeof(FlAdvancedState) == 1472); // region 5: fl_shm.h is its declaration, member by member
|
||||
static_assert(FL_SHM_DISPLAY_OFFSET == 0xC0 && FL_SHM_ADVANCED_OFFSET == 0x100 && FL_SHM_RING_OFFSET == 0x6C0 && FL_SHM_RING_OFFSET % 64 == 0);
|
||||
```
|
||||
|
||||
**Region 5 — what a hooked game told its upscaler (layout 5, 2026-11-11; Advanced metrics train B, owner decisions
|
||||
D111 and D113; written by the Overlay's watchdog since 0.1.0-beta.40).** `18_GPU_VENDOR_APIS` §Train B is the design.
|
||||
What the region is, as a contract between the two sides:
|
||||
|
||||
- **Off means nothing is read and nothing is written.** `FlControlBlock.advancedRequested` is the Agent's word that
|
||||
this session records Advanced metrics — written at attach, either way, because the control block outlives a session
|
||||
(`ShmRingReader.SetAdvancedRequested`). While it is 0 the Overlay reads no field and installs no hook beyond what
|
||||
it did before, and writes nothing here: a ring nobody ever asked is zero from end to end (`fl_guard` checks every
|
||||
byte, with a target that sends everything), and `validMask == 0` means "nothing was read", never "the game used
|
||||
none of it".
|
||||
- **"On" is a request, not a 1** *(2026-11-12)*. A game outlives a session, and so do the summaries the Overlay keeps
|
||||
inside it — a range, a count, a mask of what was ever seen. So the word is a value no session of this ring used
|
||||
before (above the word as it stands and above the request the region last answered; never 0), the watchdog starts
|
||||
its summaries afresh at a value it has not seen, and every publication names the request it answers
|
||||
(`FlAdvancedState.request`, the word that was `reserved0`). The reader returns only a publication that names the
|
||||
value it wrote: what a second session of the same game finds in the region before the first tick is the first
|
||||
session's, and is not read. After an "off" the region keeps its last publication, untouched.
|
||||
- **One writer, once a second.** The detours keep process-local accumulators; the watchdog copies them here at its
|
||||
tick. No game thread writes the region, so the seqlock has a single writer: `seq` odd, the fields, `seq` even.
|
||||
- **The reader keeps its last consistent copy** (`ShmRingReader.AdvancedState`): null until something was published
|
||||
for its request;
|
||||
the same copy while `seq` has not moved, without copying 1472 bytes again; and that copy still when the writer is
|
||||
inside on every attempt — a watchdog killed with its process leaves `seq` odd for good, and what it published
|
||||
before is still what the game said.
|
||||
- **Zero is "not read", never a value.** A Streamline `Boolean` and a DLSS preset are stored as the vendor's value
|
||||
plus one; a float as its bits, with `FL_ADV_FLOAT_NONE` for "none seen" — and, in `ffxNearBits` / `ffxFarBits` alone, `FL_ADV_FLOAT_INFINITE` (`0x7F800000`, +infinity's own bits) for a plane at infinity *(0.1.0-beta.42, owner decision D119: an engine with an infinite depth hands FSR `FLT_MAX` or +infinity for one plane; for Streamline `FLT_MAX` is "not set" and stays refused)* — the vendors' own sentinels are refused in
|
||||
the detour and never reach the region; a size of 0 is "not given".
|
||||
- **A per-frame value is summarised where it is seen**: a flag is an "ever seen" mask, a jitter the largest magnitude,
|
||||
a field of view its lowest and highest (D114), the reported frame time a count and a sum the watchdog drains.
|
||||
- **Sized once for the train's three releases.** The members ~~0.1.0-beta.41 and beta.42~~ ~~0.1.0-beta.42 and
|
||||
beta.43~~ 0.1.0-beta.43 and beta.44 fill *(renumbered twice on 2026-11-12 — D118: a fix release took beta.41;
|
||||
D122: the second step became two releases, and beta.42 fills none of them. The comments in `fl_shm.h` and
|
||||
`ShmLayout.cs` carry the new numbers since beta.42)* (`ffxFg*`,
|
||||
`sl*`, `features`) are declared now and stay zero until then, so those releases bump no layout. **The `sl*` group
|
||||
is filled since 0.1.0-beta.43** by the `slSetConstants` hook (`17_HOOK_ENGINE` §Hook inventory), under
|
||||
`FL_ADV_VALID_SL_CONSTANTS`: the call count of every viewport, and for the first viewport seen the resets, the
|
||||
jitter's largest magnitude, the motion-vector scale, the two depth planes, the field of view's range, the aspect
|
||||
ratio, and one bit per `Boolean` in each of two words — seen true, seen false. `FlHookFamily` gains
|
||||
`FL_HOOK_SL_CONSTANTS` (bit 13): the hook is in, which it is only in a process that was asked at least once.
|
||||
**The `ffxFg*` group is filled since the same release** by the `ffxConfigure` hook, under
|
||||
`FL_ADV_VALID_FFX_FG_CONFIG`: the frame-generation configures of the one module counted, three switches as "seen
|
||||
off / seen on" bit pairs (enabled, asynchronous, generated frames only), every flag any configure carried, and
|
||||
the last generation rectangle as left, top, width, height — **four `-1` for a rectangle with a negative side or
|
||||
one past 32,767**, never a clipped one. `FL_HOOK_FFX_CONFIGURE` (bit 14) is published when every ffx-api module
|
||||
the process loaded has its `ffxConfigure` patched.
|
||||
- **The feature slots are written since 0.1.0-beta.44**: `features` is twelve slots of twenty-four words — word 0
|
||||
the `sl::Feature` id plus one (0 is an empty slot), word 1 which of the two questions has an answer (bit 0 the
|
||||
version, bit 1 the requirements), then the two versions, the flags, three counts and four more versions, as
|
||||
`fl_shm.h` lays them out. Slots fill from 0 in the order the game first asked about each feature; **a new request
|
||||
does not empty them** — the one group that is a fact about the process and not about a session — and
|
||||
`FL_ADV_VALID_SL_FEATURES` stays set with them. `FL_HOOK_SL_FEATURE_VERSION` (bit 15) and
|
||||
`FL_HOOK_SL_FEATURE_REQUIREMENTS` (bit 16) are published with their patches, in a process that was asked.
|
||||
- **Word 1 of a slot carries more since 0.1.0-beta.45** (no layout change): bit 2 `slIsFeatureSupported` answered,
|
||||
with the `sl::Result` it gave in bits 8..15 (0 is `eOk`; a refusal is kept, it is the answer; `0xFF` a code a byte
|
||||
cannot carry); bit 3 `slIsFeatureLoaded` answered and bit 4 what it said; bit 5 the game switched the feature off
|
||||
through `slSetFeatureLoaded`, bit 6 on. **Bits 5 and 6 are a session's and a new request clears them**; every
|
||||
other bit of the word is a fact about the process and stays, as the slot does. A feature Streamline refused has
|
||||
a slot with only that word in it. `FL_HOOK_SL_FEATURE_SUPPORTED` (bit 17), `FL_HOOK_SL_FEATURE_LOADED` (18) and
|
||||
`FL_HOOK_SL_SET_FEATURE_LOADED` (19) are published with their patches.
|
||||
- **And two counts** (the same release): bits 16..19 of word 1 are how many times the game allocated the feature's
|
||||
resources (`slAllocateResources`), bits 20..23 how many times it freed them (`slFreeResources`) — each stops at
|
||||
15 — and `slShutdowns` (@308, taken from the three reserved words that ended the `sl::Constants` line; two remain)
|
||||
counts `slShutdown` calls, with `FL_ADV_VALID_SL_SHUTDOWN` (bit 6 of the mask) set once one was seen. All three
|
||||
are a session's and a new request clears them. `FL_HOOK_SL_ALLOCATE_RESOURCES` (bit 20),
|
||||
`FL_HOOK_SL_FREE_RESOURCES` (21) and `FL_HOOK_SL_SHUTDOWN` (22) are published with their patches.
|
||||
- The Vulkan layer never writes it. `ShmLayoutMirrorTests.TheAdvancedStateMirrorMatches` checks every member's
|
||||
offset against `fl-layout-dump`; `ShmRingReaderTests` the three reads and that the request is stored either way.
|
||||
|
||||
**Region 4 — the presenting swap chain's display facts (layout 4, 2026-09-27, beta.10).** The owner asked for the game's
|
||||
window size and display mode (exclusive fullscreen / borderless / windowed) and the share of a session each took. The two
|
||||
facts only the process knows — whether the chain is in exclusive fullscreen, and which window it presents to — are
|
||||
getters on the chain the title passed to the hooked Present (`GetFullscreenState`, `GetDesc`), asked at most every 500 ms
|
||||
per chain; everything else — the window's rectangle and style, its monitor, the classification — is the Agent's, read
|
||||
out of process with user32 at the drain tick, exactly as the foreground sample is (`03_METRICS` §Display mode). The
|
||||
region describes ONE chain: the largest back buffer, and a chain silent for 2 s gives way; `chainId` names it. It is a
|
||||
seqlock the writer never waits on — a writer that finds `seq` odd (another presenting thread inside) skips the sample and
|
||||
the next present retries — and `ShmRingReader.DisplayState` takes a copy between two reads of an even, unchanged `seq`
|
||||
(eight attempts, then null for that tick). The Vulkan layer never writes it (all zeros: nothing sampled); an OpenGL stream
|
||||
writes the window and client size with no exclusive bits, which a reader treats as *unknown*, never as *windowed*. A
|
||||
minimised game presents only `DXGI_PRESENT_TEST`, which the hook drops before sampling, so a `sampleQpc` older than 2 s
|
||||
leaves the exclusive bits unknown.
|
||||
|
||||
The cross-process fields are declared as plain integers and accessed through
|
||||
`std::atomic_ref` rather than as `std::atomic<T>` members. `std::atomic<T>` has
|
||||
no guaranteed layout, cannot be memcpy'd, and cannot be mirrored by a C#
|
||||
@@ -339,30 +454,35 @@ 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 */, ~~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.)* |
|
||||
| `LaunchGame` | UI→A *(the App sends it since beta.21: Play in its Start directly mode, and in the store mode where no store installed the game — `App.Services.GamePlayer`, D59)* | `{ 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) · `PackagedGame` (beta.33, D80: the executable's install root is a GDK package root — a game the Xbox app or the Microsoft Store installed, which Windows starts through its package and never by its path, `spike-notes` §25; nothing is started, and the App says to start it from the Xbox app or the Start menu. The App hands such a game to Windows itself and sends this only when it found no package record for it. Additive: an older App says the unknown outcome as a failure). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
|
||||
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). **Since D33 (2026-09-26):** for a blocked game whose user-mode exception is in force for the executable on disk (the option on, a grant made on these bytes, the block naming that family) the pre-scan NAMES the family, and a pass under it is stamped as ever and answered `prescan: "exception"`; a finding about the game under it also ends the exception. |
|
||||
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — a tolerant pre-scan of the executable on disk naming the block's family (`Refused { reason, family, signal }` unless the guard let exactly that family through) and the successful Tier-1 sessions (`Refused { reason: "TooFewSessions", signal: <count> }` under two) — and the store writes the grant only over facts that make the game eligible → `AntiCheatExceptionAck { granted, outcome, family }`. **A grant turns nothing on**: hooking is FR-2.1's `SetHookEnabled`, afterwards. Not answered (`UnknownType`) by an Agent composed without the exception. |
|
||||
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — ~~the successful Tier-1 sessions (`Refused { reason: "TooFewSessions", signal: <count> }` under two)~~ *(D38, 2026-10-03: no session is needed)*; a game an exception of which ended during its trial is refused before anything is scanned (`Refused { reason: "TrialFailed", family, signal: <unix ms> }`); a tolerant pre-scan of the executable on disk naming the block's family (`Refused { reason, family, signal }` unless the guard let exactly that family through) — and the store writes the grant only over facts that make the game eligible, and never over a failed trial → `AntiCheatExceptionAck { granted, outcome, family }`. **A grant turns nothing on**: hooking is FR-2.1's `SetHookEnabled`, afterwards. Not answered (`UnknownType`) by an Agent composed without the exception. |
|
||||
| `PauseCapture` / `ResumeCapture` | UI→A | global → `PauseAck { paused }`; `StatusAck.paused` reports it. *(Built 2026-09-13, PR-1b: one in-memory flag, `CapturePause`, read by every session loop at its tick and told to the ring once per transition; supervision — the guard scan, the kill switch, the safety stop — never pauses. Not persisted: an Agent that restarts resumes.)* |
|
||||
| `StopSession` | UI→A | `{ sessionGuid }` — graceful ~~unhook~~ stop + finalize → `StopAck { sessionGuid, accepted, reason? }`. *(Built 2026-09-13, PR-1b: the orchestrator names every session it starts and cancels THAT session's stop token; the loop reads it at its next tick, drains once more, and ends as `SessionEndReason.StoppedByUser` — `exit_status = normal`, the row stored like any other, the target left running. A guid nobody runs is `accepted: false`. Distinct from the host's cancellation, which leaves a `.partial`.)* |
|
||||
| `UpdateRules` | UI→A | **no payload** — a trigger, not a source. The Agent re-reads only its own `%LOCALAPPDATA%\FrameLedger\rules\` copy → `UpdateRulesAck { outcome }`. *(Built 2026-09-13, PR-1b: the seeder's `EnsureSeededAsync` outcome; a payload naming a path is ignored, and a test sends one to prove it.)* |
|
||||
| `Shutdown` | UI→A | graceful stop → `ShutdownAck`, then the host stops (sessions finalize inside its grace window). *(Built 2026-09-13, PR-1b: `IAgentLifetime`, the host's under `--serve`, a logged no-op under `--console`.)* |
|
||||
| `DeleteSessions` | UI→A | **Added 2026-10-03 (beta.11, D40).** `{ gameId? }` — every session of that game, or of every game when it is null, with their segments, frame and sensor series and annotations (they cascade) → `DeleteSessionsAck { gameId?, games, sessions }`. `Error SessionRunning` and nothing deleted while a session of that game — of any game, for all — is being recorded (`CaptureOrchestrator.IsRecording` / `IsRecordingAny`). The client names no rows beyond the game: they are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the App says as "restart the agent". Carries no safety fact. |
|
||||
| `SweepRetention` | UI→A | **no payload** — a trigger, like `UpdateRules`: the Agent applies `06_DATA_MODEL` §Retention to every game with the `retention.raw_sessions_per_game` it reads itself → `SweepRetentionAck { keep, games, sessions }` (`keep` 0 = unlimited, and then nothing was swept). *(Built 2026-09-15, P4 PR-7, for Tools ▸ Database maintenance: `Application.Recording.RetentionSweep` over `ISessionRepository.SweepRetentionAllAsync`, composed into `AgentCommandHandler` under `--serve`. The client names no number because the rows are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the dialog reads as "restart the Agent". Carries no safety fact.)* |
|
||||
| `GetAdvancedMachine` | UI→A | **Added 2026-11-11 (Advanced PR-6, owner decisions D101/D107).** `{ factsHash? }` → `AdvancedMachineAck { ready, takenAtUnixMs, factsHash?, factsJson?, readings[{ series, value }], series[{ series, metricId, label }], nvapi, nvapiCode?, sensors, elevatedSensors }` — what the Agent's shared advanced reader last read about this PC (`18_GPU_VENDOR_APIS` §The page's feed). **The handler reads no sensor**: the answer is the reader's last snapshot, one reference, because the pipe's read loop awaits its handler and a driver call there would hold up `Ping` and `StopSession`; the one thing it awaits is the option, a `settings` row asked for at most every two seconds. **A request is the page's hold on the reader**: the first acquires it and each renews a five-second lease, so the App asks once a second while the page is open and nothing has to say that it closed (`Application.Ipc.AdvancedMachineResponder`). `ready: false` — held, not yet read — carries nothing else. `readings` are that tick's only: a slow source is read every few ticks and the client keeps the last value it saw; a value that is not a number is left out. `factsJson` is the PC's facts as the ledger stores them (`AdvancedJson.OfFacts`), left out when the request's `factsHash` is the Agent's own. The three states are `AdvancedSourceStatus` names; a name a client does not know reads as unknown. `Error AdvancedOff` while `telemetry.advanced` is off — nothing is read, and a hold a previous request took is let go at once. Additive, protocol 2: an older Agent answers `Error UnknownType`, which the page shows as such. Carries no safety fact and changes nothing. |
|
||||
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt, hold? }` — **published once per session**: at the attach (tier 1, `startedAt` the attach), or — **since 2026-09-23** — at the first tick of a session held unhooked (tier 2, `startedAt` the session's start, `pid` 0 when the loop never opened the process, as a hooking-off hold never does). ~~a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2)~~ — that was the beta.5 wire, and every hooking-off, refused or unreadable game read "Nothing is being captured." for as long as it ran. **`hold` (optional, tier 2 only)** is why nothing is measured: `{ reason, guardReason?, family?, signal?, hookingTurnedOff }` — the loop's `SessionEndReason` and, when the guard said anything but allow, its reason, family and signal: the same words the row's `capture_notes` will carry, so the live card and the summary read one sentence (`Formats.Tier2HoldReason` / `Tier2Reason`). The refusal's own event (`CaptureRefused` and the rest, below) goes out with this start rather than when the game exits, and is not repeated at the end |
|
||||
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct? }` — how long it has run and the machine's sensors. **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
|
||||
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus? }` — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
|
||||
| `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). **`upscalerQualityOverride` added 2026-10-19 (beta.24, D63), optional:** the mode an NVIDIA App override set when the driver reports it applied in the target and DLSS super resolution ran there — `performance`, `balanced`, `quality`, `ultra_performance`, `ultra_quality`, `dlaa`, or `override` when the driver's report alone does not settle the mode (the profile is the stored session's); absent otherwise. **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
|
||||
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
|
||||
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
|
||||
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
|
||||
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, 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.)* |
|
||||
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff, guardReason? }` — **`guardReason` (beta.13, optional)** is the guard's own reason ~~when it named a family~~ **whenever it refused (beta.18; beside a family only until then)**: `BlockedService` / `BlockedDriver` is a finding on the PC, not in the game, and the notice says so (§S23-3), and a refusal no family names is said in the guard's words (`Formats.GuardSentence`) — it printed the end's name, "reason RefusedByGuard"; `reason` stays the session's end reason — **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. *(Since beta.18 it says the end in words, `Formats.EndReasonText`; it printed `reason` raw — "The hook stopped (WriterSelfDisabled); the session continues without measuring" — and a stop ends the session, it does not continue it.)* *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
|
||||
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff, guardReason? }` — `guardReason` as on `CaptureRefused` (beta.13) — 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.)* |
|
||||
| `GameRemoved` | A→UI | `{ gameId, gameName?, exePath, reason }` — **since beta.19 (D55):** the Agent removed a library entry by itself; `reason` is `uninstalled` (its executable gone for ten minutes from a folder that is still there, no session, no anti-cheat block or exception — `06_DATA_MODEL` §Writer ownership). Not a session event. The Games page on screen reloads and says so; a game page showing that entry reloads into its not-found state. Additive: a client that does not know the type ignores it (§Versioning). |
|
||||
| `HookingTurnedOff` | A→UI | `{ gameId, gameName?, reason, family?, signal? }` — **since 2026-09-25 (beta.8):** the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) found anti-cheat in a game whose hooking the user had turned on, and turned it off. Not a session event — no session is running — so the UI's notice carries no "record without measuring" action, only Dismiss (`SafetyNoticeKind.HookingOff`). A finding on a game whose hooking was already off sends nothing: its page and its library card change, nothing the user switched on did. Additive: a client that does not know the type ignores it (§Versioning). |
|
||||
| `CaptureError` | A→UI | `{ sessionGuid?, code, message }` — `InjectFailed`, `RingVersionMismatch`, `AttachRefused`, ~~`EtwAccessDenied`~~ (struck 2026-09-13 with the tier), ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed`, `SessionFaulted` (the session's task threw before finalize; the `.partial` stays for recovery, and ~~no `SessionCompleted` follows~~ a `SessionCompleted` with `finalize: faulted` follows since 2026-09-23). *(Built: `RingVersionMismatch` for a layout / record-size / build-id refusal — the "restart the game after an update" case — `AttachRefused` for the rest of the ring's refusals, `InjectFailed` for a target that could not be started, pinned, read or singled out.)* |
|
||||
| `Ping`/`Pong` | ~~both~~ UI→A | 15 s keepalive, **client-driven** (built 2026-09-13): the client pings, the Agent answers; the Agent initiates nothing on an idle connection |
|
||||
@@ -412,7 +532,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
|
||||
@@ -421,7 +541,29 @@ message, and that message always re-scans.
|
||||
> before this the reason was swallowed, and a refusal looked exactly like an absent Agent). The Agent it does start
|
||||
> is watched until it exits and its exit code logged, so exit 10 — the folder was already claimed — is visible in
|
||||
> the App's log. `AgentConnectionTests` pins both.
|
||||
> **Amended 2026-09-27 (beta.10, the admin mode, D34): a start may ask Windows first.** With `capture.run_elevated` on
|
||||
> and this App a standard user's, the start is a UAC prompt owned by the App's window (`IAgentLauncher.WillAskForElevation`
|
||||
> turns the pill into *Waiting for administrator permission*), and while it is up the folder's `ElevationMarker`
|
||||
> (`Local\FrameLedger.Agent.Elevating.<hash>`) is held — `RunningAgent` reads it as "an Agent is coming", so the App never
|
||||
> prompts beside the logon task's Agent, which holds the same marker while its own prompt waits on the taskbar. A declined
|
||||
> prompt starts the standard user's Agent with `--elevation declined`; an elevated Agent that exits 11 (another account
|
||||
> answered) makes the App start standard-user Agents until it restarts.
|
||||
- **Named objects an elevated process creates state their DACL (beta.10).** An elevated token's default DACL grants
|
||||
Administrators and SYSTEM and not the user, so an object an elevated Agent creates with it cannot be opened by the same
|
||||
user's unelevated App or game: the pipe (`PipeAccessControl`), the tolerance mapping (§D) and — since beta.10 — the
|
||||
ledger's migration lock (`Infrastructure.Startup.SharedMutex`: owner the user, full access to the user, Administrators
|
||||
and SYSTEM) each carry an explicit descriptor. The instance lock and the elevation marker are only ever probed, and a
|
||||
probe that is refused reads as "held".
|
||||
- Treat the pipe as unreliable: library, history and charts must all work with the Agent offline. Only live status degrades.
|
||||
- **A request the Agent never answered is neither a failure nor a refusal (beta.22).** `IAgentRequests.RequestAsync` fails
|
||||
in one of four ways: `InvalidOperationException` — not connected, nothing was sent; `IpcRequestException` — the Agent
|
||||
answered `Error`; `TimeoutException`; and `IOException` — the connection closed before the answer, whatever closed it
|
||||
(`AgentConnection.AnsweredAsync` turns the `IpcFramingException` and `ObjectDisposedException` that `PipeClient` can fail a
|
||||
request in flight with into it, so a caller handles one). The last two mean *whether it was carried out is not known*
|
||||
(`AgentAnswers.IsUnanswered`): the caller says so in words (`Agent_Unanswered`) and reads what is stored again — deleting
|
||||
sessions, the hooking switch, the anti-cheat exception and Play alike. Until beta.22 deleting sessions caught no
|
||||
`IOException` (the App's crash dialog) and showed a timeout's own message, and the hooking switch and the exception
|
||||
showed `IOException` or `TimeoutException` as their notice.
|
||||
- SQLite is the source of truth for anything persisted; pipe events are refresh signals (except `SessionProgress`, which is live-only by design).
|
||||
- `CaptureRefused`, `SafetyUnhook` and (since 2026-09-25) `HookingTurnedOff` are **never** collapsed into a generic error toast — they get dedicated, explanatory UI (`08_UI` §Notifications).
|
||||
|
||||
|
||||
+809
-62
File diff suppressed because it is too large.
Load diff
+22
-4
@@ -2,6 +2,9 @@
|
||||
|
||||
Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as the rest of the poli0981 portfolio.
|
||||
|
||||
> **The user guide is English (beta.12, owner decision D44)**, like the legal documents: `guide/` is Markdown the App
|
||||
> embeds and renders, not `.resx` text. The UI around it — the menu item, the window's title — is translated.
|
||||
|
||||
> **Both string families are given the UI culture explicitly (2026-09-21).** `App.ApplyCulture` sets `Strings.Culture`
|
||||
> AND `FrameLedger.Shared.Strings.Culture`. The second was missing: the safety family fell back to the thread's
|
||||
> `CurrentUICulture`, and a culture set inside the App's async start flows with that async context, not to the
|
||||
@@ -11,10 +14,20 @@ 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.
|
||||
**The new window opens on the page that was on screen** *(beta.34, owner request 2026-11-06)* — Settings, after a
|
||||
change made there. `ShellHost` remembered only the pages opened from code (`PageNavigator`), never a click in the
|
||||
pane, so a language changed on Settings brought back the last game page opened; it now notes every page the live
|
||||
window's NavigationView shows (`ShellHost.NoteShown`).
|
||||
**Two kinds of text did not follow, until beta.15:** a list of choices built once in a static (Settings' themes and update
|
||||
channels, the Logs page's two lists, the Games page's sort order — `x:Static` read the list built in the language the
|
||||
App started in), and the singletons that outlive the rebuilt window (the tray's menu, the title bar's Agent pill and the
|
||||
update banner). The lists are per page now, bound through the view model; the singletons implement
|
||||
`ILanguageFollower`, which `ShellHost.Rebuild` calls once the new window is up. `LanguageFollowingTests` refuses a new
|
||||
static list of labelled choices — the language list, each language in its own words, is the one exception.
|
||||
- `SatelliteResourceLanguages` = `en;vi;ja` in ~~the App csproj~~ `Directory.Build.props` (corrected 2026-10-04) to keep publish size down.
|
||||
|
||||
## Key conventions
|
||||
|
||||
@@ -31,7 +44,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)
|
||||
@@ -52,6 +65,11 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
| Anti-cheat | Anti-cheat (giữ nguyên) | アンチチート |
|
||||
| Capture tier | Mức thu thập | 計測ティア |
|
||||
| Measured / Supports | Đo được / Hỗ trợ | 実測 / 対応 |
|
||||
| VRAM / RAM (beta.12) | VRAM / RAM (giữ nguyên) | VRAM / RAM |
|
||||
| Dedicated / Shared GPU memory | Bộ nhớ GPU chuyên dụng / dùng chung | 専用 / 共有 GPU メモリ |
|
||||
| Private working set / Working set / Commit | giữ nguyên | プライベート ワーキング セット / ワーキング セット / コミット |
|
||||
| this game / whole graphics card / whole PC | game này / cả card đồ họa / cả máy | このゲーム / グラフィックス カード全体 / PC 全体 |
|
||||
| Median / Mean / Peak | Trung vị / Trung bình / Đỉnh | 中央値 / 平均 / ピーク |
|
||||
|
||||
Technical benchmark vocabulary stays in English across all locales where the community convention is English (1% Low, stutter, present mode, frame pacing).
|
||||
|
||||
|
||||
@@ -3,9 +3,19 @@
|
||||
## Serilog configuration
|
||||
|
||||
- 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.)*
|
||||
- *(beta.15, D52: an App started with `--data-dir <copy>` — a viewer — writes `ui-.log` and its crash dumps under the
|
||||
copy, never under `%LOCALAPPDATA%\FrameLedger`; its first lines name the folder and say it is a viewer.)*
|
||||
- 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.
|
||||
|
||||
@@ -54,6 +64,16 @@
|
||||
> and never the Agent's usage code 1. The catch exists because an exception escaping `Main` runs `Main`'s `finally`
|
||||
> first, which closes the logger; the AppDomain handler alone would dump with no Fatal line.
|
||||
>
|
||||
> **A background service that fails, since 0.1.0-beta.37 (.NET 11, D94).** `--serve` awaits the Generic Host's
|
||||
> `RunAsync` and catches nothing. On .NET 10 a `BackgroundService` whose `ExecuteAsync` threw stopped the host and
|
||||
> `RunAsync` completed, so the Agent exited 0 with the fault in the log alone (the host's own line, in `agent-*.log`
|
||||
> since 2026-09-23). On .NET 11 `RunAsync` rethrows that exception — an `AggregateException` when several services
|
||||
> failed — so it reaches `Main`'s catch above: Fatal, the dump, and the runtime's exit code. Nothing was changed to get
|
||||
> this and nothing wraps it: an Agent that stopped because a piece of it broke should not report success. The App
|
||||
> hosts with `StartAsync` and `StopAsync` inside its own try/catch and is not affected. `HostBackgroundFailureTests`
|
||||
> holds the runtime's behaviour — a host with one throwing service fails `RunAsync` with that exception; the three
|
||||
> alphas shipped with it unobserved (`spike-notes` §24).
|
||||
>
|
||||
> Tests: `CrashDumpWriterTests` (a real dump of the test process starts `MDMP` and carries the UTC time in its name; the
|
||||
> prune keeps five and touches no other file; an unusable directory is null and one line), `CrashReporterTests` (the
|
||||
> order, no report on No, three further exceptions show nothing and are counted, a failed dump still asks, a failed
|
||||
@@ -73,7 +93,7 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
|
||||
2. **Bundle builder** creates `FrameLedger-bugreport-YYYYMMDD-HHmm.zip` in a user-chosen location:
|
||||
- `logs/` (last 7 days, redacted copies)
|
||||
- `sysinfo.json` (app + agent + **overlay build id**, OS build, CPU/GPU name, driver version, telemetry source, Vulkan layer state, PawnIO present?, elevation state, locale)
|
||||
- `overlay-<pid>-*.log` for the last hooked sessions, plus hook fault details and the ring's dropped/fault counters — these are what make injection bugs diagnosable at all. *(The file exists since 2026-09-06 — `17_HOOK_ENGINE` §Native logging: written at init, on the Agent's request at session end, and on the stop; `FAULT` lines carry the exception code and the hook's name, `UNHOOK_*` lines say per patch whether it was restored or left to a later hooker.)*
|
||||
- `overlay-<pid>-*.log` for the last hooked sessions, plus hook fault details and the ring's dropped/fault counters — these are what make injection bugs diagnosable at all. *(The file exists since 2026-09-06 — `17_HOOK_ENGINE` §Native logging: written at init, on the Agent's request at session end, and on the stop — and since 0.1.0-beta.42 by the Overlay's watchdog whenever something new was logged, so it is whole after a game that simply exits, with each install named by module and symbol and each descriptor type an ffx module was handed; `FAULT` lines carry the exception code and the hook's name, `UNHOOK_*` lines say per patch whether it was restored or left to a later hooker.)*
|
||||
- `settings.json` (sanitized — no paths)
|
||||
- optional checkbox: last session metadata + aggregates JSON (never raw blobs by default)
|
||||
- crash dumps included only when the user ticks the checkbox (size warning shown)
|
||||
@@ -151,7 +171,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 +182,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
|
||||
|
||||
+86
-12
@@ -1,14 +1,17 @@
|
||||
# 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.)* *(Corrected 2026-10-05: the default is `auto` since beta.14, which follows the running copy — §The update audit, beta.14.)* *(2026-10-31, D73: an **alpha line** beside them, on Velopack's `alpha` channel — §Built, Channels.)*
|
||||
|
||||
## Flow
|
||||
|
||||
- **Startup silent check** (if enabled): `UpdateManager.CheckForUpdatesAsync()` 5 s after UI idle. Offline/any failure → log `Information`, no dialog (NFR-10). Update found → non-blocking toast "Update vX.Y.Z available" → Downloads in background → "Restart to update" button (never auto-restart; the user may be mid-capture — if a capture is active, defer the prompt until session end).
|
||||
- **Manual check** (Help → Check for updates): progress dialog; all failures produce the mapped dialog below.
|
||||
- **A viewer never updates** (beta.15, D52): an App started with `--data-dir <copy>` registers neither Velopack nor the
|
||||
startup check (`Services.MachineFacingServices` gives it `ViewerUpdateClient`, which answers "not installed"), and
|
||||
Help → Check for updates and the automatic-check switch are disabled — an update replaces this PC's installed copy.
|
||||
- **Never apply an update while a game is hooked** (FR-12): the Overlay DLL on disk must not change under a running game, and a mid-session swap would invalidate the ring layout handshake. If a capture is active, defer the prompt and the apply until the session ends.
|
||||
- Apply: `WaitExitThenApplyUpdates` on restart. Agent is stopped via `Shutdown` before applying and the scheduled task action path is re-validated after update (Velopack keeps a stable `current` path, but verify in P4 and re-register task if the action path changed).
|
||||
- Release notes (GitHub release body, Markdown) rendered in the update dialog.
|
||||
- Release notes (GitHub release body, Markdown) rendered in the update dialog. ~~(shown as plain text until beta.12 — §Flow and §Limits below said so)~~ **Rendered since beta.12** by `Controls/MarkdownView` (`08_UI` §Menu, *Documents are rendered*), relative links resolved against `CHANGELOG.md` at this build's source.
|
||||
|
||||
## Error mapping (FR-12)
|
||||
|
||||
@@ -21,7 +24,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,17 +32,27 @@ 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.)* **Built in beta.13:**
|
||||
`release.yml` downloads the previous release into `out/release` before `vpk pack`, so a release carries
|
||||
`FrameLedger.App-<version>-delta.nupkg` beside the full package; the previous full package is moved out (neither uploaded
|
||||
nor checksummed) and the feed lists this build alone, as `vpk upload github` would write it. Velopack applies the delta
|
||||
when the installed copy is the previous release and falls back to the full package otherwise — `0.1.0-beta.13` is the
|
||||
first release with one, so beta.12 → beta.13 is the first update that can use it (owner-only: HANDOFF item 10).
|
||||
- Never bypass or suppress OS warnings programmatically.
|
||||
|
||||
## Versioning
|
||||
|
||||
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~~ 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`.
|
||||
|
||||
## Built 2026-09-14 (P4 PR-5) — what exists, and where it deviates from the above
|
||||
|
||||
`src/FrameLedger.App/Update/`. Velopack 1.2.0 (`Directory.Packages.props`, pinned since P0, referenced since
|
||||
this PR) behind the `IUpdateClient` port — `VelopackUpdateClient` is the one implementation, `UpdateService` the
|
||||
this PR; **1.2.161 since beta.30**, owner decision D71 — the library and `vpk` together) behind the `IUpdateClient` port — `VelopackUpdateClient` is the one implementation, `UpdateService` the
|
||||
flow, and the tests run the flow over a fake client because nothing here may touch the network in a test.
|
||||
|
||||
- **Startup silent check:** `UpdateHostedService`, 5 s after the host starts (the "5 s after UI idle" above —
|
||||
@@ -50,8 +63,8 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
window is off screen (`08_UI` §Notifications policy), and the shell's persistent InfoBar carries the download
|
||||
and the **Restart to update** button.
|
||||
- **Manual check:** Help ▸ Check for updates → `UpdateService.CheckInteractivelyAsync` and the dialogs in
|
||||
`UpdatePrompts` (WPF-UI `MessageBox`): the offer with the release notes (the GitHub release body, shown as text —
|
||||
no Markdown renderer is shipped), the unsigned-release footer, Download / Later; "up to date"; "not an
|
||||
`UpdatePrompts` (WPF-UI `MessageBox`): the offer with the release notes (the GitHub release body, ~~shown as text —
|
||||
no Markdown renderer is shipped~~ rendered since beta.12, at most 260 px tall and scrolling), the unsigned-release footer, Download / Later; "up to date"; "not an
|
||||
installed copy"; and the error table below. There is no progress *dialog*: progress is the banner's percent. A
|
||||
package that fails its checksum is downloaded once more before the Corrupt row is shown (the table's "auto-retry
|
||||
once").
|
||||
@@ -66,14 +79,28 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
connect SEEDS the running set rather than being OR-ed with it forever — before, a session running when the App
|
||||
connected held every download at `Deferred` until the next reconnect, hours after it ended.
|
||||
- **Apply:** `Shutdown` to the Agent over the pipe, the connection's relaunch held (`IAgentLink.SetLaunchHold`),
|
||||
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so),
|
||||
the pipe watched until it drops (10 s; an Agent that does not stop leaves everything as it was and says so) —
|
||||
**and since beta.10 the data folder's instance lock watched until it is let go, within the same 10 s**: an Agent run as
|
||||
administrator (the admin mode) holds the install directory's files exactly as long as its process lives, and one that
|
||||
holds the folder without answering this App (still starting, another version) is never updated under — the apply is
|
||||
refused with `Update_AgentStillRunning` instead,
|
||||
then `WaitExitThenApplyUpdates(asset, silent: false, restart: true)` and the host ends. The restarted App
|
||||
starts the Agent beside itself as always, and when Velopack reports the restart (`OnRestarted`) the host reads
|
||||
the logon task: `Stale` (the action path moved) runs `--install-task`, this user's own task, and says so in the
|
||||
log — the "re-validated after update" above. Velopack keeps `current` stable, so `Installed` is the expectation.
|
||||
- **Channels:** `stable` = releases GitHub does not mark pre-release; `beta` = those too (`GithubSource(prerelease)`).
|
||||
Not Velopack's own `--channel` mechanism — one package set per tag, the GitHub flag decides. `13_CI_CD` §Branch &
|
||||
release policy.
|
||||
release policy. *(Corrected 2026-10-31, D73: true of the main line, whose packages are on Velopack's default `win`
|
||||
channel. **The alpha line uses Velopack's channels**: an alpha is packed with `--channel alpha`, so its feed is
|
||||
`releases.alpha.json`, and an installed copy reads only its own channel's feed — `VelopackUpdateClient` passes no
|
||||
`ExplicitChannel`, so the channel is the one the installed package was built for (its `sq.version` names it). Velopack's
|
||||
`GithubSource` merges the assets of every release that carries that feed, so a beta never sees an alpha and an alpha
|
||||
never sees a beta, under either setting of `update.channel` — and in an alpha build that picker is locked, its line
|
||||
saying so (`08_UI` §Settings). **One limit follows from the source, read from Velopack's code 2026-10-31:** it asks
|
||||
GitHub for one page of ten releases, newest first, so ten releases of one line in a row would hide the other line's
|
||||
newest from its update check. The cadence is one alpha per beta (`13_CI_CD` §The alpha line) — *while the line tries a .NET; it rests since 0.1.0-alpha.4 (D98, 2026-11-11), betas then follow one another with no alpha between, and once ten of them have been published after alpha.4 a copy of alpha.3 or older no longer finds it: the alpha's notes, the guide and its banner say to install the beta.* Moving between the lines
|
||||
is a deliberate install, never an update: the other line's `Setup.exe` over the installed copy, which Velopack answers
|
||||
with its overwrite prompt — the packId, the install folder and the data folder are the same.)*
|
||||
- **Hooks** (`VelopackHooks`, in the hand-written `Program.Main` so `VelopackApp.Run()` precedes any window):
|
||||
install registers nothing; uninstall = `UninstallHook` (`12_BUILD` §Publish & package). `Run()` in a copy the
|
||||
installer did not lay down returns at once and runs no hook (probed on 1.2.0); it does append a line to Velopack's
|
||||
@@ -95,8 +122,55 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
empty token — measured on 1.2.0 by reflection, so the request identifies the product and nothing else. When the rules fetch is built
|
||||
(`05_DETECTION` FR-7.3, `20_OPEN_QUESTIONS` §S20 feed half) it needs a client of its own; this paragraph no
|
||||
longer claims the updater provides one.
|
||||
- Release notes are rendered as plain text, not Markdown.
|
||||
- ~~Release notes are rendered as plain text, not Markdown.~~ Corrected 2026-10-03: rendered since beta.12 (Markdig; HTML off, no image fetched).
|
||||
|
||||
## The update audit, beta.14 (owner request 2026-10-05: "check the update logic")
|
||||
|
||||
No failure had been reported; the audit read the flow above against Velopack 1.2.0 and the owner's own updater log
|
||||
(`%LOCALAPPDATA%\velopack\velopack_FrameLedger.App.log`, read-only) and found two defects that made the flow above
|
||||
partly fiction, and six smaller ones. Each is fixed in place:
|
||||
|
||||
- **A copy left on its defaults never found an update.** `update.channel` defaulted to `stable` while every release is a
|
||||
GitHub pre-release; the owner's log reads "No releases found" from the day their ledger (and its settings row) was reset.
|
||||
**Owner decision D47:** the default is `auto`, which follows the running copy — a pre-release asks for pre-releases, a
|
||||
release for releases (`Update/UpdateChannelPolicy`, SemVer's `-` before any `+`) — and a stored `stable` or `beta` is the
|
||||
user's choice and wins. Settings shows *Automatic (Beta)* or *(Stable)* first. Only an explicit selection ever wrote the
|
||||
row (`SettingsViewModel.Persist` is guarded while loading), so existing copies with no row move to `auto`.
|
||||
- **Velopack applied a downloaded update at the next start, behind FR-12.** `VelopackApp` applies a package waiting in
|
||||
the install folder on startup unless told not to (`SetAutoApplyOnStartup`, ON by default), and the startup check
|
||||
downloads in the background — so the next start of `FrameLedger.exe` (the Start menu, the logon Run value, a second
|
||||
click, `--diag`) applied it inside `VelopackApp.Run()`, before the single-instance claim, before FR-12 could ask
|
||||
whether a session runs, and before the Agent was asked to stop; its updater killed the Agent instead (the owner's log:
|
||||
"Auto apply is true, so restarting to apply update…", then "Killing process: …FrameLedger.Agent.exe"). Off now
|
||||
(`VelopackHooks`, pinned by `VelopackHooksTests` through the builder's private fields); a package an earlier run left
|
||||
is adopted at start — `UpdateService.AdoptPending`, from `UpdateManager.UpdatePendingRestart`, no feed request — and is
|
||||
Ready or Deferred like any other.
|
||||
- **An update Velopack starts itself** (the installer run over an installed copy) asks the Agent to stop first, as the
|
||||
uninstaller does (`OnBeforeUpdateFastCallback`, 15 s budget, a line in `logs\update.log`). The hook runs in the
|
||||
version being replaced, so it first works for the update after beta.14.
|
||||
- **The apply waits while a game still has the Overlay loaded** from the install folder (`Update/PayloadInUse`: a mapped
|
||||
image refuses an exclusive write — a file-system question, no process opened). The Overlay is never unloaded from a
|
||||
live game (`17_HOOK_ENGINE`), so after a mid-game stop the swap would fail half way after the App had quit. Asked before
|
||||
the Agent is stopped; the strip names the file.
|
||||
- **An Agent waiting on the administrator prompt** (the logon task's, the admin mode) holds only its elevation marker, not
|
||||
the instance lock; the apply now waits for either (`UpdateService.AgentHolds`).
|
||||
- **The stop budget is the Agent's own shutdown grace and five seconds** (`IpcProtocol.AgentShutdownGrace`, 15 s, which
|
||||
the Agent's host now reads too): the App waited 10 s for an Agent that took up to 15 to finalize its sessions.
|
||||
- **The offer says the download Velopack will make:** the deltas from the installed version when the feed has them
|
||||
(`UpdateInfo.DeltasToTarget`; 1.6 MB for beta.12 → beta.13) and the full package as the fallback — it said ~102 MB.
|
||||
Velopack's own lines are in the App's log since beta.14 (`velopack: …`, `VelopackSerilogLogger`), so whether a delta
|
||||
or the full package came is in the bug report too.
|
||||
- **Smaller:** an `IOException` is "offline" only from the network (`HttpIOException`, a socket error) — a full disk
|
||||
read as offline; the uninstaller removes the "Start FrameLedger with Windows" Run value, which named an executable it
|
||||
deletes.
|
||||
|
||||
**What none of this reaches:** a copy still on 0.1.0-beta.13 or older runs its own code for the update to beta.14 —
|
||||
stable by default, apply-at-start on. Its user chooses *Beta* in Settings ▸ Updates and updates with no game running
|
||||
(the beta.14 release notes say so); everything above holds from beta.14 on.
|
||||
|
||||
`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).
|
||||
+189
-26
@@ -1,11 +1,12 @@
|
||||
# 12 — Build & development environment
|
||||
|
||||
Mixed toolchain: .NET 10 for managed projects, MSVC for the native layer.
|
||||
Mixed toolchain: .NET 11 for managed projects *(since 0.1.0-beta.37, owner decision D94, 2026-11-11; .NET 10 until
|
||||
0.1.0-beta.36 — §The main line's .NET)*, 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).
|
||||
- Windows 11 (dev), **.NET 11 SDK** (11.0.100 or a later 11.0 feature band), **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, 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.
|
||||
@@ -19,12 +20,18 @@ cmake --preset x64-release
|
||||
cmake --build --preset x64-release
|
||||
```
|
||||
|
||||
A third preset, **`x64-vs-analysis`** *(2026-11-11)*, builds nothing that ships: it has CMake write a Visual Studio
|
||||
solution (`build/native/x64-vs-analysis/FrameLedgerNative.slnx`, generator "Visual Studio 18 2026", tests and tools
|
||||
on) for Qodana's native report, which reads C++ through a solution (`13_CI_CD` §Qodana). It needs Visual Studio 18;
|
||||
the gate and the release never use it.
|
||||
|
||||
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,19 +50,19 @@ 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. **Since beta.14 (D50) the managed binaries are held to the same** — §Version, *Identity*.
|
||||
|
||||
## Managed build & native integration
|
||||
|
||||
- **`global.json` pins the SDK band** (`10.0.x`, `rollForward: latestFeature`). Without it `dotnet build` picks the newest installed SDK — on a machine with a .NET 11 preview installed that silently changes analyzer behaviour under `TreatWarningsAsErrors`, and makes local and CI disagree for reasons nobody can see in a diff.
|
||||
- **`global.json` pins the SDK band** (`11.0.x` since beta.37 — `10.0.x` before — `rollForward: latestFeature`, `allowPrerelease: false`). Without it `dotnet build` picks the newest installed SDK — on a machine with a preview of the next .NET installed that silently changes analyzer behaviour under `TreatWarningsAsErrors`, and makes local and CI disagree for reasons nobody can see in a diff. *(The `alpha` branch carries the same file while its line rests, and pins the SDK it is trying when it does not — §The alpha line.)*
|
||||
- `Directory.Build.props`:
|
||||
- **`TargetFramework` = `net10.0-windows10.0.22621.0`** and **`SupportedOSPlatformVersion` = `10.0.19045.0`**. These are two different knobs and must not be conflated: the TFM platform version selects which Windows API projections are available to compile against, while the supported version is the floor CA1416 enforces. NFR-8 requires Windows 10 **22H2** = build **19045**; letting the supported version default to the TFM's would silently accept installs below the stated floor. Two constraints pin the target to 22621 rather than something closer to the floor: the SDK rejects `SupportedOSPlatformVersion` above `TargetPlatformVersion` (NETSDK1135), and 19045 is not a targeting-pack version in any case — the packs are cut at 19041, 20348, 22000, 22621, 26100. The Windows 11 SDK ≥ 10.0.22621 is already a prerequisite above, so this costs nothing. A bare `net10.0-windows` is wrong for a different reason: it resolves to `net10.0-windows7.0`, and CA1416 would then error on Mica, `MiniDumpWriteDump` and `QueryVideoMemoryInfo` — every Windows-10-era API this app is built on.
|
||||
- **`TargetFramework` = `net11.0-windows10.0.22621.0`** *(`net10.0-…` until beta.36)* and **`SupportedOSPlatformVersion` = `10.0.19045.0`**. These are two different knobs and must not be conflated: the TFM platform version selects which Windows API projections are available to compile against, while the supported version is the floor CA1416 enforces. NFR-8 names Windows 10 **22H2** = build **19045** as the oldest Windows the code is held to *(since D95, 2026-11-11: not blocked there, and neither tested nor supported — Microsoft supports .NET 11 on Windows 11)*; letting the supported version default to the TFM's would silently accept installs below that floor. Two constraints pin the target to 22621 rather than something closer to the floor: the SDK rejects `SupportedOSPlatformVersion` above `TargetPlatformVersion` (NETSDK1135), and 19045 is not a targeting-pack version in any case — the packs are cut at 19041, 20348, 22000, 22621, 26100. The Windows 11 SDK ≥ 10.0.22621 is already a prerequisite above, so this costs nothing. A bare `net11.0-windows` is wrong for a different reason: it resolves to `net11.0-windows7.0`, and CA1416 would then error on Mica, `MiniDumpWriteDump` and `QueryVideoMemoryInfo` — every Windows-10-era API this app is built on.
|
||||
- `Platforms`/`PlatformTarget` = `x64`. "x64 only" is asserted in CLAUDE.md and NFR-8 but was previously enforced nowhere except an ad-hoc `-r win-x64` on the publish command.
|
||||
|
||||
> **`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 +71,25 @@ 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.)*
|
||||
|
||||
**To look at real data with a build of your own (beta.15, D52): `FrameLedger.exe --data-dir <copy>`.** Make the copy with
|
||||
SQLite's online backup, which is consistent while the Agent writes — in Python,
|
||||
`sqlite3.connect("file:C:/Users/<you>/AppData/Local/FrameLedger/ledger.db?mode=ro", uri=True).backup(sqlite3.connect(r"<copy>\ledger.db"))`
|
||||
— or copy the whole folder with every FrameLedger process stopped
|
||||
(closing the App does not stop the Agent). A copy of the database alone has no `covers\`: the games whose image the user
|
||||
chose show the store's artwork instead (beta.23), and choosing one in the viewer writes into the copy's own `covers\`. The App opens the copy, migrating it if your build is newer, which is exactly
|
||||
why it must be a copy, and writes its log and crash dumps beside it. It is a viewer: no Agent is started or contacted and
|
||||
nothing on the PC is changed (`08_UI` §Shell). It refuses the profile's own folder however it is spelled, and a folder
|
||||
that does not exist.
|
||||
|
||||
**Toolchain gotchas, both hit on a real machine and both handled by `build.ps1`:**
|
||||
|
||||
@@ -88,7 +110,7 @@ Launch profiles:
|
||||
|
||||
Native debugging notes: use **`hook-harness`, never a real game**, for step-through debugging — a breakpoint inside a present hook of a real game freezes it in ways anti-cheat and drivers both dislike. Enable the Vulkan validation layers when touching `FrameLedger.VkLayer`. Application Verifier + PageHeap on the harness catches ring-buffer bugs early.
|
||||
|
||||
Agent flags: `--serve`, `--console`, `--write-crash-dump <file>` (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — `10_LOGGING` §Crash handling), ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
|
||||
Agent flags: `--serve` (since beta.10 with at most one of `--for-user <SID>` — the account an Agent started as administrator must be, else it exits 11 — or `--elevation declined|other-account|failed` — its starter asked Windows and got this; both from the admin mode, `01_ARCHITECTURE` ADR-9), `--console`, `--write-crash-dump <file>` (2026-09-17: the crash-dump helper a crashing App or Agent starts; it dumps its parent and takes no pid — `10_LOGGING` §Crash handling), ~~`--diag`~~ (the App's — `FrameLedger.exe --diag`, `10_LOGGING`; the Agent answers exit 2 for it), `--install-task`, `--uninstall-task`, `--register-vklayer`, `--unregister-vklayer` (all four real since 2026-09-14, P3 PR-8b: the task is `\FrameLedger\FrameLedger.Agent` through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated on the dev box, measured — this user's logon trigger, interactive token, lowest run level; the layer registration is `17_HOOK_ENGINE` §Vulkan's HKCU value).
|
||||
|
||||
> **Built 2026-09-10 (P2 PR-F): `--serve` and `--console`; the other five answer "not implemented in P2"
|
||||
> with exit 2** rather than being silently accepted (`--diag` is the App's anyway, `10_LOGGING`). The console
|
||||
@@ -146,6 +168,90 @@ repairs state, it does not grant machine-wide reach on its own).
|
||||
> after every sweep; the flag and the button run the same rule. The uninstall hook is still the updater's
|
||||
> (P4, Velopack).
|
||||
|
||||
## The main line's .NET (owner decisions D94 and D95, 2026-11-11)
|
||||
|
||||
**The main line — the betas and the first release — builds on .NET 11 since 0.1.0-beta.37**: SDK `11.0.100` (the band
|
||||
`global.json` pins), runtime and Windows Desktop `11.0.0`, C# 15 by `LangVersion latest`, and the three packages that are
|
||||
serviced with the runtime (`Microsoft.Extensions.Hosting`, `System.Diagnostics.EventLog`, `Microsoft.Data.Sqlite`) at
|
||||
`11.0.0`. .NET 11 shipped on 2026-11-10; the owner moved the line the next day.
|
||||
|
||||
- **What decided it, and what did not.** `20_OPEN_QUESTIONS` §G held a decision table written on 2026-10-31, before any
|
||||
evidence: move only after (a) two alphas on the released runtime had passed the gate and an owner's run of a hooked
|
||||
title, (b) the owner's word on Windows 10, and (c) something .NET 11 brings being wanted. **The owner set (a) aside** —
|
||||
no alpha had run on the released runtime; three had run on Release Candidate 3 (alpha.1 to alpha.3, the gate green
|
||||
each time) — decided (b) as D95, below, and for (c) asked for C# 15 in the same release (D96). What stands in for (a)
|
||||
is this release's own gate on 11.0.100 (`spike-notes` §28) and owner-only item 34.
|
||||
- **Windows 10 (D95).** Microsoft supports .NET 11 on Windows 11, and on Windows 10 only in its LTSC and IoT editions.
|
||||
FrameLedger does not block Windows 10 22H2: `SupportedOSPlatformVersion` stays `10.0.19045.0`, so CA1416 still holds
|
||||
the code to it, and nothing checks the Windows version at start. It is **untested** there — it always was
|
||||
(`ACCESSIBILITY.md`, `08_UI` §Accessibility) — and now **unsupported** too; NFR-8, `LIMITATIONS.md`, the README and the
|
||||
guide say so.
|
||||
- **The processor.** .NET 11 needs x86-64-v2 — SSE4.2 and POPCNT among its instruction sets — and does not start without
|
||||
it ("The current CPU is missing one or more of the baseline instruction sets"). Its ReadyToRun code targets x86-64-v3
|
||||
(AVX2 among others); Microsoft says a processor that lacks those may pay for it at start-up, where that code is
|
||||
compiled again. Every processor Windows 11 accepts has x86-64-v2.
|
||||
- **What .NET 11 changes in the software**, measured or read: `IHost.RunAsync` rethrows the exception of a
|
||||
`BackgroundService` that failed, so the Agent's `--serve` leaves through its crash report where on .NET 10 it exited 0
|
||||
(`10_LOGGING` §Crash handling; `HostBackgroundFailureTests` holds it); `Microsoft.Data.Sqlite` 11 declares SQLitePCLRaw
|
||||
3.0.5, whose engine is SourceGear's `SQLite` package; nine `Microsoft.Extensions.*` libraries are part of the runtime
|
||||
and no longer packages beside it (`legal/licenses/nuget/`: 78 packages became 69).
|
||||
- **C# 15 (D96)** is the language the main line compiles, and none of its constructs is used yet: the analyses do not
|
||||
read them (`13_CI_CD` §C# 15 and the analyses, `spike-notes` §29). What beta.37 takes from .NET 11 is API.
|
||||
- **Going back** is installing 0.1.0-beta.36 over a later build: the ledger's schema did not move with the runtime.
|
||||
|
||||
## The alpha line (owner decisions D73–D76, 2026-10-31; resting since D98, 2026-11-11)
|
||||
|
||||
The owner, 2026-10-31: an alpha build, "a place where new .NET versions are tried", with code updated where needed and a
|
||||
warning that it is an experiment used at one's own risk. **The alpha line** is the source of a released beta built to
|
||||
try a newer .NET — at times a prerelease one — from the long-lived `alpha` branch, published as `vX.Y.Z-alpha.N` GitHub
|
||||
pre-releases on Velopack's `alpha` channel (`13_CI_CD` §The alpha line, `11_UPDATER` §Channels). It tried .NET 11:
|
||||
Release Candidate 3 in alpha.1 to alpha.3 (2026-10-31 to 2026-11-06), the release itself in alpha.4.
|
||||
|
||||
- **The line rests since 0.1.0-alpha.4 (D98, 2026-11-11).** The main line moved to .NET 11 the day after it shipped
|
||||
(§The main line's .NET), so alpha.4 is 0.1.0-beta.37's source on the same .NET 11.0.0 — published so that a copy of
|
||||
alpha.3 leaves the release candidate by an update, since an alpha never updates to a beta. After it no alpha is cut
|
||||
until a newer .NET has a preview to try (.NET 12's, expected in 2027). While the line rests, the `alpha` branch differs
|
||||
from main in **`RELEASE_LINE` alone** (`git diff main alpha --name-only` prints that one name), and a resting alpha
|
||||
gets no update: its anti-cheat list, which reaches a user only inside a release (`13_CI_CD` §rules-publish.yml), stays
|
||||
the one it shipped with. Its notes, the guide and the Alpha notice tell its user to install the beta — **and the build
|
||||
itself does**: `Directory.Build.props` stamps its `FlAlphaLineRests` property (true on main since beta.37) into every
|
||||
assembly, `Shared.AlphaLine.Rests` reads it, and an alpha cut while it is true shows a banner that says the line is
|
||||
paused and to install the beta, in place of the experimental-build one (`App/Services/AlphaTexts`; D97: the words
|
||||
"a prerelease .NET" appear only where the runtime's own description is a prerelease's).
|
||||
- **The switch — what `alpha` differs from main in while it tries a newer .NET, and nothing else:** `RELEASE_LINE`
|
||||
(`alpha`); `global.json` (that SDK, with `allowPrerelease: true` when it is a prerelease); the TFM in
|
||||
`Directory.Build.props` (`SupportedOSPlatformVersion` stays `10.0.19045.0`); the three Microsoft packages in
|
||||
`Directory.Packages.props` that are serviced with the runtime (`Microsoft.Extensions.Hosting`,
|
||||
`System.Diagnostics.EventLog`, `Microsoft.Data.Sqlite`); `legal/licenses/nuget/` regenerated for that package set and
|
||||
the *Transitive* row of `legal/THIRD_PARTY_NOTICES.md`; `FlAlphaLineRests` set to `false` in `Directory.Build.props`;
|
||||
and a fix only the newer .NET can take, if one is ever forced.
|
||||
As it stood for .NET 11 RC3: SDK `11.0.100-rc.3.26522.148`, `net11.0-windows10.0.22621.0`, the three packages at
|
||||
`11.0.0-rc.3.26522.148` (`spike-notes` §24). **No newer language syntax and no preview feature on `alpha`** (D76): the
|
||||
source is main's, and main compiles with its own SDK.
|
||||
- **Everything else lives on main**, dormant on the main line. `RELEASE_LINE` is read like `VERSION` and stamped into
|
||||
every assembly as the `FrameLedger.ReleaseLine` metadata (`Directory.Build.props` refuses any value but `main` and
|
||||
`alpha`); `Shared.BuildLine` reads it back for the App and the Agent, which compose with it rather than reading it
|
||||
where they act, so a test hands either line to the code it tests. On the alpha line they act on it (D74): the Alpha
|
||||
notice in the Legal Gate with its own tick box, the Agent's wait for it, the ALPHA badge and banner, the locked update
|
||||
channel (`08_UI`), and the ledger's copy before an alpha first opens it (D73, `06_DATA_MODEL` §Migrations). What the
|
||||
alpha's SDK asks of the source and main's can also take lands on main.
|
||||
- **The native layer does not change.** MSVC builds it from the same source; only its build id differs (the alpha's
|
||||
tag). The hook, the guard and the Vulkan layer in an alpha are the beta's.
|
||||
- **Sync, and the cadence while it tries a .NET.** After each beta release a pull request merges main into `alpha` with
|
||||
a merge commit (the repository allows them; the linear rule is main's) and the next alpha is cut from it — **one alpha
|
||||
per beta, never several in a row**, because Velopack reads only the newest ten releases (`11_UPDATER` §Channels). A
|
||||
conflict in a switch file is resolved for the switch; `legal/licenses/nuget/` by regenerating it on `alpha`
|
||||
(`tools/license-gather.ps1`). An alpha older than the ledger's schema refuses to open it (`LedgerSchemaException`), so
|
||||
a beta that adds a migration is followed by an alpha soon. **The sync that ended the .NET 11 trial** (alpha.4) went
|
||||
the other way round: every switch file conflicted and main's version was taken for each, leaving `RELEASE_LINE`.
|
||||
- **Building it locally:** check out `alpha` with the SDK its `global.json` names installed and run `./build.ps1 check`
|
||||
as on main.
|
||||
- **Starting the next trial** (a preview of the next .NET): the switch above on `alpha`, the whole gate in a throwaway
|
||||
worktree first (`spike-notes` §24 is the pattern, with its decision table written before the run), and the Alpha
|
||||
notice's sentence naming the .NET.
|
||||
- **Whether the main line follows a trial** is the owner's each time: `20_OPEN_QUESTIONS` §G, *The main line's .NET*,
|
||||
holds the table and what happened to it for .NET 11.
|
||||
|
||||
## Version
|
||||
|
||||
**One source: the `VERSION` file at the repository root** (`MAJOR.MINOR.PATCH`, nothing else — P4 PR-5,
|
||||
@@ -164,6 +270,29 @@ two products claiming to be one.
|
||||
- `release.yml` refuses a tag whose numeric core is not the file's. Bumping the version is one edit to
|
||||
`VERSION`, in the same commit as the changelog section, before the tag.
|
||||
|
||||
**Identity (beta.14, D50).** Every binary names the product, says what it is and carries one copyright line. Until
|
||||
beta.14 only the native blocks did: the managed ones carried the SDK's defaults — the Agent's company and product read
|
||||
`FrameLedger.Agent`, each library's its own assembly name — and no copyright, and those blocks are what Explorer's
|
||||
*Properties ▸ Details* and Task Manager show (Task Manager lists the Agent by its file description).
|
||||
|
||||
| Field | Native (`src/native/CMakeLists.txt`) | Managed (`Directory.Build.props`, the two entry points' csproj) |
|
||||
|---|---|---|
|
||||
| CompanyName, ProductName | `FL_COMPANY_NAME`, `FL_PRODUCT_NAME` = `FrameLedger` | `Company`, `Product` = `FrameLedger` |
|
||||
| LegalCopyright | `FL_COPYRIGHT` | `Copyright` — the same line, word for word |
|
||||
| FileDescription | each target's `fl_add_version_resource` description | `AssemblyTitle`: `FrameLedger` (App), `FrameLedger Agent` (Agent); a library keeps its assembly name |
|
||||
| Comments | the identification sentence | `Description` — the same sentence for a library, a line of its own for each entry point |
|
||||
| FileVersion / ProductVersion | the numeric core, `x.y.z.0` | `x.y.z.0` / the full version (`-p:Version`, a pre-release's tag included) |
|
||||
| OriginalFilename | the file's own name | the assembly's (`FrameLedger.dll`) — the apphost `.exe` carries a copy of its assembly's block |
|
||||
|
||||
Also stamped on every assembly: `AssemblyMetadata("RepositoryUrl")` (the SDK, from `RepositoryUrl`; the App test holds
|
||||
it equal to `IssueLink.Repository`) and, when `release.yml` passes it, `FrameLedgerSourceRef` — the App csproj's alone
|
||||
until beta.14, now `Directory.Build.props`', and passed to both publishes. `tools/versioninfo-check.ps1` reads all of it
|
||||
from the BUILT binaries — the native five and, with `-ManagedDir`, the managed eight (`FrameLedger.exe`/`.dll`,
|
||||
`FrameLedger.Agent.exe`/`.dll`, Domain, Application, Infrastructure, Shared) — and is red when a copyright differs
|
||||
anywhere, when a managed `ProductVersion` is not `-ExpectedProductVersion` (required: a comparison with nothing passes
|
||||
everything), or when an apphost does not carry its assembly's block; its `-SelfTest` (ten cases, nine RED, each for the
|
||||
reason it names) runs first. `AssemblyIdentityTests` (App and Agent) pins the source against `FL_COPYRIGHT`.
|
||||
|
||||
The Velopack package version is the tag's (`vpk pack --packVersion`), and `UpdateManager.CurrentVersion` reads
|
||||
the installed package's manifest — not the assembly — which is why the two are made to agree here rather than
|
||||
assumed to.
|
||||
@@ -172,15 +301,24 @@ assumed to.
|
||||
|
||||
```
|
||||
cmake --build --preset x64-release
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -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
|
||||
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 -p:FrameLedgerSourceRef={tag} -o out/app
|
||||
vpk download github --repoUrl https://github.com/poli0981/frameledger --channel win --pre --outputDir out/release # beta.13: the previous release, for a delta
|
||||
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
```
|
||||
|
||||
> **On the alpha line (D73, 2026-10-31) both vpk commands take `--channel alpha`** — the download, so an alpha's delta
|
||||
> is made from the previous alpha, and the pack, so its feed is `releases.alpha.json`, which no beta reads. The main
|
||||
> line's pack keeps the command above exactly (no `--channel`: Velopack's default on Windows is `win`). §The alpha line.
|
||||
|
||||
> **Run by `release.yml` since 2026-09-14 (P4 PR-5)** — `13_CI_CD` §release.yml carries the steps around it
|
||||
> (the version gate, `{{RELEASE_DATE}}`, the published-tree assertion, checksums, the release). Both publishes
|
||||
> take `-p:Version=<tag>` (§Version). No `--icon`: `assets/icon.ico` does not exist, and this line named it
|
||||
> for six weeks.
|
||||
> for six weeks. **Since beta.12 the App also takes `-p:FrameLedgerSourceRef`** — the tag, or for a rehearsal the
|
||||
> commit — stamped as assembly metadata so its links into the repository open THIS version's documents
|
||||
> (`Services/RepositoryLinks`); a build without it links to `main`. **Since beta.14 the Agent takes it too**, because
|
||||
> `Directory.Build.props` stamps it on every assembly and both publishes build the same libraries into `out/app` (§Version,
|
||||
> *Identity*).
|
||||
>
|
||||
> **The package id is `FrameLedger.App`, and this line said `FrameLedger` until 2026-09-14 — which would have
|
||||
> deleted every user's ledger on uninstall.** Velopack installs into `%LOCALAPPDATA%\<packId>` and removes that
|
||||
@@ -215,7 +353,7 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
|
||||
|
||||
- No trimming (WPF + reflection), no NativeAOT (WPF unsupported), **no obfuscation** (GPLv3 policy, and `19_SAFETY` forbids making our binaries harder to identify).
|
||||
- `SatelliteResourceLanguages=en;vi;ja`. ~~Expected package ≈ 95–130 MB self-contained.~~ **Measured 2026-09-14 (P4 PR-5): the published tree is 250 MB in 362 files** (App + Agent, self-contained, ReadyToRun roughly doubles the IL). `vpk pack` 1.2.0 over that tree, run by hand the same day with the workflow's arguments: `FrameLedger.App-win-Setup.exe` **104 MB**, the full `.nupkg` and the portable zip 100 MB each, plus `releases.win.json` / `RELEASES` / `assets.win.json`; vpk's own pre-process step verified `VelopackApp.Run()` in `FrameLedger.App.Program::Main()`. **From the hosted runner on the first tag (2026-09-16, `v0.1.0-beta.1`):** the tree 252 MB, `Setup.exe` 110 MB, the nupkg and the zip 105 MB — the same shape, a few MB heavier for two more days of code.
|
||||
- Velopack hooks (**built 2026-09-14, P4 PR-5**: `App/Update/VelopackHooks`, wired in the hand-written `Program.Main` before any window). **Install registers nothing** — the first-run flow is the offer (Agent setup), and the layer follows the ledger (§The Vulkan layer is not registered at install time); this line used to say "offer Agent setup + Vulkan layer registration", and the second half was the thing the section below forbids. Uninstall runs `UninstallHook`: `Shutdown` to a running Agent over the pipe (best effort, it holds the install directory), unregister the layer (HKCU), remove the logon task, then **ask** about the data folder — deleted on Yes only, never when it and the install overlap (`AreSeparate`), and a question unanswered inside Velopack's 30 s callback budget keeps it.
|
||||
- Velopack hooks (**built 2026-09-14, P4 PR-5**: `App/Update/VelopackHooks`, wired in the hand-written `Program.Main` before any window; since beta.14 Velopack's apply-at-start is off and an update it starts itself stops the Agent first — `11_UPDATER` §The update audit). **Install registers nothing** — the first-run flow is the offer (Agent setup), and the layer follows the ledger (§The Vulkan layer is not registered at install time); this line used to say "offer Agent setup + Vulkan layer registration", and the second half was the thing the section below forbids. Uninstall runs `UninstallHook`: `Shutdown` to a running Agent over the pipe (best effort, it holds the install directory), unregister the layer (HKCU), remove the logon task, remove the *Start FrameLedger with Windows* Run value (beta.14 — it named the executable being deleted), then **ask** about the data folder — deleted on Yes only, never when it and the install overlap (`AreSeparate`), and a question unanswered inside Velopack's 30 s callback budget keeps it.
|
||||
|
||||
## Release-time token substitution
|
||||
|
||||
@@ -223,33 +361,58 @@ 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
|
||||
document the app displays for acceptance (FR-11) is a defect, not a template.
|
||||
|
||||
**The build id is read before it (beta.18).** The substitution edits tracked files, and the native build id is
|
||||
`git describe --dirty` at CMake's configure (`src/native/FrameLedger.Shm/CMakeLists.txt`): every release until beta.18
|
||||
shipped `<tag>-dirty` — the owner's Dashboard read *Overlay build v0.1.0-beta.17-dirty*, and that run's log printed
|
||||
`FL_BUILD_ID = v0.1.0-beta.17-dirty` two lines after `RELEASE_DATE = 2026-10-07 in 3 file(s)`. `release.yml` now reads
|
||||
describe from the clean checkout first, refuses one that is already dirty or longer than 31 characters, and passes it
|
||||
as the environment's `FL_BUILD_ID`, which CMake takes as given (checked for the characters a C string literal carries);
|
||||
after the publish, `tools/buildid-check.ps1` reads it back out of the four native binaries that compile it, by their
|
||||
bytes — nothing is loaded. A developer's build still runs describe itself (`+` marks a dirty tree when the long form
|
||||
would not fit).
|
||||
|
||||
## Local quality gate (pre-push)
|
||||
|
||||
`./build.ps1 check`:
|
||||
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`)
|
||||
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`) — since beta.12 also `FrameLedger.ProcessStats.dll` (the game
|
||||
process's memory, D43; staged beside the Agent, CaptureHost and Infrastructure.Tests by
|
||||
`FrameLedger.ProcessStats.targets`), its ctest `fl_process_stats` (GPU_INSTANCE on a machine with a hardware adapter,
|
||||
NO_GPU_INSTANCE elsewhere) and the instrument `fl-probe-processstats` (`spike-notes` §16)
|
||||
2. native tests (Catch2)
|
||||
3. `clang-format --dry-run -Werror` over `src/native`
|
||||
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`
|
||||
`FrameLedger.Domain` and `FrameLedger.Application`. *(Since 2026-10-25 step 6 writes OpenCover beside each
|
||||
Cobertura report — `--collect:"XPlat Code Coverage;Format=cobertura,opencover"` — for SonarCloud, whose C# importer
|
||||
reads no Cobertura; `ci.yml`'s `sonarcloud` job takes them from the gate's artifact, `13_CI_CD` §SonarCloud. This
|
||||
gate still reads Cobertura only.)*
|
||||
8. `tools/rules-validate.ps1` (schema + `anticheat` block sanity — a malformed or empty blocklist is a safety bug)
|
||||
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every `FileVersion` against the `VERSION` file (§Version)
|
||||
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every `FileVersion` against the `VERSION` file (§Version); **since beta.14 (D50) both halves run — the self-test, then the native five and the managed eight from the App's and the Agent's build output** (`-ManagedDir`, `-ExpectedProductVersion` = `VERSION`), one copyright across all of them (§Version, *Identity*). Under `-SkipNative` the managed half still runs
|
||||
10. `tools/chokepoint-check.ps1` — injection and evasion primitives confined to one file, native **and** managed, plus the `FL_GUARD_TESTABLE` symbol check against the shipped artifacts
|
||||
11. **`tools/hookinventory-check.ps1`** — three passes: A resolves every vendor symbol the Overlay names against `docs/vendor-exports.json`, B sweeps for stray literals, C reads the BUILT Overlay's import table and asserts it imports no vendor module. C skips loudly under `-SkipNative`. **Missing from this list until 2026-08-28**, which is §R10 happening again
|
||||
12. **`tools/package-closure-check.ps1`** — both halves: the self-test (5 cases, 4 of which must go RED) **and** a live pass over this repository. It walks the transitive `ProjectReference` closure of the two publish roots below and fails on anything outside the allowlist, naming the reference edge. `FrameLedger.CaptureHost` is an injecting entry point kept out of the package by construction, and `20_OPEN_QUESTIONS` §S27 is closed on exactly that basis
|
||||
13. `tools/license-check.ps1` — asserts every vendored third-party has a licence copy in `legal/licenses/`, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that `legal/licenses/nuget/` is exactly what `tools/license-gather.ps1` writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. `license-gather.ps1 -SelfTest` runs first: fourteen fixture cases, five that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture
|
||||
13. `tools/license-check.ps1` — asserts every vendored third-party has a licence copy in `legal/licenses/`, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that `legal/licenses/nuget/` is exactly what `tools/license-gather.ps1` writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. `license-gather.ps1 -SelfTest` runs first: ~~fourteen~~ sixteen fixture cases, ~~five~~ six that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an expression with no text in the script and no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture. **Since beta.12 (78 packages):** a reviewed override also answers for an expression the script has no text for — Markdig declares BSD-2-Clause and ships no file, and `tools/license-overrides/Markdig.txt` is the project's own `license.txt` at the packaged commit
|
||||
13b. `tools/accuracy-check.ps1 -SelfTest`, then live — the accuracy block is ONE text (`legal/ACCURACY.md`) embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06)
|
||||
13c. **`tools/notice-check.ps1 -SelfTest`, then live** (beta.12, owner decision D45, 2026-10-03) — every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`, tracked or new, minus `src/native/third_party/`) opens with `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (`NOTICE` carries them); the second line may name another holder and year in the same form (a contributor's own file).
|
||||
Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a missing header, and `tools/resx-gen.ps1` generates the accessor with it
|
||||
13d. **`tools/wiki-build.ps1 -SelfTest`, then `-Check`** (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from `wiki/`, `guide/`, `LIMITATIONS.md` and (beta.35) `ACCESSIBILITY.md` into a temporary folder, as `wiki.yml` does at a release (`13_CI_CD` §wiki.yml), and fails on a link to a file, folder or section that does not exist, two sources for one page, a page that neither Home nor the sidebar leads to, a sidebar that lists the guide in another order than `guide/README.md`, a backticked repository path in a `wiki/` page that names nothing, and a version number written into a `wiki/` page (the footer says which release the wiki shows). ~~Nine~~ Ten self-test cases since beta.35 (the statement's page, D88), both directions
|
||||
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
|
||||
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one). The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
|
||||
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one), and since beta.24 three over a temporary tree: a version with its own `docs/changelog/<version>.md` is read from it, one without from `CHANGELOG.md`, a prefix of a file name is not that file. The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
|
||||
14e. **`tools/nvapi-readonly-check.ps1 -SelfTest`, then live** (owner decision D108, 2026-11-11) — every `NvAPI_*` call in `src/native/FrameLedger.NvapiBridge/src/fl_nvapi_bridge.cpp`, the one translation unit that links `nvapi64.lib` into a shipped binary, is on `tools/nvapi-allowed-calls.txt` and every name there is called; a name that sets, saves, restores, deletes, registers, resets, enables, disables or controls something is red **even when the list names it**, and so is one that returns an identifier (D104) — three reads the verb rule would refuse are exempt by name, each with its reason. Comments and string literals are taken out first, so a setter named in the comment that says it is never called is not a call. Seventeen self-test cases, both directions. Text only: it runs with or without the native build. `18_GPU_VENDOR_APIS` §Runtime policy's "never call a setter", which was a sentence until the bridge went from fourteen calls to forty-four
|
||||
14f. **`tools/overlay-fields-check.ps1 -SelfTest`, then live** (owner decision D116, 2026-11-12) — the same for the code loaded into a game: every member of a vendor's struct the Overlay reads for Advanced metrics is read in ONE header, `src/native/FrameLedger.Overlay/include/fl_adv_fields.h`, through parameters with fixed names, and is on `tools/overlay-allowed-fields.txt`; every name there is read; the parameters are not aliased and `->` reaches nothing but `desc` and the Overlay's own `region`; no other Overlay or Vulkan-layer source reads a listed member; **a camera's position, axes and matrices** (`cameraPos`, `cameraUp`, `cameraRight`, `cameraFwd`, the five matrices, `cameraPinholeOffset`, `cameraPosition`, `cameraForward`) **are named nowhere in those sources and not on the list, whatever the list says**; and neither `sl::Constants` nor `ffxDispatchDescFrameGenerationPrepareV2` is copied by value or measured with `sizeof`. Comments and string literals are taken out first. Nineteen self-test cases, both directions. Text only. It reads names, not types — which struct version carries a member is `17_HOOK_ENGINE` §Which struct version carries which field and ctest `fl_adv_fields`
|
||||
14d. **`tools/docs-split-check.ps1 -SelfTest`, then live** (beta.24, owner decision D66) — `CHANGELOG.md` holds no released section beside `[Unreleased]`; each `docs/changelog/<version>.md` holds one `## ` heading, its own `## [<version>] - date`, and no relative link (the App renders release notes as `CHANGELOG.md`); `CHANGELOG.md` and the files under `docs/changelog/`, and `docs/HANDOFF.md` and the files under `docs/handoff/` — and since PR-5 `docs/20_OPEN_QUESTIONS.md` and `docs/open-questions/`, `docs/spike-notes.md` and `docs/spike-notes/` — name each other in both directions. Eleven self-test cases, both directions
|
||||
14c. **`tools/buildid-check.ps1 -SelfTest`** (beta.18) — eight cases, both directions: a binary built from a dirty tree (`-dirty`, or the short form's `+`), one with no id, a missing one, and an expected id that is dirty or not an id are red. The live half needs the release's clean-checkout id and runs in `release.yml` over the published tree (§Release-time token substitution)
|
||||
15. `tools/resx-audit.ps1` — ~~**skipped loudly; it does not exist, and no `.resx` file does either**~~ **built 2026-09-13 (P3 PR-2)**: `-SelfTest` first (11 fixture cases, both directions), then the live pass over every `Strings.resx` family under `src/` — key sets equal across en/vi/ja, `Safety_*` in `ja` marked for review or signed, `Strings.Designer.cs` current with `tools/resx-gen.ps1`. A tree with no family is red (`09_I18N` §Translation workflow)
|
||||
16. **struct-mirror** — reads this run's `.trx` and fails when `ShmLayoutMirrorTests` did not execute, so deleting the mirror test is red as well as breaking it
|
||||
16b. **`tools/test-artifacts-check.ps1`** — `-SelfTest` first (seven cases, two RED), then live: an `overlay-*.log` created since this gate started, still in the real `%LOCALAPPDATA%\FrameLedger\logs` after the tests, whose first line names a `hook-harness*` image, fails the gate. It is what makes a test binary without its log sweep red (`17_HOOK_ENGINE` §Native logging, 2026-09-15); a game's log never counts
|
||||
|
||||
+736
-23
@@ -6,9 +6,9 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
|
||||
## Workflows (`.github/workflows/`)
|
||||
|
||||
### `ci.yml` — push to `main` + all PRs · **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.
|
||||
### `ci.yml` — push to `main` *(and to `alpha` since 2026-10-31, D73 — §The alpha line)* + 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` (pinned to its v1.13.0 commit since beta.24 — the one third-party action, SonarCloud `githubactions:S7637`; Dependabot moves the pin), 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. *(That is the `check` job. Since 2026-10-25 a second job, `sonarcloud`, runs after it — §SonarCloud below; it is not the gate and not a required context.)*
|
||||
- ~~**`-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.
|
||||
- **The hosted runner refuses guard scans intermittently — THREE failures in eight gate runs, measured
|
||||
2026-09-10 while merging P2's stack.** Every one was an `Category=Integration` case, every one passed on
|
||||
@@ -52,6 +52,17 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
case. `Kill` now waits for exit (bounded, asserted) and the delete retries. Not §S19(b) either — a test-harness
|
||||
race, and the third flake shape of the day (the registry-subtree race between `VkLayerRegistrationTests` and the
|
||||
GOG reader's test, fixed in #188) was the same kind.
|
||||
- **Two more on 2026-10-07 (beta.18), both re-run green and then fixed the same day.**
|
||||
`WhenTheTargetExitsTheHostStopsAndSaysWhy` ended **`TargetNotRunning`** (#286, run 37619719203): the host resolves its
|
||||
target once, as it starts, and a host slower than the harness's 6 s hold found it gone — the shape recorded since
|
||||
2026-09-21. The hold is 15 s: a margin, not a signal, because the host prints nothing until its session ends.
|
||||
`LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing` ended **`RefusedByGuard` / `ModuleScanFailed`**
|
||||
(#288, run 37627351438): the hosted runner has the Vulkan loader and no device, so the harness exits 77 with a
|
||||
`[SKIP]` line — but the runner is elevated, the host starts the harness through `CreateProcessWithTokenW`
|
||||
(`UnelevatedProcess`), the child gets no stdout, and the line never reached the host's output; the test then
|
||||
depended on the session reading `LaunchTargetExited`, and a scan that hit the dying harness failed it instead. The
|
||||
test now asks the harness directly, before the host runs (exit 77 = skip, with the harness's own line); hiding the
|
||||
Vulkan ICDs from that probe makes it skip in under a second, and on a machine with a device it runs in full.
|
||||
- **A re-run ERASES the evidence, which is why the count above had to be kept by hand.**
|
||||
`gh run rerun --failed` updates the original run's conclusion, so `gh run list` showed **18 success, 1
|
||||
cancelled, 0 failed** across the twenty runs that contained all three failures above. Anyone measuring
|
||||
@@ -69,7 +80,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
The next Integration failure is the measurement: read the probe step *before* re-running. Struck rather
|
||||
than deleted because a session planned a workflow change on this bullet's word.
|
||||
- **Signer probe step** (2026-09-06): `fl-probe-signer` runs as its own step after the gate — `continue-on-error`, a measurement and not a gate — because `ctest fl_signer_probe` passes on a regular expression and prints nothing, so §S19(b)'s CI leg was never readable from the log. Its answers are read off this step.
|
||||
- Uploads coverage artifacts.
|
||||
- Uploads coverage artifacts — ~~Cobertura~~ Cobertura and OpenCover since 2026-10-25, one pair per test project, as the `coverage` artifact the `sonarcloud` job reads (§SonarCloud).
|
||||
- **Changelog gate**, on pull requests only: the changed-file list comes from GitHub's own view of the PR — not `git diff`, so a shallow checkout cannot silently produce a short one — and an empty list is refused rather than read as "no `src/` changes". It is a **step of the required `check` job** and deliberately not a job of its own: `main`'s required contexts are exactly `check` and the two `analyze` jobs, so a new job would go red while the merge button stayed green, which is what already makes `Rules / validate` advisory (§S23-2).
|
||||
|
||||
> **Three claims in this section were false and are corrected 2026-08-06.** There is no Vulkan SDK
|
||||
@@ -81,17 +92,49 @@ 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)*. *Since 2026-10-25 per job:* the workflow grants nothing (`permissions: {}`), `check` holds those two and `sonarcloud` `contents: read` alone — a workflow-level grant reaches every job (SonarCloud `githubactions:S8264` on the first analysis from CI).
|
||||
|
||||
### `codeql.yml` — push, PR, weekly cron · **repo-local**
|
||||
### `codeql.yml` — push, PR, weekly cron, `workflow_dispatch` (since 2026-11-11) · **repo-local**
|
||||
|
||||
> **Not a caller stub, which this heading said until 2026-08-06.** `codeql.yml`'s own header says
|
||||
> the opposite: the ops repo has `codeql-mixed.yml`, but C++ needs manual build mode driven by the
|
||||
> CMake preset and that input surface has not been verified. The paragraph below already anticipated
|
||||
> exactly this outcome; the heading was never updated when it happened.
|
||||
- Languages: `csharp` **and `cpp`** (manual build mode for C++, driven by the CMake preset). The native layer is where memory-safety bugs would live; excluding it would defeat the purpose. Verify the mixed template exposes a C++ build-command input; if it does not, this one goes repo-local too.
|
||||
- **And `actions`, since 2026-10-25** (build mode `none`): CodeQL reads `.github/workflows` for injection from event data, untrusted checkouts and over-broad tokens — the class of finding SonarCloud raised once (`githubactions:S7631`, `wiki.yml`, beta.26). Its context, `analyze (actions, none)`, is not one of `main`'s required checks; adding it to them is the owner's setting.
|
||||
- **Concurrency, since 2026-10-25:** a new push to a pull request cancels that pull request's run; a push to `main` and the weekly scan each run in a group of their own (the run id), so none is cancelled or left pending, and the default branch's alerts come from a finished analysis.
|
||||
- `permissions: security-events: write, contents: read`.
|
||||
- **On .NET 11 since beta.37 (D94) — measured on the pull request that moved the line (#376, run 42916491104, CodeQL
|
||||
2.27.4).** CodeQL's documentation lists C# up to 14 and .NET up to 10, and `analyze (csharp, none)`, a required
|
||||
context, had never met `net11.0`. With build mode `none` the extractor reads the source with its own compiler front
|
||||
end and uses a `dotnet` only for references: it found the 11.0.100 SDK `setup-dotnet` had installed and used that (on
|
||||
.NET 10 it downloaded 10.0.100 for itself), restored, and reported 363 resolved references and none unresolved, 9
|
||||
types it could not resolve (main's last run on .NET 10, 42862718138: 23, in three `Windows.Win32` namespaces), and
|
||||
**`CodeQL scanned 1220 out of 1220 C# files`** — main's line, word for word — in 4 min 5 s. The source it read used
|
||||
no C# 15 construct. **What it reads of C# 15 is measured construct by construct before one is used** (D96): a
|
||||
construct in whose file the extractor reports an error is not used on main until CodeQL reads it, and the same holds
|
||||
for Qodana's engine (§Qodana).
|
||||
*(Corrected the same day, two pull requests later: that run was an **overlay** — on a pull request the C# analysis
|
||||
extracts the files it changed on top of the database cached from `main`, then a .NET 10 one — so its "1220 out of
|
||||
1220" was `main`'s baseline figure and its other numbers the changed files'. The whole source on `net11.0` was first
|
||||
read by `main`'s own run after the merge (42921492229, "Overlay mode not enabled"): 1,221 source files, 363
|
||||
references resolved and none unresolved, 23 types unresolved in the three `Windows.Win32` namespaces — the figure it
|
||||
had on .NET 10 — and "CodeQL scanned 1221 out of 1221 C# files", in 4 min 45 s. So CodeQL reads `net11.0` as it
|
||||
read `net10.0`; and for a construct it has not met, a pull request's run is not the evidence — a
|
||||
`workflow_dispatch` on the branch is, §C# 15 and the analyses.)*
|
||||
|
||||
### `qodana.yml` — push to `main`, pull requests into `main`, `workflow_dispatch` · **repo-local, built 2026-11-10 (D93); Qodana for .NET since 2026-11-11 (D99)**
|
||||
- ~~One job, `qodana`, on `ubuntu-latest` — the only Linux job in this repository, because the linter is a Linux
|
||||
container~~ Two jobs, on `windows-latest`, each a report of its own: **`native`** (*Qodana (native)*) has CMake
|
||||
write a Visual Studio solution and reads the C++ of `src/native` with `qodana-native.yaml`'s settings; and
|
||||
`managed` (*Qodana (managed)*): `JetBrains/qodana-action` (pinned to
|
||||
`v2026.2.2`'s commit; Dependabot moves the pin) runs **Qodana for .NET** in native mode over `FrameLedger.slnx`
|
||||
with `qodana.yaml`'s settings, after a `dotnet build`. No job here runs on Linux any more. §Qodana below says what
|
||||
it reads, what was changed from JetBrains' template and where an inspection is switched off.
|
||||
- **Advisory, with a gate of zero problems:** one problem turns the job red; it is not a required context.
|
||||
- `permissions: contents: read, checks: write, pull-requests: write` — the annotations and the one comment; granted to
|
||||
the job, the workflow grants none.
|
||||
|
||||
### `release.yml` — on tag `v*` · **repo-local, built 2026-09-14 (P4 PR-5)**
|
||||
|
||||
@@ -127,29 +170,49 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
`VERSION` file (`12_BUILD` §Version); and `CHANGELOG.md` must carry a **non-empty** `## [x.y.z]` section for the
|
||||
full version, extracted by `tools/release-notes.ps1` (self-tested on every `build.ps1 check`). A missing
|
||||
section is a red release, not an empty note — the ledger's header said the opposite for five weeks.
|
||||
- **The build id from the clean checkout** (beta.18): `git describe --always --dirty --abbrev=12` before anything edits a
|
||||
tracked file — a dirty one or one over 31 characters stops the run — into `FL_BUILD_ID` for CMake. Until beta.18 the
|
||||
substitution below ran first and every release's natives called themselves `<tag>-dirty` (`12_BUILD` §Release-time
|
||||
token substitution).
|
||||
- `{{RELEASE_DATE}}` substituted in `legal/*.md` with the run's UTC date **before the build**, because the App
|
||||
embeds those documents (FR-11); any `{{` token left anywhere after that fails the job.
|
||||
- **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;
|
||||
run again over `out/app`, because a `.targets`-staged DLL that failed to copy is a warning to `dotnet publish` —
|
||||
**since beta.14 (D50) with its managed half** (`-ManagedDir out/app -ExpectedProductVersion <tag>`): the eight managed
|
||||
binaries name FrameLedger, carry the tag's full version and the native binaries' copyright line (`12_BUILD` §Version,
|
||||
*Identity*). Both publishes take `-p:FrameLedgerSourceRef` since beta.14.
|
||||
- **since beta.13, `vpk download github --pre` first**, so `vpk pack` finds the previous release's full package in
|
||||
`out/release` and writes a delta; after the pack, what `assets.win.json` names is kept and the rest (the previous full
|
||||
package) moves to `out/previous`, the feed and `RELEASES` are filtered to this build, and a downloaded previous package
|
||||
with no delta beside it fails the job. A failed download is a warning: the release is full-only, as every one before it
|
||||
was (`11_UPDATER` §Built).
|
||||
- `vpk pack --packId FrameLedger.App` (the `vpk` tool pinned to the library's ~~1.2.0~~ 1.2.161 since beta.30, D71) with the release notes;
|
||||
`FrameLedger.App-win-Setup.exe` must come out, because README §Install names it. **Not `--packId FrameLedger`**:
|
||||
Velopack installs into and uninstalls `%LOCALAPPDATA%\<packId>`, which with that id is the data folder
|
||||
(`12_BUILD` §Publish & package). No `--icon` until `assets/icon.ico` exists.
|
||||
- `SHA256SUMS.txt` over every asset, published beside them and printed into the release body (`11_UPDATER`
|
||||
§Unsigned releases).
|
||||
- `gh release create` with the assets, `--verify-tag`, and `--prerelease` for a `-beta.N` tag.
|
||||
- **The alpha line (D73, 2026-10-31):** the version gate reads `RELEASE_LINE` beside `VERSION` and refuses a tag that
|
||||
disagrees with it — on the `alpha` line only `vX.Y.Z-alpha.N`, and an `-alpha.` tag nowhere else. An alpha's download
|
||||
and pack take `--channel alpha`, so the feed, the asset list, the legacy index and the installer are named for that
|
||||
channel (`releases.alpha.json`, `assets.alpha.json`, `RELEASES-alpha`, `FrameLedger.App-alpha-Setup.exe`, and the
|
||||
packages themselves, `FrameLedger.App-<version>-alpha-full.nupkg` / `-alpha-delta.nupkg` — measured on the first alpha's
|
||||
rehearsal, after which the delta check reads the name from `assets.<channel>.json` rather than building it) and its delta
|
||||
is made from the previous alpha; the main line's pack is unchanged. The release is titled *(experimental alpha)*, and
|
||||
its notes — the alpha's own file, `docs/changelog/x.y.z-alpha.N.md` — open with the warning (§The alpha line).
|
||||
- The assets and the notes are also uploaded as a workflow artifact for the smoke checklist (`14_TESTING`
|
||||
§Release smoke).
|
||||
- ~~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,30 +236,676 @@ 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`)
|
||||
### `wiki.yml` — after a successful Release run, and by hand · **repo-local, built 2026-10-07 (beta.17, D53/D54)**
|
||||
- **What:** the GitHub Wiki is a copy of the repository's own pages — `wiki/` (Home, the sidebar, the developer pages)
|
||||
and `guide/` (the user guide: the End-user part, the same pages the App shows) with `LIMITATIONS.md` and, since
|
||||
beta.35 (D88), `ACCESSIBILITY.md`. `tools/wiki-build.ps1` names each page (a guide page after its first heading,
|
||||
`guide/README.md` as *User-guide*, `LIMITATIONS.md` as *Limitations*, `ACCESSIBILITY.md` as *Accessibility*), rewrites links between pages to page names and every other repository link to
|
||||
its address on GitHub **at the release's tag**, drops each page's first heading (the wiki prints the page name), and
|
||||
writes a footer naming the tag. The same assembly is `build.ps1`'s `wiki-check` gate (`12_BUILD` §Local quality gate,
|
||||
13d), so a dead link is red on the pull request, never on the published wiki.
|
||||
- **When:** `workflow_run` on `Release`, completed — the job runs only when that run succeeded and was started by a
|
||||
pushed `v*` tag in this repository (`head_repository` is checked since beta.26: a fork cannot start the Release run,
|
||||
and the condition now says so — SonarCloud `githubactions:S7631`), so a `workflow_dispatch` rehearsal of
|
||||
`release.yml` never publishes. It checks out the run's
|
||||
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. **Not after an
|
||||
alpha's release** (D73, 2026-10-31: a `-alpha.` tag is skipped): the wiki shows the newest beta. By hand:
|
||||
`gh workflow run wiki.yml -f ref=main -f publish=false` builds, checks and uploads the pages as an artifact; with
|
||||
`publish=true` it publishes them.
|
||||
- **Why not a step of `release.yml`:** the release stays as it was, its rehearsal stays a pure rehearsal, and a wiki
|
||||
that fails to publish is a red run of its own that can be re-run — a step after `gh release create` could never be
|
||||
re-run, the release already existing. A release created with `GITHUB_TOKEN` fires no `release` event for other
|
||||
workflows; `workflow_run` fires because the Release run itself was started by a tag push.
|
||||
- **Publishing:** `gh auth setup-git`, a clone of `<repo>.wiki.git`, everything but `.git` replaced, a commit as
|
||||
`github-actions[bot]` only when something changed, `git push origin HEAD:master` (the wiki's branch is `master`). A
|
||||
page edited on the Wiki tab is overwritten at the next release: edit `wiki/` or `guide/`.
|
||||
- `permissions: contents: write` — the repository's default workflow token is read-only (read from the API,
|
||||
2026-10-07), and pushing to the wiki repository needs write.
|
||||
|
||||
## The alpha line — the `alpha` branch (owner decisions D73–D76, 2026-10-31; resting since D98, 2026-11-11)
|
||||
|
||||
What it is, what differs on the branch and why it rests since 0.1.0-alpha.4: `12_BUILD` §The alpha line. What CI and the
|
||||
release do with it:
|
||||
|
||||
- **`ci.yml`** runs `check` on a push to `alpha` and on every pull request into it, under the branch's own `global.json`
|
||||
— `setup-dotnet` installs the exact SDK it names whatever the `rollForward`, a prerelease one included. The
|
||||
`sonarcloud` job does not run for the branch (the organisation's plan analyses main alone, §SonarCloud), and neither
|
||||
does the `Changelog` step: what an alpha changes is written in its release's own file on main, never in an
|
||||
`[Unreleased]` entry on `alpha`, which would collide with main's at every sync.
|
||||
- **`codeql.yml` and `qodana.yml`** stay on main: the source is main's, and it is analysed there. *(Until beta.37 the
|
||||
reason given here was the alpha's compiler — C# 15, where CodeQL's extractor read C# 14. Main compiles C# 15 since
|
||||
beta.37; what CodeQL reads of it is §`codeql.yml`'s to say.)*
|
||||
- **The branch is not protected** (an owner's setting; none was asked for): pull requests into it are how changes land
|
||||
(squash), and the sync from main is a pull request merged with a merge commit — main's linear rule is main's alone.
|
||||
- **A release of the line**, in order: the alpha's notes on main (`docs/changelog/x.y.z-alpha.N.md` opening with the
|
||||
warning, its row in `CHANGELOG.md`'s Releases table, a line in HANDOFF's START HERE) → the sync pull request into
|
||||
`alpha` → a `release.yml` dispatch on `alpha` (`gh workflow run release.yml --ref alpha -f version=x.y.z-alpha.N`) →
|
||||
the signed tag on `alpha`'s head → the run (§release.yml: the line's tag rule, `--channel alpha`). **No wiki publish**
|
||||
(`wiki.yml` skips an `-alpha.` tag) and **no release line moves**: README, ACCURACY, the Disclaimer's copy,
|
||||
LIMITATIONS and ACCESSIBILITY keep naming the newest beta.
|
||||
- **The cadence while the line tries a .NET:** one alpha per beta, cut from it. Velopack's GitHub source reads the
|
||||
newest ten releases (one page, `perPage` 10), so ten alphas in a row would hide every beta from the betas' own update
|
||||
check, and the other way round (`11_UPDATER` §Channels). **While it rests** no alpha is cut, and that limit has a
|
||||
consequence the alpha's notes state: once ten betas have followed alpha.4, a copy of alpha.3 no longer finds it.
|
||||
|
||||
## SonarCloud — from CI, `ci.yml`'s `sonarcloud` job (owner decision D68, 2026-10-25)
|
||||
|
||||
**D68 — SonarCloud is analysed from CI.** The owner turned SonarCloud's Automatic Analysis off and set the
|
||||
`SONAR_TOKEN` secret (2026-10-24), and asked for the CI-based analysis with the newest scanner, run until its quality
|
||||
gate passed on issues and coverage both. It replaces D67 (the subsection below, as it stood): `.sonarcloud.properties`
|
||||
is gone, `SonarQube.Analysis.xml` holds what it held, and the two rules broken by design everywhere are configuration
|
||||
rather than marks in the UI.
|
||||
|
||||
**How it runs.** A second job of `ci.yml`, after `check` (`needs: check`), on every pull request from this
|
||||
repository and every push to `main` (or a `workflow_dispatch` of `main`) — never another branch: the organisation's
|
||||
plan refuses a branch analysis ("Organization is not allowed to access data from non main branches", a dispatch of
|
||||
the feature branch, 2026-10-25), so a dispatch of any other branch runs `check` alone:
|
||||
|
||||
1. a full-depth checkout (blame dates the new code; the tags name the version), .NET, MSVC, the NuGet and
|
||||
`~/.sonar/cache` caches;
|
||||
2. the gate's coverage — the `coverage` artifact `check` uploaded, not a second test run;
|
||||
3. `cmake --preset x64-release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_SCAN_FOR_MODULES=OFF` and the one
|
||||
header the build generates (`fl_ac_floor_gen`) — the compilation database, with nothing compiled. *Scanning off
|
||||
because the first run failed on it:* with C++20 and Ninja, CMake gives every compile command an
|
||||
`@<object>.modmap` response file that only the build writes, and the C/C++ analyser (CFamily 6.85) stops with
|
||||
`IllegalStateException: unexpanded response file`; no source here uses a module;
|
||||
4. **SonarScanner for .NET 12.0.0** (2026-10-15, the newest), a local tool (`.config/dotnet-tools.json`, `dotnet tool
|
||||
restore`; Dependabot's nuget entry moves it), which provisions its own JRE: `begin` with `/s:SonarQube.Analysis.xml`
|
||||
→ `dotnet build FrameLedger.slnx -c Release` → `end`.
|
||||
|
||||
**Why a job of its own, and a build of its own.** The scanner's targets turn `TreatWarningsAsErrors` off and empty
|
||||
`WarningsAsErrors` in every build they instrument (`SonarQube.Integration.targets`, read in 12.0.0's source), so
|
||||
wrapping the gate's build would quietly weaken the gate. And the job is **advisory**: `main`'s required contexts stay
|
||||
`check`, `analyze (csharp, none)` and `analyze (cpp, manual)`. It waits for the quality gate
|
||||
(`sonar.qualitygate.wait`), so a failed gate — or a SonarCloud outage — is a red job beside a green `check`, never a
|
||||
blocked merge, and SonarCloud's app still posts its own *SonarCloud Code Analysis* check on the pull request.
|
||||
|
||||
**The C++.** The SonarScanner for .NET analyses only files an MSBuild project names: it drops `sonar.sources`, and
|
||||
its scan of the files outside the projects (`sonar.scanner.scanAll`: PowerShell, YAML, JSON and a dozen more) has no
|
||||
C or C++ in its list (`AdditionalFilesService`, 12.0.0). So `FrameLedger.Infrastructure.csproj` — the project that
|
||||
reaches the native layer — names `src/native`'s `.cpp` and `.h` files, `third_party` excepted, as `FlNativeSource`
|
||||
items, read through the scanner's `SQAdditionalAnalysisFileItemTypes`. The items exist only in a build the scanner
|
||||
instruments (its ImportBefore targets set `SonarQubeTempPath`), so a normal build, an IDE and a publish never see them;
|
||||
because they lie outside the project's folder, the scanner analyses them at the root, with the compilation database:
|
||||
MSVC's own flags and defines, where Automatic Analysis guessed them. Native code has no coverage report (below).
|
||||
|
||||
**Coverage.** `build.ps1` collects `"XPlat Code Coverage;Format=cobertura,opencover"`: Cobertura for
|
||||
`tools/coverage-gate.ps1`, as before, and OpenCover for SonarCloud, whose C# importer reads no Cobertura. The
|
||||
reports' paths are absolute, and every hosted Windows runner checks out to the same path, so the reports `check`
|
||||
wrote name the sources this job reads. Only `tests/*/TestResults/<guid>/` is read; the trx logger's second copy under
|
||||
`In/` is not. **Coverage is the C#'s alone** (`sonar.coverage.exclusions`): SonarCloud counts the executable lines of
|
||||
a file no report covers as uncovered — the first pull request analysis read `build.ps1`'s 232 lines to cover, every
|
||||
one uncovered, and failed the gate at 0 % on the two it changed — so the PowerShell tools (proven by their own
|
||||
`-SelfTest` cases, which no coverage tool reads) and the native code (Catch2 and the injection tests, with no coverage
|
||||
collector) are left out of the coverage figures; they are analysed for issues as everything else is. Measuring the
|
||||
native code would be the runner's Visual Studio coverage tool and `sonar.cfamily.*` coverage paths — not done.
|
||||
|
||||
**The version, and so the new code.** The project's new-code period is SonarCloud's *Previous version*. Until now
|
||||
every analysis was "not provided", so the new code was everything since the first analysis (2026-09-27): 34,268 lines
|
||||
on 2026-10-20. The job now passes `/v:` the newest `v*` tag the commit descends from, so new code is everything
|
||||
since the last release — **from the second analysis with a version on**, measured on `main` (below): the first,
|
||||
`main`'s first from CI, still counted from before any version existed; the second set the start at the last analysis
|
||||
without one (2026-10-20 05:11; 257 new lines on 2026-10-25). An issue the CI analysis raises on an older line is
|
||||
dated by blame — the newest line of its path — and is new code only when that line is. The gate is *Sonar way*: its
|
||||
coverage condition (80 % on new code) was skipped while no analysis had coverage, and applies from the first analysis
|
||||
from CI.
|
||||
|
||||
**What it reads** — `SonarQube.Analysis.xml`: the exclusions of `.sonarcloud.properties` (below) and what a build
|
||||
writes into the checkout, since the scanner walks all of it (`build/`, with the sources CMake fetches there, `out/`,
|
||||
every `bin/` and `obj/`, `TestResults/`) — SonarCloud also drops what `.gitignore` names (the first run: "63 files
|
||||
ignored because of scm ignore settings"), and the patterns say it in the file rather than rely on that; the same
|
||||
duplication exclusions *(and, since 2026-11-12, `src/FrameLedger.Domain/Metrics/HookFamilies.cs`: the Domain's
|
||||
mirror of `FlHookFamily`, the same enum twice by design and held together by `MetricEnumMirrorTests`. The six
|
||||
members 0.1.0-beta.45 added to both were 3.7 % duplication on new code against the gate's 3 %, and failed the gate
|
||||
on the release's commit with no issue open)*; C++20; UTF-8; the OpenCover paths; the compilation database;
|
||||
**`sonar.cs.roslyn.ignoreIssues`** — Roslynator, Meziantou, the VS threading and the .NET
|
||||
analyzers already gate the build, warnings as errors, and what they report at a lower severity is this project's
|
||||
choice, so only SonarCloud's own rules are imported; and **two rules ignored where they apply by design** — `S8417`
|
||||
(sequentially consistent atomics) in `src/native`, any repository because a header is indexed as C, and
|
||||
`csharpsquid:S6640` (unsafe code) in Infrastructure and Shared. Those are the optional rows of the owner's steps below,
|
||||
which the UI's *Ignore issues on multiple criteria* would have held; a pull request adding atomics no longer fails the
|
||||
gate on them.
|
||||
|
||||
**What it does not cover.** A fork's pull request and Dependabot's get no secrets, so the job is skipped for them;
|
||||
Dependabot's would run if the owner added `SONAR_TOKEN` to the repository's *Dependabot secrets*. A pull request's
|
||||
analysis lists only the issues on the lines it changed, and no other branch can be analysed (above), so what the
|
||||
analysis from CI finds in the older code shows on `main`'s first analysis from CI and nowhere before it.
|
||||
|
||||
**The first analyses (2026-10-25, PR #334).** Run 40147463349: the scanner began, the build ran, the C# coverage was
|
||||
imported (635 files) — and CFamily stopped on the `.modmap` response files (step 3). Run 40148541525, with scanning
|
||||
off: everything analysed — 1,300 files indexed, 249 left out by the exclusions and 63 by `.gitignore`; of the
|
||||
compilation database's 181 units, 32 analysed in full (none partly; 118 whose sources are not analysed — the vendor
|
||||
stubs and what CMake fetched, Catch2 and MinHook —, 18 duplicates, 13 it does not support) in 139 s; 21 C and 32 C++
|
||||
files indexed (a `.h` is C to SonarCloud) — and the
|
||||
gate failed on two conditions, both fixed the same day: `githubactions:S8264` (a C security rating: workflow-level
|
||||
permissions reaching both jobs) and 0 % coverage on new code (`build.ps1`'s lines, before the coverage exclusions).
|
||||
A dispatch of the branch (40148544753) analysed it and was refused the gate, which is how the plan's limit was found.
|
||||
|
||||
**`main`'s first analysis from CI (run 40160302893, the merge of #334).** The gate failed on one condition, a C
|
||||
reliability rating on new code, and passed the others (84.7 % coverage on new code). The 34 open issues were all C++,
|
||||
raised there for the first time — the real MSVC flags let CFamily see them — and each dated by blame, 2026-08-02 to
|
||||
2026-10-19. Two were new code: `hook-harness`'s null dereferences, whose paths reach lines changed on 2026-10-19 — two
|
||||
MAJOR bugs, so C; the BLOCKERs were older lines. (A pull request's analysis never showed any of them: it reports no new
|
||||
issue on an old line.) The next analysis, the merge of #335 at 05:20, moved the new code's start to 2026-10-20 05:11
|
||||
and turned the gate green with nothing fixed; the merge of #336 at 06:17 closed 33 of the 34. The 34th, `S3519` in
|
||||
`fl_patch_check.h`, stayed open: its `NOSONAR` sat on `p -= 5`, and SonarCloud reports the read on the line after —
|
||||
moved there by the release pull request. The C# had none open. Beta.29 PR-3 settled them — fixed where the code was
|
||||
wrong, `// NOSONAR` with its reason above it where the analyser was (five):
|
||||
|
||||
| Rule | Where | n | What it was | Done |
|
||||
|---|---|---|---|---|
|
||||
| `cpp:S2275` format/argument | `fl-probe-nvapi` | 19 | `%u` for `NvU32`, an `unsigned long` (32 bits on Windows, so nothing printed was wrong) | `%lu`; the machine line `CaptureHost` parses prints the same |
|
||||
| `cpp:S2259` null dereference | `hook-harness` `main.cpp` ×2, `proxy_swapchain.h` | 3 | **real:** `--vulkan` and `--opengl` create no D3D11 objects, and `--opengl` alone ran the default probes through a null swapchain, as did any D3D11 mode beside either flag | `HaveD3D11`, asked first by every mode that drives the D3D11 swapchain; the duplicate mode flags are one |
|
||||
| `cpp:S2259` | `fl_ring.h` `Publish` | 1 | the path runs on past a failed `REQUIRE(w.Init(...))` in `ring_test`, which ends the test case; every real caller publishes through a writer whose `Init` succeeded, before any hook is installed | `NOSONAR` — a comment on the per-present path, no code |
|
||||
| `cpp:S3519` negative offset | `fl_patch_check.h` | 1 | by design: the 5 bytes before a hot-patchable function are its patch area, which the check reads under `StillOurs`' SEH guard | `NOSONAR`, no code |
|
||||
| `cpp:S6232` union pun | `dllmain.cpp`, the log's QPC epoch | 2 | `LARGE_INTEGER f{}` makes the union's first member, the `LowPart`/`HighPart` struct, the active one, so reading `QuadPart` reads a member that is not — undefined in C++, whatever `QueryPerformanceFrequency` wrote | initialised through the member read, `{.QuadPart = 0}` |
|
||||
| `cpp:S6232` | `guard_test.cpp` | 2 | a `ULARGE_INTEGER` to take a second off a `FILETIME` | 64-bit arithmetic on the two halves |
|
||||
| `cpp:S5813` `strlen` | `guard_test.cpp` | 1 | `strlen` of a fixed-size rules value | `strnlen(…, kMaxValueLen)` |
|
||||
| `cppsecurity:S9340` index from input | `layer.cpp`, `fl-baseline-probe` | 2 | the terminator written at the count `ReadFile` / `fread` returned, which never exceeds the request | the bound tested first (in the layer, its once-per-process enable-list read — whose `LARGE_INTEGER size{}` drew this PR's own `S6232` twice, and is initialised through `QuadPart` too) |
|
||||
| `cppsecurity:S5145` log injection | `rules_budget_test.cpp`, `fl-baseline-probe` ×2 | 3 | console output of a test and a probe: four numbers, and the ids of the seed rules file fixed at build time | `NOSONAR` |
|
||||
|
||||
**The C# gate is the server's profile, not the analyser's defaults.** SonarCloud applies *Sonar way core* here (166 C#
|
||||
rules, 176 C++). A local build with the `SonarAnalyzer.CSharp` package and its own default rules reports about 240
|
||||
findings in this code, nearly all from rules that profile does not activate (`S3358`, `S6667`, `S3267`, `S108`,
|
||||
`S3236`, `S2094`, `S927` among them); chasing them changes code for nothing the gate reads. What counts is
|
||||
`api/issues/search` for `main` or the pull request.
|
||||
|
||||
### Until 2026-10-25 — Automatic Analysis, no workflow (beta.24, owner decision D67)
|
||||
|
||||
*The text from here to the end of this section stood as written; what changed is marked.* ~~The project
|
||||
`poli0981_frameledger` is analysed by SonarCloud's GitHub app in **Automatic Analysis** mode: on every~~ The project
|
||||
`poli0981_frameledger` was analysed by SonarCloud's GitHub app in **Automatic Analysis** mode: on every
|
||||
push to `main` and on every pull request, with no workflow in this repository and no logs published. Its check on a
|
||||
pull request (*SonarCloud Code Analysis*) is advisory — it is not a required status.
|
||||
|
||||
**What it reads is set by `.sonarcloud.properties`** at the root, the only file Automatic Analysis reads, from the
|
||||
default branch. It excludes what is not FrameLedger's code or not code: the vendored SDK headers under
|
||||
`src/native/third_party/` (51 headers, 66 thousand lines — before this file they were 41.7 thousand of the project's
|
||||
94 thousand counted lines, classed C), the generated `Strings.Designer.cs` and `dxr_raygen_dxil.h`, the vendor stubs
|
||||
(fixtures that carry the vendors' export names on purpose), `tests/fixtures/`, the licence texts, the generated
|
||||
`docs/vendor-exports.json` and the SQLite migrations (a SQL analyser reads them as another dialect). It reports C++
|
||||
against C++20, the standard `src/native/CMakeLists.txt` sets. `build/`, `bin/`, `obj/` and `presentmon/` are
|
||||
git-ignored and never reach it.
|
||||
|
||||
**What it cannot do.** `sonar.issue.ignore.*` is not read by Automatic Analysis, so a rule this project breaks by
|
||||
design is recorded here and marked in SonarCloud's own UI — by the owner, who holds the account. A CI-based scan (the
|
||||
only way to import coverage or analyse one build variant of the C++) would mean turning Automatic Analysis off, a
|
||||
`SONAR_TOKEN` secret, OpenCover output beside today's Cobertura and a full-depth checkout; ~~it is not done~~ *done
|
||||
2026-10-25 (D68, above)*.
|
||||
|
||||
**The triage of 2026-10-19** — the analysis of `main` at `372389c` (2026-09-28; nothing had been analysed since),
|
||||
341 open issues, none resolved. Rules broken by design are *Accept*ed and false positives marked as such, each with
|
||||
the comment below; the rest are fixed in the same train (beta.24 PR-2).
|
||||
|
||||
| Rule | Issues | Verdict | Comment for the UI |
|
||||
|---|---|---|---|
|
||||
| `cpp:S8417` atomics should be sequentially consistent | 225 | **Accept** — by design | The SPSC ring and the hook counters use explicit acquire/release and relaxed orders on purpose (`07_IPC`); sequential consistency would add fences on the per-present path. |
|
||||
| `csharpsquid:S6640` unsafe code blocks | 31 | **Accept** — by design | Interop with the native layer and the shared-memory mirror, confined to `Infrastructure` and `Shared` (CLAUDE.md: the native layer is reachable only through `Infrastructure`). |
|
||||
| `cpp:S6232` union type-punning | 24 | **False positive** | `LARGE_INTEGER.QuadPart` is how the Windows API returns the value. |
|
||||
| `cpp:S5813` bounds when computing string length | 19 | **Accept** for the 17 below; the 2 with a buffer bound at hand were bounded (beta.24 PR-2: `FlGuardRulesFilePath` reads `wcsnlen(out, cap)`, the NVAPI bridge `strnlen` over the driver's `NvAPI_ShortString`) | Every string measured is NUL-terminated by construction — see the list under this table. |
|
||||
| `csharpsquid:S2077` dynamic SQL | 3 | **False positive** | A `PRAGMA` argument cannot be bound; the values are an `int` and closed sets of constants (`wal_checkpoint` mode, the tri-state column), never user text. |
|
||||
| `cpp:S935` `FlGetBuildId` returns no value | 1 | **False positive** | `FL_BUILD_ID` is defined by the build (`12_BUILD` §Version); the analysis compiles without it. |
|
||||
| `cpp:S3519` out-of-bounds `memcpy` | 1 | **False positive** | `fl_patch_check.h` reads the prologue of a function this DLL hooked, under SEH, by design (`17_HOOK_ENGINE` §Unhooking). |
|
||||
| `cpp:S836` garbage value returned | 1 | **False positive** | `hook-harness`'s `VtableOf` reads the vtable of a COM object it created itself. |
|
||||
| `csharpsquid:S3869` `DangerousGetHandle` | 1 | **Accept** | `ParentDump` passes the dump file's handle to `MiniDumpWriteDump` inside the `using` that owns the stream, on the same thread, so it cannot be released during the call; CsWin32 generates no `SafeHandle` overload here (`NativeMethods.json`: `useSafeHandles: false`). **Raised again 2026-11-12:** #398 moved that call into `TryWriteOnce` (the dump is now tried three times), and SonarCloud tracks an issue by where it is — the accepted one closed and a new one opened on the same expression, as a blocker on new code. Nothing about the call changed; it is to be accepted again (HANDOFF owner-only item 38 (j)). |
|
||||
| `cpp:S1669`, `cpp:S6191`, `csharpsquid:S4036`, `githubactions:S7637`, `csharpsquid:S2190`, `S3427`, `S8949` | 35 | **Fixed** in beta.24 PR-2 — 5 of the 23 `S1669` were in the vendored Vulkan headers and leave with the exclusions | — |
|
||||
|
||||
**`cpp:S5813`, the 17 accepted, and why each string is terminated** (lines as of beta.24):
|
||||
|
||||
- `fl_ac_rules.cpp` — `IStartsWith`/`IContains` (`:38`, `:43-44`) and `TokenIs` (`:74`) measure rule fragments and
|
||||
literals the guard itself holds; `:151` and `:288` measure a value `CopyToken` has just written, which refuses a token
|
||||
that does not fit and always writes the terminator; `CopyLiteral` (`:176`) measures a compiled literal; `:834`
|
||||
measures `SHGetKnownFolderPath`'s answer, terminated by the API.
|
||||
- `fl_guard.cpp:109` — the guard's own DLL path, built and terminated by its caller before injection.
|
||||
- `fl_guard_sources.cpp` — `:345` measures the executable's path the guard read itself and walked to its terminator
|
||||
in the loop just above; `:753` the install root the guard resolved from it; `VdfValue` (`:582`) measures the
|
||||
compiled keys its callers pass (`"installdir"`, `"appid"`), and `AllDigits` (`:617`) a value `VdfValue` copied with
|
||||
its own bound.
|
||||
- `fl_prescan.cpp` — `IsKernelDriverName` (`:40`) measures a name the directory walk handed over terminated;
|
||||
`SegmentIs` (`:181`) a literal; `:337` the executable's folder the pre-scan built itself.
|
||||
- `layer.cpp:99` (the Vulkan layer) — a leaf of `GetModuleFileNameA`'s result, which the line above has already
|
||||
checked is shorter than `MAX_PATH`, so it is terminated.
|
||||
- `fl-baseline-probe/main.cpp:55` — a literal (a developer probe, not shipped).
|
||||
|
||||
**The six left open after the trains (2026-10-19, beta.26)** — the analysis of `main` at `e35b971` (0.1.0-beta.25),
|
||||
after the owner's marking: 366 issues resolved (284 fixed — the exclusions and beta.24 PR-2 —, 49 accepted, 33 false
|
||||
positives) and six open, all in the new-code period, which is why its quality gate read C for reliability and security.
|
||||
Five were written after the analysis of `372389c` the table above was built from.
|
||||
|
||||
| Rule | Issues | Verdict | Comment for the UI |
|
||||
|---|---|---|---|
|
||||
| `csharpsquid:S3869` `DangerousGetHandle` | 1 | **Accept** — the row above | as above |
|
||||
| `csharpsquid:S1244` floating-point equality | 4 | **False positive** | Exact on purpose. `ColorMath.Hsv` compares `max` with `r` and `g` — `Math.Max` returned one of them, the same double; `MarkdownView`'s `next == _wheelTarget` is true only when `next` was assigned `_wheelTarget` (the snap that ends the easing); `SensorsChart.Line`'s `scale == 1.0` compares a parameter with its own default literal to skip a copy. |
|
||||
| `githubactions:S7631` untrusted code from a fork | 1 | **False positive**, and hardened in beta.26 | `wiki.yml` checks out `workflow_run.head_sha` only after a successful Release run started by a pushed `v*` tag, which a fork cannot start; since beta.26 it also requires `workflow_run.head_repository` to be this repository. |
|
||||
|
||||
**Marked by the owner the same day** (2026-10-19, 14:27–14:29 UTC), each as the table says: the four `S1244` and
|
||||
`S7631` as false positives, `S3869` accepted. `main`'s next analysis (`6b07eb2`) has no open issue and its quality gate
|
||||
passes.
|
||||
|
||||
**The owner's steps** after the next analysis of `main`: for each rule above, open
|
||||
`https://sonarcloud.io/project/issues?id=poli0981_frameledger&resolved=false&rules=<rule>`, select all, *Bulk change*,
|
||||
choose *Accept* or *False positive* and paste the comment. Optionally, *Administration ▸ General Settings ▸ Analysis
|
||||
Scope ▸ Ignore issues on multiple criteria*: `cpp:S8417` and `cpp:S6232` on `src/native/**/*`, `csharpsquid:S6640`
|
||||
on `src/FrameLedger.Infrastructure/**/*` and `src/FrameLedger.Shared/**/*`, so new instances of the by-design rules
|
||||
stop reappearing on pull requests. *(Since D68 the `S8417` and `S6640` rows are `SonarQube.Analysis.xml`'s, in the
|
||||
repository; `S6232`'s are not — a union read outside `LARGE_INTEGER` would be a finding — and its 24 stay marked.)*
|
||||
|
||||
## Qodana — `qodana.yml`, a workflow of its own (owner decisions D93, 2026-11-10; D99 and D100, 2026-11-11)
|
||||
|
||||
**Since 2026-11-11 the linter is Qodana for .NET, on the Ultimate licence (D99).** The owner took an Ultimate licence for
|
||||
the Qodana Cloud organisation and asked for Qodana over every language. So the linter is **Qodana for .NET**
|
||||
(`qodana-dotnet`: Rider's engine) where it was the Community one, in **native mode** on a Windows runner: no container,
|
||||
the projects built and loaded with the SDK the job installs from `global.json`, and no `EnableWindowsTargeting`.
|
||||
`qodana.yaml` names the linter and the mode (`withinDocker: false`); nothing is an action argument, so `qodana scan` on
|
||||
a developer's PC reads the same file. The job is `managed` — *Qodana (managed)* in a pull request's checks: checkout,
|
||||
`setup-dotnet`, the NuGet cache restored, `dotnet build -c Release` first — so that a build that fails is one red step
|
||||
with the compiler's own message, not a report of unresolved symbols — then the action, pinned by commit. No MSVC step,
|
||||
on purpose: it exports `Platform=x64`, which MSBuild reads as a solution platform. The linter's log says what the token
|
||||
bought: "Qodana license plan: Ultimate", and the Qodana Cloud project it is linked to (`frameledger`). Still advisory,
|
||||
still a gate of zero, still `main` and its pull requests alone. From here down to *As it was built* is the job as it
|
||||
is; below that is D93's own account, which is now history.
|
||||
|
||||
**Two reports (D99).** Asked how to gather the C# and the C++, the owner chose two reports from the start, and made a
|
||||
second Qodana Cloud project (`frameledger-cpp`, the `QODANA_TOKEN_NATIVE` secret). The managed report leaves
|
||||
`src/native` out; the native one (*The native report*, below) reads nothing else, so every file is in exactly one.
|
||||
|
||||
**What is read, and by what.**
|
||||
|
||||
| What | Read by | |
|
||||
|---|---|---|
|
||||
| The C#, XAML and `.resx` of the thirteen projects | `managed` | ReSharper's engine, as under D93 |
|
||||
| Markdown and XML around the solution | `managed` | the IntelliJ platform's own inspections — 23 and 10 results on the first run |
|
||||
| JetBrains' security rules over the C# — pattern rules for a process start, an SQL text and the like | `managed` | new with this linter (its OpenGrep plugin) — 36 results on the first run, every one read; the files they were read in are listed in `qodana.yaml`, so a new one is reported |
|
||||
| The C++ of `src/native` | `native` | ReSharper's C++ engine and the clang-tidy checks it bundles, over a Visual Studio solution CMake writes for it |
|
||||
| JSON and YAML, the workflows among them | nothing reported | whether the profile inspects them and found nothing, or does not inspect them, was not established; CodeQL's `actions` language reads the workflows |
|
||||
| PowerShell (`build.ps1`, `tools/`), CMake files, the HLSL shader | no linter of JetBrains' reads them here | SonarCloud reads the PowerShell |
|
||||
|
||||
**The first runs on this linter, and what was done (2026-11-11).** Run 42923079119 — the job with no settings beyond the
|
||||
solution: **3,953 problems** in 92 inspections, and 3,607 of them **hints**: the lowest level an IDE has, which the
|
||||
editor offers without underlining anything (this linter files them as `TYPO`, Qodana as *Low*). Meziantou's "name the
|
||||
parameter" 1,084 times, a trailing comma 979, a XAML binding whose `DataContext` the engine cannot know 414, the MVVM
|
||||
Toolkit's partial-property proposal 224, "invert `if`" 114 — and every other Roslyn analyzer message below the level
|
||||
this build makes an error. **Hints are off as a severity**, one group in `qodana.yaml` (`severity:TYPO`): the Community
|
||||
linter never reported them, and D93's rule is about warnings and suggestions. With that, run 42928814104: **347**.
|
||||
|
||||
| What | n | Done |
|
||||
|---|---|---|
|
||||
| `OverriddenWithSameValue` — a vi or ja value equal to the English one | 271 | off in `.editorconfig` (`[*.resx]`): product and technology names, units and format strings are not translated, and a ja safety string is the English verbatim until a reviewer signs it |
|
||||
| `csharp_injection_rule-CommandInjection` — a process started with something that is not a literal | 35 | **read, one by one** (below): 11 places in `src`, 24 in tests; one place was hardened. The rule stays on, and the files read are left out of the plugin's inspection by path in `qodana.yaml` (*How the security rules are scoped*, below), so a new file that starts a process is reported |
|
||||
| `MarkdownIncorrectTableFormatting` | 20 | off in `qodana.yaml`: Rider wants columns padded to one width; these tables are written to be diffed |
|
||||
| `XmlHighlighting` in `src/FrameLedger.App/app.manifest` | 10 | that file ignored for that inspection: the linter has no schema for a Windows application manifest |
|
||||
| `UnusedVariable.Compiler` and `RedundantUsingDirective` in `PrimaryDisplay.cs` | 6 | **the linter's own fault**, and the file is left as it is: resolving `PInvoke.EnumDisplaySettings(null, …)` — the `null`-to-`PCWSTR` conversion — the engine of this linter's build (QDNET-262.12299) fails an internal assertion (`IsStandardImplicitConversionFromExpression(conversion.Kind)`, in its `backend.log`), loses the method, and reports its three locals and the file's three usings as unused. The compiler builds the file with warnings as errors, and InspectCode 2026.2.3.1 and 2026.3.0 report nothing in it. Those two inspections are excluded for that one file in `qodana.yaml`, to be removed when a linter build reads it |
|
||||
| `MarkdownUnresolvedHeaderReference` | 3 | off in `qodana.yaml`: all three resolve on GitHub, whose anchor rule the linter does not follow (`#display-mode--both-tiers-beta10`) |
|
||||
| `csharp_injection_rule-SQLInjection` | 1 | the same: the one place assigns a constant command text and binds every value as a parameter, as every statement in this repository does; its file is listed with the others |
|
||||
| `RedundantBoolCompare`, in a test | 1 | fixed — the expression also carried a clause its first half implied |
|
||||
|
||||
With those settled, run 42940926340 (2026-11-11, this pull request's branch, the whole solution): **no problem
|
||||
reported** — the gate's zero, on this linter.
|
||||
|
||||
**How the security rules are scoped — by the plugin's one inspection, not by a rule.** Every result of the
|
||||
OpenGrep plugin's several hundred rules is produced by one inspection, `OpenGrepInspection`; a rule's own id
|
||||
(`csharp_injection_rule-CommandInjection`) is in the report and is honoured nowhere. Three runs measured it — a
|
||||
profile entry's `ignore` (42932842462), an `exclude` path under the rule's id (42935752891), `enabled: false`
|
||||
on the rule (42938295264): all 36 results stood each time, and the linter's log shows why — the plugin hands its
|
||||
server every rule file whatever the profile says. What the plugin's inspection does honour is a path: an
|
||||
`exclude` entry named `OpenGrepInspection` (its scopes are in the report's `log/effective.profile.xml`). So the
|
||||
eleven files of `src` the results were read in, and `tests`, are listed there — and in the run above the
|
||||
inspection was performed on 943 files, where it had been 1,308, and reported nothing: it is on, and it reads
|
||||
what is not listed. The price is stated in `qodana.yaml`: a listed file is left out of **all** of the plugin's
|
||||
rules, not only the one that fired. The plugin is also most of the job's time — about six of its fifteen
|
||||
minutes.
|
||||
|
||||
**A second tripwire, in the gate: `ProcessStartSitesTests`.** Qodana is advisory, and its rule is a pattern for
|
||||
`Process.Start`. The test sweeps `src` for every way a process is started here — `Process.Start`, a
|
||||
`ProcessStartInfo`, `CreateProcessWithTokenW` through CsWin32, and the registration of the logon task — and fails
|
||||
on a file that is not in its list, until that file has been read and listed. `Startup/UnelevatedProcess`, which
|
||||
the rule never saw, is in it.
|
||||
|
||||
**Every place that starts a process, as read on 2026-11-11.** The rule is a pattern, not a data flow: it reports any
|
||||
`Process.Start` whose argument is not a literal. What matters at each is what is started and where its path and
|
||||
arguments come from.
|
||||
|
||||
| Place | What it starts | Where the path and the arguments come from |
|
||||
|---|---|---|
|
||||
| `App/Services/AgentLauncher` | `FrameLedger.Agent.exe` | the file beside the App (`AppContext.BaseDirectory`); arguments the App builds (`--serve`, the data folder) |
|
||||
| `App/Services/AgentTool` | the same Agent, with one maintenance flag | a constant at each of its two callers (`--install-task`, the Settings page's flags) |
|
||||
| `Infrastructure/Startup/AgentElevation` | the Agent, elevated (`runas`) | the Agent's own path; `--serve --for-user <this user's SID>` |
|
||||
| `Infrastructure/Startup/LogonTask` | nothing itself — it registers the logon task, whose action Windows starts at sign-in | the Agent's path and constant arguments (`--serve`), into a Task Scheduler definition for this user, at the lowest privileges |
|
||||
| `Infrastructure/Diagnostics/CrashDumpWriter` | this process's own executable, as the dumper | `Environment.ProcessPath`; an `ArgumentList`, no shell |
|
||||
| `Infrastructure/Capture/ProcessLauncher` | the game | the executable the user added and enabled hooking for, and the launch arguments the user wrote for it; no shell |
|
||||
| `App/Services/ShellStarter` | a game, directly or through its store (`steam://…`, `explorer.exe shell:AppsFolder\<AUMID>`) | the launch `GamePlayer` resolves from the record of a game the user added (D59, D80) |
|
||||
| `App/Services/Explorer` | `explorer.exe` on a folder or a file | a quoted path of FrameLedger's own: the data folder, the logs, a bug report's zip, the licences folder |
|
||||
| `App/Services/ShellUrlOpener` | the browser or the mail client | the project's own pages, or a Markdown link `MarkdownLinks` has already held to `http`, `https` and `mailto`. **Hardened here**: the opener now refuses any other scheme itself (`ShellUrlOpenerTests`) — the shell runs whatever it is handed, and a `file:` address is a program |
|
||||
| `App/ViewModels/SettingsViewModel` | the browser | one constant address |
|
||||
| `Infrastructure/Startup/UnelevatedProcess` | the Agent or a game with the shell's token, from an elevated process (`CreateProcessWithTokenW`) | its two callers above, `AgentLauncher` and `ProcessLauncher` — not a `Process.Start`, so the rule did not see it; the sweep does |
|
||||
|
||||
None takes a value from outside the PC or from a file FrameLedger did not write, except the game's own path and
|
||||
arguments — which starting the game the user chose is.
|
||||
|
||||
**The native report — `qodana-native.yaml`, the job `native` (D99, 2026-11-11).** The C++ of `src/native`, read by
|
||||
the same linter — Qodana for .NET, whose C++ is ReSharper C++ — in native mode on a Windows runner. It is the only
|
||||
linter of JetBrains' that can: the native layer is MSVC-only, and the two C/C++ linters (`qodana-cpp`,
|
||||
`qodana-clang`) are Linux images. It reads C++ through a Visual Studio solution, and `src/native` is a CMake tree, so
|
||||
the job has CMake write one first: the preset **`x64-vs-analysis`** (generator "Visual Studio 18 2026", tests and
|
||||
tools on) puts `FrameLedgerNative.slnx` under `build/native/x64-vs-analysis`, and the job builds from it the one
|
||||
target whose output is a header (`fl_ac_floor_gen`, the blocklist floor). Nothing else is compiled, and nothing from
|
||||
that tree ships. Then the action, with `--config qodana-native.yaml`: the solution, `RelWithDebInfo` and `x64` — the
|
||||
flags the shipped binaries are built with — and, left out by path, what is not FrameLedger's code (the build tree,
|
||||
`third_party`, the vendor stubs, a compiled shader as a byte array). Its own results folder, cache keys and artifact
|
||||
(`qodana-report-native`), and the Qodana Cloud project `frameledger-cpp` through `QODANA_TOKEN_NATIVE`. It posts no
|
||||
comment and no annotations — a second job of the same linter would overwrite the managed job's — so its result is the
|
||||
job's own status and its report. Advisory, and a gate of zero, like the other.
|
||||
|
||||
**What it runs** is ReSharper's C++ inspections and, through them, the clang-tidy checks and clang diagnostics that
|
||||
engine bundles. clang never builds this code — MSVC does, with `/W4 /WX` — so what clang says is read as advice. Every
|
||||
one of them has a key in `.editorconfig` (`resharper_cpp_…_highlighting`; a clang-tidy check's is
|
||||
`resharper_cpp_clang_tidy_<check>_highlighting`), so D100's rule holds without a second file: no `.clang-tidy`.
|
||||
|
||||
**Its first runs, and what was done.** Run 42923079119: **4,695 problems**, 4,040 of them hints, which are off as on
|
||||
the managed side. Run 42928814104: **655** — **494 distinct**, because a source file compiled into three targets is
|
||||
reported three times.
|
||||
|
||||
| What | distinct | Done |
|
||||
|---|---|---|
|
||||
| A choice this code made, off for the native tree: where the compiler pads a struct (46); MSVC's own keywords, `__try` among them (54); a function pointer got by name cast to its real type, through `void*` (55); `reinterpret_cast` where memory is read as something else (5); `std::cmp_less` proposed for comparisons that already cast (20); a `default:` under a full enum switch (3); a copied verdict (4); the moves of a type that owns a handle (11); a zeroed out-parameter enum (8); an enum's width (5); "can be made const / constexpr / static" (52); "possibly unused `#include`" (15) | 278 | off in `.editorconfig`, each with its reason. Of the fifteen includes two were unused and were removed; the others are a file including what it uses although another header already brings it |
|
||||
| A newer idiom proposed for working code — a range-for, `std::ranges`, `any_of`, `starts_with`, a raw string, an `if` with an initialiser | 53 | off: the native code is written to be read beside the hook path, an index and a plain loop |
|
||||
| **The engine misreading**: `std::atomic_ref<T>::fetch_or` as an expression without side effects (7); a Win32, D3D12 or ffx-api structure zero-initialised and then filled field by field as "always rewritten" and "assigned, never used" (15); a test of a `constexpr` function as a redundant argument (3) | 25 | off, with what the engine gets wrong written beside the keys |
|
||||
| Fields nothing names, in a structure Windows defines and the SDK's headers do not give (`RTL_PROCESS_MODULE_INFORMATION`, `PROCESS_MEMORY_COUNTERS_EX2`) and in a test's stand-in for a Vulkan object | 25 | off for those four files: the fields are what puts the others at their offsets |
|
||||
| `%lu` with an `NvU32`, in `fl-probe-nvapi` | 19 | off for that file: NVAPI's header makes `NvU32` an `unsigned int` under clang and an `unsigned long` under MSVC — the linter's compiler, not the build's |
|
||||
| The probes, the harness and the tests: an unchecked `printf` (35), `atoi` on the harness's own arguments (20), a `&pointer` handed to a `void*` parameter (7), a printf-shaped helper (4), a fake handle built from a number (4), a test's fixtures (4), `layout_test`'s run-time checks of compile-time facts (3), a macro that pastes a name (1) | 78 | off for `tools` and `tests` |
|
||||
| Code loaded into a game (below) | 7 | kept as it is, off for those files; one of them is dead code, recorded for the owner |
|
||||
| **Fixed**: `sizeof(a) / sizeof(a[0])` → `std::size(a)` (4); a multiplication done in a narrower type than the one it is stored in or compared with (2: a constant in the guard's sources, a test); a member function, and a type alias, nothing used (3) | 9 | in the code; none changes what a shipped binary does |
|
||||
|
||||
With those settled, run 42942068024 — the first with these settings — reported **one** problem: `LogNoteW`, now by
|
||||
ReSharper's own inspection where clang's had said it before (below). And run 42943094415 (2026-11-11, this pull
|
||||
request's branch): **no problem reported** — the gate's zero, in the native report too.
|
||||
|
||||
**Code loaded into a game — the Overlay, the Vulkan layer, the shared-memory headers, the guard's rule matcher.**
|
||||
D100: there only a defect is fixed, in a pull request of its own with the hook's overhead measured (rule 5,
|
||||
`14_TESTING` §Hook overhead), and a proposal about style is not acted on. About a quarter of the 655 results were in
|
||||
those files; nearly all of them are the tree-wide kinds above. **The report found no defect there.** What is
|
||||
particular to them, read and kept: two `if` chains whose arms have the same body and are different cases, each with
|
||||
its comment (`dllmain.cpp`); MinHook's `MH_ALL_HOOKS`, which is `NULL` by its header; a retired enumerator kept so
|
||||
that its bit is not reused; `slSetTag`, deprecated by a header whose replacement no measured module exports;
|
||||
`ResolveTolerance` clearing its out-parameter with `memset`, as `ResetRules` does — a `Tolerance` is flags whose
|
||||
default initialisers are zero. And one thing that is not as it should be: **`LogNoteW` in `dllmain.cpp`, which nothing
|
||||
calls** — dead code. It is not a defect, so D100 leaves its removal to the owner (HANDOFF); until then that one file
|
||||
is not read for an unused function (`.editorconfig` says so, in a section to be removed with it).
|
||||
|
||||
**"Zero" has to mean "analysed".** A report with no problem cannot tell a clean tree from one the linter did not
|
||||
read. So the settings were proved on a branch that puts back three of the things fixed here — the unused alias, the
|
||||
unused member function, the narrow multiplication. Run 42942390715 reported exactly those three, each by the
|
||||
inspection that had found it the first time (`CppTypeAliasNeverUsed` in `tools/fl-probe-interposer/main.cpp`;
|
||||
`clang-diagnostic-unused-member-function` and `bugprone-implicit-widening-of-multiplication-result` in
|
||||
`tests/ring_test.cpp`), and `LogNoteW`, and nothing else. The branch was deleted. Do the same before trusting a
|
||||
zero after a change to the preset, the settings or the linter's version.
|
||||
|
||||
**What it does not read.** CMake files and PowerShell have no inspection in this linter (SonarCloud reads the
|
||||
PowerShell); the HLSL shader and the `.def` file are not C++. CodeQL (`analyze (cpp, manual)`, a required check) and
|
||||
SonarCloud go on reading the C++ as before: this is a third reader, and the only one of the three that is ReSharper's.
|
||||
|
||||
**Where an inspection is switched off: by the engine that raised it (D100, amending D93's "never in `qodana.yaml`").**
|
||||
What Qodana reports is fixed, unless the inspection argues with a choice this project made; then it is off, with the
|
||||
reason on the line above — in the place the engine that raised it reads:
|
||||
|
||||
- **ReSharper's** — the C#, the XAML, the `.resx`, and the C++ of the native report with the clang-tidy checks it
|
||||
runs — in **`.editorconfig`** (`resharper_*_highlighting`), where Rider and ReSharper in the editor read it too:
|
||||
sixty-four keys for the managed code, fifty-four lines for the C++, some of them for a folder or a file alone.
|
||||
- **What has no key there** — in **`qodana.yaml`**: a whole severity (the hints) and the IntelliJ platform's Markdown
|
||||
and XML inspections under `profile.inspections`; under `exclude`, by inspection and path, the files JetBrains'
|
||||
security rules were read in and a file the linter itself fails on.
|
||||
- **What is not FrameLedger's code** is left out by path (`exclude`): `SonarQube.Analysis.xml`'s list, for its reasons.
|
||||
|
||||
**What it does not use, and what happens if the licence lapses.** Quick-fixes (the linter would push commits — the job
|
||||
has no `contents: write`, and a change nobody read is not wanted), code coverage in Qodana (the gate's coverage and
|
||||
SonarCloud's already read the same reports) and FlexInspect are Ultimate features this job leaves alone. Without a
|
||||
valid licence the linter does not start, so the job is red — advisory, never a blocked merge; the way back is
|
||||
`linter: qodana-cdnet` with the job on `ubuntu-latest`, as it ran until beta.37.
|
||||
|
||||
**Running it on a developer's PC.** `qodana scan` in the repository root reads `qodana.yaml`, downloads the linter and
|
||||
needs the project's token in `QODANA_TOKEN` — the Ultimate linter checks the licence. Without a token, InspectCode
|
||||
still gives ReSharper's part (*As it was built*, below), with `--toolset-path` at the 11.0 SDK's `MSBuild.dll`; the
|
||||
Markdown, XML and security results are the Rider linter's alone.
|
||||
|
||||
**As it was built — the Community linter, 2026-11-10 to beta.37 (D93).** Kept as written; where it says *is*, read *was*.
|
||||
|
||||
**D93 — Qodana reads the C# and the XAML from CI.** The owner made the project on Qodana Cloud, set the `QODANA_TOKEN`
|
||||
secret (2026-11-10) and asked for Qodana in CI from the workflow JetBrains gives, changed where it had to be, with what
|
||||
it reports fixed. Asked which licence the Qodana Cloud organisation holds, the owner answered: a 30-day trial. So the
|
||||
linter is **Qodana Community for .NET** (`qodana-cdnet`) — ReSharper's InspectCode in a Linux container, which runs
|
||||
under every licence — and not Qodana for .NET (`qodana-dotnet`, Rider), which needs Ultimate and would turn the job red
|
||||
the day the trial ends. JetBrains calls the Community linter Early Access.
|
||||
|
||||
**How it runs.** `.github/workflows/qodana.yml`, on every pull request into `main` from this repository, every push to
|
||||
`main`, and by hand: a full-depth checkout of the pull request's own commit, then `JetBrains/qodana-action` pinned to
|
||||
the commit of `v2026.2.2` (the newest; the template names `v2026.1`, and every action that is not GitHub's own is pinned
|
||||
by commit here). The action brings the Qodana CLI of its own version, the CLI the linter's image
|
||||
(`jetbrains/qodana-cdnet:2026.2` — InspectCode 2026.2.3.1 on the image's .NET SDK 10.0.403), and the linter reads
|
||||
`qodana.yaml`: the solution (`FrameLedger.slnx`), the configuration (Release), the gate. It builds the solution itself,
|
||||
then inspects it — the whole solution every time (`pr-mode: false`), so a pull request and `main` are judged by one
|
||||
list. The report goes to Qodana Cloud, a summary to the pull request as a comment and annotations, and the SARIF and
|
||||
the linter's logs to the run as the `qodana-report` artifact.
|
||||
|
||||
**What had to change from the template, and why.**
|
||||
|
||||
- **`EnableWindowsTargeting=true`, passed to the container** (`env-vars-to-linter`). Every project here targets
|
||||
`net10.0-windows`, and the .NET SDK on Linux refuses such a project unless that property is set. With it, the
|
||||
container restores, builds and loads all thirteen projects — WPF's markup compiler and CsWin32's generator are managed
|
||||
code — which the first run showed (below). It is the workflow's, not `Directory.Build.props`': no build of the product
|
||||
is meant to run anywhere but Windows. JetBrains' own page says a project with an OS-specific target needs Qodana for
|
||||
.NET in native mode; that is the Ultimate linter, and the Community one did the work.
|
||||
- **`ubuntu-latest`, the one Linux job here** — the Community linter ships as a Linux image only.
|
||||
- **Permissions:** `contents: read`, `checks: write` (the annotations), `pull-requests: write` (the comment). The
|
||||
template's `contents: write` is for pushing quick-fixes, an Ultimate feature this job never uses.
|
||||
- **`main` only.** The `alpha` branch is main's source under another release line (§The alpha line); main's is what
|
||||
is analysed. *(Until beta.37 the reason was the alpha's prerelease .NET, which the image does not carry.)*
|
||||
- **Interim since beta.37 (D94, 2026-11-11): the .NET 11 SDK is installed into the container first.** Main builds on
|
||||
.NET 11 and the image carries the SDKs 8 to 10, so `qodana.yaml` has the `bootstrap` line JetBrains' page gives for
|
||||
an SDK the image lacks — `dotnet-install.sh` with `global.json`, into `/usr/share/dotnet`. It lasts until the
|
||||
Ultimate linter's pull request replaces this job with one on Windows, where `setup-dotnet` does it. Measured on its
|
||||
first run (#376, run 42916491047): the script installed SDK 11.0.100 beside the image's own, InspectCode 2026.2.3.1
|
||||
loaded and inspected all thirteen `net11.0-windows` projects, and it reported one problem — a redundant `!` in the
|
||||
test that pull request added, fixed there. So the 63 keys and the zero held across the move.
|
||||
- **Not a fork's pull request, nor Dependabot's:** neither gets the secret or a token that can write the comment.
|
||||
- **Caches are saved from `main` only** (`cache-default-branch-only`); a pull request reads them.
|
||||
|
||||
**What it reads, and what it does not.** The C# of the thirteen projects, their XAML and `.resx`. **Not the C++:**
|
||||
`src/native` is a CMake tree no solution names, and it is MSVC-only, which no Linux container compiles — CodeQL and
|
||||
SonarCloud read it. The native DLLs are absent in the container, so the `.targets` that copy them warn and the build
|
||||
goes on, as on a fresh clone (measured here the same day: `dotnet build` of a clean worktree, 15 warnings, 0 errors).
|
||||
|
||||
**The gate is zero, and it is advisory.** `qodana.yaml` sets `failureConditions.severityThresholds.any: 0`: one
|
||||
problem and the job is red. `main`'s required contexts stay `check`, `analyze (csharp, none)` and
|
||||
`analyze (cpp, manual)`, so a problem Qodana finds — or a Qodana Cloud outage — is a red job beside a green `check`,
|
||||
never a blocked merge. That it can fail was shown before it was
|
||||
relied on: run 42847369329 had the settings and none of the fixes, found 409 problems and ended red — "Detected 409
|
||||
problems across all severities, fail threshold 0".
|
||||
|
||||
**Where an inspection is switched off: `.editorconfig`, never `qodana.yaml`.** InspectCode reads its severities from
|
||||
`.editorconfig`'s `resharper_*_highlighting` keys, and so do Rider and ReSharper in the editor — one list for the job
|
||||
and for the person at the keyboard, beside the analyzer severities already kept there, and testable without CI. Each
|
||||
key has its reason on the line above it. The rule: **what Qodana reports is fixed, unless the inspection argues with a
|
||||
choice this project made** — then it is off, and the reason says which choice. Sixty-three keys, in these groups:
|
||||
|
||||
| Group | Inspections | The choice it argues with |
|
||||
|---|---|---|
|
||||
| The compiler's missing-XML-comment warning | `CS1591` | already a suggestion in this file; InspectCode reports suggestions — 2,050 of the first run's 3,679 |
|
||||
| Naming | `InconsistentNaming` | names follow this file's rule and the .NET analyzers'; ReSharper's scheme renames `OpenGL`, `XeSS`, `Presents5s` and every `Chart_*` resource key |
|
||||
| Unwrapping a nullable | `ConvertTypeCheckPatternToNullCheck`, `PatternAlwaysMatches` | `x is long v` and `x is > 0 and int v` name the type, as `csharp_style_var_for_built_in_types = false` asks |
|
||||
| What a guard is for | three `…AccordingToAPIContract` inspections | the compiler's nullable analysis is the gate; a dependency property, a JSON document and a WPF event hand over null whatever an annotation promises |
|
||||
| Said on purpose | `RedundantExtendsListEntry`, `RedundantArgumentDefaultValue`, `RedundantEmptySwitchSection`, `MemberHidesStaticFromOuterClass`, `CompareOfFloatsByEqualityOperator` | a code-behind names its base; an argument repeats a default it relies on; `default: break;` says the rest is left alone; exact float comparisons are with a copied value or a sentinel |
|
||||
| Not this code's to change | `UnusedParameterInPartialMethod`, `Xaml.StaticResourceNotResolved`, `Xaml.PossibleNullReferenceException`, `LocalizableElement` | CommunityToolkit's generated signatures; WPF UI's run-time resources (`PagesLoadTests` fails a wrong key); a binding through null shows nothing, by design; exception and log text is English (`09_I18N`), and `resx-audit` gates what a user reads |
|
||||
| Records | `NotAccessedPositionalProperty.*` | a positional property is part of equality and of what the record prints |
|
||||
| Style proposals | twenty, from `ConvertToPrimaryConstructor` to `UseAwaitUsing` | the style is this file, `dotnet format` and the analyzers; `await using` under CA2007 reads worse than what it replaces |
|
||||
| Accessibility proposals | `MemberCanBePrivate.*`, `PropertyCanBeMadeInitOnly.*`, `AutoPropertyCanBeMadeGetOnly.*` | a member's accessibility is what its type offers, not a count of today's callers |
|
||||
| "Never used" across the solution | eight `.Global` inspections | enum values mirror the native layout and stored columns, exception types carry CA1032's constructors, rows and messages are read by Dapper and System.Text.Json; the private kind (`.Local`) stays on — and what this group named on 2026-11-10 is listed below |
|
||||
| In `tests/` only | eleven | an assertion lambda runs inside the `using` it captures from; a test that dereferences null fails, which is its job; a test double keeps the shape of what it stands for |
|
||||
|
||||
Five places carry a `// ReSharper disable once …` comment with its reason instead, where the inspection is right in
|
||||
general and wrong once: the tolerance channel closed early in `CaptureSession`, the volatile read in
|
||||
`SessionEventPublisher`, the awaited `Task.Run` in `CaptureOrchestrator`, the window read lazily in
|
||||
`SessionSummaryOpener`, and a test row that is never on.
|
||||
|
||||
**The first run, and what was done (2026-11-10, PR #373).** Run 42842741359, the template's shape with no settings:
|
||||
the container built the solution and inspected it in under six minutes, and reported **3,679 problems** — 858 warnings
|
||||
and 2,821 suggestions, in 93 inspections. About 400 were fixed in the code, in 181 files, none changing what the
|
||||
software does:
|
||||
|
||||
| What | n | Done |
|
||||
|---|---|---|
|
||||
| Redundant qualifiers, casts, `using` directives, `!` suppressions, `unsafe` modifiers, tuple names | 290 | removed, by script from the report's own positions; the build (warnings as errors, Release and Debug) and `dotnet format` held every one — one cast of a pair in `SqliteGameMerge` was needed after all, and stayed |
|
||||
| `var` for a built-in type, a block body for a one-line method | 52 | this file's own style (`csharp_style_var_for_built_in_types`, `…expression_bodied_methods`), applied by `dotnet format` |
|
||||
| XAML bindings the inspection could not resolve | 35 | every item template names its `DataType`; a binding that reached the page through `DataContext.ViewModel` with `AncestorType=Page` names the page's type and its `ViewModel` — the same object at run time, and now navigable in the editor (`ViewerModeTests` pins the new text) |
|
||||
| Left over in the code | 12 | `LogsViewModel`'s unread `_strip` field and `PipeServer.Client`'s unread `_run`; two initialisers a constructor overwrote; `GameFileProbe.UnityDataFile`'s unused parameter; `SpokenTextAutomationPeer` no longer assumes `GetNameCore` returns a string; a redundant setter and two grid positions in XAML; a `$` on a string with no hole; `!Any(==)` as `All(!=)`; a `foreach` variable's type |
|
||||
| In the tests | 14 | unused variables, lambda parameters and an accessor; a linear `Contains` on a set; three simplifications |
|
||||
|
||||
The rest was settled by the settings above — 2,050 of it the one inspection the project had already made a
|
||||
suggestion. A suggestion to use `m[^1]` inside an expression tree was wrong (CS8790) and its inspection is off.
|
||||
|
||||
**The runs (PR #373).** 42842741359 — the template's shape, no settings: 3,679 problems, the job green (no gate yet).
|
||||
42847369329 — the settings and the gate, none of the fixes: 409 problems, every one in an inspection left on, the job
|
||||
red; so `.editorconfig`'s keys are read in the container as they are on Windows, and the 3,270 others were the
|
||||
settings'. 42849331796 — the fixes: **0 problems**, the job green; and `main`'s first run, the merge of #373
|
||||
(run 42852304026): 0 problems. A job takes about ten minutes.
|
||||
|
||||
**Named by the "never used" group and left as it is (2026-11-10).** Nothing in the solution, its tests included, uses
|
||||
these; whether each is vocabulary, a piece not wired yet, or dead is the owner's to say, so none was removed:
|
||||
`AtomicFileWrite` (the class and `PublishAsync`), `ExecutableMarkerScan` and `IExecutableMarkerScan.Scan`,
|
||||
`FpsPresentation.GeneratedLine`, `IPageNavigator.GoBack`, `OperatorDisclosure.VersionOf` and `ProvenanceOf`,
|
||||
`CrashReporterCatalog.AlwaysOn`, `ProcessWatcher.Tracked`, `LedgerWalCheckpoint.Complete`,
|
||||
`LhmTelemetryOptions.EnableCpuAndMemory`, `MeasuredFacts.StreamlineNoneWithheldFrom`, `ILegalAcceptanceStore.ListAsync`
|
||||
and `ITelemetryPoller.Dropped` (only their implementations are called), `DocumentBrowser.PageChanged` and
|
||||
`UrlOpener`'s getter, the charts' `PercentilePlot`, `NoteText` and `TempsPlotView`, `GameDetailViewModel`'s
|
||||
`TrendEmptyText`, `LatencyHeader` and `SensorsEmptyText`, `GamesViewModel.SortLabel`, `TriStateChipModel.IsNo`,
|
||||
`AboutWindow`'s `AppTab` and `ThirdPartyTab`, `NvapiNgxWords.Degraded`, `IpcMessages`' `TelemetryUnavailable` and
|
||||
`DbWriteFailed`, `IpcProtocol.Keepalive`, `ShmLayout.GuardTickDeadlineMs`, `HarnessOverlayLogSweep.Own`; and the
|
||||
getters of 49 auto-properties, among them view-model texts no page binds and columns of stored rows. The list is
|
||||
`UnusedMember.Global` and its siblings in run 42842741359's report.
|
||||
|
||||
**Running it on a developer's PC.** The same InspectCode is a .NET tool:
|
||||
`dotnet tool install JetBrains.ReSharper.GlobalTools --version 2026.2.3.1 --tool-path <somewhere>`, then, after
|
||||
`dotnet build FrameLedger.slnx -c Release`:
|
||||
`jb inspectcode FrameLedger.slnx --no-build --format=Sarif --output=<file> --caches-home=<folder> --properties:Configuration=Release --toolset-path="C:\Program Files\dotnet\sdk\<11.0.x>\MSBuild.dll" --dotnetcore="C:\Program Files\dotnet\dotnet.exe"`.
|
||||
Two things measured on the owner's PC: without `--toolset-path` it picked Visual Studio 18 Insiders' MSBuild, which
|
||||
crashed at start ("No files to inspect were found"); and a `--caches-home` a failed run had written left one project
|
||||
unloaded on the next (2,875 false compile errors, all in `Infrastructure.Tests`) — a fresh folder loaded all thirteen.
|
||||
A clean run there reports what the container does, to within a handful of findings that differ between Windows and
|
||||
Linux (3,679 in the container, the same inspections on Windows with counts a few apart).
|
||||
|
||||
**What it does not cover, and what would change it.** No C++ (above); no `alpha`; no pull request from a fork or from
|
||||
Dependabot; no quick-fixes, coverage or licence audit (Ultimate). **If the organisation gets an Ultimate licence** —
|
||||
JetBrains has a programme for open-source projects — Qodana for .NET runs natively on Windows: `linter: qodana-dotnet` in
|
||||
`qodana.yaml`, `runs-on: windows-latest`, `args: --within-docker false`, .NET set up from `global.json` first, and
|
||||
`EnableWindowsTargeting` dropped. Until then the trial's end changes nothing here: the token only names the project
|
||||
the report is sent to.
|
||||
|
||||
## C# 15 and the analyses (owner decision D96, 2026-11-11)
|
||||
|
||||
The main line compiles C# 15 since beta.37 — `LangVersion latest` on the .NET 11 SDK — and the owner asked for its
|
||||
constructs to be used. **None is used yet, and this section is why.** The rule the plan was approved with: a construct
|
||||
is used on main only where (1) the build, its analyzers and `dotnet format` take it with no analyzer switched off,
|
||||
(2) CodeQL extracts its file without an error, and (3) Qodana reports nothing that is only its engine not knowing the
|
||||
syntax — the first two are required checks, and Qodana's gate is zero. Each construct was written once, in a file of its
|
||||
own, and shown to each tool (`spike-notes` §29, the canary):
|
||||
|
||||
| Construct | Build and analyzers | ReSharper's engine — InspectCode 2026.2.3.1, which Qodana 2026.2 runs, and 2026.3.0 | Used on main |
|
||||
|---|---|---|---|
|
||||
| Collection expression arguments, `[with(…), …]` | taken | an error: "Feature 'collection expression arguments' is not available. Please use language version 'preview'." | no |
|
||||
| Closed hierarchies, `closed` | taken | not parsed ("Cannot resolve symbol 'closed'") | no |
|
||||
| Unions, `union` | CA1815, from the SDK's own rules, on every union | not parsed ("Cannot resolve symbol 'union'") | no |
|
||||
| Labeled `break` / `continue` | taken; `dotnet format` moves the label one indent to the left | not parsed by 2026.2.3.1; "not available… language version 'preview'" in 2026.3.0 | no |
|
||||
|
||||
**CodeQL's reading of them is not established**: its documentation lists C# up to 14, and a pull request's C# analysis
|
||||
is an overlay that prints no per-file result (§`codeql.yml`). A full analysis of a branch is a `workflow_dispatch` of
|
||||
`codeql.yml` on it.
|
||||
|
||||
**What moves this:** a ReSharper engine that reads C# 15 as a released language, in the Qodana linter this repository
|
||||
runs; then the canary again, and a dispatched CodeQL run. `spike-notes` §29 lists where each construct would go.
|
||||
**What main does take from .NET 11:** its API — the `string` overloads that name the comparison of a `char` search, and
|
||||
`Process.TryGetProcessById`. The two preview features (runtime-async, the updated memory-safety rules) stay out, as D76
|
||||
kept them out of the alphas.
|
||||
|
||||
## Dependabot (`.github/dependabot.yml`) and the NuGet audit
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: nuget
|
||||
- package-ecosystem: nuget # also .config/dotnet-tools.json (the SonarScanner, since 2026-10-25)
|
||||
directory: /
|
||||
schedule: { interval: weekly }
|
||||
cooldown: { default-days: 7 } # since 2026-10-25
|
||||
groups: { minor-and-patch: { update-types: [minor, patch] } }
|
||||
# ignore: WPF-UI*, FluentAssertions majors — the file says why
|
||||
- package-ecosystem: github-actions
|
||||
directory: /
|
||||
schedule: { interval: weekly }
|
||||
cooldown: { default-days: 7 } # since 2026-10-25
|
||||
groups: { actions-minor-and-patch: { update-types: [minor, patch] } }
|
||||
```
|
||||
|
||||
Central package management makes Dependabot PRs single-file diffs.
|
||||
|
||||
- **Cooldown (2026-10-25):** a version update waits seven days after its release is published, so a release that is
|
||||
pulled or found compromised in its first week never becomes a pull request here. Security updates do not wait — the
|
||||
option does not apply to them. The actions' minor and patch releases come as one pull request; a new major comes
|
||||
alone, because it is the one that changes inputs.
|
||||
- **No `dotnet-sdk` entry, on purpose:** `global.json` is a floor (11.0.100 since beta.37, D94; 10.0.100 before) with
|
||||
`rollForward: latestFeature`, so a developer's machine and the runner already build with the newest SDK of that band
|
||||
they have (the runner installed 10.0.402 on 2026-10-20, 10.0.404 on 2026-11-10). Raising the floor is a decision
|
||||
about what a contributor must install, not an update — the owner's, as D94 was.
|
||||
- **Dependabot has never proposed a NuGet library update here — measured 2026-10-25.** Every NuGet pull request it
|
||||
opened, #66 (2026-08-09) through #314 (2026-10-18), updated analyzers only (Meziantou, Roslynator, the VS threading
|
||||
analyzers), while Dapper 2.1.89 (published 2026-09-23), coverlet 10.1.0 (09-27), xunit.v3.mtp-off 4.0.2 (10-09) and
|
||||
the 10.0.13 servicing packages (10-13) were never proposed. Its update runs are GitHub Actions runs of their own (`gh
|
||||
run list`, event `dynamic`), and the run of 2026-10-18 (39134906593) logs the test projects' resolution failing —
|
||||
`Requested dependency resolution to include coverlet.collector/10.1.0 but it was instead resolved to 10.0.1`, `The
|
||||
package FluentAssertions.7.2.2 is not compatible. Incompatible project frameworks: net10.0-windows10.0.22621` — and
|
||||
opens nothing for them. The run of 2026-10-25 (40160307095), the first with the cooldown, says it of the shipped
|
||||
libraries too, the versions in use among them — `The package Dapper.2.1.86 is not compatible. Incompatible project
|
||||
frameworks: net10.0-windows10.0.22621`, and the same of Hosting, Sqlite, EventLog, Markdig and Velopack. Why its
|
||||
resolver reads a package that targets `netstandard2.0` as incompatible with this framework is **unmeasured**. So a
|
||||
quiet Dependabot is not evidence that the packages are current: `dotnet list FrameLedger.slnx package --outdated` is,
|
||||
and the updates it had missed were made by hand in beta.29 PR-2 (#335) — `coverlet.collector` 10.1.0 excepted,
|
||||
whose reason `Directory.Packages.props` gives beside it.
|
||||
- **beta.30 (2026-10-26), by hand under the same cooldown** (the owner: "check the dependencies and conflicts, update if
|
||||
needed"): Velopack and `vpk` 1.2.0 → 1.2.161 (the owner's decision, D71 — never 1.2.158, NuGet-deprecated), Markdig
|
||||
1.4.0 → 1.4.2 (parser fixes; its licence text unchanged at the packaged commit), and **the `SQLitePCLRaw` pin
|
||||
dropped**: `Microsoft.Data.Sqlite` 10.0.13 declares the patched 2.1.13, and the 3.0.5 pin had put it on SQLitePCLRaw's
|
||||
3.x line — a cross-major resolution NuGet does not report, because the declared range has no upper bound. The engine
|
||||
is now 2.1.13's, SQLite 3.53.3 (it was 3.53.4 under the pin; 2.1.14 carries 3.54.0 and comes with Microsoft's next
|
||||
servicing). Not taken: the 10.0.14 servicing packages (published 2026-10-25, the out-of-band Brotli fix — which is
|
||||
the RUNTIME's, shipped by the SDK the release builds with, not in a package referenced here), Markdig 1.5.0
|
||||
(2026-10-24), CsWin32 0.3.366 (it changes how SafeHandles are generated; 0.3.367, its fix, is from 2026-10-22), and,
|
||||
as before, `coverlet.collector` 10.1.0 and FluentAssertions 8. Catch2 3.16, NVAPI R615 (its licence file changed),
|
||||
the Vulkan and Streamline headers and clang-format (paired with Visual Studio's) were read and not needed.
|
||||
- **beta.31 (2026-10-26), the owner's request — inside the cooldown, on purpose** ("làm thêm bản beta 31 với các deps
|
||||
còn lại (.net 10.0.14) và 1 số thư viện khác"; owner decision D72): `Microsoft.Extensions.Hosting`,
|
||||
`Microsoft.Data.Sqlite` and `System.Diagnostics.EventLog` 10.0.14 (published the day before; `Microsoft.Data.Sqlite`
|
||||
10.0.14 still declares `SQLitePCLRaw` 2.1.13), Markdig 1.5.0 (its licence text again byte-identical at the packaged
|
||||
commit), CsWin32 0.3.367 (0.3.366 changed how SafeHandles are generated, 0.3.367 fixed its overflow; nothing here
|
||||
needed a change), Meziantou.Analyzer 3.0.317 (no new finding), Catch2 3.16.1 for the native tests (clean under
|
||||
`/W4 /WX`, the `/EHsc` fix kept), and `coverlet.collector` 10.1.0 — `NoSecondMatcherTests` now leaves out the
|
||||
`Coverlet.*` types the collector injects, whose constant reflection cannot read; they were never ours. Still not
|
||||
taken: FluentAssertions 8 (its licence), and the vendored native SDKs (NVAPI R615's licence file changed; the Vulkan
|
||||
and Streamline headers follow the measured loader and titles).
|
||||
- **The NuGet audit** (`Directory.Build.props`, written down 2026-10-25): `NuGetAudit` on, `NuGetAuditMode` `all`
|
||||
(transitive packages too), `NuGetAuditLevel` `low` — the SDK's defaults for net10.0 when they were written down,
|
||||
stated so that a later SDK's defaults cannot move them (and net11.0's did not). With `TreatWarningsAsErrors` a vulnerable package is NU1901–NU1904 and the restore, so
|
||||
the gate, is red — what `SQLitePCLRaw` 2.1.11 did (`Directory.Packages.props`). `dotnet list FrameLedger.slnx
|
||||
package --vulnerable --include-transitive` read none on 2026-10-25.
|
||||
- **The repository's own alerts:** Dependabot alerts and security updates are enabled, and so are secret scanning and
|
||||
its push protection (read from the API, 2026-10-25); no alert of either kind, and no code-scanning alert, was open.
|
||||
|
||||
## 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) *(since beta.24, D66: into their own file, `docs/changelog/X.Y.Z.md`, which opens with that heading, plus its row in `CHANGELOG.md`'s Releases table — `release-notes.ps1` reads the version's own file)* → 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).
|
||||
- **Alphas (D73, 2026-10-31):** `vX.Y.Z-alpha.N`, tagged on the `alpha` branch only — `release.yml` refuses one anywhere
|
||||
else, and any other tag there — published as GitHub pre-releases on Velopack's `alpha` channel. §The alpha line above.
|
||||
|
||||
## Repo hygiene checklist
|
||||
|
||||
@@ -207,15 +916,19 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
|
||||
**In the tree — done:**
|
||||
|
||||
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph
|
||||
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done
|
||||
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly)
|
||||
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph *(and `wiki.yml` since beta.17, repo-local too: five; and `qodana.yml` since 2026-11-10, D93: six)*
|
||||
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done *(and since 2026-11-09, beta.35, D88: `accessibility.yml`, the form `ACCESSIBILITY.md` sends a barrier to, and the PR template's user-interface section)*
|
||||
- [x] The labels the forms apply exist *(2026-11-09: `accessibility`, and `safety` and `priority-high`, which `safety_gap.yml` had named since it was written (2026-08-02) while the repository had neither — GitHub applies only a label that exists, so no Safety gap report was ever labelled)*
|
||||
- [x] `ACCESSIBILITY.md` — the accessibility statement: WCAG 2.2 AA through WCAG2ICT as a goal, never a claim; how a barrier is reported and handled (2026-11-09, D88)
|
||||
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly; a seven-day cooldown and the actions grouped since 2026-10-25 — and a NuGet library update it never proposed is `dotnet list package --outdated`'s to find, §Dependabot and the NuGet audit)
|
||||
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
|
||||
- [x] A release rehearsal: `release.yml` `workflow_dispatch` runs every step but the Release itself (§release.yml)
|
||||
|
||||
**GitHub settings — the owner's (`HANDOFF` §Owner-only):**
|
||||
|
||||
- [ ] Branch protection as §Branch & release policy states; `Rules / validate` as a required check (§S23-2, after its skip-shim)
|
||||
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
|
||||
- [ ] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves
|
||||
- [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)
|
||||
- [x] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting) *(marked 2026-10-25, read from the API: both enabled, with secret scanning and its push protection)*
|
||||
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
|
||||
- [ ] Wiki editing restricted to collaborators (Settings ▸ General ▸ Features ▸ Wikis ▸ *Restrict editing to collaborators only*): otherwise anyone with a GitHub account can change a page until the next release overwrites it (§wiki.yml, beta.17)
|
||||
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
|
||||
+97
-6
@@ -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.
|
||||
@@ -16,12 +16,19 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
- **Absence-of-override test:** no code path may reach the injection primitive without a passing guard result. The mechanism previously described here — a `sealed` token type "only the guard can produce" — does not work and was disproved by compiling (`20_OPEN_QUESTIONS` §S8: C# accessibility flows inward, `CS0122`). The replacement is structural: the guard **owns the chokepoint** and calls the primitive itself, the primitive has internal linkage in the guard's own translation unit so no other TU has a symbol to call, and a build-time check asserts that nothing else references it. A token that escapes can be ignored; a symbol that does not exist cannot.
|
||||
- Static pre-scan: a game directory containing `EasyAntiCheat/` renders `hook_enabled` un-settable; API-level attempt to set it is rejected — including via `SetWatchlist`, which no longer carries hooking state at all (`07_IPC` §The pipe is not a trust boundary). ~~**The toggle half needs persistence and is not built yet**~~ **built in P2/P3**: `SqliteGameConsentStore.RecordGuardBlockAsync` forces `hook_enabled = 0`, `AgentCommandHandler.SetHookEnabledAsync` re-runs the pre-scan and answers `Refused`, and `GameDetailViewModel` disables the toggle on a blocked row (corrected 2026-09-21; since 2026-09-22 a finding at a session's start or at the re-scan writes the same block — `CaptureSessionTests`); the scan itself is ctest `fl_prescan`, whose matrix is mostly fail-closed: a listing that FAILED, one that was TRUNCATED, a directory that could not be established, unusable rules, and a missing evidence source must each be *undetermined*, never clean. Two cases exist only to stop the rest passing vacuously — a genuinely clean directory must be **allowed**, and a name matching the wrong group (a directory named like a `files` entry) must **not** fire. One case removes a family from the rules and asserts the hit disappears, which is what proves there is a single matcher rather than a second one that happens to agree.
|
||||
|
||||
> **D48 (beta.14):** the module check's one re-read is held both ways in ctest `fl_guard` `[D48]` — a member still
|
||||
> loading reads clean on the re-read (one pause, two snapshots); one still unreadable refuses; one that exited drops out of
|
||||
> the fresh set; a target that exited refuses; `ACCESS_DENIED` is never retried; a finding refuses at once and a finding
|
||||
> the re-read sees refuses — and against the real source (`[live]`: a process created suspended and a pid with no process
|
||||
> answer `kRetry`). The managed half — a refused re-scan of a game that has exited ends as its exit, never for a finding —
|
||||
> is `CaptureSessionTests` and `SessionRecorderTests`.
|
||||
|
||||
## Native unit tests (Catch2)
|
||||
|
||||
- **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~~ five header structs** *(five since layout 5, 2026-11-11: `FlAdvancedState`, 1472 bytes; what reads and writes it is tested at four levels since 0.1.0-beta.40 — `fl_adv_fields` the Overlay's header alone, `fl_guard` `[advanced]` the injected Overlay with the word off and on, `InGameAdvancedSamplerTests` / `CaptureSessionTests` / `SessionRecorderTests` what the Agent makes of a publication, and `AgentEndToEndTests.WhatTheGameTellsFsrIsStoredOnlyByASessionThatRecordsAdvancedMetrics` the shipped Agent, the real Overlay and the harness: two sessions of one target, the first storing nothing of it)* (`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.
|
||||
@@ -44,6 +51,52 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
- Blob codecs round-trip for every series in `frame_blobs` (NaN forbidden — assert), including the two-pair `render_res` encoding and the three-bit `rt_flags` byte. SQLite migrations apply cleanly from an empty file to the current schema, and re-applying is a no-op. (There is no v1→v2 upgrade to test — `06_DATA_MODEL` §Migrations.)
|
||||
- IPC pipe: framing, split reads, oversize rejection, unknown fields/types ignored, protocol mismatch.
|
||||
|
||||
### What the App draws (beta.14)
|
||||
|
||||
A page or dialog that only *loads* has proved nothing about how it looks: `PagesLoadTests` counted the import list's
|
||||
rows while every row was white text on white in the dark theme (`08_UI` §Contrast). The rendered checks run on the one
|
||||
STA thread with the App's three dictionaries (`PagesLoadTests.OnStaAsync`) and look at the result: `Visuals` lays a
|
||||
control out at a window's size, pumps the dispatcher (a `NavigationViewContentPresenter`'s navigation), swaps the theme
|
||||
dictionary for one check and puts Dark back, and composites every Border and Panel background between a text and the
|
||||
window into the colour actually painted under it; `Wcag` is the arithmetic. `ImportReviewRenderTests` measures each text
|
||||
cell against that colour in both themes and counts the accent pixels of each ticked box in a `RenderTargetBitmap`; the
|
||||
paging checks navigate a real page in WPF UI's presenter and send it the wheel. Each was run red against the unfixed XAML
|
||||
first — a rendered check that cannot fail is the counted-rows check again.
|
||||
|
||||
**A theme switch needs a window (beta.17).** A change to `Application.Resources` reaches only the trees of
|
||||
`Application.Windows`, and a `Window` registers itself there when it is constructed, shown or not. So
|
||||
`PagesLoadTests.EveryTextFollowsAThemeSwitch` hosts each surface in a `FluentWindow` it never shows, swaps the theme
|
||||
dictionary as `ApplicationThemeManager.Apply` does, and compares every text's colour with the same surface made fresh
|
||||
under the new theme. `PagesLoadTests.Surfaces` builds every page, window and dialog content from loaded view models, for
|
||||
any check that wants all of them. Colours are compared and texts only reported: another test class may change
|
||||
`Strings.Culture` between the two builds.
|
||||
|
||||
**A page is measured in the Frame the App shows it in, and a theme brings its accent (beta.18).** WPF UI's
|
||||
`NavigationViewContentPresenter` is a `Frame`, which passes no inherited value into the page, the text colour included, so
|
||||
a page laid out straight in a window measures the window's colour and not the App's: the theme-switch check above did, and
|
||||
stayed green over every page title drawn black (`08_UI` §Contrast, fifth hole). The rendered checks host a page in the
|
||||
presenter (`PagesLoadTests.Hosted`), and `PagesLoadTests.EveryTextIsReadableInBothThemes` measures every surface's shown
|
||||
texts at ≥ 3:1 in both themes. `Visuals.UnderTheme` switches as the App does — the accent resources derived for the theme
|
||||
from Windows' default accent (`Visuals.DefaultAccent`, the App's derivation rather than the machine's own palette), then
|
||||
the dictionary — and puts the application's own resources back afterwards. The accent lives in `Application.Resources`,
|
||||
not in a theme dictionary; until then a check under Light measured the dark theme's link blue on the light window, 1.9:1,
|
||||
a colour the App never shows. The theme-switch check compares what can be seen: a text only one of the two instances holds
|
||||
counts where it shows, and a collapsed part is not compared (a switch re-applies the template of a DataGrid's idle scroll
|
||||
bar, and its glyphs exist in the switched instance only).
|
||||
|
||||
**Loaded needs a shown window, and even then it is not raised everywhere (beta.17).** A tree laid out by hand never raises
|
||||
Loaded, and a shown one raises it only where a subtree listens for it (`16_WPFUI_SYNTAX` §Gotchas) — so a test that calls
|
||||
`RaiseEvent(Loaded)` proves a handler, never that WPF reaches it. `ScrollBarHidingTests.EverySurfaceShownWithTheOptionOnDrawsNoBar`
|
||||
shows each surface in a real window, off the screen and never activated, with the option on before anything is built as
|
||||
at start-up; `WpfRaisesLoadedOnlyWhereASubtreeListensForIt` checks the harness against WPF itself (a scroller holding a
|
||||
Border is never loaded, one holding a CheckBox is), on CI too.
|
||||
|
||||
**A test that sends input must also say which keys are held.** `Keyboard.Modifiers` is the machine's real keyboard, read
|
||||
from any thread (a fresh background thread's `GetKeyState` reports the machine's NumLock — measured 2026-10-06), so a
|
||||
wheel test that read it held whatever key a person pressed while the gate ran: `ChartWheelTests`' plain half went red once
|
||||
on the developer's machine and never on CI. The handlers read `ChartWheel.CurrentModifiers`, which the test sets inside its
|
||||
own work item on the STA thread and puts back — and with the keys a parameter, the Ctrl half is driven end to end too.
|
||||
|
||||
## Integration tests (CI-runnable, no game, no anti-cheat surface)
|
||||
|
||||
`hook-harness` is what makes this architecture testable without touching a real title:
|
||||
@@ -62,12 +115,37 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
caused when its run ends, and `tools/test-artifacts-check.ps1` fails the gate for one left behind
|
||||
(`17_HOOK_ENGINE` §Native logging, 2026-09-15). A new native test binary that starts the harness needs the listener;
|
||||
a managed test project that stages it gets the sweep from `FrameLedger.DrainFixtures.targets`.
|
||||
- **Test isolation: a suite whose host resolves its target BY NAME consents to a run-unique copy of the harness**
|
||||
(beta.16). `build.ps1` runs the test projects as parallel processes, and `TargetResolver` counts every process of the
|
||||
consented executable's name — an unreadable one too, which is what a `hook-harness.exe` another project is still
|
||||
starting is (its module list a partial copy). #269's first CI run lost `AgentEndToEndTests` that way:
|
||||
`TargetAmbiguous`, exit 6. `AgentEndToEndTests`, `PartialRecoveryEndToEndTests` and `CaptureHostEndToEndTests` now copy
|
||||
the staged harness to `hook-harness-<their scratch directory>.exe` beside their data, as `PipeEndToEndTests` already
|
||||
did, register that directory with the sweep, and pin the copy to the staged harness byte for byte;
|
||||
`AnotherHookHarnessRunningBesideTheSuiteDoesNotMakeTheTargetAmbiguous` runs a second harness beside the capture (red
|
||||
against the shared name: `TargetAmbiguous`). A suite that attaches by pid (`ShmDrainIntegrationTests`, the native
|
||||
`fl_guard_test`) is not exposed and keeps the staged name.
|
||||
- **Test readiness: an injection test waits for the harness to say it presents** (beta.27). The suites that start
|
||||
hook-harness and then inject into it or look for it — `ShmDrainIntegrationTests`, `CaptureHostEndToEndTests`,
|
||||
`AgentEndToEndTests`, `PartialRecoveryEndToEndTests` — slept 800 ms after starting it, a guess at when it presents.
|
||||
They now wait, bounded at 30 s, for the line the harness prints and flushes right before its present loop
|
||||
(`tests/Shared/HarnessReady.cs`, compiled in by `FrameLedger.DrainFixtures.targets`), and the pause case — which read
|
||||
the writer's status as INIT once under a full gate on 2026-10-19 — waits for the writer's READY
|
||||
(`WaitUntilInitFinishedAsync`) before it pauses.
|
||||
- **The guard reads the test host too** (beta.27). The guard's scan set is the target and its ancestors up to a platform
|
||||
launcher, so for an injection test it includes the test host that started the harness, `dotnet test` and the shell
|
||||
above them. Under a full gate the test host is still starting its other test classes, and a module it releases
|
||||
between the guard's list and the module's name refuses as `ModuleScanFailed` — measured 2026-10-20, once in the gate
|
||||
and once in twelve runs of `FrameLedger.Infrastructure.Tests` with coverage, never in a run of the class alone;
|
||||
`ProcessUnreadable` (2026-10-19, twice) is the same race met at the list. `ShmDrainIntegrationTests.InjectAsync` asks
|
||||
again, four times at most, on those two reasons only. The end-to-end suites inject through the Agent or the capture
|
||||
host, which records such a session as Tier 2; they have the same exposure and have not shown it.
|
||||
- Guard integration: harness loads a **dummy DLL named like an anti-cheat module** → injection refused pre-launch; loaded late → safety unhook. (A renamed harmless DLL, not real anti-cheat software.)
|
||||
|
||||
## Hook overhead measurement (NFR-1, per release)
|
||||
|
||||
1. `hook-harness` in a fixed workload, present-rate uncapped: 3 runs hooked vs 3 unhooked → mean present-call cost delta must be ≤ 1 µs (measured with QPC around the call site in an instrumented harness build).
|
||||
2. Real game, fixed 10-minute scene, capture ON vs OFF, 3 runs each: **game's own Avg FPS delta ≤ 0.5%**, Agent CPU ≤ 1% of a core, Agent RSS ≤ 150 MB, Overlay resident ≤ 8 MB.
|
||||
2. Real game, fixed 10-minute scene, capture ON vs OFF, 3 runs each: **game's own Avg FPS delta ≤ 0.5%**, Agent CPU ~~≤ 1%~~ ≤ 2.5 % of a core *(NFR-2 as D117 amended it, 2026-11-11; `tools/agent-cost.ps1` measures the unhooked half without a game)*, Agent RSS ≤ 150 MB, Overlay resident ≤ 8 MB.
|
||||
|
||||
> **NOT MEASURED. The runbook exists as of 2026-09-10 (P2 PR-G); the run is the owner's.**
|
||||
> `tools/fps-impact-runbook.ps1` sequences the six launches, holds consent granted for the ON leg and
|
||||
@@ -80,6 +158,13 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
> Until the run happens, the honest state of this line is *unmeasured*, not *passing*.
|
||||
3. Results recorded in the release notes ("measured overhead this release: …").
|
||||
|
||||
**What a patch costs when it goes in and comes out (since 0.1.0-beta.46) is not the per-present number above**, and
|
||||
is measured where it happens: `fl_guard`'s Streamline `[advanced]` case prints the microseconds of each install
|
||||
batch and of the stop's one restore (the Overlay's `PATCH_BATCH` lines), and the time from the unhook request to
|
||||
`UNHOOKED`; it asserts that every lazily installed patch is under a batch line, that the stop is one, and that the
|
||||
restore stays under a second — the bound the one-patch-at-a-time stop did not meet on the development PC. In a real
|
||||
game the same lines are in `logs\overlay-<pid>-….log`.
|
||||
|
||||
## Tier cross-validation (accuracy regression net) — **GONE, 2026-08-28, and this is the entry to read before planning P5**
|
||||
|
||||
~~Run the same game session with Tier 1 and Tier 2 simultaneously where possible (ETW does not conflict with hooking) and compare frametime distributions: Avg/1% Low must agree within **1%**. Divergence beyond that means one of the two paths is wrong and blocks the release. This is also the check that would have caught the original detection-accuracy problem.~~
|
||||
@@ -123,7 +208,7 @@ that it was checked against anything.
|
||||
|
||||
| Axis | Values |
|
||||
|---|---|
|
||||
| OS | Win 10 22H2 VM · Win 11 dev machine |
|
||||
| OS | Win 11 dev machine · a Win 10 22H2 VM where one exists — since beta.37 (D95) Windows 10 is not blocked and is neither tested nor supported, so a run there is information, not a gate |
|
||||
| GPU vendor | NVIDIA (primary) · AMD or Intel if available, else document as untested |
|
||||
| API | D3D11 · D3D12 · Vulkan (layer path) · OpenGL · **a 32-bit title, asserting it is correctly refused and recorded as Tier 2 with the reason** |
|
||||
| Upscaler | DLSS SR · DLSS-G · DLSS-RR · FSR2/3 · XeSS · none |
|
||||
@@ -131,8 +216,14 @@ 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* |
|
||||
| Accessibility *(added 2026-11-09, beta.35, D88)* | **keyboard only** with the mouse disconnected — every page, menu and dialog, Ctrl+1…5, Esc · **Narrator** — names, values, headings, the notices as they appear · a **contrast theme** on and off (Aquatic, Desert) · Windows **animation effects** off · a large **display scale**. The owner's first pass: 2026-11-09, keyboard only and Narrator on 0.1.0-beta.34 and 0.1.0-alpha.3, no fault (`ACCESSIBILITY.md` §How it is checked; the automated half is `08_UI` §Accessibility) |
|
||||
| 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; **since beta.13** a release carries a delta against the previous one, and the first
|
||||
update that can use it is beta.12 → beta.13 — HANDOFF owner-only item 10)* |
|
||||
|
||||
## Release smoke
|
||||
|
||||
Clean-VM install → Legal Gate → Agent setup (unelevated) → add a game → consent dialog → hooked 2-min session → charts render → CSV opens in Excel → Vulkan layer registered/unregistered cleanly → uninstall removes layer registration, task, and asks about data.
|
||||
|
||||
*(Added 2026-11-09, beta.35, D88:)* and an **accessibility smoke**, the same build: the Legal Gate, the consent dialog and
|
||||
the session summary reached and answered with the keyboard alone; Narrator reads the notice a refused game raises; the
|
||||
window readable under one contrast theme. The release's owner-only item in `HANDOFF` lists what that release moved.
|
||||
+18
-10
@@ -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.)*
|
||||
@@ -298,7 +306,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> `logs\overlay-<pid>-*.log` (init / Agent request / stop), `opengl32!wglSwapBuffers` with the harness's
|
||||
> `--opengl` mode. **D3D9 is not built and will not be**: `20_OPEN_QUESTIONS` §Scope decisions rules it out
|
||||
> of v1 (the Overlay is x64-only and those titles are 32-bit); listing it here was the roadmap's, not the
|
||||
> scope's. What P1 still leaves ⏳ in `17_HOOK_ENGINE` §Hook inventory: `SetFullscreenState`,
|
||||
> scope's. What P1 still leaves ⏳ in `17_HOOK_ENGINE` §Hook inventory: ~~`SetFullscreenState`~~ (polled instead, 2026-09-27),
|
||||
> `SetColorSpace1`, `CreateSwapChain*`, `ID3D12Device5::CreateStateObject`, the Vulkan RT / pipeline entries,
|
||||
> §Pipeline and §Memory/latency — feature rows, each with its own measurement question, not P1's core. P2
|
||||
> (the Agent, the recorder, SQLite) is next per this file.
|
||||
@@ -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~~ a pre-release at each step since, listed in the CHANGELOG *(corrected 2026-10-14: the count went stale at the next release)* — (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.
|
||||
|
||||
@@ -336,10 +344,10 @@ CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 —
|
||||
- ~~PresentMon Service + API2 for a richer Tier 2~~ — **struck 2026-08-27**, and the shape hardened 2026-08-28: v1's ladder has two rungs and Tier 2 is not a measurement. What v2 may want is **a no-injection measurement at all** — which would restore two things at once: the FG oracle §S31 spent four attempts looking for, and `14_TESTING`'s Tier-1 accuracy cross-check, which is struck for the same reason (§G)
|
||||
- **YouTube overlay export**: frametime/FPS graph as transparent PNG sequence for DaVinci Resolve benchmark videos (SkullMute workflow)
|
||||
- CapFrameX-compatible CSV import/export
|
||||
- Microsoft Store / Game Pass titles (packaged-app injection constraints)
|
||||
- ~~Microsoft Store / Game Pass titles (packaged-app injection constraints)~~ *(struck 2026-11-03: GDK titles from the Xbox app and the Microsoft Store are imported, played and measured since beta.33, D77–D82, `spike-notes` §25; UWP apps stay out, refused with a reason of their own)*
|
||||
- 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
|
||||
|
||||
|
||||
+202
-11
@@ -6,8 +6,8 @@ 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` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net11.0-windows10.0.22621.0` TFM — `net10.0-…` until beta.36 — (`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~~ **= 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) |
|
||||
|
||||
@@ -62,6 +62,7 @@ private static readonly IHost _host = Host.CreateDefaultBuilder()
|
||||
Theme rules:
|
||||
- Manual Light/Dark: `ApplicationThemeManager.Apply(ApplicationTheme.Dark)`.
|
||||
- System: `SystemThemeWatcher.Watch(mainWindow)` — call it in the window's `Loaded` handler (needs an HWND), and unwatch when switching to manual.
|
||||
- A Windows contrast theme (beta.35, D91): wins over all three while it is on, and is never left to the watcher, which would apply WPF UI's own high-contrast files (§Gotchas). `Services/ThemePlan.For` is the table, `Services/WpfThemeApplier` applies it.
|
||||
- Persist the choice in `settings`; re-apply before the main window shows to avoid a flash. **Measured 2026-09-13: this is a correctness rule, not a cosmetic one** — `ApplicationThemeManager.Apply(theme, backdrop, updateAccent: true)` is what registers the `SystemAccentColor*` resources the control templates `StaticResource` at first Measure; a `FluentWindow` shown before any `Apply` throws `XamlParseException: Cannot find resource named 'SystemAccentColorPrimary'`. The shell applies the theme in its constructor before `InitializeComponent()` and again from `Loaded` for the watcher.
|
||||
- Subscribe `ApplicationThemeManager.Changed` once, centrally, to re-theme ScottPlot (below).
|
||||
|
||||
@@ -81,7 +82,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 +104,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>
|
||||
```
|
||||
@@ -115,13 +116,21 @@ Code-behind wires services once: `navigationService.SetNavigationControl(RootNav
|
||||
- Navigate **only** via `INavigationService.Navigate(typeof(SomePage))` — never manipulate `Frame` directly, never `new` a Page.
|
||||
- Pages implement `INavigableView<TViewModel>` with `ViewModel` injected via constructor DI; `DataContext = this` in the page constructor (WPF UI template idiom) so bindings read `ViewModel.*`.
|
||||
- Page state: pages are Transient; anything that must survive navigation lives in the ViewModel-backing services/DB, not the Page.
|
||||
**Except the library, since beta.34** (owner request 2026-11-06, "Games stalls 0.5–1.5 s"; `spike-notes` §27): the window
|
||||
keeps the `GamesPage` it built — `Services.WindowPageCache`, the window's own `INavigationViewPageProvider`, set after
|
||||
`INavigationService.SetNavigationControl` (which hands the NavigationView the container's provider) — and its view model
|
||||
reads the library again each time the page is shown (`GamesViewModel.Attach`). Still Transient in the container; one
|
||||
instance per window, so a language change's new window builds its own in the new language. **Not**
|
||||
`NavigationViewItem.NavigationCacheMode`: WPF UI 4.3.0 reads it only when the NavigationView has neither a service
|
||||
provider nor a page provider (`NavigationView.Navigation.cs`, `GetNavigationItemInstance`), and this App sets one — the
|
||||
attribute would have changed nothing.
|
||||
|
||||
## Control mapping (always prefer these)
|
||||
|
||||
| Need | Use | Not |
|
||||
|---|---|---|
|
||||
| Button | `ui:Button` with `Appearance="Primary/Secondary/Danger"`, `Icon="{ui:SymbolIcon Play24}"` | bare `Button` |
|
||||
| Text | `ui:TextBlock` with `FontTypography="Caption/Body/BodyStrong/Subtitle/Title"` | hardcoded FontSize |
|
||||
| Text | `ui:TextBlock` with `FontTypography="Caption/Body/BodyStrong/Subtitle/Title"`; muted text with `Style="{StaticResource SecondaryText}"` or `TertiaryText` (beta.17) | hardcoded FontSize; `Appearance="Secondary"` on a TextBlock (§Gotchas) |
|
||||
| Text input | `ui:TextBox` (`PlaceholderText`, `Icon`) | native TextBox |
|
||||
| Numbers | `ui:NumberBox` (`Minimum/Maximum/SmallChange`, `SpinButtonPlacementMode="Compact"` — needs ≥ 4.3.0) | TextBox + parsing |
|
||||
| Toggle | `ui:ToggleSwitch` | CheckBox for on/off settings |
|
||||
@@ -132,9 +141,9 @@ Code-behind wires services once: `navigationService.SetNavigationControl(RootNav
|
||||
| Busy | `ui:ProgressRing` | |
|
||||
| Contextual popup | `ui:Flyout` | Popup hand-rolling |
|
||||
| Hyperlink-ish | `ui:HyperlinkButton`, `ui:Anchor` | |
|
||||
| Grid of records | native `DataGrid` (WPF UI restyles it) | third-party grids |
|
||||
| Grid of records | native `DataGrid` (WPF UI restyles it — through the grid's own `RowStyle`/`CellStyle`/`ColumnHeaderStyle` setters, so a local one is based on WPF UI's keyed style: §Gotchas, added 2026-10-05) | third-party grids |
|
||||
|
||||
Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `ControlsDictionary` restyles standard WPF controls to Fluent automatically.
|
||||
Native `Menu`, `TabControl`, `ComboBox`, `Slider`~~, `ListView`~~ are fine — the `ControlsDictionary` restyles standard WPF controls to Fluent automatically. *(Corrected 2026-10-05: 4.3.0 has no implicit style for the native `ListView`, `ListViewItem` or `GridViewColumnHeader` — only `ui:ListView` is restyled — nor for `DataGridRow`, `DataGridCell`, `DataGridColumnHeader` or `FlowDocumentScrollViewer`; read from the loaded `ControlsDictionary`.)*
|
||||
|
||||
## Icons
|
||||
|
||||
@@ -143,7 +152,7 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `
|
||||
|
||||
## Theming & brushes
|
||||
|
||||
- Colors **only** via `{DynamicResource …}` theme keys, e.g. `TextFillColorPrimaryBrush`, `TextFillColorSecondaryBrush`, `ControlFillColorDefaultBrush`, `CardBackgroundFillColorDefaultBrush`, `ApplicationBackgroundBrush`, `AccentTextFillColorPrimaryBrush`, `SystemFillColorCriticalBrush`. `DynamicResource` always (theme can change at runtime); `StaticResource` for theme brushes is a review-blocking bug.
|
||||
- Colors **only** via `{DynamicResource …}` theme keys, e.g. `TextFillColorPrimaryBrush`, `TextFillColorSecondaryBrush`, `ControlFillColorDefaultBrush`, `CardBackgroundFillColorDefaultBrush`, `ApplicationBackgroundBrush`, `AccentTextFillColorPrimaryBrush`, `SystemFillColorCriticalBrush`. `DynamicResource` always (theme can change at runtime); `StaticResource` for theme brushes is a review-blocking bug. *(Added 2026-10-07: so is a property that looks like a theme colour but is looked up once — `ui:TextBlock Appearance`, §Gotchas.)*
|
||||
- **`ui:Badge` `Appearance="Info"` / `Caution` / `Danger` / `Success` are NOT theme colours.** Their backgrounds are
|
||||
`Palette*Brush` from WPF UI's `Palette.xaml` — one fixed Material palette shared by both themes — under the theme's
|
||||
text: Info is white on `#03A9F4` in dark (2.6:1), measured 2026-09-16 on the Games card. ~~Use `Secondary` (theme
|
||||
@@ -152,7 +161,49 @@ 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.
|
||||
- **Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`** (2026-10-07): the navigation's
|
||||
Frame passes no text colour into a page, and a text with none is black (§Gotchas).
|
||||
- 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.
|
||||
- Second exception (beta.23, D61): the game page's artwork band, `Controls/ArtTint` — a colour worked out in code from the
|
||||
artwork and the theme's own text and fill colours, the strongest tint at which every text on it still reads (4.5:1,
|
||||
tertiary 3:1). It follows a theme switch through a **resource reference on the band** (`SetResourceReference` on a
|
||||
private attached property bound to `ApplicationBackgroundColor`), not through `ApplicationThemeManager.Changed`, which
|
||||
only `ApplicationThemeManager.Apply` raises — a page made and switched in the tests' harness would never hear it.
|
||||
- The change markers (beta.30, D70) take the palette's `Chart_StutterPso` under `ChartTheme.TextOn` — black or white by
|
||||
WCAG contrast, black in both themes. The chart reads `ChartTheme.Current` at every render; the WPF chip in the list
|
||||
(`Controls/ChangeBadge`) follows a switch through the same resource reference as `ArtTint` and `FgMixBar`
|
||||
(`ChartPalette.ForBackground`). No colour in XAML.
|
||||
- Third exception (beta.35, D91): **a Windows contrast theme's colours**, read from `SystemColors` in one place
|
||||
(`Services/ContrastPalette.FromSystem`) and laid over the theme by `Services/ContrastOverlay` — never written in XAML. A
|
||||
colour the App works out itself reads `Services.ContrastTheme.Active` first (the charts, the badges, the artwork band);
|
||||
XAML that must change with it binds `{Binding Path=(services:ContrastTheme.IsOn)}`, a static property WPF hears through
|
||||
its `StaticPropertyChanged` event.
|
||||
- **`ui:Button Appearance="Danger"` / `Info` / `Success` / `Caution` / `Dark` / `Light` paint fixed colours** — values in
|
||||
WPF UI 4.3.0's button style (`#F44336` for Danger), not resources, so no theme and no contrast theme reaches them, under
|
||||
the theme's button text (white on the red in the dark theme, 3.68:1). Danger is the one the App uses: its implicit
|
||||
`ui:Button` style (`Styles/FrameLedger.xaml`) puts the theme's dark text on the red, and the theme's own button under a
|
||||
contrast theme — message boxes' buttons included. The other five are refused
|
||||
(`ContrastThemeTests.NoButtonOrBadgeTakesAnAppearanceThatPaintsAFixedColour`).
|
||||
- **A snackbar's appearances are fixed colours too** (`ISnackbarService.Show`): Success, Caution, Info, Danger, Primary,
|
||||
Dark and Light are values under white or black text — Success 2.78:1, Caution 2.16:1 in both themes. Only Secondary is
|
||||
the theme's: `Services/SnackbarStrip`, the one place a snackbar is shown, uses it for every message.
|
||||
- **A `ui:Badge` with a BOUND palette appearance** is the same hole as a literal one, and no XAML scan of literals sees it
|
||||
(the agent's pill, beta.35: `AgentPill` now). A bound badge appearance is refused by the same test.
|
||||
|
||||
## FlowDocument (rendered documents, beta.12)
|
||||
|
||||
- **WPF UI 4.3.0 styles no `FlowDocument`.** Its own defaults are black Georgia on white, so a document in the dark theme
|
||||
is unreadable unless the document is themed in code: `Markdown/MarkdownRenderer` sets `TextElement.Foreground` to
|
||||
`TextFillColorPrimaryBrush` and `TextElement.FontFamily` to `ContentControlThemeFontFamily` **by resource reference**
|
||||
(`SetResourceReference`, the code form of `DynamicResource`), a transparent background, and resource references for
|
||||
every other colour (`AccentTextFillColorPrimaryBrush` links, `SubtleFillColorSecondaryBrush` code and table headers,
|
||||
`ControlStrokeColorDefaultBrush` rules, quote bars and table borders). Never a literal brush.
|
||||
- Host it in `Controls/MarkdownView` (a `FlowDocumentScrollViewer`, toolbar hidden) — not a `RichTextBox`, which is an
|
||||
editor. A `Hyperlink` there does not navigate by itself: the view handles `RequestNavigate` and decides
|
||||
(`Markdown/MarkdownLinks`).
|
||||
- `AccentTextFillColorPrimaryBrush` is the light accent in the dark theme only after `ApplicationThemeManager.Apply(…,
|
||||
updateAccent: true)` — measured 2026-10-03 in the test host, which skips it: links drew #003E92 on #202020 there and
|
||||
#73C2FF once the accent was applied as `WpfThemeApplier` applies it.
|
||||
|
||||
## Custom controls (`FpsReadout`, `TriStateChip`, sparklines)
|
||||
|
||||
@@ -160,6 +211,9 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `
|
||||
- `TriStateChip`: `Border` CornerRadius 12, states — Yes: `AccentFillColorDefaultBrush` bg + on-accent text; No: transparent bg + `ControlStrokeColorDefaultBrush` 1px border; N/A: dashed `StrokeDashArray="2 2"` border + `TextFillColorTertiaryBrush` text.
|
||||
- **Built 2026-09-14 (P3 PR-5):** both derive from `Control` with one dependency property, `Model` (`FpsReadoutModel` / `TriStateChipModel`, decided by `Services.FpsPresentation` and the view models — the control renders, it never decides), templates in `Styles/FrameLedger.xaml` with `DataTrigger`s on the model's flags; the dashed N/A outline is a `Rectangle` behind the `Border` (a `Border` cannot dash). The source suffix icon became the tooltip: the Fluent System Icons names for 🔍/✎/↧ are not certain in this pinned version and a wrong `SymbolRegular` is a build error. The override flyout is PR-6's.
|
||||
- No `SystemColors.*` anywhere.
|
||||
- `ChangeBadge` (beta.30): a `Control` with one `Text` property, not focusable (the row's text carries the meaning), its
|
||||
template a `Border` and a `TextBlock` bound to `Background`/`Foreground`, which the control sets in code from the chart
|
||||
palette (`Styles/FrameLedger.xaml` writes no colour).
|
||||
|
||||
## Dialogs & notifications
|
||||
|
||||
@@ -176,9 +230,14 @@ 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))`.
|
||||
- Transient in-app: ~~`ISnackbarService.Show(title, message, ControlAppearance.Success, new SymbolIcon(SymbolRegular.Checkmark24), TimeSpan.FromSeconds(4))`~~
|
||||
`IMessageStrip` (`Info` / `Success` / `Warn`) — `Services/SnackbarStrip` is the one caller of `ISnackbarService.Show`, and
|
||||
says each message to a screen reader (beta.35, D89). A view model never holds `ISnackbarService`.
|
||||
- A change a screen reader must hear goes through `IAnnouncer` (`Services/UiaAnnouncer`, UI Automation's notification
|
||||
event). **`AutomationProperties.LiveSetting` alone says nothing in WPF**: the app must raise `LiveRegionChanged` itself,
|
||||
and no XAML of the App's sets one (beta.35).
|
||||
- System/tray notifications: H.NotifyIcon only (08_UI §Notifications policy).
|
||||
|
||||
## ScottPlot theme sync
|
||||
@@ -194,10 +253,43 @@ On startup and on `ApplicationThemeManager.Changed`: for every live plot set fig
|
||||
> Pinned `ScottPlot.WPF` 5.1.59: `Add.SignalXY` for the decimated series, `Add.Scatter` (no line) for markers,
|
||||
> `Add.HorizontalSpan` for the ribbon, `Add.Bars` over `Statistics.Histogram.WithBinCount`, `Add.ScatterLine`
|
||||
> for the percentile curve, a series' `Axes.YAxis = plot.Axes.Right` for the sensor overlay.
|
||||
>
|
||||
> **Accessible charts, beta.35 (D90).** Every plot in XAML is `charts:ChartPlot` (a `WpfPlot` subclass; ScottPlot's
|
||||
> default style and input stay) with `AutomationProperties.Name` and `HelpText` from `A11y_Chart_*` / `A11y_ChartData_*`.
|
||||
> `ChartTheme.Attach` adds `Charts/ChartKeys` (arrows and A marked handled after ScottPlot's class handler has acted — an
|
||||
> instance handler runs after it) and `ResetOnDoubleClick` (`DoubleLeftClickBenchmark(false)` and a `DoubleClickResponse` on
|
||||
> the left button that autoscales). A series takes `ChartPatterns.Line` / `Points` / `Hatch` by its index — a new series
|
||||
> without one is red in `NoChartTellsTwoSeriesApartByColourAlone`. Under a Windows contrast theme `ChartTheme.Current` is
|
||||
> `ChartPalette.ForContrast(ContrastTheme.Active)` — the theme's window under every plot, its text, link, highlight,
|
||||
> button text and disabled text for the rest — and the patterns carry the series apart (D91).
|
||||
>
|
||||
> **The trend's change markers, beta.30 (D70):** `Charts/ChangeMarkerPlottable`, an `IPlottable` + `IRenderLast` added
|
||||
> with `Add.Plottable` (which assigns no axes: the chart sets `Axes.XAxis`/`YAxis` itself), draws the dashed lines in
|
||||
> `Render` — clipped to the data area — and the numbered badges in `RenderLast`, after the panels and unclipped, in a
|
||||
> band kept with `plot.Axes.Top.MinimumSize` (the top axis is unused and measures 15 px; `MinimumSize` clamps it up, and
|
||||
> `Clear` keeps it, so `Show` sets it every time — 0 with no marker). `LabelStyle.Measure` sizes a badge with a
|
||||
> `Paint.NewDisposablePaint()`; `Charts/ChangeBadgeLayout` places them. `GetAxisLimits` returns
|
||||
> `AxisLimits.HorizontalOnly`, so the markers count toward the date axis's autoscale as `VerticalLine`s did.
|
||||
|
||||
## Gotchas checklist
|
||||
|
||||
- [ ] Dictionaries order: `ThemesDictionary` → `ControlsDictionary` → app styles. Wrong order = default-looking controls.
|
||||
- [ ] **A ScottPlot `VerticalLine` label grows into a panel nothing sizes for it (5.1.59).** With `LabelOppositeAxis` it is
|
||||
anchored 5 px above the data area, its box (text + 5 px padding each side) growing up into the top-axis panel, which
|
||||
an unused axis measures at 15 px; clipping is off, so the control's edge cut it — the owner's "Driver GPU: … → …",
|
||||
beta.30. `LabelAlignment` is overwritten each frame (only `ManualLabelAlignment` holds), and
|
||||
`LabelStyle.LastRenderPixelRect` includes the 3 px default `ShadowOffset` even with no shadow. The trend draws its
|
||||
own badges now (§ScottPlot theme sync).
|
||||
- [ ] **`WpfPlot.DisplayScale` is read once, in the constructor**, from `VisualTreeHelper.GetDpi` before the control has
|
||||
a window. Read a pointer with `GetPlotPixelPosition(e)` (the element's DPI now); ScottPlot's pixels are device
|
||||
pixels while no `Plot.ScaleFactor` is set, and none is.
|
||||
- [ ] **WPF UI 4.3.0's high-contrast theme cannot be applied as it is** (beta.35, D91). `ApplicationTheme.HighContrast` has
|
||||
no dictionary (the watcher picks HC1/HC2/HCBlack/HCWhite by Windows' theme name); each of those holds 84 `#FFFF0000`
|
||||
placeholders among 97 colours and 17 brushes (`SystemFillColor*Brush`, `MenuBar*`) that throw when the file is read
|
||||
alone — inside the App their forward references fall back to the application's resources and read as the Fluent
|
||||
theme's fills; their colours are Windows 11's defaults, not the user's; their text on the accent is the window text.
|
||||
Never let `SystemThemeWatcher` watch while a contrast theme is on: it would apply them. The App reads them for each
|
||||
key's role only (§Theming & brushes; `08_UI` §Contrast).
|
||||
- [ ] `SystemThemeWatcher.Watch` after HWND exists (`Loaded`), not in the constructor — but `ApplicationThemeManager.Apply(…, updateAccent: true)` BEFORE the first window's XAML loads, or the accent resources are missing at first Measure (§App bootstrap).
|
||||
- [ ] Menu row lives **outside** `ui:TitleBar` (its area is the drag region; a Menu inside becomes undraggable/unclickable territory).
|
||||
- [ ] Don't set `AllowsTransparency`/`WindowStyle` on `FluentWindow` — it manages its own chrome.
|
||||
@@ -212,9 +304,108 @@ On startup and on `ApplicationThemeManager.Changed`: for every live plot set fig
|
||||
bar with no exit, which is exactly how the safety notices shipped (2026-09-14). `Styles/FrameLedger.xaml` carries
|
||||
the upstream template plus one presenter column; `PagesLoadTests.TheInfoBarTemplateRendersItsContent` renders both
|
||||
templates and turns red when upstream gains a presenter, which is when the copy comes out.
|
||||
- [ ] **What a screen reader is given is the UI Automation tree, and WPF builds it with four holes** (beta.35, D88;
|
||||
`PagesLoadTests.Automation` sweeps every surface for each). (1) **A control with no automation peer** — a plain `Control`
|
||||
or `ContentControl`, WPF UI's `Image`, `Card`, `Badge`, `InfoBar` (measured on .NET 10.0.14) — is skipped by the tree; if
|
||||
it is also focusable (a `Control` is, by default) it is a Tab stop Narrator says nothing about. Give a display-only
|
||||
control a peer (`Controls/SpokenTextAutomationPeer`) and take it out of the tab order; `ui:CardControl` has a peer with an
|
||||
empty name even with a string `Header` — the App's implicit style takes it out of the tab order. (2) **A list's,
|
||||
drop-down's or grid row's item is named by its `ToString()`**: a record's is its printed form (`Choice { Value = dark,
|
||||
Label = Dark }`), a class's its full type name. Every item type overrides it (`Services/SpokenText` builds the words).
|
||||
(3) **A `TextBlock` written straight into a `ControlTemplate` is no control element** (`TextBlockAutomationPeer`: not when
|
||||
its templated parent is something other than a `ContentPresenter`): draw a template's text through a `ContentPresenter`
|
||||
(the App's InfoBar template), or give the control a peer that says it. (4) **A `DataGridTemplateColumn`'s cell has no text
|
||||
of its own**, so WPF names it `Item: <row>, Column Display Index: n`: name it with `controls:CellName.Path` (a cell style
|
||||
based on `DefaultDataGridCellStyle`, the one WPF UI's grid gives every cell). Also: a plain `ItemsControl` is focusable
|
||||
(the App's implicit style says no), and WPF UI's `CardExpander` leaves its expand button (`ExpanderToggleButton`)
|
||||
unnamed (`Controls/ExpanderToggleName`, set by the App's implicit CardExpander style).
|
||||
- [ ] **WPF UI 4.3.0 keys its DataGrid parts' styles and defines no implicit one** (`DefaultDataGridRowStyle`,
|
||||
`DefaultDataGridCellStyle`, `DefaultDataGridColumnHeaderStyle`, handed to the grid by its implicit `DataGrid` style's
|
||||
`RowStyle`/`CellStyle`/`ColumnHeaderStyle` setters). A local `RowStyle` replaces WPF UI's; based on
|
||||
`{StaticResource {x:Type DataGridRow}}` it falls through to Aero2's row, whose `SystemColors.WindowBrush` no theme
|
||||
reaches: the import list was white text on white in the dark theme (owner's screenshot, beta.14). Base it on
|
||||
`DefaultDataGridRowStyle`. `AccessibilityTests.NoStyleIsBasedOnAnImplicitStyleTheThemeDoesNotDefine` refuses any
|
||||
`BasedOn` a type the App's dictionaries hold no style for, and `ImportReviewRenderTests` measures the rendered rows.
|
||||
- [ ] **A style of the App's for a WPF UI control replaces the style that holds its template** (beta.23). WPF UI 4.3.0 gives
|
||||
its controls their templates in its own styles (`DefaultImageStyle`, …), applied only to a control with no style of its
|
||||
own: a local `<Style TargetType="ui:Image">` with no `BasedOn` leaves the control with no template, and it takes its
|
||||
place and draws nothing — the game page's cover was an empty space beside the name while the banner above it, with no
|
||||
style, drew (caught in a render before it shipped). Base it on WPF UI's (`BasedOn="{StaticResource DefaultImageStyle}"`).
|
||||
`AccessibilityTests.NoStyleOfAWpfUiControlLeavesOutItsTemplate`, `PagesLoadTests.TheGamePagesArtworkIsDrawn`.
|
||||
- [ ] **WPF UI's `CheckBox` is `MinWidth` 120 with an 11 px padding**: in a narrow grid column it draws a sliver of the box.
|
||||
`MinWidth="0" Padding="0"` there. A `DataGridCheckBoxColumn` uses WPF's own element style, an Aero2 box — use a template
|
||||
column (`AccessibilityTests.NoDataGridCheckBoxColumn`).
|
||||
- [ ] **Every page sets `ScrollViewer.CanContentScroll="False"`.** `NavigationViewContentPresenter` changes that property's
|
||||
default to true for `Page` and, on each navigation, wraps a page that keeps it in a `DynamicScrollViewer`. A page with
|
||||
its own root `ScrollViewer` inside that wrapper has infinite height, nothing to scroll — and a stock `ScrollViewer`
|
||||
marks every wheel handled even then, so the wheel scrolled nothing on five pages until beta.14 (owner: "I have to drag
|
||||
the scroll bar"); the Logs tail grew to hold every line and never followed the end.
|
||||
`AccessibilityTests.EveryPageOptsOutOfTheDynamicScrollViewer`, `PagesLoadTests.ANavigatedPageIsNot…`.
|
||||
- [ ] **A stock `ScrollViewer` nested in a scroller takes the wheel at its ends too.** Inside a dialog use
|
||||
`ui:PassiveScrollViewer`, which hands the wheel on when it cannot scroll (`AccessibilityTests.NoPlainScrollViewerInsideADialog`).
|
||||
A `ContentDialog` whose content should not scroll as a whole sets `ScrollViewer.VerticalScrollBarVisibility="Disabled"`
|
||||
on the dialog: its content row then has the window's height, and a `*` row inside it can hold a list that scrolls alone
|
||||
(`ImportReviewPrompt`).
|
||||
- [ ] **A `ScrollViewer` moves a FIXED 48 DIP per wheel message, whatever its delta** (`ScrollViewer._mouseWheelDelta`,
|
||||
read from .NET 10.0.12; measured on a `FlowDocumentScrollViewer`: deltas of −1, −15, −120 and −360 each moved 48). It
|
||||
ignores Windows' *lines to scroll*, and a precision touchpad's small deltas each jump the whole step — a long document
|
||||
read as slow and jerky while its layout cost about a millisecond a step. `Controls/MarkdownView` handles
|
||||
`PreviewMouseWheel` itself (beta.21): the delta in proportion at Windows' lines, eased, unhandled at its ends.
|
||||
- [ ] **Microsoft.Data.Sqlite completes its "async" calls synchronously** (measured 2026-10-14, beta.23): a
|
||||
`ConfigureAwait(false)` after a ledger read does not leave the thread that asked, so a view model's load, a session's
|
||||
decode, a sort over its frames all ran on the UI thread. Work that must not run there goes in `Task.Run` —
|
||||
`Charts.SessionSeriesLoader`, the game page's executable check (`spike-notes` §21).
|
||||
- [ ] **A transient page's view model is never `IDisposable`** (beta.23). Pages and their view models are transient, and
|
||||
the root container keeps every transient disposable it makes until the App exits: every Dashboard and Logs page ever
|
||||
opened stayed in memory, and each Dashboard stayed subscribed to the Agent — at a session's end every one reloaded its
|
||||
lists on the UI thread and raised its own notice. Listen on Loaded and stop on Unloaded (`Attach`/`Detach`, as Games,
|
||||
the game page and the Dashboard do); `DashboardViewModelTests.ADashboardOffScreenHearsNothing…`.
|
||||
- [ ] **ScottPlot 5 zooms on every wheel and never marks it handled.** Without `Charts/ChartWheel` a wheel over a chart
|
||||
zoomed it and scrolled the page at once; a plain wheel is the page's, Ctrl+wheel the chart's, for every plot that
|
||||
`ChartTheme.Attach` registers.
|
||||
- [ ] **A scroll bar's visibility is bound inside its scroller's template** (`ComputedVerticalScrollBarVisibility`), so a style
|
||||
on `ScrollBar` or `ui:DynamicScrollBar` cannot hide it. Set the scroller's own `ScrollBarVisibility` to `Hidden` — no
|
||||
bar, and the wheel, the keyboard and touch still scroll (`ui:PassiveScrollViewer` treats only `Disabled` as "cannot
|
||||
scroll") — as `Services.ScrollBarHiding` does for `ui.hide_scrollbars` (beta.14), reaching each scroller from a class
|
||||
handler on `ScrollChanged` since beta.17 rather than from `Loaded` alone (next item).
|
||||
- [ ] **A class handler on `Loaded` is not a load hook.** WPF raises Loaded only on an element whose subtree listens for it
|
||||
with a handler of its own — an instance handler, a style's `EventSetter`, a template's trigger
|
||||
(`BroadcastEventHelper.OnBroadcastCallback` walks only into `SubtreeHasLoadedChangeHandler`;
|
||||
`FrameworkElement.ThisHasLoadedChangeEventHandler`) — and `EventManager.RegisterClassHandler` counts as none of them.
|
||||
WPF UI 4.3.0's `ToggleSwitch`, `CheckBox` and `ProgressRing` templates carry a Loaded trigger, so a scroller over those
|
||||
loads and a scroller over plain cards and text never does: `ScrollBarHiding` hid Settings' bar and not the Dashboard's
|
||||
(beta.17). To reach every instance, hook an event the element raises itself — a scroller's `ScrollChanged` comes from its
|
||||
first layout. `ScrollBarHidingTests.WpfRaisesLoadedOnlyWhereASubtreeListensForIt` keeps the behaviour visible, and a test
|
||||
that raises Loaded with `RaiseEvent` proves the handler, never that it is reached.
|
||||
- [ ] **No dialog in 4.3.0 closes on Esc.** Neither `ContentDialog.cs` nor `MessageBox.cs` at the 4.3.0 tag handles a
|
||||
key (read 2026-09-15), and `ContentDialog.CloseButtonText` DEFAULTS to "Close" — an empty string is how a dialog
|
||||
says it has no Close button. `MessageBox.Close()` is `[Obsolete("Use Close with MessageBoxResult instead")]` while no
|
||||
such overload is public; the Close button's own path is `TemplateButtonCommand.Execute(MessageBoxButton.Close)`.
|
||||
`Services/DialogKeyboard` registers one class handler on `Window` (bubbling `KeyDown`, so a dropdown's Esc wins) and
|
||||
closes through those paths; `AccessibilityTests.EscapeClosesTheOpenDialogWithNoResult` holds it (`08_UI` §Accessibility).
|
||||
*(Corrected 2026-10-26, beta.30: the CODE handles no key, but `ContentDialog.xaml` does route them — each template
|
||||
button's `IsDefault` follows `DefaultButton`, Close is `IsCancel`, and while the primary is disabled a trigger makes
|
||||
Close the default. Enter therefore clicks the default button from a single-line text box: the consent dialog's
|
||||
`DefaultButton = Close` declined a typed phrase on Enter (the owner's report; D69 made the primary the default and the
|
||||
content keeps Enter until the phrase matches). Esc through `IsCancel` is read from the template, not measured —
|
||||
`DialogKeyboard` handles it first.)*
|
||||
- [ ] **`ui:TextBlock Appearance` keeps the theme a text was made under (4.3.0).** `TextBlock.OnAppearanceChanged` stores
|
||||
`TryFindResource(…)` in the internal `AppearanceForeground`, and `TextBlockMetadata` coerces every TextBlock's `Foreground`
|
||||
to it — the brush found when the element was made, never looked up again (read at tag 4.3.0, 2026-10-07; `main` is the
|
||||
same). After a theme switch the page on screen kept the old theme's secondary text: light grey on white, dark grey on dark
|
||||
(the owner's screenshots of Settings, beta.17). The property also inherits, so the attached form on a container pins every
|
||||
text under it. Muted text takes `Style="{StaticResource SecondaryText}"` or `TertiaryText` (`Styles/FrameLedger.xaml`,
|
||||
`DynamicResource`). `ContrastTests.NoTextBlockTakesItsColourFromAppearance` refuses every form in the App's XAML and code,
|
||||
`PagesLoadTests.EveryTextFollowsAThemeSwitch` renders every surface through a switch both ways, and
|
||||
`PagesLoadTests.WpfUisAppearanceStillKeepsTheThemeATextWasMadeUnder` turns red the day upstream follows a switch.
|
||||
- [ ] **A page in the `NavigationView` inherits nothing, its text colour included.** `NavigationViewContentPresenter` is a
|
||||
`Frame`, and `Frame` sets `InheritanceBehavior.SkipToAppNow`: the window's `Foreground` stops there, and a text that sets
|
||||
no colour falls to the TextBlock default, which WPF UI 4.3.0's `TextBlockMetadata` makes `Brushes.Black`. Cards, grids
|
||||
and controls set their own colour in their templates; the bare texts did not — every page's title and section headings
|
||||
were black on the dark window, 1.3:1 (the owner's screenshots of beta.17; beta.16's show it too). It came and went: a
|
||||
page on screen during a theme switch did take the window's new colour through the switch, and every navigation makes a
|
||||
new page that does not. Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`
|
||||
(`AccessibilityTests.EveryPageSetsItsOwnTextColour`). A check that lays a page out straight in a window measures the
|
||||
window's colour, not the App's — beta.17's theme-switch check did and was green over the black titles — so the rendered
|
||||
checks host a page in the presenter, and `PagesLoadTests.EveryTextIsReadableInBothThemes` measures every surface so
|
||||
hosted at ≥ 3:1 in both themes.
|
||||
+266
-32
@@ -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,19 @@ 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.)* *(And since beta.25,
|
||||
> 2026-10-19: up to TWENTY — four `ffxQuery` rows join them, on the same four AMD modules, D65.)* 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
|
||||
@@ -143,7 +147,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
> Reset is load-bearing — and no vendor symbol is resolved by name, so `FL_HOOK_INVENTORY`
|
||||
> and `hookinventory-check` do not cover them at all.
|
||||
> **Every other row below is unwritten**, including
|
||||
> `SetFullscreenState`, `SetColorSpace1`, `CreateSwapChain*`, ~~`wglSwapBuffers`~~ (built 2026-09-06, #141, its row below),
|
||||
> ~~`SetFullscreenState`~~ (polled instead since 2026-09-27, its row below), `SetColorSpace1`, `CreateSwapChain*`, ~~`wglSwapBuffers`~~ (built 2026-09-06, #141, its row below),
|
||||
> `ID3D12Device5::CreateStateObject`, §Pipeline and §Memory/latency.
|
||||
>
|
||||
> Stated here because the distinction is invisible from the table. What a writer may then
|
||||
@@ -161,12 +165,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
|
||||
|
||||
@@ -179,7 +183,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
|---|---|
|
||||
| ✅ `IDXGISwapChain::Present`, `Present1` | Frame boundary, QPC, sync interval, present flags. **`DXGI_PRESENT_TEST` calls are dropped without a record** — the occlusion probe submits nothing, and a minimised game emits a stream of them (`07_IPC` §Protocol rules). **Since 2026-09-05 the hook also reads `IDXGISwapChain::GetLastPresentCount` on the chain it just saw** (rule 4: the same COM object `FindOrAdd` already calls `GetDesc` on, no new hook) and publishes `dxgiPresentSamples` / `dxgiPresentsUnseen` — DXGI's count of presents on that chain that this hook never saw, the in-process half of `20_OPEN_QUESTIONS` §H5 Leg 1. One virtual call per hooked present, costed by `hook-harness --probe-frames`. **And per record since the same night: `dxgiUnseen` @52 under `FL_MEASURED_DXGI_PRESENTS`**, so the consumer's window counts `Displayed = hooked + unseen` per bucket (`03_METRICS` §Displayed may be DXGI-COUNTED) — measured 2.90 / 2.95 on DL:TB at Streamline 2.8.0, 0 on 2.7.3 and 2.10.3. **And since 2026-09-06 (P1 item 2) the same read, at the FIRST hooked present on the first hooked chain, is published once as `FlWriterState.dxgiPresentsBeforeHook` @60** — DXGI's count of presents that ran before the hook was in, launch mode's cost meter (`20_OPEN_QUESTIONS` §S1); 0xFFFFFFFF until a present is seen, set before the present hooks go in. **Corrected 2026-09-14 (`fl_dxgi_count.h`, ctest `fl_dxgi_count`):** a reading that went *backwards* — a chain released and re-created at the same address inherits the slot's old count — used to wrap `now − previous` to ~4e9, saturate the record byte at 255 (the `DxgiSaturated` refusal) and add the wrap to the session total: the owner's ledger held `dxgi_unseen_total = 4294967243`. A regression is now a reset (no delta claimed, nothing added, the slot re-armed) and the total saturates at `UINT32_MAX` rather than wrapping. Cost: one compare on the same virtual call; measured per `14_TESTING` §Hook overhead in the PR |
|
||||
| ✅ `IDXGISwapChain::ResizeBuffers` · ⏳ `ResizeTarget` | Output resolution changes mid-session. `ResizeBuffers` re-reads the swapchain description *after* the original returns; `ResizeTarget` is not hooked |
|
||||
| ⏳ `IDXGISwapChain::SetFullscreenState` | Fullscreen ↔ borderless transitions |
|
||||
| ~~⏳ `IDXGISwapChain::SetFullscreenState`~~ **not hooked — polled (2026-09-27, beta.10)** | ~~Fullscreen ↔ borderless transitions~~ **Region 4, `FlDisplayState` (`07_IPC`, layout 4).** DXGI leaves exclusive fullscreen by itself — focus lost, Alt+Enter inside its own window hook — without the title calling this method, so a hook would miss exactly the transitions a mode share must count. Instead the present hook asks, **at most every 500 ms per chain**, two getters on the chain the title passed: `GetFullscreenState(&fs, nullptr)` (no `IDXGIOutput` taken) and `GetDesc` (the window, the back buffer, the swap effect). Rule 4: the same object `FindOrAdd` already calls `GetDesc` on and the counter reads — no new hook, no read beyond it; the window's geometry and the classification are the Agent's, out of process. `GetDesc` again also refreshes the size every record carries, which closes `IDXGISwapChain3::ResizeBuffers1` (unhooked: a D3D12 title resizing through it kept its old size until now). Published through a seqlock the writer never waits on (a taken lock skips the sample). OpenGL publishes the window and client size `ReadGlSize` already holds, with no exclusive bits. Cost per `14_TESTING` §Hook overhead in the PR |
|
||||
| ⏳ `IDXGISwapChain3::SetColorSpace1` | HDR output detection. **`IDXGISwapChain3`, not 4** — 4 adds only `SetHDRMetaData` (`20_OPEN_QUESTIONS` §H9 — *answered and removed with H1/H3/H4 in the P0 spike (`6b1fa83`); this row used to say `IDXGISwapChain4`, and the corrected interface here IS the answer, so the citation points at history rather than at a live entry*). Unbuilt, which is why `colorSpace` reads `NOT_REPORTED` and `FL_MEASURED_HDR` stays clear. **When it is built, the writer must initialise `colorSpace = FL_COLOR_SPACE_SDR` at swapchain identification** — an SDR title never calls `SetColorSpace1`, so "hook live, no call" would otherwise sit at `NOT_REPORTED` forever and HDR's definite `No` would be unreachable. DXGI documents G22/Rec.709 as the default, which makes SDR a *measured* default rather than an affirmative negative |
|
||||
| ⏳ `IDXGIFactory::CreateSwapChain*` | Capture swapchain desc (format, buffer count, swap effect, flags) at creation. Unbuilt — the swapchain description is currently read on demand in the present hook via `GetDesc` |
|
||||
| ✅ `wglSwapBuffers` (2026-09-06, P1 item 4) | OpenGL titles: one record per `opengl32!wglSwapBuffers`, `api` = OpenGL, the output size from `GetClientRect` on the window the HDC belongs to (first sighting and every 256th present, so a resize is caught without a second hook), **no `FL_MEASURED_PRESENT_ARGS`** — the call has no sync interval and no flags. A MinHook inline patch on the flat export (measured 2026-08-05: a `jmp` thunk into the vendor ICD, relocated like any first instruction), installed at init when `opengl32.dll` is already mapped and lazily on the watchdog otherwise, with the `LoadLibrary` detour waking it for `opengl32.dll`. Exercised by `hook-harness --opengl --hold-presenting N`, which calls **gdi32's `SwapBuffers`** the way a title does — measured to reach the hook (ctest `fl_guard` `[opengl]`, on Microsoft's generic renderer, so it runs on CI too). The one system-module row below carries the inventory asymmetry |
|
||||
@@ -190,11 +194,17 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
|---|---|
|
||||
| NGX: `NVSDK_NGX_D3D11/D3D12/VULKAN_CreateFeature`, `EvaluateFeature`, `ReleaseFeature` | Which NGX feature is *actually created and evaluated per frame*: SuperSampling (DLSS), RayReconstruction (DLSS-D), FrameGeneration (DLSS-G) |
|
||||
| NGX parameter accessors (`NVSDK_NGX_Parameter_SetI/GetI/SetUI`) — **exported by `sl.common.dll` only; see below** | `Width`/`Height` (render) vs `OutWidth`/`OutHeight` (output), `PerfQualityValue` (quality preset), sharpness |
|
||||
| ✅ Streamline: `slEvaluateFeature` · ⏳ `slInit`, `slSetFeatureLoaded`, `slSetConstants`, `slGetFeatureRequirements` | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **Never `FL_UPSCALER_NONE`** — a Streamline-only writer cannot see FFX, XeSS or NGX-direct, and `NONE` is the only one of the three states that may be aggregated as a negative |
|
||||
| ✅ Streamline: `slEvaluateFeature` · ~~⏳ `slInit`~~ *(not hooked, and not to be: owner decision D129, 2026-11-12 — its row below says why)*, ~~`slSetFeatureLoaded`~~ *(its own row below since beta.45)*, ~~`slSetConstants`~~ *(its own row below since beta.43)*, ~~`slGetFeatureRequirements`~~ *(its own row below since beta.44, with `slGetFeatureVersion`)* | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`; since beta.34 `kFeatureDLSS_NR` — DLSS 5's neural rendering, its own fact bit and family `FL_HOOK_SL_NEURAL_RENDERING`, D84; rule 4: the `feature` argument of the API hooked, nothing else). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **Never `FL_UPSCALER_NONE`** — a Streamline-only writer cannot see FFX, XeSS or NGX-direct, and `NONE` is the only one of the three states that may be aggregated as a negative. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks** (`FlControlBlock.advancedRequested`): the `sl::DLSSOptions` a title chains into `inputs` — the struct the quality mode is read from — is read further: `outputWidth`/`outputHeight`, `preExposure`, `exposureScale`, `colorBuffersHDR`, the five presets of version 1, and where the struct's own `structVersion` proves them present `ultraQualityPreset` and `useAutoExposure` (≥ 2) and `alphaUpscalingEnabled` (≥ 3) — §Which struct version carries which field. Rule 4: more members of the same argument of the same call; `fl_adv_fields.h` is the one place, `tools/overlay-fields-check.ps1` holds it. No new patch site. **Measured** (the header's own functions, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3): +9.5–11.7 ns per evaluation that chains the options while asked; with the word at 0, one relaxed load and a branch not taken — below what the bench resolves. Most titles set these through `slDLSSSetOptions`, which is not an export, and read N/A (train D) |
|
||||
| ✅ Streamline: `slSetConstants` (0.1.0-beta.43, Advanced metrics train B; owner decisions D111–D116, D122) | **What the game tells Streamline about a frame**, once per frame and viewport, read from the `sl::Constants` it passes — rule 4: an argument of the call hooked, and of it only the members named here. **Read:** `jitterOffset`, `mvecScale`, `cameraNear`, `cameraFar`, `cameraFOV`, `cameraAspectRatio` and the seven `Boolean`s (`depthInverted`, `cameraMotionIncluded`, `motionVectors3D`, `reset`, `orthographicProjection`, `motionVectorsDilated`, `motionVectorsJittered`). **Never read:** the five matrices (bytes 32..351 of the struct), `cameraPinholeOffset`, and the camera's position and three axes (bytes 368..423) — `tools/overlay-fields-check.ps1` refuses their names anywhere in code loaded into a game, and ctest `fl_adv_fields` publishes two structs that differ in every one of those bytes and gets the same bytes out. **The one row that is not installed unless asked for** (D111): `InstallByFamily` returns before it resolves the symbol in a process the Agent has never asked for Advanced metrics — resolving takes a reference on the module — so with the option off the export's first bytes are the file's (`fl_guard` `[advanced]` reads them from the target). Once asked, the patch goes in on that watchdog tick and stays for the life of the process; the detour forwards without looking while the request is off, and after a stop (`MayObserve`). **Every call** checks the struct's GUID and a `structVersion` of at least 1 before any member is read, and the viewport handle's the same way; every member read is one version 1 carries, so a version-1 struct laid against unreadable memory is read whole without a fault (the same ctest). **Summaries are the first viewport's**: a title with two viewports sets constants for each every frame, and "the last value" across them would flip twice a frame; the call count is of every viewport. `FLT_MAX` is Streamline's "not set" here and is kept nowhere (D119's plane at infinity is FidelityFX's). Family `FL_HOOK_SL_CONSTANTS` (bit 13), published with the patch: it entitles no field of a frame record, and tells "hooked, never called" from "not hooked". **Measured overhead** (the detour's body on the headers, the Overlay's flags, 20 million calls a run, three runs): not asked **+0.57 / +0.60 / +0.58 ns**; asked, the summarised viewport **+19.61 / +19.54 / +19.79 ns**; asked, another viewport +5.83 / +6.01 / +5.62 ns. |
|
||||
| ✅ Streamline: `slGetFeatureVersion` and `slGetFeatureRequirements` (0.1.0-beta.44, Advanced metrics train B's third step; owner decisions D111–D116, D122) | **What Streamline answers when the game asks about a feature** — which version it is, and what it requires. Two rows, two patches, two detours of one shape: **the original runs first, exactly once, on every path, with both arguments forwarded untouched**, and the struct the game passed is read only when the original said `eOk` — a refusal leaves the struct as the game made it, which is not an answer. Rule 4: an argument of the call hooked, read after the call, and of it only the members named here. **Read from `sl::FeatureVersion`:** `versionSL`, `versionNGX`. **Read from `sl::FeatureRequirements`:** `flags`, `maxNumCPUThreads`, `maxNumViewports`, `numRequiredTags`, `osVersionDetected`, `osVersionRequired`, `driverVersionDetected`, `driverVersionRequired`. **Never read:** `requiredTags` — the pointer the count belongs to — and everything after `driverVersionRequired`: the Vulkan queue counts and the pointers to the names of extensions and features. **No pointer of the game's is followed** (`tools/overlay-fields-check.ps1`, parameters `fv` and `fr`; ctest `fl_adv_fields`: two answers that differ only in those bytes publish the same region, and an answer cut off where the Vulkan members begin, laid against unreadable memory, is read without a fault; the injected `fl_guard` case's stub hands back wild pointers and no fault is counted). **Installed only where asked for** (D111), as `slSetConstants` is: `InstallByFamily` returns before it resolves either symbol in a process the Agent has never asked for Advanced metrics; once in, a patch stays for the life of the process and its detour forwards without looking while the request is off. **They are the first two rows of the table**: a game asks these while it starts, the watchdog patches rows in the table's order, and each patch stops the game's threads for a moment (0.1–0.25 s apart in the owner's logs of 2026-11-12, where `slSetConstants` was the fifth Streamline patch in, 1.9–7.8 s after the attach). *(Since 0.1.0-beta.46 the rows a tick finds go in together, under one stop of the threads — §Unhooking, Batches — so the order no longer decides which row waits behind which; it is still the order of their log lines.)* In a process never asked they are passed over and the order changes nothing. ~~**Most sessions will still have missed the calls** — an attach after the game's start-up is the usual case — and the session then says the call was hooked and the game did not ask again.~~ *(Measured 2026-11-12, the owner's eight sessions on beta.44: both calls were read in six of six Streamline sessions on five games — Unreal's Streamline plugin asks again after the attach, Cyberpunk 2077 asks again for requirements and not for versions. A game that asks only while starting still reads "hooked, not asked again".)* Three conditions before a read, as for `slSetConstants`: the Agent is asking, observing has not stopped, and the struct carries its own GUID and a version of at least 1 on this call (a struct with another GUID is not kept: the injected case sends one). Every member read is version 1's (§Which struct version carries which field). **Twelve slots** in region 5 (`FlAdvancedState.features`, layout 5 as it was), one per feature in the order first asked about; the last answer about a feature is the one kept; a thirteenth feature is not kept. **A new request does not empty them**: what version a feature is and what it requires are facts about the process, and a second session of a game that kept running would otherwise have nothing where the first had the answer — the one group `Reset` leaves, with its bit of the mask. Streamline 1.x is refused before anything is resolved (`SpeaksStreamline2`). Families `FL_HOOK_SL_FEATURE_VERSION` (bit 15) and `FL_HOOK_SL_FEATURE_REQUIREMENTS` (bit 16), each published with its patch; neither entitles a field of a frame record. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs, eight features asked about in turn): the version — not asked **+0.58 / +0.61 / +0.58 ns**, asked **+14.82 / +14.54 / +14.47 ns**; the requirements — not asked **+0.58 / +0.63 / +0.61 ns**, asked **+20.88 / +21.01 / +20.96 ns**. A game makes these calls a handful of times. |
|
||||
| ✅ Streamline: `slIsFeatureSupported`, `slIsFeatureLoaded`, `slSetFeatureLoaded` (0.1.0-beta.45; owner decisions D129–D131) | **Whether a feature is supported, whether it is loaded, and the game switching it on and off.** Three rows, three patches. Rule 4: bare arguments and results of the calls hooked, and no vendor struct at all — the feature's id; the `sl::Result` `slIsFeatureSupported` returned, **every result**, since a refusal is the answer to that question (the original runs first, both arguments forwarded untouched); the `bool` `slIsFeatureLoaded` wrote, read only when it returned `eOk`; the `bool` the game passed to `slSetFeatureLoaded`, noted before the call. **The adapter `slIsFeatureSupported` is asked about is never read** (D131): `sl::AdapterInfo` holds the adapter's LUID or a Vulkan physical device; the detour forwards the reference and `tools/overlay-fields-check.ps1` refuses the names of its members (`deviceLUID`, `deviceLUIDSizeInBytes`, `vkPhysicalDevice`) anywhere in the Overlay and the Vulkan layer — the fixture's adapter carries a wild pointer. **Installed only where asked for** (D111), as the four rows before them. `slIsFeatureSupported` and `slIsFeatureLoaded` follow the two rows of beta.44 at the head of the table; `slSetFeatureLoaded` follows `slSetConstants`. **Kept in word 1 of the feature's slot** (region 5, layout 5 as it was): bit 2 and the result in bits 8..15, bits 3 and 4, bits 5 and 6 — the last two a session's, cleared by a new request; the rest the process's, kept (`fl_adv_fields.h` `kFeatureSessionBits`). A refused feature therefore has a slot now, with nothing in it but that word. The declarations of the three functions are the same from Streamline v2.0.0 to v2.14.16, and `sl::Result` is the same forty codes in the same order at all sixteen tags (`include/sl_result.h`, `05a3c7e3889c` … `8a844b68ff55`), so a code means the same whatever interposer answered. Families `FL_HOOK_SL_FEATURE_SUPPORTED` (bit 17), `FL_HOOK_SL_FEATURE_LOADED` (18), `FL_HOOK_SL_SET_FEATURE_LOADED` (19), each published with its patch. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs, eight features in turn): `slIsFeatureSupported` — not asked **+1.50 / +1.48 / +1.50 ns**, asked **+11.97 / +11.98 / +12.08 ns**; `slIsFeatureLoaded` — **+1.79 / +1.77 / +1.89 ns**, **+12.35 / +12.31 / +12.33 ns**; `slSetFeatureLoaded` — **+1.44 / +1.47 / +1.80 ns**, **+11.28 / +11.54 / +11.45 ns**. **`slInit` is not a row and will not be** (D129): a game calls it once, before the Overlay is in the process or before a patch can land — launch mode waits for the presentation runtime before it injects, nothing is ever patched on a game's thread (§H2), and a row that exists only for Advanced metrics waits for the Agent's request. **A stop takes about 160 ms for every patch it restores** (measured on the fixture, 0.1.0-beta.45: each `MH_DisableHook` snapshots the system's threads): twelve patches took 1.9 s, fifteen 2.4 s, and the watchdog's wait for the stop's log lines, 2 s until then, is now a quarter of a second for every patch the registry can hold. **Since 0.1.0-beta.46 (D134) a stop restores its patches under one stop of the threads**: eighteen in 76–90 ms on the fixture, where one by one they took 1.37–1.56 s (§Unhooking, Batches). |
|
||||
| ✅ Streamline: `slAllocateResources`, `slFreeResources`, `slShutdown` (0.1.0-beta.45; owner decision D130) | **The game allocating and freeing a feature's resources, and shutting Streamline down — counted, and nothing else.** Three rows, three patches. Rule 4: the feature's id is the only argument looked at; the command buffer and the viewport of the two resource calls are forwarded and never read (the fixture's command buffer is a wild pointer), and `slShutdown` has no argument. **`slFreeResources` and `slShutdown` are on a game's way out**: each detour notes the call first and then calls the original, exactly once, and runs nothing of ours after it returns; the fixture goes on calling the stub after `slShutdown`, through every detour. **Installed only where asked for** (D111); the last three Streamline rows of the table. **Kept** in word 1 of the feature's slot as two four-bit counts — allocations in bits 16..19, frees in 20..23, each stopping at 15 and never carrying into its neighbour — and, for `slShutdown`, in `FlAdvancedState.slShutdowns` (@308, the first of three reserved words; layout 5 as it was) with `FL_ADV_VALID_SL_SHUTDOWN` (bit 6 of the mask). All three are a session's: a new request clears them. Families `FL_HOOK_SL_ALLOCATE_RESOURCES` (bit 20), `FL_HOOK_SL_FREE_RESOURCES` (21), `FL_HOOK_SL_SHUTDOWN` (22). The three declarations are the same from Streamline v2.0.0 to v2.14.16. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs): `slAllocateResources` — not asked **+0.70 / +0.72 / +0.80 ns**, asked **+10.43 / +10.53 / +10.74 ns**; `slFreeResources` — **+0.61 / +0.84 / +0.58 ns**, **+10.33 / +10.57 / +10.44 ns**; `slShutdown` — not asked within the bench's noise (+0.06 / −0.12 / +0.04 ns), asked **+3.39 / +3.37 / +3.52 ns**. Inventory 23 → 26 rows; a Streamline title with Advanced metrics asked for now carries thirteen patches on the interposer, and a stop restores each in about 160 ms (the row above). **In real games (2026-11-13: six sessions, five games)** `slAllocateResources` was not called once after the attach, `slFreeResources` once in one game (Phantom Blade Zero, frame generation's) and `slShutdown` once in one (Dying Light: The Beast); no session counted a fault, and the two games that fault while closing did so at the offsets they had before these hooks. Installing the thirteen interposer patches took 0.7 s to 2.8 s of a game's start, 57 to 215 ms a patch. The owner's word on both (2026-11-13): `slAllocateResources` keeps its patch and is looked at again with more sessions (D135); installs and restores are to be batched, one stop of the threads for a batch (D134, 0.1.0-beta.46). |
|
||||
| ✅ 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 |
|
||||
| ✅ **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 — *since beta.25 the quality byte is the mode the `ffxQuery` row below names for the dispatched size, `0xFF` when none does*) + one COUNT *(since 0.1.0-beta.43, owner decision D125: **counted at the first source that saw an UPSCALE and at no other** — `g_ffxUpscaleOwner`, `fl::adv::Owns`. Cyberpunk 2077's loader 2.3.0 hands a dispatch on to the leaf's export — its frame-generation dispatch types are logged on the loader and on the leaf — so an UPSCALE through such a loader reaches two hooked modules, and one count per module read K = 1 as 2.0 on the fixture bound that way (`--ffx-topology 2x-export`: 60 presents, 120 counted). No title run so far upscales through one; it is a precaution. Measured on the header with the Overlay's flags: +0.02 to +0.03 ns on the module that is counted, about 4 ns less on the forwarded copy)*; **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. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks:** the UPSCALE arm reads the rest of `ffxDispatchDescUpscale` — `enableSharpening`, `sharpness`, `jitterOffset`, `preExposure`, `cameraNear`, `cameraFar`, `cameraFovAngleVertical`, `flags`, `reset`, `frameTimeDelta` — into process-local summaries (an "ever seen" mask, a largest magnitude, a lowest and highest, a count and a sum; one module's dispatches are counted, so a dispatch that reaches the loader and a leaf is one). Never on the FSR 3.0 host's legacy descriptor, which is vouched Line truncated
|
||||
| ✅ **FidelityFX ffx-api: `ffxQuery` on the same four modules** (beta.25, owner decision D65) — `amd_fidelityfx_dx12.dll`, `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, `amd_fidelityfx_loader_dx12.dll` | **Built 2026-10-19.** The mode an FSR title runs at reaches the vendor only as an argument of `ffxQuery` — "what render size (`…GETRENDERRESOLUTIONFROMQUALITYMODE`, `0x00010003`) or ratio (`…GETUPSCALERATIOFROMQUALITYMODE`, `0x00010002`) does this mode give at this display size?" — asked before the title sizes its targets; the per-frame dispatch carries the size alone. The detour calls the original FIRST, exactly once, and only when it returned `FFX_API_RETURN_OK` reads the descriptor's type, display size and mode and the values the vendor wrote through the title's own out pointers, into a five-slot table (one per `FfxApiUpscaleQualityMode`); the `ffxDispatch` UPSCALE arm names the ONE mode whose kept answer fits the dispatched `renderSize` (and `upscaleSize`, where stated) as `0x10 + mode` in `upscalerQuality`, else `0xFF` (`03_METRICS` §Upscaling). **Rule 4:** the arguments of the API we hooked — the descriptor the title passed and the out values of that same call — never `context`, a resource or anything the title did not hand the hooked export; nothing of the title's is written, and every read is under the hook's SEH guard. Both query layouts and type ids are pinned to literals by `static_assert`s, identical at SDK v1.1.4 and v2.3.0. **Its own family**, `FL_HOOK_UPSCALER_QUALITY` (bit 11 of `hooksInstalledMask`, mirrored in `FlHookFamily` and `HookFamilies`): `InstallByFamily` binds a row by equality, and the query entitles no measured field by itself — the byte rides under `FL_MEASURED_UPSCALER_PARAMS` from the dispatch arm — so the bit says only that the query was hooked, which tells "never asked" from "could not have seen it ask". Published like the dispatch family, once every loaded leaf is patched (`PublishFfxQueryFamilyIfWhole`); the FSR 3.0 host has no `ffxQuery` and no row (`static_assert`). A loader that passes a query on to a leaf's export refreshes one kept answer twice; nothing is counted, so nothing is counted twice. **Measured overhead** (a copy of the two bodies, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3 runs, every slot holding both a size and a ratio — the worst case): 7.6–8.2 ns added per UPSCALE dispatch, i.e. per application frame, and 1.6 ns per query beside the trampoline; the per-present path gains one load. Harness: `--ffx-query sizes|ratios`; `fl_guard` "FSR's quality mode". **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks:** when the query the vendor answered OK is the upscaler's memory — `FFX_API_QUERY_DESC_TYPE_UPSCALE_GPU_MEMORY_USAGE` (`0x00010008`, ffx-api 1.1.2) or `…_V2` (`0x00010009`, 2.0) — the `FfxApiEffectMemoryUsage` it wrote through the title's own out-pointer is kept (total and aliasable bytes), one module's queries counted. Only a title that asks is answered: FrameLedger never calls `ffxQuery` itself. The frame-generation memory queries (`0x00020007`, `0x0002000b`) are not read. +4.3–6.1 ns per such query while asked. Harness: `--ffx-memory-query v1|v2`; `fl_guard` "region 5 stays empty until the Agent asks". |
|
||||
| ~~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~~ |
|
||||
| ✅ **FidelityFX ffx-api: `ffxConfigure` on the same four modules** (0.1.0-beta.43, Advanced metrics train B; owner decisions D111–D116, D122) | **How the game configures FSR frame generation** — a title calls `ffxConfigure` with a frame-generation descriptor, usually every frame. Rule 4: an argument of the call hooked, and of it only what is named here. **Read**, and only when the header's type is `FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION` (`0x20002`): `frameGenerationEnabled`, `allowAsyncWorkloads`, `flags`, `onlyPresentGenerated`, `generationRect`. **Never read:** `swapChain`, the two callbacks and their contexts, `HUDLessColor`, `frameID`; and of every other configure type — key-value pairs, the distortion field, the camera info — nothing but the header's type. ctest `fl_adv_fields` publishes two descriptors that differ in all of those and gets the same bytes out, and hands the detour a key-value descriptor, which is shorter, without a read past it. **Installed only where asked for** (D111), as `slSetConstants` is: `InstallByFamily` returns before it resolves anything in a process never asked for Advanced metrics, so with the option off the export's first bytes in the target are the file's (`fl_guard` `[advanced]`). Published when every ffx-api module the process loaded is patched (`FL_HOOK_FFX_CONFIGURE`, bit 14), as the dispatch and query families are. **Counted at the first module that saw a frame-generation configure** — an owner slot of its own: the fixture's loader has always handed `ffxConfigure` on to the leaf's export, and Cyberpunk 2077's loader does the same with dispatches, so one call reaches two hooked modules (the injected case reads one configure a frame through the loader, not two). The rectangle is stored in one word, sixteen bits a side, so a publication never carries half of one rectangle beside half of the next; a side that is negative or past fifteen bits makes it four `-1`. The descriptor's type is kept for the log whatever it is (`FFX_CONFIGURE`, §Native logging). The detour consults `MayObserve()` first. **Measured overhead** (the detour's body on the headers, the Overlay's flags, 20 million calls a run, three runs): not asked **+1.72 / +1.68 / +1.78 ns** (the type kept for the log); asked, the counted module **+15.02 / +15.55 / +15.11 ns**; asked, the forwarded copy +2.70 / +2.81 / +2.65 ns; asked, another configure type +2.43 / +2.55 / +2.47 ns. |
|
||||
| ✅ **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
|
||||
@@ -295,6 +305,72 @@ So:
|
||||
> **`third_party/streamline/README.md` asserted this pass existed for five days
|
||||
> before it did**, which is why it is described here rather than only there.
|
||||
|
||||
### Which struct version carries which field (owner decision D115, 2026-11-11)
|
||||
|
||||
**A field of a vendor struct is read only where it is proven to be there.** A game hands a hook a struct of the
|
||||
version it was built against; a member a later version added lies past the end of what an older game allocated, and
|
||||
reading it is reading game memory outside the argument (rule 4) — not merely a wrong value. So every read of a tail
|
||||
member is gated on the struct's own version, and the gate comes from this table, not from the one header in the tree
|
||||
— which declares only the newest shape, and for `sl::DLSSOptions` says nothing about which version added what.
|
||||
|
||||
Established 2026-11-11 from the upstream tags, through GitHub's API: each tag's header was fetched by blob and the
|
||||
struct's declarations — type, name and order — compared across tags. The members' own types were checked at the
|
||||
oldest and the newest tag (`enum Boolean : char`, `enum class DLSSMode : uint32_t`, `enum class DLSSPreset :
|
||||
uint32_t`, `float2`/`float3`/`float4x4`; no `#pragma pack` in either).
|
||||
|
||||
**Streamline** (`NVIDIA-RTX/Streamline`; tags v2.0.0, v2.1.0, v2.2.0, v2.4.0, v2.4.15, v2.7.2, v2.7.30, v2.7.32,
|
||||
v2.8.0, v2.9.0, v2.10.0, v2.10.3, v2.11.1, v2.12.0, v2.14.1, v2.14.16):
|
||||
|
||||
| Struct | `structVersion` | First tag (blob of the header) | Members that version adds, in order |
|
||||
|---|---|---|---|
|
||||
| `sl::DLSSOptions` (`include/sl_dlss.h`) | 1 | v2.0.0 (`7de7411e507d`) | `mode`, `outputWidth`, `outputHeight`, `sharpness`, `preExposure`, `exposureScale`, `colorBuffersHDR`, `indicatorInvertAxisX`, `indicatorInvertAxisY`, `dlaaPreset`, `qualityPreset`, `balancedPreset`, `performancePreset`, `ultraPerformancePreset` |
|
||||
| | 2 | v2.1.0 (`60882f60e6f4`) | `ultraQualityPreset`, `useAutoExposure` |
|
||||
| | 3 | v2.4.0 (`27d352db364f`) | `alphaUpscalingEnabled` |
|
||||
| `sl::Constants` (`include/sl_consts.h`) | 1 | v2.0.0 (`db6f37adcf66`) | every member through `motionVectorsJittered` — the matrices, `jitterOffset`, `mvecScale`, `cameraPinholeOffset`, the camera's position and axes, `cameraNear`, `cameraFar`, `cameraFOV`, `cameraAspectRatio`, `motionVectorsInvalidValue`, the seven `Boolean`s |
|
||||
| | 2 | v2.4.0 (`bba15338a623`) | `minRelativeLinearDepthObjectSeparation` |
|
||||
| `sl::FeatureVersion` (`include/sl.h`; `include/sl_core_types.h` from v2.7.2) | 1 | v2.0.0 (`fc2d6ee39fea`) | `versionSL`, `versionNGX` |
|
||||
| `sl::FeatureRequirements` (the same headers) | 1 | v2.0.0 (`fc2d6ee39fea`) | `flags`, `maxNumCPUThreads`, `maxNumViewports`, `numRequiredTags`, `requiredTags`, `osVersionDetected`, `osVersionRequired`, `driverVersionDetected`, `driverVersionRequired`, then ten Vulkan members from `vkNumComputeQueuesRequired` to `vkFeatures13` |
|
||||
| | 2 | v2.1.0 (`79037e0974d2`) | `vkNumOpticalFlowQueuesRequired` |
|
||||
|
||||
`sl::DLSSOptions` keeps those seventeen declarations, same types and order, through v2.14.16 (`9a875bd4f843`); v2.8.0
|
||||
only re-spelled the deprecated `sharpness`. `sl::Constants` is unchanged from v2.4.0 through v2.14.16
|
||||
(`15589e577df9`). Streamline 1.x is refused before any read (`SpeaksStreamline2`). **Since 0.1.0-beta.43 the
|
||||
Overlay reads `sl::Constants`, and only members of version 1** — nothing of version 2 — so no version test beyond
|
||||
"at least 1" is needed, and the read ends before `minRelativeLinearDepthObjectSeparation`, the member version 2
|
||||
added.
|
||||
|
||||
**The two answers about a feature** (established 2026-11-12, the same way, over the same sixteen tags):
|
||||
`sl::FeatureVersion` is two members at every tag, and `sl::FeatureRequirements` is the nineteen of v2.0.0 plus the
|
||||
one v2.1.0 added, unchanged through v2.14.16 (`a255f5c5e99a`). `sl::Version` is three `uint32_t` — `major`, `minor`,
|
||||
`build` — in `include/sl_version.h` from v2.0.0 (`deec7cd04363`) to v2.14.16 (`dc3041ae8b44`), and the two functions'
|
||||
declarations are the same at both ends: `sl::Result slGetFeatureVersion(sl::Feature, sl::FeatureVersion&)` and
|
||||
`sl::Result slGetFeatureRequirements(sl::Feature, sl::FeatureRequirements&)`. **Since 0.1.0-beta.44 the Overlay reads
|
||||
both, and only members of version 1**: the read of the requirements ends at `driverVersionRequired`, before the first
|
||||
Vulkan member, so no version test beyond "at least 1" is needed.
|
||||
|
||||
**FidelityFX** (`GPUOpen-LibrariesAndSDKs/FidelityFX-SDK`; tags v1.1.0 — FSR 3.1.0, the first ffx-api — v1.1.1,
|
||||
v1.1.2, v1.1.3, v1.1.4, v2.0.0, v2.1.0, v2.2.0, v2.3.0, v2.4.0). The descriptor header carries a `type` and no size
|
||||
or version, so the question is whether the declaration ever changed:
|
||||
|
||||
| Struct | Tags | Result |
|
||||
|---|---|---|
|
||||
| `ffxDispatchDescUpscale` | v1.1.0 (`68860479bb94`) … v2.4.0 (`9d4a3e5f6c60`) | **one declaration in all ten**: twenty-three members, `flags` the last |
|
||||
| `ffxConfigureDescFrameGeneration` | v1.1.0 (`0ecdd4b4e59b`) … v2.4.0 (`823a3b4720f1`) | **one declaration in all ten**: thirteen members |
|
||||
| `FfxApiResource`, `FfxApiResourceDescription`, `FfxApiFloatCoords2D`, `FfxApiDimensions2D`, `FfxApiRect2D` | v1.1.0 … v2.4.0 | one declaration each in all ten |
|
||||
| `ffxQueryDescUpscaleGetGPUMemoryUsage` (`0x00010008`), `FfxApiEffectMemoryUsage` | from v1.1.2 | one declaration since; a game that sends the type knows the struct |
|
||||
| `ffxQueryDescUpscaleGetGPUMemoryUsageV2` (`0x00010009`) | from v2.0.0 | one declaration since |
|
||||
|
||||
**What follows for a hook** (Advanced metrics, train B):
|
||||
|
||||
- `sl::DLSSOptions`: a member is read at `structVersion >=` the row that adds it — never "at least 1" for the tail.
|
||||
- `sl::Constants`: everything this project may read is version 1's. The camera's position, axes and matrices are
|
||||
never read at any version (rule 4; the catalog's `PlayerState`).
|
||||
- `ffxDispatchDescUpscale`, `ffxConfigureDescFrameGeneration`: every member may be read on the ffx-api route, since
|
||||
no ffx-api release has a shorter one. `ffxDispatchDescFrameGenerationPrepareV2`'s camera arrays are never read.
|
||||
- **Not established, so nothing more is read there**: the FSR 3.0 host's legacy descriptors (`fsr3-v3.0.x`) beyond
|
||||
the `renderSize` the existing hook pins; any struct of a Streamline or FidelityFX release newer than the last tag
|
||||
above — a re-vendoring re-runs this comparison (`third_party/*/README.md` §Checklist).
|
||||
|
||||
### Ray tracing
|
||||
| Hook | Yields |
|
||||
|---|---|
|
||||
@@ -328,8 +404,8 @@ So:
|
||||
### Memory / latency
|
||||
| Hook / call | Yields |
|
||||
|---|---|
|
||||
| `IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread) | **Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact |
|
||||
| NVAPI Reflex: hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`; call `NvAPI_D3D_GetLatency` | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
|
||||
| ~~`IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread)~~ | ~~**Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact~~ **Never built; superseded 2026-10-03 (D43):** the game's memory is read from OUTSIDE the game by the Agent (`18_GPU_VENDOR_APIS` §The game process's memory), so nothing in the Overlay calls it. Only the budget would need it, and that stays open (`20_OPEN_QUESTIONS` §M11) |
|
||||
| NVAPI Reflex: ~~hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`~~; call `NvAPI_D3D_GetLatency` *(**never built.** The two hooks cannot be: neither function is an export — `20_OPEN_QUESTIONS` §M14. What a call-only route would take is read through in `spike-notes` §30, 2026-11-12, and waits for the owner's go or no)* | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
|
||||
|
||||
### Explicitly not hooked
|
||||
Input APIs, file I/O, network, memory allocators, window messages beyond what the overlay needs, anything game-specific. Rule 4 in CLAUDE.md.
|
||||
@@ -359,7 +435,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.
|
||||
|
||||
@@ -474,7 +552,7 @@ struct alignas(64) FlFrameRecord { // 64 bytes exactly, static_assert'd
|
||||
uint16_t outputW, outputH; // @22
|
||||
uint8_t api; // @26 d3d11|d3d12|vulkan|opengl
|
||||
uint8_t upscaler; // @27 0 = NOT_REPORTED; dlss|fsr2..4|xess|nis|none(8)|unknown(0xFF)
|
||||
uint8_t upscalerQuality; // @28 vendor enum; 0xFF = a hook ran and could not tell
|
||||
uint8_t upscalerQuality; // @28 vendor enum (FSR: 0x10 + mode, beta.25); 0xFF = a hook ran and could not tell
|
||||
uint8_t fgMode; // @29 0 = NOT_REPORTED; dlss_g|fsr_fg|xefg|none(4)|unknown(0xFF)
|
||||
uint8_t rtFlags; // @30 bit0 asBuildOBSERVED, bit1 dispatchOBSERVED, bit2 psoCreatedEver
|
||||
uint8_t colorSpace; // @31 0 = NOT_REPORTED, 1 SDR, 2 HDR10, 3 scRGB
|
||||
@@ -487,7 +565,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 +605,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 +642,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 — and, since layout 5 (2026-11-11), region 5's twenty-three, which the watchdog alone writes and only while the Agent asks (`07_IPC` §Region 5) — *(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 +659,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 +687,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.
|
||||
|
||||
@@ -624,7 +714,7 @@ Every hook body is wrapped:
|
||||
```
|
||||
|
||||
- Any SEH exception inside our code ⇒ increment `faultCount`, record which hook, **return control to the original function** so the game continues.
|
||||
- 3 faults total ⇒ set `status = self_disabled`, uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
|
||||
- 3 faults total ⇒ set `status = self_disabled`, ~~uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`)~~ restore each patch's prologue only while its bytes are still our jump (compare-and-restore per patch through `StopObserving`, §Unhooking, §H7 — `MH_ALL_HOOKS` would have removed an overlay chained after us; corrected 2026-09-27; since 0.1.0-beta.46 the patches that are still ours come out together, under one stop of the threads — §Unhooking, Batches), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
|
||||
- Never `__try` around the call to the original function — only around *our* code, so we never mask a game bug as ours or vice versa.
|
||||
- The trampoline call to the original is always executed exactly once, on every path, including error paths.
|
||||
|
||||
@@ -644,8 +734,84 @@ Every hook body is wrapped:
|
||||
> foreign one in ctest `fl_unhook_inline` (the vtable form stays in `fl_unhook_preserves_foreign`), and
|
||||
> against the injected Overlay in ctest `fl_guard` `[log]`, where every patch reads `UNHOOK_RESTORED`
|
||||
> because the harness is alone in its process.
|
||||
>
|
||||
> **The registry refuses what it cannot hold, and a patch is registered before it can run (0.1.0-beta.42,
|
||||
> `fl_patch_registry.h`).** The registry was an array and a counter, and two things were wrong with it — found by
|
||||
> reading the code for the plan of the next two hooks, not by a failure. **Full meant silent:** `RegisterPatch`
|
||||
> wrote its entry only while it fitted, after `PatchTarget` had already enabled the hook, so a 49th patch would
|
||||
> have been live and unknown to the stop, with no line anywhere. (Twenty patch sites exist; the rule no longer
|
||||
> depends on that count being right, and a `static_assert` now checks the capacity against the inventory's own row
|
||||
> count plus the seven sites that are not rows.) **Enabled before registered:** `PatchTarget` enabled the hook,
|
||||
> re-read `g_observing`, and registered last; a stop between the re-read and the registration walked a table
|
||||
> that did not hold the patch yet, and the patch stayed in after "stopped". The DXGI three and the loader detour
|
||||
> registered after enabling too, with no re-read at all.
|
||||
>
|
||||
> One sequence now, `fl::patch::Install`: **take a slot — no slot, no patch, nothing created — create, enable,
|
||||
> commit the slot, then re-read the flag.** The stop clears the flag and then walks the committed slots. Each side
|
||||
> writes and then reads what the other wrote, sequentially consistent, so at least one sees the other: the walk
|
||||
> restores the patch, or the installer finds the flag clear and takes its own patch out (and retires the slot,
|
||||
> so the walk does not report it as somebody else's). A slot whose patch failed is free again; one that was ever
|
||||
> live is never reused — the walk reads it without a lock. Nothing is created once observing is off. A patch
|
||||
> that did not go in is logged once per target and reason, `PATCH_FAILED a=<reason>` (`2` stopped, `3` registry
|
||||
> full, `4` create failed, `5` enable failed, `6` the stop arrived meanwhile); until now every such failure was
|
||||
> silent. The three DXGI patches are still enabled together and keep the same rules by hand; when any step of
|
||||
> theirs fails, whatever a partial enable left in is taken out — it used to stay, unregistered, with init
|
||||
> reporting failure. And two stores that could overwrite a stop's reason no longer do: `READY` is written only
|
||||
> over `INIT`, and init's failure path stores nothing. No hook body changed. ctest `fl_unhook_inline` drives
|
||||
> the shipped sequence against real MinHook patches: a full registry leaves the target's bytes untouched and
|
||||
> MinHook unasked; a stop arranged between the enable and the re-read ends with the function unpatched; a failed
|
||||
> patch gives its slot back; a slot is invisible to the walk until committed.
|
||||
>
|
||||
> **Batches, 0.1.0-beta.46 (owner decision D134): one stop of the game's threads for a group of patches.** MinHook
|
||||
> writes a jump with every other thread of the process stopped — a snapshot of the system's threads, then a
|
||||
> suspend, a context read and a resume for each of the process's — and `MH_EnableHook` / `MH_DisableHook` for one
|
||||
> target do all of that for one jump. The owner's logs of 2026-11-13 put a number on it: the thirteen Streamline
|
||||
> patches took 0.74 s to 2.8 s of a game's start, 57 to 215 ms each, and a stop restored its patches the same way.
|
||||
> MinHook 1.3.4 can queue — `MH_QueueEnableHook` / `MH_QueueDisableHook` mark a hook, `MH_ApplyQueued` executes
|
||||
> every mark under one stop — and `fl_patch_registry.h` now has the two sequences that use it:
|
||||
> `fl::patch::Batch` (`Add`: slot and create, nothing marked; `Commit`: enable them all) and
|
||||
> `fl::patch::RestoreAll`, which is the stop's walk. `InstallUpscalerHooks` queues every row a tick finds
|
||||
> something for and commits once, before the families that are published "when whole"; `InstallRtHooks` batches
|
||||
> its two; `StopObserving` calls `RestoreAll`. A patch's `HOOK_INSTALLED` line, family bit and latch still come in
|
||||
> that order and only once it is in. The loader detour, OpenGL and the three DXGI patches of init are as they were.
|
||||
>
|
||||
> **What the queue makes dangerous, and what the code therefore never does** (the plan was reviewed against
|
||||
> `hook.c` before a line was written, and its first form was refused). `MH_ApplyQueued` applies **every** hook
|
||||
> whose mark differs from its state — the process has one table, not one per caller. So (1) **no mark is ever left
|
||||
> standing**: a hook that failed to enable has its mark removed, or the next apply — the stop's own — would enable
|
||||
> it; (2) **only a patch that is still ours is ever marked for a restore** (`StillOurs`, as before; §H7), and
|
||||
> nothing is marked "all" — the refused draft marked everything and then un-marked what it must not restore, and
|
||||
> un-marking a hook that is already out marks it for *enabling*: the stop would have put a patch back in after the
|
||||
> stop; (3) **mark, apply and commit happen inside a gate** (`MinHookEngine::BeginQueue`, a slim lock taken
|
||||
> exclusively) so the watchdog's apply cannot execute the stop's marks nor the stop's the watchdog's. The gate is
|
||||
> held for one apply and never across a symbol lookup, which takes the loader's lock. It is the one lock in the
|
||||
> Overlay, and it is on no hook body's path: the only way from a hook to it is the stop itself, which already
|
||||
> waited for MinHook's own lock and a stop of the threads for every patch. Its owner re-enters it without
|
||||
> waiting. **The verdict on an install is the engine's, not the bytes'**: a foreign overlay patching over us a
|
||||
> moment after the apply would read as "not in", and treating that as a failure would mark a restore nobody had
|
||||
> compared. `MH_ApplyQueued` stops at the first hook that fails and says only that one did; the ones after it
|
||||
> are then enabled — or, in the stop, restored — one at a time, so one bad patch still costs one patch.
|
||||
> The write-then-read pair is unchanged: the stop clears the flag and then walks; `Commit` commits its slots and
|
||||
> then re-reads the flag, and takes out — compared first — what it put in when the flag is clear. A stop that
|
||||
> lands before the commit enables nothing.
|
||||
>
|
||||
> **Measured** on `hook-harness`'s Streamline target, the development PC, three runs before and after (`fl_guard`
|
||||
> `[advanced]` prints them): the nine Advanced-only patches went in one by one over 0.60 s / 0.70 s / 0.60 s
|
||||
> from the first log line to the ninth, 76–88 ms each; as one batch they take **81 / 90 / 78 ms**. The stop restored
|
||||
> eighteen patches in 1.37 s / 1.56 s / 1.37 s; under one apply, **77 / 90 / 76 ms** — and from the Agent's request
|
||||
> to `UNHOOKED`, 1.27–1.48 s became 94–110 ms. One stop of the threads costs what it cost for one patch, whether it
|
||||
> covers four, nine or eighteen. A new log line says so in the field: `PATCH_BATCH install` / `restore`, `a` the
|
||||
> microseconds, `b` the patches. **Not measured:** a real game — how long one stop of the threads is with a few
|
||||
> hundred of them, and whether any title minds patches arriving together (owner-only item 44). One more thing the
|
||||
> queue changes for the better: MinHook's single-target disable does not move a thread that is suspended inside
|
||||
> the patched bytes (`hook.c` passes the enable action to its thread fix-up in both directions); the queued apply
|
||||
> does. ctest `fl_unhook_inline` drives `Batch` and `RestoreAll` against real MinHook (three in under one apply,
|
||||
> a duplicate target refused without holding the others up, a foreign patch left byte for byte) and against a
|
||||
> model of MinHook's table for what real MinHook cannot be made to do on demand: an apply that fails halfway or
|
||||
> not at all, a stop inside the apply, a committed patch that is already out — the refused draft's failure — and
|
||||
> that no mark is ever standing or made outside the gate.
|
||||
|
||||
`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
|
||||
|
||||
@@ -672,6 +838,12 @@ before it. And when the slot has changed, going dormant costs nothing: we stay
|
||||
loaded anyway, and our detour remains in someone else's chain doing nothing
|
||||
harmful.
|
||||
|
||||
> **Said plainly, 2026-11-13: for the inline patches that re-check has never been made.** MinHook owns the write
|
||||
> window — it stops the threads, changes the protection and writes — and `StillOurs` is asked before it is called,
|
||||
> not inside. Between the two a foreign overlay could patch over us, on a thread MinHook has not stopped yet. The
|
||||
> batches of 0.1.0-beta.46 neither close that window nor widen it: the comparison and the write are apart by one
|
||||
> stop of the threads, as they were for each patch, once instead of once a patch.
|
||||
|
||||
Verified by `hook-harness --probe-unhook` (ctest `fl_unhook_preserves_foreign`),
|
||||
which simulates the foreign hooker rather than depending on RTSS being
|
||||
installed, so it is deterministic and runs on CI. Both halves are asserted: we
|
||||
@@ -683,20 +855,82 @@ compare-and-restore that never restores is not a fix.
|
||||
No logging in hook bodies. A small fixed-size in-memory ring of structured events (hook installed, symbol missing, fault, unhook) is flushed to `logs\overlay-<pid>-*.log` by the init thread at session end, on unhook, or on Agent request — never mid-frame.
|
||||
|
||||
> **Built 2026-09-06 (P1 item 4), as specified, with the details a bug report needs.** A ring of 256 ×
|
||||
> 64-byte events (`qpc`, code, two operands, a 40-char name) appended with one `fetch_add` from init and
|
||||
> ~~64-byte events (`qpc`, code, two operands, a 40-char name)~~ 96-byte events (`qpc`, code, two operands, a
|
||||
> 72-char name — 64 bytes and 40 characters until beta.42) appended with one `fetch_add` from init and
|
||||
> watchdog paths and from a hook's **SEH handler** — `NoteFault` records the exception code and the hook's
|
||||
> `__func__` — never from a hook body. Codes: `RING_CREATED`, `PRESENT_HOOKS`, `HOOK_INSTALLED` (one per
|
||||
> patch, with the target address), `SYMBOL_MISSING` (once per pair, and only when the module IS mapped),
|
||||
> `FAULT`, `STOP` (the reason), `UNHOOK_RESTORED` / `UNHOOK_DECLINED` (one per patch), `LOADER_DETOUR`,
|
||||
> `SUPERVISION_LOST`. **Three flush points, none on a present path:** the end of `InitThread` (so the
|
||||
> `SUPERVISION_LOST`, since beta.24 `STOP_FLUSHED` (the last line after a stop: `a=1` when the stop had finished
|
||||
> writing), and since beta.42 `PATCH_FAILED` (a patch that did not go in, once per target and reason — §Unhooking)
|
||||
> and `FFX_DISPATCH`, `FFX_QUERY`, `UPSCALE_ROUTE`, `RUNTIME_CENSUS` (the note at the end of this section), and
|
||||
> since beta.43 `FFX_CONFIGURE` — each configure type a hooked ffx module was handed, in a process where
|
||||
> `ffxConfigure` is hooked at all (one asked for Advanced metrics) — and since beta.46 `PATCH_BATCH`: one line an
|
||||
> apply, `install` or `restore`, `a` the microseconds it took and `b` the patches it covered (§Unhooking, Batches).
|
||||
> **Three flush points — four since beta.42, the same note —, none on a present path:** the end of `InitThread` (so the
|
||||
> file exists from the start of the session and a crash mid-session still leaves it), the watchdog when
|
||||
> `FlControlBlock.logFlushRequested` changes (a counter the Agent bumps at session end; nothing clears it),
|
||||
> and the watchdog on its way out after any stop. Appended, never recreated; events overwritten before a
|
||||
> flush are counted in a `#` line. Path: `%LOCALAPPDATA%\FrameLedger\logs\overlay-<pid>-<yyyymmdd-hhmmss>.log`,
|
||||
> flush are counted in a `#` line.
|
||||
>
|
||||
> **The stop and the last flush, beta.24 (`fl_guard`'s native-log case, red under load since beta.9).** A stop sets
|
||||
> `g_observing` to 0 first and writes its `STOP` / `UNHOOK_*` lines after, and the watchdog's loop returns the moment
|
||||
> it reads 0. When the stop ran on a presenting thread — `MayObserve`'s one-frame safety stop — the watchdog's one
|
||||
> final flush could run while that thread was still writing, and the lines after it (the kernelbase loader detour is
|
||||
> the last patch) reached the ring after the last flush ever made. The stop now says when its last line is in, and
|
||||
> wakes the watchdog; the final flush waits for that, bounded at 2 s *(a quarter of a second for every patch the registry can hold since beta.45; the stop is one apply since beta.46 and the bound is for its fallback)*, then writes `STOP_FLUSHED`. And each slot has a
|
||||
> commit word written after its fields: `LogNote` claims a slot with one `fetch_add` and fills it afterwards, so a
|
||||
> flush on another thread could print a slot still being filled. A flush now prints only slots whose writer has
|
||||
> finished — an ordinary flush stops at the first that is not, for the next one; the final flush names it in a `#`
|
||||
> line. Nothing on a present path changed. Path: `%LOCALAPPDATA%\FrameLedger\logs\overlay-<pid>-<yyyymmdd-hhmmss>.log`,
|
||||
> resolved by `SHGetKnownFolderPath` (§S21's rule, not the environment). No allocation: static ring,
|
||||
> static 64 KiB format buffer, static path. The CaptureHost prints the file and its `FAULT` / `STOP` /
|
||||
> `UNHOOK_*` / `SYMBOL_MISSING` / `SUPERVISION_LOST` lines at the end of every session
|
||||
> `UNHOOK_*` / `SYMBOL_MISSING` / `PATCH_FAILED` / `SUPERVISION_LOST` lines at the end of every session
|
||||
> (`Consume/OverlayLog.cs`).
|
||||
>
|
||||
> **The log outlives the game, and says what each ffx module was handed (0.1.0-beta.42, owner decision D121).**
|
||||
> Cyberpunk 2077, set to FSR upscaling with FSR frame generation, was recorded with frame generation measured and
|
||||
> the upscaler "unknown": PREPARE and FRAMEGENERATION dispatches arrived and no UPSCALE ever did. The log could
|
||||
> not say why. **It ended half a second into the session** — written at the end of init, then only when the Agent
|
||||
> asked or a stop ran, and a game that exits does neither: the watchdog dies with the process. And **it could not
|
||||
> have said much**: the two one-target rows logged their symbol and every other row the word `hook`, so four ffx
|
||||
> modules were one indistinguishable line each. Four changes, none of them a new patch site:
|
||||
>
|
||||
> 1. **A fourth flush point: the watchdog, on any tick that finds something new in the ring** (`FlushLogIfNew`:
|
||||
> one load on an uneventful tick, no file opened). Events are few and bounded — installs, first sights, three
|
||||
> faults at most — so this is a handful of appends a session. The init thread's flush moved to **before** the
|
||||
> watchdog is created: `FlushLog`'s state belongs to one thread at a time, and with the watchdog flushing on its
|
||||
> first tick the old order could run two at once.
|
||||
> 2. **Every install line names its module and its symbol** — `amd_fidelityfx_dx12.dll!ffxDispatch` — built at
|
||||
> compile time from the inventory row's own two spellings (`fl::inventory::NameOfRow`), so no second list of
|
||||
> names exists. The same name is on the `UNHOOK_*` and `PATCH_FAILED` lines. The event's text grew from 40 to
|
||||
> 72 characters for it (an event is 96 bytes; the ring 24 KiB, static), and `PatchTarget` lost its default
|
||||
> name, so a new call site cannot log `hook`.
|
||||
> 3. **`FFX_DISPATCH` / `FFX_QUERY`: each descriptor type a hooked ffx-api module was handed, once**
|
||||
> (`fl_ffx_types.h`). Text = the module, `b` = the type (`0x10001` UPSCALE, `0x20004` / `0x2000c` PREPARE,
|
||||
> `0x20003` FRAMEGENERATION, …); `a` ≠ 0 with `b=0` says what did not fit (`1` a ninth distinct type, `2` a
|
||||
> type of zero). The detour keeps the value of `type` — the member it reads already to choose an arm — in the
|
||||
> first free of eight slots per module and entry point; the watchdog writes it. A query's type is kept whatever
|
||||
> the vendor answered. `UPSCALE_ROUTE` names each source an UPSCALE came from, once (the FSR 3.0 host has no
|
||||
> descriptor type, so this is the only line that says its export was called), and `RUNTIME_CENSUS` repeats the
|
||||
> census word (`b`) whenever it gains a bit — both from words the detours kept before, at no cost to a hook.
|
||||
> 4. **`PATCH_FAILED`** (§Unhooking) is the fourth: a patch that did not go in used to leave no line at all.
|
||||
>
|
||||
> **This is a diagnostic, not a measurement, and it is not behind the Advanced-metrics switch** — like
|
||||
> `HOOK_INSTALLED`, it reaches the log file and nothing else: no record, no region of the shared memory, no session.
|
||||
> Rule 4: the only thing read is `type`, of a descriptor handed to a hooked call. Rule 5: no allocation, no lock,
|
||||
> no logging in the body; a type already kept costs loads and no write.
|
||||
>
|
||||
> **Measured overhead** (on `fl_ffx_types.h` itself with the Overlay's compile flags — `/O2 /GS /guard:cf
|
||||
> /Qspectre`, 50 million calls a run, three runs, i7-14700KF): a frame's three dispatch types in turn, **+3.8 ns a
|
||||
> dispatch** (3.79 / 3.87 / 3.81); a type in the first slot +0.9 to +1.0 ns; in the eighth, the worst steady
|
||||
> state, +8.1 to +8.4 ns. A new type costs one compare-exchange, once per type and module.
|
||||
>
|
||||
> ctest `fl_ffx_types` (the header, including eight threads meeting the same six types at once: each kept exactly
|
||||
> once) and `fl_guard` `[log]`: a harness on the 1.1.x monolith, generating frames and asking a ratio query, is
|
||||
> supervised and told **nothing else** — no flush request, no stop — and its log holds the two install lines by
|
||||
> module and symbol, the three dispatch types and the query type once each, the route and the census; the process
|
||||
> is then killed and the file is as it was, one header, no `STOP`.
|
||||
|
||||
> **Tests and the real logs folder (2026-09-15).** The injection tests use the shipped Overlay, so their harness
|
||||
> logs land in the user's real `logs\` too: measured that day, 2506 overlay logs, **2492 of them hook-harness's**,
|
||||
@@ -714,7 +948,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 +956,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`.)* *(Added 2026-11-12, Advanced metrics train B: `--probe-adv-fields`, ctest `fl_adv_fields` — `fl_adv_fields.h` alone: a struct of a lower version is not read past its end, the vendors' sentinels never leave as values, the summaries, the publication, a new request starting afresh; and `--advanced` / `--ffx-memory-query v1|v2`, which make the `--hold-presenting-upscaled` and `--hold-presenting-ffx` fixtures send what Advanced metrics reads.)*
|
||||
|
||||
> **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).
|
||||
+665
-14
@@ -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,20 +52,58 @@ 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.)* **Built in beta.13:** the recorder hands the handshake's
|
||||
> `adapterLuid` to the poller at the first tick that carries one (`CaptureProgress.AdapterLuid`, noted in the
|
||||
> `.partial`), and `CompositeTelemetrySource.SelectAdapter` points L1 at it (`IGpuAdapterSelector`) and tells the layers
|
||||
> that read their own GPU its vendor (`IGpuVendorFollower`): L2 maps that vendor's GPU node instead of the first one
|
||||
> LibreHardwareMonitor lists (on a laptop often the integrated GPU), and L3 contributes nothing when the game's adapter
|
||||
> is not NVIDIA's — N/A rather than another card's temperature. **What stays first-found:** a session before the game's
|
||||
> first present, a Tier-2 session (no handshake), a game presenting through OpenGL or Vulkan (they publish no LUID), two
|
||||
> GPUs of one vendor (L2 and L3 take that vendor's first), and the session's hardware snapshot
|
||||
> (`HardwareSnapshotSource`, taken before the first present). Every
|
||||
> poller sample is stamped with QPC (`TelemetrySample.QpcTicks`), the ring's clock, and
|
||||
> `QpcClockTests` pins `Stopwatch` / `TimeProvider.GetTimestamp` to the real counter.
|
||||
|
||||
> Per-process VRAM comes from the **Overlay** (`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game), not from here. Adapter-wide VRAM is a separate series with a different label — they answer different questions and users will otherwise think one of them is broken.
|
||||
> ~~Per-process VRAM comes from the **Overlay** (`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game), not from here.~~
|
||||
> **Corrected 2026-10-03 (beta.12, D43): the game process's memory is read from OUTSIDE the game** — §The game process's
|
||||
> memory below; the Overlay never called `QueryVideoMemoryInfo`. Adapter-wide VRAM is a separate series with a different
|
||||
> label — they answer different questions and users will otherwise think one of them is broken.
|
||||
|
||||
### The game process's memory (beta.12, owner decision D43)
|
||||
|
||||
`FrameLedger.ProcessStats.dll` — the third native facade the Agent loads beside itself (`NativeProcessStats`, after the
|
||||
guard's and the NVAPI bridge's), never into a game — reads one process's memory per call:
|
||||
|
||||
- **Video memory:** the documented performance counters `\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated
|
||||
Usage` and `\Shared Usage` (`PdhAddEnglishCounterW` with a `*` instance, so a localised counter name does not matter;
|
||||
`PdhGetFormattedCounterArrayW` after each collection), every instance naming the pid **summed** — each adapter and
|
||||
physical index the process allocated on. This is the per-process figure, so the adapter-wide rule below ("filter to our
|
||||
adapter, don't sum blindly") does not apply to it. **No handle to the game is needed.**
|
||||
- **System memory:** `GetProcessMemoryInfo` with `PROCESS_MEMORY_COUNTERS_EX2` (its `PrivateWorkingSetSize` is Task
|
||||
Manager's "Memory"), retried with `PROCESS_MEMORY_COUNTERS_EX` where the OS refuses the larger structure; an EX2
|
||||
answer whose private working set was left as written (a sentinel) or reads zero beside a nonzero working set is N/A,
|
||||
never a measured zero. It needs `PROCESS_QUERY_LIMITED_INFORMATION` and
|
||||
nothing more: the session's held handle when it has one, else a handle opened for the read and closed after it, whose
|
||||
creation time must be the watcher's (a reused pid is refused, not read).
|
||||
- **Not `D3DKMTQueryStatistics`.** It answers the same per-process segment figures, but Microsoft documents it as
|
||||
"Reserved for system use"; the counters are the documented face of the same accounting.
|
||||
- Measured on the dev box (`spike-notes` §16): one collect + read costs 0.1 ms (max 0.22 ms), a 512 MiB allocation reads
|
||||
+512.0 MiB, the private working set equals `\Process V2(…)\Working Set - Private`, 600 collections leak nothing. One
|
||||
`GameMemoryReader` per session, on the session's `fl-telemetry` thread (`TelemetryPoller`'s third source).
|
||||
|
||||
## 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`
|
||||
- `\GPU Process Memory(*)\Dedicated Usage` (cross-check against the Overlay's figure)
|
||||
- `\GPU Process Memory(*)\Dedicated Usage` ~~(cross-check against the Overlay's figure)~~ — **read since 2026-10-03
|
||||
as the game process's own figure** (§The game process's memory; the Overlay never produced one)
|
||||
- Instance names embed the LUID — parse and filter to our adapter, don't sum blindly across GPUs.
|
||||
|
||||
> **Built 2026-09-09 (PR-E1), one counter of the three:** `PdhAdapterMemoryCounter` binds
|
||||
@@ -75,8 +113,10 @@ Implementations compose rather than compete:
|
||||
> idle desktop, moving tick to tick. A machine without the counter set fails the open and the
|
||||
> field is N/A with the layer standing — not a fault. **`Utilization Percentage` is deliberately
|
||||
> not read** (`20_OPEN_QUESTIONS` §M10, decided): `LoadPct` is L2's vendor-reported load and is
|
||||
> labelled as such. `GPU Process Memory` is not read either — the Overlay's in-process figure is
|
||||
> the one the pipeline stores, and a cross-check is a diagnostic, not a field.
|
||||
> labelled as such. ~~`GPU Process Memory` is not read either — the Overlay's in-process figure is
|
||||
> the one the pipeline stores, and a cross-check is a diagnostic, not a field.~~ **Since 2026-10-03 (D43) `GPU Process
|
||||
> Memory` IS read** — by `FrameLedger.ProcessStats.dll`, as the game process's dedicated and shared GPU memory; there was
|
||||
> never an in-process figure to cross-check.
|
||||
- **Driver version:** ~~`SetupAPI` / registry adapter properties.~~ **`IDXGIAdapter::CheckInterfaceSupport(IDXGIDevice)`** — its documented second output is the user-mode driver version for that interface, four 16-bit fields of one 64-bit value (`32.0.16.1664` on the dev box, 2026-09-09; the WARP adapter answers with the OS build). Neither SetupAPI nor the registry is walked: both need a device-instance enumeration nothing else here has a reason to carry. Feeds the hardware snapshot and the trend-chart change markers (`06_DATA_MODEL`). This is the four-part form the vendor's own tooling shows, not the marketing number (`561.09`), which only L3 knows.
|
||||
- **Optional probe, P0 evaluation only:** `D3DKMTQueryAdapterInfo` with `KMTQAITYPE_ADAPTERPERFDATA` reportedly exposes temperature, power and fan for any vendor. The D3DKMT structures are **not fully documented and have changed across Windows builds**. Treat as an experiment: if it proves stable on both Win 10 22H2 and Win 11 during P0, keep it as an L1 extra behind a capability flag; if it looks fragile, drop it and let L2 handle temperatures. Never let it be load-bearing.
|
||||
|
||||
@@ -105,7 +145,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). *(2026-11-11: still true of THIS layer's `Computer`. Advanced metrics opens a third one, of its own — the graphics card, and as administrator with PawnIO the processor, memory and motherboard groups; D103, §Advanced metrics. Storage, the power supply, controllers, the battery and the network are opened by nothing.)*
|
||||
- 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.
|
||||
@@ -118,11 +158,14 @@ 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
|
||||
> with PawnIO is the measurement. `HelloAck.cpuTempAvailable` reports those same two conditions (it was a constant
|
||||
> with PawnIO is the measurement — **which the user can now choose to make (beta.10, the admin mode: Settings ▸ Capture
|
||||
> agent ▸ Run the agent as administrator, `01_ARCHITECTURE` ADR-9)**; until beta.10 an elevated Agent existed only when an
|
||||
> App started as administrator happened to start it, and `PrivilegeFootprintTests` now asserts on the elevated CI runner
|
||||
> that opening this CPU group enables no privilege. `HelloAck.cpuTempAvailable` reports those same two conditions (it was a constant
|
||||
> `false`). A tick only the machine answered is still queued, under a placeholder `GpuSample` with
|
||||
> `TelemetryLayer.None` and no field. The `.partial` sensor chunk carries the three values in bits 12–14 of the
|
||||
> existing 16-bit presence mask, so an older file reads back with an empty reading.
|
||||
@@ -161,6 +204,8 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
|
||||
> **Not in this build, stated so nobody infers it from the table below:** VRAM (`FlNvSample.vram` is
|
||||
> reserved and its bit is never set — see the Memory row), power, hotspot temperature, per-domain
|
||||
> utilisation beyond the GPU domain, and anything Reflex (§M8: a hook fact, not a poller field).
|
||||
> *(2026-11-11: still true of `FlNvSample`, the 1 Hz telemetry layer's struct. The memory figures and the other
|
||||
> three utilisation domains are read since ABI 3 — below — into structs of their own, for Advanced metrics only.)*
|
||||
>
|
||||
> **ABI 2 (2026-09-25, beta.8): the driver profile, read-only.** The owner asked whether the NVIDIA App overrides a
|
||||
> game's DLSS (frame generation, ray reconstruction, the model preset). The NVIDIA App writes those overrides into the
|
||||
@@ -179,6 +224,39 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
|
||||
> ctest `fl_nvapi_bridge` (argument refusals, DEGRADED before init, the global profile of the test's own executable on
|
||||
> a GPU machine) and `NvapiBridgeMirrorTests` (`FlNvDriverProfileSize`, ABI 2).
|
||||
>
|
||||
> **ABI 3 (2026-11-11, owner decision D101): what "Advanced metrics" reads.** Five reads, each a struct with its
|
||||
> size first and a `present` mask, and each call behind it a query: `FlNvReadFacts` (what is true of the card whatever
|
||||
> is running — its type, bus, PCI ids, VBIOS version, architecture, core counts, the base and boost clocks, the
|
||||
> sensor's range, `NvAPI_GPU_GetMemoryInfoEx`'s four sizes, the frame-buffer sizes, the driver's package and base
|
||||
> branch, NVAPI's interface version, the chipset), `FlNvReadLive` (the same memory call's free figure with evictions
|
||||
> and promotions, the frame-buffer, video and bus utilisation, the video clock, the P-state, the board and
|
||||
> power-supply temperatures where the card has them, the throttle word, the encoder's session count and averages),
|
||||
> `FlNvReadDisplays` (per connected display: HDR formats and luminances, variable-refresh support, the adaptive-sync
|
||||
> flags), `FlNvSessionDisplay` (the display a GDI device name names: its variable-refresh state and the colour space
|
||||
> the driver reports for one process) and `FlNvProfileSettings` (every setting of the global profile, or only what a
|
||||
> game's own profile sets — a game no profile names is answered `GLOBAL` with nothing listed, never with the PC's
|
||||
> settings). No struct of ABI 2 changed size; `FL_NV_FIELD_VRAM` stays clear.
|
||||
>
|
||||
> **No identifier has an entry point** (D104): not `NvAPI_GPU_GetBoardInfo`, `NvAPI_GPU_GetUUID`, an EDID read, or
|
||||
> `NvAPI_GPU_GetEncoderSessionsInfo`, which lists WHICH programs encode. A display is passed on by its place in the
|
||||
> driver's list; NVAPI's display id is a handle of this boot and is neither stored nor shown.
|
||||
>
|
||||
> **Read-only is now a gate** (D108): `tools/nvapi-readonly-check.ps1` holds every `NvAPI_*` call of the bridge's
|
||||
> source to `tools/nvapi-allowed-calls.txt` in both directions — forty-four names — and refuses a name that sets,
|
||||
> saves, restores, registers or controls something, or that returns an identifier, **even when the list names it**.
|
||||
> Managed: `INvapiAdvancedBridge` (a port of its own beside `INvapiBridge`; `NativeNvapiBridge` implements both, and a
|
||||
> DLL that predates ABI 3 answers `Unavailable` rather than throwing) and `NvapiAdvancedReader`, which turns the five
|
||||
> structs into the catalog's facts and readings — every `nvapi.` entry whose reach is `Agent`, and no other, held by
|
||||
> `NvapiAdvancedReaderTests` in both directions. **Nothing composes the reader yet**: no Agent code calls it.
|
||||
>
|
||||
> **Measured on the dev box the day it was written** (RTX 5080, a driver of base branch `R620`, ctest `fl_nvapi_bridge`'s
|
||||
> AVAILABLE branch — `20_OPEN_QUESTIONS` §M12): all twenty facts answer (`present = 0xFFFFF`: discrete, desktop, PCI
|
||||
> Express, 84 ray-tracing and 336 tensor cores, base 2295 / boost 2670 MHz, 16,303 MiB dedicated, a DCH Game Ready
|
||||
> driver); eight of the ten live groups answer (`0x33F`) — **the board and power-supply temperatures do not exist on
|
||||
> this card**, as the memory temperature does not, and read N/A; the one display answers all four groups; the global
|
||||
> profile lists 24 settings. One thing the header had wrong: it misspells `NV_ENCODER_STATISTICS_VER` as
|
||||
> `NNV_ENCODER_STATISTICS_VER`, so the bridge names `NV_ENCODER_STATISTICS_VER1`.
|
||||
>
|
||||
> **The ctest could not fail on a GPU machine until the same day.** `fl_nvapi_bridge` was registered with
|
||||
> `PASS_REGULAR_EXPRESSION` alone, which makes ctest ignore the exit code: the AVAILABLE branch's reference-counting
|
||||
> check (two references, two releases, then a read expected to work) failed on every machine with an NVIDIA GPU while
|
||||
@@ -191,10 +269,10 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
|
||||
| Temperatures | `NvAPI_GPU_GetThermalSettings` (+ extended thermal query for hotspot/memory where available). **Bridge (2026-09-10):** the public enumeration only — core is the `GPU` target; memory is the `MEMORY` target when the driver lists one, and on the RTX 5080 it does not (bit clear → `null`); hotspot is not read |
|
||||
| Utilisation | `NvAPI_GPU_GetDynamicPstatesInfoEx` (GPU / FB / VID / BUS domains). **Bridge (2026-09-10):** the GPU domain only, as `loadPct` |
|
||||
| Clocks | `NvAPI_GPU_GetAllClockFrequencies` — **bridge (2026-09-10):** current graphics and memory clocks |
|
||||
| Memory | `NvAPI_GPU_GetMemoryInfoEx` — **not `NvAPI_GPU_GetMemoryInfo`**, which this table named until 2026-08-05. The vendored headers mark it `__nvapi_deprecated_function` ("deprecated in release 520"), so under `/W4 /WX` a call to it fails the native build. **Neither is called (2026-09-10):** the vendored `nvapi.h` (`cd6918f6`) does not declare `GetMemoryInfoEx` at all — the deprecation message names a function the same header set does not ship — so the bridge's `vram` field is **reserved**, its bit is never set, and VRAM stays L1's PDH adapter counter. Taking a newer header set is the way to change that, not a call to the deprecated one |
|
||||
| Memory | `NvAPI_GPU_GetMemoryInfoEx` — **not `NvAPI_GPU_GetMemoryInfo`**, which this table named until 2026-08-05. The vendored headers mark it `__nvapi_deprecated_function` ("deprecated in release 520"), so under `/W4 /WX` a call to it fails the native build. **Neither is called (2026-09-10):** ~~the vendored `nvapi.h` (`cd6918f6`) does not declare `GetMemoryInfoEx` at all — the deprecation message names a function the same header set does not ship~~ — so the bridge's `vram` field is **reserved**, its bit is never set, and VRAM stays L1's PDH adapter counter. ~~Taking a newer header set is the way to change that, not a call to the deprecated one~~ **Corrected 2026-11-11: the vendored set does declare it** — `nvapi_lite_common.h:600`, which `nvapi.h` includes, with `NV_GPU_MEMORY_INFO_EX_V1` above it and its id in `nvapi_interface.h`; the search that found nothing looked in `nvapi.h` alone. It was not called because of that sentence, from 2026-09-10 until now. The bridge calls it from ABI 3 for the advanced memory rows (§Advanced metrics); `FlNvSample.vram` stays reserved, so which layer fills the base `vram_adapter` series does not change |
|
||||
| **Throttle reasons** | `NvAPI_GPU_GetPerfDecreaseInfo` — not available from L1 or L2. **Bridge (2026-09-10):** the raw reason mask, and 0 is a measurement (no reason), not a clear bit |
|
||||
| Driver version | `NvAPI_SYS_GetDriverAndBranchVersion` — **bridge (2026-09-10):** `FlNvDriverVersion`, surfaced as `616.64 (r616_41)` |
|
||||
| **NGX per-process state** | `NvAPI_NGX_GetNGXOverrideState` (R570+) — the driver's feedback word per DLSS feature for a PID, read OUT OF PROCESS by `fl-probe-nvapi --ngx-state` and, since 2026-09-06, by the capture host beside each module snapshot — **in-process through the bridge since 2026-09-10** (`NvapiNgxStateProbe`; the spawn is retired and the words, the merge and the printed block are unchanged). Measured: the SR word's `CREATED \| EVALUATE` is set without an NVIDIA-app override; the FG word follows DLSS-G once created (`CREATED \| EVALUATE` at ×4, corrected the same day — the first reading was blind because it was early), the multiplier bits stay clear; `scalingRatio` is 0 even under an override. Identity only, SR and FG (`03_METRICS` §Upscaling) |
|
||||
| **NGX per-process state** | `NvAPI_NGX_GetNGXOverrideState` (R570+) — the driver's feedback word per DLSS feature for a PID, read OUT OF PROCESS by `fl-probe-nvapi --ngx-state` and, since 2026-09-06, by the capture host beside each module snapshot — **in-process through the bridge since 2026-09-10** (`NvapiNgxStateProbe`; the spawn is retired and the words, the merge and the printed block are unchanged). Measured: the SR word's `CREATED \| EVALUATE` is set without an NVIDIA-app override; the FG word follows DLSS-G once created (`CREATED \| EVALUATE` at ×4, corrected the same day — the first reading was blind because it was early), the multiplier bits stay clear; `scalingRatio` is 0 even under an override. Identity only, SR and FG (`03_METRICS` §Upscaling) — and, since beta.24 (D63), the mode an NVIDIA App override set where the word says it applied; its `performanceMode` is in NGX's own numbering (Silent Hill 2, 2026-10-13: the App's Ultra Performance, profile value 5, reported as 3). *(Beta.27: never read after the game has gone — that reading, the last, had cleared `CREATED \| EVALUATE` on every stored session — and the two bits stand once a reading carried them: `03_METRICS` §The driver-reported rung.)* |
|
||||
| **Reflex / PC latency** | `NvAPI_D3D_GetLatency` → per-frame sim/render/present/driver/GPU timestamps; hooking `NvAPI_D3D_SetSleepMode` / `SetLatencyMarker` in the Overlay tells us the game enabled Reflex (`17_HOOK_ENGINE`) |
|
||||
|
||||
Reflex latency is the single strongest reason L3 exists — it is genuinely unavailable anywhere else.
|
||||
@@ -335,7 +413,7 @@ as the same thing.
|
||||
|---|---|---|---|
|
||||
| GPU utilisation | **deferred by decision** (§M10, 2026-09-09) — L2's vendor-reported load is what `LoadPct` carries, labelled as such; the engine counters are not read | untested | untested |
|
||||
| Adapter VRAM | ✓ **measured 2026-09-09** — PDH `GPU Adapter Memory … Dedicated Usage`, 1301 MB at an idle desktop, RTX 5080 (`QueryVideoMemoryInfo` measured **not** adapter-wide: 0 bytes from the Agent) | untested | untested |
|
||||
| Per-process VRAM | `arch` for L1 — the Overlay's in-process `QueryVideoMemoryInfo` is the figure stored; `GPU Process Memory` is not read | `arch` | `arch` |
|
||||
| Per-process VRAM | ~~`arch` for L1 — the Overlay's in-process `QueryVideoMemoryInfo` is the figure stored; `GPU Process Memory` is not read~~ ✓ **measured 2026-10-03** — `GPU Process Memory` Dedicated/Shared by pid from outside the game, +512.0 MiB for a 512 MiB buffer (`spike-notes` §16) | untested | untested |
|
||||
| Driver version | ✓ **measured 2026-09-09** — `CheckInterfaceSupport(IDXGIDevice)` → `32.0.16.1664` | untested | untested |
|
||||
| Core temp | ? (D3DKMT probe, Win 11 only — see below) | untested | untested |
|
||||
| Power | ? (D3DKMT probe) | untested | untested |
|
||||
@@ -450,3 +528,576 @@ alone could never catch.
|
||||
> (`NvapiTelemetrySource` over `FrameLedger.NvapiBridge.dll`, §L3). §M5 in particular (do LHM GPU
|
||||
> sensors work unelevated, without PawnIO?) decided whether the default unelevated
|
||||
> Agent has temperatures at all — **it does, on NVIDIA; row R1 above.**
|
||||
|
||||
## Advanced metrics (owner decisions D101–D108, 2026-11-11)
|
||||
|
||||
The owner asked for a setting, *"Thông số nâng cao"* (Advanced metrics), with a navigation item of its own, that shows
|
||||
as much as the Streamline and NVAPI headers and PawnIO make available — numbers, tables, charts — **with each value
|
||||
assigned to what it belongs to: one game session, or the PC**. Asked while planning, the owner chose: everything
|
||||
that can be reached inside a game as well, in stages, the route refused on 2026-08-09 re-examined; stored in full with
|
||||
the session; off by default, and off means nothing more is read; and the page never asks for administrator rights
|
||||
itself. This section is the design those answers gave, the decisions taken with it, and the inventory.
|
||||
|
||||
**Nothing here is built by the pull request that wrote it** except the catalog
|
||||
(`FrameLedger.Application.Advanced.AdvancedMetricCatalog`) and this section. Each later pull request of the train
|
||||
states here what it built.
|
||||
|
||||
### The decisions
|
||||
|
||||
- **D101 — the option.** `telemetry.advanced`, off by default, read by the Agent at each session's start. **Off means
|
||||
not read**: no additional call to NVAPI or LibreHardwareMonitor, nothing more stored, and the navigation item is
|
||||
hidden. A session recorded while it was off shows N/A for everything here — it is not filled in afterwards.
|
||||
- **D102 — where it is stored.** In two tables of their own (schema 0023), not in new columns of `sessions`: every
|
||||
read of a `sessions` row, the JSON export and the bug bundle carry the whole row, and a driver profile does not
|
||||
belong in a bug bundle. `machine_profiles` holds the facts of the PC, one row per distinct set, and a session points
|
||||
to the row that was true when it ran — the trend's hardware-change markers and `hardware_snapshots` are untouched.
|
||||
`session_advanced` holds one session's facts, its series' statistics and their directory. The series themselves go
|
||||
to `sensor_blobs` under names that start with `adv.`, **with NaN for a tick that has no reading**: the fixed series
|
||||
store −1 there and their readers drop every negative value, which would silently eat a −12 V rail.
|
||||
- **D103 — LibreHardwareMonitor's other groups.** CPU, memory and motherboard (its sensor chip and embedded
|
||||
controller) are opened **only when the Agent already runs as administrator and PawnIO is installed** — the existing
|
||||
admin mode (D34); the page says what is missing and links to that setting. **Refused**: the power-supply and
|
||||
fan-controller groups, which make the library search every USB HID device. **Deferred**: the battery group — and
|
||||
**storage**. The plan had storage in, temperature only and internal drives only, with one outcome written down
|
||||
before any run: *if the group cannot be opened without touching removable drives, it stays closed*. It cannot: the
|
||||
library's `StorageGroup` (0.9.6, read 2026-11-11) lists every drive through DiskInfoToolkit's `ReloadStorages` with
|
||||
no filter by bus, and subscribes to drives being plugged in afterwards. So `lhm.storage.*` is `Deferred`, a drive's
|
||||
temperature reads N/A, and `LhmGroups` — the only way this code can name a group to open — has no member for it
|
||||
(`20_OPEN_QUESTIONS` §M13). This amends §L2's "nothing else, ever" from the pull request that opened the three.
|
||||
- **D104 — identifiers are never read.** The card's board serial number and unique id, a display's EDID, and the list
|
||||
of programs that are encoding. They are named in the inventory so the page can say so; a test holds that no stored
|
||||
JSON has their keys. This is the only part of "everything" left out on purpose.
|
||||
- **D105 — the navigation item** is the last of the pane's items; Ctrl+1 to Ctrl+5 keep their pages and **Ctrl+6**
|
||||
opens it only while the option is on.
|
||||
- **D106 — the `.partial` file skips what it does not know.** A chunk of an unknown type whose checksum is right is
|
||||
passed over; until now it ended the read, so a build one release older lost everything after the first new chunk.
|
||||
- **D107 — with no game running**, the Agent reads sensors only while the page is open, through one reader shared
|
||||
with the sessions, closed again some seconds after the last use. A PC idling with FrameLedger in the tray reads
|
||||
nothing (NFR-2's "~0% idle").
|
||||
- **D108 — read-only, by a gate.** §Runtime policy's "never call a setter" becomes a build check: every `NvAPI_*`
|
||||
call in the bridge's source is compared with a committed list, in both directions, and a name that changes
|
||||
something or returns an identifier is refused whatever the list says. An entry point that both reads and writes by
|
||||
a command argument — the colour and info-frame controls — is refused like a writer: the check reads names, not
|
||||
arguments, and nothing on the list is one. *(Built with ABI 3: `tools/nvapi-readonly-check.ps1`.)*
|
||||
|
||||
### The reader (built 2026-11-11; composed by the Agent since the switch)
|
||||
|
||||
`Application.Advanced.IAdvancedHardware` is the port: `Acquire()` keeps the reader running until the handle is let
|
||||
go, `Latest` is the last tick without waiting, `ReadSessionFacts` reads one session's facts on the caller's thread.
|
||||
`Infrastructure.Telemetry.AdvancedHardwareHub` implements it — **one reader for the whole Agent, on a thread of its
|
||||
own (`fl-advanced`), running only while somebody holds it** and for a linger after, so that two sessions in a row,
|
||||
or a session ending as the page opens, do not close and reopen the sensors (D107). The Agent records several
|
||||
sessions at once, each with a poller; a reader per session would open the motherboard's sensor chip as many times.
|
||||
|
||||
What runs on that thread is `AdvancedHardwareReader`: NVAPI through `NvapiAdvancedReader`, and
|
||||
`LhmAdvancedReader` over a `Computer` of its own, opened with `LhmAdvancedReader.GroupsFor(elevated, pawnIo)` —
|
||||
`LhmGroups`, an enum that has a member for the four groups this project may open and for no other. Each sensor is a
|
||||
member of a catalog family by the device at the top of its tree and its type (`LhmAdvancedMap.FamilyOf`); its series
|
||||
is named from the library's own identifier (`/lpc/nct6798d/0/voltage/3` → `adv.lhm.board.voltage.lpc_nct6798d_0_3`)
|
||||
and labelled with the hardware's words. A sensor with no family is not read.
|
||||
|
||||
- **A source that is not there is a state** (`AdvancedSources`): no NVIDIA driver, not administrator, PawnIO
|
||||
missing. Never an exception, and never a value in its place.
|
||||
- **A device that throws twice is left alone** until the reader opens again; the others go on. The library's own
|
||||
traversal stops at the first exception, so each top-level device is refreshed in a guard of its own.
|
||||
- **NVAPI answering with no field, twice running, after it had answered**: released and initialised again, once
|
||||
(`20_OPEN_QUESTIONS` §M12).
|
||||
- **The cadence was set by a measurement, before anything composed the reader.** `FrameLedger.CaptureHost
|
||||
probe-advanced` runs this reader on the caller's own rights and prints what it read and what it cost. On the dev
|
||||
box (RTX 5080, unelevated, 2026-11-11): 35 facts and 58 readings a tick — 17 from NVAPI, 41 from the card's sensors;
|
||||
**one NVAPI live read costs 0.4 ms of processor time; one refresh of LibreHardwareMonitor's graphics-card group
|
||||
costs 14 ms (62 ms elapsed)**. Once a second that refresh alone is 1.4% of one core, above NFR-2's 1% for the
|
||||
whole Agent. So NVAPI is read every tick and **the sensor library every fifth** (0.28%), and on the ticks between a
|
||||
sensor has no reading — its last value is not repeated. The same refresh is what the L2 telemetry layer does once
|
||||
a second in every session: that cost is not this feature's, and is `20_OPEN_QUESTIONS` §M16 — measured in a real
|
||||
Agent on 2026-11-11 (1.93 % of one core off, 2.04 % on) and answered by amending NFR-2 to 2.5 % (D117).
|
||||
|
||||
### From the reader to the ledger (built 2026-11-11; fed since the switch)
|
||||
|
||||
- **The poller attaches, it does not read.** `TelemetryPoller` takes an optional `IAdvancedHardware`, holds it from
|
||||
`Start` to `Dispose`, and at each poll takes `Latest` — a read of one reference. A snapshot it has not taken yet
|
||||
rides on that poll's `TelemetrySample.Advanced`; one it has already taken is not attached again, because a
|
||||
reading is of one tick. Null — the option off — composes nothing, and a sample is what it always was.
|
||||
- **The `.partial`** carries those readings in a chunk of their own after the sensor chunk (type 9) and the
|
||||
session's context in another (type 10), so a recovered session keeps both; with the option off neither is
|
||||
written. An unknown chunk type is now skipped rather than the end of the file (D106). `06_DATA_MODEL` §The
|
||||
`.partial` file.
|
||||
- **The finalizer** (`AdvancedSessionBuilder`, both tiers) turns the samples' readings into one series each,
|
||||
aligned to `t_ms` with NaN for a tick with none, and builds the session's row: facts, sources, statistics,
|
||||
directory. Schema 0023 and the rule for NaN are `06_DATA_MODEL` §Blob encoding and §Migrations.
|
||||
|
||||
### The switch (built 2026-11-11, Advanced PR-5)
|
||||
|
||||
`telemetry.advanced` (`SettingsRegistry.TelemetryAdvanced`, Boolean, default `0`, read by the Agent) becomes
|
||||
`RecorderOptions.AdvancedMetrics` through `SettingsRecorderPolicy`, at each session's start like the other recording
|
||||
settings; exactly `1` is on. From there:
|
||||
|
||||
- **The process has one sensor library** *(2026-11-12)*. One *reader* was never the whole of it: a session's L2
|
||||
source and its CPU-temperature reader each open a LibreHardwareMonitor `Computer` of their own beside the
|
||||
Advanced reader's, and the library keeps part of its state — the driver it reads the processor through, its bus
|
||||
mutexes — per process. `Computer.Close()` lets go of that part whoever else is still reading. The first sessions
|
||||
recorded as administrator with PawnIO showed it (`20_OPEN_QUESTIONS` §M13): a processor device that faulted out
|
||||
some seconds after each session's sources closed, and one session whose reader could not open at all. Every
|
||||
`Computer` is now opened and closed through `Infrastructure.Telemetry.LhmLibrary` (`LhmComputerAdapter` is its
|
||||
user): opens and closes never run at once, and a `Computer` closed while another is in use is **parked** — left
|
||||
open, read by nobody, handed to the next user of the same groups — until the last user lets go, when all are
|
||||
closed. The reads are not serialised: the readers keep their own threads, so a sensor that hangs in one still
|
||||
holds up neither the other nor the pipe.
|
||||
- **The Agent has one reader** — `AgentServices` registers `AdvancedHardwareHub` as `IAdvancedHardware`, a tick a
|
||||
second and a linger of ten — and nothing starts it but a holder. `SessionRecorder` holds it for a session's length
|
||||
**only when the option is on**, and `AgentRecording` gives the session's `TelemetryPoller` the reader on the same
|
||||
condition. Off: not held, not asked, no chunk 9 or 10, no row (`SessionRecorderTests.WithAdvancedMetricsOff…`).
|
||||
- **A session's facts are read once, off the capture loop.** Fifteen seconds after the game's process is known — by
|
||||
then it has a window — or at the session's end if that comes first, `IAdvancedHardware.ReadSessionFacts` runs on a
|
||||
pool thread: asking the driver for a profile takes some hundred milliseconds. The finalize waits at most five
|
||||
seconds for a read still in flight and stores the session without its facts rather than hold it. A read that
|
||||
throws costs the facts, never the session.
|
||||
- **Which display is the game's** comes from Windows, not from the game: `WindowGeometryProbe.MonitorDeviceOf` — the
|
||||
monitor the process's largest visible window is on, as its GDI device name — which the reader hands to
|
||||
`FlNvSessionDisplay`. No window, or a display another adapter drives: the session's display facts are absent.
|
||||
- **The context reaches the crash file as it changes** (chunk 10), from `IAdvancedHardware.Latest` — a read of one
|
||||
reference on the capture loop's task — so a recovered session keeps its machine facts, its sources and its
|
||||
directory of series.
|
||||
- **A session recorded with the option on always stores a row**, if only one that says every source is `Unknown`:
|
||||
no row means "the option was off when this was recorded", which the page (PR-7) shows as such.
|
||||
|
||||
What elevation adds changed with this: an Agent running as administrator with PawnIO reads the processor, memory
|
||||
and motherboard groups in a session with the option on. The texts that state what the admin mode adds say so —
|
||||
Disclaimer 2.15 §5 and §5A (the owner's answer of 2026-11-11), the admin mode's disclosure (`agent-admin-dialog/2`),
|
||||
Settings, the first run, the guide and `LIMITATIONS.md` — and Privacy Policy 2.15 names what is read and stored.
|
||||
|
||||
### The page's feed (built 2026-11-11, Advanced PR-6; shown by the page since PR-7)
|
||||
|
||||
With no game running the Agent reads sensors **only while the page is open** (D107), and nothing tells the Agent
|
||||
that a page opened or closed:
|
||||
|
||||
- **`GetAdvancedMachine`** (`07_IPC` §Messages) is answered by `Application.Ipc.AdvancedMachineResponder` from
|
||||
`IAdvancedHardware.Latest` alone. The first request acquires the shared reader and each one renews a five-second
|
||||
lease; a lease after the last request the hold is let go, and the reader closes its sources ten seconds later
|
||||
unless a session holds it. A page that closes, an App that exits and a pipe that drops all look the same: no
|
||||
request. With the option off the answer is `Error AdvancedOff`, and nothing is held.
|
||||
- **`App.Services.AdvancedMachineFeed`** asks once a second while a page holds `Watch()`, and keeps the facts (asked
|
||||
for once, by their hash), **the last value of every series with the tick it was read on** — a sensor read every
|
||||
fifth tick is "1400, as of then", never shown as new — five minutes of each series for the live charts, and the
|
||||
sources' states. It stores nothing. Its states are the page's own words for why there is nothing to show: waiting
|
||||
for the first read, off, no agent (a viewer never has one), an older agent.
|
||||
|
||||
### The page (built 2026-11-11, Advanced PR-7)
|
||||
|
||||
`08_UI` §Advanced is the screen. What this document's model becomes there:
|
||||
|
||||
- **A machine fact** is under *This PC* ▸ *About this PC* while the Agent answers, and under *Session* as it was
|
||||
when that session was recorded (`machine_profiles`, one row per distinct set).
|
||||
- **A session fact** is under *Session* only.
|
||||
- **A series** is a row of *Right now* and a line of *Over time* while live — never stored then — and a row of the
|
||||
session's statistics and a line of its chart once a session stored it.
|
||||
- **An entry that is not read** is on *Sources* with its reason, in the same words as §Left out, by name.
|
||||
|
||||
`ISessionRepository.ListAdvancedAsync` lists the sessions that have a row; `SessionSeriesLoader.LoadAdvancedAsync`
|
||||
decodes their series against `t_ms`, leaving a NaN tick out and keeping a negative reading.
|
||||
|
||||
### What belongs to what
|
||||
|
||||
| Scope | What it is | Stored | Shown |
|
||||
|---|---|---|---|
|
||||
| `MachineFact` | true of the PC whatever is running: the card's firmware and architecture, the driver's package, what a display can do | `machine_profiles`, once per distinct set; a session points to its row | This PC |
|
||||
| `SessionFact` | true of one session: the game's display state, the settings the driver's profile for that game sets | `session_advanced.facts_json` | Session |
|
||||
| `Series`, during a session | a sensor of the PC sampled while the game ran | `sensor_blobs` (`adv.*`), statistics in `session_advanced.stats_json` | Session |
|
||||
| `Series`, with no session | the same sensor, read because the page is open | nowhere | This PC |
|
||||
|
||||
A third tab, **Sources**, lists every row of the inventory with its state on this PC — read, or N/A with the reason:
|
||||
not an NVIDIA card, the Agent is not administrator, PawnIO is not installed, the option was off when the session was
|
||||
recorded, the hook is not built, the route is refused, a vendor's licence. A PC without an NVIDIA card shows N/A for
|
||||
every `nvapi.` row; nothing is estimated in its place (FR-4.9).
|
||||
|
||||
### The trains
|
||||
|
||||
| Train | Release | What | Its gate |
|
||||
|---|---|---|---|
|
||||
| A | 0.1.0-beta.39 | read by the Agent only — NVAPI and LibreHardwareMonitor — storage, the page. **Nothing changes in code loaded into a game** | this section |
|
||||
| B | 0.1.0-beta.40, ~~.41, .42~~ ~~.42, .43~~ .42, .43, .44 *(three releases since D113, 2026-11-11; one was planned. Renumbered 2026-11-12, D118: 0.1.0-beta.41 is a fix release for the sensor library, not part of the train. **Four since D122, the same day**: the second step is beta.42 — no new patch site — and beta.43, the two new hooks; the third step is beta.44)* | inside the game: more fields of the Streamline and FidelityFX calls already hooked, and new hooks on functions `sl.interposer.dll` **exports** (`17_HOOK_ENGINE` §Hook inventory's ⏳ rows); shared-memory layout 5 — §Train B below | a plan of its own; overhead measured; each release after the first waits for the owner's run of the one before |
|
||||
| B, a fourth step | 0.1.0-beta.45 *(D130, 2026-11-12)* | six more of Streamline's core calls — is a feature supported, is it loaded, the game switching it, its resources allocated and freed, Streamline shut down | hooks installed only where asked for, as in the second and third steps; `slInit` is not among them (D129) |
|
||||
| C | ~~0.1.0-beta.41~~ ~~0.1.0-beta.43~~ ~~0.1.0-beta.44~~ ~~0.1.0-beta.45~~ after 0.1.0-beta.45 *(D118, D122, D130)* | Reflex latency per frame | a spike — written beside beta.45, a document only — then the owner's go or no |
|
||||
| D | ~~0.1.0-beta.42~~ ~~0.1.0-beta.44~~ ~~0.1.0-beta.45~~ ~~0.1.0-beta.46~~ after train C *(D118, D122, D130)* | the Streamline feature state behind `slGetFeatureFunction` — DLSS frame generation's, DLSS's, Reflex's | a spike, then the owner's go or no |
|
||||
|
||||
Rules 4 and 5, the hook inventory, the measured overhead and the anti-cheat guard bind B, C and D exactly as they bind
|
||||
every hook. `sl::Constants` is read without its camera position, axes and matrices: where the camera is, is where the
|
||||
player is (rule 4). NGX stays closed by its licence (`17_HOOK_ENGINE` §NGX).
|
||||
|
||||
**Train D re-examines a refusal; it does not lift it.** `handoff/history/p0-queue-1-6.md` refused, on five grounds,
|
||||
hooking `slGetFeatureFunction` and patching the function it returns. The route to try is a different one:
|
||||
`slGetFeatureFunction` is itself an export (`vendor-exports.json`), so its hook is an ordinary inventory row, and
|
||||
what it hands back could be a wrapper for a fixed list of names instead of a patch at an address learned at run time
|
||||
— which would answer grounds 1 to 4, and turn ground 5 into "measured only when injected at launch". Two things it
|
||||
raises are the owner's: replacing the pointer the game receives is a **write**, which rule 4 forbids as written; and
|
||||
a wrapper must outlive the Overlay's own unhook. If the spike cannot answer all of it, the route stays refused and
|
||||
the page says so.
|
||||
|
||||
### Train B (planned 2026-11-11, owner decisions D110–D116)
|
||||
|
||||
What the catalog marks `HookedCall` and `NewHook`. Planned the day train A shipped, the owner's decisions asked while
|
||||
planning, the design reviewed against the code before it was approved.
|
||||
|
||||
- **D111 — off means off inside the game too.** The Agent writes one word of the control block
|
||||
(`advancedRequested`, ~~0 or 1~~ 0 or that session's request, unconditionally at attach) when the session records Advanced metrics. The Overlay
|
||||
reads a new field, and installs a new hook, only while it is set; with the option off it hooks and reads exactly
|
||||
what 0.1.0-beta.39's does.
|
||||
**Built 2026-11-12 (0.1.0-beta.40, PR-3), with one thing the plan did not have:** "on" is not a 1 but a
|
||||
*request* — a value no session of that ring used before. A game outlives a session, and the Overlay's summaries
|
||||
with it; a second session of a game that kept running would have read the first one's field of view and counts.
|
||||
The watchdog starts its summaries afresh at a request it has not seen and names the request in every publication;
|
||||
the Agent reads only what answers its own (`07_IPC` §Region 5). The detours consult one process-local flag, the
|
||||
watchdog is the region's one writer, and `fl_guard` shows the off half on a target that sends everything: every
|
||||
byte of the region zero until asked, untouched after an "off", a count that starts again at the next request.
|
||||
**The Agent and the App, 2026-11-12 (PR-4).** A session that records Advanced metrics says so through
|
||||
`ICaptureObserver.WantsInGameAdvanced`; `CaptureSession` writes the word either way as the ring is attached, before
|
||||
its first guard result, and from then on carries each publication of region 5 on `CaptureProgress.InGameAdvanced`
|
||||
— one instance a publication, the same one on the ten ticks between two. `Application.Capture.InGameAdvancedSampler`
|
||||
turns a publication into what a session stores: the session facts of the thirteen `Game` entries below (nineteen since 0.1.0-beta.43, twenty-one since 0.1.0-beta.44, twenty-three since 0.1.0-beta.45), in the
|
||||
vendor's own words (a preset is its letter, a member its name), and two series —
|
||||
`adv.ffx.upscale.frame_time_delta`, the mean of one second's dispatches, and `adv.ffx.memory_usage`, a point for
|
||||
each second the game asked. The facts are one list until a field they are made of moves, so the recorder's context
|
||||
is rewritten when a range widens and not once a second; the readings ride the newest telemetry sample of the tick.
|
||||
**No schema change**: the facts go into `session_advanced.facts_json` beside the driver's, the series into
|
||||
`sensor_blobs` under their `adv.` names, the `.partial`'s chunks 9 and 10 carry both. `AdvancedSources.InGame`
|
||||
(optional; absent in every row 0.1.0-beta.39 wrote) says what became of those entries in the session: `Reading`,
|
||||
`NothingSeen` — measured inside the game, and the game made none of the calls where they can be seen — or
|
||||
`NotHooked`. The page says it in the session's sources line and, on Sources, that such an entry is read inside a
|
||||
game FrameLedger measures when the game makes the call. The aliasable part of FSR's memory is published and not
|
||||
shown: the catalog has one memory entry.
|
||||
**The second step, 2026-11-12 (0.1.0-beta.43, PR-4).** Six more entries have reach `Game`: `sl.constants.jitter`,
|
||||
`.motion_vectors`, `.depth`, `.projection`, `.resets` and `ffx.framegen.config`, from the two calls hooked only
|
||||
for Advanced metrics (`17_HOOK_ENGINE` §Hook inventory, `slSetConstants` and `ffxConfigure`). The sampler makes
|
||||
them from members region 5 already had (layout 5 as it was; schema 23 as it was): a switch is `on`, `off` or
|
||||
`on_and_off` from the two words of what was seen, the flags are AMD's own names, the rectangle is the last one
|
||||
the game gave and is left out where the capture side could not state it, the field of view is a range (D114).
|
||||
**A field of view over π is said as given (owner decision D128, 0.1.0-beta.44).** Both vendors' headers say
|
||||
radians; Cyberpunk 2077 gives Streamline 51–90, and the row read `51.0055 – 90 rad (2922.4° – 5156.6°)`. Such a
|
||||
value is now the number alone, with a second row (`cameraFOV unit`, token `not_radians`) that says what it is
|
||||
not; it is never converted, which would store this project's guess at the unit as the game's word. A
|
||||
frame-generation configure that set no flag has a `flags` row of `none`, as an upscale does.
|
||||
**A count is not part of what makes the facts new** — `sl.constants.resets` grows all session, and a context
|
||||
rewritten on each would be one a second — so `InGameAdvancedSampler.Conclude` brings it up to the last
|
||||
publication once, when the session ends. `AdvancedSources.StreamlineConstants` and `.FsrFrameGeneration`
|
||||
(`AdvancedInGameCall`; null in every row written before, and in a session not measured inside the game) say for
|
||||
each call which of three things happened: `Read`; `NeverCalled` — the capture side published the hook's family
|
||||
(`FlHookFamily.SlConstants`, `.FfxConfigure` in the writer state's mask) and no publication carried the group; or
|
||||
`NotHooked` — the family was never published, which is a game that did not load the library, a Streamline 1.x
|
||||
interposer, or a patch that was refused. The page says it in one more sentence of the session's sources line.
|
||||
**The third step, 2026-11-12 (0.1.0-beta.44).** Two more entries have reach `Game`: `sl.feature.versions` and
|
||||
`sl.feature.requirements`, from what Streamline answers `slGetFeatureVersion` and `slGetFeatureRequirements`
|
||||
(`17_HOOK_ENGINE` §Hook inventory). The sampler makes them from region 5's twelve feature slots (layout 5 and
|
||||
schema 23 as they were): rows named `<feature> · <member>`, the feature by NVIDIA's constant (`kFeatureDLSS_G`;
|
||||
`feature 4242` for an id this build has no name for), a version as `major.minor.build`, the requirement flags by
|
||||
their enumerators. A version of all zeros is the vendor's "none" and has no row — a feature with no NGX model, a
|
||||
requirement nobody stated — except `versionSL`; a count of 0 is a count. One bit of the mask covers both
|
||||
questions, so which was answered is told by the slots (`InGameAdvancedSampler.FeatureCall`), and
|
||||
`AdvancedSources.StreamlineFeatureVersion` and `.StreamlineFeatureRequirements` say for each: `Read`;
|
||||
`NeverCalled` — hooked, and the game did not ask after that, ~~**the usual case, because a game asks while it
|
||||
starts**~~ *(not the usual case: measured 2026-11-12, six of six Streamline sessions on five games read both, bar
|
||||
Cyberpunk 2077's version question)*, and the page words it as "did not ask again"; or `NotHooked`. The slots are not emptied by a new request, so a second
|
||||
session of a game that kept running stores what the first one read. `sl.init.preferences` stays unread (D112).
|
||||
**The fourth step, 2026-11-12 (0.1.0-beta.45).** Two more entries have reach `Game`, from six calls
|
||||
(`17_HOOK_ENGINE` §Hook inventory): `sl.feature.support` — `<feature> · slIsFeatureSupported`, the `sl::Result`
|
||||
by NVIDIA's enumerator (`eOk`, `eErrorFeatureNotSupported`; `result 40` for a number past the forty this build
|
||||
names, `result 255` for a code a byte could not carry), and `<feature> · slIsFeatureLoaded`, `on` or `off` — and
|
||||
`sl.feature.lifecycle` — `<feature> · slSetFeatureLoaded` (`on`, `off`, `on_and_off`: what the game asked for
|
||||
during the session, not the state it left), `· slAllocateResources` and `· slFreeResources` (a count; `≥ 15`
|
||||
where the four bits stopped), and a row `slShutdown` with the number of shutdowns. All of it is word 1 of the
|
||||
twelve feature slots and one word that was reserved (layout 5 and schema 23 as they were). A feature with nothing
|
||||
to say has no row and a fact with no row is not stored. `AdvancedSources` has one member a call
|
||||
(`StreamlineFeatureSupported`, `…Loaded`, `StreamlineSetFeatureLoaded`, `StreamlineAllocateResources`,
|
||||
`StreamlineFreeResources`, `StreamlineShutdown`), `Read` / `NeverCalled` / `NotHooked` as before and null in a
|
||||
row written before; the page says the six in one sentence. The switching and the counts are a session's — the
|
||||
capture side clears them at a new request — so, unlike the answers, a second session does not inherit them.
|
||||
`sl.init.preferences` now has reach `BeforeAttach` (D129): not a later release, never.
|
||||
**Measured 2026-11-13** (six Streamline sessions on five games; `HANDOFF` item 43): `slIsFeatureSupported` was
|
||||
read in every one — refusals among the answers, `eErrorFeatureMissing` for ImGUI, NIS and DeepDVC —
|
||||
`slIsFeatureLoaded` in three games, `slSetFeatureLoaded` in two (every feature off and on), `slFreeResources`
|
||||
and `slShutdown` once in one game each, and `slAllocateResources` in none.
|
||||
- **D113 — three releases, because a new patch site cannot be proven in CI.** A crash in a game under the user-mode
|
||||
anti-cheat exception's trial ends that exception for good (D38), and every release already means restarting the
|
||||
game. **beta.40**: more fields of calls *already* hooked — `sl::DLSSOptions` where the game chains it into
|
||||
`slEvaluateFeature`, the FSR upscale dispatch, the FSR memory query — shared-memory layout 5, the Agent and the
|
||||
page; **no new patch site**. **~~beta.41~~ beta.42**: `slSetConstants` and `ffxConfigure`. **~~beta.42~~
|
||||
beta.43**: `slGetFeatureVersion` and `slGetFeatureRequirements` — the owner's words: a release of their own, still
|
||||
hooked. Each starts when the owner says the one before passed its owner-only item.
|
||||
- **D122 — the second step is two releases** (owner decision 2026-11-12, after the owner's sessions on beta.40
|
||||
and beta.41 and a review of the draft against the code). **0.1.0-beta.42 adds no patch site**: the session's
|
||||
upscaler label (D120, `03_METRICS` §Upscaling), a patch registry that refuses what it cannot register, a native
|
||||
log that survives the game's exit and says which descriptor types each ffx module saw — because Cyberpunk 2077,
|
||||
set to FSR upscaling, was named "unknown" and nothing in the field could say why (D121) — and FSR's infinite depth
|
||||
plane (D119). **0.1.0-beta.43 is `slSetConstants` and `ffxConfigure`**, begun only when that log was read. The
|
||||
third step (`slGetFeatureVersion`, `slGetFeatureRequirements`) is beta.44, train C beta.45, train D beta.46.
|
||||
- **D118 — 0.1.0-beta.41 is a fix release, and the train's numbers move by one** (owner decision 2026-11-12). The
|
||||
owner's first evening with beta.40 showed the sensor library being closed under its other users (the paragraph on
|
||||
`LhmLibrary` below; `20_OPEN_QUESTIONS` §M13); told that the fix would take the number D113 had given the train's
|
||||
second release, the owner chose to release it at once. So: second release beta.42, third beta.43, train C
|
||||
beta.44, train D beta.45. Text written before that day says beta.41 and beta.42 for the second and third — in
|
||||
the released changelogs and the moved HANDOFF sections, which are not edited, and in the comments of `fl_shm.h`
|
||||
and `ShmLayout.cs`, which the release that fills each member rewrites (they were left so that the code loaded
|
||||
into a game stayed 0.1.0-beta.40's, line for line, in a release that fixes something else).
|
||||
- **D112 — `slInit` is not hooked in train B.** A game calls it before FrameLedger attaches, so its preferences
|
||||
would almost never be seen. If it is ever hooked: `applicationId`, `projectId` and the paths are never read.
|
||||
- **D129 — `slInit` is not hooked at all** (owner decision 2026-11-12, asked to reopen D112 and shown what was
|
||||
found). No mode of the shipped product is in the game in time: *Play ▸ Start directly* does not create the game
|
||||
suspended — it waits for the presentation runtime, runs the guard, then injects; nothing is ever patched on a
|
||||
game's thread, so a hook lands some hundred milliseconds after its module appears (`17_HOOK_ENGINE`, the loader
|
||||
lock); and a hook that exists only for Advanced metrics waits for the Agent's request, which comes after the
|
||||
attach. A hook on it would be a patch that reads nothing. `sl.init.preferences` says so in the catalog. Most of
|
||||
what it would have told is read another way: which features are loaded (`slIsFeatureLoaded`), and whether a
|
||||
newer plugin than the game's own is in use (the versions of 0.1.0-beta.44).
|
||||
- **D130 — six more core calls in one release, 0.1.0-beta.45**: `slIsFeatureSupported`, `slIsFeatureLoaded`,
|
||||
`slSetFeatureLoaded`, `slAllocateResources`, `slFreeResources`, `slShutdown`. Trains C and D come after it; train
|
||||
C's spike is written beside it, as a document.
|
||||
- **D131 — the adapter a game asks `slIsFeatureSupported` about is never read**: `sl::AdapterInfo` holds its LUID
|
||||
or a Vulkan physical device. The feature's id and the result are all that is kept, and a build check refuses the
|
||||
names of the struct's members in the code loaded into a game.
|
||||
- **D114 — the field of view is a session's range**, lowest to highest, never a series: a series would say when the
|
||||
player aimed.
|
||||
- **D115 — a tail member is read only where it is proven to be there** (`17_HOOK_ENGINE` §Which struct version
|
||||
carries which field): the table from the upstream tags, not the one header in the tree.
|
||||
- **D116 — "never the camera" is a build check**, as "never a setter" is (D108): `tools/overlay-fields-check.ps1` —
|
||||
every read of a vendor struct in one header, each allowed member named and used, the camera's names refused
|
||||
anywhere in the Overlay and the Vulkan layer, no copy of `sl::Constants` by value. *(Built 2026-11-12:
|
||||
twenty-eight members on `tools/overlay-allowed-fields.txt`; `12_BUILD` gate 14f. Fifty-six since 0.1.0-beta.44,
|
||||
with the two answers about a feature.)*
|
||||
- **What will read N/A, and says why.** Many titles set their DLSS options through `slDLSSSetOptions`, which is not
|
||||
an export (train D), so `sl.dlss.*` is filled only for a title that passes its options with the evaluate call.
|
||||
`slGetFeatureVersion` and `slGetFeatureRequirements` are calls a game makes while starting.
|
||||
- **Privacy Policy 2.19** at beta.45 (approved with that release's plan): 2.18 named two of Streamline's answers
|
||||
about a feature; whether it is supported and loaded, the game switching it, allocating and freeing its resources
|
||||
and shutting Streamline down are in neither list, so they are named — with two more things never read: what
|
||||
identifies the graphics card a game hands over with its question, and the content of a graphics resource.
|
||||
- **Privacy Policy 2.18** at beta.44 (approved with that release's plan): 2.17 named two further calls and what
|
||||
they give; Streamline's answers about a feature are in neither list, so they are named, with what of the answer
|
||||
is never read — the lists it points to.
|
||||
- **Privacy Policy 2.17** at beta.43 (approved with that release's plan): 2.16 listed DLSS's and FSR's upscaling
|
||||
parameters by name, and Streamline's per-frame constants and the frame-generation configuration are in neither
|
||||
list, so they are named — and §4 says the two calls are intercepted only once a session with the option on has
|
||||
started in the game.
|
||||
- **Privacy Policy 2.16** at beta.40, once for the three releases: with Advanced metrics on, for a game FrameLedger
|
||||
injects into, the parameters the game gives its upscaler and frame generation through the intercepted calls are
|
||||
*stored* — sizes, presets, exposure, sharpening, the jitter's, the depth's and the field of view's ranges, flags,
|
||||
versions — and never the camera's position, axes or matrices.
|
||||
|
||||
### Left out, by name
|
||||
|
||||
Present in the vendored `nvapi.h`, readable from the Agent, and not in the inventory — each is either not a
|
||||
measurement of how a game runs or exists on professional cards only: ECC status and errors, NVLINK, illumination
|
||||
(the card's lighting zones), licensable features, virtualization and GSP information, Quadro status, VR-ready data,
|
||||
the IRQ and bus slot numbers, logical GPUs and SLI state, HDCP support, scan-out configuration, the colour and
|
||||
info-frame controls. `NvAPI_DISP_GetTiming` calculates a timing from an input and reads nothing.
|
||||
`NV_GET_ADAPTIVE_SYNC_DATA`'s last-flip count and timestamp mean nothing sampled once a second.
|
||||
`NvAPI_GPU_ClientRegisterForUtilizationSampleUpdates` registers a callback, which is not a read.
|
||||
|
||||
### The inventory
|
||||
|
||||
One row per entry of `AdvancedMetricCatalog`, in its order; `AdvancedMetricCatalogTests` fails when this table and
|
||||
the catalog differ in either direction. **Reach** is where a value can be read from, or why it is not read: `Agent`
|
||||
(the Agent's own process), `AgentElevated` (the same, as administrator with PawnIO), `Game` (read inside a game
|
||||
FrameLedger measures, from the arguments of a call the Overlay hooks, while the session records Advanced metrics —
|
||||
since 0.1.0-beta.40), `HookedCall` (an argument of a call the Overlay already hooks, not read yet), `NewHook` (a hook
|
||||
that is not built — Train B; no entry carries it since 0.1.0-beta.45), `BeforeAttach` (a call the game makes once,
|
||||
before FrameLedger is inside it, so no hook could read it — D129), `Spike` (Trains C and D), `Refused`, `Deferred`, `Identifier` (D104), `PlayerState`
|
||||
(rule 4), `Licence`, `NotInHeaders`. ~~Only the first two are read by a build of Train A.~~ The first three are read
|
||||
(`AdvancedMetric.IsRead`).
|
||||
|
||||
**NVAPI, the graphics card: facts**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `nvapi.gpu.type` | Integrated or discrete graphics | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.gpu.system_type` | Laptop or desktop, as the driver sees the PC | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.gpu.external` | The card is an external one | MachineFact | Nvapi | Agent | Flag |
|
||||
| `nvapi.gpu.bus_type` | The bus the card sits on | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.gpu.pci_ids` | PCI device, subsystem and revision ids - the model, not the unit | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.gpu.vbios_version` | Video BIOS version | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.gpu.architecture` | Chip architecture, implementation and revision | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.gpu.core_count` | Graphics cores | MachineFact | Nvapi | Agent | Count |
|
||||
| `nvapi.gpu.rt_cores` | Ray-tracing cores | MachineFact | Nvapi | Agent | Count |
|
||||
| `nvapi.gpu.tensor_cores` | Tensor cores | MachineFact | Nvapi | Agent | Count |
|
||||
| `nvapi.gpu.ram_bus_width` | Width of the card's memory bus | MachineFact | Nvapi | Agent | Bits |
|
||||
| `nvapi.gpu.clock_base_core` | Base core clock | MachineFact | Nvapi | Agent | Megahertz |
|
||||
| `nvapi.gpu.clock_base_memory` | Base memory clock | MachineFact | Nvapi | Agent | Megahertz |
|
||||
| `nvapi.gpu.clock_boost_core` | Boost core clock | MachineFact | Nvapi | Agent | Megahertz |
|
||||
| `nvapi.gpu.clock_boost_memory` | Boost memory clock | MachineFact | Nvapi | Agent | Megahertz |
|
||||
| `nvapi.gpu.temp_default_max` | The core sensor's default maximum temperature | MachineFact | Nvapi | Agent | Celsius |
|
||||
|
||||
**NVAPI, the card's memory**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `nvapi.vram.dedicated` | Dedicated video memory on the card | MachineFact | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.dedicated_available` | Dedicated video memory available for surfaces | MachineFact | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.system` | System memory the driver reserved at load | MachineFact | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.shared` | Shared system memory the driver may commit | MachineFact | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.framebuffer_physical` | Physical frame buffer size | MachineFact | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.framebuffer_virtual` | Virtual frame buffer size | MachineFact | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.available` | Dedicated video memory available now, all programs | Series | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.in_use` | Dedicated video memory in use now, all programs: available for surfaces less available now | Series | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.evictions_size` | Memory released by evictions since the driver loaded | Series | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.eviction_count` | Evictions from dedicated video memory since the driver loaded | Series | Nvapi | Agent | Count |
|
||||
| `nvapi.vram.promotions_size` | Memory moved in by promotions since the driver loaded | Series | Nvapi | Agent | Mebibytes |
|
||||
| `nvapi.vram.promotion_count` | Promotions into dedicated video memory since the driver loaded | Series | Nvapi | Agent | Count |
|
||||
|
||||
**NVAPI, the card over time**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `nvapi.load.framebuffer` | Frame-buffer (memory controller) utilisation | Series | Nvapi | Agent | Percent |
|
||||
| `nvapi.load.video` | Video-engine utilisation | Series | Nvapi | Agent | Percent |
|
||||
| `nvapi.load.bus` | Bus-interface utilisation | Series | Nvapi | Agent | Percent |
|
||||
| `nvapi.clock.video` | Video clock | Series | Nvapi | Agent | Megahertz |
|
||||
| `nvapi.pstate` | The card's current performance state (P-state id) | Series | Nvapi | Agent | Count |
|
||||
| `nvapi.temp.board` | Board ambient temperature, where the card has the sensor | Series | Nvapi | Agent | Celsius |
|
||||
| `nvapi.temp.power_supply` | The card's power-supply temperature, where it has the sensor | Series | Nvapi | Agent | Celsius |
|
||||
| `nvapi.limit.ac_battery` | Held back by a switch to battery on the tick: 100 or 0 | Series | Nvapi | Agent | Percent |
|
||||
| `nvapi.limit.api` | Held back at a program's request on the tick: 100 or 0 | Series | Nvapi | Agent | Percent |
|
||||
| `nvapi.limit.insufficient_power` | Held back by a missing power connector on the tick: 100 or 0 | Series | Nvapi | Agent | Percent |
|
||||
| `nvapi.encoder.sessions` | Active hardware-encoder sessions, all programs | Series | Nvapi | Agent | Count |
|
||||
| `nvapi.encoder.fps` | Average encoding rate of the active sessions | Series | Nvapi | Agent | FramesPerSecond |
|
||||
| `nvapi.encoder.latency` | Average encoding latency | Series | Nvapi | Agent | Microseconds |
|
||||
|
||||
**NVAPI, the driver**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `nvapi.driver.package` | Game Ready, Studio or an RTX enterprise branch | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.driver.dch` | The driver is a DCH package | MachineFact | Nvapi | Agent | Flag |
|
||||
| `nvapi.driver.base_branch` | The driver's base branch | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.driver.interface_version` | NVAPI's own interface version | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.driver.chipset` | Chipset vendor and name, as the driver reports them | MachineFact | Nvapi | Agent | Text |
|
||||
| `nvapi.driver.global_profile` | Every setting of the driver's global profile, read-only | MachineFact | Nvapi | Agent | Table |
|
||||
| `nvapi.session.driver_profile` | The settings the driver's profile for this game sets itself, read-only | SessionFact | Nvapi | Agent | Table |
|
||||
|
||||
**NVAPI, displays**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `nvapi.display.hdr_formats` | HDR formats a display accepts: HDR10, HDR10+, HDR10+ Gaming, Dolby Vision, EDR | MachineFact, one per device | Nvapi | Agent | Text |
|
||||
| `nvapi.display.luminance_max` | A display's maximum luminance for HDR content | MachineFact, one per device | Nvapi | Agent | Nits |
|
||||
| `nvapi.display.luminance_min` | Its minimum luminance | MachineFact, one per device | Nvapi | Agent | Nits |
|
||||
| `nvapi.display.luminance_max_frame_average` | Its maximum frame-average light level | MachineFact, one per device | Nvapi | Agent | Nits |
|
||||
| `nvapi.display.vrr_support` | Variable refresh: supported, G-SYNC module or adaptive sync, ULMB, usable at the current mode | MachineFact, one per device | Nvapi | Agent | Text |
|
||||
| `nvapi.display.adaptive_sync_off` | Adaptive sync is switched off on the display | MachineFact, one per device | Nvapi | Agent | Flag |
|
||||
| `nvapi.display.max_frame_interval` | The longest frame interval adaptive sync is set to hold | MachineFact, one per device | Nvapi | Agent | Microseconds |
|
||||
| `nvapi.session.vrr_enabled` | Variable refresh was active on the game's display | SessionFact | Nvapi | Agent | Flag |
|
||||
| `nvapi.session.vrr_requested` | Variable refresh was requested for it | SessionFact | Nvapi | Agent | Flag |
|
||||
| `nvapi.session.vrr_possible` | Variable refresh was possible on it | SessionFact | Nvapi | Agent | Flag |
|
||||
| `nvapi.session.vrr_display_mode` | The display itself was in variable-refresh mode | SessionFact | Nvapi | Agent | Flag |
|
||||
| `nvapi.session.source_colorspace` | The colour space the game presented in, as the driver reports it for the process | SessionFact | Nvapi | Agent | Text |
|
||||
|
||||
**LibreHardwareMonitor, the graphics card (every vendor, unelevated)**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `lhm.gpu.temperature` | Every temperature sensor of the card | Series, one per device | Lhm | Agent | Celsius |
|
||||
| `lhm.gpu.load` | Every load of the card: its engines, its bus, its memory controller | Series, one per device | Lhm | Agent | Percent |
|
||||
| `lhm.gpu.memory` | The card's memory counters: total, free, used, Direct3D dedicated and shared | Series, one per device | Lhm | Agent | Mebibytes |
|
||||
| `lhm.gpu.clock` | Every clock of the card | Series, one per device | Lhm | Agent | Megahertz |
|
||||
| `lhm.gpu.power` | Every power reading of the card | Series, one per device | Lhm | Agent | Watts |
|
||||
| `lhm.gpu.fan` | Every fan of the card | Series, one per device | Lhm | Agent | Rpm |
|
||||
| `lhm.gpu.fan_control` | Each fan's duty | Series, one per device | Lhm | Agent | Percent |
|
||||
| `lhm.gpu.voltage` | Every voltage of the card | Series, one per device | Lhm | Agent | Volts |
|
||||
| `lhm.gpu.current` | Every current of the card | Series, one per device | Lhm | Agent | Amperes |
|
||||
| `lhm.gpu.throughput` | PCI Express traffic to and from the card | Series, one per device | Lhm | Agent | BytesPerSecond |
|
||||
|
||||
**LibreHardwareMonitor through PawnIO (the Agent as administrator, D103)**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `lhm.cpu.temperature` | Processor temperatures: the package and each core | Series, one per device | Lhm | AgentElevated | Celsius |
|
||||
| `lhm.cpu.load` | Processor load: the total and each core | Series, one per device | Lhm | AgentElevated | Percent |
|
||||
| `lhm.cpu.clock` | Each core's clock, and the bus clock | Series, one per device | Lhm | AgentElevated | Megahertz |
|
||||
| `lhm.cpu.power` | Processor power: the package, the cores | Series, one per device | Lhm | AgentElevated | Watts |
|
||||
| `lhm.cpu.voltage` | Processor voltages | Series, one per device | Lhm | AgentElevated | Volts |
|
||||
| `lhm.board.model` | The motherboard's maker and model | MachineFact | Lhm | AgentElevated | Text |
|
||||
| `lhm.board.sensor_chip` | The board's sensor chip | MachineFact | Lhm | AgentElevated | Text |
|
||||
| `lhm.board.temperature` | The board's temperature sensors | Series, one per device | Lhm | AgentElevated | Celsius |
|
||||
| `lhm.board.fan` | Each fan header's speed | Series, one per device | Lhm | AgentElevated | Rpm |
|
||||
| `lhm.board.fan_control` | Each fan header's duty | Series, one per device | Lhm | AgentElevated | Percent |
|
||||
| `lhm.board.voltage` | The board's voltage rails | Series, one per device | Lhm | AgentElevated | Volts |
|
||||
| `lhm.memory.modules` | The memory modules: size, speed, maker's part name - never a serial number | MachineFact | Lhm | AgentElevated | Table |
|
||||
| `lhm.memory.load` | Memory in use: physical and virtual | Series, one per device | Lhm | AgentElevated | Percent |
|
||||
| `lhm.memory.temperature` | Each memory module's temperature, where it has a sensor | Series, one per device | Lhm | AgentElevated | Celsius |
|
||||
|
||||
**What the Agent could reach and does not**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `lhm.psu` | Power-supply sensors: reading them makes the library search every USB device | MachineFact | Lhm | Refused | Table |
|
||||
| `lhm.controller` | Fan-controller sensors: the same search of USB devices | MachineFact | Lhm | Refused | Table |
|
||||
| `lhm.battery` | Battery sensors | MachineFact | Lhm | Deferred | Table |
|
||||
| `lhm.storage.models` | The drives' model names: the library cannot list drives without touching removable ones | MachineFact | Lhm | Deferred | Table |
|
||||
| `lhm.storage.temperature` | Each drive's temperature: the same, so the storage group is not opened | Series, one per device | Lhm | Deferred | Celsius |
|
||||
| `nvapi.gpu.board_serial` | The card's board serial number | MachineFact | Nvapi | Identifier | Text |
|
||||
| `nvapi.gpu.uuid` | The card's unique id | MachineFact | Nvapi | Identifier | Text |
|
||||
| `nvapi.display.edid` | A display's EDID block, which carries its serial number | MachineFact, one per device | Nvapi | Identifier | Text |
|
||||
| `nvapi.encoder.session_processes` | Which programs are encoding | Series | Nvapi | Identifier | Table |
|
||||
| `nvapi.gpu.power` | Card power through NVAPI (LibreHardwareMonitor reads it) | Series | Nvapi | NotInHeaders | Watts |
|
||||
| `nvapi.gpu.fan_duty` | Fan duty through NVAPI (LibreHardwareMonitor reads it) | Series | Nvapi | NotInHeaders | Percent |
|
||||
| `nvapi.gpu.voltage` | Card voltage through NVAPI (LibreHardwareMonitor reads it) | Series | Nvapi | NotInHeaders | Volts |
|
||||
| `nvapi.gpu.ram_type` | The card's memory type | MachineFact | Nvapi | NotInHeaders | Text |
|
||||
|
||||
**Inside the game: calls the Overlay already hooks**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `sl.dlss.output_size` | The output size the game gave DLSS | SessionFact | Streamline | Game | Text |
|
||||
| `sl.dlss.presets` | The DLSS model preset per quality mode | SessionFact | Streamline | Game | Table |
|
||||
| `sl.dlss.hdr_input` | The game told DLSS its colour buffers are HDR | SessionFact | Streamline | Game | Flag |
|
||||
| `sl.dlss.auto_exposure` | DLSS auto-exposure | SessionFact | Streamline | Game | Flag |
|
||||
| `sl.dlss.alpha_upscaling` | DLSS upscales the alpha channel | SessionFact | Streamline | Game | Flag |
|
||||
| `sl.dlss.exposure` | Pre-exposure and exposure scale given to DLSS | SessionFact | Streamline | Game | Table |
|
||||
| `ffx.upscale.sharpening` | FSR sharpening: on or off, and its strength | SessionFact | FidelityFx | Game | Table |
|
||||
| `ffx.upscale.jitter` | The largest jitter offset the game gave FSR | SessionFact | FidelityFx | Game | Table |
|
||||
| `ffx.upscale.exposure` | Pre-exposure given to FSR | SessionFact | FidelityFx | Game | Text |
|
||||
| `ffx.upscale.depth` | Near and far planes and the range of the field of view given to FSR | SessionFact | FidelityFx | Game | Table |
|
||||
| `ffx.upscale.flags` | The flags of the game's FSR dispatch | SessionFact | FidelityFx | Game | Text |
|
||||
| `ffx.upscale.frame_time_delta` | The frame time the game reported to FSR | Series | FidelityFx | Game | Milliseconds |
|
||||
| `ffx.memory_usage` | FSR's own video memory, when the game asks it | Series | FidelityFx | Game | Mebibytes |
|
||||
|
||||
**Inside the game: hooks that are not built**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `sl.constants.jitter` | The jitter offsets the game gave Streamline | SessionFact | Streamline | Game | Table |
|
||||
| `sl.constants.motion_vectors` | Motion-vector scale, and whether they are 3D, dilated, jittered | SessionFact | Streamline | Game | Table |
|
||||
| `sl.constants.depth` | Near and far planes, and whether depth is inverted | SessionFact | Streamline | Game | Table |
|
||||
| `sl.constants.projection` | Field of view, aspect ratio, orthographic or not | SessionFact | Streamline | Game | Table |
|
||||
| `sl.constants.resets` | How often the game reset the upscaler's history | SessionFact | Streamline | Game | Count |
|
||||
| `ffx.framegen.config` | The game's FSR frame-generation configuration | SessionFact | FidelityFx | Game | Table |
|
||||
| `sl.feature.versions` | Each Streamline feature's version and its NGX model version | SessionFact | Streamline | Game | Table |
|
||||
| `sl.feature.requirements` | What each Streamline feature requires: operating system, driver, buffers | SessionFact | Streamline | Game | Table |
|
||||
| `sl.feature.support` | Whether Streamline says each feature is supported, and loaded | SessionFact | Streamline | Game | Table |
|
||||
| `sl.feature.lifecycle` | Each feature switched on or off, its resources allocated and freed, Streamline shut down | SessionFact | Streamline | Game | Table |
|
||||
| `sl.init.preferences` | The preferences the game started Streamline with | SessionFact | Streamline | BeforeAttach | Text |
|
||||
| `sl.constants.camera` | Camera position, axes and matrices | SessionFact | Streamline | PlayerState | Text |
|
||||
|
||||
**Inside the game: routes a spike decides**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `nvapi.reflex.mode` | Reflex: low-latency mode, boost, the frame-rate limit | SessionFact | Nvapi | Spike | Text |
|
||||
| `nvapi.reflex.sleep_status` | What the driver's low-latency state is | SessionFact | Nvapi | Spike | Text |
|
||||
| `nvapi.reflex.frame_report` | Latency per frame: simulation, render submit, present, driver, OS queue, GPU render | Series, one per device | Nvapi | Spike | Microseconds |
|
||||
| `sl.dlss.optimal_settings` | The render size and sharpness DLSS recommends | SessionFact | Streamline | Spike | Text |
|
||||
| `sl.dlss.vram_estimate` | DLSS's own estimate of its video memory | Series | Streamline | Spike | Mebibytes |
|
||||
| `sl.dlssg.options` | DLSS frame generation: mode, frames to generate | SessionFact | Streamline | Spike | Text |
|
||||
| `sl.dlssg.state` | DLSS frame generation: status, the most frames it can generate | SessionFact | Streamline | Spike | Text |
|
||||
| `sl.dlssg.frames_presented` | Frames DLSS frame generation presented, by its own count | Series | Streamline | Spike | Count |
|
||||
| `sl.dlssg.vram_estimate` | DLSS frame generation's estimate of its video memory | Series | Streamline | Spike | Mebibytes |
|
||||
| `sl.dlssd.options` | Ray reconstruction's options | SessionFact | Streamline | Spike | Text |
|
||||
| `sl.nis.options` | NVIDIA Image Scaling's options | SessionFact | Streamline | Spike | Text |
|
||||
| `sl.deepdvc.options` | RTX Dynamic Vibrance's options | SessionFact | Streamline | Spike | Text |
|
||||
| `sl.reflex.state` | Reflex through Streamline: availability and its frame reports | SessionFact | Streamline | Spike | Table |
|
||||
| `sl.pcl.markers` | PC-latency markers the game sets | Series | Streamline | Spike | Count |
|
||||
|
||||
**Closed by a licence**
|
||||
|
||||
| Id | What it is | Scope | Source | Reach | Unit |
|
||||
|---|---|---|---|---|---|
|
||||
| `ngx.parameters` | NGX parameters: the quality value, the DLSS hints | SessionFact | Ngx | Licence | Table |
|
||||
| `xess.options` | XeSS's options | SessionFact | Xess | Licence | Table |
|
||||
| `sl.nvperf` | Streamline's performance counters (NSight Perf SDK licence) | Series | Streamline | Licence | Table |
|
||||
+284
-34
@@ -22,7 +22,7 @@ These are permanently out of scope. A PR implementing any of them is rejected re
|
||||
- Reading or writing game memory outside the arguments of APIs we hooked
|
||||
- Kernel drivers of our own
|
||||
|
||||
The DLL ships with its real filename, a populated VERSIONINFO block (`CompanyName`, `ProductName=FrameLedger`, version), and named kernel objects that clearly say `FrameLedger`. Being identifiable is a feature.
|
||||
The DLL ships with its real filename, a populated VERSIONINFO block (`CompanyName`, `ProductName=FrameLedger`, version), and named kernel objects that clearly say `FrameLedger`. Being identifiable is a feature. Since beta.14 (D50) the Agent — the process that injects — and the App say the same about themselves: `FrameLedger` as company and product, *FrameLedger Agent* as the Agent's description, the native binaries' copyright line (`12_BUILD` §Version, *Identity*; `tools/versioninfo-check.ps1` reads both kinds).
|
||||
|
||||
## The anti-cheat guard (hard gate)
|
||||
|
||||
@@ -51,6 +51,39 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> handle rights above are confirmed sufficient for every target this call can
|
||||
> legitimately reach.
|
||||
>
|
||||
> **Amended 2026-10-05 (owner decision D48, beta.14): one re-read, never a pass.** A member of the scan set that
|
||||
> is still being created answers `ERROR_PARTIAL_COPY` (its loader has not built a module list), and one that exited
|
||||
> between the snapshot and the open answers `ERROR_INVALID_PARAMETER`. Both refused the whole session — and at the
|
||||
> 30 s re-scan an engine's crash reporter starting as its game died, or any helper started a moment before the scan,
|
||||
> turned an ordinary exit into a "safety" unhook, which ends a user-mode exception's trial for good. Such a member
|
||||
> (`Collected::kRetry`, `fl_guard.h`) is now read once more: the pass finishes (a finding in any member still refuses
|
||||
> at once), waits `kScanRetryPauseMs` (250 ms), takes a **fresh** scan set and scans it whole. A member still unreadable
|
||||
> then refuses `kProcessUnreadable`, as before; one that has gone is not in the new set; a target that has gone leaves
|
||||
> no set, which refuses `kProcessTreeUnavailable`. **`ERROR_ACCESS_DENIED` — a protected process — is never retried**,
|
||||
> and no other answer of any source is *(one more since D123, below)*. The sentence above stands: every failure still means REFUSE; what changed is
|
||||
> how many times "still loading" is asked before it counts as one. ctest `fl_guard` `[D48]` holds both directions,
|
||||
> against fakes and against the real source (a process created suspended, a pid with no process).
|
||||
>
|
||||
> **Amended 2026-11-12 (owner decision D123): a module list that changed while it was read is read again, at most
|
||||
> three times — never a pass.** The module check lists a process's modules and then asks each one's name. A game at
|
||||
> its launch loads and unloads modules for seconds, and a module that was in the list and could not be named a
|
||||
> moment later made the whole answer "incomplete": a refusal before injection, or — 0.5 s after it, at the first
|
||||
> supervision scan — a safety unhook with no frame recorded, the game then running on unrecorded. **Five such ends
|
||||
> in one PC's Agent logs in a week** (Phantom Blade Zero three times on 2026-11-05, Crown & Coin on 11-10,
|
||||
> Cyberpunk 2077 on 11-12), and twice in this repository's own gate. Asked with that, the owner chose: read it
|
||||
> again. Such a list is now `Collected::kUnsettled`; the pass finishes — **a blocklisted module among those that
|
||||
> were read still refuses at once** — waits `kScanRetryPauseMs`, takes a fresh scan set and reads it whole, up to
|
||||
> `kMaxUnsettledRereads` (3) times: four reads and 750 ms of pauses at most. A list still unsettled on the last
|
||||
> read refuses `kModuleScanFailed` ("a module list kept changing while it was read"). **What did not change:** a
|
||||
> list too long for the guard's buffer is still `kIncomplete` and refuses at once (a second read would be as
|
||||
> long); a protected process still refuses at once; D48's re-read is still one for the whole check; every read is
|
||||
> of the whole scan set, and the read that allows is one in which every member was read whole and none held a
|
||||
> finding. A failure to read is still never a pass — what changed is how many times a list that is moving is
|
||||
> asked before it counts as unreadable. The launch poll's presentation-runtime probe treats an unsettled list as
|
||||
> "ask again" rather than deciding on half of one. ctest `fl_guard` `[D123]`: against fakes, every direction
|
||||
> above; against the real source, a process that loads and frees a module in a loop — read some 3,600 times in
|
||||
> three seconds, about one read in four is unsettled and none is anything else.
|
||||
>
|
||||
> **Launch mode (2026-09-06, P1 item 2) does not weaken this.** `FlGuardedInjectWhenReady` polls
|
||||
> the same enumeration to learn *when* the launched target has mapped a presentation runtime, and a
|
||||
> failing enumeration there means "not yet" — the poll continues. That is not a pass: the poll
|
||||
@@ -91,6 +124,23 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> inspected (`ERROR_ACCESS_DENIED`) refuses too — there is no "scanned what we
|
||||
> could" state.
|
||||
>
|
||||
> **Amended 2026-10-06 (owner decision D51, beta.15): a parent link is followed only while creation times allow it.**
|
||||
> The set is walked over one process snapshot, which links a process to its parent by pid alone, and Windows reuses
|
||||
> pids. A launcher that exits after starting its game leaves the game naming a pid that may now belong to anything:
|
||||
> until beta.15 the walk scanned whatever held it — a protected process refused the session as unreadable, a
|
||||
> blocklisted one turned the game's hooking off for good — and a cycle of reused pids sent the same processes round
|
||||
> again. A parent/child link is now cut **only when it is proven wrong**: both creation times read (`GetProcessTimes`,
|
||||
> under the module scan's own read-only right) and the child created **before** the process whose pid it names as its
|
||||
> parent, which no real child can be. A cut ancestor link ends the ancestor walk there; a cut child is not walked, nor
|
||||
> is anything below it. A time that cannot be read keeps the link, equal times keep it, and each pid is walked and
|
||||
> scanned once (`WalkScanSet`, `fl_guard_scanset.cpp`). Nothing else about the set moved: the launcher boundary, the
|
||||
> depth (16 ancestors), the frontier (512 — one more refuses) and "a member that cannot be read refuses". **The
|
||||
> residual:** creation times are wall-clock, so a clock set *backwards* between a parent's start and its child's makes a
|
||||
> real link look wrong and drops that branch from the module check; the install-folder scan and the machine-wide driver
|
||||
> and service checks do not depend on the tree. ctest `fl_guard` `[D51]` holds the walk against fixtures (a reused
|
||||
> parent, an older "child", unread times, equal times, cycles, the limits) and the real source against a child this
|
||||
> process starts.
|
||||
>
|
||||
> **One reviewed exception, decided 2026-08-03 and implemented 2026-08-04
|
||||
> (§S18), then re-keyed the same day (§S22(b)).** A module that is FrameLedger's
|
||||
> own does not trip the *fuzzy* fragment tier. The exact blocklist still applies
|
||||
@@ -217,8 +267,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.
|
||||
@@ -235,12 +287,24 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> be read (a manifest that will not open, more than 4096 of them, a listing error) refuses as `PreScanFailed`. With
|
||||
> nothing listed, nothing is read. Epic has no reader: an Epic install carries no identity to this check.
|
||||
>
|
||||
> **What is listed, and why a title list at all:** 30 Steam app ids and 33 executable names across nine families —
|
||||
> **What is listed, and why a title list at all:** ~~33~~ 34 Steam app ids and 33 executable names across ten families —
|
||||
> Valve VAC (CS2, Dota 2, TF2, Deadlock and Valve's older VAC titles), Riot Vanguard, Roblox Hyperion, Blizzard's
|
||||
> online titles ("Blizzard Warden"), Call of Duty (Activision Ricochet), NetEase (Marvel Rivals, NARAKA, FragPunk,
|
||||
> Once Human), ACE (Delta Force, Arena Breakout: Infinite), HoYoverse and EA (Battlefield 2042/6, EA SPORTS FC 25/26).
|
||||
> Once Human), ACE (Delta Force, Arena Breakout: Infinite), HoYoverse and EA (Battlefield 2042/6, EA SPORTS FC 25/26),
|
||||
> and since 2026-10-03 (rules `2026.10.1`, owner's list) HyperTech's **CrackProof** (Umamusume: Pretty Derby
|
||||
> `3224770`, Heaven Burns Red `1973710`, Madoka Magica Magia Exedra `2987800` — Steam ids only: no executable name
|
||||
> was verified, and a guessed one is a false refusal waiting for an unrelated game). **Since 2026-10-13 (rules
|
||||
> `2026.10.4`, owner decision D58) Wuthering Waves `3513350`, under ACE**, by its Steam id alone (its executable,
|
||||
> `Client-Win64-Shipping.exe`, is a name Unreal games share): its ACE sits beside the executable, where check 4 did
|
||||
> not reach until the same rules (item 4 below), and a session was hooked for 37 s on 2026-10-12 before the 30 s
|
||||
> re-scan met the driver — a machine-wide finding, which turned nothing off (`spike-notes.md` §19).
|
||||
> These are the titles whose anti-cheat leaves nothing of the game's own for checks 1, 2 and 4 to find — VAC runs
|
||||
> inside Steam, Blizzard's scanner is built into the game — or whose kernel driver loads only after the checks run.
|
||||
> CrackProof is the second kind: a Proton log of Umamusume shows its driver loaded from `C:\Windows\System32` under a
|
||||
> numbered name (`usrdrv017864.sys`, ValveSoftware/Proton#8853), outside the game's folder, so the `.sys` rule cannot
|
||||
> see it before the first run and no driver token could name it. Each of the three store pages states *"Uses Kernel
|
||||
> Level Anti-Cheat"* and CrackProof (read 2026-10-03); ANOTHER EDEN, which a community list also names, was left out
|
||||
> because its store page says nothing of the kind.
|
||||
> Every app id was checked against its Steam store page; Call of Duty's changed when Activision split CoD HQ, so only
|
||||
> ids with a live store page are listed. The per-title lists are **floored** like the families: a rules file can
|
||||
> add a title and cannot take one off. `rules-validate` refuses a name engines and tools share (`Game.exe`,
|
||||
@@ -297,7 +361,8 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> `ResolveInstallRoot`, plus check 3 on the executable's name and the install's store identity.
|
||||
|
||||
> **Implemented, and stated narrowly.** `fl_prescan.cpp` walks the target's
|
||||
> own directory (derived from its pid, never from a caller-supplied path) to
|
||||
> install root and, since 2026-10-13, its executable's own folder (both derived from its pid, never from a
|
||||
> caller-supplied path — "Which directory" below) to
|
||||
> **depth 3** — raised from 2 on 2026-08-04 (§S22, `spike-notes.md` §13), because a
|
||||
> title shipping its own kernel driver two levels below the install root was
|
||||
> invisible from where the scan starts, so the blocklist row naming it could not
|
||||
@@ -308,7 +373,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.
|
||||
@@ -317,9 +382,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
|
||||
@@ -340,24 +407,56 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> appeal. A nested executable outside a recognised store layout is therefore
|
||||
> still scanned narrowly; that residual is stated, not closed.
|
||||
>
|
||||
> **Amended 2026-11-03 (beta.33, `spike-notes` §25): a GDK package root is a boundary too, and `GamesInstalled`
|
||||
> is one natively.** The Xbox app and the Microsoft Store install to `<games folder>\<Game>\Content\` under a
|
||||
> folder the user names, which no string can bound — so for the executable the import picks there (an Unreal
|
||||
> title's `Content\<Project>\Binaries\WinGDK\…-Shipping.exe`), check 4 walked `Binaries\WinGDK` alone, and an
|
||||
> `EasyAntiCheat\` at `Content`'s root would have read clean: the residual above, on a whole store. The package
|
||||
> marks its own root — `MicrosoftGame.config` beside `appxmanifest.xml`, both files — so **only when no string
|
||||
> boundary matched**, the nearest folder at or above the executable's that holds both is the root (at most eight
|
||||
> levels up, never a drive's root; `ResolveInstallRoot` and the managed `InstallRoot`). Not a blind walk up: a
|
||||
> marker the package writes, measured as exactly one per package at `Content`'s root on the owner's 11 titles; and
|
||||
> only ever a widening relative to the executable's folder — a Steam build carrying GDK files keeps its Steam root.
|
||||
> The native list also gains `GamesInstalled\<X>`, which the managed one had since #17 and the native one never
|
||||
> did; one case list (`tests/fixtures/install-roots/cases.txt`), read by both suites, holds the two resolvers
|
||||
> together from now on.
|
||||
>
|
||||
> **Amended 2026-10-13: the root AND the executable's folder.** The root replaced the executable's folder, and
|
||||
> that was half the answer. The walk reaches three levels below where it starts, and an Unreal executable is
|
||||
> already three below its root, so a folder **beside** the executable is four: MEASURED on Wuthering Waves, whose
|
||||
> Tencent ACE lives in `Client\Binaries\Win64\AntiCheatExpert\` (with `ACE-BASE.sys` and `ACE-CORE.sys` in it). The
|
||||
> walk from the root listed `Win64` and never opened it, so the library pre-scan read the game clean three times,
|
||||
> hooking stayed available, and the first session was hooked for 37 s until the 30 s re-scan met ACE's driver —
|
||||
> machine-wide, so nothing was turned off (`spike-notes.md` §19). Neverness To Everness keeps a second
|
||||
> `AntiCheatExpert\` beside its `HTGame.exe`, six levels down, that no walk had seen either. Check 4 now walks the
|
||||
> root and then, when the executable lives below it, the executable's own folder — same walk, same reach, its own
|
||||
> 4096-entry budget, the same matcher and the same D33 tolerance (`ScanGameFolders`). `ImageDirectory` names the
|
||||
> executable's folder and the checks resolve the root from it. Raising the reach instead was measured and rejected:
|
||||
> depth 4 still misses NTE's folder, and at depth 5 three installed titles overrun 4096 entries (Yu-Gi-Oh! Master
|
||||
> Duel: 41,251), which would refuse them. Measured across the owner's 83 Steam installs, the second walk costs at most
|
||||
> 103 entries and newly finds exactly those two folders.
|
||||
>
|
||||
> **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
|
||||
> closed by never firing, which is a silent hole.
|
||||
>
|
||||
> **Every uncertainty refuses**, with `Reason::kPreScanFailed` rather than a
|
||||
> hit: directory absent or unlistable, either bound exceeded, a name we could
|
||||
> hit: directory absent or unlistable, ~~either bound exceeded~~ the 4096-entry bound exceeded, a name we could
|
||||
> not convert, or a reparse point — which is never followed, because a
|
||||
> junction can hide an `EasyAntiCheat/` beneath it. **Unmeasured:** how often
|
||||
> junction can hide an `EasyAntiCheat/` beneath it. *(Corrected 2026-10-13: the DEPTH bound never refused. It is a
|
||||
> reach — a folder at the last level is named and not opened, and the walk still reads as complete — which is how
|
||||
> Wuthering Waves' ACE was missed; the paragraph above is what answers it.)* **Unmeasured:** how often
|
||||
> a legitimate library trips the reparse-point rule or the 4096-entry bound.
|
||||
> That needs a real game library, and it is a false-refusal path, so it is
|
||||
> recorded rather than assumed benign.
|
||||
|
||||
Any check failing ⇒ **injection is refused**. The UI shows which check fired and offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing (`04_CAPTURE` §Frame source abstraction).
|
||||
Any check failing ⇒ **injection is refused**. The UI shows which check fired and ~~offers Tier-2 (ETW) capture instead, which requires no injection — but does require an elevated Agent, so the offer must state that plainly and fall through to Tier 3 rather than appearing to succeed and recording nothing (`04_CAPTURE` §Frame source abstraction)~~ **records the session unmeasured — Tier 2: its duration, the machine's sensors and the reason — which needs no injection and no elevation; there is no ETW rung and no Tier 3 since 2026-08-28** (corrected 2026-09-27: this sentence outlived the ladder it described by a month).
|
||||
|
||||
### The payload is checked too, and for a long time it was not
|
||||
|
||||
@@ -396,6 +495,41 @@ the injection primitive, not a fifth question about the title.
|
||||
|
||||
> **There is no override.** ~~There is one, since 2026-09-21, and it is none of the things this paragraph named~~ *(one day; withdrawn 2026-09-22)*: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below — and since 2026-09-26 (D33), one narrow, evidence-bound exception for anti-cheat that is user-mode throughout, which lets a named family through while every check still runs (§The user-mode exception).
|
||||
|
||||
### The target must be able to take the Overlay — beta.33 (D78)
|
||||
|
||||
The last question before the primitive, after checks 1–4 and the payload's identity passed: **can this process take the
|
||||
Overlay at all?** The guard reads it from the target itself (`Sources::TargetIsolationFacts`, one
|
||||
`PROCESS_QUERY_LIMITED_INFORMATION` handle — measured 2026-11-03 to answer both questions, `GetProcessMitigationPolicy`
|
||||
needing no more):
|
||||
|
||||
| Read | Refusal | Why it cannot work |
|
||||
|---|---|---|
|
||||
| `TokenIsAppContainer` | `kTargetAppContainer` | a Microsoft Store app of the UWP kind: the Overlay's shared memory, its `Local\` names and the rules file live in the user's session namespace and profile, which an AppContainer cannot open. D78: GDK games are in, UWP apps are out |
|
||||
| `ProcessSignaturePolicy`: `MicrosoftSignedOnly` or `StoreSignedOnly` | `kTargetMitigation` | the Overlay is neither (CLAUDE.md rule 9: unsigned): the remote `LoadLibraryW` fails |
|
||||
| `ProcessDynamicCodePolicy`: `ProhibitDynamicCode` | `kTargetMitigation` | MinHook's trampolines are dynamic code: the Overlay would load and hook nothing |
|
||||
| `ProcessUserShadowStackPolicy`: strict mode, or `BlockNonCetBinaries` / `BlockNonCetBinariesNonEhcont` | `kTargetMitigation` | the Overlay is not marked CET-compatible: refused at load, or a violation ends the game |
|
||||
| `ProcessControlFlowGuardPolicy`: `StrictMode` | `kTargetMitigation` | `native/CMakeLists.txt` H1: measured safe with strict mode off only; a host in strict mode could still `__fastfail` on the trampolines, which no fault policy can catch (rule 5) |
|
||||
|
||||
**The policy is the signal**, and only the enforcing flags count: an `Audit*` flag refuses nothing, and
|
||||
`SetContextIpValidation` without strict mode is what every CET-compatible process carries (measured: `pwsh.exe`
|
||||
`0x105`). A policy the running Windows does not know answers `ERROR_INVALID_PARAMETER` (measured) and cannot be in
|
||||
effect. **"Could not tell" refuses** — a seam that fails, or none wired — as `kProcessUnreadable`, the module check's word
|
||||
for a process it could not read. ctest `fl_guard` `[isolation]` holds each refusal through fakes, and two of them against
|
||||
Windows itself: a child started under "no dynamic code" and "Microsoft-signed images only".
|
||||
|
||||
**Neither is a finding.** Nothing is written to the game's row and no family is named; the session is Tier 2 with the
|
||||
reason, as for a 32-bit game. **No game that measured before is refused now**: each of these ended as a failed injection,
|
||||
an Overlay that installed no hooks, or a risk of ending the game. It is asked once, before the injection — never by the 30 s
|
||||
re-scan, which runs inside a process the Overlay is already in — and, like the payload check, it is not numbered as a
|
||||
check: it is a precondition of the primitive, not a question about the title.
|
||||
|
||||
**A GDK game's tree, measured (`spike-notes` §25, six titles activated through their packages):** the chain is
|
||||
`GameLaunchHelper.exe` → `gamingservicesui.exe` → `XboxPcTray.exe` → the launch executable (→ an Unreal title's shipping
|
||||
executable), `GameLaunchHelper` exits first, and its parent is the activator — the user's shell when **Play** starts it,
|
||||
which is where the scan set already stops. Every member opened with the guard's rights as a standard user, none is an
|
||||
AppContainer, none runs under any of the policies above, and no member's module matched a fuzzy fragment or a blocklist
|
||||
name. So the scan set needs nothing new for these titles; an Xbox title that ships anti-cheat is unmeasured
|
||||
(`20_OPEN_QUESTIONS` §G).
|
||||
### What a finding does to the game — owner decision 2026-09-22
|
||||
|
||||
**The per-game override of 2026-09-21 is withdrawn.** It shipped in `0.1.0-beta.3` and `beta.4`. Its first real use
|
||||
@@ -456,7 +590,10 @@ card is back with the finding under its disabled switch. The finding itself is o
|
||||
**What clears it.** Nothing, as before: the block outlives *Change executable* and a re-import (§A game already enabled
|
||||
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
|
||||
switch. *(Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
|
||||
exception.)*
|
||||
exception.)* *(And under D55, beta.19: the Agent removes an entry whose game is no longer installed and that has no session,
|
||||
but never one that carries a block, an exception's grant or a failed trial — the delete's own SQL refuses them
|
||||
(`SqliteGamePrune`), so an uninstall is not how a block, a grant or D38's "never again" disappears. Only the user's
|
||||
*Remove… ▸ Delete sessions too* deletes such a row, as before.)*
|
||||
|
||||
**D21 stands as a fact.** A process an anti-cheat driver protects is `SessionEndReason.TargetUnreadable` (2026-09-21:
|
||||
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
|
||||
@@ -475,24 +612,36 @@ unmeasured rule — NetEase Yidun, `AntiCheatFile NEP2.dll` — after FrameLedge
|
||||
normal Tier-1 sessions in the owner's ledger, 474,143 frames). The owner asked for a way to keep measuring a game like
|
||||
that, and chose, against the rule this document had kept since 2026-09-22 and with that rule quoted back to them, **an
|
||||
exception the user grants per game, bound to evidence, and only for anti-cheat that is user-mode throughout.** The
|
||||
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — an exception is only
|
||||
offered where FrameLedger has already measured the game hooked; it "only exposed the user to the risk its own disclosure
|
||||
described" — that risk stands, and the disclosure says so, including that a ban can arrive days later and that FrameLedger
|
||||
cannot know.
|
||||
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — ~~an exception is only
|
||||
offered where FrameLedger has already measured the game hooked~~ *(D38 below: the measurement now comes under the grant,
|
||||
as its trial)*; it "only exposed the user to the risk its own disclosure described" — that risk stands, and the disclosure
|
||||
says so, including that a ban can arrive days later and that FrameLedger cannot know.
|
||||
|
||||
> **Amended 2026-10-03 (owner decision D38): the evidence comes after the grant, as a trial.** The owner deleted their
|
||||
> ledger and found *GIRLS' FRONTLINE 2* "Not eligible: 0 successful hooked session(s), two are needed" — for good. The rule
|
||||
> below was a catch-22 for every game it could ever meet again: since beta.8 the library sweep blocks a game the moment
|
||||
> it is added, a blocked game is never hooked without a grant (`CaptureSession` sends it to Tier 2 before the resolver),
|
||||
> so it can never earn the two sessions, and a reset ledger loses the ones it had. D33's evidence was reachable only for a
|
||||
> game measured before its block, and only while those rows lasted. Asked with that, the owner chose: **a grant needs no
|
||||
> session; the first two hooked sessions under it are a trial; any of them that does not go well ends the exception for
|
||||
> good** (`games.ac_exception_trial_failed_at`, schema 0017, which nothing clears). Every other condition is unchanged.
|
||||
|
||||
**What may be excepted — all of it must hold:**
|
||||
|
||||
- every finding about the game is `BlockedModule`, `AntiCheatFile` or `AntiCheatDirectory` of **one** family;
|
||||
- that family's whole footprint is user-mode — no `drivers` entry, no `services` entry and no `*.sys` among its `files`, in
|
||||
the compiled floor or the rules file (`fl::guard::FamilyIsUserModeOnly`). The floor cannot be shrunk, so data can make a
|
||||
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain and
|
||||
FredaikisAntiCheat; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
|
||||
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
|
||||
- no `*.sys` anywhere in the install tree *(within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder)* — the kernel-driver rule (D30) is never excepted, whichever family a driver
|
||||
belongs to (so *Aniimo*, which unpacks `NEPKernel.sys` beside `NEP2.dll` on its first run, stays blocked);
|
||||
- the game is on no title list (`BlockedExecutable`, `BlockedStoreId` — the notorious titles are there by design);
|
||||
- the ledger holds **at least two successful Tier-1 sessions** of the game: hooked, frames recorded, `exit_status = normal`
|
||||
(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.
|
||||
- ~~the ledger holds **at least two successful Tier-1 sessions** of the game: hooked, frames recorded, `exit_status = normal`
|
||||
(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.~~
|
||||
**Since D38 (2026-10-03): no session is needed** — and no exception of the game has ever ended during its trial
|
||||
(`ac_exception_trial_failed_at` is NULL).
|
||||
|
||||
**Never excepted, whatever the user ticked:** a machine-wide `BlockedDriver` or `BlockedService`, the fuzzy tier
|
||||
(`SuspiciousUnsigned`), a scan that could not look or finish, unusable rules, `TargetUnreadable` (D21), a 32-bit target,
|
||||
@@ -517,6 +666,20 @@ in-process floor stop revokes it; an executable change ends it with the consent
|
||||
the option off suspends every exception. **The block itself is never cleared** — the exception is a separate layer over
|
||||
it, and the finding stays on the game's page (FR-2.2).
|
||||
|
||||
**The trial (D38).** Until two sessions under a grant have succeeded — hooked, stored, frames recorded, `normal`
|
||||
(`ISessionRepository.CountSuccessfulUnderGrantAsync`: under that family, started at or after the grant) — the grant is in
|
||||
its trial, and the App says so ("trial: 1 of 2"). During the trial **any** end of the list above ends the exception
|
||||
**for good**, and so does a stored hooked session that recorded no frame or did not end normally
|
||||
(`UserModeExceptionLapse.TrialFailed`, decided by `UserModeExceptionLapsePolicy` when the recorder stores the row): the
|
||||
end is recorded with its own reason and `ac_exception_trial_failed_at` is set. While it is set the sweep writes the game
|
||||
not eligible, the Agent refuses a grant (`Refused.reason = TrialFailed`, the signal is when) and the store refuses one in
|
||||
SQL; withdrawing, a game update, *Change executable* and a twin merge all keep it. A session too short to be stored, or
|
||||
one that was never hooked, is not judged by its frames or its exit — it neither counts toward the two nor fails the
|
||||
trial that way — but an end of the list above still ends the exception for good during the trial: a crash while
|
||||
hooked, however short, or a finding about the game at the start. After the trial, an end is what it was under
|
||||
D33: the exception may be made again once the sweep finds the game eligible. Deleting sessions can only lengthen a trial
|
||||
— the count is read, never stored as a grant's own fact.
|
||||
|
||||
**What it is not.** Not a bypass of a live refusal, not a global switch (a Settings option off by default enables the list,
|
||||
and the user ticks each game), not reachable from the command line, and not evasion: the DLL stays `LoadLibraryW`-loaded,
|
||||
named and visible (rule 3). `InjectViaLoadLibrary` still has internal linkage in `fl_guard.cpp`; `tools/chokepoint-check.ps1`
|
||||
@@ -531,6 +694,13 @@ option and the list in Settings, the versioned disclosure (`Safety_Exception_*`,
|
||||
game page's exception card and its usable switch under an exception in force, the marks, and the legal text
|
||||
(Disclaimer §2A 2.7, EULA 1.3, the accuracy block, SECURITY.md) — `08_UI` §Games.*
|
||||
|
||||
*D38 in beta.11 (2026-10-03): `UserModeExceptionRules.TrialSessions` replaces `RequiredSessions`; eligibility is the
|
||||
guard's answer and the trial mark; `ac_exception_sessions` is the trial's progress; schema 0017
|
||||
(`ac_exception_trial_failed_at`); `Refused.reason` `TrialFailed` replaces `TooFewSessions`; the disclosure is
|
||||
`ac-exception-dialog/2` (its `Why` names no count, a new `Trial` paragraph); the Settings list shows only games it can act
|
||||
on; and a sweep that cannot read the executable answers "could not verify" instead of leaving the row "checking" for ever.
|
||||
Legal text: Disclaimer §2A 2.9, EULA 1.4, the accuracy block, SECURITY.md, LIMITATIONS.md.*
|
||||
|
||||
|
||||
### The floor data cannot remove
|
||||
|
||||
@@ -647,10 +817,13 @@ normative documentation. Write tokens here exactly as the data must hold them.
|
||||
| mihoyo protect | `services` | name | `mhyprot2`, `mhyprot3`, `HoYoKProtect` | 2026-09-25 |
|
||||
| mihoyo protect | `files` | name | `mhypbase.dll`, `mhyprot2.sys`, `mhyprot3.sys`, `HoYoKProtect.sys` | 2026-09-25 |
|
||||
| Anti-Cheat Expert | `modules` | prefix | `SGuard`, `AntiCheatExpert` | 2026-09-25 |
|
||||
| Anti-Cheat Expert | `modules` | exact | `ACE-Base64.dll` | 2026-10-13 |
|
||||
| Anti-Cheat Expert | `drivers` | exact | `ACE-BASE.sys`, `ACE-ADVT.sys`, `ACE-GAME.sys` — **machine-wide refusal** (check 2) | seed |
|
||||
| Anti-Cheat Expert | `drivers` | exact | `ACE-CORE.sys` — **machine-wide refusal** (check 2) | 2026-10-13 |
|
||||
| Anti-Cheat Expert | `directories` | name | `AntiCheatExpert`, `AceAntibotClient` | 2026-09-25 |
|
||||
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service` | seed |
|
||||
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service`, `ACE-BASE` | seed; `ACE-BASE` 2026-10-13 |
|
||||
| Anti-Cheat Expert | `files` | name | `PGameProtectDriver_X64.sys`, `SGuard64.exe`, `SGuardSvc64.exe` | seed; `SGuard64.exe`, `SGuardSvc64.exe` 2026-09-25 |
|
||||
| Anti-Cheat Expert | `files` | name | `ACE-BASE.sys`, `ACE-CORE.sys`, `ACE-Base64.dll`, `ACE-Service64.exe`, `ACE-Setup64.exe` (measured in Wuthering Waves' folder) | 2026-10-13 |
|
||||
| EA AntiCheat | `modules` | prefix | `EAAntiCheat` | 2026-09-25 |
|
||||
| EA AntiCheat | `drivers` | exact | `EAAntiCheat.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
|
||||
| EA AntiCheat | `files` | name | `EAAntiCheat.Installer.exe`, `EAAntiCheat.GameServiceLauncher.exe`, `EAAntiCheat.GameServiceLauncher.dll` | 2026-09-25 |
|
||||
@@ -681,10 +854,12 @@ normative documentation. Write tokens here exactly as the data must hold them.
|
||||
| Activision Ricochet | `files` | name | `randgrid.sys` | 2026-09-25 |
|
||||
| FredaikisAntiCheat | `directories` | name | `FredaikisAntiCheat` | 2026-09-25 |
|
||||
| **Valve VAC** | — | — | ~~**No data yet** — needs `blockedStoreIds`, whose half of check 3 **cannot be called**~~ **Per-title lists since 2026-09-25** (check 3): 13 Steam app ids and 8 executables, the store half wired. VAC runs inside Steam, so no module, driver or file of the game's own can name it — this row stays a dash on purpose. (**Measured 2026-08-04: a real VAC title returned `Allow`**, `spike-notes.md` §13 — the gap these lists close.) | 2026-09-25 |
|
||||
| **CrackProof** | — | — | **Per-title list since 2026-10-03** (check 3, rules `2026.10.1`): 3 Steam app ids, no executables. Its kernel driver loads from `System32` under a numbered name, so no module, driver or file of the game's own can name it — this row stays a dash on purpose, like VAC's. | 2026-10-03 |
|
||||
|
||||
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
|
||||
@@ -731,7 +906,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
|
||||
@@ -788,6 +963,15 @@ checked stays untrusted and refuses — that direction is deliberate.
|
||||
Re-run **every pre-injection check** every 30 s, for **every Tier-1 session —
|
||||
injected or layered**.
|
||||
|
||||
> **A refused re-scan of a game that has already exited is that exit (owner decision D48, beta.14).** When the re-scan
|
||||
> refuses only because it could not read the game's tree (`ProcessUnreadable`, `ModuleScanFailed`,
|
||||
> `ProcessTreeUnavailable` — never a finding) and the game itself has exited by the time the session concludes, the
|
||||
> session ends as `TargetExited`, its exit code deciding normal or crashed, with `scan_at_exit=<reason>` in its notes
|
||||
> (`Application.Capture.ExitScanRelabel`). The stop was still published to the Overlay — the game it would have stopped
|
||||
> is gone. A finding, any refusal while the game still runs, and a refusal of another check (drivers, services, the
|
||||
> pre-scan) are a safety unhook exactly as before. `CaptureSessionTests.AnUnreadableRescanOfAGameThatHasExited…` and
|
||||
> its three refusing neighbours.
|
||||
|
||||
> **This said "both the module scan and the driver scan" until 2026-08-05, and
|
||||
> the loop runs four checks, not two** (`20_OPEN_QUESTIONS` §S23-4).
|
||||
> `FlGuardEvaluate` → `EvaluateImpl` runs `CheckDrivers`, `CheckServices`,
|
||||
@@ -856,12 +1040,32 @@ 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
|
||||
|
||||
If `OpenProcess` with the needed rights fails (protected process, higher integrity), do **not** escalate creatively. Report "cannot attach" and offer Tier-2. Never attempt to acquire privileges beyond running the Agent elevated at the user's explicit request.
|
||||
|
||||
> **The explicit request exists since beta.10 (owner decision D34, 2026-09-27): the admin mode.** An option off by default,
|
||||
> turned on through a versioned disclosure (`Safety_AdminMode_*`, `agent-admin-dialog/2` *(`/1` until 2026-11-11, when Advanced metrics widened what the option adds — D101)*) that states what it adds, what it
|
||||
> does not change, how Windows asks and the risk of a per-user install; then **Windows asks at every start of the Agent**
|
||||
> (`01_ARCHITECTURE` ADR-9). What it does NOT do, each held by code rather than by this paragraph:
|
||||
>
|
||||
> - **It clears no finding and opens no protected process.** The guard runs exactly as unelevated: the driver scan asks
|
||||
> `NtQuerySystemInformation`, and a process an anti-cheat driver protects stays `TargetUnreadable` (D21) — elevation turns
|
||||
> "could not look" into an answer only where Windows would give any administrator one.
|
||||
> - **It enables no privilege.** An elevated token holds `SeDebugPrivilege` and `SeLoadDriverPrivilege` disabled and they
|
||||
> stay so: `AdjustTokenPrivileges`, `RtlAdjustPrivilege`, `EnterDebugMode` and the debug privilege's name may not appear
|
||||
> under `src/` (`tools/chokepoint-check.ps1`), and `PrivilegeFootprintTests` asserts on the elevated CI runner that opening
|
||||
> targets and LibreHardwareMonitor's CPU group enabled none.
|
||||
> - **It elevates no game.** A game started from FrameLedger gets the desktop shell's token (`UnelevatedProcess`); with no
|
||||
> shell to take one from, the launch is refused with that reason (`Launch_Error_1400`), never made elevated instead.
|
||||
> - **It is not silent.** Every start asks; a start that was declined serves as a standard user and says so; the prompt
|
||||
> answered by another account ends that Agent before it touches anything (exit 11).
|
||||
>
|
||||
> The residual risk is stated to the user, not solved: FrameLedger installs per user and unsigned, so a program running
|
||||
> under the account could replace its files and be run as administrator the next time the user accepts the prompt.
|
||||
|
||||
## User-facing consent
|
||||
|
||||
Enabling hooking is a **per-game** action, gated by a one-time dialog per game that states, in plain language:
|
||||
@@ -901,7 +1105,8 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
|
||||
> neither choice), what is injected and why, **Tier 1 and Tier 2 as two paragraphs of the same shape** (each
|
||||
> enumerating what the session records; Tier 2 is described by what it does, never as less), the anti-cheat
|
||||
> statement including the 30 s unhook, the terms-of-service statement, and the typed acknowledgement — the
|
||||
> primary button is disabled until the phrase is typed exactly, and Enter never enables. `en` and `vi` are
|
||||
> primary button is disabled until the phrase is typed exactly~~, and Enter never enables~~ *(Enter enables once the
|
||||
> phrase matches since beta.30, owner decision D69 — below)*. `en` and `vi` are
|
||||
> written (the owner reviews `vi`); **`ja` is the English verbatim, marked `safety: human review required`**,
|
||||
> which the resx audit enforces (`09_I18N` §Safety-critical strings). The wording carries a version
|
||||
> (`Shared.Safety.SafetyDisclosure.Version = consent-dialog/1`; bump on any change of meaning in any
|
||||
@@ -913,6 +1118,18 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
|
||||
> `PipeEndToEndTests` (the real pipe, the real pre-scan, the row read back) pin each half. The toggle that opens
|
||||
> it is the game page's, PR-5.
|
||||
|
||||
> **Amended 2026-10-26 (beta.30, owner decision D69): Enter enables once the phrase is typed exactly.** "Enter never
|
||||
> enables" was built as `DefaultButton = Close`, and WPF UI 4.3.0's template sends Enter to the default button (each
|
||||
> button's `IsDefault` follows `DefaultButton`, read at the tag) — so the owner typed the phrase, pressed Enter and
|
||||
> declined without a word, while the game page's switch went on showing *on* beside *off*. Asked with that, the owner
|
||||
> chose: the primary button is the default; while the phrase does not match, the dialog's content keeps Enter
|
||||
> (`ConsentDialogContent.SwallowsEnter`) and nothing happens; once it matches, Enter enables, as a click on the
|
||||
> then-visible *Enable hooking* does. **The typed phrase is still the gate**: the button Enter reaches is disabled — and
|
||||
> hidden — until the phrase is typed exactly, so a reflexive Enter cannot enable; Esc and *Keep hooking off* still
|
||||
> decline. No `Safety_Consent_*` string changed, so `consent-dialog/1` stands. `ConsentDialogKeysTests` holds both
|
||||
> halves on the real template. The tick-box dialogs (D33's exception, D34's admin mode) are unchanged: Enter keeps them
|
||||
> declined.
|
||||
|
||||
> **The Agent stamps one since 2026-09-10 (P2 PR-F, HANDOFF §P2 decision D4):** `FrameLedger.Agent --console
|
||||
> consent grant` shows `OperatorDisclosure` (the same four statements, first line naming the surface), requires
|
||||
> the typed phrase, refuses redirected stdin, and records `ConsentProvenance.AgentConsoleOperator` with the
|
||||
@@ -925,7 +1142,12 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
|
||||
> publishing `unhookRequested`, and keeps the Vulkan layer off by never setting `FRAMELEDGER_ENABLE_VK_LAYER`
|
||||
> on a launch.
|
||||
|
||||
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection).
|
||||
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection). *(Corrected 2026-10-03, beta.12, owner
|
||||
decision D43: such a hold now reads the game process's own memory once a second — its video memory from performance
|
||||
counters that open nothing, its system memory through a handle opened with `PROCESS_QUERY_LIMITED_INFORMATION` for the
|
||||
read and closed after it, the same least right the watcher's snapshot already opens every process with, each second. No
|
||||
handle is held, nothing is injected, the guard is not involved, and what is read is the kernel's accounting about the
|
||||
process, never its memory — rule 4 is untouched. A process that refuses even that right reads N/A.)*
|
||||
|
||||
### A moved drive is the same executable — owner ask 2026-09-22
|
||||
|
||||
@@ -991,20 +1213,48 @@ 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).*
|
||||
- **Measured 2026-10-19/20 (`spike-notes` §23): direct starts turned hooking off for exits no hook caused.** Lies of P
|
||||
started by **Play** ▸ *Start directly* hands itself to Steam within seconds — its process leaves with nothing
|
||||
presented and Steam starts the game again —, and Clair Obscur: Expedition 33 started directly closes within five
|
||||
seconds and reads *crashed*, hooked or not (its third start, refused and unhooked, closed the same way). Each was a
|
||||
hooked session's early abnormal end; the policy counted them, and two turned hooking off. It cannot tell either from
|
||||
the hang it exists for, so it stands as written; whether a witness — the same executable started again within
|
||||
seconds — may exempt a hand-off is the owner's decision, not taken. Users are told in `LIMITATIONS.md` §Play.
|
||||
- **The count starts again when the user switches hooking on (owner decision D126, 0.1.0-beta.44).** Until then
|
||||
`hook_crash_count` only ever grew: Lies of P had two such ends on 2026-10-19/20 (the hand-off above), its user
|
||||
switched hooking on again, and on 2026-11-12 one more early end — the game's own crash, by the owner, after a shader
|
||||
failed to compile — switched it off at once, under a reason that says *twice*. The consent grant, the only
|
||||
statement that turns hooking on, now sets the count to 0 (`SqliteGameConsentStore`). The policy still only
|
||||
disables, a block is still never cleared, and the user-mode exception's trial (D38) keeps its own record, which
|
||||
nothing sets back.
|
||||
- **A fault while the game is closing is not seen by a hooked session (owner decision D127: written down, not
|
||||
changed in 0.1.0-beta.44).** Hogwarts Legacy faults in the driver's `_nvngx.dll` at exit — six times in Windows'
|
||||
application log since 2026-11-06, hooked or not. The one unhooked session reads `crashed`; the five hooked ones
|
||||
read `normal` with exit code 0: the witness is looked for when the session is saved, which for a hooked session
|
||||
is before Windows has written the event. Looking again later would make every session of such a game `crashed`,
|
||||
and under a user-mode exception that ends the exception for good for a fault no hook caused — so it is a decision
|
||||
of its own, not a fix to slip in beside two new hooks.
|
||||
- **What reads as a crash changed in beta.14, in both directions** (`04_CAPTURE` §Crash & exit classification): a
|
||||
Windows report that is not a crash (a memory-leak or hang report) no longer makes one, and an engine's crash reporter
|
||||
started by a game that then left does — Unreal's crash ended with exit code 3 and read `normal`. Both feed this policy,
|
||||
the D33 lapse and D38's trial as `crashed` always has: an Unreal game that crashes under a user-mode exception ends it
|
||||
now, where before beta.14 the crash went unseen; a leak report no longer ends one.
|
||||
- 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
|
||||
|
||||
+95
-2520
File diff suppressed because it is too large.
Load diff
+789
-1944
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,107 @@
|
||||
# Games FrameLedger has been run with
|
||||
|
||||
*As of 2026-11-06 (0.1.0-beta.34). Built from a copy of the developer's own FrameLedger database and the repository's
|
||||
measurement notes, and reviewed by the project's owner before it was published. It lists what happened on one machine;
|
||||
it promises nothing about any other.*
|
||||
|
||||
*~~(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.)~~ Refreshed
|
||||
2026-11-06 from a copy of the database taken that day, and reviewed by the owner with the plan of 0.1.0-beta.34: the
|
||||
sessions since 2026-09-27 are below, with the graphics memory a game used where it adds something.*
|
||||
|
||||
**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; the graphics
|
||||
driver went from 32.0.16.1714 to 32.0.16.2114 over the sessions in the database. **No AMD or Intel
|
||||
graphics card and no second machine has been tested**, and ~~**no real Vulkan or OpenGL game has been measured** — every
|
||||
measurement below is Direct3D 11 or 12~~ **one real Vulkan game has been measured (Everhex Demo, 2026-10-13) and no
|
||||
OpenGL game** — every other measurement below is Direct3D 11 or 12 *(corrected 2026-10-14)*. What the tiers mean and what FrameLedger cannot do: [LIMITATIONS.md](../LIMITATIONS.md).
|
||||
|
||||
**Two periods.** From 2026-08-03 to 2026-09-06 the games were measured with the developer's capture tool, one run at a
|
||||
time against the game's own settings menu (reports in [spike-notes.md](spike-notes.md)). From 2026-09-16 the shipped
|
||||
app and agent recorded them as a user would; ~~the database holds the sessions from 2026-09-22 on~~ the copy of
|
||||
2026-11-06 holds the sessions from 2026-10-04 on — earlier ones went with the 2026-09-16 recovery and with library
|
||||
entries and sessions removed since; a row citing the database before 2026-10-04 was read from the copy of 2026-09-27.
|
||||
|
||||
## Measured — hooked (Tier 1)
|
||||
|
||||
| Game | Engine | API | What was measured | When | Evidence |
|
||||
|---|---|---|---|---|---|
|
||||
| Cyberpunk 2077 | — | D3D12 | DLSS Balanced 1485×835 → 2560×1440, exact against its settings file; DLSS Frame Generation off ×1.00, ×3 (61.4 → 183.5 FPS), ×4 (58.7 → 234.1); FSR 3 + FSR frame generation ×2 (74.3 → 148.6); ray tracing *Yes* with path tracing on and *No* with it off, as set; on 2026-10-20, ×2, ×3 and ×4 chosen in the game's menu within one session read as separate states, ×4.0 at 63.8 → 255.3 FPS, with ray tracing and Ray Reconstruction *Yes* | 2026-08-15 → 10-20, about 26 runs | [spike-notes §8, §9, §11, §23](spike-notes.md), database |
|
||||
| Dying Light: The Beast | — | D3D12 | DLSS Frame Generation ×4: Native 70.5 → Displayed 282.1 FPS, counted through DXGI; FSR + FSR frame generation ×2 (70.5 → 140.9); ray tracing *Yes* | 2026-09-04 → 09-06 | [spike-notes §9](spike-notes.md), [03_METRICS §Frame Generation](03_METRICS.md) |
|
||||
| Hell Is Us | Unreal Engine 5.5.4 | D3D12 | DLSS Frame Generation ×4 (76.5 → 306.2); DLSS shown as *driver-reported* (it bypasses Streamline); FSR + FSR frame generation ×2 (85.7 → 171.4); XeSS frame generation shown as Presented FPS only; ray tracing *No* | 2026-09-03 → 09-16 | [spike-notes §8, §9](spike-notes.md) |
|
||||
| Black Myth: Wukong | Unreal Engine 5.0.0 | D3D12 | DLSS Frame Generation ×4 (55.4 → 221.5); ray tracing *Yes* (16.2 % of frames in the app's session); a session that changed state showed its steady state (×4.1) instead of an average | 2026-08-20 → 09-16 | [spike-notes §9, §14](spike-notes.md) |
|
||||
| Clair Obscur: Expedition 33 | Unreal Engine 5.4.4 | D3D12 | DLSS + Frame Generation ×4 (54.9 → 218.4) and ×2 (76.0 → 149.8); frame generation off read *none*, with DXGI agreeing; ray tracing *No*; the NVIDIA App's *Fixed ×6* read ×6.0 (81.8 → 490.9) on 2026-10-20 | 2026-09-04 → 10-20 | [spike-notes §9, §23](spike-notes.md), database |
|
||||
| Rune Factory: Guardians of Azuma | Unreal Engine (version not in the executable) | D3D12 | DLSS Frame Generation ×4 (128.9 → 513.0); FSR frame generation compiled into the game counted ×2 but not named; ray tracing *No* (the game has none) | 2026-08-20 → 09-06 | [spike-notes §9](spike-notes.md) |
|
||||
| Kingdom Come: Deliverance II | — | D3D12 | FSR (3.1 or 4) at 1505×847 → 2560×1440; frame generation *none* (the game ships none); ray tracing *No* | 2026-09-04 | [spike-notes §9](spike-notes.md) |
|
||||
| Lies of P | Unreal Engine 4.27.2 | D3D12 | FSR 3 at 1506×848 → 2560×1440 with FSR frame generation ×2.04 (57.1 → 116.4) in the app; frame generation off read *none*; DLSS shown as *driver-reported*; ray tracing *No*; on 2026-10-19 and 10-20, FSR 3 at 1707×961 and at 1280×720 → 2560×1440 with FSR frame generation ×2.0 (54.6 → 109.6, 57.6 → 116.7) and no FSR quality mode — the game never asked for one while the hook was in | 2026-08-03 → 10-20 | [spike-notes §7, §9, §14, §22, §23](spike-notes.md), database |
|
||||
| Onimusha: Way of the Sword (demo) | RE Engine | D3D12 | DLSS + DLSS Frame Generation: ×3.67 and ×3.93 with the capture tool, ×4.00 in the app's steady state (60 → 240 FPS), ×3.0 (60 → 180) in the app on 2026-09-22; ray tracing *Yes* | 2026-09-05 → 09-22 | [spike-notes §9, §14](spike-notes.md), database |
|
||||
| Cronos: The New Dawn (demo) | Unreal Engine (version not in the executable) | D3D12 | DLSS with frame generation off (105 FPS, *none*); on ×2 (86.8 → 172.7), DLSS Frame Generation named; ray tracing *Yes* | 2026-09-06 → 09-16 | [spike-notes §9, §14](spike-notes.md) |
|
||||
| Alan Wake 2 | — | D3D12 | Path tracing Ultra with DLSS and Ray Reconstruction: ray tracing *Yes* (96.8 % of frames), frame generation read ×1.00 (the game did not apply the setting that run). On 2026-09-04: DLSS with ray tracing *Yes* (99 % of frames), 92.5 FPS, frame generation *none* by count; then ray tracing off (*No*), DLSS, Presented 114.5 FPS. The quality preset was never read | 2026-08-04 → 09-04 | [spike-notes §8](spike-notes.md), run reports |
|
||||
| SILENT HILL 2 | Unreal Engine 5.1 | D3D12 | DLSS Frame Generation identified, frames not counted (Presented 78 FPS) on 2026-09-25; then under the NVIDIA App's *Fixed ×6* ×6.0 (53.3 → 320.0) and under its *Dynamic, up to ×6* states ×2.0, ×3.0 and ×6.1; DLSS *driver-reported*; ray tracing *Yes* | 2026-09-25 → 10-20 | database, [spike-notes §22, §23](spike-notes.md) |
|
||||
| DARK SOULS III | FromSoftware | D3D11 | Presented 59.8 FPS; no upscaler, frame generation or ray tracing loaded; then 34 sessions at the game's 60 FPS cap, the longest 6 h 12 min, four of them ended by the game crashing | 2026-09-03 → 10-25 | [spike-notes §9](spike-notes.md), database |
|
||||
| Sekiro: Shadows Die Twice | FromSoftware | D3D11 | Presented 60 FPS (the game's cap): two sessions of 15 min and 2 h 18 min, then three more of up to 1 h 6 min | 2026-09-26 → 10-29 | database |
|
||||
| Yu-Gi-Oh! Master Duel | Unity 6000.0 | D3D11 | Presented 239 FPS across six sessions (up to 5 h 25 min) | 2026-09-22 → 09-25 | database |
|
||||
| GIRLS' FRONTLINE 2: EXILIUM | Unity 2019.4 | D3D11 | Presented 53–101 FPS; the last three sessions under the user-mode anti-cheat exception (NetEase Yidun), one of them 3 h 9 min, all ended normally; ten more under the exception, 28–72 FPS, the longest 2 h 9 min, all ended normally | 2026-09-21 → 10-20 | database, [HANDOFF](HANDOFF.md) |
|
||||
| Aniimo | Unity 2022.3 | D3D12 | DLSS at 1707×960 → 2560×1440, frame generation *none* (×1.00, 205 FPS), ray tracing *No* — then blocked (below) | 2026-09-22 | database |
|
||||
| AbyssMemory | Unreal Engine 4.26.1 | D3D11 | Presented 55 FPS, one short session | 2026-09-22 | database |
|
||||
| Umamusume: Pretty Derby | Unity 2022.3 | D3D11 | Presented 37 FPS, one session | 2026-09-27 | database |
|
||||
| 恋しかるべき (KOISHIKARUBEKI) | Unity 6000.3 | D3D11 | Presented 59.6 FPS | 2026-09-03 | [spike-notes §9](spike-notes.md) |
|
||||
| Flower in Us | RPG Maker MV/MZ (NW.js) | D3D11 | Presented 59.8 FPS over three swap chains, after two refusals that found the game's browser process ambiguous (fixed) | 2026-09-03 → 09-04 | [spike-notes §9](spike-notes.md) |
|
||||
| UMIGARI | Unreal Engine 5.5.4 | D3D12 | Presented 95–97 FPS, frame generation *none*, ray tracing *No* | 2026-09-05 → 09-06 | run reports only |
|
||||
| Everhex Demo | — | Vulkan | Presented 239.7 FPS (1 % low 213.5), 14,955 frames in 69 s, through FrameLedger's Vulkan layer — the first real Vulkan game measured; started by Play set to *Start directly* | 2026-10-13 | database *(row added 2026-10-14 from a copy of the database)* |
|
||||
| The Witcher 3: Wild Hunt — Remastered | — | D3D12 | DLSS 1707×960 → 2560×1440 with DLSS Frame Generation ×2.0 (118.8 → 237.4 FPS); ray tracing and Ray Reconstruction *Yes*; under the NVIDIA App's *Fixed ×6* it still presented ×2.0 — the setting is not the frames | 2026-10-04 → 10-20 | database, [spike-notes §23](spike-notes.md) |
|
||||
| Phantom Blade Zero | Unreal Engine (version not in the executable) | D3D12 | DLSS *driver-reported*; DLSS Frame Generation under the NVIDIA App's *Dynamic* mode: up to ×6 held ×4.0 (59.5 → 235.6 FPS) and ×5.2 (44.3 → 231.2), up to ×3 held ×3.0 (58–76 → 175–227) for 75–94 % of each session longer than an hour; ray tracing *Yes*; thirteen sessions, the longest 6 h 29 min (5.26 million frames); up to 9.6 GB of graphics memory | 2026-11-01 → 11-05 | database, [spike-notes §26](spike-notes.md) |
|
||||
| Hogwarts Legacy | Unreal Engine (version not in the executable) | D3D12 | With the game's *Neural Rendering* on, DLSS 5's runtime (`nvngx_dlssnr.dll` 310.9.16.0) loaded from the game's folder — the first game seen loading it; DLSS *driver-reported*; DLSS Frame Generation not counted (non-uniform, ×1.97 overall), Presented 140.2 FPS; ray tracing *Yes*, Ray Reconstruction *No* | 2026-11-06 | database, [spike-notes §26](spike-notes.md) |
|
||||
| Valor Mortis (Xbox app) | Unreal Engine | D3D12 | DLSS Frame Generation ×6.0 (39.9 → 239.2 FPS), DLSS *driver-reported*, ray tracing *No*; recorded in attach mode | 2026-11-04 | database |
|
||||
| inKONBINI (Xbox app) | Unity 6000.0 | D3D11 | Presented 205.9 FPS, one short session | 2026-11-03 | database |
|
||||
| DARK SOULS II: Scholar of the First Sin | FromSoftware | D3D11 | The game's 60 FPS cap, nine sessions up to 5 h 29 min; one was unhooked by the safety check and recorded on | 2026-10-09 → 10-12 | database |
|
||||
| Mithril | Unreal Engine (version not in the executable) | D3D12 | Presented 91.5–119.4 FPS, ray tracing *Yes*, four sessions up to 3 h 4 min | 2026-10-12 → 10-16 | database |
|
||||
| KEEP IT ON HER | Unreal Engine 5.8 | D3D12 | Presented 59.5–108.8 FPS, ray tracing *Yes* | 2026-10-12 → 10-13 | database |
|
||||
| WALTO | Unity 6000.3 | D3D12 | Presented 212.5 FPS over 2 h 41 min (2,057,022 frames) | 2026-10-08 | database |
|
||||
| White Mask Mansion | Unity 6000.1 | D3D12 | Presented 286–309 FPS, five sessions | 2026-10-27 | database |
|
||||
| LIMINAL: Within Demo | Unity 2022.3 | D3D11 | Presented 222.5–228.6 FPS | 2026-10-12 | database |
|
||||
| Sleepytime Village | Unity 2021.3 | D3D11 | Presented 906–1,440 FPS (the game sets no cap) | 2026-10-25 → 10-26 | database |
|
||||
| Scarlet Wolf | Unity 2021.3 | D3D11 | Presented 128.5 FPS | 2026-10-15 | database |
|
||||
| March Out! Playtest | Unity 2022.3 | D3D11 | Presented 118.2 FPS | 2026-10-08 | database |
|
||||
| A Space for the Unbound – Prologue (GOG) | Unity 2019.4 | D3D11 | Presented 61.0 FPS, started by FrameLedger | 2026-10-20 | database |
|
||||
|
||||
## Recorded without measurement (Tier 2)
|
||||
|
||||
| Game | Why nothing was measured | When | Evidence |
|
||||
|---|---|---|---|
|
||||
| HELLO, HELLO WORLD! | A 32-bit game (RPG Maker MV): refused by the guard once, and two sessions with hooking switched off — each recorded with its duration and sensors. *Its itch.io download puts malware in front of the game — do not run it (noted 2026-10-13, [spike-notes §20](spike-notes.md))* | 2026-09-23 | database |
|
||||
| Umamusume: Pretty Derby | Three sessions played with hooking switched off for the game | 2026-09-27 | database |
|
||||
| Sekiro: Shadows Die Twice | Two sessions played with hooking switched off | 2026-09-25, 10-07 | database |
|
||||
| GIRLS' FRONTLINE 2: EXILIUM | One session whose process Windows would not let FrameLedger open, and two recovered after the agent itself stopped mid-session (*interrupted*) | 2026-09-22 → 09-23 | database |
|
||||
| Bound Between Desks | Two sessions with hooking switched off (a Ren'Py 8.5 game) | 2026-10-15 → 10-20 | database |
|
||||
| Phantom Blade Zero | Three sessions after a game update changed its executable on 2026-11-04, until hooking was consented to again on 11-05; one refused because a module list came back incomplete | 2026-11-04 → 11-05 | database |
|
||||
| The Witcher 3: Wild Hunt — Remastered | Three sessions before hooking was consented to | 2026-10-13 → 10-20 | database |
|
||||
| Mithril | Two sessions before hooking was consented to | 2026-10-16 | database |
|
||||
| Hogwarts Legacy | One session with hooking switched off; Windows logged a crash of the game | 2026-11-06 | database |
|
||||
| Valor Mortis, WALTO, Scarlet Wolf, Lies of P, A Space for the Unbound – Prologue | One session each with hooking switched off | 2026-10-08 → 11-04 | database |
|
||||
|
||||
## Refused by the anti-cheat guard
|
||||
|
||||
| Game | What was found | When | Evidence |
|
||||
|---|---|---|---|
|
||||
| ELDEN RING | Easy Anti-Cheat: its folder, and a process Windows would not let FrameLedger open. Nothing was ever injected; eight sessions recorded without measurement | 2026-09-21 → 09-27 | [CHANGELOG](../CHANGELOG.md), database |
|
||||
| GIRLS' FRONTLINE 2: EXILIUM | NetEase Yidun (`NEP2.dll`, user mode) — turned hooking off after it had been measured; measured again since 2026-09-26 under the user-mode exception its owner made | 2026-09-25 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
|
||||
| Aniimo | NetEase Yidun with a kernel driver (`NEPKernel.sys`) in the game's folder — never eligible for an exception | 2026-09-25 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
|
||||
| Goose Goose Duck | Easy Anti-Cheat's service running, and its folder | 2026-08-04 | [spike-notes §13](spike-notes.md) |
|
||||
| Neverness To Everness | Anti-Cheat Expert's kernel driver in the game's folder | 2026-08-04 | [spike-notes §13](spike-notes.md) |
|
||||
| Wuthering Waves | Anti-Cheat Expert, kept beside the game's executable four folder levels in, where the check did not look before beta.21: a session with hooking on was injected and unhooked 37 seconds later, when the 30-second re-check met ACE's driver (`ACE-BASE.sys`); nothing was measured. Since beta.21 its folder and its Steam id refuse it before any injection *(row added 2026-10-13 from the agent's log)*; two sessions recorded without measurement on 2026-10-31 | 2026-10-12 → 10-31 | [spike-notes §19](spike-notes.md), database |
|
||||
| Arknights: Endfield | Anti-Cheat Expert's folder (`AntiCheatExpert`) beside the game; one session recorded without measurement | 2026-10-31 | database |
|
||||
| Stella Sora | Anti-Cheat Expert's folder (`AntiCheatExpert`); three sessions recorded without measurement | 2026-10-30 → 10-31 | database |
|
||||
| Umamusume: Pretty Derby | CrackProof, on FrameLedger's title list since beta.11 (Steam 3224770) — measured before the list named it (above) | 2026-10-03 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
|
||||
| Counter-Strike 2 | Valve Anti-Cheat — refused by FrameLedger's title list since beta.8. On 2026-08-04 the checks alone allowed it (VAC is invisible to them); nothing was injected | 2026-08-04, beta.8 | [spike-notes §13](spike-notes.md), [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
|
||||
|
||||
Also refused before any injection: **Deadly Heart Gambit** — a 32-bit game (2026-08-03).
|
||||
|
||||
## Engine version read from the executable only
|
||||
|
||||
The Unreal Engine version (beta.10) was checked against ten installed Unreal games without running them: Hell Is Us
|
||||
5.5.4, Black Myth: Wukong 5.0.0, Clair Obscur: Expedition 33 5.4.4, Lies of P 4.27.2, SILENT HILL 2 5.1, UMIGARI 5.5.4,
|
||||
AbyssMemory 4.26.1, **Martha Is Dead 4.27.0**; Cronos (demo) and Rune Factory name no version in their executables and
|
||||
read *not found*. ([spike-notes §15](spike-notes.md), [05_DETECTION §Engine version](05_DETECTION.md)) Read since on the games
|
||||
in the database: KEEP IT ON HER 5.8 and Wuthering Waves 4.26.2; Phantom Blade Zero, Hogwarts Legacy and Mithril name no
|
||||
version in their executables, and an Xbox game's executable cannot be read outside its package (Valor Mortis).
|
||||
@@ -0,0 +1,95 @@
|
||||
# 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~~ D1 onward — *corrected 2026-10-07: the range grows with every train*) and the traps that each cost a cycle. It carries no status on purpose |
|
||||
| Find your way around first | The [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages (source: [`../wiki/`](../wiki/), beta.17) — a short page per part, each linking here |
|
||||
| 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), [`../CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) *(it and `SECURITY.md`, below, added 2026-11-09: the index named neither)* |
|
||||
|
||||
**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 open owner-only items, the index of the owner's decisions |
|
||||
| [`handoff/`](handoff/) | Since beta.24 (D66): the history of every train and phase, the passed owner-only items, the traps — moved out of `HANDOFF.md` verbatim |
|
||||
| [`open-questions/`](open-questions/) | Since beta.24 (D66): the entries §S24 marks resolved, moved out of `20_OPEN_QUESTIONS.md` verbatim — a table there lists them |
|
||||
| [`spike-notes/`](spike-notes/) | Since beta.24 (D66): one file per measurement section; `spike-notes.md` is the index that resolves `spike-notes §N` |
|
||||
| [`changelog/`](changelog/) | Since beta.24 (D66): each release's notes in its own file, and the ledger kept before the first tag; `../CHANGELOG.md` keeps `[Unreleased]` and the list |
|
||||
| [`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); since beta.17 (D54) also the wiki's End-user part.
|
||||
- [`../wiki/`](../wiki/Home.md) — the wiki's own pages: Home, the sidebar, the developer pages (D53). `wiki.yml`
|
||||
publishes them with the guide to the Wiki tab when a release is made; `build.ps1`'s `wiki-check` holds every link.
|
||||
- [`../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.
|
||||
- [`../ACCESSIBILITY.md`](../ACCESSIBILITY.md) — the accessibility statement (beta.35, D88): the goal, what works with the
|
||||
keyboard, a screen reader and contrast themes, the known limits and how a barrier is reported; shown in the App under
|
||||
Help ▸ Accessibility. Its checks are [`08_UI.md`](08_UI.md) §Accessibility.
|
||||
- [`../SECURITY.md`](../SECURITY.md) — the private route for a vulnerability, and why the guard has no override.
|
||||
- [`../rules/detection-rules.json`](../rules/detection-rules.json) — engine, platform and capability signatures and the
|
||||
anti-cheat blocklist, validated by `tools/rules-validate.ps1`.
|
||||
@@ -0,0 +1,40 @@
|
||||
<!-- The first alpha's notes (D73-D76), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-alpha.1] - 2026-10-31
|
||||
|
||||
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK.** This is an **alpha**: the source of `0.1.0-beta.32` built on
|
||||
> **.NET 11 Release Candidate 3** (SDK `11.0.100-rc.3.26522.148`, runtime `11.0.0-rc.3.26522.148`), a version of .NET
|
||||
> Microsoft has not finished, with the C# 15 compiler. It has not been tested the way a beta is, and it can crash, record
|
||||
> wrongly or fail to update in ways no beta has. **If you want results you can rely on, use the beta.** Before it runs it
|
||||
> shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.0), which you must accept, with its own box to tick.
|
||||
|
||||
**The first alpha.** What it is and how to go back: the user guide's *Alpha builds* page
|
||||
(`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
|
||||
|
||||
**Installing it:** download `FrameLedger.App-alpha-Setup.exe` below, verify its hash against `SHA256SUMS.txt`, run it,
|
||||
and let it replace the FrameLedger already installed. **It replaces the beta** — one of them is installed at a time — and
|
||||
uses the same data folder: before it first opens your database it copies it to
|
||||
`%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.1.db`, and it does not open the database if the copy cannot
|
||||
be made. It never arrives as an update to a beta, and it updates only to newer alphas.
|
||||
|
||||
**Going back:** install the newest beta's `FrameLedger.App-win-Setup.exe` over it; your database stays where it is, with
|
||||
any sessions the alpha recorded.
|
||||
|
||||
**Windows and your PC:** Microsoft supports .NET 11 on Windows 11 24H2 and later, and on Windows 10 only in its LTSC and
|
||||
IoT editions; on Windows 10 22H2 Home or Pro this alpha may run, but nobody supports it there. It needs a processor with
|
||||
SSE4.2 and POPCNT. .NET 11 RC3 is supported by Microsoft until .NET 11 ships (10 November 2026); the next alpha moves to
|
||||
the final release.
|
||||
|
||||
### What differs from 0.1.0-beta.32
|
||||
|
||||
- **The runtime and the compiler**: .NET 11 RC3 in place of .NET 10.0.14, self-contained as always; C# 15. The source
|
||||
uses no C# 15 syntax and no preview feature (owner decision D76) — what .NET 11's SDK asked of it was taken on main in
|
||||
forms .NET 10 also compiles (`docs/spike-notes/24-dotnet11-probe.md`), so a beta and this alpha are the same code.
|
||||
- **Three libraries serviced with the runtime**: `Microsoft.Extensions.Hosting`, `System.Diagnostics.EventLog` and
|
||||
`Microsoft.Data.Sqlite` `11.0.0-rc.3.26522.148`. The database engine is SQLite 3.53.4 (`SQLitePCLRaw` 3.0.5, which
|
||||
`Microsoft.Data.Sqlite` 11 declares), where the beta's is 3.53.3; the database file is the same format. Nine
|
||||
`Microsoft.Extensions.*` libraries are now part of the runtime and no longer ship beside it.
|
||||
- **What .NET 11 itself changes**: a failure in the capture agent's own background work ends the agent with a crash report
|
||||
where the beta's exits quietly (`IHost` now reports it); the runtime's ReadyToRun code targets processors with AVX2, so
|
||||
an older processor starts the program a little slower.
|
||||
- **The part of FrameLedger loaded into a game is the beta's**, built from the same C++ source: it does not use .NET.
|
||||
@@ -0,0 +1,33 @@
|
||||
<!-- The second alpha's notes (D73, D82), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-alpha.2] - 2026-11-03
|
||||
|
||||
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK.** This is an **alpha**: the source of `0.1.0-beta.33` built on
|
||||
> **.NET 11 Release Candidate 3** (SDK `11.0.100-rc.3.26522.148`, runtime `11.0.0-rc.3.26522.148`), a version of .NET
|
||||
> Microsoft has not finished, with the C# 15 compiler. It has not been tested the way a beta is, and it can crash, record
|
||||
> wrongly or fail to update in ways no beta has. **If you want results you can rely on, use the beta.** Before it runs it
|
||||
> shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.0), which you must accept, with its own box to tick.
|
||||
|
||||
**The second alpha: `0.1.0-beta.33` on .NET 11 RC3** — games from the Xbox app and the Microsoft Store (the beta's
|
||||
notes, `docs/changelog/0.1.0-beta.33.md`, say what that brings). What an alpha is and how to go back: the user guide's
|
||||
*Alpha builds* page (`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
|
||||
|
||||
**Updating from `0.1.0-alpha.1`:** Help ▸ Check for updates, then *Restart to update* with no game running — an alpha
|
||||
updates only to newer alphas. Before it first opens your database it copies it to
|
||||
`%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.2.db` (the newest three copies are kept). The terms window
|
||||
shows the **Privacy Policy 2.13** once and, as every time an alpha's terms window opens, waits for the Alpha notice's box
|
||||
to be ticked again; the notice itself stays 1.0. The ledger stays at schema 21; the detection rules move to `2026.11.1`.
|
||||
|
||||
**Installing it over a beta:** download `FrameLedger.App-alpha-Setup.exe` below, verify its hash against
|
||||
`SHA256SUMS.txt`, and let it replace the FrameLedger already installed; the Alpha notice is shown first. **Going back:**
|
||||
install the newest beta's `FrameLedger.App-win-Setup.exe` over it; your database stays where it is.
|
||||
|
||||
**Windows and your PC:** as for the first alpha — Microsoft supports .NET 11 on Windows 11 24H2 and later, and on Windows
|
||||
10 only in its LTSC and IoT editions; it needs a processor with SSE4.2 and POPCNT. .NET 11 RC3 is supported until .NET 11
|
||||
ships (10 November 2026); the next alpha moves to the final release.
|
||||
|
||||
### What differs from 0.1.0-beta.33
|
||||
|
||||
The same as `0.1.0-alpha.1` differed from `0.1.0-beta.32` (`docs/changelog/0.1.0-alpha.1.md`): the runtime and the
|
||||
compiler, the three libraries serviced with the runtime, what .NET 11 itself changes — and the part of FrameLedger loaded
|
||||
into a game is the beta's.
|
||||
@@ -0,0 +1,36 @@
|
||||
<!-- The third alpha's notes (D73, D87), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-alpha.3] - 2026-11-06
|
||||
|
||||
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK.** This is an **alpha**: the source of `0.1.0-beta.34` built on
|
||||
> **.NET 11 Release Candidate 3** (SDK `11.0.100-rc.3.26522.148`, runtime `11.0.0-rc.3.26522.148`), a version of .NET
|
||||
> Microsoft has not finished, with the C# 15 compiler. It has not been tested the way a beta is, and it can crash, record
|
||||
> wrongly or fail to update in ways no beta has. **If you want results you can rely on, use the beta.** Before it runs it
|
||||
> shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.0), which you must accept, with its own box to tick.
|
||||
|
||||
**The third alpha: `0.1.0-beta.34` on .NET 11 RC3** — DLSS 5 and DLSS 4.5 named from what the game and the driver did,
|
||||
filters on Games and Compare, and a Games page that opens at once (the beta's notes, `docs/changelog/0.1.0-beta.34.md`,
|
||||
say what that brings). What an alpha is and how to go back: the user guide's *Alpha builds* page
|
||||
(`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
|
||||
|
||||
**Updating from `0.1.0-alpha.2`:** Help ▸ Check for updates, then *Restart to update* with no game running — an alpha
|
||||
updates only to newer alphas. Before it first opens your database it copies it to
|
||||
`%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.3.db` (the newest three copies are kept). The terms window
|
||||
shows the **Disclaimer 2.13** and the **Privacy Policy 2.14** once and, as every time an alpha's terms window opens, waits
|
||||
for the Alpha notice's box to be ticked again; the notice itself stays 1.0. The ledger moves to schema 22, which an
|
||||
alpha.2 cannot open (the copy is the database as alpha.2 left it; going back is to the newest beta, which opens it); the
|
||||
detection rules move to `2026.11.2`.
|
||||
|
||||
**Installing it over a beta:** download `FrameLedger.App-alpha-Setup.exe` below, verify its hash against
|
||||
`SHA256SUMS.txt`, and let it replace the FrameLedger already installed; the Alpha notice is shown first. **Going back:**
|
||||
install the newest beta's `FrameLedger.App-win-Setup.exe` over it; your database stays where it is.
|
||||
|
||||
**Windows and your PC:** as for the first alpha — Microsoft supports .NET 11 on Windows 11 24H2 and later, and on Windows
|
||||
10 only in its LTSC and IoT editions; it needs a processor with SSE4.2 and POPCNT. .NET 11 RC3 is supported until .NET 11
|
||||
ships (10 November 2026); the next alpha moves to the final release.
|
||||
|
||||
### What differs from 0.1.0-beta.34
|
||||
|
||||
The same as `0.1.0-alpha.1` differed from `0.1.0-beta.32` (`docs/changelog/0.1.0-alpha.1.md`): the runtime and the
|
||||
compiler, the three libraries serviced with the runtime, what .NET 11 itself changes — and the part of FrameLedger loaded
|
||||
into a game is the beta's.
|
||||
@@ -0,0 +1,42 @@
|
||||
<!-- The fourth alpha's notes (D73, D98), on main as every release's are; the alpha branch takes them with its sync. CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-alpha.4] - 2026-11-11
|
||||
|
||||
> ⚠ **EXPERIMENTAL BUILD — YOU USE IT AT YOUR OWN RISK — AND THE LAST ALPHA FOR NOW.** This is an **alpha**: the source
|
||||
> of `0.1.0-beta.37` built on **.NET 11.0.0**, Microsoft's final release of .NET 11 (SDK `11.0.100`) — the same .NET the
|
||||
> betas run on from `0.1.0-beta.37`. It exists to bring an installed alpha off the release candidate. **After it the
|
||||
> alphas pause**, and a paused alpha gets no update — the list of anti-cheat software FrameLedger refuses included.
|
||||
> **Install the latest beta over it.** Before it runs it shows the *Alpha notice* (`legal/ALPHA_NOTICE.md` 1.1), which
|
||||
> you must accept, with its own box to tick.
|
||||
|
||||
**The fourth alpha: `0.1.0-beta.37` on .NET 11.0.0.** The alphas were made to try .NET 11 before the betas relied on it.
|
||||
.NET 11 shipped on 10 November 2026 and the betas moved to it the next day (the beta's notes,
|
||||
`docs/changelog/0.1.0-beta.37.md`), so an alpha and a beta now differ in nothing but what an alpha adds for itself. This
|
||||
one is published so that a copy of `0.1.0-alpha.3`, which runs on a release candidate Microsoft no longer supports,
|
||||
reaches the finished .NET 11 by an update — an alpha never updates to a beta.
|
||||
|
||||
**Then install the beta.** No alpha will follow until there is a newer .NET to try (.NET 12's first previews, expected
|
||||
in 2027). Until then this build stands still: no fixes, and **its anti-cheat list is the one it shipped with**, because
|
||||
that list reaches FrameLedger only inside an update. Its banner says so each time it starts. Download the newest beta's
|
||||
`FrameLedger.App-win-Setup.exe`, verify its hash against that release's `SHA256SUMS.txt`, and let it replace the alpha;
|
||||
your database stays where it is, and the beta opens it. What an alpha is and how to go back: the user guide's *Alpha
|
||||
builds* page (`guide/11-alpha-builds.md`), and the *Alpha builds* section of `LIMITATIONS.md`.
|
||||
|
||||
**Updating from `0.1.0-alpha.3`:** Help ▸ Check for updates, then *Restart to update* with no game running. Before it
|
||||
first opens your database it copies it to `%LOCALAPPDATA%\FrameLedger\backups\ledger-before-0.1.0-alpha.4.db` (the
|
||||
newest three copies are kept). The terms window shows the **EULA 1.7**, the **Disclaimer 2.14** and the **Alpha notice
|
||||
1.1**, and waits for the notice's box to be ticked. The ledger stays at schema 22 and the detection rules at
|
||||
`2026.11.2`. The download is large, because the .NET runtime inside the package is replaced whole. **One limit:**
|
||||
FrameLedger's updater looks at the newest ten releases, so once ten betas have been published after this alpha, an
|
||||
older alpha no longer finds it — install the beta by hand then, as above.
|
||||
|
||||
**Windows and your PC:** as for the beta from `0.1.0-beta.37` — Microsoft supports .NET 11 on Windows 11, and on Windows
|
||||
10 only in its LTSC and IoT editions; FrameLedger is untested and unsupported on Windows 10 22H2; a processor without
|
||||
SSE4.2 and POPCNT cannot start it.
|
||||
|
||||
### What differs from 0.1.0-beta.37
|
||||
|
||||
Nothing in the runtime, the compiler or the libraries: both are built on .NET 11.0.0 from the same source, and the part
|
||||
of FrameLedger loaded into a game is the beta's. What an alpha adds is its own: the Alpha notice in the terms window, the
|
||||
ALPHA badge and the banner — which in this build says that the alphas are paused — the locked update channel, and the
|
||||
copy of the database before it is first opened.
|
||||
@@ -0,0 +1,59 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.1] - 2026-09-16
|
||||
|
||||
**The first pre-release.** An unsigned installer, `FrameLedger.App-win-Setup.exe`, built by `release.yml` from
|
||||
this tag; `SHA256SUMS.txt` is published beside it and printed below. SmartScreen will warn (no code signing —
|
||||
`docs/11_UPDATER.md`); verify the hash, then *More info → Run anyway*. It installs into `%LOCALAPPDATA%\FrameLedger.App`
|
||||
and keeps its data in `%LOCALAPPDATA%\FrameLedger`; uninstalling asks before touching the data. Windows 10 22H2 is
|
||||
the supported floor and is **unmeasured** — every measurement below was taken on one Windows 11 machine with an NVIDIA
|
||||
GPU (`docs/spike-notes.md`).
|
||||
|
||||
### What it is
|
||||
|
||||
- **A desktop app and a background Agent.** The App (WPF) holds the library, imports it from Steam, GOG, Epic and
|
||||
itch.io, shows the Dashboard, session summaries, charts, trends and comparisons, Settings, Logs, the tray, the
|
||||
first-run Legal Gate and the bug report. The Agent watches the library at 1 Hz, records a session whenever a
|
||||
library game runs, and stores it in a local SQLite ledger. Nothing leaves the machine except the update check
|
||||
(`legal/PRIVACY_POLICY.md` 2.2).
|
||||
- **Measurement by hooking, opt-in per game, behind a hard anti-cheat gate.** For a game you enabled — and only
|
||||
after the consent dialog — the Agent loads `FrameLedger.Overlay.dll` into the game and reads what the game passes
|
||||
to the graphics APIs: frame times and output resolution from the present call (Direct3D 11/12, OpenGL; Vulkan
|
||||
through an implicit layer, today only when the Agent itself launches the title); upscaler identity and
|
||||
render→output resolution from Streamline and FidelityFX calls; the frame-generation factor from Streamline's frame
|
||||
token and FidelityFX's dispatches, **counted, never assumed**; ray tracing from DXR dispatch and
|
||||
acceleration-structure hooks. Before injecting, and every 30 s during a session, the guard scans the process
|
||||
tree for anti-cheat and anti-tamper modules, services and drivers and **refuses** — there is no override — and a
|
||||
refusal mid-session unhooks within a frame. A game that is not enabled, or is refused, is recorded as duration
|
||||
and hardware sensors with the reason, and every measured field reads N/A.
|
||||
- **Honest numbers by rule.** Where frame generation is active the readout is *Native → Displayed (×N FG)*;
|
||||
where it was identified but the count refused — a session whose frame-generation state changed (menus,
|
||||
loading screens, alt-tab), or a title with two swapchains — the chip says "factor not counted" and its tooltip
|
||||
says which bucket and by how much. Ray tracing, path tracing and Ray Reconstruction are Yes / No / N/A, measured
|
||||
or not at all. The one number that stands alone carries a qualifier saying whether a frame-generation runtime
|
||||
was loaded.
|
||||
- **Telemetry** from DXGI and PDH (every vendor), LibreHardwareMonitor (GPU sensors unelevated), and NVAPI on
|
||||
NVIDIA. CPU and board sensors need PawnIO and elevation and are off by default.
|
||||
- **Safety and legal surface:** the consent dialog with the disclosure text in en/vi/ja (ja machine-drafted,
|
||||
marked for review), the kill switch, a crash within 60 s of injection twice auto-disabling hooking for that game,
|
||||
the Legal Gate (EULA 1.0, Disclaimer 2.2, Privacy Policy 2.2), the bug bundle built locally and redacted,
|
||||
crash dumps offered only when ticked.
|
||||
|
||||
### What it is not, yet
|
||||
|
||||
- **No rules feed.** The anti-cheat blocklist and the detection rules ship with the build and update only with the
|
||||
next release (`docs/20_OPEN_QUESTIONS.md` §S20). A missed anti-cheat is a safety report (`SECURITY.md`).
|
||||
- **Vulkan in attach mode is unmeasured**, and the layer is registered only when you ask (Settings).
|
||||
- **The DLSS quality preset reads N/A** on every title measured: no title chains the structure that carries it.
|
||||
- **AMD and Intel GPUs are unmeasured** for telemetry and for their frame-generation runtimes; XeSS and the newer
|
||||
FidelityFX frame generation are identified by module, not counted.
|
||||
- **The frame-generation factor is refused rather than guessed** on whole play sessions that changed state; a
|
||||
steady-state figure over the uniform part of a session is a decision not yet taken.
|
||||
- **The ≤ 0.5 % FPS-impact run and the "against the game's own menu" readings** in `docs/spike-notes.md` §14 are
|
||||
still the owner's to take.
|
||||
|
||||
### The record
|
||||
|
||||
Everything that landed before this tag — every PR from 2026-08-04 to 2026-09-16, with its reasoning — is the
|
||||
section *Ledger before 0.1.0-beta.1* below, kept verbatim.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.10] - 2026-09-28
|
||||
|
||||
**The tenth pre-release: how each game was shown, the agent as administrator if you choose it, and the exact Unreal
|
||||
Engine version.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
What changed for a user:
|
||||
|
||||
- **The display mode** — exclusive full-screen, borderless, windowed or minimised, as a share of each session, with the
|
||||
window's size and the monitor's — on the session summary, the game page, the Trend (three new metrics) and Compare,
|
||||
for measured and unmeasured sessions alike. Only a measured Direct3D game can say *exclusive*; others read
|
||||
*full-screen or borderless* when the window covers the screen.
|
||||
- **Run the agent as administrator** — a Settings option, off by default. Windows asks every time the agent starts;
|
||||
games you start from FrameLedger still run with your standard rights; it changes nothing in the anti-cheat guard.
|
||||
- **The exact Unreal Engine version** on a game's page, read from its executable, with what it rests on.
|
||||
- **What FrameLedger cannot do** is one page — Help ▸ Limitations, and `LIMITATIONS.md` — and the games it has been run
|
||||
with are listed in `docs/LIST_GAME_TESTED.md`.
|
||||
- **The Privacy Policy (2.5) and the Disclaimer (2.8) say so**, so the Legal Gate opens once after the update. The EULA
|
||||
is unchanged.
|
||||
|
||||
**Updating from `0.1.0-beta.9`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schemas 0015 and 0016 add columns; the database opens in place. Sessions recorded before show the display mode as N/A.
|
||||
- The shared-memory layout between the agent and a measured game changed (version 4): **a game that was running while
|
||||
you updated must be restarted before it can be measured** — the app says so when it meets the old layout.
|
||||
- Every game is re-detected once (rules `2026.09.6`), which fills in the Unreal Engine versions.
|
||||
|
||||
### Added
|
||||
|
||||
- **The exact Unreal Engine version on a game's page** (owner request, beta.10). The Agent reads it from the game's
|
||||
shipping executable on disk — its version number and the engine's build name compiled into it (`++UE5+Release-5.1`)
|
||||
— and the page says which of the two it rests on: *Unreal Engine 4.27.2* for Lies of P, *5.4.4* for Clair Obscur:
|
||||
Expedition 33, *5.1* for SILENT HILL 2 (whose studio replaced the version number with its own), and "not found in the
|
||||
executable" where neither says anything (Cronos, Rune Factory). Measured on ten installed Unreal titles before it was
|
||||
written: eight read, two honestly none. The file is read, never the game's process; a protected executable is scanned
|
||||
whole, once per version of the file (up to 7.5 s on a USB drive for Black Myth: Wukong), and the scan stops if the Agent
|
||||
is asked to. Rules `2026.09.6`: every game is re-detected once. Schema 0015 adds `games.engine_version_source`.
|
||||
|
||||
- **How each game was shown, and for how much of the session** (owner request, beta.10): exclusive fullscreen, borderless,
|
||||
windowed or minimised, with the window's size, the monitor it was on and its refresh rate, and the swap chain's back
|
||||
buffer. On the session summary (a *Display* card and a line with every share), the game page (the last measured session,
|
||||
and a *Display* column in Sessions), the Trend (three new metrics: the share of each session in exclusive fullscreen,
|
||||
borderless and windowed), Compare (three rows, never ranked) and both exports (the CSV's `# display:` line, the JSON's
|
||||
aggregates). **Both tiers:** a game that was not hooked has its window read from outside, which can say windowed or
|
||||
*fullscreen or borderless* but never which of those two — only the swap chain of a hooked DirectX game can say
|
||||
exclusive. What Windows does with an exclusive game behind the scenes ("fullscreen optimizations") is not visible to
|
||||
FrameLedger, and a game's menu may call a borderless window "Fullscreen": the swap chain's answer is the one shown.
|
||||
Sessions recorded before, and one recovered after a crash, read N/A. Schema 0016 adds fifteen `sessions.display_*`
|
||||
columns, and `sessions.swap_effect` — a column with no writer since the first schema — is now filled.
|
||||
|
||||
- **Run the capture agent as administrator — your choice, off by default** (owner request, beta.10). Settings ▸ Capture
|
||||
agent ▸ *Run the agent as administrator* shows what it adds (measuring a game that itself runs as administrator; the CPU
|
||||
temperature where PawnIO is installed), what it does not change (a game with anti-cheat is still refused; a Vulkan game
|
||||
run as administrator is still not measured) and the risk of a per-user, unsigned install, before it turns on. Then
|
||||
**Windows asks every time the agent starts** — also at logon, when its prompt may wait on the taskbar; there is no
|
||||
silent way. Answer No and the agent runs with your standard rights and says so; answer with another administrator
|
||||
account and that agent refuses to run, because its data would not be yours. **Games you start from FrameLedger always
|
||||
run with your standard rights**, and nothing FrameLedger does enables a privilege (a CI test on an elevated runner and a
|
||||
source check hold both). While the prompt waits, the status pill says so. With the option off, an App started as
|
||||
administrator no longer makes the agent an administrator's too. Updating now also waits for an administrator agent's
|
||||
process to let go of its files.
|
||||
|
||||
- **What FrameLedger cannot do, in one place** (beta.10). `LIMITATIONS.md` lists the limits of the whole software in
|
||||
plain words — the games it will not measure, what an unmeasured session holds, frame generation, upscaling and ray
|
||||
tracing, the display mode, the engine version, sensors, the admin mode, the platform and your data — each linked to its
|
||||
details; the app shows it under **Help ▸ Limitations**. `docs/LIST_GAME_TESTED.md` lists the real games FrameLedger has
|
||||
been run with and what was measured on each.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The legal documents say what beta.10 does** — you will be shown two of them again once. **Privacy Policy 2.5** adds
|
||||
how a tracked game's window is shown (read from Windows) and the engine version read from an Unreal Engine game's
|
||||
executable, and says for the first time two things the software already did: it reads the content of a library game's
|
||||
executable (engine and library markers, its import table) and the processor load and memory in use. **Disclaimer 2.8**
|
||||
adds §5A — running the capture agent as administrator, what it does and does not do, and its risk — and points at the
|
||||
new limitations page and the tested-games list. The End-User License Agreement is unchanged (1.3).
|
||||
|
||||
- **Groundwork for the display mode (beta.10): the injected component reports how the game presents** — whether its swap
|
||||
chain is in exclusive fullscreen, which window it presents to, its back buffer and swap effect — at most twice a second,
|
||||
from two getters on the swap chain the game passed (measured at 13–15 ns each on the test fixture: nothing a frame rate
|
||||
can see). The shared-memory layout moves to version 4 (a new region; the frame ring moved behind it): **a game that is
|
||||
running while FrameLedger is updated must be restarted before it can be measured**, which the app already says when it
|
||||
meets an old layout. What the app shows from it is the display mode under *Added*.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An Unreal game's engine version was a bare "4" or "5"** — and for most titles nothing at all. The rule's pattern had two
|
||||
capture groups and the evaluator keeps the first, and it read only a version string most executables leave empty.
|
||||
Schema 0015 removes the digits the old rule wrote (only where detection wrote them — a version you typed stays), and the
|
||||
rules validator now refuses any version pattern that does not compile or that captures anything but exactly one group.
|
||||
|
||||
- **A Direct3D 12 game that resized through `ResizeBuffers1` kept its old output size in every later frame.** That call is
|
||||
not hooked; the swap chain's size is now re-read twice a second, so a resize by either route is seen.
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.11] - 2026-10-03
|
||||
|
||||
**The eleventh pre-release: a user-mode anti-cheat exception that can be reached, a library that fills the window, and
|
||||
charts and clean-up across a game's sessions.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`,
|
||||
then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The user-mode anti-cheat exception no longer needs earlier sessions.** A game blocked the moment it was added could
|
||||
never qualify; now its first two sessions under the exception are a trial, and one that does not go well ends the
|
||||
exception for good. Everything else it requires is unchanged, and a ban remains possible.
|
||||
- **The Games library** fills the window at any width, can be shown as a list, counts its games and has **Refresh**: it
|
||||
reads the library again, offers the games your stores installed since, and marks games whose executable is gone.
|
||||
- **Import** hides the games already in the library — you can show them, dimmed.
|
||||
- **Delete all sessions** — of one game on its page, or of every game in Settings ▸ Data.
|
||||
- **Charts across a game's sessions**: *Sessions at a glance* on the Sessions tab, and the Trend draws more metrics at once.
|
||||
- **Settings** has no row without a control.
|
||||
- **Three CrackProof games** are on the anti-cheat list (Umamusume: Pretty Derby, Heaven Burns Red, Madoka Magica Magia
|
||||
Exedra).
|
||||
- **The Disclaimer (2.9) and the EULA (1.4) say how the exception works now**, so the Legal Gate opens once after the
|
||||
update. The Privacy Policy is unchanged.
|
||||
|
||||
**Updating from `0.1.0-beta.10`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0017 adds one column; the database opens in place, and an older version cannot open it again.
|
||||
- Every game is re-checked once for anti-cheat (rules `2026.10.1`).
|
||||
- An exception made under beta.9 or beta.10 stays in force; if fewer than two sessions were played under it, the rest of
|
||||
its trial applies.
|
||||
|
||||
### Added
|
||||
|
||||
- **The Games library fills the window, switches to a list, counts its games and refreshes** (owner requests, beta.11).
|
||||
The cards were 300 px in a plain wrap, so a wide window left up to a card's width empty at the right and the third pill
|
||||
("Hooking off") was cut; the grid now has as many columns as fit at 300 px or wider, every card an equal share of the
|
||||
width, and the pills wrap. A button beside the sort switches to a **list** — one row per game with its store, engine,
|
||||
status, sessions, playtime and last played — and the choice is remembered (`ui.library_view`). The title counts the
|
||||
games. **Refresh** reads the library again, looks in the stores for games installed since and offers only those (*No
|
||||
new games* when there are none), and marks every entry whose executable is gone **Not installed** — the tooltip says
|
||||
when it is the drive that is not connected; nothing is removed. The page also reloads by itself when a session ends or
|
||||
an import adds games while it is open (an import made from the menu used to show only after leaving the page).
|
||||
|
||||
- **Import hides the games already in the library** (owner request, beta.11): on a re-import they were most of the list
|
||||
and pushed the new ones out of sight. *Show the N games already in the library* brings them back, dimmed, and a row
|
||||
that cannot be imported has its box disabled (a tick on it was taken and ignored).
|
||||
|
||||
- **Delete all sessions** (owner decision D40, beta.11): on a game's page, every session of that game; in Settings ▸
|
||||
**Data**, every session of every game — with their frame and sensor data and notes, after a confirmation that says how
|
||||
many. The library, the settings and every game's hooking consent stay. The capture agent deletes them (the rows are its)
|
||||
and refuses while a session is being recorded; an older agent is told to restart. A summary window still open on a
|
||||
deleted session closes. A new pipe request, `DeleteSessions`.
|
||||
|
||||
- **Charts across a game's sessions** (owner decision D39, beta.11): the Sessions tab opens with *Sessions at a glance* —
|
||||
every hooked session's frame rate (Presented FPS, or Native and Displayed where frame generation was measured, never one
|
||||
inflated line) and its 1% and 0.1% lows, oldest first; click a point to select that session. The Trend keeps its metric
|
||||
and can **draw more beside it** (*Also draw*), a second unit against the right axis, two units at most.
|
||||
|
||||
- **Three CrackProof titles on the anti-cheat title list** (owner request, beta.11): Umamusume: Pretty Derby (Steam
|
||||
`3224770`), Heaven Burns Red (`1973710`) and Madoka Magica Magia Exedra (`2987800`). Each store page states *"Uses
|
||||
Kernel Level Anti-Cheat"* and names HyperTech's CrackProof; its driver loads from `System32` under a numbered name,
|
||||
outside the game's folder, so nothing of the game's own can name it and the list does, by Steam id only (no executable
|
||||
name was verified). ANOTHER EDEN, which a community list also names, is left out: its store page says nothing of the
|
||||
kind. Rules `2026.10.1` — every game is re-checked once, and these games' hooking is turned off like any title-list
|
||||
finding, never under a user-mode exception (`19_SAFETY` check 3).
|
||||
|
||||
### Changed
|
||||
|
||||
- **The user-mode anti-cheat exception no longer needs sessions measured before it — its first two sessions are a
|
||||
trial** (owner decision D38, beta.11). D33 asked for two successful hooked sessions before a grant, but since beta.8 a
|
||||
game is blocked the moment it is added, so a blocked game could never earn them, and a reset ledger lost the ones it
|
||||
had: after the owner deleted theirs, GIRLS' FRONTLINE 2 read *"Not eligible: 0 successful hooked session(s), two are
|
||||
needed"* for good. A grant now needs no session. Until two sessions under it have succeeded, the game page says
|
||||
*trial: N of 2*, and any end during the trial — a crash, a safety unhook, the Overlay's own stop, a new finding, or a
|
||||
stored hooked session that recorded no frame or did not end normally — ends the exception **for good** (schema 0017,
|
||||
`games.ac_exception_trial_failed_at`, set once and never cleared; the Agent refuses a grant with `TrialFailed` and the
|
||||
store refuses one in SQL; a twin merge keeps the mark). Every other condition is unchanged — one user-mode family, no
|
||||
`.sys` in the game's folder, no title list — and after the trial an end is what it was. The disclosure is
|
||||
`ac-exception-dialog/2`: it names no session count and has a *Trial* paragraph (`ja` stays English until reviewed).
|
||||
**Legal text:** Disclaimer 2.9 (§2A) and EULA 1.4, so the Legal Gate opens once; the accuracy block, `SECURITY.md` and
|
||||
`LIMITATIONS.md` say the same; CLAUDE.md rule 2 carries the amendment (`19_SAFETY` §The user-mode exception).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Settings has no row without a control** (owner request, beta.11): *Games with hooking on* shows only while a game has
|
||||
hooking on, the *Elevation* row became the admin mode row's status line, and the note under the language row is gone.
|
||||
The retention message now names Settings ▸ Recording, where retention lives.
|
||||
|
||||
- **The exception's card and list say what is true** (found with D38): an eligible game's *Anti-cheat* card said hooking
|
||||
"cannot be turned on" beside a usable *Make exception…* — it now says hooking is off unless you make one; the Settings
|
||||
list showed each game's session count twice and listed games that could never qualify, with no action — it lists only
|
||||
games it can act on; a tolerant scan that found nothing of the family was said as "the check could not finish" — it
|
||||
says the family was not found; and a blocked game whose executable could not be read stayed *Checking…* for ever — the
|
||||
sweep now answers it. **Refresh** shows only while a row is being checked, the one time it can change anything.
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.12] - 2026-10-04
|
||||
|
||||
**The twelfth pre-release: how much memory each game itself uses, documents you can read, and a user guide.** The same
|
||||
unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The game's own memory, in every session** — its video memory and its RAM, the figures Task Manager's Details tab
|
||||
shows for the game's process, read once a second from outside the game, whether or not the game is hooked. The
|
||||
session summary shows the median and the peak, the Sessions tab has two new columns, the Trend and Compare have the
|
||||
memory metrics, the Sensors charts draw this game's memory beside the whole graphics card's and the whole PC's, and
|
||||
the Dashboard shows it live.
|
||||
- **Statistics per series**: every sensor's mean, median, minimum and peak, at the bottom of a session's summary.
|
||||
- **Documents are rendered**, not shown as raw text: the first-start documents, Help ▸ Limitations, the update notes,
|
||||
and a new **Help ▸ About** with the program's legal notices, the third-party licences and the legal documents.
|
||||
- **A user guide** — eight short pages, under **Help ▸ User guide**.
|
||||
- **The GPL is no longer something you accept**: it is your licence, shown for information. You accept the EULA (now
|
||||
1.5), the Disclaimer (2.10) and the Privacy Policy (2.6), so the first-start window opens once after the update.
|
||||
- Links to the project's documents open the version you run, not the newest one.
|
||||
- **The Logs page's Warning and Error filters show the Agent's lines** too; they showed only the App's.
|
||||
- **Settings no longer has "Record games launched outside FrameLedger"**: the switch never did anything.
|
||||
|
||||
**Updating from `0.1.0-beta.11`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0018 adds the memory columns; the database opens in place, and an older version cannot open it again.
|
||||
- Sessions recorded before this version have no memory figures and no per-series statistics: they read N/A, and the
|
||||
summary says so.
|
||||
- The new `FrameLedger.ProcessStats.dll` is installed beside the Agent; without it the memory figures read N/A.
|
||||
|
||||
### Added
|
||||
|
||||
- **The game's own memory, measured from outside the game, in every session** (owner decision D43, beta.12). A new
|
||||
C++ library loaded by the Agent — never into a game — `FrameLedger.ProcessStats.dll`, reads once a second the game
|
||||
process's **dedicated and shared GPU memory** (the documented `GPU Process Memory` performance counters, which need no
|
||||
handle to the game) and its **private working set, working set and commit** (`GetProcessMemoryInfo` with
|
||||
`PROCESS_QUERY_LIMITED_INFORMATION` only) — the numbers Task Manager's Details tab shows. A hooked game is read through
|
||||
the handle the session already holds; a game that is not measured (anti-cheat, hooking off) through a handle opened for
|
||||
the read and closed after it, the same least right the watcher already uses on every process, every process running its
|
||||
executable added up, a reused pid refused. Measured before it was written in (`spike-notes` §16): a 512 MiB allocation
|
||||
read +512.0 MiB, the private working set equals Windows' own counter, one read costs 0.1 ms, 600 reads leak nothing.
|
||||
Stored as five new sensor series and, in schema **0018**, the median / mean / peak columns
|
||||
(`game_vram_dedicated_*`, `game_ram_private_*`, …), the process count, the sources, and every sensor series'
|
||||
n / mean / median / min / max in `sensor_stats_json`; carried live to the Dashboard (`SessionProgress`, `SessionHeld`)
|
||||
and through the crash-recovery file (a new chunk type; beta.11's files still recover). The video-memory **budget** is
|
||||
still not measured (`20_OPEN_QUESTIONS` §M11). The App shows all of it (below).
|
||||
- **Sensor statistics have a median and a minimum** beside the mean and the maximum (`SeriesAggregates`).
|
||||
- **The App shows the game's own memory everywhere a session is** (D43, beta.12), in Task Manager's units — MB below
|
||||
1 GB, GB to two decimals, 1 GB = 1024 MB. The **session summary** has two new cards, *VRAM (this game)* and *RAM (this
|
||||
game)*: the median, with the peak (and the shared GPU memory's or the commit's peak) beneath, and a new table,
|
||||
**Statistics per series** — every series' mean, median, minimum, peak and number of readings, each in its own unit, as
|
||||
stored when the session ended. The **Sessions** tab has *VRAM (game)* and *RAM (game)* columns (median · peak, the rest
|
||||
in the tooltip); the **Trend** has *Median / Peak VRAM (game)* and *Median / Peak RAM (game)*; **Compare** has the same
|
||||
four rows; the **Sensors** charts draw *Video memory* (this game's dedicated and shared beside the whole graphics card's)
|
||||
and *Memory* (this game's private working set beside the whole PC's) in GB; the **live card** reads "This game: VRAM …
|
||||
· RAM …", for a game that is not measured too; and the CSV export has a `# game_memory:` header line. Where Windows does
|
||||
not report the private working set (before the September 2023 update) the working set is shown in its place and says
|
||||
so. A session recorded before beta.12 reads N/A, and its summary says the statistics table did not exist yet.
|
||||
- **Documents are shown rendered, not as raw Markdown** (owner request 4, beta.12): the Legal Gate, Help ▸ Limitations,
|
||||
the update notes and the new About window draw headings, lists, tables, code and links (Markdig 1.4.0, BSD-2-Clause;
|
||||
HTML in a document is shown as text and no image is fetched). The GPL is shown as written. Selectable and copyable;
|
||||
links open in the browser, scroll to a section, or open another document the window holds; a `file:` or
|
||||
`javascript:` link is never followed. **Help ▸ About** is a window with three tabs: the program's legal notices
|
||||
(copyright, no warranty, the licence with the NOTICE terms, this version's source code), the third-party licences
|
||||
with every shipped package's version and a button that opens the licences folder, and the legal documents (EULA,
|
||||
GPL, Disclaimer, Privacy Policy, NOTICE, Trademarks). Help ▸ Limitations is a window of its own.
|
||||
- **Links into the repository open the documents of the version you run**: a release stamps its tag into the App
|
||||
(`-p:FrameLedgerSourceRef`), so *View on GitHub*, the safety document and every document link go to that tag rather
|
||||
than to `main`, where the text may have changed since.
|
||||
- **A user guide** (owner decision D44, beta.12): eight short pages for players — install and first start, record a
|
||||
game, read your results, anti-cheat and safety, your data, questions and answers, and the terms in plain words — in
|
||||
the app under **Help ▸ User guide** (the first item of the Help menu) and in the repository's `guide/` folder. The
|
||||
README now opens with a pointer to it and keeps a separate section for developers and forks.
|
||||
- **`NOTICE`, and the licence header in every source file** (owner decision D45, beta.12). FrameLedger's own material is
|
||||
GPL-3.0-only with three additional terms of the kinds GPLv3 §7 permits: keep the copyright line and the attribution in
|
||||
the program's legal notices (b), mark a modified version as different and do not call it "FrameLedger" alone (c), and
|
||||
no trademark rights in the name (e). Section 7 wants such terms named in the source files themselves, so every
|
||||
first-party `.cs`, `.cpp`, `.h`, `.inl`, `.ps1` and `.xaml` file now opens with an `SPDX-License-Identifier:
|
||||
GPL-3.0-only` line and a line pointing at `NOTICE` (1,053 files; `src/native/third_party/` excluded). A new gate,
|
||||
`tools/notice-check.ps1` (six self-test cases, both directions; `-Fix` writes a missing header), keeps it true, and
|
||||
`tools/resx-gen.ps1` generates the string accessors with it. `NOTICE` ships in every package as
|
||||
`licenses\NOTICE.txt`, and `release.yml` refuses a published tree without it.
|
||||
- **For people who build, contribute or redistribute:** `CONTRIBUTING.md` (the gate, the definition of done, what will
|
||||
not be merged, and that a contribution is licensed GPL-3.0-only with the `NOTICE` terms — no CLA), `FORKING.md` (what
|
||||
the GPL asks of someone who distributes builds, and the names a fork must change so that it does not share
|
||||
FrameLedger's update feed, install folder, database, pipe, shared memory or Vulkan layer), `CODE_OF_CONDUCT.md` (the
|
||||
Contributor Covenant 2.1, adopted by reference) and `legal/TRADEMARKS.md` (third-party names, no affiliation, and how
|
||||
the name FrameLedger may be used).
|
||||
|
||||
### Changed
|
||||
|
||||
- **The GPL is no longer accepted at the first start** (owner decision D45): it is your licence to FrameLedger and is
|
||||
shown beside the documents for information — GPLv3 §9 needs no acceptance to run the program. **Accept** covers the
|
||||
End User License Agreement, the Disclaimer and the Privacy Policy; a row an earlier version wrote for the GPL stays,
|
||||
unread.
|
||||
- **The documents you accept change, and are shown again once:** **EULA 1.5** (an unmeasured session also records the
|
||||
game's own memory use; the GPL needs no acceptance; where the third-party notices are in an installed copy; your
|
||||
rights as a consumer that no agreement can limit, and severability), **Disclaimer 2.10** (what it reads about a game
|
||||
from outside it: the game's memory use, opened with the least access Windows offers; §2 names everything the thread
|
||||
it runs inside the game does, which it understated; the maintainers' preface moves to
|
||||
`docs/legal-drift-history.md`), **Privacy Policy 2.6** (the game's memory use, replacing a video-memory figure the
|
||||
software never read; a new §3A on what an export or a bug report can carry about you before you share it; the version
|
||||
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
|
||||
successful sessions — the rule until beta.11 (D38) made them a trial — and its feature list promised "per-process VRAM
|
||||
and whether the driver was exceeding its budget"; both now say what the software does. The tier tooltip names the
|
||||
game's memory beside the duration and the sensors.
|
||||
- **The Legal Gate showed the documents as raw Markdown** (`**bold**`, `| --- |`) in a text box, and Help ▸ Limitations
|
||||
and the update notes the same; they are rendered now (above). The Legal Gate's *View on GitHub* went around the App's
|
||||
link opener; it goes through it.
|
||||
- **The third-party notices' component table did not render as a table** in a Markdown renderer that follows the spec
|
||||
strictly: a note line sat between its rows. The note is moved below the table, unchanged.
|
||||
- **"Max VRAM (game)" on the Trend never had a point, the live card's VRAM was always empty, and the Sensors chart's
|
||||
"VRAM used by this game" line was never drawn**: all three read the Overlay's in-game per-present figure, which nothing
|
||||
ever produced. They read the game's memory measured from outside it now (above), and the CSV's note no longer calls
|
||||
the always-empty `vram_mb` column "a held 1 Hz sample".
|
||||
- **"Avg RAM in use" on the Trend is labelled as the whole PC's**, in GB like every other memory figure, so it is not
|
||||
read as the game's.
|
||||
- **A licence header written by a contributor no longer has to name poli0981**: `tools/notice-check.ps1` accepts any
|
||||
holder and year in the same form (`Copyright (C) <year> <holder> - additional terms under GPLv3 section 7: see NOTICE`),
|
||||
and `CONTRIBUTING.md` says so; seven self-test cases.
|
||||
- **Documents that described a per-process VRAM figure the Overlay never produced** are corrected in place
|
||||
(`03_METRICS`, `17_HOOK_ENGINE`, `18_GPU_VENDOR_APIS`, `20_OPEN_QUESTIONS` §M7/§H10), and the two that said an unmeasured
|
||||
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`.
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.13] - 2026-10-04
|
||||
|
||||
**The thirteenth pre-release: refusal notices that say where the anti-cheat is, GPU sensors that follow the game's graphics
|
||||
card, and smaller updates.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run
|
||||
anyway*. What changed for a user:
|
||||
|
||||
- **An anti-cheat driver or service running on the PC is said as that.** While, for example, Easy Anti-Cheat's service
|
||||
runs for another game, FrameLedger hooks no game at all; the notice used to say the anti-cheat "was detected in this
|
||||
game", naming a game that may not even use it. It now says the anti-cheat is running on this PC, and the session's
|
||||
summary says the same. A finding in the game itself still says "in this game".
|
||||
- **The notice for a capture stopped mid-game** no longer promises that FrameLedger will hook the game again "when you
|
||||
enable it again" — which was not true either way. It says where the anti-cheat was found and whether hooking was
|
||||
turned off.
|
||||
- **On a PC with more than one graphics card**, the GPU figures follow the card the game draws on once it has shown its
|
||||
first frame, instead of the first card Windows lists (often a laptop's integrated GPU). Not yet tested on such a PC.
|
||||
- **Updates download only what changed**: this release carries a delta package against `0.1.0-beta.12`, so updating
|
||||
from it through the App downloads a fraction of the full ~107 MB.
|
||||
|
||||
**Updating from `0.1.0-beta.12`:**
|
||||
|
||||
- Help ▸ Check for updates downloads the delta; or quit the App (tray icon → Exit), end `FrameLedger.Agent.exe` and
|
||||
run the installer as before.
|
||||
- No database change, and no document to accept again.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A refusal because of a driver or service said the anti-cheat "was detected in this game".** The guard's checks for
|
||||
drivers and services are machine-wide: while Easy Anti-Cheat's service runs for another title, every game is refused,
|
||||
and the notice named a game the user may not even own. It now says the anti-cheat is running on this PC — a driver or
|
||||
service that may belong to another game or program — and the session summary says the same; a finding in the game
|
||||
itself still says "in this game" (`20_OPEN_QUESTIONS` §S23-3, closed). The Agent's refusal and unhook events carry the
|
||||
guard's own reason for this (`guardReason`, additive).
|
||||
- **The notice for a mid-session stop promised "FrameLedger will not inject into this game again until you enable it
|
||||
again"**, untrue both ways since beta.5: a driver or service that starts on the PC turns no hooking off, and a finding
|
||||
in the game turns it off for good. It says where the finding was, and whether hooking was turned off.
|
||||
- **On a PC with more than one graphics card, the GPU sensors could describe a card the game was not using.** The
|
||||
adapter the game draws on is now followed once it has shown its first frame: the DXGI layer switches to it,
|
||||
LibreHardwareMonitor reads that brand's GPU rather than the first one it lists (often a laptop's integrated GPU), and
|
||||
NVAPI says nothing when the game runs on an AMD or Intel card — N/A rather than another card's temperature.
|
||||
`LIMITATIONS.md` says what still describes the first card.
|
||||
- **Updates download only what changed**, from this release on: each release now carries a Velopack delta package
|
||||
against the previous one beside the full package, and an installed copy one release behind downloads the delta. No
|
||||
earlier release had one — every update so far downloaded the whole ~107 MB package — so the first update that can use
|
||||
a delta is from `0.1.0-beta.12` to this one; Velopack falls back to the full package whenever the delta does not apply.
|
||||
- **Tests that change the App's language ran beside tests that read its text**, so the second kind could read the
|
||||
wrong language once in many runs; the language-changing tests now run on their own.
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.14] - 2026-10-06
|
||||
|
||||
**The fourteenth pre-release: a wheel that scrolls, updates that find this channel and wait for your games, crashes told
|
||||
apart from memory reports, and new measurements.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The mouse wheel scrolls every page, dialog and chart**; over a chart the wheel scrolls the page and **Ctrl+wheel**
|
||||
zooms the chart. **Settings ▸ Window ▸ Hide scroll bars** draws no bar and still scrolls. The import list is readable
|
||||
in the dark theme.
|
||||
- **Updates come from the channel of the copy you run** — a beta looks for betas — and are never applied on their own
|
||||
when the App starts; restarting to update waits while a game FrameLedger measured is still running, and says so.
|
||||
- **A game that crashed reads *crashed*, and only then**: a Windows memory report about a game no longer counts as a
|
||||
crash, and an Unreal Engine game that opens its crash reporter and closes is recorded as crashed, the reporter named.
|
||||
- **A game starting up or closing during FrameLedger's anti-cheat check** is read again once instead of refused, and a
|
||||
check that could not read a game that had already closed ends the session as the game's own exit.
|
||||
- **New in every session's summary**: time below 30 and 60 FPS and below the monitor's refresh rate, how even the frames
|
||||
were, VSync and tearing, the graphics card's clocks, fan and memory temperature, how much of the time its power limit
|
||||
or heat held it back (NVIDIA), frames per watt, and a render scale chart. Trend and Compare have them too.
|
||||
- **FrameLedger's own programs say what they are** in Explorer and Task Manager (*FrameLedger Agent*).
|
||||
|
||||
**Updating from `0.1.0-beta.13`:**
|
||||
|
||||
1. **First choose *Beta* in Settings ▸ Updates.** beta.13 looks for stable releases by default, and every release so far
|
||||
is a pre-release, so it finds nothing until you do. From beta.14 on the channel follows the copy you run.
|
||||
2. **Update with no game running.** beta.13 still applies a downloaded update the next time the App starts, stopping the
|
||||
Agent to do it; beta.14 no longer does.
|
||||
3. **The database is migrated in place** (schema 0019, new columns only). An earlier version cannot open it afterwards.
|
||||
4. Sessions already stored keep their status — a few may still read *crashed* because Windows logged a memory report
|
||||
about the game. The Privacy Policy (version 2.7) is shown once for you to accept.
|
||||
|
||||
### Added
|
||||
|
||||
- **Settings ▸ Window ▸ Hide scroll bars.** No scroll bar is drawn anywhere in the app while it is on, and everything
|
||||
still scrolls with the mouse wheel, the keyboard and touch. Off by default; it applies at once, to the open windows
|
||||
too, and off brings every bar back.
|
||||
- **New measurements in every session** (recorded from this version on; earlier sessions read N/A):
|
||||
- **time below 30 FPS, below 60 FPS and below the monitor's refresh rate**, and how much one frame's time differs from
|
||||
the next. A game held at its frame limit is not counted as dropping below it for the small wobble every frame limit
|
||||
has — on the developer's machine a game capped at 60 read half its time "below 60" by the plain rule;
|
||||
- **VSync and tearing**: how many of the game's frames asked to wait for the display, and how many allowed tearing
|
||||
(Direct3D games);
|
||||
- **the graphics card's clock speeds, fan speed and memory temperature**, and — on NVIDIA cards — how much of the time
|
||||
its power limit or its temperature held it back;
|
||||
- **frames per watt**: the game's own frames per second for each watt the graphics card drew, never counting generated
|
||||
frames.
|
||||
|
||||
The session's sensor statistics table shows the new card readings in their own units. The database is migrated in
|
||||
place (schema 0019), and an earlier version cannot open it afterwards.
|
||||
- **Where the new measurements are shown:** the session summary has a card for each (the 1% low card also shows the
|
||||
displayed frames' 1% low when frame generation was counted, beside the game's own), a **Render scale** chart — the
|
||||
share of the screen's resolution the game rendered at, over the session — and a **Clocks and fan** chart under
|
||||
Sensors, with the moments the card was held back shaded; the card's memory temperature joins the temperatures chart.
|
||||
A game's **Trend** has nine more metrics and **Compare** nine more rows, where a figure taken over presents says
|
||||
*(presented)* beside one taken over the game's own frames. The **Latency** tab is shown only for a game with a session
|
||||
that measured latency — none does yet.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A session could read "crashed" when the game had not crashed, and an Unreal game's crash read "ended normally".**
|
||||
Any Windows report that named the game counted as a crash — on the developer's machine a memory-leak report Windows
|
||||
writes about large games marked an ordinary The Witcher 3 session *crashed*; hang reports and another program whose
|
||||
name contains the game's would have done the same. Only a crash report of this game's own process counts now. And
|
||||
Unreal Engine games handle their own crash: they open their crash reporter and exit with code 3, which said nothing;
|
||||
FrameLedger now sees the crash reporter a game starts (Unreal's, CD PROJEKT RED's, Capcom's, BugSplat's) and records
|
||||
the session as crashed when the game exits within a minute of it — the summary names the reporter. Unity's and
|
||||
Chromium's crash handlers start with their game and are never taken for a crash. Sessions already stored keep their
|
||||
status. BugSplat's sender (Kingdom Come: Deliverance II) can no longer be picked as a game's executable by the import.
|
||||
The Privacy Policy (2.7) now says that FrameLedger reads Windows' crash reports and the names of programs a game starts.
|
||||
- **A game that exited as FrameLedger's anti-cheat check ran could be recorded as "unhooked (safety)"** — and, under a
|
||||
user-mode anti-cheat exception, end the exception's trial for good. The check reads every process in the game's
|
||||
tree every 30 s; one that was just starting (an engine's crash reporter as its game dies, any helper the game launched
|
||||
a moment before) or already gone could not be read, and the check refused. Such a process is now read once more a
|
||||
quarter of a second later, and refused only if it is still unreadable (a protected process never gets the second
|
||||
look). And when the check could not read and the game itself has exited, the session ends as that exit, normal or
|
||||
crashed by its exit code. Anything the check *finds* is a refusal exactly as before (owner decision D48).
|
||||
- **An installed copy never found an update unless you had changed its channel.** The update channel was *Stable* by
|
||||
default and every FrameLedger release so far is a pre-release, so the check found nothing. The channel is now
|
||||
*Automatic*: a pre-release looks for pre-releases and a release for releases; choosing *Stable* or *Beta* still decides.
|
||||
- **A downloaded update was applied the next time FrameLedger started, before anything could check for a running game.**
|
||||
The update library applies a waiting package at start unless told not to, and nothing told it: it stopped the capture
|
||||
agent mid-session instead of letting it finish. The App now offers such a package as *Restart to update*, which waits
|
||||
for the session to end and stops the agent properly, as it always did for a download in the same run.
|
||||
- **The update dialog said ~102 MB when the download was the 1.6 MB delta.** It now says the delta's size and names the
|
||||
full package as the fallback; the updater's own lines are in the App's log, so a full download shows there.
|
||||
- **Restart to update could fail half way** when a game FrameLedger had measured was still running — its loaded overlay
|
||||
cannot be replaced — or when an agent was still waiting on the administrator prompt, and it gave the agent 10 s to stop
|
||||
where the agent takes up to 15. It waits for all three now and says why. A full disk no longer reads as "offline",
|
||||
and uninstalling removes the *Start FrameLedger with Windows* entry.
|
||||
- **The import list was unreadable in the dark theme.** File ▸ Import library (and Games ▸ Refresh) drew every row white
|
||||
with white text, and each tick box as a sliver at the row's edge: a row style added in beta.11 to dim the games already
|
||||
in the library fell through to Windows' own row, which is white in every theme, and WPF UI's check box is too wide for
|
||||
its 40 px column. The rows take the theme's colours again and the boxes are whole, and the list is the one thing in the
|
||||
dialog that scrolls — its intro and the count under it stay in view, where a list scrolling inside a scrolling dialog
|
||||
used to carry the intro away. Compare's session picker draws the theme's check boxes too (it drew Windows' old ones).
|
||||
- **The mouse wheel scrolled nothing on the Dashboard, Games, a game's page, Compare and Settings** — only dragging the
|
||||
scroll bar did. WPF UI wraps a page in a scroller of its own unless the page says otherwise, and inside it each page's
|
||||
own scroller had nothing to scroll and still took every wheel. Every page scrolls itself now. The Logs page had the same
|
||||
cause: its tail grew to hold every line and never followed the newest one, as it was meant to. A scroller inside a
|
||||
dialog (the consent, administrator, anti-cheat exception and bug report dialogs) hands the wheel on at its ends.
|
||||
- **The chart-wheel test read the real keyboard** (developers): a Ctrl held anywhere on the machine while the test ran
|
||||
turned its plain wheel into a zoom, and a local gate went red once. The keys held are now the test's own input, and the
|
||||
Ctrl+wheel half is driven end to end as well.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Over a chart, the wheel scrolls the page; Ctrl+wheel zooms the chart.** ScottPlot zoomed on every wheel, which with
|
||||
the pages scrolling again would have zoomed the chart and scrolled the page at once. Dragging still pans and
|
||||
double-click still resets.
|
||||
- **FrameLedger's own programs say what they are.** In Explorer (*Properties ▸ Details*) `FrameLedger.exe` and
|
||||
`FrameLedger.Agent.exe` now name the product, the author's copyright and what each one does, as the native DLLs always
|
||||
have; Task Manager lists the background service as *FrameLedger Agent* rather than *FrameLedger.Agent*. Until this
|
||||
release the Agent called its company and product "FrameLedger.Agent" and no managed file carried a copyright. The
|
||||
release check now reads both kinds of file and fails when one of them does not name FrameLedger or carries a different
|
||||
copyright line.
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.15] - 2026-10-06
|
||||
|
||||
**The fifteenth pre-release: a quick restart recorded, an anti-cheat check that stays on the game's own programs, a
|
||||
change of language that reaches every list, and a launcher followed to its game.** The same unsigned installer: verify
|
||||
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **A game started again a few seconds after closing is recorded** — while the session before it was being saved, the
|
||||
new start used to be turned away and never looked at again.
|
||||
- **The anti-cheat check stays on the game's own programs.** Windows reuses process numbers, and a program that had
|
||||
taken over the number of a game's closed launcher could be scanned as part of the game — refusing the session, or
|
||||
turning the game's measuring off. It no longer is.
|
||||
- **A change of language reaches every list at once** — the theme and update-channel lists, the Logs page, the Games
|
||||
sort order, the tray's menu and the Agent's status — without a restart.
|
||||
- **A game started through its launcher is followed to the game itself** (the Agent's console `launch`).
|
||||
- **`FrameLedger.exe --data-dir <folder>` opens a copy of a data folder to look at**, with no Agent and nothing on the PC
|
||||
changed.
|
||||
|
||||
**Updating from `0.1.0-beta.14`:** Help ▸ Check for updates, then *Restart to update* with no game running — FrameLedger
|
||||
stops its Agent before the update is applied. Nothing in the database changes and nothing is shown again for you to
|
||||
accept; sessions already stored keep their status.
|
||||
|
||||
### Added
|
||||
|
||||
- **`FrameLedger.exe --data-dir <folder>` opens a copy of a data folder to look at**, for checking a build of your own
|
||||
against real data without touching your own. Such a window starts and contacts no Agent, records nothing and changes
|
||||
nothing on the PC — the controls that would are disabled, and a banner says whose data it shows. It refuses
|
||||
FrameLedger's own folder.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The anti-cheat check could scan a program that had nothing to do with the game**: Windows reuses process numbers, and
|
||||
once a game's launcher had closed, the check followed its number to whatever program held it now — a protected one
|
||||
refused the session, one carrying anti-cheat turned the game's measuring off for good. A program started after the game
|
||||
is no longer taken for its launcher, nor one started before the game for its child; when FrameLedger cannot read when a
|
||||
program started, it still scans it, as before.
|
||||
- **A game started again within a few seconds of closing was not recorded**: while FrameLedger was still saving the
|
||||
session that had just ended, the new start was turned away ("one session at a time") and never looked at again. It is
|
||||
recorded now, as soon as the session before it is saved — unless the game's other processes are still running beside
|
||||
it, as a multi-process game's helpers are.
|
||||
- **A game started through its launcher was never followed to the game itself** (the Agent's `--console launch`): when
|
||||
the launcher exited or never drew a frame, FrameLedger was to find the game the launcher had started and record it, and
|
||||
it never did — the launcher's process id was not passed on, so the search stopped before it began. It is passed on now,
|
||||
and a launch that ends without one says so in the log.
|
||||
- **After a change of language some text stayed in the old one** until FrameLedger restarted: the theme and update-channel
|
||||
lists in Settings, the log and level lists on the Logs page, the sort order on the Games page, the tray icon's menu and
|
||||
the Agent's status in the title bar. They follow the language at once now.
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.16] - 2026-10-06
|
||||
|
||||
**The sixteenth pre-release: nothing changes in the app.** It is 0.1.0-beta.15 as the owner verified it on real hardware
|
||||
the same day, with the developers' end-to-end tests made reliable. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.15`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
|
||||
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Development: the Agent's and the capture host's end-to-end tests no longer fail when another test project starts
|
||||
the test harness at the same moment.** Each such suite now records into a copy of the harness under a name of its
|
||||
own, so the target it asks for is never ambiguous (`14_TESTING`). Nothing in the app changes.
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.17] - 2026-10-07
|
||||
|
||||
**The seventeenth pre-release: text that keeps up with a change of theme, scroll bars hidden everywhere when you ask, a
|
||||
user guide that answers more, and a wiki.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
|
||||
*More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.16`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
|
||||
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Text keeps up with a change of theme.** After switching between Light and Dark, the descriptions and captions of the
|
||||
page in view — Settings above all, where the theme is chosen — kept the old theme's colour: light grey on white, or dark
|
||||
grey on dark. Every such text now follows the switch, on every page, window and dialog (`08_UI` §Contrast,
|
||||
`16_WPFUI_SYNTAX` §Gotchas).
|
||||
- **Hide scroll bars hides every scroll bar.** With Settings ▸ Window ▸ Hide scroll bars on, the Dashboard still drew its
|
||||
scroll bar — and so did the first run, About, the user guide and a game's wide sessions table; only screens with a
|
||||
switch or a tick box on them lost theirs. Every scroller follows the option now, and still scrolls with the wheel, the
|
||||
keyboard and touch (`08_UI` §Settings, `16_WPFUI_SYNTAX` §Gotchas).
|
||||
- **The first run names the right place to import your library.** Its last step said *File ▸ Import library… on the
|
||||
Games page*; File is the main window's menu, and the Games page has no such button. In Vietnamese it now names the menu
|
||||
as it is shown (*Tệp*).
|
||||
|
||||
### Added
|
||||
|
||||
- **The user guide looks things up too.** Four pages join it, in Help ▸ User guide: *The screens* (every page, menu,
|
||||
button and shortcut), *Every setting* (what each one does and its default), *When something goes wrong* (what you see,
|
||||
what it means, what to do) and *Words FrameLedger uses*. Tests now fail when a setting or a menu item is added without
|
||||
its line in the guide, or a link names a section that does not exist.
|
||||
- **A wiki.** The project's [wiki](https://github.com/poli0981/frameledger/wiki) has two halves: the user guide, the
|
||||
same pages the app shows, and short pages for developers — the architecture, the repository, building and testing,
|
||||
the rules every change keeps, capture, metrics, data, the app's UI and releasing — each linking to its full document.
|
||||
It is published from the repository whenever a release is made (`wiki.yml`), so it always matches the newest
|
||||
release, and `./build.ps1 check` fails on any link in it that leads nowhere (`13_CI_CD` §wiki.yml).
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.18] - 2026-10-07
|
||||
|
||||
**The eighteenth pre-release: every page readable in the dark theme, notices that say what happened in words, and a
|
||||
release whose build no longer calls itself dirty.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.17`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
|
||||
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Page titles and section headings read in the dark theme again.** Every page's title and its section headings — Dashboard,
|
||||
Recent sessions, Games, Compare, Settings and each of its groups, Logs — were drawn near-black on the dark window
|
||||
(owner's screenshots of beta.17; beta.16 had it too). A page is shown in WPF UI's navigation Frame, which passes no text
|
||||
colour into the page, and a text that sets none is black; a page open during a theme switch picked the right colour up,
|
||||
and the next one navigated to did not. Every page now sets the theme's text colour itself. `AccessibilityTests.EveryPageSetsItsOwnTextColour`
|
||||
and `PagesLoadTests.EveryTextIsReadableInBothThemes` (every surface hosted as the App hosts it, ≥ 3:1 in both themes)
|
||||
went red on the unfixed pages first; the theme-switch check now hosts pages in the Frame too, and its harness derives the
|
||||
accent for each theme as the App does (`docs/08_UI.md` §Contrast, `docs/16_WPFUI_SYNTAX.md` §Gotchas, `docs/14_TESTING.md`).
|
||||
- **Every notice says what happened in words.** With *Disable all hooking* on, a game's notice read "kill switch was
|
||||
detected in this game (the global 'disable all hooking' switch is on (FR-2.4); …)" — it reads "All hooking is switched
|
||||
off in Settings, so nothing was measured." now, and a game blocked before reads as that, not as a finding. A refusal no
|
||||
anti-cheat names read "… reason RefusedByGuard." and is said in the guard's words ("the game is 32-bit, and the hook
|
||||
runs in 64-bit games only"); the agent sends the guard's reason for every refusal (`docs/07_IPC.md`). A safety re-scan
|
||||
that could not look while the game ran read "Access is denied. was detected" and says the check could not be made. And
|
||||
*Measurement stopped* printed "The hook stopped (WriterSelfDisabled); the session continues without measuring." — it
|
||||
says why in a sentence, and no longer that the session went on: a stop ends it. `NoticesFromTheAgentTests` builds the
|
||||
agent's own events for every refusal and every stop and went red with each text above (`docs/08_UI.md` §Notifications policy).
|
||||
- **Disable all hooking says when it applies.** Turning it on said "The capture agent reads it at the next session start";
|
||||
a game being measured stops at its next safety scan, within 30 seconds, and the message says so.
|
||||
- **Turning hooking off with no agent says nothing changed** — Settings' *Turn off*, the game page's switch and a
|
||||
withdrawn exception said "Nothing was enabled.", the enabling path's words.
|
||||
- **A viewer over a copy leaves every agent setting alone.** The user-mode exception option, the three Recording numbers
|
||||
and the update channel stayed live in `--data-dir`, where no agent reads them (`ViewerModeTests`).
|
||||
- `docs/08_UI.md` listed a "PawnIO missing" banner that was never built; struck, with the banners that do exist.
|
||||
- **A release's overlay build no longer calls itself dirty.** The Dashboard read *Overlay build v0.1.0-beta.17-dirty* (and
|
||||
beta.16's, and every release's before): the release workflow writes the release date into the legal documents before
|
||||
the build, and the build id was read from the tree after that. It is read from the clean checkout first and handed to
|
||||
the build, and `tools/buildid-check.ps1` reads it back out of the published binaries (`docs/12_BUILD.md` §Release-time
|
||||
token substitution). Nothing changes for a game: both sides of the ring's handshake always carried the same id.
|
||||
- **Two end-to-end tests no longer fail CI by a race** (developers only). The Vulkan launch test asks the test harness
|
||||
whether this machine can present through Vulkan before it starts the capture host: on GitHub's runners the harness's
|
||||
own "skip" line never reached the host's output, and a scan of the exiting harness failed the test instead of skipping
|
||||
it. The target-exit test holds its harness 15 seconds instead of 6, the margin a slow runner's host needed
|
||||
(`docs/13_CI_CD.md`).
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.19] - 2026-10-12
|
||||
|
||||
**The nineteenth pre-release: an imported game that is its own runtime and not a helper, Change executable… in the game's
|
||||
folder, the engine version of Unity, Godot and RPG Maker games, and games you uninstalled leaving the library by
|
||||
themselves.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.18`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
|
||||
Policy (2.8) is shown once for you to accept. Every game is read once more for its engine (detection rules `2026.10.2`).
|
||||
The agent removes the entries of games you uninstalled that have no sessions, about ten minutes after it sees them gone —
|
||||
turn **Settings ▸ Data ▸ Remove uninstalled games** off first if you want them kept. An entry an earlier import made for a
|
||||
helper is not changed: re-point it with *Change executable…*.
|
||||
|
||||
### Added
|
||||
|
||||
- **The engine version of Unity, Godot and RPG Maker games**, as Unreal Engine's has been shown since beta.10 — on the game's
|
||||
page with what it was read from, and the maker on the library card too: *Unity 2022.3.39f1* (from the player library,
|
||||
else its data file; a game whose data file is encrypted reads without the release letter, *2019.4.40*), *Godot 4.4.1*
|
||||
(from its data pack), *RPG Maker MZ 1.10.0* and *MV 1.6.2* (from the core script), *RPG Maker VX Ace (RGSS 3.0.1)*
|
||||
(from the runtime library its `Game.ini` names — that number is the library's, not the editor's). A Unity version used
|
||||
to read as its library's build number (`2022.3.39.5118735`), and a Godot one was never found. Every game is read once
|
||||
more after the update (detection rules `2026.10.2`). RPG Maker 2000/2003 is not recognised (`docs/05_DETECTION.md`
|
||||
§Engine version — Unity, Godot, RPG Maker).
|
||||
- **The Privacy Policy (version 2.8)** names the files those versions are read from, and two that were already read and
|
||||
never named (Unity's player library and an RPG Maker game's title); it is shown once for you to accept.
|
||||
- **A game you uninstalled leaves the library by itself** when it has no sessions: the agent removes an entry whose `.exe`
|
||||
has been gone for ten minutes, if its drive is connected and the folder it was installed in is still there — an
|
||||
unplugged or re-lettered drive never counts — and never one where anti-cheat was found. A game with sessions stays, with
|
||||
them, and reads *Not installed* as before. The Games page says so when it happens — once, naming them, for all the games
|
||||
one check removes; **Settings ▸ Data ▸ Remove uninstalled games** turns it off (`docs/02_SPEC.md` FR-1.8).
|
||||
|
||||
### Changed
|
||||
|
||||
- **Change executable… opens in the game's own folder** — the install folder a store made (`steamapps\common\<game>`
|
||||
and the like), or above an Unreal game's `Binaries\Win64`, else the folder the executable is in — instead of wherever
|
||||
the last file dialog was. For a game whose folder is gone it opens at the nearest folder still there
|
||||
(`docs/08_UI.md` §Games).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An imported game is no longer one of its helpers, and an RPG Maker MV/MZ game behind a launcher is its runtime.**
|
||||
A Doll's Locket - Remake (itch) was added as `notification_helper.exe`, NW.js's notification helper, because the itch
|
||||
app's own record named only that file (it leaves out a launcher that asks for administrator and anything a folder
|
||||
deeper) and the import took it as the game. A helper named by the store is skipped now and the executable is guessed —
|
||||
the import list says so — and the guess takes the executable beside NW.js's `nw.dll` and `package.json`, the process
|
||||
that draws (`css\Game.exe` there; its launcher asks for administrator, so it is measured with *Run the agent as
|
||||
administrator* on — *withdrawn 2026-10-13: that launcher is malware, do not run it; [0.1.0-beta.21]'s Security*). The
|
||||
import also no longer offers a store's game again when the library has it at another
|
||||
executable: an entry already there is re-pointed with *Change executable…* (`docs/05_DETECTION.md` §Library import).
|
||||
- **The Games page shows its newest read of the library.** When two reads overlapped — a session ending while an import
|
||||
added games — the one that started first could finish last and be shown, an older list until the next read.
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.2] - 2026-09-17
|
||||
|
||||
**The second pre-release.** The same unsigned installer as `0.1.0-beta.1`: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user: a finished session whose frame generation
|
||||
did not stay in one state — a menu, a loading screen — now shows the factor of its steady state with the share of
|
||||
the session it covers, where `0.1.0-beta.1` showed "factor not counted" for most real sessions; and three faults from
|
||||
the first day of use are fixed: an App started as administrator started another Agent every few seconds, and each of
|
||||
them recorded every game; closing the App ended in an error; and a crash dump could hang the process it described.
|
||||
|
||||
**Updating from `0.1.0-beta.1`:**
|
||||
|
||||
- **Quit the App (tray icon → Exit), then end every `FrameLedger.Agent.exe` in Task Manager before installing.** If the
|
||||
App was ever started as administrator, some Agents run elevated, and Task Manager can end those only when it runs
|
||||
as administrator itself.
|
||||
- On its first start the ledger migrates to schema 6. Sessions recorded before keep the frame-generation result they
|
||||
were stored with; the steady state applies to sessions recorded from this version on.
|
||||
- Sessions recorded while more than one Agent was running appear once per Agent. Nothing removes them automatically.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Closing the App no longer ends in a Fatal error and exit code 1 (2026-09-17).** Measured on the installed
|
||||
0.1.0-beta.1: `ui-*.log` recorded `ui: the run ended in an exception` — "the calling thread cannot access this object
|
||||
because a different thread owns it" — from `TrayHost.Dispose` on every close after an update check. The App waited
|
||||
with `WaitForShutdownAsync`, which resumes on the thread pool and stops the hosted services there, so the tray icon (a
|
||||
WPF object whose disposal unsubscribes `Application.Exit`) was removed off its thread; `TearDownAsync` then stopped every
|
||||
service a second time. The App now waits for the stop request on the dispatcher and stops the host once, from the UI
|
||||
thread, and `TrayHost.Dispose` marshals to the icon's own dispatcher from any thread (bounded at 5 s; skipped when the
|
||||
dispatcher has already shut down). Test: `TrayHostTests` disposes a real tray icon from a pool thread while the UI
|
||||
thread pumps — red on the old code with that exception, green now; skipped where the session has no notification area.
|
||||
|
||||
- **A crash dump can no longer hang the process it describes, and the test suite no longer freezes (2026-09-17).**
|
||||
`FrameLedger.Infrastructure.Tests` hung about one run in eight — it cancelled the first tag's release run after 58
|
||||
minutes — and the verbose reporter of a hung run showed thirteen tests started and none finished, one of them
|
||||
`CrashDumpWriterTests.WritesAMinidumpOfThisProcess…`. That test, and the product's crash path in the App and the Agent,
|
||||
called `MiniDumpWriteDump` on the calling process, which suspends every other thread of it; one holding the heap or
|
||||
loader lock deadlocks the dumper, and the whole process freezes with it. Forty runs without the test: no hang. The dump
|
||||
is written by a child now: `CrashDumpWriter.TryWrite` starts `FrameLedger.Agent.exe --write-crash-dump <file>` and waits
|
||||
up to 30 s, and the helper (`Infrastructure.Diagnostics.ParentDump`) dumps its parent with the same flags — it takes no
|
||||
pid and refuses unless the parent is still running, started before it and sits in the helper's own directory, so it can
|
||||
only ever read the App or the Agent (CLAUDE.md rule 4). Forty runs of the suite with the new tests: no hang.
|
||||
`--blame-hang` (#196) did not stop the hung xUnit v3 executable, so `build.ps1` runs `dotnet test` under a 25-minute
|
||||
wall-clock limit, kills the tree on expiry and names the test projects that wrote no `results.trx`. Tests:
|
||||
`ParentDumpTests` (a real minidump of another process; which parent is ours), `CrashDumpWriterTests` (a failing and a
|
||||
missing dumper), `CrashDumpHelperTests` (the shipped Agent dumps the test process from outside; it refuses a parent
|
||||
from System32; the flag's surface). Docs: `10_LOGGING` §Crash handling, `12_BUILD` Agent flags, `13_CI_CD` tally.
|
||||
**A hang in one test process no longer fails the others.** The migration mutex was one name for every ledger
|
||||
(`Local\FrameLedger.Ledger.Migrate`), so a suite frozen mid-migration held every other process's scratch ledger: on
|
||||
#199's run `Infrastructure.Tests` hung and seven App and Agent tests failed after 30 s with "another process has been
|
||||
migrating the ledger". It is the file's now (`MigrationRunner.LockNameFor`; `MigrationLockTests`; `06_DATA_MODEL`
|
||||
§Migrations). And a failed dump names dbghelp's error instead of 0: CsWin32 declares `MiniDumpWriteDump` without
|
||||
`SetLastError`, so the code is read with `GetLastSystemError` (`ParentDumpTests`: an exited process).
|
||||
|
||||
- **One Agent per data folder: an App started as administrator no longer starts an Agent per connect round
|
||||
(2026-09-17).** On the owner's machine the installed 0.1.0-beta.1 ran four `FrameLedger.Agent.exe --serve`: the App
|
||||
opened at 10:04 was elevated, the pipe of the Agent already serving refused it, and it took the refusal for an absent
|
||||
Agent and started three more, elevated like itself, 17 seconds apart. Nothing in the Agent noticed the first — the
|
||||
single instance `01_ARCHITECTURE` §Lifecycle specified was never built — so every game launched in the next hour was
|
||||
injected, read and recorded by all four (four copies of each session, equal frame counts), and the three extras
|
||||
logged "accept failed" every 260 ms for four hours. The cause of the refusal: `PipeOptions.CurrentUserOnly` compares
|
||||
the pipe's owner with the client token's default *owner*, which an elevated token sets to Administrators (the elevated
|
||||
Agents' log files are owned by Administrators, measured), not with its *user*.
|
||||
- `Infrastructure.Startup.AgentInstanceLock`: a named mutex per data folder, claimed by `--serve` and the console's
|
||||
`capture` / `launch` / `recover` before logging, rules and the ledger; a second process exits **10** with one line.
|
||||
- The App starts an Agent only when no process holds the folder and the one it started last has exited; it logs why a
|
||||
connect failed, once per reason, and the exit code of the Agent it started.
|
||||
- The pipe states its owner (`O:<user>` in the SDDL) and the client checks the owner against its token user
|
||||
(`PipeAccessControl.RequireOwnedByCurrentUser`), so an elevated App and an unelevated Agent reach each other in both
|
||||
directions.
|
||||
- A pipe instance that cannot be created backs off 250 ms → 10 s and is logged with its Win32 error, once per streak
|
||||
(CsWin32 declares `CreateNamedPipeW` without `SetLastError`; the error is read with `GetLastSystemError`).
|
||||
- Tests: `AgentInstanceLockTests`, `OneAgentPerDataFolderTests` (the shipped binary against a claimed scratch folder),
|
||||
`AgentConnectionTests` (an Agent that is up and does not answer is never started again; the real launcher sees the
|
||||
claim), `PipeServerClientTests` (the owner; an Administrators-owning token trusts its user's pipe and refuses an
|
||||
Administrators one — on CI's elevated runner; the backoff logs once with error 231). Docs: `01_ARCHITECTURE`
|
||||
§Lifecycle, `07_IPC` §C and §Client behavior, `08_UI`, `12_BUILD`, `20_OPEN_QUESTIONS` §G.
|
||||
|
||||
### Added
|
||||
|
||||
- **A session whose frame-generation state changed publishes its steady state, with its share (2026-09-17, owner
|
||||
decision — `03_METRICS` §The steady state).** The owner saw the live card show the FG factor all session and the
|
||||
finished session show "factor not counted" most of the time, and suspected the path from the hook to the UI. The
|
||||
path is whole: the stored per-frame counts of all nine hooked sessions of 2026-09-16 read 2.00 / 3.00 / 4.00 inside
|
||||
gameplay. The live card looks at five seconds; the stored row looked at the whole session, split it in eight and
|
||||
refused it when one bucket departed — and every real session opens with a splash, a menu or a loading screen, so
|
||||
one session in nine published. The refusal is right (Wukong's session averages to 2.22; its gameplay ran ×4.1) and
|
||||
stays; what changes is that the gameplay's number is no longer thrown away with the average.
|
||||
`Domain.Metrics.FgSteadyState`: five-second windows (the live card's own), the ACTIVE windows agreeing within 10 %
|
||||
that hold the most time, published at ≥ 10 s and ≥ 10 % of the presenting time — `fg_factor` / `native_fps` /
|
||||
`displayed_fps` from that state's own windows, `fg_factor_scope = 'steady'`, `fg_steady_share` (schema **0006**),
|
||||
the refusal and its detail kept beside it. The readout is the generated shape with the chip **`×2.0 FG · 75%`** —
|
||||
the share is never omitted — and a tooltip saying why there is no session-wide factor. Replayed over the nine
|
||||
sessions through the real `FgWindow`: eight publish (Onimusha ×4.00 60 → 240, Lies of P ×2.00, Hell Is Us ×3.03,
|
||||
Cronos ×2.00 225 → 451, Wukong ×4.11); the ninth had nine seconds of gameplay. **Two constants moved with it:**
|
||||
`BucketTolerance` 25 % → 10 % (at 25 % a ×3-then-×4 session published 3.69, and the one published session read
|
||||
×2.04 for a gameplay of 2.00), and `MultipleStreams` refuses only when the chains' samples interleave — Onimusha
|
||||
recreates its swapchain on entering gameplay, one stream at a time, and had been refused as two on every session.
|
||||
CLAUDE.md rule 6 amended. Two strings (en/vi/ja). Tests: `FgSteadyStateTests`, `FgWindowTests` (interleaved vs
|
||||
sequential), `SessionAggregatorTests`, `FpsPresentationTests`, `LedgerDatabaseTests` (script six), the repository
|
||||
round trip. Existing rows are not re-aggregated.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The first tag ran (2026-09-16).** `v0.1.0-beta.1` on `becc208`; `release.yml` run 35111939019. The first attempt
|
||||
passed the version gate and the substitution and then sat in `Infrastructure.Tests` for 58 minutes — every other
|
||||
suite green, the same suite 42 s in the rehearsal — until the job's 60-minute limit cancelled it with no test named;
|
||||
`gh run rerun --failed` on the same tag went green in 11 minutes and created the pre-release with the section's notes
|
||||
and the checksums appended. `build.ps1` now runs `dotnet test` with `--blame-hang --blame-hang-timeout 15m` (#196) so
|
||||
the next hang is a named failure; the capture-host suite's `Kill` waits for exit (#194) and the layer-registration
|
||||
test deletes only its own registry subtree (#188), the two harness races the same evening's merge train kept hitting.
|
||||
Docs: `13_CI_CD` §release.yml and §ci.yml's tally, `12_BUILD` §Publish & package (the runner's sizes),
|
||||
`15_ROADMAP` §P5.
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.20] - 2026-10-12
|
||||
|
||||
**The twentieth pre-release: the engine version of Ren'Py games.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.19`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
|
||||
Policy (2.9) is shown once for you to accept. Every game is read once more for its engine (detection rules `2026.10.3`).
|
||||
|
||||
### Added
|
||||
|
||||
- **The engine version of Ren'Py games**, as Unity's, Godot's and RPG Maker's have been shown since beta.19 — on the game's
|
||||
page with what it was read from, the engine's own `renpy/vc_version.py`: *Ren'Py 8.5.0*. A game whose engine names no
|
||||
version there reads as not found. Every game is read once more after the update (detection rules `2026.10.3`;
|
||||
`docs/05_DETECTION.md` §Engine version — Ren'Py).
|
||||
- **The Privacy Policy (version 2.9)** names that file among the version marks it reads; it is shown once for you to
|
||||
accept.
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.21] - 2026-10-13
|
||||
|
||||
**The twenty-first pre-release: an anti-cheat kept beside a game's executable found before anything is injected, four
|
||||
itch.io downloads that carry malware, documents that scroll further and smoothly, and Play.** The same unsigned
|
||||
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.20`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
|
||||
Policy (2.10) is shown once for you to accept. Every game is read and checked for anti-cheat once more (detection rules
|
||||
`2026.10.4`): Wuthering Waves, and any game that keeps an anti-cheat beside its executable, has its hooking turned off.
|
||||
If you installed HELLO, HELLO WORLD!, A Doll's Locket - Remake, City of Bones or Träumerei Chapter 2 from itch.io, read
|
||||
*Security* below first.
|
||||
|
||||
### Added
|
||||
|
||||
- **Play, on a game's page and on each game in the library.** Through the store that installed the game — Steam or the
|
||||
Epic Games Launcher starts it, GOG GALAXY runs it, the itch app asks which copy to launch — or started directly by
|
||||
FrameLedger, recorded from its first frame: **Settings ▸ Games ▸ Play button** switches between the two. A game no
|
||||
store installed, and a GOG game without GOG GALAXY, is started directly. FrameLedger never starts a game as
|
||||
administrator: *Start directly* does not start one that asks for it, and while FrameLedger itself runs as
|
||||
administrator, Play starts every game directly so that the game does not. A game whose recording is off is started
|
||||
only through its store. The Epic Games Launcher's link is the one its own shortcuts carry and has not been tried on a
|
||||
real Epic game yet (`docs/08_UI.md` §Games).
|
||||
- **The Privacy Policy (version 2.10)** names the store records Play and the library import read — the lists of installed
|
||||
games the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed; the import
|
||||
read the Epic and itch lists before and the policy did not say so — and that Play hands a game to its store's app,
|
||||
which may connect to its store while FrameLedger itself connects to nothing. It is shown once for you to accept.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The documents in the app scroll further and smoothly** — the user guide, Help ▸ Limitations, About's documents, the
|
||||
Legal Gate and the update notes. A wheel notch moved them a fixed short step whatever the wheel or touchpad sent;
|
||||
it now moves the number of lines Windows is set to scroll (a screen if it is set to that), about twice as far by
|
||||
default, in proportion for a touchpad, and glides there unless Windows' animations are off. At the end of the update
|
||||
notes the wheel scrolls the window instead; Ctrl+wheel still zooms. A page is drawn once when it is opened, not two or
|
||||
three times, and going back to a page you have read in the same window is immediate.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An anti-cheat kept beside a game's executable is found before anything is injected.** The safety check looked three folder
|
||||
levels into a game's install folder and no further, so an anti-cheat beside an executable that is itself three levels down
|
||||
was never seen: Wuthering Waves keeps Tencent's Anti-Cheat Expert in `Client\Binaries\Win64\AntiCheatExpert\`, its
|
||||
page read clean, and a session with hooking turned on was hooked for 37 seconds before the check that runs every 30 seconds
|
||||
met the anti-cheat's driver — and because a driver counts for the whole PC, the game's hooking stayed on. The check now also
|
||||
looks in the executable's own folder, on the game's page and before every injection. Wuthering Waves is also named by its
|
||||
Steam id (owner decision D58), and ACE's files, its second driver, its driver's service and its module are named (detection
|
||||
rules `2026.10.4`). Every game is checked for anti-cheat once more after the update; one found this way has its hooking
|
||||
turned off, as any finding does (`docs/19_SAFETY_AND_ANTICHEAT.md` §Pre-injection checks, item 4).
|
||||
- **A game's Supports card said *Not scanned yet* for a game the agent had read** whenever the game ships none of the
|
||||
upscaler, frame-generation or Vulkan files the rules name — beside a Details card the same read had filled. It says
|
||||
so now only until the agent has read the game, then *None found*.
|
||||
|
||||
### Security
|
||||
|
||||
- **Four itch.io downloads this project's documentation used as examples carry malware.** HELLO, HELLO WORLD!, A Doll's
|
||||
Locket - Remake, City of Bones and Träumerei Chapter 2 put the same 213 MB program in front of their RPG Maker game.
|
||||
Read without running it, it ships a registry file that switches off Windows' script scanning (AMSI) and adds
|
||||
Microsoft Defender exclusions, carries an encrypted payload, and checks for virtual machines and debuggers before it
|
||||
starts the game. The documentation called it a launcher and, for A Doll's Locket, said to measure it with the agent
|
||||
running as administrator: that advice is withdrawn. If you installed one of them, remove it and scan your PC.
|
||||
FrameLedger itself does not change: it reads a game's files to find its engine and anti-cheat, and does not judge
|
||||
whether a game is safe (`docs/spike-notes.md` §20).
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.22] - 2026-10-13
|
||||
|
||||
**The twenty-second pre-release: a request the capture agent never answered is said as such, never as a crash.** The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.21`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown to accept and no game is read again: the legal documents and the detection rules (`2026.10.4`) are beta.21's.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A request the capture agent never answered is said as such, never as a crash.** When the agent stopped, or restarted
|
||||
for an update, while FrameLedger was asking it something, deleting sessions ended in the crash dialog, and turning a
|
||||
game's hooking on or off or making or withdrawing an anti-cheat exception showed *IOException* or *TimeoutException* as
|
||||
its notice. Each now says that the agent did not answer and that whether it was done is not known, and the page shows
|
||||
what is stored; Play says the same (it said the agent was not running). A request that could not be sent because the
|
||||
agent was already gone still says that nothing was changed (`docs/07_IPC.md` §Client behavior).
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.23] - 2026-10-14
|
||||
|
||||
**The twenty-third pre-release: a game's artwork on its page, in a band that takes the picture's colour, and pages
|
||||
that open and change session without freezing.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.22`:** Help ▸ Check for updates, then *Restart to update* with no game running. The
|
||||
Privacy Policy (2.11) is shown once for you to accept. No game is read again: the detection rules (`2026.10.4`) are
|
||||
beta.22's. The artwork shows by itself for the games Steam or GOG GALAXY installed; **Settings ▸ Games** turns it, or
|
||||
its colour, off.
|
||||
|
||||
### Added
|
||||
|
||||
- **A game's page shows its artwork** (owner request 2026-10-14, decisions D60/D61). At the top of the page: the
|
||||
banner and the cover the Steam or GOG GALAXY app already keeps on your PC for the game it installed — read where that
|
||||
app keeps them, never downloaded and never copied — or an image you choose yourself in **Edit… ▸ Choose image…** (a
|
||||
copy is kept in the data folder's `covers` folder; **Use the store's image** goes back). The band they sit in takes the
|
||||
picture's main colour, never so strongly that a text on it gets hard to read (primary and secondary text keep 4.5:1,
|
||||
the faintest 3:1, in both themes), and follows a theme switch. A game from itch, the Epic Games Launcher or another
|
||||
store has a picture only once you choose one, because those apps keep no image files. **Settings ▸ Games** has *Show
|
||||
game artwork* and *Colour the game page from its artwork*, both on. **Privacy Policy 2.11** names the images read and
|
||||
the copies kept; FrameLedger still makes no request to any store.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The list of tested games has its first Vulkan game**: Everhex Demo, measured through FrameLedger's Vulkan layer on
|
||||
2026-10-13 when Play started it directly (`docs/LIST_GAME_TESTED.md`, `LIMITATIONS.md`). Four places in the developer
|
||||
documents that described something never built, or kept a count that went stale, are corrected in place.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A game's page opens and changes session without freezing the window** (owner request 2026-10-14). Measured on the
|
||||
dev PC over a ledger shaped like the owner's (`docs/spike-notes.md` §21): a game with 100 sessions took 1.2–1.5 s to
|
||||
open — its Sessions list built every row, now only the rows on screen (it scrolls itself and hands the wheel to the
|
||||
page at its ends) — 0.37 s now; choosing a two-million-frame session froze the window 0.8–1.0 s — the session was read
|
||||
and decoded on the UI thread, then sorted three times for the Distribution tab — 17 ms now: it is read on the thread
|
||||
pool and what the charts need from all of it is worked out there once. The page also asks whether the game's `.exe` is
|
||||
on disk off the UI thread (a USB drive that sleeps answered on it), and no longer summarises every game to show one.
|
||||
- **Each visit to the Dashboard or Logs no longer stays in memory.** Every Dashboard ever opened stayed alive and kept
|
||||
listening to the capture agent, so at each session's end each one reloaded its lists and raised its own "Session
|
||||
saved" notice — twenty visits, twenty notices, the last one shown. The Dashboard listens only while it is on screen,
|
||||
and the notice has one home for the App's life, shown once whichever page is open; each Logs page kept its tail of up
|
||||
to 2 MB, twice.
|
||||
- **The Logs page reads its file only when it changed**, not every two seconds, and filters it off the UI thread; **Play**
|
||||
reads the stores' lists of installed games off the UI thread (Steam's manifests sit on whatever drive its libraries
|
||||
are on). At Debug level the App now logs how long each page took to appear (`ui: page … shown … ms`).
|
||||
- **The native ring-buffer tests no longer pass or fail by the scheduler's luck** (developers only). The
|
||||
hammering-writer test required the reader to keep more than half of the stream, which measured how the operating
|
||||
system scheduled two threads: on a hybrid Intel processor it failed 5 of 200 runs with the ring correct every time.
|
||||
Both concurrency tests now start the writer only once the reader is running, repeat until the reader really read
|
||||
the ring while the writer wrote it, and require that; the small-ring test's old check also passed a reader that
|
||||
started after the writer had finished (`src/native/tests/ring_test.cpp`).
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.24 was cut, 2026-10-19 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.24] - 2026-10-19
|
||||
|
||||
**The twenty-fourth pre-release: every frame-generation state a session held, the quality mode the NVIDIA App set, and
|
||||
which DLSS ran.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.23`:** Help ▸ Check for updates, then *Restart to update* with no game running. The
|
||||
Disclaimer (2.11) and the Privacy Policy (2.12) are shown once for you to accept. The ledger moves to schema 21, which
|
||||
a beta.23 cannot open. No game is read again: the detection rules (`2026.10.4`) are beta.23's. The mix of
|
||||
frame-generation states and where each DLSS library was loaded from are kept for sessions recorded from now on; the
|
||||
quality mode the NVIDIA App set reads on sessions you already have.
|
||||
|
||||
### Added
|
||||
|
||||
- **Every frame-generation state a session held, in its summary** (owner request 2026-10-19, decision D62). Under the
|
||||
figures, *Frame generation in this session* lists each state — `×2.0`, `×3.0`, `×4.0`, `×6.0`… — with its own
|
||||
Native → Displayed and its share of the time to two decimals, then the time with no frame generation and the time no
|
||||
state explains (*Not classified*: switching, loading, a multiplier that changed faster than five seconds), above a bar
|
||||
of those shares. A line above them says how frame generation was set: in the NVIDIA App (*Dynamic, up to ×6, target:
|
||||
max refresh rate*, *Fixed ×4*, from the driver profile stored with the session) or in the game. Each state is read
|
||||
over the same five-second windows as the steady state and lasts at least 10 seconds; nothing is averaged across
|
||||
states (rule 6). Stored with the session (schema 0020, `sessions.fg_mix`): a session recorded before has none, and
|
||||
its summary says so in one line. The CSV export gains a `# fg_mix:` line; the JSON carries the column. The FG×
|
||||
column's two formats are translated strings now, and the driver-profile line's automatic dynamic target reads as the
|
||||
NVIDIA App says it: *max refresh rate*.
|
||||
|
||||
- **The quality mode the NVIDIA App set, on every page that names the upscaler** (owner request 2026-10-19, decision
|
||||
D63). Where the NVIDIA App overrides DLSS Super Resolution for a game and the NVIDIA driver reports that the
|
||||
override applied in the session, the summary, the Sessions tab, the game page and the live card say so:
|
||||
*DLSS (driver-reported) Quality · NVIDIA App*. It is read from what every session already stores, so sessions
|
||||
recorded before read the same; when the profile and the driver disagree, or the driver's report alone cannot settle
|
||||
the mode, the session reads *· NVIDIA App override* with no mode — never the game's own value in its place. The CSV
|
||||
export gains a `# quality_mode:` line. `legal/ACCURACY.md`'s *Quality mode* bullet says so, in the words approved
|
||||
with the plan; **the Disclaimer is 2.11** and the Legal Gate shows it once.
|
||||
|
||||
- **Which DLSS a session ran** (owner request 2026-10-19, decision D64). The summary's DLSS line gives each DLSS
|
||||
library's version and whether it was loaded from the game or from the graphics driver (the NVIDIA App's override
|
||||
loads the driver's own copy), the model preset the NVIDIA driver reports, and *DLSS 4* or *DLSS 4.5* only where the
|
||||
session shows it — the preset (L or M: 4.5; J or K: 4) or a measured multi-frame factor (×5–×6: 4.5; ×3–×4: 4) —;
|
||||
DLSS 2 and 3 from their libraries; *DLSS 5 runtime loaded* when its library is. The game page repeats the label and
|
||||
the CSV export gains `# dlss:`. The module snapshot now records every library under the NVIDIA override folder,
|
||||
whatever its name, and each module's folder class (schema 0021, `sessions.runtime_module_sources` — never the path),
|
||||
plus five more libraries by name (`sl.dlss_d.dll`, `sl.common.dll`, `sl.reflex.dll`, `amd_fidelityfx_loader_dx12.dll`,
|
||||
`nvngx_dlssnr.dll`). **Privacy Policy 2.12** says so, in the words approved with the plan; `legal/ACCURACY.md` gains
|
||||
the *DLSS version* bullet.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The analyzers are Meziantou.Analyzer 3.0.307 and Microsoft.VisualStudio.Threading.Analyzers 18.12.1**
|
||||
(developers only): the update Dependabot proposed in #314 and then closed itself as "updatable in another way" —
|
||||
applied by hand, with the two suppressions it needed merged earlier in the train.
|
||||
- **SonarCloud analyses only FrameLedger's own code** (developers only; owner request 2026-10-19, decision D67). A
|
||||
`.sonarcloud.properties` at the root keeps the vendored SDK headers, generated files, test fixtures, licence texts and
|
||||
the SQLite migrations out of the analysis and reports the native code against C++20; `docs/13_CI_CD.md` §SonarCloud
|
||||
records the triage of the 341 issues the last analysis left — the rules this project breaks by design and why, the
|
||||
false positives, and the ones the next change fixes — with the steps to mark them in SonarCloud.
|
||||
- **The long documents are split** (developers only; owner request 2026-10-19, decision D66). `CHANGELOG.md`
|
||||
keeps `[Unreleased]` and a table of the releases; each release's section now lives in its own file,
|
||||
`docs/changelog/<version>.md`, and the ledger kept before the first tag in five parts — moved verbatim: the notes
|
||||
`tools/release-notes.ps1` takes for each of the 23 releases are byte for byte what they were, and it reads the
|
||||
version's own file. `docs/HANDOFF.md` (2,844 lines, now 299) keeps what to do next, the open owner-only items and an
|
||||
index of every owner decision; the history of each phase and train, the passed owner-only items and the traps
|
||||
moved to `docs/handoff/`, and a table there resolves every section the code and the documents cite. A new gate,
|
||||
`tools/docs-split-check.ps1`, keeps each index and its files naming each other.
|
||||
- **The open questions and the measurement notes are split too** (developers only, D66). `docs/20_OPEN_QUESTIONS.md`
|
||||
(4,467 lines, now 2,008) keeps its rules, §S24 and every entry not resolved; the 30 entries §S24 marks resolved
|
||||
moved, with their reasoning and in their order, to `docs/open-questions/closed-s.md` and `closed-h.md`, and a table
|
||||
at the end of each series lists them. `docs/spike-notes.md` (2,816 lines) is now the index of its 24 sections, each
|
||||
in its own file under `docs/spike-notes/`; a new measurement gets the next number, its own file and a row. Both
|
||||
rebuild their originals byte for byte, and the same gate holds their indexes to their files.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The NVIDIA driver line read the driver's mode in the wrong numbering.** The driver reports the mode an override
|
||||
set in NGX's own numbering, not the driver profile's: the owner's Silent Hill 2 session ran under the NVIDIA App's
|
||||
Ultra Performance (profile value 5) and the driver reported 3 — which the line printed as nothing, and a DLAA
|
||||
override's 5 would have printed as "Ultra Performance". Five comments in the native code called a quality byte of
|
||||
0 "NGX MaxPerf" — in the numbering that byte carries, 0 is "DLSS off" (comments only, no code changes).
|
||||
- **Opening a folder in Explorer** — the logs, the data folder, the licences, a bug report's zip and the folder named
|
||||
after a failed start — starts `explorer.exe` from the Windows folder by its full path, never a program of that name
|
||||
found on the search path, and always hands it the path in quotes (three of the five places passed it bare).
|
||||
- **What SonarCloud found that was real** (developers only): the one third-party GitHub Action is pinned to its
|
||||
commit; two string reads in native code are bounded by their buffer (the guard's rules-file path handed to the Agent,
|
||||
and the driver's branch name the NVAPI bridge copies); the pipe server's accept loop states that it ends only when
|
||||
cancelled; a launch's own session names its absent stop token (`CancellationToken.None`, with the reason) where it
|
||||
wrote `default` — the same value, now said on purpose; an unused overload of
|
||||
the process launcher that hid the other is gone; the identifier `module` (a C++20 keyword in some positions) is
|
||||
renamed in the hook layer — a rename only, no code changes; and a hook-overhead probe no longer uses a compound
|
||||
assignment on a `volatile`, which C++20 deprecates. The analyzers Dependabot updates in #314 flag the first-start
|
||||
window's own answer task and one test fake's synchronous wait; both are suppressed with their reasons, so that update
|
||||
can merge.
|
||||
- **The game-side log keeps every line a stop writes.** When hooking stopped on a game's own drawing thread — the
|
||||
capture agent's safety stop takes effect within one frame there — the Overlay's last write of its log could happen
|
||||
while that thread was still listing the hooks it removed, and the last of them never reached the file
|
||||
(`overlay-*.log`, the file a bug report carries). The last write now waits, at most two seconds, for the stop to
|
||||
finish and ends with a `STOP_FLUSHED` line; a line still being written is never printed half-done. Nothing changes
|
||||
on the per-frame path. This was the native test that went red under load since beta.9 (`fl_guard`'s log case),
|
||||
now run 20 times with every processor busy.
|
||||
@@ -0,0 +1,27 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.25 was cut, 2026-10-19 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.25] - 2026-10-19
|
||||
|
||||
**The twenty-fifth pre-release: FSR's quality mode.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.24`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
|
||||
no game is read again: the detection rules (`2026.10.4`) are beta.24's. FSR's quality mode is recorded for sessions
|
||||
from now on; a session recorded before keeps what it had.
|
||||
|
||||
### Added
|
||||
|
||||
- **FSR's quality mode** (owner decision D65, planned for beta.24 and moved to this release). For a game that runs FSR
|
||||
through AMD's FidelityFX libraries, the summary, the Sessions tab, the game page and the live card name the mode —
|
||||
*FSR 3 Quality*, *FSR Performance*, *FSR Native AA* — when the game asked AMD's library what render size that mode
|
||||
gives and then rendered at that size. A game at a dynamic resolution, one that sizes its frames without asking, and
|
||||
one FrameLedger joined after it asked show none. FrameLedger reads one more call in those libraries (`ffxQuery`,
|
||||
beside the `ffxDispatch` it already reads): the size or ratio AMD's library answered, nothing else — about 8 ns per
|
||||
upscaled frame. The CSV export's `# quality_mode:` carries it (`native_aa (game)` for Native AA).
|
||||
`legal/ACCURACY.md`'s *Quality mode* bullet gains its FSR clause, in the words approved with the beta.24 plan; the
|
||||
Disclaimer stays 2.11, as it did for the accuracy statement's additions in beta.19 and beta.20. Checked with AMD's
|
||||
interface on the test program; a real game is owner-only item 21. Developers: the hook has its own family bit
|
||||
(`FL_HOOK_UPSCALER_QUALITY`, bit 11 of `hooksInstalledMask`), the byte is `0x10 + FfxApiUpscaleQualityMode`, the
|
||||
harness asks with `--ffx-query sizes|ratios`, and `Domain.Metrics.QualityByte` is the one rule a session, its
|
||||
segments and the live card read.
|
||||
@@ -0,0 +1,35 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.26 was cut, 2026-10-19 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.26] - 2026-10-19
|
||||
|
||||
**The twenty-sixth pre-release: a frame-generation state no frame generation produces, fixed.** The same unsigned
|
||||
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.25`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
|
||||
no game is read again: the detection rules (`2026.10.4`) are beta.25's. Sessions you already recorded read by the new
|
||||
rule at once — nothing in them is rewritten.
|
||||
|
||||
### Changed
|
||||
|
||||
- **SonarCloud's last six findings on `main`, triaged** (developers only; D67's follow-up). After the owner's marking,
|
||||
the analysis of 0.1.0-beta.25 left six open: `docs/13_CI_CD.md` §SonarCloud lists them with a verdict and the comment
|
||||
to paste — one to accept as the table already said, four false positives (exact floating-point comparisons that are
|
||||
exact on purpose), and one fixed here: `wiki.yml` publishes only after a Release run started by a tag pushed to this
|
||||
repository, now checked by the repository's name in its condition as well as by the run's trigger.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A frame-generation "state" of ×1336.0.** The owner's Silent Hill 2 session (0.1.0-beta.25, the NVIDIA App's
|
||||
*Dynamic* multi frame generation) listed a ×1336.0 state — 0.20 → 267.20 FPS for ten seconds — under *Frame
|
||||
generation in this session*, and the DLSS line cited it: *DLSS 4.5 (a ×1336.0 frame-generation state)*. Those ten
|
||||
seconds — the game compiling its shaders at start — were presented with one application frame counted per
|
||||
five-second window, and a window needed eight presents but only one counted frame to be read. A window now needs eight
|
||||
application frames and a ratio no higher than ×8 — more than any frame generation produces (DLSS 4.5's ×6 is the
|
||||
most); every other window is *Not classified*, and the steady state reads the same windows. A session-wide or live ratio that held above ×8 is
|
||||
refused and says why (*the ratio is beyond what any frame generation produces*), in en/vi/ja. Sessions already
|
||||
recorded are read by the same rule, so that session now lists ×2.0, ×3.0, ×6.1, no frame generation and 30 seconds
|
||||
not classified, and its DLSS line cites ×6.1. The owner's runs of beta.24 and beta.25 are recorded in
|
||||
`docs/spike-notes/22-owner-runs-2026-10-19.md`: the *Dynamic* settings line matched the NVIDIA App's own words, the
|
||||
override's two library names are written down, and Lies of P read no FSR mode with the query hooked — the title
|
||||
rounds its own render size and asked nothing the hook kept.
|
||||
@@ -0,0 +1,56 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.27 was cut, 2026-10-20 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.27] - 2026-10-20
|
||||
|
||||
**The twenty-seventh pre-release: the owner's eight sessions of 2026-10-20, checked — six faults fixed, and *Start
|
||||
directly* says what a Steam game may do.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
|
||||
*More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.26`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
|
||||
no game is read again: the detection rules (`2026.10.4`) are beta.26's. Sessions you already recorded read the
|
||||
frame-generation fix at once; the driver's DLSS report, the display sizes and the game Steam starts are recorded from
|
||||
this version on — nothing already stored is rewritten.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Play ▸ *Start directly* says what a Steam game may do.** Some Steam games hand themselves to Steam when
|
||||
FrameLedger starts them — Lies of P closes within seconds and Steam starts it again. Starting a game Steam installed,
|
||||
the notice now says it may hand itself to Steam first and that the game Steam then starts is recorded; the *Start
|
||||
directly* tooltip and Settings ▸ Games ▸ *Play button* say so too, adding that a few will not start outside Steam at
|
||||
all. Steam games keep *Start directly*: three of the five started directly on 2026-10-20 ran and were measured from
|
||||
their first frame, and a Vulkan game is measured only when FrameLedger starts it. In en/vi/ja (ja marked for review).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A frame-generation "state" of ×2.52.** The owner's Silent Hill 2 session under the NVIDIA App's *Dynamic* multi
|
||||
frame generation listed ×2.52 for 13 seconds beside ×2.0 and ×3.0: the five-second windows in which the multiplier
|
||||
stepped from ×2 to ×3 read in between, and three of them formed a state nobody held. Every frame generation that
|
||||
ships multiplies by a whole number, so a window now counts toward a state only within 10 % of one; the others are
|
||||
*Not classified*. Sessions already recorded are read by the same rule: that session lists ×2.0, ×3.0, no frame
|
||||
generation and 7.36 % not classified. The owner's runs of 2026-10-20 are recorded in
|
||||
`docs/spike-notes/23-owner-runs-2026-10-20.md`.
|
||||
- **The NVIDIA driver's DLSS report was lost from every stored session.** FrameLedger asked the driver one last time
|
||||
after the game had closed, and that answer — which no longer says DLSS ran — replaced the ones read while the game
|
||||
ran. So no session said *DLSS (driver-reported)* where no hook saw DLSS, and none named the NVIDIA App's quality mode
|
||||
on such a game: Clair Obscur: Expedition 33 under the App's override read *Upscaler not identified*. The driver is no
|
||||
longer asked once the game has closed, and once it reports that DLSS ran, the session keeps it. Sessions recorded
|
||||
before keep what they stored.
|
||||
- **Play ▸ *Start directly* recorded nothing of a game that hands itself to Steam.** Lies of P, started directly, closes
|
||||
within seconds and Steam starts it again; the game Steam started was turned away while the first session ended and
|
||||
never recorded. It is now recorded once that session ends, as a game started again already was. Each such start
|
||||
still counts toward the two early exits that turn hooking off for a game, so Limitations ▸ Play advises starting such
|
||||
a game through its store.
|
||||
- **Opening a session's summary twice opened two windows.** The open window comes forward instead, restored if
|
||||
minimised.
|
||||
- **No window or monitor size for a game in exclusive full-screen.** A game leaving exclusive full-screen closes its
|
||||
window a moment before its swap chain says so, and those last samples replaced the sizes: two Lies of P and three
|
||||
Dark Souls III sessions show none. The sizes are now the last ones the mode saw.
|
||||
- **A DLSS line that said only "DLSS"**, under a header that already did, is no longer shown: the NVIDIA App's override
|
||||
loads its libraries under names FrameLedger does not list (The Witcher 3), and the *Loaded:* line prints them.
|
||||
- **Two integration tests that failed under load** (developers only). The guard reads every process above the test
|
||||
harness too, the test host among them, and under a full `build.ps1 check` the test host is still starting its other
|
||||
test classes: a module it released while the guard read its list refused the injection (`ModuleScanFailed`, and
|
||||
`ProcessUnreadable` on 2026-10-19). The drain suite asks the guard again on those two reasons, four times at most;
|
||||
the pause case, which once read the writer still starting, waits for it to be ready; and every injection test waits
|
||||
for the harness's own "presenting" line instead of 800 ms (`tests/Shared/HarnessReady.cs`).
|
||||
@@ -0,0 +1,26 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.28 was cut, 2026-10-20 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.28] - 2026-10-20
|
||||
|
||||
**The twenty-eighth pre-release: the Dashboard shows every game being recorded.** The same unsigned installer: verify
|
||||
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.27`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
|
||||
no game is read again: the detection rules (`2026.10.4`) are beta.27's. Only the App changes; the capture agent and
|
||||
what it records are beta.27's.
|
||||
|
||||
### Added
|
||||
|
||||
- **The Dashboard shows every game being recorded.** Two games running at once are two sessions, and until now the
|
||||
Dashboard's *Live capture* card showed one of them — a measured one first — while the other appeared only as
|
||||
*Running sessions: 2*. Each running game now has its own card, side by side, with its own frame rate, settings,
|
||||
elapsed time and memory, or why it is recorded without being measured; measured games come first, and the title
|
||||
says how many games are being recorded (*2 games recording*). In en/vi/ja (ja marked for review).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A native injection test that failed under load** (developers only). Two `fl_guard_test` cases — the OpenGL hook,
|
||||
and a swap chain on a real window — waited 4 seconds for twenty frames, and on a loaded CI runner (the suite took
|
||||
115 s) the OpenGL hook, installed, had recorded none. They now wait up to 12 seconds, the harness presenting for 16,
|
||||
and a failure says the writer's state.
|
||||
@@ -0,0 +1,55 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.29 was cut, 2026-10-25 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.29] - 2026-10-25
|
||||
|
||||
**The twenty-ninth pre-release: updated libraries, and SonarCloud analysing every change from CI.** The same unsigned
|
||||
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.28`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
|
||||
no game is read again: the detection rules (`2026.10.4`) are beta.28's. What you see and what is recorded are
|
||||
beta.28's; the libraries under them are newer.
|
||||
|
||||
### Changed
|
||||
|
||||
- **SonarCloud analyses the repository from CI** (developers only; owner decision D68). The owner turned SonarCloud's
|
||||
Automatic Analysis off and set the `SONAR_TOKEN` secret; `ci.yml`'s new `sonarcloud` job runs the SonarScanner for
|
||||
.NET 12.0.0 (a local tool, `.config/dotnet-tools.json`) after `check`, in a build of its own — the scanner turns
|
||||
warnings-as-errors off in the build it instruments, so it cannot wrap the gate's — with the gate's own test coverage
|
||||
(`build.ps1` now writes OpenCover beside Cobertura; the C# only, since the PowerShell tools and the native code have
|
||||
no coverage report) and CMake's compilation database for the C++, which
|
||||
`FrameLedger.Infrastructure.csproj` names to the scanner only in that build. `SonarQube.Analysis.xml` replaces
|
||||
`.sonarcloud.properties`. The job is advisory, not a required check, and waits for the quality gate, so a failed gate
|
||||
is a red job (`docs/13_CI_CD.md` §SonarCloud).
|
||||
- **Dependabot, the NuGet audit and CodeQL** (developers only). Dependabot's version updates wait seven days after a
|
||||
release (security updates do not), and the actions' minor and patch releases come as one pull request a week. The
|
||||
NuGet audit is written down in `Directory.Build.props` (the whole graph, every severity — the SDK's defaults for
|
||||
net10.0), so a later SDK cannot move it. CodeQL also reads the workflows (`analyze (actions, none)`, not required),
|
||||
and a new push to a pull request replaces its CodeQL run.
|
||||
- **The libraries Dependabot never updated.** Every NuGet pull request Dependabot opened here updated analyzers only,
|
||||
so the libraries fell behind with nothing to say so (`docs/13_CI_CD.md` §Dependabot and the NuGet audit). Updated by
|
||||
hand, each release at least seven days old (the cooldown Dependabot now keeps): the October .NET servicing release of
|
||||
`Microsoft.Extensions.Hosting`, `Microsoft.Data.Sqlite` and `System.Diagnostics.EventLog` (10.0.13) and `Dapper`
|
||||
2.1.89, which ship; the CsWin32 source generator 0.3.363, which writes the Win32 declarations the shipped code calls;
|
||||
for developers, the test SDK 18.11.0 and xunit 4.0.2. The licence texts under `legal/licenses/nuget/` name the new
|
||||
versions; no licence changed. Not taken: Markdig 1.5.0 (published the day before, and its licence is a reviewed copy
|
||||
at the packaged commit), Velopack 1.2.161 (the updater itself — a change to how updates install is the owner's to
|
||||
try), FluentAssertions 8 (its licence) and `coverlet.collector` 10.1.0: the tracker it adds to each assembly it
|
||||
instruments declares a constant whose value reflection cannot read ("Literal value was not found"), and
|
||||
`NoSecondMatcherTests` reads every string constant in three of ours. The first CI run blamed CsWin32 for it; with
|
||||
coverage collected locally the failure followed coverlet, and 10.0.1 passes (`Directory.Packages.props` says so
|
||||
beside it).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The 34 C++ issues of `main`'s first SonarCloud analysis from CI** (developers only). Read with MSVC's real flags,
|
||||
the native code showed issues Automatic Analysis had not, on older lines; SonarCloud dates each by blame, and the
|
||||
two on lines changed since its new code began failed `main`'s gate on reliability. One was a defect in a test tool: `hook-harness --opengl` or `--vulkan` beside
|
||||
a D3D11 mode — or `--opengl` alone, which ran the default probes — called through a null swapchain; every mode that
|
||||
drives the D3D11 swapchain now asks first. The rest: `NvU32` printed with `%u` in `fl-probe-nvapi` (`%lu`; its
|
||||
machine line reads the same), a union and a `strlen` in the guard's tests, a `LARGE_INTEGER` read through
|
||||
`QuadPart` after `{}` had made its other member the active one (the Overlay's clock epoch, and the Vulkan layer's
|
||||
once-per-process enable-list read — now initialised through `QuadPart`), two terminators written after a read whose
|
||||
bound is now tested first, and five marked `// NOSONAR` with the reason above each. The Overlay compiles to the same
|
||||
instructions: built from either side, in one folder with one build id, its `.text` is byte-identical
|
||||
(`docs/13_CI_CD.md` §SonarCloud has the table).
|
||||
@@ -0,0 +1,140 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.3] - 2026-09-21
|
||||
|
||||
**The third pre-release.** The same unsigned installer as before: verify its hash against `SHA256SUMS.txt`, then
|
||||
*More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The terms changed, so the Legal Gate opens once after the update.** They now say plainly that this is beta
|
||||
software with bugs, that your PC must meet each game's own minimum requirements, and what the new guard bypass means.
|
||||
- **CPU load, system memory and (when the Agent runs as administrator with PawnIO) CPU temperature are recorded**, and a
|
||||
game's Trend tab can chart them, the GPU's load and power, VRAM and the ×FG factor across that game's sessions.
|
||||
Settings ▸ System shows this PC as FrameLedger records it.
|
||||
- **DLSS is named.** Titles that call DLSS directly read "Unknown upscaler"; they now read "DLSS (driver-reported)"
|
||||
where the NVIDIA driver reports it — including sessions you already recorded.
|
||||
- **A game imported from Steam could never hook** when the import picked a helper executable instead of the game
|
||||
(GIRLS' FRONTLINE 2 was one). The import picks the game now, and the game page shows the executable and can change it.
|
||||
- **The platform and engine tags were blank white boxes in the light theme.** Fixed.
|
||||
- **New, off by default, per game: "Bypass the anti-cheat guard (at your own risk)".** Read its warning. Your account
|
||||
can be permanently banned, and the developers accept no responsibility if you turn it on.
|
||||
|
||||
**Updating from `0.1.0-beta.2`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) before installing, as before.
|
||||
- On its first start the ledger migrates to schema 7 (the guard-bypass columns; nothing existing is rewritten).
|
||||
- **A game an earlier Steam import created for the wrong executable is not rewritten.** Open it, check the path under
|
||||
its name, and use *Change executable…* (hooking is turned off for it and must be enabled again), or remove it.
|
||||
- Sessions recorded before this version keep N/A for CPU load, memory and CPU temperature: nothing measured them.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **DLSS read "Unknown upscaler" on most titles while FSR was named.** Most DLSS titles call NGX directly, and no NGX
|
||||
hook may exist (the SDK's licence; `20_OPEN_QUESTIONS`), so the hook runs and sees nothing. The NVIDIA driver does
|
||||
report the feature per process, the Agent has stored that on every session since P2
|
||||
(`sessions.upscaler_driver_reported`) and the capture host has printed it since 2026-09-06 — **the App never read
|
||||
it.** It does now: where no hook named an upscaler and the driver reports NGX super resolution created and
|
||||
evaluated, the library, the session summary, the game page and the live card say **DLSS (driver-reported)** —
|
||||
attributed, identity only, never a quality. A hook's name still outranks it. Sessions already recorded show it too,
|
||||
because the column was always written. `unknown` itself now reads "Upscaler not identified". Nothing native changed.
|
||||
- **A measured DLSS preset is its name, not its number**: `DLSS Balanced`, not `DLSS 2` (`Domain.Metrics.UpscalerNames`,
|
||||
which `03_METRICS` had promised from the start). Only the Streamline route produces the byte; a value with no name
|
||||
is shown as stored. A preset derived from the render scale is still not shown — that is an open owner decision.
|
||||
|
||||
- **The Games card's platform and engine tags were empty white boxes in the light theme.** They were
|
||||
`ui:Badge Appearance="Secondary"`, whose WPF UI 4.3.0 trigger repaints the background only and keeps the default
|
||||
badge's on-accent foreground: near-white text on a near-white fill. They, and the edit dialog's "Detected" marker,
|
||||
are the App's own `TagPill` now, with the theme's secondary text; `ContrastTests` refuses a Secondary badge in App
|
||||
XAML beside the four palette appearances it already refused (`08_UI` §Contrast).
|
||||
- **A game imported from Steam could be a game that never hooks.** Steam names no executable, so the import guessed
|
||||
"the largest non-helper", and on GIRLS' FRONTLINE 2: EXILIUM that was the embedded browser
|
||||
`GF2_Exilium_Data\Plugins\ZFGameBrowser.exe`, not the 675 KB Unity player `GF2_Exilium.exe`. Everything downstream is
|
||||
keyed on the executable path, so hooking enabled on that row could never match the running game, while the same
|
||||
game added by its exe worked. The locator now ranks by the engines' own layouts (Unity `X.exe` beside `X_Data`,
|
||||
Unreal `*-Win64-Shipping.exe`), then by a name matching the install folder, then by size; it skips `X_Data\Plugins`
|
||||
and redistributables folders, knows `browser`/`webview`/`subprocess`/`analyzer`/`vconsole` as helpers, and walks four
|
||||
levels instead of three. Verified read-only over the owner's Steam library: GF2, Red Dead Redemption 2 (was the
|
||||
Rockstar launcher installer), Counter-Strike 2 (was `vconsole2.exe`), Rune Factory, Dying Light: The Beast (was
|
||||
nothing at all). **A row an earlier import created for the wrong executable is not rewritten**: remove it, or use
|
||||
the new button below.
|
||||
|
||||
### Added
|
||||
|
||||
- **A per-game "bypass the anti-cheat guard" switch, at your own risk (owner decision 2026-09-21).** Off by default,
|
||||
never global: there is no setting, no command-line switch and no rules-file field for it. Turning it on opens its
|
||||
own disclosure, which says what the guard found for that game, that anti-cheat treats a loaded DLL as tampering
|
||||
whatever it does, that **your account can be permanently banned without warning or appeal**, that FrameLedger does
|
||||
not hide and never will, and that **by turning it on you accept the entire risk yourself and the developers accept
|
||||
no responsibility or liability**. It is accepted only by ticking the acknowledgement AND typing `BYPASS`; Enter keeps
|
||||
the guard on. The Agent stamps it (the App writes nothing), keyed on the executable like consent; turning hooking
|
||||
off or the executable changing turns it off again. **It overrules the guard's judgement and nothing else**: the kill
|
||||
switch, a game that was merely added, a missing consent, a foreign payload, a 32-bit target, a failed injection and
|
||||
a Vulkan title the guard refuses all still refuse. The guard still runs every check and still reports what it
|
||||
found; the verdict is `AllowedUnderUserBypass`, never `Allow`. **How FrameLedger injects is unchanged** — the same
|
||||
documented `LoadLibraryW`, the DLL's real name and version info, one chokepoint file (CLAUDE.md rule 3). Every
|
||||
session started under it is marked, permanently, with what the guard found: in the sessions list, the session
|
||||
summary, the CSV and JSON exports (schema 0007: `games.guard_bypass_*`, `sessions.guard_bypassed` /
|
||||
`guard_bypass_family` / `guard_bypass_signal`). A session recovered after an Agent crash does not carry the mark.
|
||||
CLAUDE.md rule 2, `19_SAFETY`, `02_SPEC` FR-2.7, `SECURITY.md` and `tools/chokepoint-check.ps1`'s own description
|
||||
are amended with it. Japanese shows this dialog in English until a reviewer signs the translation.
|
||||
|
||||
- **CPU load, memory in use and (elevated) CPU temperature are measured.** `sessions.avg_cpu_load`, `avg_cpu_temp`,
|
||||
`max_cpu_temp` and `avg_ram_mb`, and the `cpu_load` / `cpu_temp` / `ram_mb` sensor series, were in the schema from
|
||||
0001 with no producer. The telemetry poller now reads the machine beside the GPU on the same 1 Hz tick: CPU time
|
||||
busy across every logical processor (`GetSystemTimes` — not Task Manager's frequency-scaled "utility") and physical
|
||||
memory in use, both unprivileged and opening no process. **CPU temperature is read only when the Agent runs as
|
||||
administrator with PawnIO installed, and has not been checked on real hardware yet**; everywhere else it is N/A,
|
||||
never 0. Sessions recorded before this keep their nulls; no migration. The live card carries CPU load and
|
||||
temperature (`SessionProgress.cpuLoadPct`, optional).
|
||||
- **One game's sessions over time, beyond the frame rate.** The game page's Trend tab gains average GPU load, average
|
||||
GPU power, max VRAM (game), average CPU load, max CPU temperature, average memory in use, and the **×FG factor**. A
|
||||
factor that is its session's steady state (rule 6) covers part of the session, so it is left out by default and
|
||||
drawn marked when "include mid-session changes" is on — never as the session's. The Sensors chart draws CPU
|
||||
temperature, CPU load and system memory; Compare gains average GPU load, average CPU load and max CPU temperature;
|
||||
the session summary gains GPU and CPU cards (average load · peak temperature).
|
||||
- **Settings ▸ System shows this PC** — processor, graphics card and driver, memory, Windows build, primary display —
|
||||
as FrameLedger records it with every session, with a Copy button; nothing is sent anywhere. The session summary
|
||||
shows that session's snapshot under its header, and `--diag` prints the machine's. The bug bundle is unchanged.
|
||||
|
||||
- **Game page: the row's executable is shown, and "Change executable…" re-points it.** The remedy for a wrong import
|
||||
guess used to be remove-and-add. The row comes back exactly as a new game would — hooking off, no consent, pre-scan
|
||||
not run — with consent revoked over the pipe first, as removal does; a block is never cleared by it, and a path
|
||||
another row owns (in the library, or removed with its sessions kept) is refused.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The terms say what an end user needs to hear, and must be accepted again.** `legal/DISCLAIMER.md` 2.2 -> **2.3**:
|
||||
a new §0 (**this is pre-release software — it certainly still has bugs, and the developer is not responsible for
|
||||
incidents that result**), §2A (the guard bypass, entirely at your own risk, no liability), §4A (**your PC must meet
|
||||
at least the minimum requirements the game's developer or publisher states — read them first; problems on a machine
|
||||
below them, or on unstable, overclocked or overheating hardware, are yours and not the developer's**) and §7A (back
|
||||
up your own data; builds are unsigned, download only from the project's Releases page and verify the hash; no
|
||||
affiliation with any game, platform or vendor; numbers are for your own information). `legal/EULA.md` 1.0 -> **1.1**
|
||||
says the same in §2A/§2B. The first-run Legal step shows a short plain-language summary of those points in en/vi/ja
|
||||
above the documents, which remain the terms. Because both versions moved, the Legal Gate opens once after the update.
|
||||
The accuracy block's Safety bullet no longer says "There is no override anywhere".
|
||||
- **Docs that had gone stale.** `legal/THIRD_PARTY_NOTICES.md` gains the test-time row it never had (xUnit.net v3 4.x
|
||||
under Apache-2.0, FluentAssertions 7.x and why it is pinned, NSubstitute, coverlet, Test.Sdk, Catch2);
|
||||
`16_WPFUI_SYNTAX` named a TFM this repository never built; `14_TESTING` still called Catch2 and the blocked toggle
|
||||
future work; README's status line said "pre-alpha" beside three pre-releases; `build.ps1` "skipped" the coverage and
|
||||
rules gates when their tools were missing, which its own header calls worse than no gate — a missing tool fails now.
|
||||
- **Two flaky tests, seen on CI the same day.** The native-log test slept a fixed 1500 ms and read the Overlay's log
|
||||
between two lines (it polls for the last one now); `ParentDumpTests` dumped a child process microseconds after starting
|
||||
it and got `ERROR_PARTIAL_COPY` (it waits for the child to finish loading). Neither was a product defect.
|
||||
- **A local native build no longer fails on an uncommitted change.** After the first tag `git describe --dirty`
|
||||
produces `v0.1.0-beta.2-2-g<12 hex>-dirty`, 35 characters against `FlShmHandshake::buildId`'s 31, so every CMake
|
||||
configure of a dirty tree was fatal and the workaround was "commit before you build". The id now falls back to an
|
||||
8-digit abbreviation with `+` for dirty when the long form does not fit; a release is a clean checkout at a tag and
|
||||
never takes the fallback. Still too long after that is still fatal.
|
||||
- **Dependencies, 2026-09-21.** The test framework moves from xUnit.net v3 3.2.2 to **4.0.1**, referenced as
|
||||
`xunit.v3.mtp-off` with `xunit.runner.visualstudio` 4.0.0: 4.0 makes Microsoft Testing Platform v2 the default of the
|
||||
plain `xunit.v3` package, and `build.ps1`'s gates are VSTest-shaped on purpose (the `XPlat Code Coverage` collector,
|
||||
the `results.trx` the struct-mirror gate and the 25-minute wall clock read), so the projects take the same 4.x
|
||||
framework through the variant xunit publishes for that. The tree carried no v2-era API; the one test change is a
|
||||
race 4.0.1's scheduler found on its first gate run: eight `App.Tests` classes write the process-wide `Strings.Culture`
|
||||
and ran in parallel, so `StringsTests` read "Settings" where it had just written `vi`. They share one collection now.
|
||||
Also: Dapper 2.1.86, Microsoft.Data.Sqlite / Microsoft.Extensions.Hosting / System.Diagnostics.EventLog 10.0.12,
|
||||
CsWin32 0.3.333, Roslynator 5.0.0, Meziantou.Analyzer 3.0.266, Microsoft.NET.Test.Sdk 18.10.1, NSubstitute 6.2.0.
|
||||
**Deliberately not moved:** `WPF-UI [4.3.0]` and `FluentAssertions [7.2.2]` (8.x is not an OSI licence), both pinned
|
||||
with their reasons in `Directory.Packages.props`. `legal/licenses/nuget/` is regenerated for the shipped packages
|
||||
that moved.
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.30 was cut, 2026-10-26 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.30] - 2026-10-26
|
||||
|
||||
**The thirtieth pre-release: Enter in the consent dialog, readable hardware-change markers, updated libraries, and the
|
||||
.NET 10.0.14 runtime.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run
|
||||
anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.29`:** Help ▸ Check for updates, then *Restart to update* with no game running — a download
|
||||
of about 5 MB. Nothing is shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger
|
||||
stays at schema 21, and no game is read again: the detection rules (`2026.10.4`) are beta.29's. This update is installed
|
||||
by beta.29's updater; the next one is the first that this release's updater installs.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Updated libraries, and a version conflict removed** (owner decision D71 for the updater). Velopack, the installer
|
||||
and updater, 1.2.0 → 1.2.161 with its packing tool: the update from beta.29 to this release is still installed by
|
||||
beta.29's updater, and the next one is the first this one installs. Markdig, which draws the documents the App shows,
|
||||
1.4.0 → 1.4.2 (parser fixes; its licence text is unchanged). The database's `SQLitePCLRaw` is again the version
|
||||
`Microsoft.Data.Sqlite` declares, 2.1.13: a pin kept since August for a security issue fixed since had put it on
|
||||
another major version with nothing to say so; the SQLite engine is 3.53.3 (it was 3.53.4). Not taken, each with its
|
||||
reason in `docs/13_CI_CD.md` §Dependabot and the NuGet audit: the .NET 10.0.14 packages (a day old), Markdig 1.5.0,
|
||||
CsWin32 0.3.366 and 0.3.367, `coverlet.collector` 10.1.0 and FluentAssertions 8.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Enter in the consent dialog declined, and the hooking switch then showed on beside "off"** (owner decision D69).
|
||||
The dialog's default button was *Keep hooking off* — the rule was "Enter never enables" — and WPF UI's template sends
|
||||
Enter to the default button, so typing `I ACCEPT THE INJECTION RISK` and pressing Enter kept hooking off without a
|
||||
word. Asked with that, the owner chose: Enter enables once the phrase is typed exactly, as a click on *Enable hooking*
|
||||
does, and does nothing before it; Esc and *Keep hooking off* still decline. The typed phrase is still the gate — the
|
||||
button Enter reaches stays disabled and hidden until the phrase matches — and no text of the dialog changed
|
||||
(`consent-dialog/1`). The game page's two switches, Hooking and Recording, now read their row again after every
|
||||
click: a click that changed nothing — the dialog declined, a refusal, no agent running — left the switch on while the
|
||||
text beside it said off, and the next click asked to enable again (`docs/19_SAFETY_AND_ANTICHEAT.md` §User-facing
|
||||
consent, `docs/08_UI.md` §Keyboard).
|
||||
- **A hardware change on a game's charts was cut off and hard to read** (owner decision D70). *Sessions at a glance* and
|
||||
the *Trend* marked each day the GPU driver, GPU, CPU, display or Windows changed with a dashed line labelled with the
|
||||
change itself — white on orange, its top cut off by the chart's edge, and a day with several changes showed one at
|
||||
most. Each such day now carries a number — 1 for the oldest, the same on both charts — in a band kept above the chart,
|
||||
dark on the orange in both themes, never cut off and never over another: badges too close for their lines stand aside,
|
||||
joined to them, and a run that still cannot stand side by side is one badge (*3–5*). The list under each chart gives
|
||||
each number's day and every change in full, and pointing at a line or a badge shows the same text. In en/vi/ja (ja
|
||||
marked for review). A click on *Sessions at a glance* now reads the pointer at the monitor's own scale
|
||||
(`docs/08_UI.md` §Games, §DPI).
|
||||
|
||||
### Security
|
||||
|
||||
- **The .NET runtime inside is 10.0.14**, Microsoft's out-of-band security release of 2026-10-25 (CVE-2026-111497, a
|
||||
Brotli decompression flaw; it also completes the SocketAsyncEventArgs fix, CVE-2026-70197, that 10.0.13 left
|
||||
incomplete). FrameLedger is self-contained, so
|
||||
it ships the runtime of the SDK that builds it: beta.29 carried 10.0.13; this release was built with SDK 10.0.403 and
|
||||
carries 10.0.14 — read from the published package's `FrameLedger.deps.json` in the release rehearsal.
|
||||
@@ -0,0 +1,24 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.31 was cut, 2026-10-26 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.31] - 2026-10-26
|
||||
|
||||
**The thirty-first pre-release: the remaining library updates.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.30`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown for you to accept again (the Disclaimer stays 2.11, the Privacy Policy 2.12), the ledger stays at schema 21, and
|
||||
no game is read again: the detection rules (`2026.10.4`) are beta.30's. This is the first update that beta.30's updater
|
||||
(Velopack 1.2.161) installs; if it downloads the whole package rather than a few megabytes, or the App does not come back,
|
||||
the installer on this page puts it right. What you see and what is recorded are beta.30's; the libraries under them are
|
||||
newer.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The remaining library updates** (the owner's request after beta.30, owner decision D72 — inside the seven-day wait
|
||||
the project otherwise keeps). The .NET 10.0.14 servicing packages the App and the agent use
|
||||
(`Microsoft.Extensions.Hosting`, `Microsoft.Data.Sqlite`, `System.Diagnostics.EventLog`; beta.30 already carried the
|
||||
10.0.14 runtime) and Markdig 1.5.0 (its licence text unchanged); for developers, the CsWin32 generator 0.3.367,
|
||||
Meziantou.Analyzer 3.0.317, `coverlet.collector` 10.1.0 — a test that reads every constant of three assemblies now
|
||||
leaves out the types the coverage tool adds to them — and Catch2 3.16.1 for the native tests. The SQLite engine stays
|
||||
3.53.3 (`SQLitePCLRaw` 2.1.13, which `Microsoft.Data.Sqlite` 10.0.14 still declares). Still not taken: FluentAssertions
|
||||
8, for its licence (`docs/13_CI_CD.md` §Dependabot and the NuGet audit).
|
||||
@@ -0,0 +1,45 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.32 was cut, 2026-10-31 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.32] - 2026-10-31
|
||||
|
||||
**The thirty-second pre-release: the alpha line's groundwork.** An *alpha* — the same program built on a version of .NET
|
||||
Microsoft has not finished, .NET 11 first — is published beside the betas from now on, and this beta carries what that
|
||||
needs; nothing in a beta's measuring changed. The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
|
||||
*More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.31`:** Help ▸ Check for updates, then *Restart to update* with no game running. The terms
|
||||
window shows the **EULA 1.6** and the **Disclaimer 2.12** once — each now says the builds are pre-releases, betas *and
|
||||
alphas*; nothing else in them moved — and the Privacy Policy stays 2.12. The ledger stays at schema 21 and the detection
|
||||
rules at `2026.10.4`. A beta never updates to an alpha: an alpha is installed only on purpose, from its own release page
|
||||
(the user guide's new page, *Alpha builds*).
|
||||
|
||||
### Added
|
||||
|
||||
- **The alpha line** (the owner's request of 2026-10-31, owner decisions D73–D76): an `alpha` branch builds this source
|
||||
on a prerelease .NET — .NET 11 RC3 first — and publishes it as `x.y.z-alpha.N` pre-releases on an update channel of
|
||||
their own, so a beta never updates to an alpha and an alpha never to a beta. What the line needs on main changes nothing
|
||||
in a beta: the `RELEASE_LINE` file and the line every assembly is stamped with (`Shared.BuildLine`), `release.yml`'s
|
||||
rule that an alpha is tagged on the alpha line and nowhere else and packed on Velopack's `alpha` channel, CI on the
|
||||
`alpha` branch, and no wiki publish for an alpha (`docs/12_BUILD.md` §The alpha line, `docs/13_CI_CD.md` §The alpha
|
||||
line, `docs/11_UPDATER.md` §Channels). Whether the main line ever leaves .NET 10 is an open question whose decision
|
||||
table is written before the evidence (`docs/20_OPEN_QUESTIONS.md` §G, *The main line's .NET*).
|
||||
- **An alpha says what it is, and asks first** (owner decisions D73 and D74; none of it shows in a beta). Its terms window
|
||||
shows the **Alpha notice** (`legal/ALPHA_NOTICE.md` 1.0) with the other documents and a box of its own to tick — *I
|
||||
understand that this is an experimental build and I use it at my own risk* — and Accept waits for it; until it is
|
||||
accepted the alpha's capture agent does not run. The title bar carries an **ALPHA** badge, a banner says what the build
|
||||
is at every start, Help ▸ About and `--diag` name the .NET it runs on, and its update channel is locked: an alpha updates
|
||||
only to newer alphas. It replaces the beta and shares its data, so before it first opens the database it copies it to
|
||||
`backups\ledger-before-<version>.db` (the newest three are kept) and does not open it if the copy cannot be made. The
|
||||
user guide has a page for it, *Alpha builds*, and `LIMITATIONS.md` a section.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The EULA (1.6) and the Disclaimer (2.12) say the builds are pre-releases — betas, and alphas** (owner decision D75):
|
||||
they said every build was a beta, which an alpha would make untrue. Nothing else in them moved; the terms window shows
|
||||
them once more after the update. About ▸ Legal documents lists the Alpha notice on every build, for information.
|
||||
- **What .NET 11's SDK asks of the source, taken where .NET 10 can take it too** (owner decisions D73–D76): the whole
|
||||
gate run on .NET 11 RC3 before the alpha line was cut found 21 places its analyzers flag — `LastIndexOf`,
|
||||
`StartsWith` and `EndsWith` of a single character, which .NET 11 overloads with a comparison; string sets and maps
|
||||
built with `[]`, which C# 15 can give a comparer; one undisposed `JsonDocument` in a test. Each is rewritten in a form
|
||||
both SDKs compile and that answers exactly as before (ordinal, as it was). Every test suite passed on .NET 11 with no
|
||||
change of answer (`docs/spike-notes/24-dotnet11-probe.md`).
|
||||
@@ -0,0 +1,71 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.33 was cut, 2026-11-03 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.33] - 2026-11-03
|
||||
|
||||
**The thirty-third pre-release: games from the Xbox app and the Microsoft Store.** PC Game Pass games included: Import
|
||||
library finds the games those apps installed, a game's page shows its own logo and splash image, **Play** starts one
|
||||
through Windows as its Start-menu tile does, and, with your consent, FrameLedger hooks it like any other game. How these
|
||||
games are laid out, how Windows starts them and what it lets another program read were measured first on the owner's
|
||||
eleven titles; a hooked session of one is still to be run. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.32`:** Help ▸ Check for updates, then *Restart to update* with no game running. The terms
|
||||
window shows the **Privacy Policy 2.13** once — it names what the Xbox library reads, that Play asks Windows to start
|
||||
such a game, and the two facts read from a game before any injection; the EULA and the Disclaimer do not change. The
|
||||
ledger stays at schema 21; the detection rules move to `2026.11.1`, so every game in the library is read again once.
|
||||
|
||||
### Added
|
||||
|
||||
- **Games from the Xbox app and the Microsoft Store** (the owner's request of 2026-11-03, owner decisions D77–D81; PC Game
|
||||
Pass games included): **Import library** finds the games those apps installed into a games folder — each drive's
|
||||
`.GamingRoot` names the folders, each game's own `MicrosoftGame.config` and `appxmanifest.xml` say what it is, and
|
||||
Windows says whether its package is installed for you — and lists them as **Xbox**, with the process that actually
|
||||
draws (an Unreal title's shipping executable, not the stub its package launches; never the GDK's `gamelaunchhelper.exe`).
|
||||
A game's page shows its own square logo and splash image, read from its folder, and its package version (*Xbox version
|
||||
1.3.5124.0*). Only games built on Microsoft's GDK are listed; an older Store app (UWP) is not (`docs/05_DETECTION.md`
|
||||
§Platform signatures & metadata, `LIMITATIONS.md`, the user guide). Everything was measured first, on the owner's eleven
|
||||
titles: the layout, and what Windows lets another program read there — every game executable refuses to be read, so no
|
||||
Unreal Engine version is shown for these games (`docs/spike-notes/25-xbox-gdk.md`).
|
||||
- **The detection rules know Xbox games** (rules `2026.11.1`, so every game in the library is read again once): an `xbox`
|
||||
platform, first in the list — a GDK FINAL FANTASY ships Steam's DLL and read *Steam* — decided by a new signal,
|
||||
`root_file`, from the install folder's own listing, so a very large install whose deep walk ran short still reads as
|
||||
its store (`docs/05_DETECTION.md`).
|
||||
- **Play starts a game from the Xbox app or the Microsoft Store through Windows** (D80), in either Play mode and from an
|
||||
App running as administrator: the user's shell activates the game's package as its Start-menu tile does
|
||||
(`explorer.exe shell:AppsFolder\<AUMID>`), because started by its path such a game is never the game in its package —
|
||||
measured on the owner's titles (`docs/spike-notes/25-xbox-gdk.md`). The capture agent refuses to start one by its path
|
||||
(`LaunchGame` answers `PackagedGame`), and the game is recorded once it appears, a few seconds after its start
|
||||
(`docs/04_CAPTURE.md`, `docs/08_UI.md`, `LIMITATIONS.md`).
|
||||
- **The anti-cheat guard says when a game cannot take the hook at all** (D78), read from the game's own token and code-protection
|
||||
settings just before the injection: `TargetAppContainer` — an older Microsoft Store app (UWP) — and `TargetMitigation` —
|
||||
only Microsoft- or Store-signed code, no generated code, a strict or non-CET-blocking user shadow stack, or strict Control
|
||||
Flow Guard. Neither is a finding: nothing is written to the game, and the session keeps its duration, the sensors and the
|
||||
reason. Each ended before as a failed injection, a hook that installed nothing, or a risk of ending the game, so no game
|
||||
that measured before is refused now (`docs/19_SAFETY_AND_ANTICHEAT.md`).
|
||||
|
||||
### Changed
|
||||
|
||||
- **The Privacy Policy is 2.13**, shown once at the next start: it names what the Xbox library reads — the games folders
|
||||
`.GamingRoot` names, each game's package files, Windows' answer whether its package is installed for you, and the
|
||||
pictures a game ships in its own folder — that Play asks Windows to start such a game, and that before any injection
|
||||
FrameLedger reads whether a game runs in an app container and which of Windows' code protections it runs under. The
|
||||
EULA and the Disclaimer do not change.
|
||||
- **The capture path reads a game's executable path one way** (for developers): `TargetResolver`, which finds the game again
|
||||
just before the guard, read the loader's spelling (`Process.MainModule`) where the watcher had the kernel's, so a game
|
||||
started through a junction could end `TargetNotRunning` about a process the watcher had just matched. Both read
|
||||
`ProcessImagePath` now, and the resolver still opens a candidate with the guard's own rights, so a process an anti-cheat
|
||||
driver closes stays `TargetUnreadable` (`docs/04_CAPTURE.md` §Process watcher).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The anti-cheat check saw only part of an Xbox game's folder** (safety): no install-root boundary matched the
|
||||
`<games folder>\<Game>\Content\` layout, so for an Unreal title's executable, three levels down, check 4 walked only its
|
||||
`Binaries\WinGDK` folder, and anti-cheat at the root of `Content` would have read clean. A GDK package root — the folder
|
||||
holding `MicrosoftGame.config` beside `appxmanifest.xml` — is now a boundary for the guard and for detection alike, used
|
||||
only where no store boundary matched, so it can only widen what is walked. The guard also gained `GamesInstalled\<X>`,
|
||||
which detection had had alone since #17; one case list read by both test suites now holds the two resolvers together
|
||||
(`docs/19_SAFETY_AND_ANTICHEAT.md`, `tests/fixtures/install-roots/cases.txt`).
|
||||
- **The second alpha's release would have stopped at its delta check** (for developers): Velopack names a non-default
|
||||
channel's packages with the channel (`FrameLedger.App-<version>-alpha-delta.nupkg`), and `release.yml` looked for the
|
||||
default channel's name. It now takes the delta the pack listed in `assets.<channel>.json`; the betas' packages are named
|
||||
as before (seen on the `0.1.0-alpha.1` rehearsal, which had no delta to make).
|
||||
@@ -0,0 +1,81 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.34 was cut, 2026-11-06 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.34] - 2026-11-06
|
||||
|
||||
**The thirty-fourth pre-release: DLSS 5 and DLSS 4.5 named from what the game and the driver did, filters on Games
|
||||
and Compare, and a Games page that opens at once.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.33`:** Help ▸ Check for updates, then *Restart to update* with no game running. The
|
||||
Disclaimer (2.13) and the Privacy Policy (2.14) are shown once for you to accept; the EULA does not change. The ledger
|
||||
moves to schema 22, which a beta.33 cannot open. The detection rules move to `2026.11.2`, so every game in the
|
||||
library is read again once. DLSS 4.5 under the NVIDIA App's *Dynamic* frame generation reads on sessions you already
|
||||
have; whether DLSS 5's neural rendering ran is kept for sessions recorded from now on.
|
||||
|
||||
### Added
|
||||
|
||||
- **Filters on Games and Compare** (owner request 2026-11-06, decision D85). Games: store, engine, state, installed and
|
||||
played, beside the search and sort, with *Clear filters*; the title counts what is shown of all. Compare: game, tier
|
||||
and frame generation over every session (it listed the newest 200), with a count; a ticked session stays listed.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The list of games FrameLedger has been run with is current again** (`docs/LIST_GAME_TESTED.md`, decision D35's
|
||||
method): refreshed from a copy of the owner's database taken 2026-11-06 and reviewed by the owner — fifteen more
|
||||
games measured hooked, among them Phantom Blade Zero under the NVIDIA App's *Dynamic* mode, Hogwarts Legacy loading
|
||||
DLSS 5's runtime and the first two Xbox app games — and the sessions recorded without measurement or refused by the
|
||||
guard since 2026-09-27. The guide's Settings page says a language change stays on Settings; the closed §S30 notes the
|
||||
fifth Streamline id decoded (`docs/open-questions/closed-s.md`).
|
||||
- **The Compare page's layout** (the owner's screenshot): the selection bar beside the list instead of a window's width
|
||||
away, with *Clear selection*; columns sized to what they hold — *Tier* and *FPS* touched, and wide gaps split the rest —;
|
||||
the date sorts by when; the settings-changed column says so in words or shows a dash (it was blank); the result
|
||||
table's session labels sit over their columns.
|
||||
- **The selected page keeps its name in the left pane** (D86): WPF UI's pane animates the selected item's label away
|
||||
(Compare's, in the screenshot — every page's while selected); FrameLedger uses a copy of its template without that.
|
||||
- **Games opens at once from any page** (owner request 2026-11-06: switching to Games stalled 0.5–1.5 s). The window
|
||||
keeps the library page it built and shows it again on every later visit, reading the library again behind it; the
|
||||
library is read off the UI thread; the cards appear before the executables are checked — a USB drive that sleeps
|
||||
took a second or more to answer, and no card was shown until every one had — and each card gets its *Not installed*
|
||||
pill when its check answers; a read keeps every card that would look the same instead of rebuilding them all; the
|
||||
list view builds only the rows on screen (`spike-notes` §27).
|
||||
- **Changing the language keeps the page you are on** — Settings, after a change made there. The App remembered only
|
||||
the pages it opened from code, so the language changed on Settings came back on the last game page opened
|
||||
(`src/FrameLedger.App/Services/ShellHost.cs`).
|
||||
- **DLSS 5 is named where the game ran it** (owner decision D84, amending D64). The owner's Hogwarts Legacy, Neural
|
||||
Rendering on, loaded DLSS 5's runtime (`nvngx_dlssnr.dll` 310.9.16.0, from the game's folder) and the session could say
|
||||
only *DLSS 5 runtime loaded* — nothing measured whether it ran. The Overlay's Streamline hook now decodes DLSS 5's
|
||||
feature (`kFeatureDLSS_NR`, Streamline 2.14) into its own per-frame fact, and the Agent keeps the share of the frames
|
||||
the game rendered through Streamline that carried it (`sessions.dlss_nr_pct`, **schema 0022** — a ledger this build
|
||||
migrated no longer opens in an earlier one). Seen running, the DLSS line reads *DLSS 5 (neural rendering on 97.3% of
|
||||
rendered frames)*, above every other generation; loaded and seen not running, *DLSS 5 runtime loaded, not seen
|
||||
running*; where nothing could tell (an earlier Overlay, a title outside Streamline), *DLSS 5 runtime loaded*, as
|
||||
before. Its library is listed with its version and source like the others, its Streamline plugin `sl.dlss_nr.dll`
|
||||
is recorded when loaded, and a game shipping either file shows *Supports DLSS 5 Neural Rendering* (rules
|
||||
`2026.11.2`, capability `dlss_nr`). The **Privacy Policy 2.14** names neural-rendering libraries among those whose
|
||||
versions are read; the **Disclaimer 2.13**'s accuracy block says when DLSS 5 is named. One hook-path change: one more
|
||||
compare in the `slEvaluateFeature` detour and one more test where a present is recorded (`spike-notes` §26).
|
||||
- **Streamline's headers are `v2.14.16`'s** (developers): the vendored copy was `v2.12.0`, byte for byte; three of its
|
||||
eleven files change — `kFeatureDLSS_NR`, the uplift buffer types 70–72, `kStructVersion7`, the version — and
|
||||
nothing FrameLedger consumed otherwise (`src/native/third_party/streamline/README.md`).
|
||||
- **A session under the NVIDIA App's *Dynamic* frame generation reads DLSS 4.5** (owner decision D83, amending D64).
|
||||
Dynamic and its ×6 mode exist only in DLSS 4.5, and the DLSS line named a generation from the measured multiplier
|
||||
alone: the owner's Phantom Blade Zero under *Dynamic, up to ×3* held ×2.0 and ×3.0 and read *DLSS 4 (a ×3.0
|
||||
frame-generation state)*. It reads *DLSS 4.5 (Dynamic multi frame generation, set in the NVIDIA App)* where the game's
|
||||
driver profile sets Dynamic, the driver reports its frame-generation override applied in the game's process, and DLSS
|
||||
Frame Generation was identified (whether or not its factor was counted); a state measured at ×5 or more still ranks first, and a *Fixed* multiplier names nothing
|
||||
by itself (The Witcher 3 under Fixed ×6 still presented ×2.0). The game page's chip and the CSV's `# dlss:` line
|
||||
(`basis=dynamic_frame_generation`) follow; the **Disclaimer 2.13** says so in its accuracy block
|
||||
(`src/FrameLedger.Domain/Detection/DlssGeneration.cs`, `src/FrameLedger.App/Services/DlssText.cs`; `spike-notes` §26).
|
||||
- **The guard's source reads in order again** (developers only; no behaviour changes): the note that says what runs only
|
||||
for a target the anti-cheat evaluation allowed sits above the function it describes again — beta.33's two isolation
|
||||
checks had come between them — and names that isolation check among what runs
|
||||
(`src/native/FrameLedger.Injector/src/fl_guard.cpp`).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An Xbox game's page no longer fails on a strange picture name** in the game's own `MicrosoftGame.config` (beta.33's):
|
||||
a name that points at a stream of a file (`a:b.png`) made the search for its scaled variants throw — the page then
|
||||
showed no picture and logged an error, and an action on the page that reloads it could end in the crash report. Such a
|
||||
name is no picture a package ships, so it is passed over like a name outside the package
|
||||
(`src/FrameLedger.Infrastructure/Art/XboxArtCache.cs`). Found by a self-review of #351 and #352 after their gates
|
||||
passed; no install of the owner's eleven titles has such a name.
|
||||
@@ -0,0 +1,91 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.35 was cut, 2026-11-09 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.35] - 2026-11-09
|
||||
|
||||
**The thirty-fifth pre-release: accessibility.** An accessibility statement (Help ▸ Accessibility); a screen reader
|
||||
that reads every control and value in its words and is told what appears; headings and charts it can use; Windows
|
||||
contrast themes followed; the keyboard following a page shortcut, and a message box opening over the window. And three
|
||||
places where text read below WCAG's 4.5:1 in a Fluent theme, found on the way: the agent's pill, two kinds of short
|
||||
message, a destructive button. The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info →
|
||||
Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.34`:** Help ▸ Check for updates, then *Restart to update* with no game running. The legal
|
||||
texts keep their versions, so nothing is shown for you to accept; the ledger stays at schema 22 and the detection rules
|
||||
at `2026.11.2`. Nothing about capture or measurement changes.
|
||||
|
||||
### Added
|
||||
|
||||
- **An accessibility statement** (owner request 2026-11-09, decision D88). `ACCESSIBILITY.md` says what FrameLedger aims
|
||||
for — WCAG 2.2 at level AA as W3C's WCAG2ICT applies it to desktop software, a goal and not a claim of conformance —
|
||||
what works with the keyboard alone, a screen reader, a contrast theme or Magnifier, how it is checked (the project's
|
||||
tests, and the owner's pass of 2026-11-09: keyboard only and Narrator on 0.1.0-beta.34 and 0.1.0-alpha.3, no fault),
|
||||
what does not work yet and what to do instead, and how a barrier is reported and handled — by severity, with no
|
||||
promised times. The app shows it under **Help ▸ Accessibility**, and after Limitations in the user guide's window; the
|
||||
wiki gets an *Accessibility* page.
|
||||
- **An *Accessibility problem* issue form** (`.github/ISSUE_TEMPLATE/accessibility.yml`) asking what was tried, what
|
||||
happened and what the reporter uses — never anything about the reporter themself — and a user-interface section in the
|
||||
pull-request template. The `accessibility` label exists, and so do `safety` and `priority-high`, which the *Safety gap*
|
||||
form had named since its first day without either existing — so GitHub had never applied them.
|
||||
|
||||
- **A screen reader reads what the window shows** (decision D88's goal; measured in the UI Automation tree WPF builds on
|
||||
every page, window and dialog, every tab — `PagesLoadTests.Automation`). Drop-down options were read as an internal
|
||||
record (*Choice { Value = dark, Label = Dark }*), lists and table rows by their program names, table cells drawn by a
|
||||
template as *Item: …, Column Display Index: n*, and the terms window's list by each document's whole text; each now
|
||||
reads the words it shows, and an empty cell reads *empty*. The frame-rate readout says Native, Displayed and the
|
||||
factor together (CLAUDE.md rule 6, in speech), a ray-tracing chip its value and where it came from, a change badge its
|
||||
number. The safety notices' title and message reach a screen reader (they were hidden inside the notice's template),
|
||||
and the notice's button says which notice it answers. A button repeated on each row names its row (*Open: …*, *Play:
|
||||
…*, *Turn off: …*). Tab no longer stops on pictures, lists, Settings' rows, the FPS readout, the chips or the dialog
|
||||
host, where it found nothing to say; an expander's button is named after its header.
|
||||
|
||||
- **A screen reader is told what appears** (owner decision D89): a safety notice as it arrives, the capture agent going
|
||||
offline and coming back, an update's steps (not each percent), every short message at the bottom of the window, a
|
||||
notice on a game's page and each result of Tools ▸ Database maintenance — in the words shown, and only while
|
||||
FrameLedger's window is the active one, so a game that has the screen is never interrupted. The database line's live
|
||||
region, which announced nothing, is gone.
|
||||
|
||||
- **Headings and charts a screen reader can use** (owner decision D90). Every page's title is a first-level heading and
|
||||
each section title a second-level one, so a screen reader's heading keys move between sections. Every chart says what
|
||||
it is and where its numbers are written as text; its keys — arrows to move, Ctrl with an arrow to zoom, A to see all of
|
||||
it — now stay with the chart instead of also scrolling the page or moving the focus on, and its focus is drawn. No
|
||||
chart tells two series apart by colour alone any more: Compare's five sessions, the GPU's temperature and its hot spot,
|
||||
the two kinds of stutter, the two lows and the two limits each have their own line pattern, marker or hatch.
|
||||
|
||||
- **Windows contrast themes are followed** (owner decision D91). With a contrast theme on — Aquatic, Desert, Dusk, Night
|
||||
sky, or one whose colours were edited, on Windows 10 or 11 — every colour in FrameLedger's windows is one of that
|
||||
theme's, whatever Settings ▸ Theme says, and it changes the moment the theme is turned on, edited or turned off;
|
||||
Settings ▸ Theme says so under its box. Before, *System* could apply WPF UI's own high-contrast files, most of whose
|
||||
colours are a red placeholder, and the next window opened put the light or the dark theme back. The charts draw in the
|
||||
theme's colours, their patterns telling the series apart; the frame-generation, ray-tracing and upscaler chips are the
|
||||
theme's highlight and its text (WPF UI's files put the window text there, 1.26–1.78:1); a destructive button is the
|
||||
theme's own button; a pressed menu item is no longer white on white; nothing is drawn translucent, and a game's picture
|
||||
lends its page no colour, as before.
|
||||
|
||||
- **The keyboard follows a page shortcut.** **Ctrl+1** … **Ctrl+5** now move the focus into the page they open — its
|
||||
first control — and a screen reader hears the page's title; before, the focus stayed where it was, often on the page
|
||||
that had just gone, and Tab began again at the top of the window.
|
||||
- **Pages no longer slide in while Windows' animation effects are off** (Settings ▸ Accessibility ▸ Visual effects),
|
||||
followed as the setting changes.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A message box opens over FrameLedger's window** — Remove game, Delete sessions, the database's and the update's
|
||||
questions. It had no owner, so it could fall behind the window it came from and, closing, give the focus to another
|
||||
program; it is owned by the window that opened it now, and the focus comes back there.
|
||||
- **A double-click on a chart shows all of it again**, as the user guide said; it toggled ScottPlot's render-time overlay.
|
||||
- **The capture agent's state in the title bar reads in the light theme.** It was drawn on WPF UI's fixed green, blue,
|
||||
orange and red under white — 2.78, 2.63, 2.16 and 3.68:1 — and is on the theme's own success, caution and critical
|
||||
fills now, as the notices are; its words say the state.
|
||||
- **The short messages at the bottom of the window read.** A *done* or a *warning* message was white on a fixed green or
|
||||
orange, 2.78:1 and 2.16:1 in both themes; every message is in the theme's colours now, its icon saying which kind.
|
||||
- **A destructive button's label reads in the dark theme** — Remove on a game's page, Delete in the confirmations: the
|
||||
theme's dark text on the red, 5.3:1 and 5.7:1, where white read 3.68:1.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Documents corrected**: charts do take focus and keys (`docs/08_UI.md` said neither — `ChartKeyboardTests` measures
|
||||
it); the database-maintenance result's live region announced nothing, since WPF raises one only when the app does; the
|
||||
"no Narrator pass" gap is the owner's pass now, beside what that pass could not show; the open question "Accessibility
|
||||
/ DPI: no design anywhere" is closed; NFR-9 names screen readers and contrast themes (D88–D91). `LIMITATIONS.md` gains an
|
||||
*Accessibility* section and loses its one struck sentence — a screen reader reads struck text as current, so no page
|
||||
the app shows strikes text through. The guide's menu table names its menu on every row, read one row at a time.
|
||||
@@ -0,0 +1,41 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.36 was cut, 2026-11-10 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.36] - 2026-11-10
|
||||
|
||||
**The thirty-sixth pre-release: the same software, its C# read by a second analyser and tidied.** Nothing you see,
|
||||
record or measure changes. Qodana — JetBrains' code analysis — now reads the C# and the XAML of every change, and what
|
||||
its first run reported is settled: about 400 small corrections in the code, none changing what the program does. The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.35`:** Help ▸ Check for updates, then *Restart to update* with no game running. The legal
|
||||
texts keep their versions, so nothing is shown for you to accept; the ledger stays at schema 22 and the detection rules
|
||||
at `2026.11.2`. Nothing about capture or measurement changes.
|
||||
|
||||
> **Added the day of the release, after the tag (2026-11-10).** The package carries the **.NET runtime 10.0.15**, where
|
||||
> beta.35's carried 10.0.14: the release was built with SDK 10.0.404, November's servicing release, which the build
|
||||
> machine had that day (10.0.403 the day before), and `global.json` lets a build take the newest 10.0 SDK. Nothing in
|
||||
> FrameLedger's own code asked for it, and the notes above did not name it when the tag was cut. It is why the update
|
||||
> from beta.35 replaces 343 of the package's 456 files (a 5.8 MB download). The NuGet libraries stay at their 10.0.14
|
||||
> versions.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Qodana reads the C# and the XAML from CI** (developers only; owner decision D93). The owner made the project on
|
||||
Qodana Cloud and set the `QODANA_TOKEN` secret; `.github/workflows/qodana.yml` is JetBrains' workflow for its Qodana
|
||||
Scan action, changed where FrameLedger differs: the linter is Qodana Community for .NET — ReSharper's inspections in
|
||||
a Linux container, which runs under every licence, where the Rider-based linter needs the Ultimate licence the
|
||||
organisation holds only as a 30-day trial — over `FrameLedger.slnx`, with `EnableWindowsTargeting` passed to the
|
||||
container so that the Windows-only projects build and load there; the action is pinned to a commit; the job's
|
||||
permissions are the ones it uses. It reads no C++ (CodeQL and SonarCloud do). Its gate is zero problems
|
||||
(`qodana.yaml`), and it is advisory: a red job beside a green `check`, never a blocked merge. An inspection that
|
||||
argues with a choice this project made is switched off in `.editorconfig`, where Rider reads it too, with the reason
|
||||
on the line above — sixty-three keys (`docs/13_CI_CD.md` §Qodana).
|
||||
- **What Qodana's first run reported is settled** — 3,679 problems, 2,050 of them the missing-XML-comment warning the
|
||||
project had already made a suggestion. About 400 were fixed in the code, in 181 files, none changing what the
|
||||
software does: redundant qualifiers, casts, `using` directives, `!` suppressions and `unsafe` modifiers removed (290);
|
||||
`var` for built-in types and one-line block bodies brought to `.editorconfig`'s own style (52); every XAML item
|
||||
template names its `DataType`, and a binding that reached its page through `DataContext.ViewModel` names the page's
|
||||
type (35), so the editor resolves them; two fields nothing read (`LogsViewModel`, `PipeServer.Client`), two
|
||||
initialisers a constructor overwrote and an unused parameter removed; `SpokenTextAutomationPeer` no longer assumes
|
||||
the base peer's name is a string. The members nothing in the solution uses are listed in `docs/13_CI_CD.md` §Qodana
|
||||
and left as they are.
|
||||
@@ -0,0 +1,77 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.37 was cut, 2026-11-11 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.37] - 2026-11-11
|
||||
|
||||
**The thirty-seventh pre-release: FrameLedger runs on .NET 11.** The same program, built on .NET 11.0.0 — released the
|
||||
day before — where every beta until now was built on .NET 10 (owner decision D94). Nothing about how a game is measured
|
||||
changes: the part of FrameLedger loaded into a game is native code, and it is 0.1.0-beta.36's. What changes is what
|
||||
FrameLedger needs from your PC, and two of its legal texts. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Before you update from `0.1.0-beta.36`, three things:**
|
||||
|
||||
- **Your processor.** .NET 11 does not start on a processor without SSE4.2 and POPCNT. Every processor Windows 11
|
||||
accepts has them; one from before about 2010 may not. On such a PC this version installs and then does not start, and
|
||||
0.1.0-beta.36 cannot check that for you. Installing 0.1.0-beta.36 again brings FrameLedger back, with your data as it
|
||||
was.
|
||||
- **Windows 10.** Microsoft supports .NET 11 on Windows 11, and on Windows 10 only in its LTSC and IoT editions.
|
||||
FrameLedger does not block Windows 10 22H2 — but it has never been tested there, on any version, and nobody supports
|
||||
it there (D95).
|
||||
- **The update is a large download** — about 70 MB, where a usual one is a few: the .NET runtime inside the package is
|
||||
replaced whole.
|
||||
|
||||
Then: Help ▸ Check for updates, and *Restart to update* with no game running. **The terms window appears once**, with
|
||||
the **EULA 1.7** and the **Disclaimer 2.14** to accept — what an alpha build is, now that .NET 11 has shipped, and a
|
||||
paragraph on Windows and the processor. The ledger stays at schema 22 and the detection rules at `2026.11.2`, so going
|
||||
back to 0.1.0-beta.36 is installing it over this version.
|
||||
|
||||
**For anyone on an alpha:** `0.1.0-alpha.4` follows this release on the same .NET 11.0.0, and after it the alphas pause
|
||||
— install the beta (`guide/11-alpha-builds.md`).
|
||||
|
||||
### Changed
|
||||
|
||||
- **FrameLedger runs on .NET 11** (owner decisions D94 and D95, 2026-11-11). The betas are built on .NET 11.0.0 —
|
||||
released 2026-11-10 — where they were built on .NET 10: SDK 11.0.100, `net11.0-windows10.0.22621.0`, and the three
|
||||
libraries serviced with the runtime (`Microsoft.Extensions.Hosting`, `Microsoft.Data.Sqlite`,
|
||||
`System.Diagnostics.EventLog`) at 11.0.0. The runtime is inside the package as before; nothing is installed beside
|
||||
it. **What a user should know:** Microsoft supports .NET 11 on Windows 11, and on Windows 10 only in its LTSC and
|
||||
IoT editions — FrameLedger does not block Windows 10 22H2, and it is untested and unsupported there; **on a
|
||||
processor without SSE4.2 and POPCNT it no longer starts** (every processor Windows 11 accepts has them); the
|
||||
ledger's schema is unchanged, so installing 0.1.0-beta.36 again is a way back. The part of FrameLedger loaded into
|
||||
a game is native code and does not change. `docs/12_BUILD.md` §The main line's .NET says what decided the move
|
||||
and what was set aside.
|
||||
- **The capture agent ends with a crash report when a piece of its own background work fails**, where it used to
|
||||
stop and exit as if nothing had happened: .NET 11 passes that failure on, and the Agent's existing crash path — a
|
||||
Fatal log entry and a crash dump — takes it. Nothing was added for it (`docs/10_LOGGING_AND_BUG_REPORTS.md` §Crash
|
||||
handling).
|
||||
- **The NuGet licence texts follow the package set** (`legal/licenses/nuget/`, 69 packages where there were 78):
|
||||
nine `Microsoft.Extensions.*` libraries are part of the .NET 11 runtime, and SQLite's engine is SourceGear's
|
||||
`SQLite` package through SQLitePCLRaw 3.0.5.
|
||||
- **For developers:** `release.yml` installs a .NET 10 runtime beside the SDK for `vpk` 1.2.161, which has no build
|
||||
that runs on .NET 11 alone; Qodana's container installs the .NET 11 SDK before it builds (an interim, until the
|
||||
Ultimate linter); two `string.StartsWith`/`EndsWith(char)` calls in the App's tests name the comparison .NET 11's
|
||||
analyzer asks for; `HostBackgroundFailureTests` holds .NET 11's `IHost.RunAsync` behaviour.
|
||||
- **What an alpha is, now that .NET 11 has shipped** (owner decisions D97 and D98). Until 0.1.0-alpha.3 an alpha was
|
||||
"a beta's source built on a prerelease .NET", and every text said so. 0.1.0-alpha.4 runs on .NET 11's release — the
|
||||
betas' own from this version — so an alpha is now described as *a beta's source built to try a newer version of
|
||||
.NET, at times a prerelease one*: **EULA 1.7** (§2B), **Disclaimer 2.14** (§0, which also gains a paragraph on
|
||||
Windows and the processor), **Alpha notice 1.1** (what an alpha is, the hardware, and a new part on the pause), the
|
||||
accuracy statement's line, the guide and `LIMITATIONS.md`. The terms window shows the EULA and the Disclaimer once
|
||||
more; an alpha asks for its notice's tick again.
|
||||
- **The alphas pause after 0.1.0-alpha.4, and a paused alpha says so** (D98). With the betas on the same .NET there is
|
||||
nothing for an alpha to try, so none is published until a newer .NET has a preview — and a paused alpha gets no
|
||||
update, the anti-cheat list included, which reaches FrameLedger only inside one. An alpha cut while the line rests
|
||||
shows, above every page, that the line is paused and to install the latest beta; the words "a prerelease .NET" now
|
||||
appear only in an alpha that really runs on one. For developers: `FlAlphaLineRests` in `Directory.Build.props`,
|
||||
stamped into every assembly, `Shared.AlphaLine`, `App/Services/AlphaTexts`; three new strings in en, vi and ja.
|
||||
- **.NET 11's API where it reads better, and no C# 15 syntax yet** (developers only; owner decision D96). Sixteen
|
||||
`char` searches name their comparison through the `string` overloads .NET 11 adds
|
||||
(`StartsWith`/`EndsWith`/`LastIndexOf(char, StringComparison)`) where they went through a span to satisfy both .NET
|
||||
10 and 11, and the App finds the Agent it started with `Process.TryGetProcessById` instead of a caught exception;
|
||||
nothing changes in what the software does. **C# 15's constructs were asked for and are not used**: each was tried in
|
||||
a file of its own, and ReSharper's engine — what Qodana runs — reads none of the four (it does not parse `closed`
|
||||
or `union`, and calls collection expression arguments and labeled jumps preview features), so every file using one
|
||||
would be an error on a gate of zero; a union also draws a warning from the SDK's own analyzers.
|
||||
`docs/13_CI_CD.md` §C# 15 and the analyses holds the table and what unblocks each; `docs/spike-notes/29-…` where
|
||||
each would go. `codeql.yml` takes `workflow_dispatch`, so a branch can have a full analysis — a pull request's C#
|
||||
analysis is an overlay on `main`'s database.
|
||||
@@ -0,0 +1,69 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.38 was cut, 2026-11-11 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.38] - 2026-11-11
|
||||
|
||||
**The thirty-eighth pre-release: the App opens web and mail links only.** One small hardening, and nothing else you
|
||||
see, record or measure changes. The one place in the App that hands a link to Windows now refuses any address that is
|
||||
not `http`, `https` or `mailto`, where it trusted each caller to have checked — Windows runs whatever it is handed, and
|
||||
a `file:` address is a program. Every link the App shows already was one of those three, so no link you could click
|
||||
before stops working. The rest of this release is for developers: Qodana — JetBrains' code analysis — now reads the C#
|
||||
with its Rider-based linter and, as a second report, the C++. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.37`:** Help ▸ Check for updates, then *Restart to update* with no game running. The legal
|
||||
texts keep their versions, so nothing is shown for you to accept; the ledger stays at schema 22 and the detection rules
|
||||
at `2026.11.2`. Nothing about capture or measurement changes: the code FrameLedger loads into a game is
|
||||
0.1.0-beta.37's, line for line.
|
||||
|
||||
**No alpha follows this release**: the alpha line rests (`guide/11-alpha-builds.md`).
|
||||
|
||||
### Changed
|
||||
|
||||
- **Every place that starts a process was read, and the App now opens web and mail links only.** JetBrains' rule for
|
||||
"a process started with something that is not a literal" reported 35 places — 11 in the product, 24 in tests. Each
|
||||
was read: what it starts, and where the path and the arguments come from (the table in `docs/13_CI_CD.md` §Qodana).
|
||||
None takes a value from outside the PC or from a file FrameLedger did not write, except the path and arguments of
|
||||
the game the user added. One was hardened: `ShellUrlOpener` — what opens a link in the browser or the mail client —
|
||||
now refuses any address that is not `http`, `https` or `mailto` itself, where it trusted each caller to have
|
||||
checked; the shell runs whatever it is handed, and a `file:` address is a program. Every caller already passed one
|
||||
of the project's own pages or a link held to those schemes, so no link you could click before stops working. The
|
||||
rule stays on: the files its results were read in are listed in `qodana.yaml`, so a new file that starts a
|
||||
process is reported — by path on the plugin's one inspection, since a rule's own id is honoured nowhere (three
|
||||
runs measured it). And a test of the repository's own, `ProcessStartSitesTests`, in the gate, fails on a new file
|
||||
that starts a process, or registers a scheduled task, until it has been read and listed.
|
||||
- **Qodana for .NET, on the Ultimate licence, reads the managed code** (developers only; owner decisions D99 and D100).
|
||||
The owner took an Ultimate licence for the Qodana Cloud organisation and asked for Qodana over every language. The
|
||||
job — `managed`, *Qodana (managed)* in a pull request's checks — now runs Qodana for .NET (Rider's engine) in native
|
||||
mode on a Windows runner, after a `dotnet build`, where the Community linter ran in a Linux container. Besides the
|
||||
C#, the XAML and the `.resx` it reads the Markdown and XML around the solution, and JetBrains' security rules read
|
||||
the C#. Its first run reported 3,953 problems, 3,607 of them **hints** — the level an editor offers without
|
||||
underlining anything, which the Community linter never reported; hints are off as a severity. Of the 347 left: a vi
|
||||
or ja string equal to the English one (271) is off in `.editorconfig` for `.resx` files — names, units and format
|
||||
strings are not translated; two Markdown inspections (table padding, and anchors computed otherwise than GitHub
|
||||
does) and the application manifest's XML are off in `qodana.yaml`; six results in `PrimaryDisplay.cs` are the
|
||||
linter's own fault (an internal assertion, in its log) and are excluded for that file; one test expression was
|
||||
simplified. The gate stays zero problems and the job stays advisory. An inspection is now switched off **where the
|
||||
engine that raised it reads** — one of ReSharper's in `.editorconfig`, what has no key there in `qodana.yaml` — which
|
||||
amends D93's "never in `qodana.yaml`" (`docs/13_CI_CD.md` §Qodana). The C++ goes to a second report, the next pull
|
||||
request's.
|
||||
- **Qodana reads the C++ too, as a second report** (developers only; owner decision D99). The job `native` has CMake
|
||||
write a Visual Studio solution for `src/native` (the preset `x64-vs-analysis`; nothing ships from it) and runs
|
||||
Qodana for .NET over it — ReSharper's C++ inspections and the clang-tidy checks they bundle — with settings of its
|
||||
own (`qodana-native.yaml`), reporting to a Qodana Cloud project of its own. Its first run reported 4,695 problems,
|
||||
4,040 of them hints; of the 655 left, 494 are distinct (a file compiled into three targets is reported three
|
||||
times). Nearly all of them are not faults, and `.editorconfig` now says why in fifty-four lines, each with its
|
||||
reason: clang's opinion of code that only MSVC builds (`__try`, a function pointer got by name, struct padding);
|
||||
the engine misreading `std::atomic_ref`, zero-initialised API structures and tests of `constexpr` functions;
|
||||
proposals to restate working code in a newer idiom; and what a probe or a test does on purpose. Eleven things
|
||||
were fixed, none changing what a shipped binary does: `std::size` for four hand-written array lengths, two
|
||||
multiplications done in a narrower type than their result, two unused member functions, an unused type alias, two
|
||||
unused includes. **In code loaded into a game nothing was changed**: the report found no defect there, and what it
|
||||
did say about those files is listed in `docs/13_CI_CD.md` §Qodana — among it one function in the Overlay that
|
||||
nothing calls (`LogNoteW`), which is recorded for the owner and not removed (D100). The gate is zero problems and the job is advisory, like the other.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A test that failed on a busy machine** (developers only). `ShmDrainIntegrationTests`' drain under supervision
|
||||
ended after one guard evaluation whenever the first scan was slow enough for fifty presents to be waiting, and
|
||||
then failed its own "supervised more than once"; the loop now supervises at least twice whatever the first
|
||||
drain holds.
|
||||
@@ -0,0 +1,125 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.39 was cut, 2026-11-11 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.39] - 2026-11-11
|
||||
|
||||
**The thirty-ninth pre-release: Advanced metrics.** A new setting, **off unless you switch it on** — Settings ▸
|
||||
Recording ▸ *Advanced metrics* — and a page of its own. With it on, the capture agent reads more from the graphics
|
||||
driver and the hardware sensors during a session and keeps it with the session: the graphics card's memory, load,
|
||||
clocks, fans, voltages and power in detail; what each display can do with HDR and variable refresh, and what the
|
||||
game's display did; the driver's settings, global and for the game; and — when the agent runs as administrator with
|
||||
PawnIO installed — the processor per core, the memory and the motherboard's sensors. The **Advanced** page (the last
|
||||
item on the left, **Ctrl+6**) shows it under what it belongs to: **This PC**, read only while the page is open and
|
||||
never stored; **Session**, what one session kept, in tables and a chart; **Sources**, every reading FrameLedger knows
|
||||
of and, for each one it does not read, why. With the setting off, nothing more is read or stored and the page is not
|
||||
there. The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**What it is not, yet.** None of these readings has been checked against another tool. The processor's, the memory's
|
||||
and the motherboard's sensors have never been read on real hardware — the first run as administrator with PawnIO is
|
||||
still to come. The driver's own figures exist on NVIDIA cards only, and no AMD or Intel card was tested. A drive's
|
||||
temperature is not read. Nothing is read inside the game by this release: the readings that need a hook come with
|
||||
later ones. `LIMITATIONS.md` §Sensors lists every limit.
|
||||
|
||||
**Updating from `0.1.0-beta.38`:** Help ▸ Check for updates, then *Restart to update* with no game running. The terms
|
||||
window shows the **Privacy Policy 2.15** and the **Disclaimer 2.15** once — they name what Advanced metrics reads and
|
||||
stores, only while it is on, and that PawnIO and the administrator mode then read more than the CPU temperature. The
|
||||
ledger moves to **schema 23** (two tables are added; nothing that was there changes), so a 0.1.0-beta.38 cannot open
|
||||
it afterwards. The detection rules stay at `2026.11.2`. With the setting off, nothing about capture or measurement
|
||||
changes: the code FrameLedger loads into a game — the overlay, the Vulkan layer, the shared-memory layout, the
|
||||
injector — is 0.1.0-beta.38's, line for line.
|
||||
|
||||
*The entries below are in the order the seven pull requests landed. One that says "not yet" describes that pull
|
||||
request; a later entry is what followed.*
|
||||
|
||||
### Added
|
||||
|
||||
- **"Advanced metrics" is planned, and its inventory is written — nothing reads it yet.** The owner asked for a
|
||||
setting, *Thông số nâng cao*, with a navigation item of its own that shows as much as the NVAPI and Streamline
|
||||
headers and PawnIO make available, each value under what it belongs to: one game session, or the PC. This pull
|
||||
request is the first of that train and changes nothing you can see or record. It adds the list everything else in
|
||||
the train reads — `AdvancedMetricCatalog`, 137 entries: what the Agent will read from NVAPI and
|
||||
LibreHardwareMonitor (the card's firmware, architecture and cores; its memory with evictions and promotions; its
|
||||
utilisation by domain; what a display can do with HDR and variable refresh; the driver's profile; and, as
|
||||
administrator with PawnIO, the processor per core, the motherboard, the memory modules and the drives'
|
||||
temperatures), what can only be read inside a game and waits for a later release, **and what is never read with the
|
||||
reason** — a serial number, a display's EDID, the list of programs that are encoding, the camera's position, what
|
||||
a vendor's licence closes. `docs/18_GPU_VENDOR_APIS.md` §Advanced metrics holds the design, the owner's decisions
|
||||
D101–D108 and the same list as a table; a test fails when the table and the catalog differ in either direction.
|
||||
|
||||
- **The NVIDIA bridge can read what Advanced metrics will show — and nothing calls it yet.**
|
||||
`FrameLedger.NvapiBridge.dll`, the library the Agent loads into its own process and never into a game, gains five
|
||||
reads (its ABI 3): the card's facts — firmware version, architecture, ray-tracing and tensor core counts, base and
|
||||
boost clocks, its memory sizes, the driver's package; what it says now — free and used video memory with evictions
|
||||
and promotions, the frame-buffer, video and bus utilisation, the performance state, the encoder's load; what each
|
||||
connected display can do with HDR and variable refresh; the state of the display a game presents on; and every
|
||||
setting of a driver profile. On the development PC's RTX 5080 all twenty facts and eight of the ten live groups
|
||||
answer — the card has no board or power-supply temperature sensor, so those two will read N/A.
|
||||
**It reads no identifier**: no serial number, no unique id, no display EDID, and not which programs are encoding.
|
||||
- **"The bridge never calls a setter" is now a build check.** A new gate, `tools/nvapi-readonly-check.ps1`, compares
|
||||
every NVAPI call in the bridge's source with a committed list of forty-four reads, in both directions, and refuses a
|
||||
name that sets, saves, restores, registers or controls something — or returns an identifier — even when someone
|
||||
adds it to the list.
|
||||
|
||||
- **The reader behind Advanced metrics exists, was measured on a real PC, and is still not switched on.** One
|
||||
reader for the whole Agent, on a thread of its own, that runs only while a session or the page needs it: NVIDIA's
|
||||
figures every second, and every sensor LibreHardwareMonitor has for the graphics card — each fan and its duty, the
|
||||
core voltage, PCI Express traffic, the load of every engine. When the Agent runs as administrator with PawnIO
|
||||
installed it will also read the processor per core, the memory and the motherboard's sensor chip.
|
||||
**A drive's temperature is not read**: the library cannot list drives without touching removable ones, so that
|
||||
group is never opened and the value will read N/A with that reason.
|
||||
- **`FrameLedger.CaptureHost probe-advanced`** (a developer tool, not shipped): runs that reader for a few seconds
|
||||
on your own rights and prints everything it read and what it cost. On the development PC it read 35 facts and 58
|
||||
values a second — and showed that one refresh of the sensor library takes 14 ms of processor time, so the reader
|
||||
refreshes it every five seconds, where NVIDIA's own figures (0.4 ms) stay at one a second.
|
||||
|
||||
- **The ledger can hold Advanced metrics — and holds none yet.** Schema 23 adds two tables: one for the facts of
|
||||
the PC, stored once per distinct set, and one for what a session recorded with the option on knows — its own
|
||||
facts, which sources answered and why the others did not, and the statistics of its extra series. Nothing is
|
||||
added to the session row itself, so what the JSON export and a bug bundle carry does not grow. The extra series
|
||||
are stored beside the others under names of their own, with a real "no reading" for a second in which a sensor
|
||||
was not read. One hour of them is about 0.2 MB. **A session recorded with the option off stores nothing of this**,
|
||||
and the option does not exist yet. *A 0.1.0-beta.38 cannot open a ledger a later build has migrated.*
|
||||
|
||||
- **Settings ▸ Recording ▸ Advanced metrics — the switch exists, off by default.** On, the capture agent reads more
|
||||
from the graphics driver and the hardware sensors during a session and stores it with the session: the graphics
|
||||
card's memory, load, clocks, fans, voltages and power in detail, what each display can do with HDR and variable
|
||||
refresh and what the game's display did, the driver's settings for the game — and, when the agent runs as
|
||||
administrator with PawnIO installed, the processor per core, the memory and the motherboard's sensors. **Off,
|
||||
nothing more is read or stored**, and the shared reader is not even started. It applies from the next session, and
|
||||
a session recorded while it was off is not filled in later. NVIDIA's figures are read once a second, the sensors
|
||||
every five. **No page shows what is stored yet** — that is the next pull requests' — and none of it is in an
|
||||
export or a bug report.
|
||||
- **The App can ask the agent what this PC reads right now — and no page asks yet.** A new request,
|
||||
`GetAdvancedMachine`, answers what the agent's shared reader last read: the PC's facts, the newest value of every
|
||||
series, and which sources answer or why they do not. It never touches a sensor itself, so it cannot hold up the
|
||||
pipe. Each request also keeps the reader running for five seconds, which is how "with no game running, sensors are
|
||||
read only while the page is open" works without anything telling the agent that a page closed. With Advanced
|
||||
metrics off it answers that it is off, and nothing is read. On the App's side `AdvancedMachineFeed` asks once a
|
||||
second while a page watches it and keeps each value with the moment it was read.
|
||||
- **The Advanced page.** While Advanced metrics is on, **Advanced** is the last item in the list on the left, and
|
||||
**Ctrl+6** opens it. **This PC** shows what the graphics driver and the sensors say right now — the card's
|
||||
firmware, cores and memory, what each display can do, the driver's settings, and every reading with the time it
|
||||
was read at and a chart of its last five minutes. It is read only while the page is open, and is not stored.
|
||||
**Session** shows what a session recorded with the option on kept: the PC as it was, what belonged to that session,
|
||||
the lowest, average and highest of each reading, and a chart over the session. **Sources** lists every reading
|
||||
FrameLedger knows of and, for each one it does not read, why — the agent is not an administrator, PawnIO is not
|
||||
installed, it comes with a later release, or it is never read. A session's summary has an **Advanced metrics…**
|
||||
button that opens that session there. In `en`, `vi` and `ja`; the user guide has a page for it.
|
||||
- **The terms window shows the Privacy Policy 2.15 and the Disclaimer 2.15 once.** The Privacy Policy names what
|
||||
Advanced metrics reads and stores, only while it is on, and what it never reads: a serial number, a display's
|
||||
identification data, a list of other programs. The Disclaimer's two sentences about PawnIO and about running the
|
||||
agent as administrator said "the CPU temperature"; they now also name the processor's, the memory's and the
|
||||
motherboard's sensors, read with Advanced metrics on. The same sentence changed in Settings, the first run, the
|
||||
administrator dialog, the guide and `LIMITATIONS.md`.
|
||||
|
||||
### Changed
|
||||
|
||||
- **A crash file from a newer build no longer loses its tail in an older one.** The file a session writes as it goes
|
||||
(so that a crash keeps what was recorded) is made of chunks; a reader that met a chunk of a kind it did not know
|
||||
stopped there. It now passes over a whole chunk it does not know and reads on.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A sentence in the documents that kept a function from being called.** `docs/18_GPU_VENDOR_APIS.md` said the
|
||||
vendored NVAPI headers do not declare `NvAPI_GPU_GetMemoryInfoEx`. They do — in `nvapi_lite_common.h`, which
|
||||
`nvapi.h` includes; the search that found nothing had looked in `nvapi.h` alone. The row is corrected, and the
|
||||
bridge will call it for the advanced memory rows. Nothing about the memory figures FrameLedger shows today changes.
|
||||
@@ -0,0 +1,59 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.4] - 2026-09-21
|
||||
|
||||
**The fourth pre-release: four faults found in the first day of `0.1.0-beta.3`.** The same unsigned installer: verify
|
||||
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **Only one FrameLedger window now.** Starting the App while it is already running (a double-click, or the shortcut
|
||||
while it sits in the tray) brings the running one forward instead of opening a second one with a second tray icon.
|
||||
- **The safety texts follow your language.** In a Vietnamese UI the consent dialog, the refusal notices and the
|
||||
guard-bypass card were English.
|
||||
- **The guard bypass is honest about what it cannot do.** A game whose anti-cheat protects its process (ELDEN RING
|
||||
under Easy Anti-Cheat is one) cannot be opened by any other program, so FrameLedger cannot measure it with or without
|
||||
the bypass, and it will not try to get around that protection. beta.3 showed nothing at all in that case; this build
|
||||
shows a notice that says so, the bypass warning says it before you accept, and the game page no longer says
|
||||
"Hooking is disabled" beside a hooking switch that is on.
|
||||
|
||||
**Updating from `0.1.0-beta.3`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
> **Corrected the same evening.** This bullet went on to say that on 2026-09-21 "an install over a running Agent left
|
||||
> a half-replaced folder and the App failed to start three times". **That cause was a guess and the logs do not
|
||||
> support it**: nothing was installed between the three failed starts (20:59–21:01, `Could not load …
|
||||
> Microsoft.Data.Sqlite`) and the start that worked at 21:02. What Windows' own event log shows for that hour is a
|
||||
> failing external USB drive (the owner's report: a loose cable) and two restarts of the PC at 20:57 and 21:02. The
|
||||
> three failed starts are **unexplained**; the advice to stop the Agent before installing stands on its own.
|
||||
- The Disclaimer moved to 2.4 (one paragraph about the bypass), so the Legal Gate opens once.
|
||||
- No schema change. A bypass you already accepted stays on; the new warning text is shown the next time you turn one on.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A second App could be started beside the first.** Nothing enforced one instance: the owner's log of 2026-09-21
|
||||
shows two started 360 ms apart from one double-click — two windows, two tray icons, a second log file, both writing
|
||||
one ledger — and with "minimize to tray" on, every click on the shortcut made another. The App now claims its data
|
||||
folder at start (`Services.SingleInstance`, a named mutex and event keyed on the folder); a later start hands over to
|
||||
the running one, which brings its window forward, and exits. `--diag` still runs beside a running App.
|
||||
- **A Vietnamese (or Japanese) UI showed the safety texts in English** — the consent dialog, the refusal notices, and
|
||||
the whole guard-bypass card in beta.3's screenshot. `FrameLedger.Shared`'s string family was never given the UI
|
||||
culture and fell back to the thread's, which the App's async start does not pass to later dispatcher work.
|
||||
`App.ApplyCulture` sets both families now. (Japanese safety text is still the English by design, until reviewed.)
|
||||
- **Under the guard bypass the game page said "Hooking is disabled for this game: …" beside a hooking switch that was
|
||||
on.** The finding stays on the page and now reads "The guard found: … You chose to bypass it for this game".
|
||||
- **With the bypass on, a game protected by a kernel anti-cheat produced nothing at all** — no session, and a toast
|
||||
reading `InjectFailed: TargetAmbiguous`. Measured on the owner's ELDEN RING (Easy Anti-Cheat): the anti-cheat's
|
||||
driver closes the game's process to other programs, the resolver could read no candidate, and it called that
|
||||
"ambiguous". It is `TargetUnreadable` now, and it reaches the user as a persistent notice that says what happened,
|
||||
that nothing was injected or measured, and that **the bypass does not change this and FrameLedger will not work
|
||||
around another product's protection** (rule 3). The bypass disclosure says the same before it is accepted (its
|
||||
version is `guard-bypass-dialog/2`), and so does `legal/DISCLAIMER.md` §2A (2.3 -> **2.4**, so the Legal Gate opens
|
||||
once). The same reason covers a game running as administrator while the Agent does not.
|
||||
- The refusal notices said "there is no way to override this"; they name the per-game bypass switch and whose risk it is.
|
||||
|
||||
### Changed
|
||||
|
||||
- The Agent's session log line names what the guard said when it was not a plain allow
|
||||
(`…; guard=BlockedService/Easy Anti-Cheat/EasyAntiCheat_EOS`), and `started-under-bypass=` for a bypassed start. A
|
||||
`SafetyUnhook` on the owner's machine left no trace of WHICH finding fired; the pipe event carried it and the log,
|
||||
which is what survives, did not.
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.40 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.40] - 2026-11-12
|
||||
|
||||
**The fortieth pre-release: Advanced metrics, inside the game.** With **Advanced metrics** on (Settings ▸ Recording;
|
||||
off unless you switch it on), a session of a game FrameLedger measures from inside now also keeps **what the game
|
||||
itself tells its upscaler**: for DLSS the output size, the model preset for each quality mode, whether the game said
|
||||
its colour buffers are HDR, auto-exposure, alpha upscaling and the exposure values; for FSR the sharpening, the
|
||||
largest jitter offset, the exposure, the near and far planes, the **range** of the field of view, the flags, the
|
||||
frame time the game reported and FSR's own video memory when the game asked for it. The **Advanced** page shows them
|
||||
under the session, in the vendor's own notation, and the session says in a sentence what became of them. With the
|
||||
setting off nothing more is read inside a game: the component in the game runs the same reads as before, and a test
|
||||
that injects into a window sending all of it finds the new memory region empty to the last byte. The same unsigned
|
||||
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**What it is not, yet.** **None of this has been read from a real game** — only from the project's own test window.
|
||||
**Many games will show nothing**: most set their DLSS options through a call FrameLedger cannot intercept, and the
|
||||
FSR rows need FSR 3.1 or later through AMD's own library (a game that upscales through the older FSR 3.0 interface
|
||||
shows none). The session then says *the game made none of the calls these are read from* — which never means the
|
||||
game uses no upscaler; its summary names the upscaler as before. These are the game's words to the upscaler, not a
|
||||
check of what the upscaler did. **Never read:** where the camera is, which way it looks, its matrices — a build
|
||||
check refuses those names anywhere in the code loaded into a game. No new hook is installed by this release; two
|
||||
further steps of this train add hooks, each after this one has been run on real games. `LIMITATIONS.md` §Sensors
|
||||
lists every limit.
|
||||
|
||||
**Updating from `0.1.0-beta.39`:** Help ▸ Check for updates, then *Restart to update* with no game running. The terms
|
||||
window shows the **Privacy Policy 2.16** once — it names what is stored of the game's upscaler parameters, only with
|
||||
Advanced metrics on and only for a game FrameLedger injects into, and what is never read. The Disclaimer stays 2.15.
|
||||
**A game that is running when you update must be restarted before FrameLedger measures it again**: the shared memory
|
||||
between the game and the agent has a new layout (version 5), and the component inside the game is new. The ledger
|
||||
stays at schema 23 and the detection rules at `2026.11.2`.
|
||||
|
||||
*The entries below are in the order the four pull requests landed. One that says "not yet" describes that pull
|
||||
request; a later entry is what followed.*
|
||||
|
||||
### Added
|
||||
|
||||
- **Advanced metrics inside the game is planned — three releases, and nothing reads it yet.** The readings that
|
||||
exist only inside a game — the options a game gives DLSS and FSR, FSR's own memory, later the constants a game
|
||||
gives Streamline and its frame-generation configuration — come in three steps (owner decisions D110–D116):
|
||||
first more fields of calls FrameLedger already intercepts, with no new hook; then two new hooks; then two more.
|
||||
Each step waits for the one before to be run on real games. With Advanced metrics off, nothing more is read
|
||||
inside a game either. This pull request changes nothing you can see or record: it records the decisions, and
|
||||
**which version of each vendor struct carries which field**, compared across every upstream release of Streamline
|
||||
2.x and of the FidelityFX API — a field is read only where it is proven to be there.
|
||||
- **`tools/agent-cost.ps1`** (a developer tool): what the shipped capture agent costs while it records, measured on
|
||||
the real program against the project's own test window, with Advanced metrics off and on.
|
||||
|
||||
- **The shared memory between a game and the agent has room for what a game tells its upscaler — and nothing
|
||||
writes it yet.** Its layout is version 5: one new region, sized once for the three releases of this train, and
|
||||
one new word by which the agent says "this session records Advanced metrics". With that word at zero — every
|
||||
session, until the next pull request, and afterwards every session with the option off — the region stays empty and
|
||||
the component inside the game does exactly what it did before. **A game that is running when you update must be
|
||||
restarted before FrameLedger measures it again**, as after every update.
|
||||
|
||||
- **The component inside a game can read what the game tells its upscaler — and only when asked.** For a game
|
||||
FrameLedger injects into, and only while the agent asks for it (nothing asks yet: that is the next pull request,
|
||||
and then only with Advanced metrics on), the calls FrameLedger already intercepts are read a little further: the
|
||||
options a game hands DLSS with each evaluation (output size, presets, exposure, three switches), what it hands
|
||||
FSR with each upscale (sharpening, the jitter's size, exposure, the depth range, the field of view as a range,
|
||||
flags, the frame time it reports), and FSR's own memory when the game itself asks for it. **No new hook**, and
|
||||
with the request off the same code as before runs: a test injects into a window that sends all of it and finds
|
||||
the new memory region empty to the last byte. **Never the camera's position, its axes or its matrices** — a
|
||||
build check now refuses those names anywhere in the code loaded into a game (`tools/overlay-fields-check.ps1`).
|
||||
Many games set their DLSS options through a call that cannot be intercepted, and will show nothing here.
|
||||
Measured cost while asked: 22–23 billionths of a second per frame for FSR, 10–12 for DLSS; not measurable when
|
||||
not asked.
|
||||
- **A second session of a game that kept running starts its summaries afresh.** The ranges and counts kept inside the
|
||||
game belong to the session that asked for them: each session asks with a request of its own, and the agent reads
|
||||
only what answers it.
|
||||
|
||||
- **Advanced metrics: what the game tells DLSS and FSR, kept with the session.** With Advanced metrics on, a session
|
||||
of a game FrameLedger measures from inside now also keeps what the game itself handed to its upscaler: for DLSS the
|
||||
output size, the model preset for each quality mode, whether the game said its colour buffers are HDR,
|
||||
auto-exposure, alpha upscaling and the exposure values; for FSR the sharpening, the largest jitter offset, the
|
||||
exposure, the near and far planes, the **range** of the field of view, the flags, the frame time the game reported
|
||||
(as a chart) and FSR's own video memory at the moments the game asked. The Advanced page shows them under the
|
||||
session, in the vendor's own notation. **Many games will show nothing**, and the session says why — most games
|
||||
set their DLSS options through a call FrameLedger cannot see, and the FSR rows need FSR 3.1 or later through AMD's
|
||||
library; it never means the game uses no upscaler. **Never read:** where the camera is, which way it looks, its
|
||||
matrices. With the option off nothing more is read inside a game, exactly as before. Not yet read from a real game.
|
||||
- **Privacy Policy 2.16** names the above: what is stored, only with the option on and only for a game FrameLedger
|
||||
injects into, and what is never read. You are shown it once after updating.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The agent's processor budget says what was measured.** The specification promised that the capture agent uses
|
||||
at most 1 % of one processor core while recording; nobody had measured it. Measured on the development PC it is
|
||||
1.93 % — 2.04 % with Advanced metrics on — nearly all of it the once-a-second read of the graphics card's sensors
|
||||
that every session has always made, and its memory is 113 MiB (119 with the option on) against a limit of 150.
|
||||
The owner chose to keep the readings and amend the limit: **NFR-2 is now ≤ 2.5 % of one core** (D117). Nothing the
|
||||
agent does changes.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A crash dump is tried up to three times.** When FrameLedger or its agent stops on an error it never expected, a
|
||||
small helper writes a dump of the program for a bug report - while the program's other threads are still
|
||||
running. Windows can fail that once when the program changes under it, and one failure used to mean no dump at
|
||||
all. It is now tried again, twice, a moment apart.
|
||||
@@ -0,0 +1,41 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.41 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.41] - 2026-11-12
|
||||
|
||||
**The forty-first pre-release: one fix, for Advanced metrics with the agent as administrator.** If you run the
|
||||
capture agent as administrator with PawnIO installed and have **Advanced metrics** on, 0.1.0-beta.40 and
|
||||
0.1.0-beta.39, which has the same code and where it was not looked for, could lose sensors: after most sessions the Advanced page stopped showing the processor's readings
|
||||
until it was reopened, and now and then a whole session was stored with the graphics driver's seventeen readings
|
||||
and none of the two hundred from the sensor library. The agent was closing the sensor library in one place while
|
||||
another place was still reading it. It now opens and closes it in one place only, and never while something is
|
||||
reading. If you do not use that combination, nothing changes for you. The same unsigned installer: verify its hash
|
||||
against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**What it is not, yet.** The fix was made from the agent's log of ten real sessions; the fault needs an
|
||||
administrator's agent with PawnIO to show, and has not been seen to be gone on such a PC yet. After a few sessions
|
||||
the agent's log (Logs page) should no longer say *a device is left alone* or *the sensor library did not open*.
|
||||
Everything 0.1.0-beta.40's notes say is not yet done still stands.
|
||||
|
||||
**Updating from `0.1.0-beta.40`:** Help ▸ Check for updates, then *Restart to update* with no game running. No
|
||||
terms to read again, no change to the ledger (schema 23), the detection rules stay at `2026.11.2`. **The code
|
||||
FrameLedger loads into a game — the overlay, the Vulkan layer, the shared-memory layout, the injector — is
|
||||
0.1.0-beta.40's, line for line**; as after every update, a game that was running across it must be restarted
|
||||
before it is measured again.
|
||||
|
||||
**A note on numbers.** The plan for Advanced metrics had named 0.1.0-beta.41 for its next step inside the game (two
|
||||
new hooks). This fix took the number; that step is now 0.1.0-beta.42, and the ones after it move by one as well.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Advanced metrics: the processor's sensors no longer drop out after a session, and a session no longer loses its
|
||||
sensors at the start.** With the agent running as administrator and PawnIO installed, the sensor library was being
|
||||
closed by one part of the agent while another part was still reading it. After most sessions the Advanced page
|
||||
lost the processor's readings until it was reopened, and one session in ten stored only the graphics driver's
|
||||
seventeen series instead of two hundred and twelve. The agent now opens and closes the sensor library in one
|
||||
place, and does not close it while anything is still reading. Found in the first sessions recorded that way; the
|
||||
cause was read from the log and could not be reproduced without that setup, so the next sessions will show
|
||||
whether it is gone — the agent's log should no longer say *a device is left alone* or *the sensor library did not
|
||||
open*. Nothing changes in the code loaded into a game.
|
||||
- **Two comparisons in the Advanced-metrics code say what they mean.** Whether a game gave FSR one field of view or
|
||||
a range of them was decided by comparing two decimal numbers for equality; it is now decided by comparing the two
|
||||
stored values bit for bit. Nothing you see changes. (Found by SonarCloud after 0.1.0-beta.40 was merged.)
|
||||
@@ -0,0 +1,62 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.42 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.42] - 2026-11-12
|
||||
|
||||
**The forty-second pre-release: groundwork, and a log that can answer a question.** Four changes, none of which
|
||||
adds a hook to a game. A session that saw two upscalers is now named after the one it ran — one real session had
|
||||
been stored as "DLSS" with FSR's quality mode and FSR's render size. The part of FrameLedger inside the game can no
|
||||
longer leave a hook in after it has stopped. Its log is now written during the session rather than only at the
|
||||
start and the end, so it is whole after a game that simply exits, and it says which module each hook went into and
|
||||
what kinds of call each AMD FidelityFX module received. And with **Advanced metrics** on, an FSR depth plane at
|
||||
infinity is shown as "∞" where it used to be missing. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**What it is not, yet.** It does not fix a game whose upscaler reads "unknown" — Cyberpunk 2077 set to FSR is the
|
||||
one known — it makes the next session of such a game say why, in `logs\overlay-<pid>-….log`. The two new readings
|
||||
planned for Advanced metrics (the frame-generation settings a game gives FSR, and what a game tells Streamline
|
||||
about each frame) are the next pre-release, after that log has been read. No real game has been run on this
|
||||
build: the changes inside the game were tested with FrameLedger's own test program, and their cost was measured
|
||||
on the code itself (about 4 billionths of a second per FidelityFX call for the log's new lines; nothing measurable
|
||||
for the rest). Everything 0.1.0-beta.41's notes say is not yet done still stands.
|
||||
|
||||
**Updating from `0.1.0-beta.41`:** Help ▸ Check for updates, then *Restart to update* with no game running. No
|
||||
terms to read again, no change to the ledger (schema 23), the detection rules stay at `2026.11.2`. **The code
|
||||
loaded into a game changed in this release** — the first time since 0.1.0-beta.40 — so a game that was running
|
||||
during the update keeps the old part until it is started again. Sessions already stored are not rewritten: one
|
||||
that was named after the wrong upscaler keeps that name.
|
||||
|
||||
### Added
|
||||
|
||||
- **Advanced metrics: FSR's depth plane at infinity is shown as "∞".** Engines with an infinite depth range tell
|
||||
FSR that one of the two camera planes is at infinity, and FrameLedger took that value for "not set" — so a
|
||||
session's depth range showed one plane where the game had given two. The plane at infinity is now stored and
|
||||
shown as such. Only for FSR, and only while Advanced metrics is on; nothing else about what is read changed.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The Overlay's log is whole after a game exits, and says more.** The log FrameLedger's part inside the game
|
||||
writes (`logs\overlay-<pid>-….log`) used to hold only the first half second of a session unless the session
|
||||
ended while the game was still running: a game that exits takes the thread that writes the log with it. It is
|
||||
now written during the session, whenever something new was noted. Each hook that went in is named by its module
|
||||
and function (four AMD modules used to be four identical lines), a hook that could not go in says why, and the
|
||||
log lists which kinds of call each AMD FidelityFX module received and which upscaling and frame-generation
|
||||
modules the game loaded, and when. This is for finding out why a game's upscaler reads "unknown" — nothing in
|
||||
it is a measurement, and nothing from it is stored in a session. Measured cost: about 4 billionths of a second
|
||||
per FidelityFX call.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The part inside the game can no longer leave a hook in after it has stopped.** Two gaps in how the Overlay keeps
|
||||
track of its own patches, found by reading the code and not by a failure: a patch made while the table of patches
|
||||
was full would have been made anyway and never taken out, and a stop that arrived at the exact moment a hook was
|
||||
going in could miss it. A patch now takes its place in the table before it is made — no place, no patch — and is
|
||||
recorded before it can run, so the stop either removes it or the installer does. A patch that could not be made
|
||||
is written to the Overlay's log with the reason, where it used to be silent. No hook's own code changed.
|
||||
|
||||
- **A session that saw two upscalers is named after the one it ran, with that one's quality and render size.** The
|
||||
session's upscaler used to be the first one FrameLedger saw named, while the quality mode and the render size
|
||||
came from whichever frames carried them. A game that evaluated DLSS briefly and then ran FSR was stored as "DLSS"
|
||||
with FSR's quality and FSR's render size. The name is now the technology named on the most frames, the quality
|
||||
and the size are read from that technology's frames only, and such a session is marked "settings changed during
|
||||
session". What that technology did not say reads N/A rather than borrowing the other's value. Sessions already
|
||||
stored are not rewritten.
|
||||
@@ -0,0 +1,86 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.43 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.43] - 2026-11-12
|
||||
|
||||
**The forty-third pre-release: a game that was still loading is no longer lost, and two more readings inside the
|
||||
game.** Two fixes first. A game that FrameLedger looked at while it was still loading its modules could be left
|
||||
unrecorded — the session ended as a safety stop with nothing in it; FrameLedger now reads the list again before it
|
||||
gives up, and what stops a session has not changed. And an FSR upscale is counted once per frame whichever way the
|
||||
game's FidelityFX loader passes it on. Then, with **Advanced metrics** on, a session of a game measured from inside
|
||||
also keeps what the game tells NVIDIA Streamline about each frame and how it configures FSR frame generation —
|
||||
from two calls FrameLedger hooks only once Advanced metrics has been asked for in that game. The same unsigned
|
||||
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**What it is not, yet.** The two new readings have been tested with FrameLedger's own test program and **have not
|
||||
been run in a real game**: this release is the first time either hook is put into one. They are what the game
|
||||
asked for, not a check of what happened, and Streamline's values are those of the first view a game draws.
|
||||
Streamline 1.x is not read. Where the game's camera is, which way it looks and its matrices are never read — they
|
||||
sit in the same data, and a check in the build refuses code that names them. The cost was measured on the code
|
||||
itself: about 20 billionths of a second per frame for Streamline's call and 15 per call for FSR's while the option
|
||||
is on, under 2 while it is off; nothing measurable for the two fixes. A game whose FSR is built in (Cyberpunk 2077's
|
||||
FSR 2.1) still reads "unknown" as its upscaler. Everything 0.1.0-beta.42's notes say is not yet done still stands.
|
||||
|
||||
**Updating from `0.1.0-beta.42`:** Help ▸ Check for updates, then *Restart to update* with no game running. **The
|
||||
terms are shown once: Privacy Policy 2.17**, which names the two new readings. No change to the ledger (schema 23),
|
||||
the detection rules stay at `2026.11.2`. **The code loaded into a game changed in this release**, so a game that
|
||||
was running during the update keeps the old part until it is started again.
|
||||
|
||||
### Added
|
||||
|
||||
- **Advanced metrics: a session now shows what the game told Streamline each frame and how it configured FSR frame
|
||||
generation.** For a game FrameLedger measures from inside, a session recorded with **Advanced metrics** on keeps
|
||||
— beside what the game told DLSS and FSR — the largest jitter offset, the motion-vector scale and how motion
|
||||
vectors are stored, the near and far planes and whether depth is inverted, the range of the field of view, the
|
||||
aspect ratio, whether the projection is orthographic and how often the game reset the upscaler's history
|
||||
(Streamline); and whether FSR frame generation was configured on, whether it may run asynchronously, its flags,
|
||||
whether only generated frames are presented, and the part of the picture it generates in. A setting the game
|
||||
changed during the session reads *on and off*. The line under the session now also says, for each of the two,
|
||||
whether it was read, hooked and never called by the game, or not hooked because the game did not load the
|
||||
library — so an empty page says which it is. These are what the game asked for, not a check of what happened;
|
||||
neither has been confirmed on a real game yet. Never read: where the camera is, which way it looks, its
|
||||
matrices.
|
||||
|
||||
- **The terms are shown once after this update: Privacy Policy 2.17.** It names the two new readings above and says
|
||||
that the two calls they come from are intercepted in a game only once a session with Advanced metrics on has
|
||||
started there. Nothing is sent anywhere, as before.
|
||||
|
||||
- **Advanced metrics, inside the game: how the game configures FSR frame generation** (the part inside the game;
|
||||
what a session shows of it comes with the same release). With **Advanced metrics** on, FrameLedger now also
|
||||
reads, from the call a game makes to configure AMD's frame generation, whether generation is on, whether it may
|
||||
run asynchronously, its flags, whether only generated frames are presented, and the part of the picture it
|
||||
generates in. Nothing else of that call is read. Like the Streamline hook, this one is put into a game only once
|
||||
Advanced metrics has been asked for. Measured cost: about 15 billionths of a second per call while the option is
|
||||
on, under 2 while it is off.
|
||||
|
||||
- **Advanced metrics, inside the game: what the game tells NVIDIA Streamline about each frame** (the part inside the
|
||||
game; what a session shows of it comes with the same release). With **Advanced metrics** on, FrameLedger now also
|
||||
reads, from a call a Streamline game makes every frame, the size of the jitter, the motion-vector scale, the depth
|
||||
range, the range of the field of view, the aspect ratio and seven on/off settings (inverted depth, how motion
|
||||
vectors are stored, whether the upscaler's history was reset). It never reads where the game's camera is, which
|
||||
way it looks, or its matrices, which sit in the same data — a check in the build refuses any code that names
|
||||
them. This is the first reading that needs a hook of its own, and that hook is put into a game only once
|
||||
Advanced metrics has been asked for: with the option off, nothing in the game is touched for it. Measured cost:
|
||||
about 20 billionths of a second per frame while the option is on, under one billionth while it is off.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **FSR upscaling is counted once per frame whichever way the game's FidelityFX loader passes it on.** Newer
|
||||
FidelityFX loaders hand a call on to the library behind them in a way that brought the same upscale to
|
||||
FrameLedger twice; with frame generation off, the count of frames the game rendered would have doubled — Native
|
||||
FPS twice too high. Seen in how Cyberpunk 2077's loader passes on its frame-generation calls; no game tested so
|
||||
far upscales through such a loader, so this is a precaution. The upscale is now counted where the game calls it,
|
||||
and nowhere else. (Owner decision D125. Measured cost: none that can be told from noise.)
|
||||
|
||||
- **A game is no longer left unrecorded because it was still loading when FrameLedger looked at it.** Before it
|
||||
hooks a game, and again right after, FrameLedger lists the modules the game has loaded and checks them against
|
||||
the anti-cheat list. A game that is starting loads and unloads modules for several seconds, and when the list
|
||||
changed in the middle of being read FrameLedger treated it as unreadable and stopped: the session ended as a
|
||||
safety stop with nothing recorded, and the game ran on unmeasured until it was restarted. It now reads the list
|
||||
again — up to three more times, a quarter of a second apart — and only stops if the list never holds still. What
|
||||
stops a session has not changed: an anti-cheat module found in any read stops it at once, a protected process
|
||||
still stops it at once, and a list that cannot be read in the end is still a stop, never a pass. (Owner decision
|
||||
D123; seen five times in one PC's logs in a week.)
|
||||
|
||||
- **A test of the Overlay's log reads its lines without `strlen`.** The helper that looks for a line in the log
|
||||
took its text as C strings and measured one with `strlen`; it takes strings now. Test code only: nothing in the
|
||||
installed software changes. (Found by SonarCloud after 0.1.0-beta.42 was merged.)
|
||||
@@ -0,0 +1,83 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.44 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.44] - 2026-11-12
|
||||
|
||||
**The forty-fourth pre-release: what the first real games on 0.1.0-beta.43 showed, fixed — and two more readings
|
||||
inside the game.** Nine sessions on five games were read the day 0.1.0-beta.43 came out. Its two new readings
|
||||
worked on four of them; three things did not read right, and are fixed first. Cyberpunk 2077 tells NVIDIA
|
||||
Streamline its field of view in degrees, and FrameLedger labelled the number as radians: a value too large to be
|
||||
radians is now shown as the game gave it, and says so. A game whose hooking had once been switched off after two
|
||||
early ends was switched off again by every single one after that: the count now starts again each time you switch
|
||||
hooking back on. And an FSR frame-generation configuration with no flag set now says *None*. Then, with
|
||||
**Advanced metrics** on, a session of a game measured from inside can also keep what Streamline answers when the
|
||||
game asks **which version a feature is and what it requires** — from two more calls FrameLedger hooks only once
|
||||
Advanced metrics has been asked for in that game. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**What it is not, yet.** **Most sessions will show nothing of the two new readings.** A game asks Streamline about
|
||||
its features while it starts, and FrameLedger is usually not in the game yet; the session then says the call was
|
||||
hooked and the game did not ask again — which is the expected answer, not a fault. They have been tested with
|
||||
FrameLedger's own test program and **have not been run in a real game**: this release is the first time either
|
||||
hook is put into one. What they give is Streamline's answer as the game received it — not FrameLedger's own check
|
||||
of the PC — and never the lists that answer points to (which buffers, which Vulkan extensions). A game that faults
|
||||
while it is closing can still read *ended normally* in a session measured from inside; that is written down, not
|
||||
changed. The two Cyberpunk 2077 sessions recorded on 0.1.0-beta.43 keep the line they were stored with. The cost
|
||||
was measured on the code itself: 15 and 21 billionths of a second per call while the option is on, under 1 while
|
||||
it is off, for calls a game makes a handful of times. Everything 0.1.0-beta.43's notes say is not yet done still
|
||||
stands.
|
||||
|
||||
**Updating from `0.1.0-beta.43`:** Help ▸ Check for updates, then *Restart to update* with no game running. **The
|
||||
terms are shown once: Privacy Policy 2.18**, which names the two new readings. No change to the ledger (schema 23),
|
||||
the detection rules stay at `2026.11.2`. **The code loaded into a game changed in this release**, so a game that
|
||||
was running during the update keeps the old part until it is started again.
|
||||
|
||||
### Added
|
||||
|
||||
- **Two more calls are hooked inside a game, only where Advanced metrics was asked for** (Advanced metrics train B,
|
||||
the third step): `slGetFeatureVersion` and `slGetFeatureRequirements` of `sl.interposer.dll` — what Streamline
|
||||
answers when a game asks which version a feature is and what it requires. The original call runs first and its
|
||||
answer is read only when it succeeded: the feature's Streamline and NGX versions; the graphics APIs it supports,
|
||||
whether V-Sync must be off and hardware-accelerated GPU scheduling on, how many threads, viewports and buffers,
|
||||
and the Windows and driver versions found beside the ones required. **The lists the answer points to — the
|
||||
buffer tags, the names of Vulkan extensions and features — are never followed.** As with `slSetConstants`,
|
||||
neither patch is made in a game no session has asked, and each stays for the life of the process once made. A
|
||||
game asks these while it starts, so the two rows are the first the Overlay patches — and most sessions, attached
|
||||
later, will still not see the calls. Nothing is shown of them yet: the Agent and the App read them in the next
|
||||
pull request. No layout change (5), no schema change (23).
|
||||
|
||||
- **A session shows which version each Streamline feature is, and what it requires** (Advanced metrics). Two
|
||||
catalog entries are now read inside the game: `sl.feature.versions` and `sl.feature.requirements` — Streamline's
|
||||
answers to the two questions a game asks about a feature, in NVIDIA's own names (`kFeatureDLSS_G · versionNGX`,
|
||||
`kFeatureDLSS · driverVersionRequired`). The line under the session says for each of the two calls whether it was
|
||||
read, not hooked, or — the usual case — *hooked — the game asks this while it starts, and did not ask again after
|
||||
FrameLedger attached*. **Most sessions will show nothing here**: a game asks before FrameLedger is in it. A game
|
||||
that asks later is read then, and a second session of a game that kept running keeps what the first read. The
|
||||
Agent's end-to-end tests now run a Streamline target as well as an FSR one.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Privacy Policy 2.18**: it names what Streamline answers about a feature — the features asked about, their
|
||||
versions, what each requires — and what of that answer is never read (the lists it points to: the buffers' names,
|
||||
the names of Vulkan extensions and features); "two further calls" is four. The terms window shows once after the
|
||||
update. The Disclaimer stays 2.15.
|
||||
- **Switching hooking back on starts the count of early abnormal ends again** (owner decision D126). The count was
|
||||
never set back, so a game that had once been switched off — after two ends within 60 seconds of injection — was
|
||||
switched off again by every single such end after its user switched it on, under a reason that still said
|
||||
"twice". Seen on 2026-11-12: Lies of P, two ends in October, one crash of its own that day. Two are needed again
|
||||
each time. Nothing else about the rule moves: it only switches off, an anti-cheat block is never cleared, and the
|
||||
user-mode exception's trial keeps its own record.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A field of view a game gives in degrees is no longer labelled radians** (Advanced metrics; owner decision
|
||||
D128). Cyberpunk 2077 gives NVIDIA Streamline 51–90 where the library expects radians, and the session read
|
||||
`51.0055 – 90 rad (2922.4° – 5156.6°)`. A value too large to be radians is now shown as the game gave it, with a
|
||||
line that says it is not radians, and is not converted. Sessions recorded on 0.1.0-beta.43 keep the line they
|
||||
were stored with.
|
||||
- **An FSR frame-generation configuration with no flag set says "None"** (Advanced metrics). The row was missing,
|
||||
where an upscale with no flag has always said so.
|
||||
- **The accuracy statement and the limitations no longer say that what a game tells Streamline, and how it
|
||||
configures FSR frame generation, have not been read from a real game**: they were, on 2026-11-12 — three games
|
||||
and one. What is still unconfirmed is named: the DLSS options, and a configuration that reaches FSR through
|
||||
AMD's 2.3 loader. A fault while a game is closing, which a session measured from inside the game does not see,
|
||||
is written down as a limit (owner decision D127: not changed in this release).
|
||||
@@ -0,0 +1,80 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.45 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.45] - 2026-11-12
|
||||
|
||||
**The forty-fifth pre-release: what a game does with NVIDIA Streamline's features.** With **Advanced metrics** on,
|
||||
a session of a game measured from inside can now also keep, for each Streamline feature the game asks about or
|
||||
controls: whether Streamline says it is **supported** — in NVIDIA's own word, a refusal included — whether it is
|
||||
**loaded**, whether the game **switched it on or off** while it ran, how many times the game **allocated and
|
||||
freed** what the feature needs, and how many times it **shut Streamline down**. They come from six more calls,
|
||||
which FrameLedger hooks only once Advanced metrics has been asked for in that game. The pages that said most
|
||||
sessions would show nothing of 0.1.0-beta.44's two readings are corrected: the first real sessions read both in
|
||||
every Streamline game. The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info →
|
||||
Run anyway*.
|
||||
|
||||
**What it is not, yet.** The six new calls have been tested with FrameLedger's own test program and **have not
|
||||
been run in a real game**: this release is the first time any of them is patched in one, and it is six at once.
|
||||
Two of them sit on a game's way out — freeing a feature's resources, shutting Streamline down — and two of the
|
||||
games run so far already fault while closing without them; whether anything changes there is for the first real
|
||||
sessions to say. What is shown are **calls the game made after FrameLedger was in it**, counted to fifteen: not
|
||||
what the game did while it started, and not a statement that a feature ran or drew anything. **What a game
|
||||
started Streamline with is not read and will not be**: the game makes that call once, before FrameLedger can be
|
||||
inside it, and the Advanced page now says so instead of "a later release". Which graphics card a game asks about
|
||||
is never read. The cost was measured on the code itself: at most 13 billionths of a second per call while the
|
||||
option is on, under 2 while it is off, for calls a game makes a few times a second at most. A stop restores every
|
||||
patch, each taking about a sixth of a second, and a Streamline game with Advanced metrics on now has six more of
|
||||
them; the Overlay's log waits for them.
|
||||
Everything 0.1.0-beta.44's notes say is not yet done still stands.
|
||||
|
||||
**Updating from `0.1.0-beta.44`:** Help ▸ Check for updates, then *Restart to update* with no game running. **The
|
||||
terms are shown once: Privacy Policy 2.19**, which names the new readings and two things that are never read. No
|
||||
change to the ledger (schema 23), the detection rules stay at `2026.11.2`. **The code loaded into a game changed
|
||||
in this release**, so a game that was running during the update keeps the old part until it is started again.
|
||||
|
||||
### Added
|
||||
|
||||
- **Three more of Streamline's calls are hooked inside a game, only where Advanced metrics was asked for** (owner
|
||||
decisions D129–D131): `slIsFeatureSupported`, `slIsFeatureLoaded` and `slSetFeatureLoaded` — whether Streamline
|
||||
says a feature is supported (its answer, a refusal included), whether it is loaded, and the game switching a
|
||||
feature off and on while it runs. No vendor struct is read for these: the feature's id, a result code, a yes or
|
||||
no. **The adapter a game names when it asks whether a feature is supported is never read**, and the build now
|
||||
refuses code that names what identifies it. As with the four hooks before them, none of the three patches is made
|
||||
in a game no session has asked. Nothing is shown of them yet: the Agent and the App read them in a later pull
|
||||
request. No layout change (5), no schema change (23).
|
||||
- **And three more, counted only**: `slAllocateResources`, `slFreeResources` and `slShutdown` — how many times a
|
||||
game allocated and freed a feature's resources (up to fifteen each) and how many times it shut Streamline down.
|
||||
The feature's id is the only argument looked at; the two that sit on a game's way out note the call and then
|
||||
call the original, and run nothing after it. Six new calls in all in this release, each patched only where a
|
||||
session asked.
|
||||
- **`slInit` is not hooked, and will not be** (D129). A game starts Streamline once, before FrameLedger can be in
|
||||
it — also when FrameLedger starts the game itself — so a hook there would be a patch that reads nothing. The
|
||||
Advanced page's entry for what a game started Streamline with now gives that reason instead of "a later release".
|
||||
- **A session shows whether each Streamline feature is supported and loaded, and what the game did with it**
|
||||
(Advanced metrics). Two catalog entries are read from the six calls above: `sl.feature.support` — Streamline's
|
||||
answer by NVIDIA's own name (`kFeatureDLSS_G · slIsFeatureSupported` = `eOk`; a refusal is named, and it is an
|
||||
answer) and whether the feature is loaded — and `sl.feature.lifecycle` — the game switching a feature on, off or
|
||||
both, how many times it allocated and freed the feature's resources (`≥ 15` past fifteen), and how many times it
|
||||
shut Streamline down. The line under the session names the six calls in one sentence: read; hooked, the game did
|
||||
not make the call; not hooked. They begin when FrameLedger is in the game — what a game did while it started is
|
||||
not there — and they are calls the game made, not a statement that a feature ran. Not confirmed on a real game.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A stop that restores many patches no longer leaves its last lines out of the Overlay's log.** Restoring a patch
|
||||
takes about 160 ms, and the wait for the stop's log lines was two seconds whatever the number of patches: with
|
||||
fifteen the log ended "the stop was still writing". The patches were restored; the log did not say so. The wait
|
||||
is now sized to the number of patches a game can hold.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Privacy Policy 2.19**: it names, for each Streamline feature a game asks about or controls, whether Streamline
|
||||
says it is supported and loaded, the game switching it on or off, and how many times its resources were allocated
|
||||
and freed, and how many times the game shut Streamline down — and two more things that are never read: what
|
||||
identifies the graphics card a game hands over with its question, and the content of a graphics resource. "Four
|
||||
further calls" is ten. The terms window shows once after the update. The Disclaimer stays 2.15.
|
||||
- **The limitations, the accuracy statement and the user guide no longer say that most sessions will show nothing
|
||||
of what Streamline answers about a feature.** 0.1.0-beta.44's notes expected that, because a game asks while it
|
||||
starts. The first real sessions (2026-11-12, five games) read both answers in every Streamline session: the
|
||||
Unreal Engine games ask again later. The pages now say what was seen — and two things the readings showed: the
|
||||
version Streamline gives for a feature can be newer than the file in the game's folder, and a game that does not
|
||||
upscale through Streamline lists frame generation there and no upscaler. No code changes.
|
||||
@@ -0,0 +1,86 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.5] - 2026-09-22
|
||||
|
||||
**The fifth pre-release: the guard override is gone, Tier 2 exists, and a drive that changes its letter is followed.**
|
||||
The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for
|
||||
a user:
|
||||
|
||||
- **The "Bypass the anti-cheat guard" switch is removed.** Where FrameLedger finds anti-cheat in a game — before it
|
||||
injects, when a session starts, or during one — it refuses and **turns hooking off for that game**, says so in the
|
||||
notice and on the game's page, and offers no way to turn it back on for that executable. The terms say so
|
||||
(Disclaimer 2.5, EULA 1.2), so the Legal Gate opens once after the update.
|
||||
- **Sessions that could not be hooked are recorded now.** A refused or hooking-off game gets a T2 row with its
|
||||
duration, hardware telemetry and the reason — the summary says why ("the guard refused — …", "hooking was off for
|
||||
this game", "Windows would not let FrameLedger open the process"). Until now every such session was thrown away
|
||||
within a second.
|
||||
- **A hooking-off entry that runs as administrator (Borderless Gaming, imported from Steam) no longer gets the
|
||||
"anti-cheat driver" notice**, and Steam's tools are no longer imported as games. An entry you already have for one
|
||||
stays until you remove it.
|
||||
- **A drive that changes its letter no longer loses your games.** The Agent finds the same file under the new letter
|
||||
and moves the entry to it with its consent kept — within about 15 s in the background, at once when you launch the
|
||||
game, and when you click the hooking switch. The game's page says when its executable is not where the entry points.
|
||||
|
||||
**Updating from `0.1.0-beta.4`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0008 drops the five columns of the removed switch; the database opens in place, nothing else changes.
|
||||
- Entries whose switch was on lose it; if the guard blocked such a game, its hooking is off and its page says why.
|
||||
|
||||
### Removed
|
||||
|
||||
- **The per-game guard override ("Bypass the anti-cheat guard") is gone** — owner decision 2026-09-22, two pre-releases
|
||||
after it arrived. Its first real use could not reach a process an anti-cheat driver protects, and where it could
|
||||
inject it only exposed the user to the risk its own warning described. Removed entirely: the native entries
|
||||
(`FlGuardedInjectAcknowledged`, its WhenReady twin, `FlGuardIsJudgement`, reason 28), the `SetGuardBypass` message, the
|
||||
App's card and dialog, the session mark and its export line, the `Safety_Bypass_*` strings, and schema 0007's five
|
||||
columns (schema 0008 drops them — the first `DROP COLUMN` in the migration set). Sessions that ran under it keep
|
||||
`guard-bypass=` in their notes. CLAUDE.md rule 2 reads "there is no override" again; Disclaimer 2.5 and EULA 1.2 say
|
||||
so, so the Legal Gate opens once.
|
||||
|
||||
### Added
|
||||
|
||||
- **Tier 2 exists now: a session that could not be hooked is recorded — duration, hardware telemetry and the
|
||||
reason — instead of being thrown away.** Until 2026-09-22 every refusal returned within a second and the 30 s
|
||||
minimum discarded it (`Discarded (tier 2, exit=Normal, frames=0)` for every one in the owner's log), so "the session
|
||||
is still recorded" in the notice was false. The loop now holds a refused session open, ticking the telemetry poller,
|
||||
until the game exits; the row lands as T2 with N/A everywhere a measurement would be, and its summary says why
|
||||
("Why: the guard refused — Easy Anti-Cheat (…)", "Why: hooking was off for this game", "Why: Windows would not let
|
||||
FrameLedger open the process"). The unshipped operator host keeps returning at the refusal.
|
||||
- **A drive that changes its letter no longer loses your games.** When the drive holding a library comes back as
|
||||
another letter (the owner's external drive: `D:` one evening, `H:` the next morning), every game on it read
|
||||
"executable unreadable" and a game launched from the new letter ran as a stranger with no consent. The Agent now
|
||||
finds the same file — same size, same modified time, under exactly one other drive letter — and moves the entry to
|
||||
it with consent, block and detection kept: within about 15 s in the background sweep, at once when such a game is
|
||||
launched, and when you click the hooking switch. The game's page says when its executable is not where the entry
|
||||
points. *Change executable* is still the way to point an entry at a different file.
|
||||
- **Steam's tools are no longer imported as games**: Steamworks Common Redistributables, Borderless Gaming, Wallpaper
|
||||
Engine, SteamVR, the Proton and Steam Linux Runtime entries and Blender are skipped by app id. A row you already have
|
||||
for one of them stays until you remove it.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A hooking-off entry that runs as administrator no longer gets the "anti-cheat driver" notice.** Borderless Gaming,
|
||||
imported from Steam with hooking off, produced a red "hooking refused" notice on every launch: the Agent tried to
|
||||
open its process before it looked at whether hooking was on. Hooking-off is decided first now — no process is
|
||||
opened, no resolver, no gate — and the row gets a quiet Tier-2 session like any other hooking-off game.
|
||||
|
||||
### Changed
|
||||
|
||||
- **A finding turns the game's hooking off, wherever the guard makes it** (`19_SAFETY` §What a finding does to the game). The
|
||||
pre-scan always did this; now a finding at a session's start or at the 30 s re-scan writes the same block — hooking
|
||||
off, the reason on the row, the toggle disabled on the game's page — when it names an anti-cheat *in the game* (its
|
||||
process, its folder, its title lists). A machine-wide driver or service refuses that session only. The notice says
|
||||
"Hooking has been turned off for this game", the session's notes carry `hooking-turned-off=`, and `CaptureRefused` /
|
||||
`SafetyUnhook` carry `hookingTurnedOff`.
|
||||
- **`0.1.0-beta.4`'s notes named a cause they had no evidence for, and are corrected in place** (see its *Updating*
|
||||
section). The owner reported afterwards that the external USB drive holding the Steam library had a loose cable that
|
||||
evening. Windows' System and Application logs for 2026-09-21 agree and re-date the day's symptoms: disk resets and
|
||||
paging errors on that drive from 20:42; `start_protected_game.exe` (20:56) and `GF2_Exilium.exe` (21:45) both
|
||||
ended with `0xc0000006`, an in-page I/O error — the drive, not FrameLedger, and **FrameLedger had injected nothing
|
||||
into ELDEN RING in any run**; the Agent's "executable unreadable" for all 46 titles and the two pipe timeouts at
|
||||
21:12–21:13 sit inside a burst of 30 disk errors. **What the drive does NOT explain, and beta.4's fixes stand on:**
|
||||
Easy Anti-Cheat's own log says "successfully loaded in-game" for ELDEN RING at 21:29:28, the second the resolver
|
||||
found a process it could not open (`TargetUnreadable`); the two App instances started 360 ms apart at 21:07; the
|
||||
English safety texts and the contradictory line are in the screenshot itself.
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.6] - 2026-09-23
|
||||
|
||||
**The sixth pre-release: a game is recorded under its own entry, one entry per game after a drive changes its
|
||||
letter, a game that is not measured is shown while it runs, and RE Engine and FromSoftware games are detected.** The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
|
||||
user:
|
||||
|
||||
- **Another game's `Game.exe` is no longer recorded under your entry.** A process that matches an entry by file name
|
||||
only starts nothing — unless it is that entry's own executable on a drive that changed its letter — so an RPG Maker
|
||||
game can no longer be recorded under another RPG Maker game's name, twice, as *HELLO, HELLO WORLD!* was under
|
||||
*Flower in Us*.
|
||||
- **A game that is not measured is shown while it runs.** Hooking off, refused by the guard, or a process Windows
|
||||
would not open: the Dashboard shows the game, the time and the temperatures, says why nothing is measured, and the
|
||||
tray turns to recording-only — until now it said "Nothing is being captured." for as long as the game ran.
|
||||
- **One entry per game when a drive changes its letter.** Two entries for the same executable under two letters
|
||||
merge on their own (the older one stays, with both histories); a game updated while its drive had another letter is
|
||||
followed with hooking off; the library import no longer adds a game again under the new letter.
|
||||
- **A game removed while it runs keeps its session** (under the entry that holds its executable), and a session file
|
||||
left behind can no longer stop the Agent at every start.
|
||||
- **RE Engine and FromSoftware games are detected**, engines are shown by name, and a game added by hand whose
|
||||
executable is `Game.exe` is named after the game.
|
||||
|
||||
**Updating from `0.1.0-beta.5`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- No schema change; the database opens in place. Every game is re-detected once (rules `2026.09.2`).
|
||||
- Session files in `%LOCALAPPDATA%\FrameLedger\tmp` that beta.5 could not store are stored at the Agent's first start —
|
||||
under the entry that holds their executable — or dropped with a line in `agent-*.log`; the Agent keeps running either
|
||||
way.
|
||||
- An entry that a beta.5 file-name match created for another game keeps its wrong name until you rename it (*Edit…*)
|
||||
or remove it; its executable path says which game it is.
|
||||
- A game whose **folder** moved — not only its drive letter — now records nothing until *Change executable* points its
|
||||
entry at the new file.
|
||||
|
||||
### Added
|
||||
|
||||
- **RE Engine and FromSoftware games are detected.** Capcom's RE Engine titles (RESIDENT EVIL 2/3/4/7/Village, Devil
|
||||
May Cry 5, Monster Hunter Rise/Wilds, Street Fighter 6, Dragon's Dogma 2, Onimusha…) by their `re_chunk_000.pak`
|
||||
archive; FromSoftware's (DARK SOULS II/III, ELDEN RING, Sekiro…) by their `.bhd` + `.bdt` archive pairs. Both are
|
||||
relative signals — a file layout, not a proof — like every engine rule. Every game in the library is re-detected on
|
||||
the next sweep. Engines are now shown by name ("RPG Maker MV/MZ", "Unreal Engine") instead of the rule's id
|
||||
(`rpgmaker_mv`). A game added by hand whose executable says nothing (`Game.exe`) is named after the game — RPG
|
||||
Maker's own title when the folder carries one, else its folder — instead of "Game".
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Another game's `Game.exe` no longer runs under a library entry — no wrong name, no second session.** On
|
||||
2026-09-23 00:16 *HELLO, HELLO WORLD!* (itch) started its RPG Maker runtime, `swiftshader\Game.exe`, and the Agent
|
||||
matched it by FILE NAME to the only entry named `Game.exe`, *Flower in Us*: it recorded the session under that name,
|
||||
which created a new "Flower in Us" entry at HHW's path, and an NW.js child process then matched the new entry and
|
||||
started a second session beside the first (57 s and 56 s). A process that matches an entry by file name only now
|
||||
starts nothing — unless it is that entry's own executable on a drive that changed its letter, in which case the entry
|
||||
follows it as before — and the log says once that it is not in the library. The same match can no longer move an
|
||||
entry onto another game whose `Game.exe` has identical bytes (every RPG Maker MV game ships the same one). One session
|
||||
per executable, whatever id its entry has; a session that could not be hooked is timed by its own executable instead
|
||||
of any process with its file name; the resolver says in the Agent's log why a process could not be read; an
|
||||
unreadable entry is logged once instead of every 15 s. **Changed:** a game whose folder moved records nothing until
|
||||
*Change executable* points its entry at the new file. The "Flower in Us" entry the old match created stays until you
|
||||
rename it (it points at HHW's `swiftshader\Game.exe`, the file to measure HHW by) or remove it.
|
||||
|
||||
- **One entry per game after a drive letter changes — the two side by side become one.** When the owner's USB drive
|
||||
came back as `H:` for a morning, a second entry was made for each game played from it, and once the letter was back
|
||||
neither entry could move onto the other's path: two of each game, and "could not be moved" in the log every 15 s.
|
||||
Now the Agent merges two entries for the same executable (same path on two letters, same size and modification
|
||||
time): the entry made first stays, the other's sessions join it, a block on either is kept, and no consent moves
|
||||
between them — it waits while either game runs. A game whose executable changed on the new letter (it was updated
|
||||
meanwhile) is followed with hooking off, as *Change executable* does; turn hooking on again to measure it. The
|
||||
library import no longer adds a game again when it is already in the library under another drive letter. And a
|
||||
database error during the Agent's 15 s library pass no longer stops the Agent.
|
||||
|
||||
- **A game removed from the library while it runs no longer loses its session — or stops the Agent at the next
|
||||
start.** On 2026-09-22 23:26 and 2026-09-23 00:25 a GIRLS' FRONTLINE 2 session ended `FAULTED` on the database's
|
||||
foreign key: its entry had been removed (and re-imported) while the game ran, and the session was written under the
|
||||
id it started with. Each left a `.partial` file, and the recovery that runs at every start would have failed on it
|
||||
the same way — with no guard, so the Agent's host would have stopped at every start and nothing would have been
|
||||
captured. Now the session is stored under the entry that holds its executable when the one it started with is gone
|
||||
(the re-imported entry); when no entry does — the game was removed with its sessions — it is dropped with a log line
|
||||
that says so. Recovery never throws: a file it cannot finalize is set aside as `<guid>.partial.failed`, kept for a bug
|
||||
report, and the next file is recovered. The `FAULTED` and end-of-session log lines now name the session, the game and
|
||||
its executable, and the Agent's host logs its own warnings and errors into `agent-*.log`.
|
||||
|
||||
- **A game that is recorded without measuring is shown while it runs.** A game with hooking off, one the guard
|
||||
refused, or one whose process could not be read is recorded (duration, sensors, the reason) since beta.5 — but the
|
||||
Agent announced only hooked sessions, so for as long as such a game ran the Dashboard said "Nothing is being
|
||||
captured." and the tray stayed idle. Now the live card shows it with the T2 badge, the elapsed time, the
|
||||
temperatures, "Recording duration and sensors only — nothing is measured." and why, in the sentence its summary will
|
||||
use (no FPS readout: nothing is measured, so nothing is shown); the tray turns to recording-only; the refusal notice
|
||||
appears when the game starts rather than when it exits. A Dashboard opened after a game started shows it at once
|
||||
(it used to wait for the next start), a session running when the App connects is in the tray, the notice after a
|
||||
session names that session's game (it could name the previous one), a session that fails is let go of instead of
|
||||
staying on the card, and an update downloaded after a session ends is ready to install instead of waiting for the
|
||||
App to reconnect. A game whose executable changed since hooking was turned on — after a store update, usually — now
|
||||
says so in its summary instead of `RefusedConsentMissing`.
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.7] - 2026-09-23
|
||||
|
||||
**The seventh pre-release: a program in the library can be left unrecorded, and Steam's own tools already are.** The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
|
||||
user:
|
||||
|
||||
- **The game page has a Recording switch.** Off, FrameLedger does not watch for that program at all — no session, no
|
||||
measurement, no injection — and a session of it that is running stops; sessions already recorded stay. The library
|
||||
card says **Not recorded**. Use it for a utility that starts with Windows: until now every program in the library was
|
||||
recorded whenever it ran, at every boot.
|
||||
- **Steam's own tools already in your library start with it off** — Borderless Gaming, Wallpaper Engine, SteamVR,
|
||||
Blender, the Steam runtimes and Proton — so a tool imported before 0.1.0-beta.5 stops being recorded without you
|
||||
doing anything.
|
||||
- **The Privacy Policy (2.3) and the Disclaimer (2.6) are updated**, so the Legal Gate opens once after the update.
|
||||
|
||||
**Updating from `0.1.0-beta.6`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0009 adds one column; the database opens in place, and the Steam tools above are switched off once.
|
||||
- Sessions a tool recorded before stay in its history; to remove them, remove the entry with *Delete sessions too* —
|
||||
the import will not add it again.
|
||||
|
||||
### Added
|
||||
|
||||
- **A library entry can be left unrecorded.** Borderless Gaming starts with Windows, and every program in the library
|
||||
was recorded whenever it ran — so each boot added a session of it, for as long as it ran, to the playtime totals. The
|
||||
game page now has a **Recording** switch: off, FrameLedger does not watch for that program at all — no session, no
|
||||
measurement, no injection — and a session of it that is running stops (sessions already recorded stay). The library
|
||||
card says **Not recorded**. Entries an earlier import made for Steam's own tools (Borderless Gaming, Wallpaper Engine,
|
||||
SteamVR, Blender, the Steam runtimes and Proton) start with it off; the import has skipped them since 0.1.0-beta.5.
|
||||
The Privacy Policy (2.3) says so — a program whose recording is off is not watched — and the Disclaimer (2.6) carries
|
||||
the updated accuracy statement, including the correction made in 0.1.0-beta.6; the Legal Gate shows both once after
|
||||
the update. Schema 0009 adds one column; the database opens in place.
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.8] - 2026-09-25
|
||||
|
||||
**The eighth pre-release: anti-cheat is found before you ask, a session says what the game and the driver were, and
|
||||
a frame-generation session's numbers and charts are the application's.** The same unsigned installer: verify its
|
||||
hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **Anti-cheat is looked for harder, and before you ask.** Twenty-two families (74 entries), any kernel driver in a
|
||||
game's folder, and per-title lists by Steam app id and executable name. The Agent checks every game in your library
|
||||
on its own, turns hooking off for those with anti-cheat, and their pages show what was found instead of the hooking
|
||||
switch. Their sessions are still recorded, with play time and sensors.
|
||||
- **A game's page says what its files say** — 64-bit or 32-bit, the file and store versions, the DLSS / FSR / XeSS
|
||||
libraries it ships — and a 32-bit game's hooking cannot be turned on.
|
||||
- **NVIDIA App overrides are shown**: each session records the driver profile the game ran under (DLSS preset and
|
||||
mode, frame generation, Smooth Motion), read from the driver and never changed.
|
||||
- **Reasons read as what they are**: End task is not a crash, a refusal says what happened, a launch that could not
|
||||
start says why, a missing executable says whether its drive is disconnected.
|
||||
- **Trend works on first open**, with Native and Presented FPS as two metrics, and FPS can show two decimals
|
||||
(Settings ▸ Window).
|
||||
- **A frame-generation session's lows, median and stutter are over application frames**, a pause no longer counts as
|
||||
one long frame, and the charts draw what they say — including the sensors of a session that was not hooked.
|
||||
- **The Privacy Policy (2.4) is updated**, so the Legal Gate opens once after the update: it now names what the
|
||||
software reads to check every library game for anti-cheat, the version information of the game's files, and the
|
||||
NVIDIA driver's settings for your games — all on your PC, none of it sent anywhere.
|
||||
|
||||
**Updating from `0.1.0-beta.7`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schemas 0010–0013 add columns; the database opens in place.
|
||||
- Shortly after the Agent starts it checks every game in your library for anti-cheat, once; a game where it finds
|
||||
some has its hooking turned off for good, with a notice if hooking was on.
|
||||
- Sessions recorded before keep the numbers they were stored with; the corrected lows and the in-step sensor overlay
|
||||
apply to sessions recorded from now on.
|
||||
|
||||
### Added
|
||||
|
||||
- **FrameLedger finds the anti-cheat games in your library on its own, and hides their hooking switch** (owner decision
|
||||
2026-09-25). The Agent now scans every game in the library for anti-cheat — once, and again whenever the rules or the
|
||||
game's executable change — where until now it scanned only a game someone asked to hook, so most games had never
|
||||
been scanned at all. A game it finds anti-cheat in has its hooking turned off for good, as any finding does, and a
|
||||
notice says so when hooking had been on. The library card says **Anti-cheat**; the game's page says what was found —
|
||||
"BattlEye — its module BEClient_x64.dll was loaded in the game", "Easy Anti-Cheat — its folder EasyAntiCheat ships
|
||||
with the game", in your language — in place of the Hooking switch, which could only be refused. Settings ▸ Capture ▸
|
||||
*Hide hooking on anti-cheat games* (on by default) brings the disabled switch back beside the finding. Sessions of
|
||||
such a game are still recorded, with play time and sensors. The scan reads the game's files only: it opens no process
|
||||
and decides nothing on its own — every session start still runs the full check. Schema 0010 adds three columns; the
|
||||
database opens in place, and the first scan of the library runs when the Agent starts.
|
||||
- **The game page has a Details card: what the game's files say about it.** Whether the executable is 64-bit (x64),
|
||||
32-bit (x86), ARM or .NET "any CPU"; its file and product versions; the store's build ("Steam build 20374416" — the
|
||||
subtitle labels it that way too, instead of a bare number); the engine; and the upscaler and frame-generation files
|
||||
it ships with their versions — "DLSS: nvngx_dlss.dll 3.7.10.0", Streamline, FSR, XeSS. FSR is named by its file: its
|
||||
DLL's version is the SDK's, and FrameLedger does not guess which FSR that is. The capture agent reads every game in
|
||||
the library once after the update. Schema 0011 adds four columns; the database opens in place.
|
||||
- **A session's summary lists the libraries the game had loaded** — recorded since the first beta and shown nowhere
|
||||
until now — and says when one differs from the copy the game ships ("nvngx_dlss.dll 310.2.1.0 (the game ships
|
||||
3.7.10.0: another copy was loaded, for example by the driver or the NVIDIA App)").
|
||||
- **FPS with two decimals** (Settings ▸ Window ▸ *Show FPS with two decimals*, off by default): every FPS figure reads
|
||||
"62.40" instead of "62". Whole numbers now round half up (62.5 is 63); they rounded half to even.
|
||||
- **FrameLedger says when the NVIDIA App overrides a game's DLSS.** Each session now records the NVIDIA driver profile
|
||||
the game ran under — read from the driver's own settings, never from the game — and its summary says what that
|
||||
profile overrides: "NVIDIA profile “…”: DLSS override (preset K, Quality) · Frame Generation override (×4)", Ray
|
||||
Reconstruction, Streamline's override, a forced frame-generation mode, Smooth Motion. It also says what the driver
|
||||
reported applying inside the game ("DLSS DLL chosen by the driver · preset K · Quality"), and the game page's Details
|
||||
card names the overrides from the newest session. These are the driver's settings, not measurements: what FrameLedger
|
||||
measured is shown as before. FrameLedger only reads these settings; it never changes them. Schema 0012 adds one
|
||||
column; the database opens in place.
|
||||
- **A 32-bit game's hooking switch cannot be turned on, and the page says why**: FrameLedger's hook runs in 64-bit
|
||||
games only. Until now the switch turned on and every launch was refused by the guard. A 32-bit game whose hooking
|
||||
was already on has it turned off the first time the capture agent reads it; its sessions are still recorded, with
|
||||
play time and sensors.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The anti-cheat blocklist names twenty-two families, twice as many, most through more than one signal.** New:
|
||||
EA AntiCheat, Activision Ricochet (`randgrid.sys` and its `atvi-randgrid_*` services — the family 19_SAFETY carried
|
||||
as "no data yet" since August), NetEase Anti-Cheat, NetEase Yidun, Nexon Game Security (BlackCipher), TenProtect,
|
||||
AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion. Existing families gained the groups they
|
||||
lacked: BattlEye's driver `BEDaisy.sys` and its services, FACEIT's and ESEA's drivers and services, HoYoverse's
|
||||
`HoYoKProtect.sys` (which the `mhyprot` prefix never matched), Xigncode3's driver and service, Denuvo Anti-Cheat's
|
||||
driver, GameGuard's folder, files and service, EAC's `start_protected_game.exe` launcher and setup files. 19 entries
|
||||
became 74 (rules `2026.09.3`). Every new name is documented — SteamDB's file-detection rules (MIT), the vendors'
|
||||
support pages, LOLDrivers, DRML — and none is measured on a real title yet; each entry's `note` says which. Three
|
||||
services are deliberately left out because they run outside play and would refuse every session on the machine:
|
||||
`EAAntiCheatService`, PunkBuster's `PnkBstrA`, and Denuvo's update service.
|
||||
- **Check 3 is live in both halves, and the per-title lists are seeded** (rules `2026.09.4`, owner decision
|
||||
2026-09-25). The store half reads the store's own files through a seam the guard owns — `appmanifest_*.acf` in the
|
||||
Steam library that holds the game, `goggame-<id>.info` for GOG — so nothing is handed in by a caller and nothing is
|
||||
read from the game. 30 Steam app ids and 33 executable names across nine families are listed: Valve's VAC titles
|
||||
(CS2, Dota 2, TF2, Deadlock and the older ones), VALORANT and League of Legends, Roblox, Blizzard's online titles,
|
||||
Call of Duty, Marvel Rivals, NARAKA, FragPunk, Once Human, Delta Force, Arena Breakout: Infinite, HoYoverse's games,
|
||||
Battlefield 2042/6 and EA SPORTS FC 25/26 — the titles whose anti-cheat leaves nothing of the game's own for the
|
||||
other checks to find. A game no store names is not refused by this half; a Steam library whose manifests cannot be
|
||||
read is. Both lists are floored like the families, so a rules file can add a title and never take one off, and the
|
||||
validator refuses names engines share (`Game.exe`, `Client-Win64-Shipping.exe`…). The AreWeAntiCheatYet bulk list was
|
||||
considered and declined: community data that outlives a game's anti-cheat would turn hooking off for good.
|
||||
- **Any kernel driver in a game's folder counts as anti-cheat** (owner decision 2026-09-25). A `*.sys` file in the
|
||||
install tree that no rule names is reported as "Kernel driver in the game folder" and turns that game's hooking off,
|
||||
like any finding. Every driver found in a game so far was an anti-cheat's; this catches the next one before anyone
|
||||
names it. It is code, so no rules file can remove it — and a game that ships a driver for another reason loses
|
||||
hooking with no way back, which is the trade the owner took.
|
||||
- **FSR 3's and XeSS's DX11 libraries count as "Supports FSR" / "Supports XeSS"** (rules `2026.09.5`):
|
||||
`ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` and `libxess_dx11.dll` matched no rule before.
|
||||
- **The guard holds 256 blocklist entries instead of 64** (2 × 74 no longer fitted the worst case of the compiled-in
|
||||
floor plus a drifted file). The parsed rules are ~530 KB, so they are now reset in place instead of being copied from
|
||||
a temporary: the Vulkan layer parses them on whichever of a game's threads creates its Vulkan instance, and a
|
||||
temporary that size on a small thread stack would crash the game. The native tests hold them on the heap.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A frame-generation session's lows, median, min / max, σ and stutter count are over application frames**, as
|
||||
`03_METRICS` always said they were: they were computed over every present, generated ones included, so a ×2
|
||||
session's 1% low could sit above its native average, and a game that submits its generated frames in a burst —
|
||||
the owner's Onimusha demo capture, DLSS frame generation ×3 — read a median of 2,073 FPS at a native 60. Sessions
|
||||
recorded before this release keep the numbers they were stored with; their charts use the corrected rule.
|
||||
- **Pausing capture no longer puts a pause-long frame and the paused minutes into the session.** The first frame
|
||||
after a resume was measured from the last one before the pause; it follows a gap now, and every average is over
|
||||
the time that was measured. Records lost when the capture agent fell behind are left out of that time the same way,
|
||||
so an average reads the rate the game ran at rather than the survivors spread over the lost time.
|
||||
- **The charts are honest about what they draw.** The frametime chart's default line is application frame to
|
||||
application frame (it was each frame's interval to the generated frame before it), of the one swapchain the
|
||||
statistics are over (two swapchains' intervals were drawn interleaved); the every-present line no longer draws
|
||||
0 ms frames after gaps and says that presents are timed at submission; segments are labelled with their settings;
|
||||
the sensor overlay is in step with the frames (it was drawn from the session's start, tens of seconds early —
|
||||
schema 0013 records where the first frame sits, so sessions recorded before keep the overlay off). The histogram
|
||||
is binned over the 0.5th–99.5th percentile with its bars centred on their bins; the percentile curve and its
|
||||
1% / 0.1% low markers are drawn only where the session has the frames for them, the rule the stat cards follow.
|
||||
The Sensors charts put power on a watt axis, call the memory plot *Memory*, leave out VRAM readings of 0, give
|
||||
every line its own colour in the light theme too, and chart **sessions that were not hooked** — their sensors
|
||||
were recorded and shown nowhere.
|
||||
- **A game's page updates when one of its sessions finishes** — its sessions, trend and header kept what the page
|
||||
opened with until it was left and reopened.
|
||||
- **The Trend tab was blank the first time a game's page opened.** It is drawn at once, on a date axis that keeps its
|
||||
label and the theme's colours. "Average" is two metrics now — Native FPS and Presented FPS — so a line never mixes
|
||||
the two, and never shows a presented rate that includes generated frames. Temperatures, loads, power and memory
|
||||
include sessions recorded without hooking; points that describe only part of their session are drawn hollow; several
|
||||
hardware changes on one day are one marker.
|
||||
- **A steady-state frame-generation factor always shows the share of the session it covers** — the average card,
|
||||
Compare and the Sessions grid's FG× column dropped it. The game header's "Lifetime average" was the last measured
|
||||
session and is labelled so.
|
||||
- **Compare**: the best value is highlighted in the accent colour (it was only bold), two values that read the same are
|
||||
both best, CPU and GPU load are not ranked, the percentile chart spans 0–100 again, and exported PNGs have a solid
|
||||
background.
|
||||
- **Ending a game with End task is no longer a "crash".** Every non-zero exit code was one, and Task Manager leaves 1.
|
||||
A crash is now an exception's exit code or Windows' own crash record, and the session summary says how each session
|
||||
ended: "crashed (0xC0000005 access violation)", "ended with exit code 1 — what End task and taskkill leave". The
|
||||
crash safety still counts an early abnormal exit of either kind, so hooking still turns itself off after two in a row.
|
||||
- **Reasons read as what they are.** Every way a session can end has its own sentence, a refusal that names no
|
||||
anti-cheat says what happened ("the game is 32-bit…", "the game's process could not be opened") instead of calling
|
||||
its detail "detected in this game", a launch that could not start says why (for example "the game requires
|
||||
administrator rights"), and a missing executable says whether its drive is disconnected or the file is gone. A
|
||||
refusal's details were stored so that a detail could be read as an anti-cheat's name; they are stored in three fixed
|
||||
places now, and older sessions are read correctly.
|
||||
- **The NVIDIA bridge's native test could not fail on a machine with an NVIDIA GPU.** It was registered to pass on
|
||||
its "which branch" line alone, which makes ctest ignore the exit code; its reference-counting check had been failing
|
||||
on every GPU machine unseen. The check is corrected and a failed assertion now fails the test.
|
||||
- **Turning hooking on for an Unreal game now sees its `EasyAntiCheat` folder.** The scan that runs when hooking is
|
||||
enabled was given the executable's own folder — `<game>\<Project>\Binaries\Win64\` for Unreal titles — and scanned
|
||||
exactly that, while `EasyAntiCheat\` sits at the game's root. The session-time scan always looked at the root, so no
|
||||
injection was ever allowed by the gap, but the toggle could be switched on and the refusal came only at launch. The
|
||||
guard now takes the executable and finds the root itself, and also checks the executable's name and its store id.
|
||||
- **A game blocked for anti-cheat no longer offers "Turn hooking back on" after a crash auto-disable.** The button
|
||||
could only be refused.
|
||||
- **19_SAFETY's fixture rule is enforced for every family, not eleven.** A generated test walks every value of the
|
||||
shipped seed and requires it to match its own family in its own group — which also catches a later row that an
|
||||
earlier prefix shadows. The rules file's note that called XIGNCODE3's `x3.xem` "not a loadable module" is corrected:
|
||||
XIGNCODE3 loads it as its loader, so the modules group names it too.
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.9] - 2026-09-26
|
||||
|
||||
**The ninth pre-release: one narrow exception you can make yourself for a game whose only anti-cheat runs in user
|
||||
mode and that FrameLedger has measured before.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **A user-mode anti-cheat exception, per game, off by default** (Settings ▸ Capture). It is offered only where the
|
||||
only anti-cheat found runs entirely in user mode — no driver or service, no driver file in the game's folder — the
|
||||
game is on no title list, and FrameLedger has measured it hooked successfully at least twice. You make it one game
|
||||
at a time, after a disclosure that states the ban risk; the guard still runs every check under it and ends it on
|
||||
anything new, a crash or safety stop under it, or a game update. Sessions under it are marked.
|
||||
- **The Disclaimer (2.7) and the EULA (1.3) say so**, so the Legal Gate opens once after the update. The Privacy
|
||||
Policy is unchanged.
|
||||
|
||||
**Updating from `0.1.0-beta.8`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0014 adds columns; the database opens in place. Nothing changes for any game until you turn the option on.
|
||||
- With the option on, the Agent looks at each game whose hooking it turned off within a minute and lists the ones
|
||||
that qualify; a game shipping a kernel driver (Aniimo's `NEPKernel.sys`, for one) never does.
|
||||
|
||||
### Added
|
||||
|
||||
- **A user-mode anti-cheat exception you can make yourself, per game** (owner decision D33). Settings ▸ Capture ▸
|
||||
*Allow hooking in games with user-mode anti-cheat that were measured before* — off by default. On, it lists the games
|
||||
FrameLedger found eligible: the only anti-cheat in the game runs entirely in user mode (no driver or service, no
|
||||
driver file anywhere in the game's folder), the game is on no title list, and FrameLedger has measured it hooked
|
||||
successfully at least twice. **Make exception…** shows a disclosure — the ban risk, possibly days later and invisible
|
||||
to FrameLedger; what is still refused; how the exception ends — and asks you to accept the risk for that game. The
|
||||
exception turns nothing on: you then turn hooking on for the game on its page, through the usual consent dialog, and
|
||||
the guard still runs every check and refuses anything else it finds. The game's page shows the exception's state
|
||||
(eligible; not eligible and why; in force; suspended; ended and why), the library card says **Exception**, and a
|
||||
session hooked under it is marked in the Sessions tab and its summary. It ends by itself on a new finding, a crash or
|
||||
safety stop under it, FrameLedger stopping because another anti-cheat loaded, or a game update; turning the option
|
||||
off suspends every exception. Aniimo stays blocked: it ships a kernel driver (`NEPKernel.sys`).
|
||||
|
||||
- **Groundwork for the user-mode anti-cheat exception** (owner decision D33, 2026-09-26; the option, the list and the
|
||||
disclosure arrive later in this train). The guard can now be asked to let ONE named anti-cheat family through, and
|
||||
grants it only for a family whose every signal — in the built-in floor and in the rules file — is user-mode: no
|
||||
driver, no service, no `.sys` (on today's rules NetEase Yidun, AhnLab HackShield, Anybrain and FredaikisAntiCheat).
|
||||
It still runs every check and keeps scanning past what it let through, so a second anti-cheat, a kernel driver in
|
||||
the game's folder, a title list, a driver or service on the machine, or a scan that could not finish still refuses;
|
||||
a pass that let something through says so and names it. The injected Overlay learns the same family before it
|
||||
starts watching the game's module loads, so a late-loading module of that family does not stop it and any other
|
||||
anti-cheat still does. Nothing asks for any of this yet: every game is judged exactly as in beta.8.
|
||||
- **The Agent can grant, keep and end a user-mode anti-cheat exception** (D33; the Settings option, the list and the
|
||||
disclosure arrive in the next PR, so nothing in the App asks for one yet). With the option on
|
||||
(`hooking.usermode_ac_exceptions`, off by default), the Agent's library scan asks each blocked game one question —
|
||||
would the guard let exactly its blocking family through, with no kernel driver and nothing else found — and counts
|
||||
its successful hooked sessions; a game with both and at least two sessions is eligible. A grant rests on facts the
|
||||
Agent gathers itself when asked, is bound to the executable's bytes and turns nothing on: hooking is the usual
|
||||
consent dialog afterwards. Under it the Agent tells the Overlay the family before injecting, names it to the guard at
|
||||
the start and at every 30 s re-scan, and marks the session with it. It ends — hooking off, the block standing, the
|
||||
reason kept — on a new finding, a safety unhook, the Overlay stopping for another anti-cheat, a crash while hooked, a
|
||||
game update, or when the user withdraws it; turning the option off suspends every exception without deleting any.
|
||||
Schema 0014 adds the columns; the database opens in place.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Legal: Disclaimer 2.7 and EULA 1.3.** Disclaimer §2A describes the user-mode exception and its risk; the EULA's
|
||||
code-injection clause names it and what making one means. The accuracy block and SECURITY.md say it too. The Legal
|
||||
Gate shows the two changed documents once more; the Privacy Policy is unchanged (2.4).
|
||||
|
||||
Loaded 100 of 1771 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user