feat(workbench): keep versioned measurements and offline replay

.gitattributes

@@ -16,3 +16,6 @@ CMakeLists.txt text eol=lf
 # so the next one-line edit showed up as a whole-file rewrite in two locales.
 *.md   text eol=lf
 *.mdx  text eol=lf
+
+# Adopted measurement manifests hash exact bytes; keep their artifacts unchanged.
+workbench/measurements/** -text

.github/scripts/previous-stable-tag.mjs

@@ -0,0 +1,41 @@
+// Prints the tag a release's notes start from: the highest stable tag (vX.Y.Z,
+// no suffix) below the given version, by SemVer, or an empty line when there is
+// none. The tags come on stdin as `git tag -l 'v*'` lists them: every tag,
+// whether or not it is reachable from the release commit.
+//
+// build.yml used to guess that tag's name by arithmetic and fall back to
+// `git describe` when the guess did not exist (#1002). 2.0.0 guessed v1.0.0,
+// which never existed, and `git describe` on release/v2.0.0 found the release's
+// own last RC: v2.0.0 shipped with an empty changelog. A guess that did exist
+// could still be wrong: 1.13.0 compared against v1.12.0 and repeated the PRs of
+// v1.12.1 and v1.12.2. Only a tag that exists can come out of here, which also
+// keeps the RC notes' `git log <tag>..` from dying on `unknown revision`, as
+// v1.9.4-rc.1's did when the guess named a 1.9.3 that never shipped.
+
+import { readFileSync } from "node:fs";
+import { argv } from "node:process";
+
+const STABLE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
+
+const parse = (tag) => tag.match(STABLE_TAG)?.slice(1).map(Number);
+const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+/**
+ * @param {string} version Stable version being released, e.g. "2.0.0".
+ * @param {string[]} tags Tag names; anything but vX.Y.Z is ignored.
+ * @returns {string} The highest vX.Y.Z below `version`, or "" when there is none.
+ */
+export function previousStableTag(version, tags) {
+	const current = parse(`v${version}`);
+	if (!current) throw new Error(`invalid version ${JSON.stringify(version)}; expected X.Y.Z`);
+	const below = tags
+		.map((tag) => [tag, parse(tag)])
+		.filter(([, parts]) => parts && compare(parts, current) < 0);
+	below.sort(([, a], [, b]) => compare(b, a));
+	return below[0]?.[0] ?? "";
+}
+
+// Only run when invoked directly, so the test can import the function.
+if (import.meta.filename === argv[1]) {
+	console.log(previousStableTag(argv[2], readFileSync(0, "utf8").split(/\s+/)));
+}

.github/scripts/previous-stable-tag.test.mjs

@@ -0,0 +1,78 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { previousStableTag } from "./previous-stable-tag.mjs";
+
+// Real tags of this repository, in the order `git tag -l` prints them: by name, so v1.9.x
+// comes after v1.13.0 and picking by position or as text gets it wrong. The v0.0.0-* tags
+// host release assets; `git describe` once picked one of them for v2.0.0-rc.1's notes.
+const TAGS = [
+	"v0.0.0",
+	"v0.0.0-onnxruntime-1.27.1",
+	"v1.0.1",
+	"v1.10.0",
+	"v1.12.0",
+	"v1.12.1",
+	"v1.12.1-rc.1",
+	"v1.12.2",
+	"v1.12.2-rc.1",
+	"v1.13.0",
+	"v1.13.0-rc.6",
+	"v1.9.2",
+	"v1.9.3-rc.1",
+	"v1.9.6",
+	"v2.0.0",
+	"v2.0.0-rc.15",
+];
+
+describe("previousStableTag", () => {
+	it("compares a major against the last stable of the line before", () => {
+		// The arithmetic guessed v1.0.0, which does not exist, and the fallback found
+		// v2.0.0-rc.15: v2.0.0 shipped with an empty changelog (#1002).
+		expect(previousStableTag("2.0.0", TAGS)).toBe("v1.13.0");
+	});
+
+	it("compares a minor against the last patch, not the .0", () => {
+		// Against v1.12.0, 1.13.0's notes repeated every PR of v1.12.1 and v1.12.2.
+		expect(previousStableTag("1.13.0", TAGS)).toBe("v1.12.2");
+	});
+
+	it("compares a patch against the patch before it", () => {
+		expect(previousStableTag("1.12.2", TAGS)).toBe("v1.12.1");
+	});
+
+	it("is empty when no stable tag sorts below", () => {
+		// A first release: its RCs exist, nothing before them does.
+		expect(previousStableTag("1.0.0", ["v1.0.0", "v1.0.0-rc.1", "v1.0.0-rc.2"])).toBe("");
+	});
+
+	it("ignores pre-release tags", () => {
+		// 1.9.3 shipped only as rc.1, so the last release before 1.9.4 is v1.9.2.
+		expect(previousStableTag("1.9.4", TAGS)).toBe("v1.9.2");
+	});
+
+	it("rejects a version that is not X.Y.Z", () => {
+		expect(() => previousStableTag("2.0.0-rc.1", TAGS)).toThrow(/invalid version/);
+	});
+
+	// The direct-invocation guard makes the script print nothing at all if it ever stops
+	// matching, and the workflow would read that as "no previous release". So this runs it
+	// exactly as build.yml does: relative path from the repo root, the tags on stdin.
+	it("runs the way build.yml invokes it", () => {
+		const repoRoot = join(import.meta.dirname, "../..");
+		const workflow = readFileSync(join(repoRoot, ".github/workflows/build.yml"), "utf8");
+		expect(workflow).toContain(
+			`git tag -l 'v*' | node .github/scripts/previous-stable-tag.mjs "$STABLE_VERSION"`,
+		);
+
+		const run = (version) =>
+			execFileSync("node", [".github/scripts/previous-stable-tag.mjs", version], {
+				cwd: repoRoot,
+				input: `${TAGS.join("\n")}\n`,
+				encoding: "utf8",
+			});
+		expect(run("2.0.0")).toBe("v1.13.0\n");
+		expect(run("0.0.0")).toBe("\n");
+	});
+});

