Files
frameledger/docs/06_DATA_MODEL.md
T
poli0981andClaude Fable 5.2 a6bebc4adf feat(input): the Agent records what a session was played with - the switch, the terms, Privacy Policy 2.22 and Disclaimer 2.18 (D155, D156, D160, D161) (#468)
* 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>
2026-11-14 21:53:04 +00:00

89 KiB
Raw Blame History

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 hook_* column and two downgrades (corrected 2026-10-04): Change executable (2026-09-21, GameLibrary.ChangeExecutableAsync) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and Remove game ▸ Delete sessions too (FR-1.4) deletes the games row, cascading to its sessions, segments, blobs and annotations), session_annotations (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on sessions), settings, legal_acceptance. Both read everything. The ports say the same in their names: IGameRepository.UpdateMetadataAsync / SetTriStateDefaultAsync / RemoveAsync, ISessionAnnotationRepository, RegisteredSettings, ILegalAcceptanceStore.RecordAsync (all P3 PR-3).

Schema (v2 — hook architecture)

src/FrameLedger.Infrastructure/Persistence/Migrations/0001_init.sql is 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 .partial file, 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 (the ExecutableFingerprint), hook_consent_provenance (the ConsentProvenance NAME, default NotRecorded), hook_consent_disclosure_version, hook_prescan_state (not_run|clean|blocked|unverified — the third state one nullable hook_blocked_reason could 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_blobs gains the t_ms series.
  • fg_source's domain is api|cadence|none|manual, NULL = not measured — this document said api|cadence|manual while 03_METRICS names rung 4 none; the CHECK carries the union.
  • Every *_at / *_ms INTEGER 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 except qpc_epoch / qpc_frequency.
  • exe_path is UNIQUE COLLATE NOCASE, because consent matches OrdinalIgnoreCase on 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 the capability_flags precedent 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 a user field — is in 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 (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 unshipped FrameLedger.CaptureHost.

  • A disclosure provenance. hook_consent_at is 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 reviewed 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 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_reason is two-state by definition here — non-null disables the toggle — while 05_DETECTION makes 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 clean removed it, and when the games table 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_provenance and hook_consent_disclosure_version; the third pre-scan state is hook_prescan_state. ConsentProvenance has 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 refuses NotRecorded.

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 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). 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

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 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)
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 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

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 the frame_flags gap bit set, so the statistics exclude it and the export still reconstructs qpc_ms. swapchain_ids is present only when the session held more than one stream. Schema 0013 (beta.8) adds frame_blobs.first_present_ms: the charts draw the dominant stream from its first present and the sensors from qpc_epoch, and nothing said how far apart the two zeros were. Gaps stay closed up on the frame axis (a gap's interval is stored as 0), so a series still drifts ahead of its sensors past each gap. Sensor series are aligned to t_ms (milliseconds from qpc_epoch) and a tick with no reading is stored as −1 — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.

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). An adv.* point that came from a game can therefore stand up to a second after its read; a tick with nothing waiting is NaN.

t_ms is the time axis; hz is 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 beside t_ms, which carries each sample's own time, and the App draws against it; hz is read only for a row that has no t_ms (SessionSeriesLoader). Until 0.1.0-beta.48 hz was 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 no cpu_temp series (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) and hz is 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 .partial file 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: 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 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. FindSensorsAsync leaves 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. FindInputSensorsAsync returns them with t_ms first. A session stores input.class and, for each of its first eight controllers (InputSessionBuilder.MaxDevices), input.dev.N.active and — 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 (PartialSessionFileTests kills 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 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 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)
11 SensorsInput the input readings of the samples of the type-8 chunk before it (D155–D163, InputSampleCodec): u32 samples, then per sample i64 QPC, seven i32 (span, observed, in front, controller, keyboard and mouse, both, no input), u8 flags, the reader's health (u8 answers, six i64 counts, i32 faults), u8 controllers 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 one each 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 _ => 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 become interrupted rows 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: a sessions_in_progress table — a blob churn every minute, a lock fight with the UI in P3, and 04_CAPTURE had already named a file under tmp\.

