# Performance capture playbook

This is the reproducible Slice A capture procedure for the Modern Runtime
Architecture plan. The machine and graphical contract is
[`2026-07-24-performance-reference-configuration.json`](2026-07-24-performance-reference-configuration.json).

## Connected captures

Build once from a clean tracked worktree:

```powershell
dotnet build AcDream.slnx -c Release
```

Run the capped nine-stop route:

```powershell
.\tools\run-connected-r6-soak.ps1 `
  -Repository (Get-Location).Path `
  -SkipBuild `
  -CaptureContention
```

Run the uncapped nine-stop route:

```powershell
.\tools\run-connected-r6-soak.ps1 `
  -Repository (Get-Location).Path `
  -SkipBuild `
  -Uncapped
```

Run the pinned uncapped Arwic scene:

```powershell
.\tools\run-connected-r6-soak.ps1 `
  -Repository (Get-Location).Path `
  -SkipBuild `
  -Uncapped `
  -DenseTown
```

Credentials come from `ACDREAM_TEST_USER` and `ACDREAM_TEST_PASS`, or the
script's local test defaults. The generated environment disclosure redacts
secret-like variable names. Never commit credentials, raw stdout/stderr,
counter CSVs, `.nettrace`, or machine-local absolute paths.

Every run captures:

- Per-frame CPU, GL GPU, frame-thread allocation, and stage history.
- Route-wide and five-second checkpoint percentiles.
- Per-portal windows from 10 seconds before through 5 seconds after
  materialization, including the 20 worst frames.
- Process-wide `System.Runtime` counters at one-second cadence.
- Canonical resource/checkpoint JSON and named screenshots.
- Optional CLR contention events with call stacks.

`-SkipRuntimeCounters` exists for measurement-overhead experiments only. A
baseline captured with it is incomplete.

## Allocation and contention attribution

The per-frame history answers which frame and which update/upload phase was
expensive. Canonical checkpoint deltas and `runtime-counters.csv` answer
whether allocations were merely moved to workers.

For per-thread allocation stacks, make a separate reproduction capture so the
observer cost is not mixed into the baseline:

```powershell
dotnet-trace collect `
  --process-id <pid> `
  --providers Microsoft-Windows-DotNETRuntime:0x0000000000000001:5 `
  --duration 00:00:00:30 `
  --output allocation-stacks.nettrace
```

The provider enables CLR GC events at verbose level; inspect allocation-tick
stacks grouped by managed thread in PerfView or Visual Studio. Interpret
sampled bytes as attribution weights, not exact object sizes.

The soak's `-CaptureContention` mode captures the CLR contention keyword
(`0x4000`) at verbose level. Inspect `ContentionStart` call stacks and group by
lock acquisition site. The first comparisons are the DAT typed-object lock,
`ObjectMeshManager` pending-request ownership, and any newly dominant caller;
do not optimize a lock solely from event count.

## Screenshot contract

Compare a candidate against the matching reference image:

```powershell
dotnet .\src\AcDream.Cli\bin\Release\net10.0\AcDream.Cli.dll `
  compare-screenshots `
  <reference.png> `
  <candidate.png> `
  <comparison.json> `
  2 `
  0.001 `
  <optional-mask.png>
```

The routes pin world time and camera input. A nonzero-alpha mask excludes
known dynamic pixels such as DAT particles. Never widen the global tolerance
to conceal a deterministic geometry, texture, visibility, or UI difference.

## Baseline authority

Name every committed compact result `capped-local`, `uncapped-local`,
`capped-rdp`, or `uncapped-rdp`. RDP captures are diagnostic only for
throughput. An authoritative local baseline must be run on the physical AMD
display path defined in the reference configuration. A baseline report records
the exact commit and must have a clean tracked source status.