@hasna/recordings 0.2.14 → 0.3.2

package/scripts/native/realtime-settle-probe/README.md

@@ -0,0 +1,39 @@
+# Realtime settle-latency probe
+
+The standalone probe that produced the settle-latency tables in PR #30. It paces
+real 24 kHz/16-bit/mono PCM through `RealtimeTranscriptionClient` exactly like the
+capture pipeline (4,800-byte chunks every 100 ms, a periodic commit every 900 ms),
+then measures the true post-release settle wait with a deliberately oversized finish
+budget so the observed wait is the session's own settle latency, not a budget cutoff.
+
+The in-tree `RecordingsTests/RealtimeSettleBenchmark.swift` measures the same thing
+through the test harness; this probe exists so the numbers can be reproduced on a
+machine where running the package test suite is not safe or not possible (it links
+only the client and its logging dependency — no test host, no RecordingEngine, no
+production paths; client logs go to an isolated temporary home).
+
+## Build (macOS)
+
+    cd scripts/native/realtime-settle-probe
+    swiftc -O -parse-as-library \
+      ../../../src/native/Recordings/RecordingsLib/RealtimeTranscriptionClient.swift \
+      ../../../src/native/Recordings/RecordingsLib/NativeAppDiagnostics.swift \
+      main.swift -o settleprobe
+
+## Run
+
+    RECORDINGS_BENCH_WAVS="s5.wav:s30.wav:s120.wav" \
+    RECORDINGS_BENCH_RUNS=5 \
+    RECORDINGS_BENCH_KEY_FILE="$HOME/.hasna/recordings/config.json" \
+    ./settleprobe
+
+- `RECORDINGS_BENCH_WAVS` (required): colon-separated 24 kHz/16-bit/mono WAV paths.
+- `RECORDINGS_BENCH_RUNS`: runs per WAV (default 5). Run 1 of the session is cold.
+- `RECORDINGS_BENCH_FINISH_BUDGET_MS`: finish budget (default 10000).
+- `RECORDINGS_BENCH_KEY_FILE` (required): JSON file with `openai_api_key`. The key is
+  read in-process and never exported into any environment.
+
+One `BENCH_RESULT` line per run on stdout:
+
+    BENCH_RESULT wav=... run=1 cold=true audio_seconds=4.6 pcm_bytes=218834 \
+      budget_ms=10000 stream_start_ms=700 finish_wait_ms=777 settled=true chars=85 error=

package/scripts/native/realtime-settle-probe/main.swift