The header's game_id is where the session started, not necessarily where it lands (2026-09-23). A live finalize and a recovery both ask ISessionRepository.ResolveOwnerAsync: that id when the row predates the session or holds the header's exe path; else the row that holds the exe path now (an entry removed and re-imported while the game ran); else nothing — FinalizeStatus.GameRemoved / RecoveryStatus.GameRemoved, file deleted, nothing written. games.id is INTEGER PRIMARY KEY without AUTOINCREMENT, so a deleted id can be handed to the next row added; added_at after the session's start and another path is how that row is told apart. A file recovery cannot finalize for any other reason is renamed <guid>.partial.failed (IPartialSessionStore.Quarantine) — not listed again, not retried, kept for a bug report — and recovery goes on to the next file: it runs before the watcher on every start, and one file used to be able to stop them all.

Retention

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 runs ISessionRepository.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 through Infrastructure.Persistence.LedgerMaintenance and change no row: PRAGMA integrity_check; a backup through VACUUM 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 fresh GetStatus reports a session. LedgerDatabase.MaintainAsync is 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 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.

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 columns on session_annotations and games.removed_at. LedgerDatabaseTests asserts one schema_migrations row per script, so LatestVersion is 2.

0003_fg_refusal.sql (2026-09-14) — sessions.fg_refusal. The owner's ledger held two hooked rows with fg_mode = 'dlssg', fg_source = 'api' and fg_factor NULL — the identity stood, the count refused — and nothing recorded which refusal; every FG surface said N/A beside a detection that had succeeded. One ALTER TABLE ADD COLUMN, written by the Agent (SessionAggregator.ApplyFg), read by the UI for the "factor not counted" tooltip (08_UI §FPS display rule). LatestVersion is 3; LedgerDatabaseTests asserts 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 from exe_size_bytes / exe_mtime_ms, which are the consent fingerprint the gate reads and which a background scan must never refresh. LatestVersion is 4; LedgerDatabaseTests asserts 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", while FgWindow had computed which of the eight buckets departed, its ratio and the window's, and SessionAggregator kept only the kind. The column is Application.Recording.FgRefusalDetail as 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 beside fg_refusal, read by the UI's tooltip (FpsPresentation.RefusalDetailText), never an input to a number. Existing rows keep NULL. LatestVersion is 5; LedgerDatabaseTests asserts the column.

0006_fg_steady_state.sql (2026-09-17) — sessions.fg_factor_scope / fg_steady_share. fg_factor was 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_fps describe the state the session spent most of its generating time in, fg_steady_share of the presenting time, with fg_refusal and 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. LatestVersion is 6.

