* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163) Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad; Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading. Every byte and reading under test was written by hand: no report from a real controller has passed through this code. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160) Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered, the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns. Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159) Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list. With no controller at hand, what the reader does with one connected is not established. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): no using that makes the file's own qualified names redundant (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * wip(input): the Agent records what a session was played with - the switch, the terms, the legal texts Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * style(input): import order in the Agent's composition; no redundant qualifier in a test (InspectCode) Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
89 KiB
06 — Data model (SQLite)
%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, (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 and two downgrades (corrected 2026-10-04): Change executable (2026-09-21, hook_* columnGameLibrary.ChangeExecutableAsync) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and Remove game ▸ Delete sessions too (FR-1.4) deletes the games row, cascading to its sessions, segments, blobs and annotations), session_annotations (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on sessions), settings, legal_acceptance. Both read everything. The ports say the same in their names: IGameRepository.UpdateMetadataAsync / SetTriStateDefaultAsync / RemoveAsync, ISessionAnnotationRepository, RegisteredSettings, ILegalAcceptanceStore.RecordAsync (all P3 PR-3).
Schema (v2 — hook architecture)
src/FrameLedger.Infrastructure/Persistence/Migrations/0001_init.sqlis normative since 2026-09-09 (P2 PR-B). The block below is the shape as drafted and is kept for its comments; the script adds what this document had no column for, each with the reason beside it in the script:
sessions.session_guid(UNIQUE) — the identity the.partialfile, the pipe and recovery key on (20_OPEN_QUESTIONS§G "Session identity");qpc_epoch+qpc_frequency— the time base the blobs and sensor series are aligned to (03_METRICS§Export, §Sensor aggregates);capture_mode(attach|launch); the drain's own accounting (drain_ticks,foreground_ticks,records_before_attach,dxgi_presents_before_hook,gap_count,guard_ticks_published,launch_wait_ms); the 2026-09 metric additions (presented_fps+presented_qualifier,dxgi_unseen_total/dxgi_present_samples/displayed_counted_by,sl_tag_census,sl_interposer_version,upscaler_driver_reported/fg_driver_reported/ngx_driver_words,fg_none_withheld_reason,runtime_modules,executable_markers,writer_status_at_end,early_stop_family,loader_signals).games.exe_size_bytes/exe_mtime_ms(theExecutableFingerprint),hook_consent_provenance(theConsentProvenanceNAME, defaultNotRecorded),hook_consent_disclosure_version,hook_prescan_state(not_run|clean|blocked|unverified— the third state one nullablehook_blocked_reasoncould not carry; nothing in P2 clears the reason, per the owner question below),hook_autodisabled_at,hook_last_injected_at.frame_blobs.frame_index,swapchain_ids;sensor_blobsgains thet_msseries.fg_source's domain isapi|cadence|none|manual, NULL = not measured — this document saidapi|cadence|manualwhile03_METRICSnames rung 4none; the CHECK carries the union.- Every
*_at/*_msINTEGER is unix-ms UTC (CLAUDE.md §Coding conventions), stated in the script because it was stated nowhere in this file. QPC never leaves the pipeline exceptqpc_epoch/qpc_frequency.exe_pathisUNIQUE COLLATE NOCASE, because consent matchesOrdinalIgnoreCaseon the normalised full path and the index must agree with the lookup.
CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL);
CREATE TABLE games (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
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|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: 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)
-- hooking state (19_SAFETY)
hook_enabled INTEGER NOT NULL DEFAULT 0, -- 0 = Tier 2, i.e. nothing measured; default for every new game
hook_consent_at INTEGER, -- per-game informed consent timestamp
hook_blocked_reason TEXT, -- set by the static AC pre-scan; non-null = toggle disabled in UI.
-- 'Reason|Family|Signal' since 2026-09-25 (SqliteGameConsentStore.
-- BlockText), so the App can say it in the user's language; older
-- rows keep "Reason: Family Signal" and are shown as stored
hook_prescan_rules_version TEXT, -- schema 0010 (2026-09-25): the key the Agent's pre-scan of the
hook_prescan_exe_size_bytes INTEGER, -- library last scanned the row under — the rules version and the
hook_prescan_exe_mtime_ms INTEGER, -- executable's size and mtime; NULL = never scanned by the sweep.
-- Change executable clears them with hook_prescan_state
-- schema 0014 (2026-09-26, D33): the user-mode anti-cheat exception, a layer OVER hook_blocked_reason, never its clearing
ac_exception_eligible INTEGER NOT NULL DEFAULT 0, -- the Agent's sweep: the exception may be granted now
ac_exception_verdict TEXT, -- its tolerant pre-scan, Reason|Family|Signal; NULL = nothing asked
ac_exception_sessions INTEGER NOT NULL DEFAULT 0, -- 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,
ac_exception_checked_block TEXT,
ac_exception_at INTEGER, -- the user's grant; NULL = no exception in force
ac_exception_family TEXT, -- the family it covers (kept as history once it ends)
ac_exception_disclosure_version TEXT, -- AntiCheatExceptionDisclosure.Version the user accepted
ac_exception_exe_size_bytes INTEGER, -- the executable the grant was made on; other bytes end it
ac_exception_exe_mtime_ms INTEGER,
ac_exception_lapsed_at INTEGER, -- when and why the last grant ended (UserModeExceptionLapse:
ac_exception_lapsed_reason TEXT, -- Withdrawn|ExecutableChanged|NoLongerEligible|NewFinding|
-- SafetyUnhook|OverlayStopped|SessionCrashed|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
-- array of the rule ids of rules/detection-rules.json (dlss, dlss_g, dlss_rr, streamline,
-- fsr, xess, xefg), written whole by the Agent's detection sweep; this line used to spell
-- the App's tokens (dlssg/dlssd), which the App still reads for older rows
-- tri-state defaults inherited by new sessions
rt_default TEXT NOT NULL DEFAULT 'na',
pt_default TEXT NOT NULL DEFAULT 'na',
rr_default TEXT NOT NULL DEFAULT 'na',
detection_rules_version TEXT,
exe_machine TEXT, -- schema 0011 (2026-09-25): what the executable runs as, from its PE
-- headers (x64|x86|arm64|arm|anycpu|anycpu32|other|unknown); NULL =
-- not read by this build yet, which the detection sweep reads as stale
exe_file_version TEXT, -- schema 0011: the executable's PE FileVersion (the file's word; game_version
exe_product_version TEXT, -- is the store's or the user's) and its ProductVersion
library_versions TEXT, -- schema 0011: JSON array, the capability files the game SHIPS —
-- {"capability","path","fileVersion","productVersion"}; what a session
-- LOADED is sessions.runtime_modules
field_provenance TEXT, -- JSON: {"engine":"detected","publisher":"user",...}
-- absent or unrecognised reads as "user"
added_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
);
field_provenance— decided now, implemented in P2. FR-1.3 requires auto-detected fields to be badged and overridable, and there was nowhere to record which was which. One JSON column rather than a column per field, matching thecapability_flagsprecedent in the same table: the overridable set is small and fixed (engine,engine_version,platform,store_id,publisher,game_version,name,cover_path), and a normalised override table would mean a join on every library-card render.Absent reads as
user, deliberately. Of the two ways to be wrong, badging a 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 auserfield — is in05_DETECTION§Caching and is enforced byStaticDetectionResult.ShouldWrite, which is tested even though nothing persists yetSqliteGameRepository.FieldProvenance.Resolve(corrected 2026-10-04: applied per field since P4 PR-1, and it also fills an empty field that has no entry;ShouldWritekeeps 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 intoWritten 2026-09-09 (P2 PR-B), with its first consumer: the column exists in0001_init.sqlbefore its consumers exist maximises the chance of baking in a wrong guess that can only be appended to.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 only adapter today is a file inside the unshippedFrameLedger.CaptureHost.
- A disclosure provenance.
hook_consent_atis a bare timestamp and cannot distinguish a stamp made after FR-2.1's reviewed dialog from one made after 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 reviewedSafety_*wording in en/vi/ja andno(superseded: the dialog shipped in P3 PR-4 as.resxexists anywhere in this treeConsentDialog, below — corrected 2026-10-04).- A disclosure/wording version.
legal_acceptancecarries(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 from the first record because retrofitting one means treating unversioned consent as either current or stale, and both are wrong about some record.- A third pre-scan state.
hook_blocked_reasonis two-state by definition here — non-null disables the toggle — while05_DETECTIONmakes the pre-scan tri-state, and says explicitly that "could not verify" must neither disable the toggle (a false refusal with no appeal) nor be cleared (a fail-open). One nullable TEXT column cannot carry three states.The file-backed record was NOT a migration source, and was not migrated. It lived in a build output,
git cleanremoved it, and when thegamestable was written (2026-09-09, P2 PR-B) it was written from this document — the file store and its DTOs were deleted the same day. The two fields the consumer needed and this table lacked are columns now:hook_consent_provenanceandhook_consent_disclosure_version; the third pre-scan state ishook_prescan_state.ConsentProvenancehas a third name since 2026-09-10 (P2 PR-F) — and a fourth,ConsentDialog, since 2026-09-13 (P3 PR-4), the only one a shipped user path produces:AgentConsoleOperator, the Agent's own--console consent grant(HANDOFF §P2 decision D4) — a shipped producer, still not FR-2.1, stamped by the Agent's clock; the store writes the NAME the acknowledgement carries and refusesNotRecorded.
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 clearshook_blocked_reasonwhen 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 the toggle is permanently disabled and that user action is impossible, while a managed component that clears it is deciding an anti-cheat fact. Nothing in this tree clears it today, which leaves the state unreachable rather than wrong.
CREATE TABLE hardware_snapshots (
id INTEGER PRIMARY KEY,
hash TEXT NOT NULL UNIQUE, -- sha256 of normalized fields
cpu_name TEXT, gpu_name TEXT, gpu_driver TEXT,
ram_gb REAL, os_build TEXT,
display_res TEXT, display_hz REAL,
captured_at INTEGER NOT NULL
);
CREATE TABLE sessions (
id INTEGER PRIMARY KEY,
game_id INTEGER NOT NULL REFERENCES games(id) ON DELETE CASCADE,
snapshot_id INTEGER NOT NULL REFERENCES hardware_snapshots(id),
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.; 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
exit_status TEXT NOT NULL, -- normal|crashed|unhooked_safety|degraded|interrupted
-- Layout v3 (2026-08-05) changed four things here, and none had shipped:
-- * `hdr INTEGER` -> `hdr_flag`/`hdr_source`, matching the three tri-states
-- beside it. The record's `hdr` bool became `colorSpace` and a bool has no
-- third state; an INTEGER column would have reintroduced zero-means-two-
-- things one layer down.
-- * `dlss_rr` leaves the `upscaler` domain. RR is an independent axis and is
-- already stored as `rr_flag`; it was a mutually exclusive upscaler VALUE in
-- the record, which is the conflation v3 removed. A session where DLSS-SR
-- and RR ran together stores `upscaler='dlss'` with `rr_flag='yes'`.
-- * `rt_tier` + `hooks_installed_mask`: 03_METRICS' definite RT `No` needs
-- both, and neither had a column. Without them the verdict is decided at
-- finalize from evidence that cannot distinguish "no rays" from "no hook".
-- * `upscaler_sharpness`, so the accessor hook's yield has somewhere to land.
-- Free exactly once: 0001_init.sql does not exist yet (see below).
-- 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: 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, 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,
upscale_ratio REAL,
settings_changed_midsession INTEGER NOT NULL DEFAULT 0,
-- 'na', NOT 'none', and the default is the whole point. `none` means "a hook ran and
-- there was genuinely no frame generation" -- the one state 03_METRICS allows to be
-- aggregated as a negative -- so a DEFAULT of 'none' reinstates at the storage layer
-- exactly the affirmative negative the writer and the consumer both refuse
-- (fl_shm.h: FL_FG_NOT_REPORTED is 0 in v3; MeasuredFacts.FgMode is null, never "none").
-- Matches hdr_flag/rt_flag/pt_flag/rr_flag beside it, which were already 'na'.
fg_mode TEXT NOT NULL DEFAULT 'na',
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, …; 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
-- the loader reported in the process. NOT a measurement and never a source for fg_mode
-- or upscaler: it qualifies the presented figure when fg_mode is 'na' (03_METRICS §Rung
-- 0's qualifier). NULL = the writer predates the field; 0 = the census never ran.
fg_runtime_census INTEGER,
-- ray tracing (measured at tier 1)
rt_flag TEXT NOT NULL DEFAULT 'na', rt_source TEXT, -- measured|manual|inherited
pt_flag TEXT NOT NULL DEFAULT 'na', pt_source TEXT,
pt_confidence REAL, -- heuristic score, never auto-promoted to 'yes'
rr_flag TEXT NOT NULL DEFAULT 'na', rr_source TEXT,
rt_frame_pct REAL, rays_per_pixel REAL, rt_pso_count INTEGER,
rt_tier INTEGER, -- D3D12_RAYTRACING_TIER x10; NULL = not queried
hooks_installed_mask INTEGER, -- FlHookFamily union over the session
raster_pso_count INTEGER,
-- frame statistics
frame_count INTEGER NOT NULL, app_frame_count INTEGER NOT NULL,
displayed_frame_count INTEGER NOT NULL, dropped_frames INTEGER NOT NULL,
native_fps REAL, displayed_fps REAL,
median_fps REAL, p1_low_fps REAL, p01_low_fps REAL,
displayed_p1_low_fps REAL, -- 03_METRICS §Lows: stored for the
-- Displayed chart series, never the headline
min_fps REAL, max_fps REAL, frametime_stddev_ms REAL,
stutter_count INTEGER, stutter_time_pct REAL,
pso_stutter_pct REAL, -- tier 1 only
reflex_active INTEGER, latency_avg_us INTEGER, latency_p95_us INTEGER,
-- data quality
dropped_records INTEGER NOT NULL DEFAULT 0, -- ring overflow (agent stalled)
fault_count INTEGER NOT NULL DEFAULT 0, -- overlay hook faults
data_quality_warnings INTEGER NOT NULL DEFAULT 0,
-- memory & sensors
vram_proc_avg_mb REAL, vram_proc_max_mb REAL, vram_budget_exceeded_pct REAL,
vram_adapter_max_mb REAL,
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,
-- 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,
-- schema 0024 (2026-11-14, beta.50, D155-D163): what the session was played with, both tiers (03_METRICS §Input) -
-- read by the Agent from outside the game. Milliseconds. NULL before, with the option off, and before the terms
-- that describe the reading were accepted - N/A, never 0. From the samples, so a recovered session has them.
input_observed_ms INTEGER, -- the reader ran and the session was not paused
input_foreground_ms INTEGER, -- of it, a window of the game was in front: the four below add up to this
input_controller_ms INTEGER, -- a controller in use, the keyboard and mouse not
input_km_ms INTEGER, -- the keyboard or mouse in use (one class - only a time is read), no controller
input_both_ms INTEGER,
input_idle_ms INTEGER, -- no input at all
input_method_switches INTEGER, -- changes between a controller and the keyboard and mouse
input_source TEXT, -- the sources that answered: rawinput, xinput, lastinput, joined by +
input_devices TEXT -- InputDevicesRecord's JSON: {"V":1,"Devices":[{"Index","Family","VendorId",
-- "ProductId","Model","Connection","XInputSlot","Virtual","Remapped",
-- "ConnectedMs","ActiveMs","Connects","Disconnects","Battery":{"Scale",
-- "States":[{"State","Level","Ms"}],"First","Last","DrainPercentPerHour"}}],
-- "Families":[{"Family","ActiveMs","Share"}],"FamilySwitches","VirtualPad",
-- "Health":{...counts...}} - no serial number, no address, no path
);
CREATE INDEX ix_sessions_game_started ON sessions(game_id, started_at DESC);
-- resolution/upscaler changes within one session (03_METRICS §Upscaling)
CREATE TABLE session_segments (
id INTEGER PRIMARY KEY,
session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
start_frame INTEGER NOT NULL, end_frame INTEGER NOT NULL,
render_w INTEGER, render_h INTEGER, output_w INTEGER, output_h INTEGER,
upscaler TEXT, upscaler_quality TEXT, fg_mode TEXT,
native_fps REAL, displayed_fps REAL, p1_low_fps REAL
);
CREATE INDEX ix_segments_session ON session_segments(session_id, start_frame);
-- Per-frame series. Every column of the CSV export (03_METRICS §Export schema)
-- must be reconstructible from this table plus session_segments — the exporter
-- reads from here, not from the live ring.
CREATE TABLE frame_blobs (
session_id INTEGER PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
codec TEXT NOT NULL, sample_count INTEGER NOT NULL,
frametimes BLOB NOT NULL, -- float32[] ms
frame_flags BLOB NOT NULL, -- byte[] : generated/dropped/gap bits
rt_flags BLOB, -- byte[] : one per frame, all 3 bits preserved
-- (asBuildObserved | dispatchObserved | psoCreatedEver).
-- Collapsing these loses the inline-RayQuery distinction.
--
-- `rtPsoAlive` was the third bit's name here and is WRONG:
-- fl_shm.h renamed it FL_RT_PSO_CREATED_EVER because the
-- bit LATCHES -- creation is observed at CreateStateObject,
-- destruction is COM Release, which is not in the hook
-- inventory and must not be added -- so "alive" claimed a
-- present-tense fact the hook set cannot retract.
render_res BLOB, -- uint16[] : TWO pairs per frame (render W/H, output W/H),
-- 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; 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
-- keep the sensor overlay off rather than draw it out of step
);
CREATE TABLE sensor_blobs (
session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-- schema 0007 (2026-09-21) added five guard-override columns (games.guard_bypass_at,
-- games.guard_bypass_disclosure_version; sessions.guard_bypassed, guard_bypass_family, guard_bypass_signal) and
-- schema 0008 (2026-09-22) DROPPED them with the feature (19_SAFETY §What a finding does to the game). Sessions that
-- ran under it keep "guard-bypass=" in capture_notes.
series TEXT NOT NULL, -- cpu_temp|gpu_temp|gpu_hotspot|gpu_load|gpu_power|vram_proc|vram_adapter|cpu_load|ram_mb
-- (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
-- since schema 0024 (2026-11-14, D155-D163) also the INPUT series, every one under a
-- name that starts with `input.`: input.class (what the tick was mostly played with:
-- 0 no input, 1 controller, 2 keyboard and mouse, 3 both), input.dev.N.active (the
-- part of the tick's time in front controller N was in use, 0-1) and
-- input.dev.N.battery (its level, in its own scale) - NaN for a tick with nothing to
-- say, and read by FindInputSensorsAsync 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.
hz REAL NOT NULL, codec TEXT NOT NULL, data BLOB NOT NULL,
PRIMARY KEY (session_id, series)
);
CREATE TABLE session_annotations (
session_id INTEGER PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
tags TEXT, notes TEXT, -- tags: a JSON string array (P3 PR-3); a row that would be all NULL is deleted
-- schema 0002 (P3 PR-3): FR-8.3's per-session overrides live HERE, on the UI's table, beside the
-- measurement on sessions and never over it — clearing an override restores what was measured.
-- NULL = no override. sessions.rt_source stays the measurement's word.
rt_override TEXT CHECK (rt_override IS NULL OR rt_override IN ('yes', 'no', 'na')),
pt_override TEXT CHECK (pt_override IS NULL OR pt_override IN ('yes', 'no', 'na')),
rr_override TEXT CHECK (rr_override IS NULL OR rr_override IN ('yes', 'no', 'na'))
);
CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
-- keys in use: hooking.kill_switch = '1' (FR-2.4, P2 PR-F; anything else, or no row, is off)
-- the full key list is §Settings registry below (P3 PR-3)
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).
docis one ofeula/gpl/disclaimer/privacy(andalphasince 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);versionis the document's own**Version:**line as embedded in the App at build (GPL-3.0-onlyfor 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,disclaimerandprivacyonly, and the gate is not held open forgpl. Agplrow an earlier version wrote stays, unread (LegalGate).
Settings registry
HANDOFF §P3 decision D16, built as Application.Settings.SettingsRegistry (P3 PR-3, 2026-09-13) and
closing 20_OPEN_QUESTIONS §G's row. settings is key/value TEXT; the registry is the only key list, and
RegisteredSettings over ISettingsStore validates writes and tolerates reads — a hand-edited or
out-of-range row reads as the default, never as an exception. Booleans are exactly 1/0 (the kill
switch's rule); integers are invariant-culture within an inclusive range; choices are compared ordinally.
No "setting changed" message exists: the Agent re-reads its keys at each session start
(SettingsRecorderPolicy → RecorderOptions), and the UI owns the rest.
| Key | Kind | Default | Range / choices | Read by |
|---|---|---|---|---|
ui.language |
choice | en |
en · vi · ja |
UI |
ui.theme |
choice | system |
system · light · dark |
UI |
ui.start_with_windows |
bool | 0 |
UI (P4) | |
ui.minimize_to_tray |
bool | 0 |
UI (PR-8) | |
ui.hide_anticheat_hooking |
bool | 1 |
UI (beta.8, 2026-09-25): the game page of an entry the guard found anti-cheat in shows the finding in place of its Hooking card (08_UI §Game detail) |
|
ui.fps_decimals |
bool | 0 |
UI (beta.8, 2026-09-25): every FPS figure with two decimals ("62.40") instead of a whole number | |
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 |
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) |
capture.input_devices |
bool | 1 |
Agent, per session (FR-16, owner decisions D155 and D156, 2026-11-14): Controllers and input. On — and only once the Privacy Policy that describes the reading (2.22 or later) is in legal_acceptance (Application.Input.InputTerms) — a session has a view of the Agent's input reader and stores what it was played with (schema 0024); off, or before that acceptance, nothing of it is read or stored, and a session held back by the terms says so in its notes. Any row that is not exactly 0 is on. Settings ▸ Recording (21_INPUT_DEVICES) |
|
capture.input_devices |
bool | 1 |
Agent, per session (FR-16, owner decisions D155 and D156, 2026-11-14): Controllers and input. On — and only once the Privacy Policy that describes the reading (2.22 or later) is in legal_acceptance (Application.Input.InputTerms) — a session has a view of the Agent's input reader and stores what it was played with (schema 0024); off, or before that acceptance, nothing of it is read or stored, and a session held back by the terms says so in its notes. Any row that is not exactly 0 is on. Settings ▸ Recording (21_INPUT_DEVICES) |
|
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) |
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 | stableauto (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 |
An operator's bounded capture (--console … --seconds N, which lowers the discard threshold to N) keeps
its bound under any capture.min_session_s: the setting moves the product's rule, not the operator's.
Comparison safety
Because Tier-1 and Tier-2 sessions carry different fields, every query that compares sessions must filter or group by capture_tier. Since 2026-08-28 the difference is total rather than partial — a Tier-2 session has no frame data at all — so a mixed-tier overlay is not a degraded comparison, it is a comparison with nothing on one side. The Compare view refuses to overlay mixed tiers without an explicit "compare across tiers anyway" acknowledgement, and marks the chart accordingly. Likewise settings_changed_midsession = 1 sessions are excluded from trend lines by default (they average across a settings change and are misleading), with a toggle to include them.
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 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 overwrite skip, carries 0 with theframe_flagsgap bit set, so the statistics exclude it and the export still reconstructsqpc_ms.swapchain_idsis present only when the session held more than one stream. Schema 0013 (beta.8) addsframe_blobs.first_present_ms: the charts draw the dominant stream from its first present and the sensors fromqpc_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 tot_ms(milliseconds fromqpc_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.A reading taken inside a game stands at the sample that carried it (0.1.0-beta.49, owner decision D150): the Overlay publishes about once a second and the Agent samples exactly once a second, so a publication waits for the next sample — two may wait, the older is carried first (
PendingInGameReadings). Anadv.*point that came from a game can therefore stand up to a second after its read; a tick with nothing waiting is NaN.
t_msis the time axis;hzis the fallback (written here 2026-11-14, owner decision D146 — the code cited this rule before the page had it). Every series of a session is stored besidet_ms, which carries each sample's own time, and the App draws against it;hzis read only for a row that has not_ms(SessionSeriesLoader). Until 0.1.0-beta.48hzwas the constant 1, whatever the samples did — and they were not one second apart: the poller waited its whole interval after a poll's work. In the owner's ledger of 2026-11-14, under a setting of 1000 ms, 180 of the 186 sessions long enough to tell have a median of 1.32 s between samples; six have 1.0 s. What takes the third of a second is not established. Unelevated — the layers composed as the Agent composes them, each read under a stopwatch — a poll takes about a millisecond. The two sessions with nocpu_tempseries (an Agent that was not elevated) are among the six, which points at the sensor library's processor update, run on the poll's thread as administrator with PawnIO; but four sessions that have the series kept one second, and the call itself was not timed (it needs elevation). Since 0.1.0-beta.48 the poller keeps a fixed period (TelemetryPoller.UntilNextTick) andhzis the rate the session's samples had, measured from the samples (SessionFinalizer.SampleRate: the gaps between the first and the last over the time between them, to a thousandth; 1 for fewer than two) — so it is right for a session recovered from a.partialfile as well. Rows written before keep their 1.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:EncodeFloat32throws on a NaN as before, because a frame time has no gaps. Both decode withDecodeFloat32.ISessionRepository.FindSensorsAsync— what every summary, chart and export reads — leaves theadv.rows out (series NOT LIKE 'adv.%'), since those readers drop every negative value as "no reading";FindAdvancedSensorsAsyncreturns them witht_msfirst. 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 input series follow the same rule under their own name (schema 0024, owner decisions D155–D163). A series whose name starts with
input.stores NaN for a tick with nothing to say — the game was not in front, the controller was not connected, the tick carried no reading — through the same sparse encoder.FindSensorsAsyncleaves them out as well (series NOT LIKE 'input.%'): a class's number is not a sensor's value, and the sensors' statistics and chart would take it for one.FindInputSensorsAsyncreturns them witht_msfirst. A session storesinput.classand, for each of its first eight controllers (InputSessionBuilder.MaxDevices),input.dev.N.activeand — where the battery has a level —input.dev.N.battery: at most seventeen, a few KiB an hour stored.
The .partial file
Built 2026-09-10 (P2 PR-D), as HANDOFF §P2 pre-committed it.
%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial(the unshipped host:tmp\beside its binary, decision D5), one per session, append-only, written at every state transition and every flush interval (60 s), deleted by the finalize's success, read by recovery at the next start. Format:chunk := u32 type | u32 length | payload | u32 crc32(type ‖ length ‖ payload), little-endian, and the valid prefix wins — the reader stops at the first chunk that is short or fails its check, so a kill at any byte loses at most the chunk being written (PartialSessionFileTestskills at every offset of a fixture and asserts exactly the complete chunks survive). The file is flushed to the OS after every chunk; the threat is the Agent dying, not the machine losing power.
type payload when 1 HeaderUTF-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 waiton create — the breadcrumb 19_SAFETY§Crash safety asks for before injection2 Recordsi64first ordinal, then N rawFlFrameRecord(64 B each); a chunk that does not continue the sequence is refusedeach flush 3 GapsN × i32gap-before record indiceseach flush 4 SensorsN × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null each flushread only since beta.12, so a beta.11 file still recovers (corrected 2026-10-04)5 Tickdrain/foreground ticks, dropped, gaps, guard ticks, wall clock, the raw FlWriterState; the last one winseach flush 6 Notewall clock + UTF-8 text: a state transition each transition 7 TouchesN × i64QPC at which the host touched the targeteach flush 8 SensorsWidethe 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 SensorsAdvancedthe advanced readings of the samples of the type-8 chunk before it (D101): u16names, then per nameu16bytes and UTF-8;u32samples, then per samplei64QPC,u16readings and per readingu16name,f64value. Each chunk carries its own names, so it reads without any earlier chunkeach 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 AdvancedContextUTF-8 JSON ( AdvancedJson.OfContext): the PC's facts, the session's, its series' directory, each source's state; the last one winsthe first flush after the recorder set it, and again only when it changed (2026-11-11) 11 SensorsInputthe input readings of the samples of the type-8 chunk before it (D155–D163, InputSampleCodec):u32samples, then per samplei64QPC, seveni32(span, observed, in front, controller, keyboard and mouse, both, no input),u8flags, the reader's health (u8answers, sixi64counts,i32faults),u8controllers and 23 bytes a controller — what it is (maker, the two USB ids, connection, XInput pad) and its part of the tick (connected, time in use, battery, connections, drops). Each sample describes every controller it counts, so a chunk reads without any earlier oneeach flush in which a sample carries one — with the option off, never; the file is then byte for byte what it was (2026-11-14) 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
_ => falseended 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 becomeinterruptedrows ended at the last flush (or the last record's clock), with every measured column computed from the prefix exactly as a live finalize would. Rejected: asessions_in_progresstable — a blob churn every minute, a lock fight with the UI in P3, and04_CAPTUREhad already named a file undertmp\.The header's
game_idis where the session started, not necessarily where it lands (2026-09-23). A live finalize and a recovery both askISessionRepository.ResolveOwnerAsync: that id when the row predates the session or holds the header's exe path; else the row that holds the exe path now (an entry removed and re-imported while the game ran); else nothing —FinalizeStatus.GameRemoved/RecoveryStatus.GameRemoved, file deleted, nothing written.games.idisINTEGER PRIMARY KEYwithout AUTOINCREMENT, so a deleted id can be handed to the next row added;added_atafter the session's start and another path is how that row is told apart. A file recovery cannot finalize for any other reason is renamed<guid>.partial.failed(IPartialSessionStore.Quarantine) — not listed again, not retried, kept for a bug report — and recovery goes on to the next file: it runs before the watcher on every start, and one file used to be able to stop them all.
Retention
Default: raw blobs for the last 20 sessions per game (configurable N or unlimited — retention.raw_sessions_per_game, 0 = unlimited, §Settings registry). Aggregates and segments kept forever. Sweep at finalize + on demand (Tools → DB maintenance, which also offers PRAGMA integrity_check, VACUUM, backup).
Built 2026-09-15 (P4 PR-7). The on-demand sweep is the Agent's: the App sends
SweepRetention(07_IPC), and the Agent runsISessionRepository.SweepRetentionAllAsync— the finalize's per-game rule for every game in one transaction,ROW_NUMBER() OVER (PARTITION BY game_id ORDER BY started_at DESC, id DESC), so the two can never disagree about which session is the Nth, and a removed game's kept sessions are swept like any other. A keep of 0 never reaches it: unlimited is honoured by not sweeping. The other three run in the App throughInfrastructure.Persistence.LedgerMaintenanceand change no row:PRAGMA integrity_check; a backup throughVACUUM INTO(a complete, consistent copy while the Agent keeps writing; never over an existing file and never onto the ledger, its WAL or its shared-memory file — the save dialog's "replace?" would otherwise have deleted the live database); and compaction,VACUUM+wal_checkpoint(TRUNCATE), refused while a freshGetStatusreports a session.LedgerDatabase.MaintainAsyncis the one way to run a statement outside a transaction, and it is for these statements only.
Migrations
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 intobackups\ledger-before-<version>.dbbeside 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 — throwsLedgerBackupExceptionand 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 isLedgerBackupTests', in scratch folders.
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 COLUMNonly — the three override columns onsession_annotationsandgames.removed_at.LedgerDatabaseTestsasserts oneschema_migrationsrow per script, soLatestVersionis 2.
0003_fg_refusal.sql(2026-09-14) —sessions.fg_refusal. The owner's ledger held two hooked rows withfg_mode = 'dlssg',fg_source = 'api'andfg_factorNULL — the identity stood, the count refused — and nothing recorded which refusal; every FG surface said N/A beside a detection that had succeeded. OneALTER TABLE ADD COLUMN, written by the Agent (SessionAggregator.ApplyFg), read by the UI for the "factor not counted" tooltip (08_UI§FPS display rule).LatestVersionis 3;LedgerDatabaseTestsasserts the column.
0004_detection_cache.sql(P4 PR-1, 2026-09-14) —games.detection_exe_size_bytes/detection_exe_mtime_ms. The detection cache key's exe half (05_DETECTION§Caching), apart fromexe_size_bytes/exe_mtime_ms, which are the consent fingerprint the gate reads and which a background scan must never refresh.LatestVersionis 4;LedgerDatabaseTestsasserts the columns.
0005_fg_refusal_detail.sql(2026-09-16) —sessions.fg_refusal_detail. 0003 recorded WHICH refusal took the factor; the owner's Dashboard then showed "DLSS-G active — factor not counted" on four titles with a tooltip that could only say "the frame-generation state changed mid-session", whileFgWindowhad computed which of the eight buckets departed, its ratio and the window's, andSessionAggregatorkept only the kind. The column isApplication.Recording.FgRefusalDetailas JSON (RecordingJsonContext): kind, subject, count, bucket index/count, the bucket's ratio (null when it held no tokens — infinity is not JSON) and the window's. Written by the Agent besidefg_refusal, read by the UI's tooltip (FpsPresentation.RefusalDetailText), never an input to a number. Existing rows keep NULL.LatestVersionis 5;LedgerDatabaseTestsasserts the column.
0006_fg_steady_state.sql(2026-09-17) —sessions.fg_factor_scope/fg_steady_share.fg_factorwas session-wide or NULL, and on real play it was almost always NULL (03_METRICS§The steady state).session= one state for the whole claimed span;steady=fg_factor/native_fps/displayed_fpsdescribe the state the session spent most of its generating time in,fg_steady_shareof the presenting time, withfg_refusaland its detail still set beside it. A reader that ignores the scope reads a steady factor as a session one, which is why every surface prints the share. Existing rows keep NULL.LatestVersionis 6.
0007_guard_bypass.sql(2026-09-21) and0008_withdraw_guard_bypass.sql(2026-09-22) — the first DROP. 0007 added five columns for the per-game guard override; the owner withdrew the feature a day later and 0008 drops them (ALTER TABLE … DROP COLUMN, SQLite ≥ 3.35 —LedgerDatabaseTestsasserts the engine's version beside the columns' absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The data dropped is the override acknowledgements themselves, which is the decision.LatestVersionis 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.KnownToolsas of the script).LatestVersionis 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 0004's columns are the detection sweep's, and apart fromexe_size_bytes/exe_mtime_msfor the same reason (the consent fingerprint must never be refreshed by a background scan).ALTER TABLE ADD COLUMNonly; existing rows read NULL, which the sweep reads as "never scanned" and scans on its first pass.LatestVersionis 10;LedgerDatabaseTests.ScriptTenAddsThePreScanKeyEmptyForExistingRowsapplies it from 9 to a ledger holding a row.
0011_executable_facts.sql(2026-09-25) —games.exe_machine/exe_file_version/exe_product_version/library_versions. The owner asked for the game's version, its DLSS / FSR versions and 32- or 64-bit; the detection sweep read the PE version resource and walked the tree for the capability files, and kept neither. Four columns, written whole by that sweep (05_DETECTION§What the files say about themselves) — facts about files, so no provenance and no user override. Existing rows read NULL, and a NULLexe_machinemakes the sweep read the row once more on its first pass.LatestVersionis 11;LedgerDatabaseTests.ScriptElevenAddsTheExecutableFactsEmptyForExistingRows.
0012_driver_profile.sql(2026-09-25) —sessions.driver_profile. The NVIDIA driver profile the session's executable ran under, read by the Agent's recorder beside every session (both tiers) through the NVAPI bridge's read-only DRS entry point (18_GPU_VENDOR_APIS§L3, ABI 2): JSON (Application.Recording.DriverProfileRecord) —Outcome(Application|Global|Degraded),Profile, and one entry per setting ofApplication.Capture.NvidiaDriverSettingswith itsValue(null = set in no profile),LocationandPredefined. A driver configuration, never a measurement (03_METRICS§Upscaling). NULL for every row before, and where no NVIDIA bridge was there to ask. The same dayngx_driver_wordsgainedRatio,Mode,Preset,FgCount,FgPreset,FgModebeside its masks (additive JSON fields; older rows lack them).LatestVersionis 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 fromqpc_epoch, written by the finalizer (§Blob encoding); NULL before, and such a row's sensor overlay stays off rather than drawn out of step.LatestVersionis 13;LedgerDatabaseTests.ScriptThirteenAddsTheFirstPresentColumn.
0014_usermode_ac_exception.sql(beta.9, 2026-09-26, owner decision D33) — the user-mode anti-cheat exception. Fourteengames.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 — andsessions.ac_exception_family, the family a HOOKED session ran under the exception with.ADD COLUMNonly; no row changes, so a blocked row stays blocked, not eligible, with no grant, until the Agent and the user say otherwise (19_SAFETY§The user-mode exception). Written throughIGameConsentStoreonly —RecordExceptionEligibilityAsync(the sweep),GrantAntiCheatExceptionAsync(theSetAntiCheatExceptioncommand; the store appliesUserModeExceptionRules.IsEligibleitself),RevokeAntiCheatExceptionAsync(every end) — plus one downgrade inChangeExecutableAsync, which ends a grant (ExecutableChanged) and forgets the eligibility. The grant and the eligibility are each bound in SQL to the block they were reached about.LatestVersionis 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 byApplyDetectionAsynconly where the run's version was taken (auserfield keeps none), cleared by a user's edit of the version (UpdateMetadataAsync). The script's one data change removes the bare4/5the old Unreal rule wrote (a two-group regex returning its first group) — only wherefield_provenancesaysdetected: 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 forAND).LatestVersionis 15;LedgerDatabaseTests.ScriptFifteenAddsTheWitnessAndRemovesOnlyTheOldRulesDetectedDigit.
0016_display_mode.sql(beta.10, 2026-09-27) — how the game was shown. Fifteensessions.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.SessionRowColumnsis hand-edited (its generator is not in the repository) and reads by name.LatestVersionis 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 byChangeExecutableAsync, 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.LatestVersionis 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_sourceandsensor_stats_json. Written by the recorder's aggregation for both tiers (SessionAggregator.WithSensorAggregates); a session before it reads N/A. Notvram_proc_*: those name the in-process DXGI figure compared with a budget (a different quantity,03_METRICS§Game process memory) and stay reserved. The.partialgains chunk type 8 (SensorsWide, a 32-bit mask with the game fields); type 4 is still read, so a beta.11 crash file recovers.LatestVersionis 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/ApplyEfficiencyfor a hooked session,WithSensorAggregatesfor 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.partialneeds no change: the six new sensor series are fields every sample already carried.LatestVersionis 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 ofDomain.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 asnon_uniform/ambiguous_band; NULL otherwise. A session before it has none and is never rebuilt from itsframe_blobs(one Generated bit per frame, the DXGI-counted presents lost). The.partialneeds no change: a recovered session is aggregated from its records like any other. Read by today's rule since beta.26:FgMixRecord.Parsefolds 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).LatestVersionis 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}besideruntime_modules—game,graphics_driver(Windows' driver store or%ProgramData%\NVIDIA) orwindows, 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\NGXwhatever 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).LatestVersionis 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 onsessions— the firstCREATE TABLEsince 0001. Every read of asessionsrow, 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 offacts_json); it stands besidehardware_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 ofsensor_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 isApplication.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 isGame, after the driver's, andsources.inGame(Reading,NothingSeen,NotHooked; absent in a row beta.39 wrote, which reads as "not said") — and its two series areadv.ffx.upscale.frame_time_deltaandadv.ffx.memory_usageinsensor_blobs. Since 0.1.0-beta.43sourcesmay also holdstreamlineConstantsandfsrFrameGeneration(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 alsostreamlineFeatureVersionandstreamlineFeatureRequirements, the same three values for the two questions a game asks Streamline about a feature — whereNeverCalledis the usual one, a game asking while it starts — and the factssl.feature.versionsandsl.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 factssl.feature.supportandsl.feature.lifecycle, rows named<feature> · <call>(slShutdownalone 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'sadv.series with its other raw series and keeps its row. Written by the Agent only, in the session's own transaction (SqliteSessionRepository.InsertAdvancedAsync).LatestVersionis 23;LedgerDatabaseTests.ScriptTwentyThreeCreatesTheTwoAdvancedTablesAndAnEarlierSessionHasNoRow(whose helper now undoes a script'sCREATE TABLEandCREATE INDEXas well as itsADD 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.
0024_input_devices.sql(0.1.0-beta.50, 2026-11-14, owner decisions D155–D163) — what a session was played with, and what a store lists. ADD COLUMN only, twelve columns. Nine onsessions:input_observed_ms,input_foreground_msand the four classes that add up to it (input_controller_ms,input_km_ms,input_both_ms,input_idle_ms),input_method_switches,input_source, andinput_devices— the session's controllers asApplication.Recording.InputDevicesRecord's JSON (03_METRICS§Input). Onsessionsand not in a table of their own, on purpose (D160) — the opposite of 0023's choice, for the opposite reason: the trend and the comparison read a session's row, and these numbers are meant to be in the JSON export and the bug bundle, which carry the whole row; the Privacy Policy's §3A says so. What may never be a column or a key of that JSON: a controller's serial number, its Bluetooth address, its device path (LedgerDatabaseTests.ScriptTwentyFourOnlyAddsColumnsAndNamesNoIdentifier,InputSessionBuilderTests.TheStoredJsonHasNoKeyThatCouldCarryASerialNumberAnAddressOrAPath). Three ongames:controller_support(full,partial, ornonefor a game the store knows and lists no support for),controller_support_source(steam-appinfo) andcontroller_support_at— the store's own word, from its file on the disk, never a verdict of FrameLedger's (D163). Written bySessionFinalizer.Buildfrom the session's samples, before the tier branch — both tiers, and a session recovered from its crash file, which carries the readings in chunk 11. NULL before; with the option off; before the terms that describe the reading were accepted (D156); on a game no store file describes. The series aresensor_blobsrows namedinput.*(§Blob encoding).LatestVersionis 24;LedgerDatabaseTests.ScriptTwentyFourAddsTheInputColumnsAndAnEarlierSessionAndGameHaveNone, the repository round trip. Nothing produces a reading yet, and nothing writes the threegamescolumns yet: the reader, the switch and the store file are the pull requests after this one. A beta.49 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 evaluatedkFeatureDLSS_NR(Domain.Metrics.NeuralRendering). Written by the recorder's aggregation (SessionAggregator.ApplyRt) only when the writer publishedFL_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_blobskeep no feature byte); a session recovered from its crash file is re-aggregated from its raw records and keeps it.LatestVersionis 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.OpenReadOnlyAsyncexists since that day: an existing file,PRAGMA query_only, noMigrationRunner, and a refusal (LedgerSchemaException) for a schema older than the build as well as newer — the older file needs the App or--serveto bring it forward, not a verb whose name says it reads. The Agent'ssessions,consent listandkillswitch statusopen that way (Program.PrintsOnlyis the list, pinned byAgentReadOnlyVerbsTests),db pathopens nothing, and the App's--diagdoes the same.What that run found, recorded because the mechanism is not known. The on-disk
ledger.dbwas 94 KB, 23 pages, dated 14 September, at schema 2 with three test games and no sessions; the day's 41 imported games and 18 sessions were inledger.db-wal— 4 MB, 1006 frames — and every one of those frames carried salt-1 one lower than the WAL header's, with a checkpoint sequence of 1 and a single frame under the new salt. That is the shape SQLite leaves after a checkpoint has moved every frame into the main file and the next writer restarts the log; but no checkpoint had reached this main file (645 pages of data, 23 on disk, and the file's own time stamp two days old). A fresh connection therefore recovered one frame and saw the 14 September state, while the App and Agent that were running saw the whole day through the wal-index they shared. Neither process closed cleanly enough to fix it: the Agent's stop at 17:57 and the console's exit at 17:58 both left the WAL in place, and-wal/-shmthen vanished between 18:00 and 18:04 with no FrameLedger process alive. The data was rebuilt by applying the old-salt chain to the main file (176 commits,integrity_checkok) and the broken set kept beside it. Nothing in this repository writes the main file behind SQLite's back, replaces it, or restarts the WAL by hand; what the code can do about an unknown mechanism is make the next occurrence visible, and it does:OpenAsyncrunswal_checkpoint(PASSIVE)after migrating and logs the frame count it found and moved (LedgerDatabase.OpenDiagnostics), andDisposeAsyncrunswal_checkpoint(TRUNCATE)and logs that, so a clean close leaves the main file complete and a WAL that will not checkpoint is a logged number rather than a silent one. A WAL at open holding frames a passive checkpoint cannot move, with no other FrameLedger process running, is the signature to look for.
Built 2026-09-09 (P2 PR-B):
Infrastructure.Persistence.MigrationRunnerover scripts embedded in the assembly (so the schema a build applies is the one it was tested against), one transaction per script, underLocal\FrameLedger.Ledger.Migrate— session-local rather thanGlobal\, because the Agent and the UI share a session and the global namespace asks for a privilege a standard user need not hold. (One name per ledger FILE since 2026-09-17 —Migrate.<hash of the path>,MigrationRunner.LockNameFor: with one name for every ledger, a test process frozen mid-migration held every other process's scratch ledger, and seven App and Agent tests failed after 30 s on #199's run.) A ledger at a version newer than the build's scripts is refused, not read (LedgerSchemaException): guessing at a schema we do not understand is the one option that could turn a newer file into wrong answers.LedgerDatabaseopens with the four pragmas above, one connection per process behind a gate, and every write in an explicit transaction — a failing blob 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 (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. 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 ( DXGI's four-part user-mode driver version (18_GPU_VENDOR_APIS)HardwareSnapshotSource; corrected 2026-10-04) rather than WMI, which makes it accurate enough to be worth charting.