Files
frameledger/tests/FrameLedger.Infrastructure.Tests/Recording/PartialSessionFileTests.cs
T
poli0981andClaude Opus 5.5 2ce8251d31 feat: the game's own memory, measured from outside the game in every session - a C++ reader of the GPU Process Memory counters and GetProcessMemoryInfo, median and mean, schema 0018 (D43, beta.12 PR-2) (#254)
- FrameLedger.ProcessStats.dll (C++20, loaded by the Agent, never into a game): the game process's dedicated and shared
  GPU memory from the documented `GPU Process Memory` performance counters (no handle to the game, every instance of the
  pid summed) and its private working set / working set / commit from GetProcessMemoryInfo (EX2, falling back to EX)
  through PROCESS_QUERY_LIMITED_INFORMATION only (a sentinel refuses an EX2 answer whose private working set was not
  filled). Not D3DKMTQueryStatistics ("Reserved for system use").
  ctest fl_process_stats (GPU_INSTANCE on a hardware adapter, NO_GPU_INSTANCE on CI) and fl-probe-processstats.
- Measured first, decision table in spike-notes §16 written before the runs: +512.0 MiB for a 512 MiB buffer,
  private working set equal to Windows' own counter, 0.1 ms per read, nothing leaked over 600 reads; dedicated reads a
  constant 4.5 MiB above DXGI's local usage, so it is never compared with a budget.
- NativeProcessStats (third facade), GameMemoryReader: a pinned session reads through its held handle; an unpinned
  Tier-2 hold opens each process of the executable for the read, refuses a reused pid, sums. CaptureSession tells the
  observer which process (ICaptureObserver.Measuring), the recorder forwards it to the poller (ITelemetryPoller.Follow).
- TelemetrySample.Game; five sensor series; schema 0018 (game_vram_dedicated_*, game_ram_private_*, ..., sensor_stats_json);
  SeriesAggregates gains Median and Min; a wide .partial sensors chunk (type 8) with type 4 still read; SessionProgress
  and SessionHeld carry the game's memory live.