0007_guard_bypass.sql (2026-09-21) and 0008_withdraw_guard_bypass.sql (2026-09-22) — the first DROP. 0007 added five columns for the per-game guard override; the owner withdrew the feature a day later and 0008 drops them (ALTER TABLE … DROP COLUMN, SQLite ≥ 3.35 — LedgerDatabaseTests asserts the engine's version beside the columns' absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The data dropped is the override acknowledgements themselves, which is the decision. LatestVersion is 8.

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 0004's columns are the detection sweep's, and apart from exe_size_bytes / exe_mtime_ms for the same reason (the consent fingerprint must never be refreshed by a background scan). ALTER TABLE ADD COLUMN only; existing rows read NULL, which the sweep reads as "never scanned" and scans on its first pass. LatestVersion is 10; LedgerDatabaseTests.ScriptTenAddsThePreScanKeyEmptyForExistingRows applies it from 9 to a ledger holding a row.

0011_executable_facts.sql (2026-09-25) — games.exe_machine / exe_file_version / exe_product_version / library_versions. The owner asked for the game's version, its DLSS / FSR versions and 32- or 64-bit; the detection sweep read the PE version resource and walked the tree for the capability files, and kept neither. Four columns, written whole by that sweep (05_DETECTION §What the files say about themselves) — facts about files, so no provenance and no user override. Existing rows read NULL, and a NULL exe_machine makes the sweep read the row once more on its first pass. LatestVersion is 11; LedgerDatabaseTests.ScriptElevenAddsTheExecutableFactsEmptyForExistingRows.

0012_driver_profile.sql (2026-09-25) — sessions.driver_profile. The NVIDIA driver profile the session's executable ran under, read by the Agent's recorder beside every session (both tiers) through the NVAPI bridge's read-only DRS entry point (18_GPU_VENDOR_APIS §L3, ABI 2): JSON (Application.Recording.DriverProfileRecord) — Outcome (Application | Global | Degraded), Profile, and one entry per setting of Application.Capture.NvidiaDriverSettings with its Value (null = set in no profile), Location and Predefined. A driver configuration, never a measurement (03_METRICS §Upscaling). NULL for every row before, and where no NVIDIA bridge was there to ask. The same day ngx_driver_words gained Ratio, Mode, Preset, FgCount, FgPreset, FgMode beside its masks (additive JSON fields; older rows lack them). LatestVersion is 12; LedgerDatabaseTests.ScriptTwelveAddsTheDriverProfileColumn.

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 ran under the exception with. ADD COLUMN only; no row changes, so a blocked row stays blocked, not eligible, with no grant, until the Agent and the user say otherwise (19_SAFETY §The user-mode exception). Written through IGameConsentStore only — RecordExceptionEligibilityAsync (the sweep), GrantAntiCheatExceptionAsync (the SetAntiCheatException command; the store applies UserModeExceptionRules.IsEligible itself), RevokeAntiCheatExceptionAsync (every end) — plus one downgrade in ChangeExecutableAsync, which ends a grant (ExecutableChanged) and forgets the eligibility. The grant and the eligibility are each bound in SQL to the block they were reached about. LatestVersion is 14; LedgerDatabaseTests.ScriptFourteenAddsTheExceptionColumnsAndChangesNoRow.

0015_engine_version_source.sql (beta.10, 2026-09-27) — where an engine version came from. games.engine_version_source (05_DETECTION §Engine version): the witness an Unreal version rests on, or the rule's extractor type for every other engine; written by ApplyDetectionAsync only where the run's version was taken (a user field keeps none), cleared by a user's edit of the version (UpdateMetadataAsync). The script's one data change removes the bare 4 / 5 the old Unreal rule wrote (a two-group regex returning its first group) — only where field_provenance says detected: a value the user typed, one with no badge (which reads as the user's) and one whose provenance does not parse stay as they were, and the last does not fail the migration (CASE WHEN json_valid(…), since SQLite promises no order for AND). LatestVersion is 15; LedgerDatabaseTests.ScriptFifteenAddsTheWitnessAndRemovesOnlyTheOldRulesDetectedDigit.

0016_display_mode.sql (beta.10, 2026-09-27) — how the game was shown. Fifteen sessions.display_* columns (03_METRICS §Display mode): milliseconds in each mode, the changes, the witness, and the window / back buffer / monitor sizes in the mode that lasted longest. ADD COLUMN only, no data change: a session recorded before reads N/A. Written by the recorder on the row's skeleton (Recording.SessionDisplayColumns.WithDisplay), so a Tier-2 session — which never reaches the aggregator — has them too; sessions.swap_effect, a column since 0001, gets its first writer from the same facts. SessionRowColumns is hand-edited (its generator is not in the repository) and reads by name. LatestVersion is 16; LedgerDatabaseTests.ScriptSixteenAddsTheDisplayColumnsAndAnEarlierSessionHasNone, SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn.

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.

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 on sessions: input_observed_ms, input_foreground_ms and 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, and input_devices — the session's controllers as Application.Recording.InputDevicesRecord's JSON (03_METRICS §Input). On sessions and 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 on games: controller_support (full, partial, or none for a game the store knows and lists no support for), controller_support_source (steam-appinfo) and controller_support_at — the store's own word, from its file on the disk, never a verdict of FrameLedger's (D163). Written by SessionFinalizer.Build from 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 are sensor_blobs rows named input.* (§Blob encoding). LatestVersion is 24; LedgerDatabaseTests.ScriptTwentyFourAddsTheInputColumnsAndAnEarlierSessionAndGameHaveNone, the repository round trip. Nothing produces a reading yet, and nothing writes the three games columns 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 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 MigrationRunner, and a refusal (LedgerSchemaException) for a schema older than the build as well as newer — the older file needs the App or --serve to bring it forward, not a verb whose name says it reads. The Agent's sessions, consent list and killswitch status open that way (Program.PrintsOnly is the list, pinned by AgentReadOnlyVerbsTests), db path opens nothing, and the App's --diag does the same.

What that run found, recorded because the mechanism is not known. The on-disk ledger.db was 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 in ledger.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/-shm then 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_check ok) 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: OpenAsync runs wal_checkpoint(PASSIVE) after migrating and logs the frame count it found and moved (LedgerDatabase.OpenDiagnostics), and DisposeAsync runs wal_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.MigrationRunner over scripts embedded in the assembly (so the schema a build applies is the one it was tested against), one transaction per script, under Local\FrameLedger.Ledger.Migrate — session-local rather than Global\, 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. LedgerDatabase opens 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 (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.