.github/scripts/refresh-nix-npm-hash.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Rewrites `npmDepsHash` in nix/package.nix for the package-lock.json in the working tree.
+#
+# Called by prerelease.yml and promote.yml right after set-release-version.mjs, in the same
+# commit. The lockfile's root `version` is part of what the hash covers, so every version bump
+# changes it; that commit is `[skip ci]`, and refreshing the hash anywhere later left `nix build`
+# red from the release until a separate bump PR landed. Needs Nix on PATH.
+set -euo pipefail
+
+hash=$(nix run nixpkgs#prefetch-npm-deps -- package-lock.json)
+if [[ -z "$hash" ]]; then
+	echo "::error::prefetch-npm-deps returned an empty hash"
+	exit 1
+fi
+sed -i -E "s|^([[:space:]]*npmDepsHash[[:space:]]*=[[:space:]]*)\"[^\"]*\";|\1\"${hash}\";|" nix/package.nix
+grep -q "npmDepsHash = \"${hash}\";" nix/package.nix || {
+	echo "::error::npmDepsHash line not found in nix/package.nix"
+	exit 1
+}
+echo "npmDepsHash: ${hash}"

.github/workflows/build.yml

@@ -52,10 +52,12 @@ jobs:
         uses: ./.github/actions/setup
 
       # STT is the bundled whisper-stt-server (whisper.cpp with native DTW token
-      # timestamps); no VAD model is fetched here. The binary is built by
-      # build-whisper-stt.yml and staged below — without that step the installer
-      # ships without speech-to-text. See
-      # technical-documentation/architecture/transcription-and-captions.md.
+      # timestamps); no model is fetched here. The binary is built by
+      # build-whisper-stt.yml and staged below, from the run built from this
+      # commit's helper sources — without that step the installer ships without
+      # speech-to-text. See
+      # technical-documentation/architecture/transcription-and-captions.md, and
+      # technical-documentation/engineering/release-and-secrets.md for the run.
       - name: Stage whisper-stt binaries
         shell: bash
         env:
@@ -376,6 +378,13 @@ jobs:
       - name: Stage ONNX Runtime
         run: npm run fetch:onnxruntime
 
+      # Fourth step spelled out for the same reason: `build:mac`, `build:win` and
+      # `build:linux` chain it before electron-builder. It writes the licence texts of the
+      # bundled npm packages and of the crates in the addon; scripts/before-pack.cjs
+      # refuses to package without them.
+      - name: Generate third-party licences
+        run: npm run licenses:generate
+
       - name: Package .app bundle
         run: npx electron-builder --mac --${{ matrix.arch }} --dir --publish never
         env:
@@ -649,9 +658,9 @@ jobs:
 
       # bsdtar (libarchive-tools) is fpm's mtree generator for the pacman target.
       # rpmbuild (rpm) is what fpm shells out to for the rpm target; without it the
-      # build fails at packaging, not at config parse.
+      # build fails at packaging, not at config parse. zsync generates AppImageUpdate sidecars.
       - name: Install Linux packaging dependencies
-        run: sudo apt-get update && sudo apt-get install -y libarchive-tools rpm
+        run: sudo apt-get update && sudo apt-get install -y libarchive-tools rpm zsync
 
       # patchelf is what build-linux-compositor-addon.mjs renames the ffmpeg symbols
       # with, so the addon cannot bind to Chromium's bundled ffmpeg — an unconditional
@@ -706,6 +715,21 @@ jobs:
             exit 1
           fi
 
+      - name: Verify AppImage update information and sidecars
+        run: |
+          VERSION="$(node -p 'require("./package.json").version')"
+          EXPECTED='gh-releases-zsync|getopenscreen|openscreen|latest|Openscreen-Linux-*.AppImage.zsync'
+          # Helper-only prereleases can be selected by AppImageUpdate's latest-all channel.
+          # RCs keep using electron-updater; their .zsync is available by its explicit URL.
+          if [[ "$VERSION" == *-* ]]; then EXPECTED=''; fi
+          while IFS= read -r -d '' IMAGE; do
+            test -s "${IMAGE}.zsync" \
+              || { echo "::error::${IMAGE}.zsync missing — external AppImage updates have no sidecar"; exit 1; }
+            INFO="$("$IMAGE" --appimage-updateinformation)"
+            [[ "$INFO" == "$EXPECTED" ]] \
+              || { echo "::error::Unexpected AppImage update information in ${IMAGE}: ${INFO}"; exit 1; }
+          done < <(find release -type f -name '*.AppImage' -print0)
+
       # The Linux counterpart of the Windows job's "Verify native binaries load under
       # package identity", added for the same reason and after the same kind of miss:
       # 1.9.1 shipped three sonames that nothing declared and nothing bundled — libgbm.so.1
@@ -745,16 +769,12 @@ jobs:
           name: openscreen-linux
           path: |
             release/**/*.AppImage
+            release/**/*.AppImage.zsync
             release/**/*.deb
             release/**/*.pacman
             release/**/*.rpm
             release/**/latest-linux.yml
-          # Still no *.zsync, and there never will be: zsync was electron-updater's old delta
-          # format and app-builder-lib 26.x dropped it in favour of the block map it embeds
-          # directly in the AppImage. That glob had matched nothing since the dependency bump,
-          # silently — `if-no-files-found: error` evaluates the union of these patterns, so one
-          # dead glob among live ones never fails. Hence the explicit assertion below.
-          #
+          # .zsync serves external AppImage tools; electron-updater uses the embedded blockmap.
           # latest-linux.yml serves all four formats from one file: each updater picks its own
           # extension out of the `files:` list. app-update.yml and the `package-type` marker are
           # already inside the deb/rpm/pacman payloads — only this feed was missing.
@@ -778,8 +798,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v7
         with:
-          # Full history + tags: the RC notes below are built from `git log` over the
-          # range since the previous RC tag, and resolving that tag needs the tags.
+          # Full history + tags: the previous release's tag is picked from every tag in the
+          # repo, and the RC notes below are built from `git log` over the range since it.
           fetch-depth: 0
 
       - name: Resolve release tag
@@ -818,16 +838,11 @@ jobs:
           # Compute the previous stable tag for auto-generated release notes. We don't use
           # GitHub's "most recent prior release by date" because the fork carries re-published
           # upstream releases whose published_at is more recent than the fork's own first release.
-          # For SemVer X.Y.Z: previous is vX.Y.(Z-1) if Z>0, else vX.(Y-1).0, else v(X-1).0.0.
+          # Picked by SemVer among the tags that exist, never guessed from the version number:
+          # the script says what guessing cost (#1002). Left EMPTY when no stable tag sorts
+          # below this version; each consumer below decides what "no previous release" means.
           STABLE_VERSION="${VERSION%%-*}"
-          IFS='.' read -r PX PY PZ <<< "$STABLE_VERSION"
-          if (( PZ > 0 )); then
-            NOTES_START_TAG="v${PX}.${PY}.$((PZ - 1))"
-          elif (( PY > 0 )); then
-            NOTES_START_TAG="v${PX}.$((PY - 1)).0"
-          else
-            NOTES_START_TAG="v$((PX - 1)).0.0"
-          fi
+          NOTES_START_TAG="$(git tag -l 'v*' | node .github/scripts/previous-stable-tag.mjs "$STABLE_VERSION")"
           # For an RC, compare against the PREVIOUS RC of the same line, not the previous
           # stable. Deriving the start tag from STABLE_VERSION alone made every RC of a
           # line span the same range, so each re-cut just repeated the last RC's notes
@@ -843,27 +858,6 @@ jobs:
               fi
             done
           fi
-          # Everything above computes what the previous release was *called* and
-          # never checks that it exists. A version line that stopped at its RC
-          # makes that a name for nothing: 1.9.3 shipped only as rc.1, so
-          # v1.9.4-rc.1 asked git for v1.9.3..v1.9.4-rc.1 and the publish step
-          # died on `unknown revision` -- after all four platforms had already
-          # built, and with publish-msstore sitting behind publish-release, so
-          # the same gap would silently block a stable release's Store
-          # deployment too. The rc walk-down above handles a skipped RC; nothing
-          # handled a skipped stable, and it does not run at all for an rc.1.
-          if ! git rev-parse -q --verify "refs/tags/${NOTES_START_TAG}" >/dev/null; then
-            # The nearest tag reachable from the release commit's parent, which
-            # is what "since the last release" meant in the first place. Left
-            # EMPTY when no tag is reachable at all, rather than filled with the
-            # root commit: the stable path hands this to `gh release create
-            # --notes-start-tag`, which is the API's previous_tag_name and takes
-            # a tag NAME -- a commit SHA there is not a lenient fallback, it is
-            # an invalid argument. Each consumer below decides what "no previous
-            # release" means for it.
-            NOTES_START_TAG="$(git describe --tags --abbrev=0 "${TAG}^" 2>/dev/null || true)"
-            echo "Previous-release tag did not exist; using ${NOTES_START_TAG:-<none>}"
-          fi
           echo "Computed notes_start_tag=${NOTES_START_TAG} for tag=${TAG}"
 
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"