@@ -0,0 +1,135 @@
+import Foundation
+
+// Standalone settle-latency probe: paces real PCM through RealtimeTranscriptionClient
+// exactly like the capture pipeline (4,800-byte chunks / 100 ms, periodic commit /
+// 900 ms), then measures the finish/settle wait. Compiled with swiftc against
+// RealtimeTranscriptionClient.swift + NativeAppDiagnostics.swift only — no test
+// harness, no RecordingEngine, no production paths: client logs go to a temp dir.
+
+func pcmData(fromWavAtPath path: String) throws -> Data {
+    let data = try Data(contentsOf: URL(fileURLWithPath: path))
+    precondition(data.count > 44, "WAV too small: \(path)")
+    precondition(
+        String(data: data[0..<4], encoding: .ascii) == "RIFF"
+            && String(data: data[8..<12], encoding: .ascii) == "WAVE",
+        "not a RIFF/WAVE file: \(path)"
+    )
+    var index = 12
+    var pcm: Data?
+    while index + 8 <= data.count {
+        let chunkID = String(data: data[index..<index + 4], encoding: .ascii) ?? ""
+        let chunkSize = Int(
+            UInt32(data[index + 4]) | UInt32(data[index + 5]) << 8
+                | UInt32(data[index + 6]) << 16 | UInt32(data[index + 7]) << 24
+        )
+        let body = index + 8
+        guard body + chunkSize <= data.count else { break }
+        if chunkID == "fmt ", chunkSize >= 16 {
+            let format = UInt16(data[body]) | UInt16(data[body + 1]) << 8
+            let channels = UInt16(data[body + 2]) | UInt16(data[body + 3]) << 8
+            let sampleRate = UInt32(data[body + 4]) | UInt32(data[body + 5]) << 8
+                | UInt32(data[body + 6]) << 16 | UInt32(data[body + 7]) << 24
+            let bits = UInt16(data[body + 14]) | UInt16(data[body + 15]) << 8
+            precondition(
+                format == 1 && channels == 1 && sampleRate == 24_000 && bits == 16,
+                "probe WAV must be PCM/mono/24kHz/16-bit: \(path)"
+            )
+        } else if chunkID == "data" {
+            pcm = data.subdata(in: body..<body + chunkSize)
+        }
+        index = body + chunkSize + (chunkSize % 2)
+    }
+    guard let payload = pcm else { fatalError("no data chunk in \(path)") }
+    return payload
+}
+
+func monotonicMilliseconds() -> UInt64 {
+    UInt64(ProcessInfo.processInfo.systemUptime * 1_000)
+}
+
+@main
+struct SettleProbe {
+    static func main() async {
+        let environment = ProcessInfo.processInfo.environment
+        let wavPaths = (environment["RECORDINGS_BENCH_WAVS"] ?? "").split(separator: ":").map(String.init)
+        precondition(!wavPaths.isEmpty, "RECORDINGS_BENCH_WAVS is required")
+        let runsPerWav = Int(environment["RECORDINGS_BENCH_RUNS"] ?? "") ?? 5
+        let finishBudget = UInt64(environment["RECORDINGS_BENCH_FINISH_BUDGET_MS"] ?? "") ?? 10_000
+        // The key is read in-process from the app's own config file and lives only in
+        // this process's memory — never exported into a shell environment, never
+        // printed. RECORDINGS_BENCH_KEY_FILE points at the config; no default writes.
+        let keyFile = environment["RECORDINGS_BENCH_KEY_FILE"] ?? ""
+        precondition(!keyFile.isEmpty, "RECORDINGS_BENCH_KEY_FILE is required")
+        let apiKey: String = {
+            guard let data = FileManager.default.contents(atPath: keyFile),
+                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+                  let key = json["openai_api_key"] as? String
+            else { return "" }
+            return key
+        }()
+        precondition(!apiKey.isEmpty, "no openai_api_key in \(keyFile)")
+
+        let benchHome = NSTemporaryDirectory() + "recordings-settle-probe-" + UUID().uuidString
+        try? FileManager.default.createDirectory(atPath: benchHome, withIntermediateDirectories: true)
+        print("BENCH_HOME \(benchHome)")
+
+        var coldRun = true
+        for wavPath in wavPaths {
+            guard let pcm = try? pcmData(fromWavAtPath: wavPath) else {
+                print("BENCH_ERROR wav=\(wavPath) reason=unreadable")
+                continue
+            }
+            let audioSeconds = Double(pcm.count) / 48_000.0
+            for run in 1...runsPerWav {
+                let client = RealtimeTranscriptionClient(apiKey: apiKey, homePath: benchHome)
+                let startBegan = monotonicMilliseconds()
+                await client.startStreaming(language: "en")
+                let streamStart = monotonicMilliseconds() - startBegan
+                guard client.isStreaming else {
+                    let text = client.stop()
+                    print(
+                        "BENCH_RESULT wav=\(wavPath) run=\(run) cold=\(coldRun) "
+                            + "audio_seconds=\(String(format: "%.1f", audioSeconds)) "
+                            + "stream_start_ms=\(streamStart) finish_wait_ms=0 settled=false "
+                            + "chars=\(text.count) error=\((client.error ?? "start_failed").replacingOccurrences(of: " ", with: "_"))"
+                    )
+                    coldRun = false
+                    continue
+                }
+
+                let chunkSize = 4_800
+                var offset = 0
+                var lastCommitAt = monotonicMilliseconds()
+                while offset < pcm.count {
+                    let end = min(offset + chunkSize, pcm.count)
+                    client.sendAudio(pcm.subdata(in: offset..<end))
+                    offset = end
+                    try? await Task.sleep(for: .milliseconds(100))
+                    let now = monotonicMilliseconds()
+                    if now - lastCommitAt >= 900 {
+                        if await client.commitInput(reason: "periodic") {
+                            lastCommitAt = now
+                        }
+                    }
+                }
+
+                let finishBegan = monotonicMilliseconds()
+                let result = await client.finish(
+                    timeoutMilliseconds: finishBudget,
+                    pipelineID: UUID().uuidString,
+                    pipelineStartedUptimeMilliseconds: finishBegan
+                )
+                let finishWait = monotonicMilliseconds() - finishBegan
+                print(
+                    "BENCH_RESULT wav=\(wavPath) run=\(run) cold=\(coldRun) "
+                        + "audio_seconds=\(String(format: "%.1f", audioSeconds)) "
+                        + "pcm_bytes=\(pcm.count) budget_ms=\(finishBudget) "
+                        + "stream_start_ms=\(streamStart) finish_wait_ms=\(finishWait) "
+                        + "settled=\(result.settled) chars=\(result.text.count) "
+                        + "error=\((result.error ?? "").replacingOccurrences(of: " ", with: "_"))"
+                )
+                coldRun = false
+            }
+        }
+    }
+}

