- 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>
259 lines
14 KiB
YAML
259 lines
14 KiB
YAML
# FrameLedger release (docs/13_CI_CD.md §release.yml, docs/12_BUILD.md §Publish & package).
|
|
#
|
|
# On a tag `v*`: the same gate ci.yml runs, then publish → pack → checksums →
|
|
# a GitHub Release whose body is CHANGELOG.md's section for the version. Three
|
|
# things are refused loudly rather than papered over, because a release is the
|
|
# one artefact nobody can re-run:
|
|
# - the tag's numeric core must equal the VERSION file (the one version source;
|
|
# the native VERSIONINFO blocks are built from it and versioninfo-check
|
|
# compares them);
|
|
# - CHANGELOG.md must carry a non-empty `## [x.y.z]` section for the tag
|
|
# (tools/release-notes.ps1) — an empty release body is a defect, not a default;
|
|
# - the published tree must hold both entry points and every shipped native
|
|
# binary, checked by name, because `dotnet publish` warns rather than fails
|
|
# when a .targets-staged DLL is missing.
|
|
#
|
|
# Unsigned by policy (11_UPDATER §Unsigned releases): SHA256SUMS.txt is published
|
|
# beside the assets and printed into the release body.
|
|
#
|
|
# A pre-release tag (`v0.1.0-beta.1`, 13_CI_CD §Branch & release policy) marks the
|
|
# GitHub release as pre-release; the App's stable channel ignores it and the beta
|
|
# channel sees it. The managed assemblies take the tag's full version through
|
|
# -p:Version; the native blocks keep the numeric core (CMake's project() accepts
|
|
# nothing else).
|
|
#
|
|
# A DRY RUN (2026-09-16, P5 prep): `workflow_dispatch` with a version runs every
|
|
# step below — the gate, the publish, the tree assertion, vpk, the checksums — and
|
|
# uploads the result as a workflow artifact, but creates no tag and no Release.
|
|
# It is the first-tag measurement without the tag: 13_CI_CD §release.yml said the
|
|
# workflow "has not been exercised by a tag yet", and everything after the version
|
|
# gate had only ever run by hand on one machine. In a dry run a missing
|
|
# `## [x.y.z]` CHANGELOG section is a printed warning with placeholder notes rather
|
|
# than a stop, because the section is written in the tag commit and a dry run
|
|
# precedes it; on a real tag it stays a hard stop.
|
|
|
|
name: Release
|
|
|
|
on:
|
|
push:
|
|
tags: ['v*']
|
|
workflow_dispatch:
|
|
inputs:
|
|
version:
|
|
description: 'Version to rehearse (e.g. 0.1.0-beta.1): numeric core must equal VERSION; no tag, no Release'
|
|
required: true
|
|
type: string
|
|
|
|
# The Release API is contents: write; nothing else is needed and nothing else is granted.
|
|
permissions:
|
|
contents: write
|
|
|
|
concurrency:
|
|
group: release-${{ github.ref }}
|
|
cancel-in-progress: false
|
|
|
|
jobs:
|
|
release:
|
|
runs-on: windows-latest
|
|
timeout-minutes: 60
|
|
|
|
steps:
|
|
- uses: actions/checkout@v7
|
|
|
|
- name: Set up .NET
|
|
uses: actions/setup-dotnet@v6
|
|
with:
|
|
global-json-file: global.json
|
|
|
|
- name: Set up MSVC (x64)
|
|
uses: ilammy/msvc-dev-cmd@v1
|
|
with:
|
|
arch: x64
|
|
|
|
# Same pin as ci.yml, for the same reason (the gate's clang-format step).
|
|
- name: Pin clang-format
|
|
shell: pwsh
|
|
run: |
|
|
pip install --disable-pip-version-check "clang-format==22.1.3"
|
|
clang-format --version
|
|
|
|
- name: Cache NuGet
|
|
uses: actions/cache@v6
|
|
with:
|
|
path: ~/.nuget/packages
|
|
key: nuget-${{ runner.os }}-${{ hashFiles('**/Directory.Packages.props', 'global.json') }}
|
|
restore-keys: nuget-${{ runner.os }}-
|
|
|
|
- name: Version gate (tag vs VERSION, CHANGELOG section)
|
|
id: version
|
|
shell: pwsh
|
|
env:
|
|
DRY_RUN: ${{ github.event_name == 'workflow_dispatch' }}
|
|
DISPATCHED_VERSION: ${{ inputs.version }}
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$dry = $env:DRY_RUN -eq 'true'
|
|
$tag = if ($dry) { 'v' + $env:DISPATCHED_VERSION.TrimStart('v') } else { $env:GITHUB_REF_NAME }
|
|
$m = [regex]::Match($tag, '^v(\d+\.\d+\.\d+)(-[0-9A-Za-z.]+)?$')
|
|
if (-not $m.Success) { throw "tag '$tag' is not vMAJOR.MINOR.PATCH[-prerelease]" }
|
|
$full = $tag.Substring(1)
|
|
$core = $m.Groups[1].Value
|
|
$pre = if ($m.Groups[2].Success) { 'true' } else { 'false' }
|
|
$file = (Get-Content VERSION -Raw).Trim()
|
|
if ($core -ne $file) { throw "tag $tag has numeric core $core but VERSION says $file — bump VERSION in the same commit as the changelog section, then tag" }
|
|
New-Item -ItemType Directory -Force out | Out-Null
|
|
./tools/release-notes.ps1 -Version $full -OutFile out/notes.md
|
|
if ($LASTEXITCODE -ne 0) {
|
|
if (-not $dry) { throw 'release notes' }
|
|
Write-Host "::warning::CHANGELOG.md has no '## [$full]' section yet - a dry run continues with placeholder notes; a real tag stops here"
|
|
[System.IO.File]::WriteAllText('out/notes.md', "DRY RUN of $full - CHANGELOG.md has no ``## [$full]`` section yet.`n", [System.Text.UTF8Encoding]::new($false))
|
|
# The runner's pwsh wrapper ends the step with `exit $LASTEXITCODE`, so a handled failure must clear it
|
|
# (measured 2026-09-16: the first rehearsal printed the warning and then failed with the script's exit 1).
|
|
$global:LASTEXITCODE = 0
|
|
}
|
|
"version=$full" >> $env:GITHUB_OUTPUT
|
|
"prerelease=$pre" >> $env:GITHUB_OUTPUT
|
|
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
|
|
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
|
|
|
|
# 12_BUILD §Release-time token substitution: the effective date of a legal
|
|
# document is the date it ships. The only placeholder that survives into the
|
|
# repository, substituted here and nowhere else; the App embeds legal/*.md at
|
|
# build time, so this runs BEFORE the build.
|
|
- name: Substitute {{RELEASE_DATE}}
|
|
shell: pwsh
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$date = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd')
|
|
$n = 0
|
|
foreach ($f in Get-ChildItem legal -Filter *.md) {
|
|
$t = Get-Content $f.FullName -Raw
|
|
if ($t.Contains('{{RELEASE_DATE}}')) {
|
|
[System.IO.File]::WriteAllText($f.FullName, $t.Replace('{{RELEASE_DATE}}', $date), [System.Text.UTF8Encoding]::new($false))
|
|
$n++
|
|
}
|
|
}
|
|
Write-Host "RELEASE_DATE = $date in $n file(s)"
|
|
if (Select-String -Path legal/*.md, README.md -Pattern '\{\{' -Quiet) { throw 'a {{ token survived substitution' }
|
|
|
|
# The identical gate ci.yml runs — native build, tests, every check including
|
|
# versioninfo-check against VERSION. A release never skips it.
|
|
- name: Quality gate
|
|
shell: pwsh
|
|
run: ./build.ps1 check
|
|
env:
|
|
CI: 'true'
|
|
|
|
- name: Publish App + Agent (self-contained, ReadyToRun)
|
|
shell: pwsh
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$v = '${{ steps.version.outputs.version }}'
|
|
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
|
|
if ($LASTEXITCODE -ne 0) { throw 'App publish failed' }
|
|
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
|
|
if ($LASTEXITCODE -ne 0) { throw 'Agent publish failed' }
|
|
|
|
# A self-contained package redistributes the .NET runtime, and its licence and
|
|
# third-party notices are ours to pass on (P4 PR-6). Not committed with the
|
|
# NuGet texts in legal/licenses/nuget: the runtime version follows the SDK of
|
|
# the machine that publishes, so the exact packs are read from the published
|
|
# runtimeconfig and copied from the NuGet cache the publish just used.
|
|
- name: Ship the .NET runtime's licence and notices
|
|
shell: pwsh
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$config = Get-Content out/app/FrameLedger.runtimeconfig.json -Raw | ConvertFrom-Json
|
|
$frameworks = @($config.runtimeOptions.includedFrameworks)
|
|
if ($frameworks.Count -eq 0) { throw 'FrameLedger.runtimeconfig.json lists no included framework -- the publish was not self-contained' }
|
|
$cache = if ($env:NUGET_PACKAGES) { $env:NUGET_PACKAGES } else { Join-Path $HOME '.nuget/packages' }
|
|
$dest = New-Item -ItemType Directory -Force out/app/licenses/dotnet
|
|
foreach ($fw in $frameworks) {
|
|
$pack = Join-Path $cache ('{0}.runtime.win-x64/{1}' -f $fw.name.ToLowerInvariant(), $fw.version)
|
|
$files = @(Get-ChildItem $pack -File | Where-Object { $_.Name -match '^(LICENSE|THIRD-PARTY-NOTICES)(\.TXT)?$' })
|
|
if ($files.Count -eq 0) { throw "no licence file in $pack" }
|
|
foreach ($f in $files) {
|
|
Copy-Item $f.FullName (Join-Path $dest ('{0}-{1}-{2}' -f $fw.name, $fw.version, $f.Name))
|
|
}
|
|
}
|
|
Get-ChildItem $dest | ForEach-Object { Write-Host (" {0,-64} {1,8:N0}" -f $_.Name, $_.Length) }
|
|
|
|
# What ships is what matters: the two entry points and the five shipped native
|
|
# binaries (versioninfo-check's list) must be in the tree, and the unshipped
|
|
# capture host must not be (package-closure-check proves it statically; this
|
|
# reads the directory).
|
|
- name: Assert the published tree
|
|
shell: pwsh
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'FrameLedger.ProcessStats.dll', 'rules/detection-rules.json',
|
|
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/NOTICE.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
|
|
$missing = @($required | Where-Object { -not (Test-Path (Join-Path out/app $_)) })
|
|
if ($missing.Count -gt 0) { throw "out/app is missing: $($missing -join ', ')" }
|
|
if (Test-Path out/app/FrameLedger.CaptureHost.exe) { throw 'out/app contains the unshipped capture host (12_BUILD: exactly two roots)' }
|
|
if (@(Get-ChildItem out/app/licenses/dotnet -File -ErrorAction SilentlyContinue).Count -lt 2) { throw 'out/app/licenses/dotnet holds fewer than two files -- the runtime licence step did not run' }
|
|
./tools/versioninfo-check.ps1 -BuildDir out/app
|
|
if ($LASTEXITCODE -ne 0) { throw 'versioninfo-check over the published tree' }
|
|
$size = (Get-ChildItem out/app -Recurse -File | Measure-Object Length -Sum).Sum / 1MB
|
|
Write-Host ("published tree: {0:N0} MB" -f $size)
|
|
|
|
# Velopack's packer, pinned to the library version the App references
|
|
# (Directory.Packages.props). No --icon: assets/icon.ico does not exist yet
|
|
# (12_BUILD §Publish & package says so rather than pointing at a file that is not there).
|
|
#
|
|
# --packId is FrameLedger.App, NOT FrameLedger, and that is a data-loss rule:
|
|
# Velopack installs into %LOCALAPPDATA%\<packId> and deletes that directory on
|
|
# uninstall, and %LOCALAPPDATA%\FrameLedger is the DATA folder (LedgerPaths:
|
|
# ledger.db, logs, the layer manifest). The same id would put the install inside
|
|
# the ledger's folder and have the uninstaller remove every session without the
|
|
# question 12_BUILD promises. The title the user sees is still "FrameLedger".
|
|
- name: Pack (Velopack)
|
|
shell: pwsh
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
dotnet tool install -g vpk --version 1.2.0
|
|
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
|
|
$v = '${{ steps.version.outputs.version }}'
|
|
vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
|
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
|
|
Get-ChildItem out/release | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
|
|
if (-not (Test-Path out/release/FrameLedger.App-win-Setup.exe)) { throw 'vpk did not produce FrameLedger.App-win-Setup.exe (README §Install names it)' }
|
|
|
|
- name: Checksums
|
|
shell: pwsh
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$lines = Get-ChildItem out/release -File | Sort-Object Name | ForEach-Object {
|
|
'{0} {1}' -f (Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLowerInvariant(), $_.Name
|
|
}
|
|
[System.IO.File]::WriteAllLines('out/release/SHA256SUMS.txt', $lines, [System.Text.UTF8Encoding]::new($false))
|
|
$notes = Get-Content out/notes.md -Raw
|
|
$notes += "`n`n## SHA-256`n`nReleases are not code-signed (11_UPDATER). Verify before running:`n`n``````text`n" + ($lines -join "`n") + "`n``````"
|
|
[System.IO.File]::WriteAllText('out/notes.md', $notes, [System.Text.UTF8Encoding]::new($false))
|
|
Get-Content out/release/SHA256SUMS.txt
|
|
|
|
- name: Create the GitHub Release
|
|
if: steps.version.outputs.dry_run != 'true'
|
|
shell: pwsh
|
|
env:
|
|
GH_TOKEN: ${{ github.token }}
|
|
run: |
|
|
$ErrorActionPreference = 'Stop'
|
|
$v = '${{ steps.version.outputs.version }}'
|
|
$ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', "FrameLedger $v", '--notes-file', 'out/notes.md', '--verify-tag')
|
|
if ('${{ steps.version.outputs.prerelease }}' -eq 'true') { $ghArgs += '--prerelease' }
|
|
$ghArgs += Get-ChildItem out/release -File | ForEach-Object { $_.FullName }
|
|
gh @ghArgs
|
|
if ($LASTEXITCODE -ne 0) { throw 'gh release create failed' }
|
|
|
|
- name: Upload the published tree (for the smoke checklist)
|
|
if: always()
|
|
uses: actions/upload-artifact@v7
|
|
with:
|
|
name: release-${{ steps.version.outputs.version || github.ref_name }}${{ steps.version.outputs.dry_run == 'true' && '-dry-run' || '' }}
|
|
path: |
|
|
out/release/**
|
|
out/notes.md
|
|
if-no-files-found: warn
|
|
retention-days: 30
|