build: the alpha line - RELEASE_LINE stamped into every assembly, release.yml's line-vs-tag rule and Velopack alpha channel, CI on the alpha branch, no wiki for an alpha (D73) (beta.32 PR-1) (#344)

The owner, 2026-10-31: an alpha build where new .NET versions are tried, .NET 11 RC3 / C# 15 first,
with an experimental-build warning (owner decisions D73-D76, asked while planning). This is the
plumbing on main; it changes nothing in a beta.

- RELEASE_LINE (main | alpha), read like VERSION by Directory.Build.props, stamped as the
  FrameLedger.ReleaseLine assembly metadata; any other value is a build error. Shared.BuildLine
  reads it back for composition (BuildLineTests, AssemblyIdentityTests).
- release.yml: the version gate reads RELEASE_LINE - the alpha line takes vX.Y.Z-alpha.N and
  nothing else, no other line may carry an -alpha. tag; an alpha's vpk download and pack take
  --channel alpha (feed releases.alpha.json, asset names from assets.<channel>.json); the main
  line's pack command is unchanged. An alpha's release is titled "(experimental alpha)".
- ci.yml: also on pushes to alpha; no sonarcloud job and no Changelog step for pull requests into
  alpha. wiki.yml: no publish after an -alpha. tag.
- tools/fps-impact-runbook.ps1: the Agent path no longer names a TFM.
- Docs: 12_BUILD §The alpha line, 13_CI_CD §The alpha line (+ ci/release/wiki sections, branch
  policy), 11_UPDATER §Channels corrected in place (the alpha line uses Velopack channels;
  GithubSource reads the newest ten releases, hence one alpha per beta), 20_OPEN_QUESTIONS §G
  "The main line's .NET" with its decision table written first, CLAUDE.md, CHANGELOG.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 authored and GitHub committed 2026-10-31 14:58:38 +00:00
1 parent 2752fe9a2d
commit 648e9c28b1
15 files changed
+288 -24

No files matched your search