package/scripts/policy/local-only-approved-targets.txt

@@ -0,0 +1,21 @@
+# Single source of truth for the Macs approved as local-only artifact targets.
+#
+# One short hostname (`hostname -s`) per line. Blank lines and lines beginning
+# with `#` are ignored. Both `scripts/macos_artifact.ts` and the two shell
+# entry points (`scripts/install_macos_app.sh`, `src/native/Recordings/build.sh`)
+# read this file, so a target is added in exactly one place.
+#
+# This file is an OPERATOR-INTEGRITY control, NOT an authorization boundary. It
+# lives in the same package root as the scripts that read it, so anyone who can
+# edit it can equally edit those guards; it is not ownership- or mode-checked
+# beyond "regular file, not a symlink". Adding a name here therefore grants
+# nothing by itself.
+#
+# Every local-only artifact is still ad-hoc signed and non-notarized, must be
+# built on a Mac other than the target AND on a different authenticated Tailscale
+# node, and stays bound to the target's authenticated machine-identity digest; the
+# install additionally re-checks `hostname -s`, the live Tailscale node digest,
+# and an authenticated manifest SHA-256. Release artifacts ignore this file
+# entirely and use the fleet target policy.
+station03
+station06

package/scripts/read_local_only_targets.sh

@@ -0,0 +1,203 @@
+# shellcheck shell=bash
+# Shared reader for the local-only approved-target policy. Sourced by both
+# scripts/install_macos_app.sh and src/native/Recordings/build.sh, so the two shell
+# entry points cannot drift apart.
+#
+# This is a SECOND implementation of the same rules as localOnlyApprovedTargets() in
+# scripts/macos_artifact.ts, not a shared one — shell cannot call that function without
+# spawning bun inside argument validation. The two are kept behaviourally equivalent by
+# an executing contract test ("the shell reader and the TypeScript reader agree on every
+# policy shape"), which is the only thing that actually holds them together. If you
+# change the rules here, change them there and extend that test.
+#
+# Rules: reject anything that is not a regular file (a symlinked policy is refused, not
+# followed) or not readable, strip an optional UTF-8 BOM from the FIRST line only and a
+# trailing CR from every line, trim ASCII space and tab only, reject any NUL byte, drop
+# blank and comment lines, then require every target to be a well-formed short hostname,
+# unique, and never the release fleet target. Anything else fails closed.
+#
+# Four of those rules exist because the two readers disagreed and the disagreement was
+# provable, not theoretical:
+#   * SYMLINKS. `[ -L ]` here refused a symlinked policy while readFileSync() there
+#     followed it, so a symlink pointing at a widened allowlist was rejected by the
+#     shell and silently honoured by TypeScript. Both now refuse; a symlink is never a
+#     legitimate shape for package-local policy data shipped inside the tarball. Note the
+#     granularity: only the FINAL path component is checked, so a policy reached through a
+#     symlinked package root — which is what pnpm and yarn produce — still resolves.
+#   * ASCII-ONLY TRIM. This used to trim [[:space:]], while TypeScript trims /[\t ]/
+#     only. Enumerated, that split 21 of 36 whitespace rows, and in every one of them
+#     THIS reader accepted a target TypeScript rejects — build gate open, install
+#     validator closed. [[:space:]] covers VT (0x0b), FF (0x0c) and CR, and in a UTF-8
+#     locale it also matched U+1680, U+2000, U+2002, U+2009, U+205F, U+2028, U+2029 and
+#     U+3000. Both now trim space and tab only and leave everything else in place for the
+#     hostname shape to reject. This one change closes all 21 rows on its own.
+#   * BOM POSITION. This used to strip a BOM from every line while TypeScript strips one
+#     only at offset 0, so a BOM on the second line was accepted here and rejected there.
+#     A U+FEFF anywhere but the very start of the file is a zero-width no-break space,
+#     not a byte-order mark, and both readers now reject it.
+#   * PHASE ORDER. See the four numbered phases below.
+#
+# DO NOT DELETE the `local LC_ALL=C LANG=C` below. It is not decoration, and the platform
+# where it matters is not the platform you are probably reading this on.
+#
+# `[a-z0-9-]` and `[!a-z]` are bracket RANGES, and range endpoints in a shell pattern are
+# resolved by collation, not by byte value. Under a UTF-8 locale collation interleaves case
+# (a A b B c C …), so `[a-z]` matches uppercase and `STATION07` — which the TypeScript
+# reader rejects unconditionally — parses here as a valid target. That is this reader's
+# whole failure mode: build gate open, install validator closed.
+#
+# The `globasciiranges` shopt forces ASCII semantics for ranges regardless of locale, which
+# is what hides this on a modern Linux box. Be precise about WHICH bash, because the obvious
+# summary is wrong: per bash's own NEWS, the option was INTRODUCED in 4.3 (§4.3 e.) but only
+# became ENABLED BY DEFAULT in 5.0 (§5.0 hh.). So bash 4.3 and 4.4 are exposed exactly as 3.2
+# is unless someone opts in, and it is only from 5.0 that the pin "looks like it does
+# nothing". macOS ships /bin/bash 3.2.57, which has no such option at all — and
+# src/native/Recordings/build.sh is `#!/bin/bash` and exports NO locale of its own, so on
+# the Mac that actually builds artifacts this function-local pin is the only thing standing
+# between the caller's LANG and the allowlist. (scripts/install_macos_app.sh:4-6 exports
+# LC_ALL=C/LANG=C/TZ=UTC0, so the installer is covered independently; the builder is not.)
+#
+# Measured, emulating 3.2 range semantics with `shopt -u globasciiranges` under
+# LC_ALL=en_US.UTF-8, on a policy containing STATION07:
+#   pinned   -> "invalid target name: STATION07"        (agrees with TypeScript)
+#   unpinned -> ACCEPTED, list=[STATION07], matched=1   (TypeScript still rejects)
+# That case is an executing test: "the shell reader stays byte-exact under a hostile
+# locale" in src/__tests__/local-only-target-policy.test.ts. An earlier revision of this
+# comment claimed the pin was unguarded and protected nothing; that was measured only on
+# bash 5.2 with globasciiranges on, which is the configuration that hides the problem.
+
+# read_local_only_targets <policy-path> <out-list-var> <out-match-var> <requested-target>
+# Sets <out-list-var> to a comma-separated list for error messages and
+# <out-match-var> to 1 when <requested-target> is approved. Returns non-zero with a
+# message on stderr when the policy itself is unusable.
+read_local_only_targets() {
+  local LC_ALL=C LANG=C
+  local policy_path="$1"
+  local list_var="$2"
+  local match_var="$3"
+  local requested="$4"
+
+  if [ ! -f "$policy_path" ] || [ -L "$policy_path" ]; then
+    echo "Local-only approved target policy is missing." >&2
+    return 1
+  fi
+
+  # A mode-000 policy passes the test above (`-f` needs no read permission) and then made
+  # every redirection below fail with bash's own "Permission denied" and no reader message,
+  # while the TypeScript reader raised a raw EACCES out of readFileSync. Same fail-closed
+  # outcome, two unrecognizable errors; both readers now say this instead.
+  if [ ! -r "$policy_path" ]; then
+    echo "Local-only approved target policy is not readable." >&2
+    return 1
+  fi
+
+  # `read` silently discards NUL bytes, so "station03\0station99" would otherwise be
+  # accepted as the single target "station03station99" — quietly dropping station03 from
+  # the allowlist. `read -d ''` succeeds only when it finds a NUL, so this fails closed.
+  if IFS= read -r -d '' _ < "$policy_path"; then
+    echo "Local-only approved target policy contains a NUL byte." >&2
+    return 1
+  fi
+
+  local line target list="" matched=0 first_line=1
+  local blanks=$' \t'
+  local -a targets=()
+  # Counted as they are collected rather than asked of the array afterwards. See Phase 1.
+  local target_count=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    if [ "$first_line" -eq 1 ]; then
+      line="${line#$'\xef\xbb\xbf'}"
+      first_line=0
+    fi
+    line="${line%$'\r'}"
+    # Trim ASCII space and tab only, so an indented entry or comment behaves the same
+    # here as it does in the TypeScript reader. Deliberately not [[:space:]]: that also
+    # covers VT and FF, which TypeScript's /[\t ]/ leaves in place to be rejected.
+    line="${line#"${line%%[!$blanks]*}"}"
+    line="${line%"${line##*[!$blanks]}"}"
+    case "$line" in '' | '#'*) continue ;; esac
+    targets+=("$line")
+    target_count=$((target_count + 1))
+  done < "$policy_path"
+
+  # The remaining rules run in FOUR SEPARATE PHASES, in this order, and the order is load
+  # bearing: it is the order localOnlyApprovedTargets() uses in scripts/macos_artifact.ts.
+  # This reader used to validate each line completely before reading the next, so a policy
+  # breaking two rules at once got whichever complaint came first by LINE while TypeScript
+  # got whichever came first by RULE — "fleet\nfleet\n" was "must not list the release
+  # fleet target" here and "has duplicate targets" there. Both still refused every such
+  # policy, so no gate ever opened on it, but two readers cannot be called one policy while
+  # they disagree about what is wrong, and the contract test that compares refusal reasons
+  # is only honest if the phase order matches. Measured over 1500 multi-violation policies:
+  # 160 reason divergences before this restructure, 0 after, 0 verdict divergences in both.
+
+  # Phase 1: any targets at all.
+  #
+  # A plain counter, not `${#targets[@]}`. This is the ONE test reachable with an empty
+  # array, and both callers run `set -euo pipefail` (src/native/Recordings/build.sh:5,
+  # scripts/install_macos_app.sh:2) on a platform whose /bin/bash is 3.2.57. Whether the
+  # LENGTH form of an empty-array expansion is safe under `set -u` in 3.2 is something
+  # nobody here can execute — there is no macOS and no bash 3.2 on this machine — so this
+  # sidesteps the question instead of asserting an answer to it. An earlier revision of
+  # this very file was talked into deleting a load-bearing line by a confident comment
+  # about behaviour nobody had run; a counter costs nothing and needs no such claim.
+  if [ "$target_count" -eq 0 ]; then
+    echo "Local-only approved target policy lists no targets." >&2
+    return 1
+  fi
+
+  # Phase 2: every name well formed. Shape and length are one regex on the TypeScript side,
+  # so they share this message and are checked together, target by target in order.
+  #
+  # `${targets[@]+"${targets[@]}"}` and not the plainer `"${targets[@]}"`: both callers run
+  # `set -euo pipefail` (src/native/Recordings/build.sh:5, scripts/install_macos_app.sh:2) and
+  # macOS ships /bin/bash 3.2.57, where expanding an EMPTY array under `set -u` is an
+  # "unbound variable" error rather than an empty list. Phase 1 above already returned for the
+  # empty case, so no loop here is reachable with an empty array today — this keeps the
+  # property PROVABLE rather than dependent on that ordering surviving the next edit. If it
+  # ever did fire, the caller would die with bash's `unbound variable` instead of
+  # "lists no targets", which is precisely the unrecognizable-error class this reader exists
+  # to eliminate. The remaining `${#targets[@]}` uses are inside Phase 3's arithmetic, which
+  # this function only reaches once Phase 1 has proven the array non-empty.
+  for target in ${targets[@]+"${targets[@]}"}; do
+    case "$target" in
+      *[!a-z0-9-]* | [!a-z]* | *-)
+        echo "Local-only approved target policy has an invalid target name: ${target}" >&2
+        return 1
+        ;;
+    esac
+    if [ "${#target}" -lt 3 ] || [ "${#target}" -gt 32 ]; then
+      echo "Local-only approved target policy has an invalid target name: ${target}" >&2
+      return 1
+    fi
+  done
+
+  # Phase 3: no duplicates.
+  local index other
+  for ((index = 0; index < ${#targets[@]}; index++)); do
+    for ((other = index + 1; other < ${#targets[@]}; other++)); do
+      if [ "${targets[index]}" = "${targets[other]}" ]; then
+        echo "Local-only approved target policy has duplicate targets." >&2
+        return 1
+      fi
+    done
+  done
+
+  # Phase 4: never the release fleet target.
+  for target in ${targets[@]+"${targets[@]}"}; do
+    if [ "$target" = "fleet" ]; then
+      echo "Local-only approved target policy must not list the release fleet target." >&2
+      return 1
+    fi
+  done
+
+  for target in ${targets[@]+"${targets[@]}"}; do
+    list="${list:+${list}, }${target}"
+    if [ "$target" = "$requested" ]; then
+      matched=1
+    fi
+  done
+
+  printf -v "$list_var" '%s' "$list"
+  printf -v "$match_var" '%s' "$matched"
+}

package/scripts/scan-artifact.ts

@@ -0,0 +1,40 @@
+// Pack this repository as it would be published, then scan the actual tarball.
+// `--ignore-scripts` prevents this prepack gate from recursively re-entering
+// prepack while it creates the artifact to inspect.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import {
+  formatArtifactScanReport,
+  resolveAssetInventoryWaivers,
+  scanPublishedArtifact,
+} from "@hasna/contracts/artifact-scan";
+
+function run(command: string[], cwd: string): string {
+  const result = Bun.spawnSync(command, { cwd, stdout: "pipe", stderr: "pipe" });
+  const stdout = new TextDecoder().decode(result.stdout).trim();
+  if (result.exitCode !== 0) {
+    const stderr = new TextDecoder().decode(result.stderr).trim();
+    throw new Error(`${command.join(" ")} exited ${result.exitCode}\n${stdout}\n${stderr}`);
+  }
+  return stdout;
+}
+
+const repoRoot = join(import.meta.dir, "..");
+const workspace = mkdtempSync(join(tmpdir(), "recordings-artifact-scan-"));
+
+try {
+  const packed = run(
+    [process.execPath, "pm", "pack", "--destination", workspace, "--ignore-scripts", "--quiet"],
+    repoRoot,
+  );
+  const archive = isAbsolute(packed) ? packed : join(workspace, packed);
+  const waivers = resolveAssetInventoryWaivers(join(repoRoot, "hasna.contract.json"));
+  for (const note of waivers.notes) console.log(`waiver: ${note}`);
+  const report = scanPublishedArtifact(archive, { waivedKinds: waivers.kinds });
+  console.log(formatArtifactScanReport(report));
+  if (!report.ok) process.exitCode = 1;
+} finally {
+  rmSync(workspace, { recursive: true, force: true });
+}

package/scripts/set-version.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+// Single writer for every copy of the release version. package.json is the
+// authority because scripts/build_companion_cli.sh derives EXPECTED_VERSION from
+// it and rejects a compiled CLI whose --version disagrees, which aborts
+// src/native/Recordings/build.sh under set -euo pipefail.
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type VersionSite = {
+  /** Repo-relative file carrying a copy of the release version. */
+  file: string;
+  /** Label used in check output. */
+  label: string;
+  /** Group 2 is the version; groups 1 and 3 are preserved verbatim on write. */
+  pattern: RegExp;
+};
+
+export const versionSites: VersionSite[] = [
+  {
+    file: "package.json",
+    label: "package.json version",
+    pattern: /("version"\s*:\s*")([^"]+)(")/,
+  },
+  {
+    file: "src/version.ts",
+    label: "src/version.ts VERSION",
+    pattern: /(export const VERSION = ")([^"]+)(")/,
+  },
+  {
+    file: "src/native/Recordings/RecordingsLib/Info.plist",
+    label: "Info.plist CFBundleShortVersionString",
+    pattern: /(<key>CFBundleShortVersionString<\/key>\s*<string>)([^<]+)(<\/string>)/,
+  },
+  {
+    file: "src/native/Recordings/RecordingsLib/Info.plist",
+    label: "Info.plist CFBundleVersion",
+    pattern: /(<key>CFBundleVersion<\/key>\s*<string>)([^<]+)(<\/string>)/,
+  },
+];
+
+export type SiteReading = {
+  site: VersionSite;
+  version: string;
+};
+
+export type VersionCheck = {
+  expected: string;
+  readings: SiteReading[];
+  mismatched: SiteReading[];
+};
+
+// The authority is whichever site the build script reads, so it stays first.
+const authoritySite = versionSites[0];
+
+export function repoRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+// Rejects a leading "v" the same way prepareReleaseInstallInputs does, so a
+// bump cannot introduce a form the release path already refuses.
+export function assertReleaseVersion(version: string): string {
+  if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`invalid release version: ${version} (expected MAJOR.MINOR.PATCH)`);
+  }
+  return version;
+}
+
+function readSite(root: string, site: VersionSite): SiteReading {
+  const match = readFileSync(join(root, site.file), "utf8").match(site.pattern);
+  if (!match) {
+    throw new Error(`${site.file}: no version found for ${site.label}`);
+  }
+  return { site, version: match[2] };
+}
+
+export function checkVersionSites(root: string = repoRoot()): VersionCheck {
+  const readings = versionSites.map((site) => readSite(root, site));
+  const authority = readings.find((reading) => reading.site === authoritySite);
+  if (!authority) {
+    throw new Error(`missing authority version site: ${authoritySite.label}`);
+  }
+  const expected = authority.version;
+  return {
+    expected,
+    readings,
+    mismatched: readings.filter((reading) => reading.version !== expected),
+  };
+}
+
+export function applyVersion(version: string, root: string = repoRoot()): SiteReading[] {
+  assertReleaseVersion(version);
+
+  // Group by file so two sites in one file (the plist) do not clobber each other.
+  const files = [...new Set(versionSites.map((site) => site.file))];
+  for (const file of files) {
+    const path = join(root, file);
+    let contents = readFileSync(path, "utf8");
+    for (const site of versionSites.filter((candidate) => candidate.file === file)) {
+      if (!site.pattern.test(contents)) {
+        throw new Error(`${file}: no version found for ${site.label}`);
+      }
+      contents = contents.replace(site.pattern, `$1${version}$3`);
+    }
+    writeFileSync(path, contents);
+  }
+
+  return versionSites.map((site) => ({ site, version }));
+}
+
+function main(argv: string[]): void {
+  const [command] = argv;
+
+  if (command === undefined || command === "--check" || command === "check") {
+    const { expected, readings, mismatched } = checkVersionSites();
+    if (mismatched.length > 0) {
+      console.error(`Version sites disagree (${authoritySite.label} says ${expected}):`);
+      for (const reading of mismatched) {
+        console.error(`  ${reading.site.label}: ${reading.version}`);
+      }
+      console.error("Fix with: bun run version:set <version>");
+      process.exit(1);
+    }
+    console.log(`Version sites agree at ${expected} (${readings.length} sites).`);
+    return;
+  }
+
+  if (command === "--help" || command === "-h") {
+    console.log("Usage: bun run scripts/set-version.ts [--check | <version>]");
+    return;
+  }
+
+  for (const reading of applyVersion(command)) {
+    console.log(`  ${reading.site.label} -> ${reading.version}`);
+  }
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}