- notice-check accepts a contributor's own copyright line in the same form.
- Tests: the two classes that open a LibreHardwareMonitor Computer run one at a time - GenericCpu.Update threw a
  NullReferenceException in the local gate when they ran in parallel (the Agent's own read is already contained).
- Docs corrected in place: 03_METRICS, 18_GPU_VENDOR_APIS, 17_HOOK_ENGINE, 20_OPEN_QUESTIONS (§M7, §H10, new §M11),
  04_CAPTURE, 19_SAFETY, 06_DATA_MODEL, 07_IPC, 02_SPEC, 01_ARCHITECTURE, 12_BUILD, CLAUDE.md; the accuracy block and
  LIMITATIONS.md.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 23:21:45 +07:00

290 lines
13 KiB
C#

// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using FluentAssertions;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Telemetry;
using FrameLedger.Domain.Sessions;
using FrameLedger.Infrastructure.Recording;
using FrameLedger.Shared;
namespace FrameLedger.Infrastructure.Tests.Recording;
/// <summary>
/// <c>14_TESTING</c>: the <c>.partial</c> recovery artifact. Every chunk type round-trips, and a file cut at
/// EVERY byte offset yields exactly the chunks that were complete before the cut — the property the
/// format exists for (<c>06_DATA_MODEL</c> §The <c>.partial</c> file).
/// </summary>
public sealed class PartialSessionFileTests : IDisposable
{
private readonly string _dir = Path.Combine(Path.GetTempPath(), "fl-partial-" + Guid.NewGuid().ToString("N"));
public PartialSessionFileTests() => Directory.CreateDirectory(_dir);
public void Dispose()
{
try
{
Directory.Delete(_dir, recursive: true);
}
catch (IOException)
{
}
}
private static readonly DateTimeOffset _t0 = new(2026, 9, 9, 12, 0, 0, TimeSpan.Zero);
private static PartialHeader Header(Guid guid) => new()
{
SessionGuid = guid,
StartedAt = _t0,
QpcEpoch = 1_000_000,
QpcFrequency = 10_000_000,
GameId = 7,
SnapshotId = 3,
ExePath = @"C:\Games\Title\game.exe",
Pid = 4242,
Tier = CaptureTier.Hooked,
Mode = CaptureMode.Launch,
OverlayBuildId = "abc123-dirty",
TelemetryDescriptor = "l1+lhm",
LaunchWaitMs = 812,
};
private static FlFrameRecord Record(uint i) => new() { FrameIndex = i, Qpc = 1_000_000 + i * 100_000UL, SwapchainId = 1, MeasuredMask = 0x240 };
private static TelemetrySample Sample(long qpc, double? temp, double? vram) => new(qpc, new GpuSample
{
TakenAt = _t0.AddSeconds(qpc / 10_000_000.0),
Layer = TelemetryLayer.Lhm,
TempCoreC = temp,
VramAdapterMb = vram,
PcieGen = 4,
});
/// <summary>Header, records in two chunks, gaps, sensors, a tick, touches, notes.</summary>
private string WriteFixture(Guid guid, out FlWriterState state)
{
string path = Path.Combine(_dir, "fixture.partial");
state = new FlWriterState { Status = 1, HooksInstalledMask = 0x3, RuntimeCensus = 0x8001, FaultCount = 0 };
using IPartialSessionWriter w = PartialSessionFile.Create(path, Header(guid));
w.AppendNote(_t0, "started Launch");
w.AppendRecords(0, [Record(0), Record(1), Record(2)]);
w.AppendGaps([2]);
w.AppendSensors([Sample(1_100_000, 61.5, 3000) with { System = new SystemReading(CpuLoadPct: 42.5, RamUsedMb: 12000, CpuTempC: null) }, Sample(1_200_000, null, 3001)]);
w.AppendTouches([1_050_000, 1_150_000]);
w.AppendTick(new PartialTick(3, 2, 0, 1, 1, _t0.AddSeconds(1).ToUnixTimeMilliseconds(), state));
w.AppendRecords(3, [Record(3), Record(4)]);
w.AppendTick(new PartialTick(5, 4, 7, 1, 2, _t0.AddSeconds(2).ToUnixTimeMilliseconds(), state));
w.AppendNote(_t0.AddSeconds(2), "ended TargetExited");
return path;
}
[Fact]
public void EveryChunkTypeRoundTrips()
{
var guid = Guid.NewGuid();
string path = WriteFixture(guid, out FlWriterState state);
PartialSession? p = PartialSessionFile.Read(path);
p.Should().NotBeNull();
p!.Truncated.Should().BeFalse();
p.Header.Should().Be(Header(guid));
p.Records.Select(r => r.FrameIndex).Should().Equal(0u, 1u, 2u, 3u, 4u);
p.Records[4].Qpc.Should().Be(Record(4).Qpc);
p.GapBefore.Should().Equal(2);
p.Sensors.Should().HaveCount(2);
p.Sensors[0].QpcTicks.Should().Be(1_100_000);
p.Sensors[0].Sample.TempCoreC.Should().Be(61.5);
p.Sensors[0].Sample.PcieGen.Should().Be(4);
p.Sensors[1].Sample.TempCoreC.Should().BeNull("null stays null across the file: N/A is never 0");
p.Sensors[0].System.Should().Be(new SystemReading(42.5, 12000, null), "the machine's reading rides the same chunk, a missing CPU temperature stays missing");
p.Sensors[1].System.IsEmpty.Should().BeTrue("a sample with no system reading reads back with none - which is every .partial written before 2026-09-21");
p.Sensors[1].Sample.VramAdapterMb.Should().Be(3001);
p.Sensors[1].Sample.LoadPct.Should().BeNull();
p.TouchQpc.Should().Equal(1_050_000, 1_150_000);
p.LastTick.Should().NotBeNull();
p.LastTick!.Value.DrainTicks.Should().Be(5, "the last tick wins");
p.LastTick.Value.TotalDropped.Should().Be(7);
p.LastTick.Value.WriterState.RuntimeCensus.Should().Be(state.RuntimeCensus);
p.Notes.Select(n => n.Text).Should().Equal("started Launch", "ended TargetExited");
p.Notes[1].At.Should().Be(_t0.AddSeconds(2));
}
/// <summary>
/// beta.12 (D43): the game process's memory rides the sensors chunk in its wide form, nulls kept null; and a beta.11
/// <c>.partial</c> — whose sensors are the narrow chunk type 4 — still recovers, with no game memory, which it never had.
/// </summary>
[Fact]
public void TheGameMemoryRoundTripsAndANarrowSensorsChunkFromBeta11StillReads()
{
string path = Path.Combine(_dir, "wide.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header(Guid.NewGuid())))
{
var game = new ProcessReading(VramDedicatedMb: 9216, VramSharedMb: 512, RamPrivateMb: null, RamWorkingSetMb: 7000, CommitMb: 8000,
Processes: 2, Sources: ProcessReadingSources.Counters | ProcessReadingSources.WorkingSetReadOnly | ProcessReadingSources.TransientHandle);
w.AppendSensors([Sample(1_100_000, 60, 3000) with { Game = game }, Sample(1_200_000, 61, 3001)]);
}
// A narrow (type 4) chunk as beta.11 wrote it: qpc, wall clock, layer, a 16-bit mask (core temperature, system RAM).
var narrow = new byte[8 + 8 + 1 + 2 + 16];
BinaryPrimitives.WriteInt64LittleEndian(narrow, 1_300_000);
BinaryPrimitives.WriteInt64LittleEndian(narrow.AsSpan(8), _t0.ToUnixTimeMilliseconds());
narrow[16] = (byte)TelemetryLayer.Lhm;
BinaryPrimitives.WriteUInt16LittleEndian(narrow.AsSpan(17), (ushort)((1 << 0) | (1 << 13)));
BinaryPrimitives.WriteDoubleLittleEndian(narrow.AsSpan(19), 55.0);
BinaryPrimitives.WriteDoubleLittleEndian(narrow.AsSpan(27), 8000.0);
AppendRawChunk(path, 4, narrow);
PartialSession p = PartialSessionFile.Read(path)!;
p.Sensors.Should().HaveCount(3);
p.Sensors[0].Game.VramDedicatedMb.Should().Be(9216);
p.Sensors[0].Game.VramSharedMb.Should().Be(512);
p.Sensors[0].Game.RamPrivateMb.Should().BeNull("no private working set on that OS: N/A stays N/A");
p.Sensors[0].Game.RamWorkingSetMb.Should().Be(7000);
p.Sensors[0].Game.CommitMb.Should().Be(8000);
p.Sensors[0].Game.Processes.Should().Be(2);
p.Sensors[0].Game.Sources.Should().Be(ProcessReadingSources.Counters | ProcessReadingSources.WorkingSetReadOnly | ProcessReadingSources.TransientHandle);
p.Sensors[1].Game.IsEmpty.Should().BeTrue("a tick that read nothing of the game reads back with nothing");
p.Sensors[2].QpcTicks.Should().Be(1_300_000);
p.Sensors[2].Sample.TempCoreC.Should().Be(55);
p.Sensors[2].System.RamUsedMb.Should().Be(8000);
p.Sensors[2].Game.IsEmpty.Should().BeTrue("a beta.11 chunk carries no game memory");
}
/// <summary>One chunk framed as the file frames it: type, length, payload, CRC-32 (IEEE) over the frame and payload.</summary>
private static void AppendRawChunk(string path, uint type, byte[] payload)
{
var frame = new byte[8];
BinaryPrimitives.WriteUInt32LittleEndian(frame, type);
BinaryPrimitives.WriteUInt32LittleEndian(frame.AsSpan(4), (uint)payload.Length);
uint crc = 0xFFFFFFFFu;
foreach (byte b in frame.Concat(payload))
{
crc ^= b;
for (int k = 0; k < 8; k++)
{
crc = (crc & 1) != 0 ? 0xEDB88320u ^ (crc >> 1) : crc >> 1;
}
}
var trailer = new byte[4];
BinaryPrimitives.WriteUInt32LittleEndian(trailer, crc ^ 0xFFFFFFFFu);
using var stream = new FileStream(path, FileMode.Append, FileAccess.Write);
stream.Write(frame);
stream.Write(payload);
stream.Write(trailer);
}
[Fact]
public void AKillAtEveryByteOffsetYieldsExactlyTheChunksThatWereComplete()
{
var guid = Guid.NewGuid();
string path = WriteFixture(guid, out _);
byte[] whole = File.ReadAllBytes(path);
PartialSession full = PartialSessionFile.Parse(whole)!;
// Chunk boundaries, from the format itself: type|len|payload|crc.
var boundaries = new List<int>();
int at = 0;
while (at < whole.Length)
{
int len = BitConverter.ToInt32(whole, at + 4);
at += 12 + len;
boundaries.Add(at);
}
boundaries[^1].Should().Be(whole.Length);
int headerEnd = boundaries[0];
for (int cut = 0; cut <= whole.Length; cut++)
{
PartialSession? p = PartialSessionFile.Parse(whole.AsSpan(0, cut));
int complete = boundaries.Count(b => b <= cut);
if (cut < headerEnd)
{
p.Should().BeNull($"cut at {cut} is inside the header: nothing to recover");
continue;
}
p.Should().NotBeNull($"cut at {cut}");
p!.Truncated.Should().Be(cut != whole.Length && boundaries.Contains(cut) == false || (cut != whole.Length && cut < whole.Length && !boundaries.Contains(cut)),
$"cut at {cut}: mid-chunk is truncated, on a boundary is not");
// Everything before the cut that was complete is present; nothing after it is.
int recordsExpected = complete >= 3 ? 3 : 0;
recordsExpected = complete >= 8 ? 5 : recordsExpected;
p.Records.Should().HaveCount(recordsExpected, $"cut at {cut}, {complete} complete chunk(s)");
p.Notes.Should().HaveCount(complete >= 10 ? 2 : complete >= 2 ? 1 : 0, $"cut at {cut}");
(p.LastTick?.DrainTicks).Should().Be(complete >= 9 ? 5 : complete >= 7 ? 3 : null, $"cut at {cut}");
}
full.Truncated.Should().BeFalse();
}
[Fact]
public void ACorruptedByteInsideAChunkDropsThatChunkAndEverythingAfterItAndKeepsWhatCameBefore()
{
var guid = Guid.NewGuid();
string path = WriteFixture(guid, out _);
byte[] whole = File.ReadAllBytes(path);
int len0 = BitConverter.ToInt32(whole, 4);
int chunk1 = 12 + len0; // the first note
int len1 = BitConverter.ToInt32(whole, chunk1 + 4);
int chunk2 = chunk1 + 12 + len1; // the first records chunk
whole[chunk2 + 8 + 5] ^= 0xFF; // one bit-flip inside its payload
PartialSession? p = PartialSessionFile.Parse(whole);
p.Should().NotBeNull();
p!.Truncated.Should().BeTrue();
p.Notes.Should().ContainSingle();
p.Records.Should().BeEmpty("the check on the records chunk failed, and nothing after a failed chunk is trusted");
}
[Fact]
public void ARecordsChunkThatDoesNotContinueTheSequenceIsRefused()
{
string path = Path.Combine(_dir, "seq.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header(Guid.NewGuid())))
{
w.AppendRecords(0, [Record(0)]);
w.AppendRecords(5, [Record(5)]);
w.AppendNote(_t0, "after");
}
PartialSession p = PartialSessionFile.Read(path)!;
p.Records.Should().ContainSingle();
p.Truncated.Should().BeTrue();
p.Notes.Should().BeEmpty();
}
[Fact]
public void AFileWithNoHeaderOrAForeignFormatVersionIsNothingToRecover()
{
PartialSessionFile.Parse([]).Should().BeNull();
PartialSessionFile.Parse(new byte[7]).Should().BeNull();
string path = Path.Combine(_dir, "v99.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header(Guid.NewGuid()) with { FormatVersion = 99 }))
{
}
PartialSessionFile.Read(path).Should().BeNull("a version this reader does not know is not guessed at");
}
[Fact]
public void CreateNeverOverwrites()
{
string path = Path.Combine(_dir, "once.partial");
PartialSessionFile.Create(path, Header(Guid.NewGuid())).Dispose();
Action again = () => PartialSessionFile.Create(path, Header(Guid.NewGuid())).Dispose();
again.Should().Throw<IOException>("one guid is one session; a second file with the same name is a bug, not a retry");
}
}