+10 -3
View File
@@ -20,7 +20,9 @@ name: CI
on:
push:
branches: [main]
# `alpha` since 2026-10-31 (D73, docs/13_CI_CD.md §The alpha line): the same source on a prerelease .NET, whose
# merges and syncs from main need the same gate under its own global.json.
branches: [main, alpha]
pull_request:
workflow_dispatch:
@@ -176,8 +178,11 @@ jobs:
Write-Host ("vulkaninfo.exe on PATH: {0}" -f ($(if ($cmd) { $cmd.Source } else { 'no' })))
Write-Host ("HKLM:\SOFTWARE\Khronos\Vulkan\Drivers present: {0}" -f (Test-Path 'HKLM:\SOFTWARE\Khronos\Vulkan\Drivers'))
# Not for a pull request into `alpha` (D73): what the alpha line changes is written in its release's own file on
# main (docs/changelog/x.y.z-alpha.N.md), and an [Unreleased] entry on the alpha branch would collide with main's
# at every sync.
- name: Changelog
if: github.event_name == 'pull_request'
if: github.event_name == 'pull_request' && github.base_ref != 'alpha'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
@@ -221,9 +226,11 @@ jobs:
# it. Any other branch is refused by the organisation's plan - "Organization
# is not allowed to access data from non main branches", measured on a
# workflow_dispatch run of a feature branch, 2026-10-25 - so a dispatch on
# one runs `check` alone.
# one runs `check` alone. The same plan is why a pull request INTO `alpha`
# (D73) and a push to it run `check` alone: SonarCloud analyses main's line.
if: >-
(github.event_name == 'pull_request' &&
github.base_ref != 'alpha' &&
github.event.pull_request.head.repo.full_name == github.repository &&
github.event.pull_request.user.login != 'dependabot[bot]') ||
(github.event_name != 'pull_request' && github.ref == 'refs/heads/main')
+41 -13
View File
@@ -22,6 +22,13 @@
# -p:Version; the native blocks keep the numeric core (CMake's project() accepts
# nothing else).
#
# THE ALPHA LINE (2026-10-31, owner decisions D73-D76; 12_BUILD §The alpha line): the
# RELEASE_LINE file says `alpha` on the long-lived `alpha` branch, where the same source
# builds on a prerelease .NET. Its tags are `vX.Y.Z-alpha.N` and nothing else, no other
# line may carry one, and its packages go to Velopack's `alpha` channel
# (releases.alpha.json) - which no beta reads, as no alpha reads releases.win.json
# (11_UPDATER §Channels). The version gate below enforces all three.
#
# 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.
@@ -101,6 +108,14 @@ jobs:
$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" }
# D73: the release line this commit builds (Directory.Build.props refuses any other value too) and the tags it may
# carry - an alpha's on the alpha line only, and nothing else there.
$line = (Get-Content RELEASE_LINE -Raw).Trim()
if ($line -cnotin @('main', 'alpha')) { throw "RELEASE_LINE says '$line'; it must be main or alpha" }
$suffix = $m.Groups[2].Value
if ($line -eq 'alpha' -and $suffix -cnotmatch '^-alpha\.\d+$') { throw "this commit is on the alpha line (RELEASE_LINE); its tag must be vX.Y.Z-alpha.N, not $tag" }
if ($line -ne 'alpha' -and $suffix -match 'alpha') { throw "tag $tag names an alpha, but RELEASE_LINE says '$line': an alpha is tagged on the alpha branch, nowhere else" }
$channel = if ($line -eq 'alpha') { 'alpha' } else { 'win' }
New-Item -ItemType Directory -Force out | Out-Null
./tools/release-notes.ps1 -Version $full -OutFile out/notes.md
if ($LASTEXITCODE -ne 0) {
@@ -113,8 +128,9 @@ jobs:
}
"version=$full" >> $env:GITHUB_OUTPUT
"prerelease=$pre" >> $env:GITHUB_OUTPUT
"channel=$channel" >> $env:GITHUB_OUTPUT
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre; line: $line; Velopack channel: $channel)"
# The Overlay's build id is `git describe --dirty` at CMake's configure
# (src/native/FrameLedger.Shm/CMakeLists.txt), and the next step edits tracked
@@ -247,32 +263,42 @@ jobs:
dotnet tool install -g vpk --version 1.2.161
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
$v = '${{ steps.version.outputs.version }}'
# D73: `win` (Velopack's default on Windows) for the main line, `alpha` for the alpha line - each release's feed
# and the previous release its delta is made from are its own line's. The main line's pack keeps its exact
# command (no --channel), so a beta is packed as every beta before the alpha line existed.
$channel = '${{ steps.version.outputs.channel }}'
New-Item -ItemType Directory out/release -Force | Out-Null
vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel win --pre --token $env:GH_TOKEN --outputDir out/release
vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel $channel --pre --token $env:GH_TOKEN --outputDir out/release
if ($LASTEXITCODE -ne 0) { Write-Host '::warning::the previous release could not be downloaded - this release carries a full package only' }
Write-Host 'previous release:'
Get-ChildItem out/release -File | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
$pack = @('pack', '--packId', 'FrameLedger.App', '--packVersion', $v, '--packDir', 'out/app', '--mainExe', 'FrameLedger.exe', '--packTitle', 'FrameLedger', '--packAuthors', 'FrameLedger', '--releaseNotes', 'out/notes.md', '--outputDir', 'out/release')
if ($channel -ne 'win') { $pack += @('--channel', $channel) }
vpk @pack
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
$built = @((Get-Content out/release/assets.win.json -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
if ($built.Count -eq 0) { throw 'vpk pack wrote no assets.win.json entries' }
$keep = $built + @('releases.win.json', 'assets.win.json', 'RELEASES')
$assets = "assets.$channel.json"
$index = "releases.$channel.json"
$legacyName = if ($channel -eq 'win') { 'RELEASES' } else { "RELEASES-$channel" }
$built = @((Get-Content "out/release/$assets" -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
if ($built.Count -eq 0) { throw "vpk pack wrote no $assets entries" }
$keep = $built + @($index, $assets, $legacyName)
New-Item -ItemType Directory out/previous -Force | Out-Null
Get-ChildItem out/release -File | Where-Object { $keep -notcontains $_.Name } | Move-Item -Destination out/previous
$feed = Get-Content out/release/releases.win.json -Raw | ConvertFrom-Json
$feed = Get-Content "out/release/$index" -Raw | ConvertFrom-Json
$feed.Assets = @($feed.Assets | Where-Object { $built -contains $_.FileName })
if ($feed.Assets.Count -eq 0) { throw 'the feed lists none of this build''s packages' }
[System.IO.File]::WriteAllText((Join-Path $PWD 'out/release/releases.win.json'), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
if (Test-Path out/release/RELEASES) {
$legacy = @(Get-Content out/release/RELEASES | Where-Object { $built -contains ($_ -split ' ')[1] })
[System.IO.File]::WriteAllLines((Join-Path $PWD 'out/release/RELEASES'), [string[]]$legacy, [System.Text.UTF8Encoding]::new($false))
[System.IO.File]::WriteAllText((Join-Path $PWD "out/release/$index"), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
if (Test-Path "out/release/$legacyName") {
$legacy = @(Get-Content "out/release/$legacyName" | Where-Object { $built -contains ($_ -split ' ')[1] })
[System.IO.File]::WriteAllLines((Join-Path $PWD "out/release/$legacyName"), [string[]]$legacy, [System.Text.UTF8Encoding]::new($false))
}
Write-Host 'this release:'
Get-ChildItem out/release | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
Write-Host ('feed: ' + (($feed.Assets | ForEach-Object { '{0} {1} {2}' -f $_.Type, $_.Version, $_.FileName }) -join '; '))
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)' }
$setup = "FrameLedger.App-$channel-Setup.exe"
if (-not (Test-Path "out/release/$setup")) { throw "vpk did not produce $setup (README §Install names the beta's, guide/11-alpha-builds.md the alpha's)" }
$delta = "out/release/FrameLedger.App-$v-delta.nupkg"
if (Get-ChildItem out/previous -Filter '*-full.nupkg' -ErrorAction SilentlyContinue) {
if (-not (Test-Path $delta)) { throw "the previous full package was downloaded, but vpk produced no delta ($delta)" }
@@ -301,7 +327,9 @@ jobs:
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')
# An alpha says what it is in the list of releases too, not only in its notes (D74).
$title = if ('${{ steps.version.outputs.channel }}' -eq 'alpha') { "FrameLedger $v (experimental alpha)" } else { "FrameLedger $v" }
$ghArgs = @('release', 'create', $env:GITHUB_REF_NAME, '--title', $title, '--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
+4 -1
View File
@@ -44,12 +44,15 @@ jobs:
# that succeeded - in THIS repository. A fork cannot start this repository's Release run (it runs on a tag push or by
# hand), so the head checked out below is always the owner's; the repository check says so in the condition rather
# than leaving it to release.yml's triggers (SonarCloud githubactions:S7631, beta.26).
# Nor does an alpha's release (D73, 2026-10-31): the wiki shows the newest beta, and an alpha's tag is on the `alpha`
# branch, whose guide is the beta's it was cut from - publishing it would only move the wiki's links off main's line.
if: >-
github.event_name == 'workflow_dispatch' ||
(github.event.workflow_run.conclusion == 'success' &&
github.event.workflow_run.event == 'push' &&
github.event.workflow_run.head_repository.full_name == github.repository &&
startsWith(github.event.workflow_run.head_branch, 'v'))
startsWith(github.event.workflow_run.head_branch, 'v') &&
!contains(github.event.workflow_run.head_branch, '-alpha.'))
runs-on: windows-latest
timeout-minutes: 10
env:
+11
View File
@@ -35,6 +35,17 @@ numeric core and does not move; the heading is the full version — corrected 20
## [Unreleased]
### Added
- **The alpha line** (the owner's request of 2026-10-31, owner decisions D73–D76): an `alpha` branch builds this source
on a prerelease .NET — .NET 11 RC3 first — and publishes it as `x.y.z-alpha.N` pre-releases on an update channel of
their own, so a beta never updates to an alpha and an alpha never to a beta. What the line needs on main changes nothing
in a beta: the `RELEASE_LINE` file and the line every assembly is stamped with (`Shared.BuildLine`), `release.yml`'s
rule that an alpha is tagged on the alpha line and nowhere else and packed on Velopack's `alpha` channel, CI on the
`alpha` branch, and no wiki publish for an alpha (`docs/12_BUILD.md` §The alpha line, `docs/13_CI_CD.md` §The alpha
line, `docs/11_UPDATER.md` §Channels). Whether the main line ever leaves .NET 10 is an open question whose decision
table is written before the evidence (`docs/20_OPEN_QUESTIONS.md` §G, *The main line's .NET*).
## Releases
Newest first. Each file holds that release's section exactly as it stood here.
+2 -1
View File
@@ -42,7 +42,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
| Concern | Choice |
|---|---|
| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md` |
| Managed runtime | .NET 10 (LTS, pinned via `global.json`), C# 14, TFM `net10.0-windows10.0.22621.0` with `SupportedOSPlatformVersion=10.0.19045.0` (Win10 22H2 floor, NFR-8), x64 only — `docs/12_BUILD.md`. **The `alpha` branch** (D73–D76, 2026-10-31) builds the same source on a prerelease .NET — .NET 11 RC3, C# 15 — and differs from main only where `docs/12_BUILD.md` §The alpha line lists; code on main must keep compiling as C# 14 on .NET 10, so no C# 15 syntax |
| Native | **C++20, MSVC v143+, `/MT` static CRT, `/GS`, `/guard:cf`, no RTTI, no C++ exceptions in hook paths** |
| Hooking | **MinHook** (BSD-2-Clause) for inline hooks; direct vtable-entry swap for COM interfaces |
| Vulkan | **Implicit Vulkan layer** (`VK_LAYER_FRAMELEDGER_overlay`), not hooking — `17_HOOK_ENGINE` §Vulkan |
@@ -68,6 +68,7 @@ FrameLedger.slnx # XML solution format (SDK default since .NET 10)
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
global.json # pins the SDK band — see 12_BUILD
RELEASE_LINE # `main`, or `alpha` on the alpha branch (D73, 2026-10-31) — 12_BUILD §The alpha line
build.ps1 # the quality gate; CI runs this identical script
SonarQube.Analysis.xml # SonarCloud's settings for ci.yml's sonarcloud job (D68, 2026-10-25; it replaced
.config/dotnet-tools.json # .sonarcloud.properties) and the scanner it runs — 13_CI_CD §SonarCloud
+17
View File
@@ -67,8 +67,25 @@
<FrameLedgerVersionFile>$(MSBuildThisFileDirectory)VERSION</FrameLedgerVersionFile>
<Version Condition="'$(Version)' == '' And Exists('$(FrameLedgerVersionFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerVersionFile)').Trim())</Version>
<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
<!-- D73 (2026-10-31): the RELEASE LINE, from the RELEASE_LINE file beside VERSION - `main`, the betas and releases on
the .NET that global.json pins, or `alpha`, a beta's source built on a prerelease .NET from the long-lived `alpha`
branch, where this file and global.json are two of the few lines that differ (docs/12_BUILD.md §The alpha line).
Not a property a command line sets: the file is the one source, release.yml refuses a tag that disagrees with it,
and the target below refuses a value that is neither line. Every assembly carries it (the ItemGroup below), and
Shared.BuildLine reads it at run time. -->
<FrameLedgerReleaseLineFile>$(MSBuildThisFileDirectory)RELEASE_LINE</FrameLedgerReleaseLineFile>
<FlReleaseLine Condition="Exists('$(FrameLedgerReleaseLineFile)')">$([System.IO.File]::ReadAllText('$(FrameLedgerReleaseLineFile)').Trim())</FlReleaseLine>
</PropertyGroup>
<ItemGroup>
<AssemblyMetadata Include="FrameLedger.ReleaseLine" Value="$(FlReleaseLine)" />
</ItemGroup>
<Target Name="FrameLedgerReleaseLineCheck" BeforeTargets="BeforeBuild" Condition="'$(FlReleaseLine)' != 'main' And '$(FlReleaseLine)' != 'alpha'">
<Error Text="RELEASE_LINE at the repository root must say 'main' or 'alpha', and it says '$(FlReleaseLine)' (docs/12_BUILD.md §The alpha line)" />
</Target>
<!-- The NuGet audit (2026-10-25, docs/13_CI_CD.md §Dependabot and the NuGet audit): every restore checks the WHOLE
package graph, transitive packages included, against the advisory database, at every severity. These are the
SDK's defaults for net10.0, written down so that a later SDK's defaults cannot move them. With
+1
View File
@@ -0,0 +1 @@
main
+12 -2
View File
@@ -1,6 +1,6 @@
# 11 — Updater
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. ~~Stable channel only in v1.~~ *(Corrected 2026-10-04: two channels since P4 PR-5 — `update.channel`, ~~stable by default~~ or beta, which adds pre-releases. Every release so far is a pre-release; see §Built, Channels.)* *(Corrected 2026-10-05: the default is `auto` since beta.14, which follows the running copy — §The update audit, beta.14.)*
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. ~~Stable channel only in v1.~~ *(Corrected 2026-10-04: two channels since P4 PR-5 — `update.channel`, ~~stable by default~~ or beta, which adds pre-releases. Every release so far is a pre-release; see §Built, Channels.)* *(Corrected 2026-10-05: the default is `auto` since beta.14, which follows the running copy — §The update audit, beta.14.)* *(2026-10-31, D73: an **alpha line** beside them, on Velopack's `alpha` channel — §Built, Channels.)*
## Flow
@@ -90,7 +90,17 @@ flow, and the tests run the flow over a fake client because nothing here may tou
log — the "re-validated after update" above. Velopack keeps `current` stable, so `Installed` is the expectation.
- **Channels:** `stable` = releases GitHub does not mark pre-release; `beta` = those too (`GithubSource(prerelease)`).
Not Velopack's own `--channel` mechanism — one package set per tag, the GitHub flag decides. `13_CI_CD` §Branch &
release policy.
release policy. *(Corrected 2026-10-31, D73: true of the main line, whose packages are on Velopack's default `win`
channel. **The alpha line uses Velopack's channels**: an alpha is packed with `--channel alpha`, so its feed is
`releases.alpha.json`, and an installed copy reads only its own channel's feed — `VelopackUpdateClient` passes no
`ExplicitChannel`, so the channel is the one the installed package was built for (its `sq.version` names it). Velopack's
`GithubSource` merges the assets of every release that carries that feed, so a beta never sees an alpha and an alpha
never sees a beta, under either setting of `update.channel`. **One limit follows from the source, read from Velopack's
code 2026-10-31:** it asks
GitHub for one page of ten releases, newest first, so ten releases of one line in a row would hide the other line's
newest from its update check. The cadence is one alpha per beta (`13_CI_CD` §The alpha line). Moving between the lines
is a deliberate install, never an update: the other line's `Setup.exe` over the installed copy, which Velopack answers
with its overwrite prompt — the packId, the install folder and the data folder are the same.)*
- **Hooks** (`VelopackHooks`, in the hand-written `Program.Main` so `VelopackApp.Run()` precedes any window):
install registers nothing; uninstall = `UninstallHook` (`12_BUILD` §Publish & package). `Run()` in a copy the
installer did not lay down returns at once and runs no hook (probed on 1.2.0); it does append a line to Velopack's
+42 -1
View File
@@ -48,7 +48,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
## Managed build & native integration
- **`global.json` pins the SDK band** (`10.0.x`, `rollForward: latestFeature`). Without it `dotnet build` picks the newest installed SDK — on a machine with a .NET 11 preview installed that silently changes analyzer behaviour under `TreatWarningsAsErrors`, and makes local and CI disagree for reasons nobody can see in a diff.
- **`global.json` pins the SDK band** (`10.0.x`, `rollForward: latestFeature`). Without it `dotnet build` picks the newest installed SDK — on a machine with a .NET 11 preview installed that silently changes analyzer behaviour under `TreatWarningsAsErrors`, and makes local and CI disagree for reasons nobody can see in a diff. *(On the `alpha` branch it pins the prerelease SDK instead, on purpose — §The alpha line, 2026-10-31.)*
- `Directory.Build.props`:
- **`TargetFramework` = `net10.0-windows10.0.22621.0`** and **`SupportedOSPlatformVersion` = `10.0.19045.0`**. These are two different knobs and must not be conflated: the TFM platform version selects which Windows API projections are available to compile against, while the supported version is the floor CA1416 enforces. NFR-8 requires Windows 10 **22H2** = build **19045**; letting the supported version default to the TFM's would silently accept installs below the stated floor. Two constraints pin the target to 22621 rather than something closer to the floor: the SDK rejects `SupportedOSPlatformVersion` above `TargetPlatformVersion` (NETSDK1135), and 19045 is not a targeting-pack version in any case — the packs are cut at 19041, 20348, 22000, 22621, 26100. The Windows 11 SDK ≥ 10.0.22621 is already a prerequisite above, so this costs nothing. A bare `net10.0-windows` is wrong for a different reason: it resolves to `net10.0-windows7.0`, and CA1416 would then error on Mica, `MiniDumpWriteDump` and `QueryVideoMemoryInfo` — every Windows-10-era API this app is built on.
- `Platforms`/`PlatformTarget` = `x64`. "x64 only" is asserted in CLAUDE.md and NFR-8 but was previously enforced nowhere except an ad-hoc `-r win-x64` on the publish command.
@@ -162,6 +162,43 @@ repairs state, it does not grant machine-wide reach on its own).
> after every sweep; the flag and the button run the same rule. The uninstall hook is still the updater's
> (P4, Velopack).
## The alpha line (owner decisions D73–D76, 2026-10-31)
The owner, 2026-10-31: an alpha build, "a place where new .NET versions are tried", with code updated where needed and a
warning that it is an experiment used at one's own risk. **The alpha line** is the source of a released beta built on a
prerelease .NET — .NET 11 RC3 first (SDK `11.0.100-rc.3.26522.148`, runtime and Windows Desktop
`11.0.0-rc.3.26522.148`) — from the long-lived `alpha` branch, published as `vX.Y.Z-alpha.N` GitHub pre-releases on
Velopack's `alpha` channel (`13_CI_CD` §The alpha line, `11_UPDATER` §Channels).
- **What differs from main, and nothing else** — `git diff main...alpha` is the whole difference: `RELEASE_LINE`
(`alpha`); `global.json` (the prerelease SDK, `allowPrerelease: true`); the TFM in `Directory.Build.props`
(`net11.0-windows10.0.22621.0` — `SupportedOSPlatformVersion` stays `10.0.19045.0`, so CA1416 still holds the code to
Windows 10 22H2 although Microsoft does not support .NET 11 on its Home and Pro editions); the three Microsoft packages
in `Directory.Packages.props` that are serviced with the runtime (`Microsoft.Extensions.Hosting`,
`System.Diagnostics.EventLog`, `Microsoft.Data.Sqlite`, each `11.0.0-rc.3.26522.148` — the last declares SQLitePCLRaw
3.0.5, SQLite 3.53.4, where main's 10.0.14 declares 2.1.13, SQLite 3.53.3); `legal/licenses/nuget/` regenerated for
that package set; and a fix only .NET 11 can take, if one is ever forced. C# is what `LangVersion latest` gives the
SDK — C# 15 on the 11 SDK — and the source uses none of its syntax: **main must keep building on .NET 10** (D76: retarget
only, no preview feature, no runtime-async).
- **Everything else lives on main**, dormant on the main line. `RELEASE_LINE` is read like `VERSION` and stamped into
every assembly as the `FrameLedger.ReleaseLine` metadata (`Directory.Build.props` refuses any value but `main` and
`alpha`); `Shared.BuildLine` reads it back for the App and the Agent, which compose with it rather than reading it
where they act, so a test hands either line to the code it tests. What the alpha's SDK asks of the source and .NET 10
can also take lands on main.
- **The native layer does not change.** MSVC builds it from the same source; only its build id differs (the alpha's
tag). The hook, the guard and the Vulkan layer in an alpha are the beta's.
- **Sync, and the cadence.** After each beta release a pull request merges main into `alpha` with a merge commit (the
repository allows them; the linear rule is main's) and the next alpha is cut from it — **one alpha per beta, never
several in a row**, because Velopack reads only the newest ten releases (`11_UPDATER` §Channels). A conflict in
`legal/licenses/nuget/` is resolved by regenerating it on `alpha` (`tools/license-gather.ps1`). An alpha older than the
ledger's schema refuses to open it (`LedgerSchemaException`), so a beta that adds a migration is followed by an alpha
soon.
- **Building it locally:** check out `alpha` with the prerelease SDK installed — `global.json` selects it — and run
`./build.ps1 check` as on main.
- **The next .NET build** (an RC, the GA on 2026-11-10, a servicing release) is one line of `global.json` and three
package versions on `alpha`; RC3's support ends at the GA.
- **Whether the main line follows** is not decided here: `20_OPEN_QUESTIONS` §G, *The main line's .NET*.
## Version
**One source: the `VERSION` file at the repository root** (`MAJOR.MINOR.PATCH`, nothing else — P4 PR-5,
@@ -217,6 +254,10 @@ vpk download github --repoUrl https://github.com/poli0981/frameledger --channel
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
```
> **On the alpha line (D73, 2026-10-31) both vpk commands take `--channel alpha`** — the download, so an alpha's delta
> is made from the previous alpha, and the pack, so its feed is `releases.alpha.json`, which no beta reads. The main
> line's pack keeps the command above exactly (no `--channel`: Velopack's default on Windows is `win`). §The alpha line.
> **Run by `release.yml` since 2026-09-14 (P4 PR-5)** — `13_CI_CD` §release.yml carries the steps around it
> (the version gate, `{{RELEASE_DATE}}`, the published-tree assertion, checksums, the release). Both publishes
> take `-p:Version=<tag>` (§Version). No `--icon`: `assets/icon.ico` does not exist, and this line named it
+34 -2
View File
@@ -6,7 +6,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
## Workflows (`.github/workflows/`)
### `ci.yml` — push to `main` + all PRs + `workflow_dispatch` (added 2026-10-04) · **repo-local**
### `ci.yml` — push to `main` *(and to `alpha` since 2026-10-31, D73 — §The alpha line)* + all PRs + `workflow_dispatch` (added 2026-10-04) · **repo-local**
- `runs-on: windows-latest`, .NET SDK pinned by `global.json` via `actions/setup-dotnet`, MSVC via `ilammy/msvc-dev-cmd` (pinned to its v1.13.0 commit since beta.24 — the one third-party action, SonarCloud `githubactions:S7637`; Dependabot moves the pin), NuGet cached.
- Single step of substance: **`./build.ps1 check`** — the same script, with the same switches (none), a developer runs before pushing. The gate list lives in `12_BUILD` §Local quality gate, **once**, rather than being restated here where it goes stale. *(That is the `check` job. Since 2026-10-25 a second job, `sonarcloud`, runs after it — §SonarCloud below; it is not the gate and not a required context.)*
- ~~**`-SkipIntegration` is the one place local and CI deliberately differ**~~ — **gone since 2026-09-06.** From 2026-08-05 CI passed it for a measured reason: §S16 puts the injecting process's ancestors in the scan set, a .NET test host loads `System.Security.Cryptography.ProtectedData.dll`, and the guard's `protect` fragment refused our own harness (§S19(b)). The signer half now verifies that module's embedded signature offline and reads `O=Microsoft Corporation` on the compiled-in bound, so the `Category=Integration` cases run here — **nine** when this was written, **20 across six classes** as of 2026-09-13 (Agent 6, CaptureHost 7, Infrastructure 7); count them with `grep -rl 'Category", "Integration' tests` rather than trusting either number — and a green CI IS evidence for the managed drain and the capture host's end-to-end behaviour. The switch remains in `build.ps1`, loud, for a developer who must.
@@ -168,6 +168,12 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
- `SHA256SUMS.txt` over every asset, published beside them and printed into the release body (`11_UPDATER`
§Unsigned releases).
- `gh release create` with the assets, `--verify-tag`, and `--prerelease` for a `-beta.N` tag.
- **The alpha line (D73, 2026-10-31):** the version gate reads `RELEASE_LINE` beside `VERSION` and refuses a tag that
disagrees with it — on the `alpha` line only `vX.Y.Z-alpha.N`, and an `-alpha.` tag nowhere else. An alpha's download
and pack take `--channel alpha`, so the feed, the asset list, the legacy index and the installer are named for that
channel (`releases.alpha.json`, `assets.alpha.json`, `RELEASES-alpha`, `FrameLedger.App-alpha-Setup.exe`) and its delta
is made from the previous alpha; the main line's pack is unchanged. The release is titled *(experimental alpha)*, and
its notes — the alpha's own file, `docs/changelog/x.y.z-alpha.N.md` — open with the warning (§The alpha line).
- The assets and the notes are also uploaded as a workflow artifact for the smoke checklist (`14_TESTING`
§Release smoke).
- ~~Optional final step: submit installer hash to VirusTotal~~ — not built; an upload of the installer to a third
@@ -213,7 +219,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
pushed `v*` tag in this repository (`head_repository` is checked since beta.26: a fork cannot start the Release run,
and the condition now says so — SonarCloud `githubactions:S7631`), so a `workflow_dispatch` rehearsal of
`release.yml` never publishes. It checks out the run's
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. By hand:
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. **Not after an
alpha's release** (D73, 2026-10-31: a `-alpha.` tag is skipped): the wiki shows the newest beta. By hand:
`gh workflow run wiki.yml -f ref=main -f publish=false` builds, checks and uploads the pages as an artifact; with
`publish=true` it publishes them.
- **Why not a step of `release.yml`:** the release stays as it was, its rehearsal stays a pure rehearsal, and a wiki
@@ -226,6 +233,29 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
- `permissions: contents: write` — the repository's default workflow token is read-only (read from the API,
2026-10-07), and pushing to the wiki repository needs write.
## The alpha line — the `alpha` branch (owner decisions D73–D76, 2026-10-31)
What it is and what differs on the branch: `12_BUILD` §The alpha line. What CI and the release do with it:
- **`ci.yml`** runs `check` on a push to `alpha` and on every pull request into it, under the branch's own `global.json`
— `setup-dotnet` installs the exact prerelease SDK it names whatever the `rollForward`. The `sonarcloud` job does not
run for the branch (the organisation's plan analyses main alone, §SonarCloud), and neither does the `Changelog` step:
what an alpha changes is written in its release's own file on main, never in an `[Unreleased]` entry on `alpha`, which
would collide with main's at every sync.
- **`codeql.yml`** stays on main: the source is main's, and CodeQL's extractor reads C# 14 (CodeQL 2.25.6, June 2026)
while the alpha's compiler is C# 15.
- **The branch is not protected** (an owner's setting; none was asked for): pull requests into it are how changes land
(squash), and the sync from main is a pull request merged with a merge commit — main's linear rule is main's alone.
- **A release of the line**, in order: the alpha's notes on main (`docs/changelog/x.y.z-alpha.N.md` opening with the
warning, its row in `CHANGELOG.md`'s Releases table, a line in HANDOFF's START HERE) → the sync pull request into
`alpha` → a `release.yml` dispatch on `alpha` (`gh workflow run release.yml --ref alpha -f version=x.y.z-alpha.N`) →
the signed tag on `alpha`'s head → the run (§release.yml: the line's tag rule, `--channel alpha`). **No wiki publish**
(`wiki.yml` skips an `-alpha.` tag) and **no release line moves**: README, ACCURACY, the Disclaimer's copy and
LIMITATIONS keep naming the newest beta.
- **The cadence:** one alpha per beta, cut from it. Velopack's GitHub source reads the newest ten releases (one page,
`perPage` 10), so ten alphas in a row would hide every beta from the betas' own update check, and the other way round
(`11_UPDATER` §Channels).
## SonarCloud — from CI, `ci.yml`'s `sonarcloud` job (owner decision D68, 2026-10-25)
**D68 — SonarCloud is analysed from CI.** The owner turned SonarCloud's Automatic Analysis off and set the
@@ -500,6 +530,8 @@ Central package management makes Dependabot PRs single-file diffs.
- `main` protected: CI + CodeQL required, linear history, no direct pushes.
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) *(since beta.24, D66: into their own file, `docs/changelog/X.Y.Z.md`, which opens with that heading, plus its row in `CHANGELOG.md`'s Releases table — `release-notes.ps1` reads the version's own file)* → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) *(corrected 2026-10-04: for a pre-release tag `vX.Y.Z-beta.N`, do not bump `VERSION` — it already holds the numeric core the gate compares, and it read `0.1.0` through eleven betas; the section is `## [X.Y.Z-beta.N] - date`, the full version. Bump `VERSION` only when the numeric core moves)* → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
- Pre-releases: `vX.Y.Z-beta.N` tags mark the GitHub release as pre-release; the App's `stable` channel ignores them and its `beta` channel (Settings ▸ Updates, `update.channel`) includes them — built with P4 PR-5, so ~~explicit beta channel is v2 backlog~~ is struck. The managed assemblies carry the full tag version; the native VERSIONINFO blocks carry the numeric core (`12_BUILD` §Version).
- **Alphas (D73, 2026-10-31):** `vX.Y.Z-alpha.N`, tagged on the `alpha` branch only — `release.yml` refuses one anywhere
else, and any other tag there — published as GitHub pre-releases on Velopack's `alpha` channel. §The alpha line above.
## Repo hygiene checklist
+1
View File
@@ -1916,6 +1916,7 @@ Each of these is referenced by an existing doc but specified nowhere.
| **Accessibility / DPI** | NFR-9 states requirements; no design anywhere | NFR-9, `08_UI` |
| **Uninstall / data deletion** | One Velopack clause. No in-app "delete all my data", despite the privacy position | `12_BUILD`, `legal/PRIVACY_POLICY.md` |
| ~~**Cover art**~~ | ~~Appears in the schema, the data directory and the UI; nothing says where it comes from or the licence position on downloaded store art~~ **Answered 2026-10-14 (beta.23, owner decisions D60/D61):** from the user's own image (a copy in `covers\`) or what the Steam and GOG GALAXY apps already keep on this PC — nothing is downloaded, so no store art is redistributed or fetched; the art stays its owners' (`legal/TRADEMARKS.md`), the Privacy Policy 2.11 names the files read. `08_UI` §Games › Game detail. **Row closed** | `06_DATA_MODEL`, `05_DETECTION` |
| **The main line's .NET** *(added 2026-10-31, D73–D76)* | **When does the main line — the betas and the first release — leave .NET 10 LTS, and for what?** The alpha line (`12_BUILD` §The alpha line) builds the same source on .NET 11 to gather the evidence; it decides nothing by existing. What is known: .NET 11 is STS, supported 24 months to about 2028-11, no later than .NET 10 LTS (2028-11-14), so moving buys no support time; Microsoft's supported-OS list for .NET 11 has Windows 10 only in its LTSC and IoT editions, against NFR-8's Windows 10 22H2 floor; C# 15's unions and closed hierarchies would suit the tri-states and refusal reasons, but only once the main line compiles C# 15. **Decision table, written before the evidence:** move to .NET 11 only if (a) at least two alphas on the GA runtime pass the gate and an owner's run of a hooked title with no runtime-specific defect, (b) the owner accepts dropping NFR-8's floor to Windows 11 or ships knowingly unsupported on Windows 10, and (c) something .NET 11 brings is wanted — a measured gain or a language feature; otherwise stay on .NET 10 and take .NET 12 LTS (expected 2027-11) the same way, through the alpha line first | `12_BUILD`, `13_CI_CD`, `02_SPEC` NFR-8, CLAUDE.md pinned stack |
| **Tier-2 mechanism** *(was: PresentMon distribution)* | **By what mechanism does a shipped build reach a no-injection MEASUREMENT?** Nothing names one. Since 2026-08-28 the ladder is two rungs and Tier 2 is explicitly not a measurement — duration, sensors and the reason — so this row is no longer about degraded fidelity but about whether that capability returns at all. **It now owns TWO casualties, not one:** the frame-generation oracle §S31 spent four attempts looking for, and `14_TESTING`'s Tier-1 accuracy cross-check, struck the same day because it required a second instrument measuring the same frames. **One mechanism would restore both**, which is the strongest argument for costing it. Constraints on any answer: `README`'s capture-tier table and its **safety** row *"always a way out"*, `legal/DISCLAIMER.md` §73 and `legal/EULA.md` §33; ETW needs elevation whatever the tool; and `15_ROADMAP` has no v2 fallback either | `README`, `legal/DISCLAIMER.md`, `legal/EULA.md`, `04_CAPTURE`, `14_TESTING`, `15_ROADMAP` |
---
+45
View File
@@ -0,0 +1,45 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Reflection;
namespace FrameLedger.Shared;
/// <summary>
/// The release line this build belongs to (owner decision D73, 2026-10-31): <see cref="Main"/>, the betas and releases on
/// the .NET that <c>global.json</c> pins, or <see cref="Alpha"/>, a beta's source built on a prerelease .NET from the
/// long-lived <c>alpha</c> branch (<c>docs/12_BUILD.md</c> §The alpha line). The <c>RELEASE_LINE</c> file at the repository
/// root names it; <c>Directory.Build.props</c> stamps it into every assembly as the <see cref="MetadataKey"/> metadata and
/// refuses any other value; <c>release.yml</c> refuses a tag that disagrees with it.
/// </summary>
/// <remarks>
/// Composition reads <see cref="Current"/> once and hands it on, so a test gives either line to the code it tests: an
/// alpha's behaviour (its notice, its banner, its ledger backup) is exercised on <c>main</c>, where no alpha is built.
/// </remarks>
public sealed class BuildLine
{
/// <summary>The metadata key <c>Directory.Build.props</c> writes.</summary>
public const string MetadataKey = "FrameLedger.ReleaseLine";
private BuildLine(string name) => Name = name;
/// <summary>The betas and releases.</summary>
public static BuildLine Main { get; } = new("main");
/// <summary>A beta's source on a prerelease .NET.</summary>
public static BuildLine Alpha { get; } = new("alpha");
/// <summary>The line this build was stamped with; <see cref="Main"/> for an assembly that carries no stamp.</summary>
public static BuildLine Current { get; } = Parse(typeof(BuildLine).Assembly.GetCustomAttributes<AssemblyMetadataAttribute>()
.FirstOrDefault(static a => string.Equals(a.Key, MetadataKey, StringComparison.Ordinal))?.Value);
/// <summary>As <c>RELEASE_LINE</c> spells it.</summary>
public string Name { get; }
public bool IsAlpha => ReferenceEquals(this, Alpha);
/// <summary>The line a stamp names. Only <c>alpha</c> is the alpha: the build refuses any value but the two, so anything else is an assembly built outside it.</summary>
public static BuildLine Parse(string? stamped) => string.Equals(stamped, Alpha.Name, StringComparison.Ordinal) ? Alpha : Main;
public override string ToString() => Name;
}
@@ -67,6 +67,9 @@ public sealed class AssemblyIdentityTests
// The repository every assembly names is the one the App sends issues and document links to.
(assembly.GetCustomAttributes<AssemblyMetadataAttribute>().FirstOrDefault(static a => string.Equals(a.Key, "RepositoryUrl", StringComparison.Ordinal))?.Value)
.Should().Be(IssueLink.Repository, name);
// D73: one release line per build, the one RELEASE_LINE names — every shipped assembly says the same.
(assembly.GetCustomAttributes<AssemblyMetadataAttribute>().FirstOrDefault(static a => string.Equals(a.Key, Shared.BuildLine.MetadataKey, StringComparison.Ordinal))?.Value)
.Should().Be(Shared.BuildLine.Current.Name, name);
}
}
@@ -0,0 +1,57 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.IO;
using System.Reflection;
using FluentAssertions;
using FrameLedger.Shared;
namespace FrameLedger.Infrastructure.Tests;
/// <summary>
/// D73: the release line is the <c>RELEASE_LINE</c> file, stamped into the assemblies by <c>Directory.Build.props</c> and
/// read back by <see cref="BuildLine"/>. On <c>main</c> the file says <c>main</c> and on the <c>alpha</c> branch
/// <c>alpha</c>, so these tests hold on both: what they pin is that the three agree, not which line this is.
/// </summary>
public sealed class BuildLineTests
{
private static string RepoRoot()
{
for (DirectoryInfo? dir = new(AppContext.BaseDirectory); dir is not null; dir = dir.Parent)
{
if (File.Exists(Path.Combine(dir.FullName, "FrameLedger.slnx")))
{
return dir.FullName;
}
}
throw new InvalidOperationException("the repository root (FrameLedger.slnx) is not above " + AppContext.BaseDirectory);
}
[Theory]
[InlineData("main", false)]
[InlineData("alpha", true)]
[InlineData(null, false)]
[InlineData("", false)]
[InlineData("Alpha", false)]
[InlineData("beta", false)]
public void OnlyTheExactWordAlphaIsTheAlphaLine(string? stamped, bool alpha)
{
BuildLine line = BuildLine.Parse(stamped);
line.IsAlpha.Should().Be(alpha);
line.Should().BeSameAs(alpha ? BuildLine.Alpha : BuildLine.Main);
}
[Fact]
public void TheBuildCarriesTheLineTheRepositoryNames()
{
string file = File.ReadAllText(Path.Combine(RepoRoot(), "RELEASE_LINE")).Trim();
string? stamped = typeof(BuildLine).Assembly.GetCustomAttributes<AssemblyMetadataAttribute>()
.FirstOrDefault(static a => string.Equals(a.Key, BuildLine.MetadataKey, StringComparison.Ordinal))?.Value;
file.Should().BeOneOf("main", "alpha");
stamped.Should().Be(file, "Directory.Build.props stamps RELEASE_LINE into every assembly");
BuildLine.Current.Name.Should().Be(file);
}
}
+8 -1
View File
@@ -71,12 +71,19 @@ param(
[string]$DataDir,
[string]$Agent = (Join-Path (Split-Path $PSScriptRoot -Parent) 'src/FrameLedger.Agent/bin/Release/net10.0-windows10.0.22621.0/win-x64/FrameLedger.Agent.exe')
# Empty: the Release build's, whichever target framework built it (the alpha line builds another, D73).
[string]$Agent = ''
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
if (-not $Agent) {
$bin = Join-Path (Split-Path $PSScriptRoot -Parent) 'src/FrameLedger.Agent/bin/Release'
$Agent = @(Get-ChildItem -Path $bin -Filter FrameLedger.Agent.exe -Recurse -File -ErrorAction SilentlyContinue |
Where-Object { $_.Directory.Name -eq 'win-x64' } | Sort-Object LastWriteTimeUtc -Descending | Select-Object -First 1 -ExpandProperty FullName) -join ''
if (-not $Agent) { $Agent = Join-Path $bin '<tfm>/win-x64/FrameLedger.Agent.exe' }
}
if (-not (Test-Path -LiteralPath $Agent)) {
throw "FrameLedger.Agent.exe not found at $Agent. Build it first (./build.ps1 check) or pass -Agent."
}