Files
frameledger/.github/workflows/release.yml
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

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