Router that virtually distributes inference across connected devices in the home.
Go
ci: run checks and builds on GitHub Actions, with release-intent automation (#87)
Noah Tervalonb4a0cc5b39a9
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 38a0939..f7b6157 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -3,6 +3,40 @@<!-- Explain the problem and the user-visible outcome. --><!-- Link issues with "Closes #123". -->+## Release intent++<!-- Keep the fences exactly as they are; CI parses between them. -->+<!-- Set each bump to none, patch, minor, or major. Leave the key names. -->+<!-- `services` must be >= the highest component bump. -->+<!-- Set the title and body to n/a when no bump is a release. -->+<!-- The release version users see is NOT declared here: it patch-bumps by+ itself whenever any bump above is a release. -->+<!-- Keep the changelog body to prose and bullets. A line starting with "### "+ ends the section and silently truncates the rest. -->++<!-- pair-release-intent:v1 -->+### Changelog title+n/a++### Changelog body+n/a++### Bumps+- services: none+- nvpair-cluster-manager: none+- nvpair-engine-manager: none+- nvpair-errors: none+- nvpair-job-scheduler: none+- nvpair-manual-nodes: none+- nvpair-node-info: none+- nvpair-node-scanner: none+- nvpair-node-settings: none+- nvpair-proxy: none+- nvpair-tui: none+- nvpair-ui-broker: none+- nvpair-workload-manager: none+<!-- /pair-release-intent:v1 -->+## Scope<!-- What is intentionally included and excluded? -->@@ -23,4 +57,4 @@- [ ] Relevant documentation is updated.- [ ] I checked the diff, changed filenames, and commit messages for credentials, private data, internal URLs, internal issue identifiers, and generated artifacts.- [ ] I recorded the validation commands and results above.-- [ ] I bumped any affected component in `services/versions.json`, and described user-visible changes above so they reach the release notes.+- [ ] I declared version bumps in the release-intent block above. `services/versions.json` is written by automation — do not edit it by hand.diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.ymlnew file mode 100644index 0000000..8fddd56--- /dev/null+++ b/.github/actions/setup/action.yml@@ -0,0 +1,70 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++# The single place the Node and Go versions are declared.+#+# GitHub Actions has no shared constants file: `env:` is per-workflow and one+# workflow cannot read another. Four workflows exist because each needs a+# distinct `on:` block, so without this they would each carry their own copy of+# the versions, and bumping one while forgetting another would have pull request+# checks and release builds running different toolchains.+#+# The caller must check out the repository first — a local action cannot exist+# until its own repo is on disk, so checkout stays in the workflow.+#+# On a fork pull request this file comes from the fork, like every other script+# those jobs run. That adds no exposure: those jobs already execute the pull+# request's `npm ci` and `go test`, hold no secret, and run on hosted runners.+name: Set up toolchains+description: Installs the pinned Node and Go toolchains used across all workflows.++inputs:+ node:+ description: Install Node.+ default: 'true'+ go:+ description: Install Go.+ default: 'false'+ npm-cache:+ description: Cache the npm download cache. Pointless without an npm install.+ default: 'true'++runs:+ using: composite+ steps:+ # desktop/package.json engines requires >=25.5.0. Pinned to a major+ # rather than read from that range, which would drift to whatever Node+ # is newest.+ - if: inputs.node == 'true'+ uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5+ with:+ node-version: '25'+ cache: ${{ inputs.npm-cache == 'true' && 'npm' || '' }}+ cache-dependency-path: desktop/package-lock.json++ # Forbids the surprise toolchain download, so the version below is the+ # one that actually builds. Set before setup-go because setup-go reads+ # GOTOOLCHAIN when resolving a version file.+ - if: inputs.go == 'true'+ shell: bash+ run: echo 'GOTOOLCHAIN=local' >> "$GITHUB_ENV"++ # Must be >= the highest `go` directive across services/*/go.mod, which+ # GOTOOLCHAIN=local would otherwise refuse to satisfy.+ #+ # cache-dependency-path is required, not an optimization. setup-go+ # caches by default and looks for the dependency file at the repository+ # root, where there is none — every Go module lives under services/.+ # Left unset it reports "Dependencies file is not found" on every run.+ # Naming the path also pins the cache key: older versions hash go.sum,+ # newer ones hash go.mod.+ #+ # scripts/ matches nothing today; it is listed so a Go dependency added+ # to the support tooling joins the key instead of silently missing it.+ - if: inputs.go == 'true'+ uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6+ with:+ go-version: '1.26.7'+ cache-dependency-path: |+ services/**/go.sum+ scripts/**/go.sumdiff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlnew file mode 100644index 0000000..3e86003--- /dev/null+++ b/.github/workflows/build.yml@@ -0,0 +1,109 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++# Unsigned installer builds on GitHub-hosted runners.+#+# These are verification and pull-request artifacts, never releases: every+# target ends in `electron-builder --publish never`, and this workflow holds no+# signing or publishing credentials. Signed releases are produced separately+# from a tag, and are rebuilt from source rather than signing anything this+# workflow produced.+name: Build++on:+ workflow_dispatch:+ push:+ branches: [main, develop]+ pull_request:+ branches: [main, develop]+ paths:+ - '.github/workflows/**'+ # The composite action pins the Node and Go versions. Without this+ # a toolchain bump would run ci.yml and skip the installer matrix,+ # which is the cross-workflow drift the action exists to prevent.+ - '.github/actions/**'+ - 'scripts/**'+ - 'services/**'+ - 'desktop/package.json'+ - 'desktop/package-lock.json'+ - 'desktop/src/**'+ - 'desktop/scripts/**'+ - 'desktop/native/**'+ - 'desktop/resources/**'+ - 'desktop/tsconfig*.json'+ - 'desktop/vite.*.config.ts'+ - 'desktop/electron.vite.config.ts'+ - 'desktop/electron-builder.config.ts'++permissions:+ contents: read++concurrency:+ group: build-${{ github.ref }}+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}++# Toolchain versions are declared once, in .github/actions/setup.++jobs:+ build:+ name: ${{ matrix.name }}+ runs-on: ${{ matrix.os }}+ timeout-minutes: 60+ strategy:+ # One platform failing should not hide the state of the other five.+ fail-fast: false+ matrix:+ include:+ - name: linux-x64+ os: ubuntu-latest+ script: build:linux:x64+ - name: linux-arm64+ os: ubuntu-latest+ script: build:linux:arm64+ - name: win-x64+ os: windows-latest+ script: build:win:x64+ - name: win-arm64+ os: windows-latest+ script: build:win:arm64+ - name: mac-arm64+ os: macos-latest+ script: build:mac:arm64+ - name: mac-x64+ os: macos-15-intel+ script: build:mac:x64+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5++ # Recorded so a failure can be read against the machine it ran on.+ - name: Report runner capacity+ shell: bash+ run: |+ echo "label: ${{ matrix.os }}"+ echo "kernel: $(uname -s) $(uname -m)"+ echo "cpus: $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo unknown)"+ free -h 2>/dev/null || sysctl -n hw.memsize 2>/dev/null || echo "mem: unknown"+ df -h . | tail -1++ - uses: ./.github/actions/setup+ with:+ go: 'true'++ # electron-builder needs fakeroot and rpm to stage Linux packages;+ # ubuntu-latest ships neither.+ - name: Install Linux packaging tools+ if: runner.os == 'Linux'+ run: sudo apt-get update -qq && sudo apt-get install -y -qq fakeroot rpm++ - run: npm --prefix desktop ci --prefer-offline++ - name: Build ${{ matrix.name }}+ run: npm --prefix desktop run ${{ matrix.script }}++ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4+ if: always()+ with:+ name: unsigned-${{ matrix.name }}+ path: desktop/release/**+ retention-days: 7+ if-no-files-found: warndiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlnew file mode 100644index 0000000..24ae051--- /dev/null+++ b/.github/workflows/ci.yml@@ -0,0 +1,191 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++# Runs on every pull request, including from forks.+#+# This workflow holds no secrets and requests no OIDC token. That is+# deliberate: it executes code from the pull request — npm postinstall hooks,+# `go test`, the tsx build scripts — so there must be no credential for that+# code to reach. Keep it that way, and keep it on GitHub-hosted runners, which+# are destroyed after each job.+#+# Signed release builds happen elsewhere, from a tag, and never from a pull+# request.+name: CI++# Pull requests target `develop`; periodic `develop` -> `main` merges are the+# release cut. Both branches are gated identically.+on:+ pull_request:+ branches: [main, develop]+ push:+ branches: [main, develop]++permissions:+ contents: read++concurrency:+ group: ci-${{ github.ref }}+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}++# Toolchain versions are declared once, in .github/actions/setup.++jobs:+ # Release-intent validation lives in release-intent-check.yml, not here: it+ # also needs the `edited` pull request type, and re-running this whole gate+ # on every description edit would rebuild six installers for a typo fix.++ # Dependency-free and therefore the cheapest gate: no npm install, no cache.+ # Deliberately unfiltered by path — a missing header can arrive anywhere.+ headers:+ name: SPDX headers+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5+ - uses: ./.github/actions/setup+ with:+ npm-cache: 'false'+ - run: node scripts/spdx-headers.mjs++ desktop:+ name: Desktop checks+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5+ - uses: ./.github/actions/setup+ - run: npm --prefix desktop ci --prefer-offline++ # Same order as the local gate documented in CONTRIBUTING.md, so a+ # local run and CI fail on the same thing first.+ - run: npm --prefix desktop run verify:build-scripts+ - run: npm --prefix desktop run service-contracts:check+ - run: npm --prefix desktop run typecheck+ - run: npm --prefix desktop run lint+ - run: npm --prefix desktop run dead-code:check+ - run: npm --prefix desktop run test:unit++ services:+ name: Services build and tests+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5+ - uses: ./.github/actions/setup+ with:+ go: 'true'+ # Engine-manager orphan-reclaim tests need lsof and ss.+ - run: sudo apt-get update -qq && sudo apt-get install -y -qq lsof iproute2+ - run: npm --prefix desktop ci --prefer-offline++ - name: Build modular binaries+ run: npm --prefix desktop run build:modular-binaries -- --force++ # Skip shared/ and eap-noob/ (libraries) and tests/ (run separately+ # below with a longer timeout — it also matches services/*/go.mod).+ - name: Go component tests+ run: |+ failed=0+ for d in services/*/go.mod; do+ dir=$(dirname "$d")+ name=$(basename "$dir")+ case "$name" in shared|eap-noob|tests) continue ;; esac+ echo "==> go test $name"+ (cd "$dir" && go test ./... -count=1 -timeout=10m) || failed=1+ done+ exit $failed++ - name: Go cross-process tests+ run: cd services/tests && go test ./... -count=1 -timeout=20m++ # Support tooling outside services/ has its own module and is not+ # matched by the glob above.+ - name: Go tooling tests+ run: |+ failed=0+ for d in scripts/*/go.mod; do+ dir=$(dirname "$d")+ echo "==> go test $dir"+ (cd "$dir" && go test ./... -count=1 -timeout=5m) || failed=1+ done+ exit $failed++ # The services tree has two independent build paths over the same Go code.+ # The `services` job above drives `scripts/build-modular-binaries.ts`, which+ # cross-compiles for the desktop app. This drives `services/build.sh`, which+ # builds natively, parses versions.json with jq, stamps each binary with+ # `-ldflags -X main.Version`, and stages `build/bin`. They read versions and+ # pass flags differently, so one can break while the other stays green.+ #+ # Runs on each supported platform because the Windows path is a separate+ # script (`build.bat`) rather than a branch of the same one.+ build-script:+ name: Build script (${{ matrix.os }})+ runs-on: ${{ matrix.os }}+ timeout-minutes: 20+ strategy:+ fail-fast: false+ matrix:+ os: [ubuntu-latest, macos-latest, windows-latest]+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5+ - uses: ./.github/actions/setup+ with:+ node: 'false'+ go: 'true'++ # Both scripts fail fast with their own message when go or jq is+ # missing, so there is no separate tool-check step here.+ - name: Build services (bash)+ if: runner.os != 'Windows'+ working-directory: services+ run: ./build.sh++ - name: Build services (Windows)+ if: runner.os == 'Windows'+ working-directory: services+ shell: cmd+ run: build.bat++ # Compares the staged set against versions.json rather than a count.+ # A floor like `-ge 13` passes quietly the moment the real number+ # grows, so it stops asserting anything; and a hardcoded `-eq 13`+ # only catches the count, not a rename. Comparing names means+ # adding, removing, or renaming a component fails here until the+ # build script and the manifest agree again.+ #+ # The binaries are not executed to check them: several are servers+ # that would ignore an unrecognized flag and start listening.+ - name: Check staged binaries match versions.json+ working-directory: services+ shell: bash+ run: |+ # Both sides run through the same normalizer, so they cannot+ # disagree on collation or line endings. Order matters: CR has+ # to go before the .exe suffix, because under Git Bash a CRLF+ # line leaves .exe mid-string and `s/\.exe$//` never matches.+ # LC_ALL=C makes the sort byte-wise, which is also what comm+ # below assumes.+ norm() { tr -d '\r' | sed 's/\.exe$//' | LC_ALL=C sort; }+ expected=$(jq -r '.components | keys[]' versions.json | norm)+ staged=$(ls -1 build/bin | norm)++ if [ "$expected" = "$staged" ]; then+ printf 'all %s declared components staged\n' \+ "$(printf '%s\n' "$expected" | wc -l | tr -d ' ')"+ exit 0+ fi++ echo "::error::build/bin does not match versions.json components"+ echo "--- declared but not staged (build script missing a component?)"+ comm -23 <(printf '%s\n' "$expected") <(printf '%s\n' "$staged")+ echo "--- staged but not declared (versions.json missing a component?)"+ comm -13 <(printf '%s\n' "$expected") <(printf '%s\n' "$staged")+ # When both lists above look identical the difference is a+ # character you cannot see. `sed -n l` renders CR as \r and+ # marks end of line with $.+ echo "--- raw build/bin"+ ls -l build/bin+ echo "--- expected, escaped"+ printf '%s\n' "$expected" | sed -n l+ echo "--- staged, escaped"+ printf '%s\n' "$staged" | sed -n l+ exit 1diff --git a/.github/workflows/release-intent-apply.yml b/.github/workflows/release-intent-apply.ymlnew file mode 100644index 0000000..21f9c9e--- /dev/null+++ b/.github/workflows/release-intent-apply.yml@@ -0,0 +1,56 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++# Applies a merged pull request's release-intent block to the version files.+#+# Kept in its own file precisely because it holds a credential. ci.yml and+# release-intent-check.yml run on pull requests from forks and must stay free+# of secrets; this one is only ever reachable from a push to an integration+# branch, which requires write access. Do not add a pull_request or+# pull_request_target trigger here.+#+# Runs on `develop`, not `main`: one merge produces one apply, and the+# Applies-PR trailer assumes exactly that. A release cut merges an accumulated+# range into `main`, which this would see as a single push covering many pull+# requests — and the script cannot aggregate them. The cut carries the already+# applied bumps forward instead.+name: Release intent++on:+ push:+ branches: [develop]++permissions:+ contents: read++# Concurrent applies are handled by the script, not here: it commits with+# `force: false` and re-reads the ref when the branch moved underneath it.+# Do not add a `concurrency:` group — GitHub keeps only one pending run and+# cancels any earlier one, so a burst of merges silently loses bumps.++jobs:+ apply:+ name: Apply+ runs-on: ubuntu-latest+ # The bot's own push triggers this workflow: an app installation token,+ # unlike GITHUB_TOKEN, does start workflow runs. The script exits early+ # on its own commits; this skips them without booting a runner first.+ if: ${{ !startsWith(github.event.head_commit.message, '[release-intent]') }}+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5++ # An installation token, not a PAT: it expires in an hour and is+ # scoped to this repository. Granted `contents: write` and+ # deliberately NOT the Workflows permission, so a compromise of this+ # job cannot rewrite .github/workflows.+ - name: Mint an app token+ id: app-token+ uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2+ with:+ app-id: ${{ vars.RELEASE_INTENT_APP_ID }}+ private-key: ${{ secrets.RELEASE_INTENT_APP_PRIVATE_KEY }}++ - name: Apply release intent+ env:+ RELEASE_INTENT_TOKEN: ${{ steps.app-token.outputs.token }}+ run: python3 scripts/release-intent/apply_pr.pydiff --git a/.github/workflows/release-intent-check.yml b/.github/workflows/release-intent-check.ymlnew file mode 100644index 0000000..462bbdc--- /dev/null+++ b/.github/workflows/release-intent-check.yml@@ -0,0 +1,57 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++# Gates a pull request on a valid pair-release-intent:v1 block.+#+# Separate from ci.yml for one reason: `edited`. A pull request body can change+# after checks go green, and the apply job reads the live body from the API at+# merge time — so validating only on opened/synchronize/reopened (the defaults)+# leaves a window where the declared bumps differ from the ones CI enforced.+# Adding `edited` to ci.yml would re-run the whole gate, six installer builds+# included, on every typo fix in a description. This check is cheap, so it gets+# its own trigger.+#+# Needs no secret: the body arrives in the webhook payload, so this runs on+# pull requests from forks like every other check.+name: Release intent check++# `develop` only, deliberately. release-intent-apply.yml runs on pushes to+# `develop`, so gating pull requests into `main` would demand an intent block+# and then discard it: a release cut is one push covering many pull requests,+# and the Applies-PR trailer assumes one merge produces one apply.+#+# Leaving `main` out also keeps the cut itself mergeable. A develop -> main pull+# request carries the bot's own edits to services/versions.json and+# CHANGELOG.md, which are exactly the paths check_forbidden_paths rejects.+on:+ pull_request:+ branches: [develop]+ types: [opened, synchronize, reopened, edited]++permissions:+ contents: read++concurrency:+ group: release-intent-check-${{ github.ref }}+ cancel-in-progress: true++jobs:+ validate:+ name: Validate+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5+ with:+ # The bot-owned path check diffs against the merge base, which+ # a shallow clone does not contain.+ fetch-depth: 0+ - name: Validate release intent+ env:+ # Author-controlled, so it is passed through `env:` and never+ # interpolated into the command.+ PR_BODY: ${{ github.event.pull_request.body }}+ PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}+ PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}+ run: |+ python3 scripts/release-intent/test_lib.py+ python3 scripts/release-intent/validate_pr.pydiff --git a/AGENTS.md b/AGENTS.mdindex db8908c..7e28422 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -131,9 +131,11 @@ On Windows, run the underlying npm and `go test` commands directly.service, the broker relay, every consumer, the desktop bridge under`desktop/src/electron/service-bridge/`, the tests, and the documentation in thesame change. Then run `npm run service-contracts:check` from `desktop/`.-- **Bump the version of any service binary whose compiled output you change** in- `services/versions.json`, and describe any user-facing change in the pull- request so it reaches the release notes.+- **Declare a bump for any service binary whose compiled output you change** in+ the `pair-release-intent:v1` block in your pull request description, and+ describe any user-facing change there so it reaches the changelog. Do not edit+ `services/versions.json` or `CHANGELOG.md` by hand — automation writes them,+ and CI rejects a pull request that modifies them.[Versioning](services/VERSIONING.md) gives the rules.- **Sign off every commit** with `git commit -s`. The Developer Certificate ofOrigin trailer has to match the commit author, so a missing or mismatcheddiff --git a/CHANGELOG.md b/CHANGELOG.mdnew file mode 100644index 0000000..f635b52--- /dev/null+++ b/CHANGELOG.md@@ -0,0 +1,45 @@+<!--+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+SPDX-License-Identifier: Apache-2.0+-->++# Changelog++Release history for Personal AI Router, newest first. Entries match the+published releases on GitHub.++Builds from this repository are unsigned and configure no update feed, so+automatic updates are unavailable in them.++## 0.1.1++### Fixed++- Building from source for an Intel/AMD (`x64`) target failed while compiling+ the bundled log sanitizer. The packaging script passed Electron's `x64`+ architecture name straight to the Go toolchain, which expects `amd64`.+ Arm64 targets were unaffected.++This release contains no application changes. The fix is to the build tooling+only, and the published 0.1.0 installers were not affected by it, so 0.1.1 is+functionally identical to 0.1.0 for anyone installing it.++## 0.1.0++### Fixed++- **Windows on Arm installations were missing every executable.** The+ installer's compressed payload used a compression filter its extractor could+ not decode, so an install reported success with the application tree present+ but all `.exe` and `.dll` files silently skipped. Arm64 installs now+ complete correctly.+- **Windows on Arm now installs under 64-bit Program Files** instead of the+ 32-bit location.+- **Silent installs no longer abort** on the installer's payload check.++### Changed++- Raised the Electron floor and updated the Go toolchain and service+ dependencies to pick up security fixes.+- Trimmed the README, and added an `AGENTS.md` so an agent working from a fork+ has an entry point.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 62593f3..7114a96 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -261,11 +261,20 @@ screenshots and examples.## Versions-When your change alters a service binary's compiled output, bump that component-in `services/versions.json` in the same pull request.+When your change alters a service binary's compiled output, declare that bump in+the `pair-release-intent:v1` block in your pull request description. The pull+request template contains the block; fill in the severity for each component and+write the changelog title and body there.++**Do not edit `services/versions.json` or `CHANGELOG.md` by hand.** Automation+writes both after your pull request merges, and CI rejects a pull request that+modifies them. If you are adding or removing a component — something the bot+cannot infer — include `<!-- pair-release-intent-allow-owned-files -->` in the+description to override that check.+[Versioning](services/VERSIONING.md) gives the rules for choosing a patch, minor,-or major bump, and covers the `desktop/package.json` version, which follows its-own release cycle.+or major bump, and explains the three version numbers and which of them you are+expected to declare.Say in the pull-request description which components you bumped and why, so areviewer can check the decision rather than infer it from the diff.@@ -280,7 +289,9 @@ clear description is what makes a change show up there correctly.Anyone may submit a pull request. Follow this checklist:1. Fork the repository.-2. Create a focused branch from `main` in your fork.+2. Create a focused branch from `develop` in your fork, and open the pull+ request against `develop`. That is the integration branch; `main` receives+ `develop` periodically as a release cut.3. Explain the problem and observable desired outcome.4. State what is intentionally in and out of scope.5. Add or update tests and documentation.diff --git a/desktop/docs/services-api.md b/desktop/docs/services-api.mdindex 3d6b66a..7aea40f 100644--- a/desktop/docs/services-api.md+++ b/desktop/docs/services-api.md@@ -7,7 +7,7 @@> capability status lives in `docs/services-parity.md`.- **Source tree**: `services/` in this monorepo-- **Versions**: see `services/versions.json` (product, installer, and per-component)+- **Versions**: see `services/versions.json` (services suite and per-component)- **Legend**: ✅ referenced by the bridge · ❌ MISSING (no consumer/caller) · ➖ ignored (see `docs/service-contract-exceptions.json`)## Drift summarydiff --git a/desktop/docs/services-backend.md b/desktop/docs/services-backend.mdindex 23b8253..25d8328 100644--- a/desktop/docs/services-backend.md+++ b/desktop/docs/services-backend.md@@ -335,8 +335,10 @@ The build is cache-aware. CI passes `--force`. Packaging validates that2. Review component version changes, emitted notifications, handled requests,and new binary components, then regenerate `docs/services-api.md` with- `service-contracts:write`. Bump the affected components in- `services/versions.json` as `services/VERSIONING.md` describes. Do not+ `service-contracts:write`. Declare bumps for the affected components in the+ pull request's `pair-release-intent:v1` block as `services/VERSIONING.md`+ describes; `services/versions.json` is written by automation and CI rejects+ a hand edit. Do nothardcode product or component versions in this document or`docs/services-parity.md` — `service-contracts:check` fails if they appear.3. Read the changed backend `README.md` / `spec.md` and the Go implementation.diff --git a/desktop/scripts/build-modular-binaries.ts b/desktop/scripts/build-modular-binaries.tsindex bfdc3cb..e84b499 100644--- a/desktop/scripts/build-modular-binaries.ts+++ b/desktop/scripts/build-modular-binaries.ts@@ -71,7 +71,7 @@ interface ManifestFile {interface BuildManifest {source: 'services-build'sourceFingerprint: string- product: string+ services: stringplatform: SupportedPlatformarch: ModularPackageArchcomponents: Record<string, string>@@ -145,7 +145,7 @@ function stringRecord(value: JsonValue | undefined): Record<string, string> {}interface ParsedVersions {- product: string+ services: stringcomponents: Record<string, string>}@@ -173,8 +173,8 @@ function readVersions(repo: string): ParsedVersions {const versionsPath = path.join(repo, 'versions.json')const parsed: JsonValue = JSON.parse(readFileSync(versionsPath, 'utf8'))if (!isJsonObject(parsed)) throw new Error(`${versionsPath} is not a JSON object`)- const product = typeof parsed['product'] === 'string' ? parsed['product'] : ''- return { product, components: stringRecord(parsed['components']) }+ const services = typeof parsed['services'] === 'string' ? parsed['services'] : ''+ return { services, components: stringRecord(parsed['components']) }}function ensureGoToolchain(): void {@@ -267,7 +267,7 @@ function parseManifest(text: string): BuildManifest | null {return {source: 'services-build',sourceFingerprint,- product: typeof parsed['product'] === 'string' ? parsed['product'] : '',+ services: typeof parsed['services'] === 'string' ? parsed['services'] : '',platform,arch,components: stringRecord(parsed['components']),@@ -310,6 +310,9 @@ function manifestIsCurrent(if (!manifest) return falseif (manifest.sourceFingerprint !== sourceFingerprint || !sourceFingerprint) return falseif (manifest.platform !== options.platform || manifest.arch !== options.arch) return false+ // Without this a services-only bump leaves the manifest current, so the+ // stale version is what the UI reports in dev.+ if (manifest.services !== versions.services) return falseif (JSON.stringify(manifest.components) !== JSON.stringify(versions.components)) return falseconst expected = new Set(expectedFileNames(options.platform))@@ -423,7 +426,7 @@ function main(): void {const manifest: BuildManifest = {source: 'services-build',sourceFingerprint,- product: versions.product,+ services: versions.services,platform: options.platform,arch: options.arch,components: versions.components,diff --git a/desktop/scripts/verify-service-contracts.ts b/desktop/scripts/verify-service-contracts.tsindex 5323a45..e09dd5e 100644--- a/desktop/scripts/verify-service-contracts.ts+++ b/desktop/scripts/verify-service-contracts.ts@@ -333,7 +333,7 @@ function renderApiDoc(reports: BinaryReport[], drift: Drift): string {L.push('> capability status lives in `docs/services-parity.md`.')L.push('')L.push(`- **Source tree**: \`services/\` in this monorepo`)- L.push(`- **Versions**: see \`services/versions.json\` (product, installer, and per-component)`)+ L.push(`- **Versions**: see \`services/versions.json\` (services suite and per-component)`)L.push('- **Legend**: ✅ referenced by the bridge · ❌ MISSING (no consumer/caller) · ➖ ignored (see `docs/service-contract-exceptions.json`)')diff --git a/desktop/src/electron/ipc/service.ipc.ts b/desktop/src/electron/ipc/service.ipc.tsindex b7b1ebc..7480e68 100644--- a/desktop/src/electron/ipc/service.ipc.ts+++ b/desktop/src/electron/ipc/service.ipc.ts@@ -80,7 +80,7 @@ export function registerServiceIpc(): void {: ''return {appVersion: app.getVersion(),- modularProduct: manifest.product,+ modularServices: manifest.services,binaries,licenseType}diff --git a/desktop/src/electron/service-bridge/modular-supervisor.ts b/desktop/src/electron/service-bridge/modular-supervisor.tsindex 680b169..8cd1012 100644--- a/desktop/src/electron/service-bridge/modular-supervisor.ts+++ b/desktop/src/electron/service-bridge/modular-supervisor.ts@@ -89,7 +89,7 @@ function getModularBinaryPath(baseName: string): string {}/**- * Read the build provenance (`sourceFingerprint` + `product`) and per-component+ * Read the build provenance (`sourceFingerprint` + `services`) and per-component* versions that `scripts/build-modular-binaries.ts` stamps into* `cli-bin/manifest.json`.* `components` is keyed by binary base name (e.g. `ollama-proxy`). Returns empty@@ -97,15 +97,15 @@ function getModularBinaryPath(baseName: string): string {*/export function readCliBinManifest(): {commit: string- product: string+ services: stringcomponents: Record<string, string>} {try {const manifestPath = path.join(getCliBinDir(), 'manifest.json')- if (!fs.existsSync(manifestPath)) return { commit: '', product: '', components: {} }+ if (!fs.existsSync(manifestPath)) return { commit: '', services: '', components: {} }const parsed: JsonValue = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))const obj = objectValue(parsed)- if (!obj) return { commit: '', product: '', components: {} }+ if (!obj) return { commit: '', services: '', components: {} }const components: Record<string, string> = {}const componentsObj = objectValue(obj['components'])if (componentsObj) {@@ -116,22 +116,22 @@ export function readCliBinManifest(): {}return {commit: stringValue(obj['sourceFingerprint']) || stringValue(obj['commit']),- product: stringValue(obj['product']),+ services: stringValue(obj['services']),components}} catch {- return { commit: '', product: '', components: {} }+ return { commit: '', services: '', components: {} }}}/**- * Read the build provenance (`commit` + `product`) that+ * Read the build provenance (`commit` + `services`) that* `scripts/build-modular-binaries.ts` stamps into `cli-bin/manifest.json`. Used* for diagnostics only; returns empty strings when the manifest is absent.*/-function readCliBinManifestInfo(): { commit: string; product: string } {- const { commit, product } = readCliBinManifest()- return { commit, product }+function readCliBinManifestInfo(): { commit: string; services: string } {+ const { commit, services } = readCliBinManifest()+ return { commit, services }}function objectValue(value: JsonValue | undefined): JsonObject | null {@@ -480,7 +480,7 @@ class ModularSupervisor {mode: app.isPackaged ? 'packaged' : 'dev',binDir,modularCommit: manifestInfo.commit,- modularProduct: manifestInfo.product,+ modularServices: manifestInfo.services,resourcesPath: process.resourcesPath,appPath: app.getAppPath()}diff --git a/desktop/src/shared/types/ipc-channels.ts b/desktop/src/shared/types/ipc-channels.tsindex 289319d..ff9c03d 100644--- a/desktop/src/shared/types/ipc-channels.ts+++ b/desktop/src/shared/types/ipc-channels.ts@@ -46,7 +46,7 @@ export interface ServiceStatus {*/export interface ServiceVersions {appVersion: string- modularProduct: string+ modularServices: stringbinaries: { name: string; version: string }[]/** SPDX-ish id parsed at runtime from the shipped LICENSE; '' if unavailable. */licenseType: stringdiff --git a/desktop/src/ui/components/ServiceSettings/VersionsCard.tsx b/desktop/src/ui/components/ServiceSettings/VersionsCard.tsxindex 6319541..8e571d9 100644--- a/desktop/src/ui/components/ServiceSettings/VersionsCard.tsx+++ b/desktop/src/ui/components/ServiceSettings/VersionsCard.tsx@@ -79,8 +79,8 @@ export default function VersionsCard() {<Stack gap="2"><Stack gap="2"><VersionRow label="Application" value={appVersion} />- {versions?.modularProduct && (- <VersionRow label="Services" value={versions.modularProduct} />+ {versions?.modularServices && (+ <VersionRow label="Services" value={versions.modularServices} />)}</Stack>diff --git a/scripts/release-intent/README.md b/scripts/release-intent/README.mdnew file mode 100644index 0000000..ce99e76--- /dev/null+++ b/scripts/release-intent/README.md@@ -0,0 +1,141 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++# Release-intent automation++Contributors declare version bumps and changelog text in the+`pair-release-intent:v1` block in a pull request description. CI validates the+block on the pull request, and after the merge lands on `develop` a bot applies+it to the version files.++SemVer meaning for each number lives in [`services/VERSIONING.md`](../../services/VERSIONING.md).++## Scripts++| Script | When | Needs a credential |+| ------ | ---- | ------------------ |+| `validate_pr.py` | Pull requests (`release-intent-check.yml`) | No |+| `apply_pr.py` | Push to `develop` (`release-intent-apply.yml`) | Yes |+| `lib.py` | Shared parse / bump / render | — |+| `test_lib.py` | Offline unit checks, also run in CI | — |++`validate_pr.py` needs no credential on purpose: the body arrives in the webhook+payload, so there is nothing to fetch. That is what lets it run on pull requests+from forks like every other check.++The check has its own workflow rather than living in `ci.yml` so it can also+trigger on the `edited` pull request type. A body can change after checks go+green, and apply reads the live body at merge time; validating only on the+default types would leave a window where the applied bumps are not the ones CI+enforced. Putting `edited` on `ci.yml` would rebuild six installers for a typo+fix in a description.++## Key policy++How hard each entry point is about the block's key set not matching+`versions.json`:++| Caller | Policy | Unknown key | Missing key |+| ------ | ------ | ----------- | ----------- |+| `validate_pr.py` | `strict` | fails | fails |+| `apply_pr.py` | `reject-unknown` | fails | warns, treated as `none` |++Apply rejects an unknown key because that means the block was edited into a+state a pull request check would have refused. It tolerates a missing key+because that is the legitimate case of a concurrent pull request adding a+component after this one was written, and reading it as `none` is what the+author meant. Full strictness there would fail the apply job on `develop` for+an ordering accident nobody did wrong.++## What apply writes++Three files, in **one** commit built through the git data API:++- `desktop/package.json` — the release version, one PATCH forward+- `services/versions.json` — the declared `services` and component bumps+- `CHANGELOG.md` — a new section titled with the new release version, citing+ the pull request number++The contents API would be one commit per file, which means a release landing in+pieces and a window where the changelog names a version `package.json` does not+yet carry. Moving the ref once avoids that, and a rejected fast-forward is the+concurrency check — the script retries that and only that, up to three times.++## Known limits++**One apply per push.** `apply_pr.py` resolves the pull request for the push's+head commit only. A push carrying two merges — a direct push of a range, or a+merge-queue batch — applies the head commit's intent and **silently skips the+others**. Nothing fails. `develop` must therefore take one merge per push: no+merge queue batching, and no pushing a range of merge commits directly. Lifting+this means iterating the push's commits rather than reading only the head.++**No concurrency group on the apply workflow, on purpose.** GitHub keeps a+single pending run per group and cancels any earlier one, so under a burst of+merges a group would drop bumps rather than serialize them. Ordering is handled+in the script instead, by committing with `force: false` and re-reading the ref+when the branch moved. Do not add one.++**`### ` inside a changelog body truncates it.** `_parse_section` ends a section+at the next line beginning with `### `, so a body containing a literal `### `+line is silently cut at that point. Keep changelog bodies to prose and bullets.++**The gate assumes branch protection.** `develop` should require the+`Release intent check` status check. An admin merge that bypasses it with an+invalid block fails at apply with exit 1, loudly, but the versions simply do not+bump until someone fixes the body and re-runs.++## Idempotency++Each bot commit carries an `Applies-PR: #N` trailer, and every attempt scans the+branch's recent commits for it first, so a re-run after a successful apply is a+no-op. A commit whose message already starts with `[release-intent]` is skipped+outright, so the bot never reacts to itself.++## Credential++`apply_pr.py` authenticates with a GitHub App installation token, minted per run+and expiring in an hour.++- **Grant `contents: write` and nothing else.** In particular do **not** grant+ the Workflows permission: without it the token cannot modify+ `.github/workflows`, so a compromise of this job cannot rewrite the pipeline.+- Add the app as a bypass actor on `develop`, the only branch it writes.+- Configure `RELEASE_INTENT_APP_ID` as a repository variable and+ `RELEASE_INTENT_APP_PRIVATE_KEY` as a secret.++**The app and both settings must exist before the first push to `develop`.**+If the credential is missing, `apply_pr.py` exits 2 and says so rather than+silently skipping the bump. Backfill by re-running the job once it is configured,+or apply from a saved body locally.++## Bot-owned files++`services/versions.json` and `CHANGELOG.md` are written only by the bot;+`validate_pr.py` rejects a pull request that edits them. Override with+`<!-- pair-release-intent-allow-owned-files -->` in the description when adding+or removing a component key, which the bot cannot invent.++`desktop/package.json` is deliberately **not** on that list even though the bot+writes its `version`: dependency work touches the file constantly, and the check+is path-granular, so listing it would block ordinary pull requests.++## Local checks++```bash+python3 scripts/release-intent/test_lib.py++python3 scripts/release-intent/validate_pr.py \+ --description-file /path/to/body.md \+ --skip-owned-files-check++python3 scripts/release-intent/apply_pr.py \+ --description-file /path/to/body.md \+ --dry-run+```++`--dry-run` **writes the working tree** despite the name. Restore afterwards:++```bash+git restore desktop/package.json services/versions.json CHANGELOG.md+```diff --git a/scripts/release-intent/apply_pr.py b/scripts/release-intent/apply_pr.pynew file mode 100644index 0000000..759ac27--- /dev/null+++ b/scripts/release-intent/apply_pr.py@@ -0,0 +1,422 @@+#!/usr/bin/env python3+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0+"""Apply a merged pull request's release-intent block to the version files.++Writes three files in ONE commit via the git data API: desktop/package.json+(the release version, patch-bumped), services/versions.json (declared services+and component bumps), and CHANGELOG.md (a new section).++The contents API would be one commit per file, which for three files means a+release landing in pieces and a window where the changelog names a version that+package.json does not yet carry. Building a tree and moving the ref once avoids+that, and the ref update doubles as the concurrency check: a non-fast-forward+means the branch moved underneath us, which is the only condition worth+retrying.+"""++from __future__ import annotations++import argparse+import base64+import json+import os+import subprocess+import sys+import urllib.error+import urllib.parse+import urllib.request+from dataclasses import dataclass+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parent))++from lib import ( # noqa: E402+ BOT_COMMIT_PREFIX,+ CHANGELOG_PATH,+ PACKAGE_JSON_PATH,+ REPO_ROOT,+ VERSIONS_PATH,+ apply_bumps,+ applies_pr_trailer,+ bump_semver,+ format_changelog_entry,+ load_versions,+ parse_release_intent,+ parse_versions,+ prepend_changelog,+ read_release_version,+ render_package_json,+ render_versions_json,+)++VERSIONS_REPO_PATH = str(VERSIONS_PATH.relative_to(REPO_ROOT))+CHANGELOG_REPO_PATH = str(CHANGELOG_PATH.relative_to(REPO_ROOT))+PACKAGE_REPO_PATH = str(PACKAGE_JSON_PATH.relative_to(REPO_ROOT))++BLOB_MODE = '100644'+++@dataclass(frozen=True)+class ReleaseUpdate:+ """The three file bodies a release intent produces, and what to call it."""++ package: str+ versions: str+ changelog: str+ release: str++ def as_paths(self) -> dict[str, str]:+ return {+ PACKAGE_REPO_PATH: self.package,+ VERSIONS_REPO_PATH: self.versions,+ CHANGELOG_REPO_PATH: self.changelog,+ }+++def _api_base() -> str:+ return os.environ.get('GITHUB_API_URL', 'https://api.github.com').rstrip('/')+++def _headers(token: str) -> dict[str, str]:+ return {+ 'Authorization': f'Bearer {token}',+ 'Accept': 'application/vnd.github+json',+ 'X-GitHub-Api-Version': '2022-11-28',+ }+++def _request(+ method: str, url: str, token: str, payload: dict[str, object] | None = None+) -> tuple[int, object]:+ data = json.dumps(payload).encode('utf-8') if payload is not None else None+ headers = _headers(token)+ if data is not None:+ headers['Content-Type'] = 'application/json'+ request = urllib.request.Request(url, data=data, headers=headers, method=method)+ try:+ with urllib.request.urlopen(request, timeout=60) as response:+ body = response.read().decode('utf-8')+ return response.status, (json.loads(body) if body else {})+ except urllib.error.HTTPError as exc:+ raw = exc.read().decode('utf-8', errors='replace')+ try:+ return exc.code, json.loads(raw)+ except json.JSONDecodeError:+ return exc.code, raw+++def _get(url: str, token: str) -> object:+ status, body = _request('GET', url, token)+ if status != 200:+ raise SystemExit(f'GitHub API HTTP {status} for {url}: {body}')+ return body+++def _post(url: str, token: str, payload: dict[str, object]) -> tuple[int, object]:+ return _request('POST', url, token, payload)+++def current_commit_message() -> str:+ return subprocess.run(+ ['git', 'log', '-1', '--pretty=%B'],+ cwd=REPO_ROOT,+ check=True,+ capture_output=True,+ text=True,+ ).stdout+++def fetch_merged_pr(repo: str, sha: str, token: str) -> tuple[str, str] | None:+ """The pull request that brought `sha` to the branch, as (number, body).++ GitHub's commits/{sha}/pulls is the direct analogue of GitLab's+ commits/{sha}/merge_requests.+ """+ url = f'{_api_base()}/repos/{repo}/commits/{urllib.parse.quote(sha)}/pulls'+ payload = _get(url, token)+ if not isinstance(payload, list) or not payload:+ return None+ chosen: dict[str, object] | None = None+ for item in payload:+ if isinstance(item, dict) and item.get('merged_at'):+ chosen = item+ break+ if chosen is None and isinstance(payload[0], dict):+ chosen = payload[0]+ if chosen is None:+ return None+ number = chosen.get('number')+ body = chosen.get('body')+ if not isinstance(number, int):+ return None+ # A pull request with an empty body has body: null.+ return (str(number), body if isinstance(body, str) else '')+++def compute_release_update(+ package_text: str,+ versions_text: str,+ changelog_text: str,+ description: str,+ pr_ref: str,+) -> ReleaseUpdate | None:+ """Apply the intent to three file bodies. None when nothing changes."""+ versions, raw = parse_versions(versions_text, VERSIONS_REPO_PATH)+ intent = parse_release_intent(+ description, versions.bump_keys, key_policy='reject-unknown'+ )+ if not intent.has_release:+ return None++ updated = apply_bumps(versions, intent)+ release_before = read_release_version(package_text, PACKAGE_REPO_PATH)+ # The release version is never declared: any release is one patch forward.+ release_after = bump_semver(release_before, 'patch')++ print(f'Applying release {release_before} → {release_after}')+ if updated.services != versions.services:+ print(f' services: {versions.services} → {updated.services}')+ for name in sorted(versions.components):+ before, after = versions.components[name], updated.components[name]+ if before != after:+ print(f' {name}: {before} → {after}')++ entry = format_changelog_entry(+ release_after, intent.changelog_title, intent.changelog_body, pr_ref+ )+ return ReleaseUpdate(+ package=render_package_json(package_text, release_after),+ versions=render_versions_json(updated, raw),+ changelog=prepend_changelog(changelog_text, entry),+ release=release_after,+ )+++def read_file_at(repo: str, token: str, path: str, ref: str) -> str:+ url = (+ f'{_api_base()}/repos/{repo}/contents/{urllib.parse.quote(path)}'+ f'?ref={urllib.parse.quote(ref)}'+ )+ payload = _get(url, token)+ if not isinstance(payload, dict):+ raise SystemExit(f'Unexpected payload reading {path} at {ref}')+ content = payload.get('content')+ if not isinstance(content, str):+ raise SystemExit(f'Incomplete payload reading {path} at {ref}')+ return base64.b64decode(content).decode('utf-8')+++def branch_has_trailer(repo: str, token: str, branch: str, trailer: str) -> bool:+ url = (+ f'{_api_base()}/repos/{repo}/commits'+ f'?sha={urllib.parse.quote(branch)}&per_page=50'+ )+ payload = _get(url, token)+ if not isinstance(payload, list):+ return False+ for item in payload:+ if not isinstance(item, dict):+ continue+ commit = item.get('commit')+ if isinstance(commit, dict) and trailer in str(commit.get('message', '')):+ return True+ return False+++def commit_tree(+ repo: str, token: str, branch: str, head: str, message: str, files: dict[str, str]+) -> tuple[bool, object]:+ """Commit every file at once and move the branch. Returns (stale, detail)."""+ head_commit = _get(f'{_api_base()}/repos/{repo}/git/commits/{head}', token)+ if not isinstance(head_commit, dict):+ raise SystemExit(f'Unexpected payload for commit {head}')+ tree_info = head_commit.get('tree')+ if not isinstance(tree_info, dict) or not isinstance(tree_info.get('sha'), str):+ raise SystemExit(f'Commit {head} has no tree sha')++ entries: list[dict[str, object]] = []+ for path, content in files.items():+ status, blob = _post(+ f'{_api_base()}/repos/{repo}/git/blobs',+ token,+ {'content': content, 'encoding': 'utf-8'},+ )+ if status != 201 or not isinstance(blob, dict):+ raise SystemExit(f'Could not create a blob for {path}: HTTP {status} {blob}')+ entries.append(+ {'path': path, 'mode': BLOB_MODE, 'type': 'blob', 'sha': blob.get('sha')}+ )++ status, tree = _post(+ f'{_api_base()}/repos/{repo}/git/trees',+ token,+ {'base_tree': tree_info['sha'], 'tree': entries},+ )+ if status != 201 or not isinstance(tree, dict):+ raise SystemExit(f'Could not create a tree: HTTP {status} {tree}')++ status, commit = _post(+ f'{_api_base()}/repos/{repo}/git/commits',+ token,+ {'message': message, 'tree': tree.get('sha'), 'parents': [head]},+ )+ if status != 201 or not isinstance(commit, dict):+ raise SystemExit(f'Could not create a commit: HTTP {status} {commit}')++ status, detail = _request(+ 'PATCH',+ f'{_api_base()}/repos/{repo}/git/refs/heads/{urllib.parse.quote(branch)}',+ token,+ {'sha': commit.get('sha'), 'force': False},+ )+ if status == 200:+ print(f'Committed {BOT_COMMIT_PREFIX} to {branch}')+ return False, detail+ # A rejected fast-forward means the branch moved while we were building.+ if status in (409, 422):+ return True, detail+ raise SystemExit(+ f'GitHub refused the release-intent commit on {branch} with HTTP {status}: '+ f'{detail}\nCheck that the app is a bypass actor for {branch} and holds '+ 'contents: write.'+ )+++def apply_release(+ message: str, description: str, trailer: str, pr_ref: str, dry_run: bool+) -> None:+ if dry_run:+ update = compute_release_update(+ PACKAGE_JSON_PATH.read_text(encoding='utf-8'),+ VERSIONS_PATH.read_text(encoding='utf-8'),+ CHANGELOG_PATH.read_text(encoding='utf-8'),+ description,+ pr_ref,+ )+ if update is None:+ print('Dry-run: nothing to apply')+ return+ PACKAGE_JSON_PATH.write_text(update.package, encoding='utf-8')+ VERSIONS_PATH.write_text(update.versions, encoding='utf-8')+ CHANGELOG_PATH.write_text(update.changelog, encoding='utf-8')+ print(+ 'Dry-run MODIFIED the working tree (package.json, versions.json, '+ 'CHANGELOG.md). Restore with: git restore '+ f'{PACKAGE_REPO_PATH} {VERSIONS_REPO_PATH} {CHANGELOG_REPO_PATH}'+ )+ print(message)+ return++ token = os.environ.get('RELEASE_INTENT_TOKEN')+ repo = os.environ.get('GITHUB_REPOSITORY')+ branch = os.environ.get('GITHUB_REF_NAME')+ if not token:+ raise SystemExit('RELEASE_INTENT_TOKEN is required to apply release-intent')+ if not repo or not branch:+ raise SystemExit('GITHUB_REPOSITORY and GITHUB_REF_NAME are required to apply')++ for attempt in range(1, 4):+ if trailer and branch_has_trailer(repo, token, branch, trailer):+ print(f'{trailer} is already on {branch}; nothing to do')+ return++ ref = _get(+ f'{_api_base()}/repos/{repo}/git/ref/heads/{urllib.parse.quote(branch)}',+ token,+ )+ if not isinstance(ref, dict) or not isinstance(ref.get('object'), dict):+ raise SystemExit(f'Could not read the {branch} ref')+ head = ref['object'].get('sha')+ if not isinstance(head, str):+ raise SystemExit(f'Could not read the {branch} head sha')++ update = compute_release_update(+ read_file_at(repo, token, PACKAGE_REPO_PATH, head),+ read_file_at(repo, token, VERSIONS_REPO_PATH, head),+ read_file_at(repo, token, CHANGELOG_REPO_PATH, head),+ description,+ pr_ref,+ )+ if update is None:+ print(f'Already applied on current {branch}; nothing to do')+ return++ stale, detail = commit_tree(+ repo, token, branch, head, message, update.as_paths()+ )+ if not stale:+ return+ print(f'{branch} advanced during attempt {attempt}; retrying\n{detail}')++ raise SystemExit('Could not apply release intent after 3 attempts')+++def main() -> int:+ # Without this, buffered progress output reaches the job log after the+ # failure written to stderr, which reads as though it happened first.+ sys.stdout.reconfigure(line_buffering=True)++ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument('--description-file', type=Path)+ parser.add_argument('--dry-run', action='store_true')+ parser.add_argument(+ '--sha',+ default=os.environ.get('GITHUB_SHA', ''),+ help='Commit SHA whose merged pull request body should be applied',+ )+ args = parser.parse_args()++ message = current_commit_message()+ if message.lstrip().startswith(BOT_COMMIT_PREFIX):+ print(f'Skipping: commit already starts with {BOT_COMMIT_PREFIX}')+ return 0++ if args.description_file is not None:+ description = args.description_file.read_text(encoding='utf-8')+ pr_ref = ''+ else:+ token = os.environ.get('RELEASE_INTENT_TOKEN')+ repo = os.environ.get('GITHUB_REPOSITORY')+ if not token or not repo:+ print(+ 'RELEASE_INTENT_TOKEN is not configured, so this release intent '+ 'was NOT applied. Record the merged pull request body for '+ 'backfill (see scripts/release-intent/README.md).',+ file=sys.stderr,+ )+ return 2+ if not args.sha:+ raise SystemExit('--sha or GITHUB_SHA is required')+ found = fetch_merged_pr(repo, args.sha, token)+ if found is None:+ print('No pull request associated with this commit; nothing to apply')+ return 0+ pr_ref, description = found++ try:+ versions, _raw = load_versions()+ intent = parse_release_intent(+ description, versions.bump_keys, key_policy='reject-unknown'+ )+ except ValueError as exc:+ print('release-intent parse failed on merged pull request:', file=sys.stderr)+ print(str(exc), file=sys.stderr)+ return 1++ if not intent.has_release:+ label = f'PR #{pr_ref}' if pr_ref else 'this body'+ print(f'{label}: all bumps none — no version files to update')+ return 0++ trailer = applies_pr_trailer(pr_ref) if pr_ref else ''+ suffix = f' after PR #{pr_ref}' if pr_ref else ''+ commit_message = f'{BOT_COMMIT_PREFIX} bump release{suffix}\n\n'+ if trailer:+ commit_message += f'Apply release intent from PR #{pr_ref}.\n\n{trailer}\n'+ apply_release(commit_message, description, trailer, pr_ref, dry_run=args.dry_run)+ return 0+++if __name__ == '__main__':+ raise SystemExit(main())diff --git a/scripts/release-intent/lib.py b/scripts/release-intent/lib.pynew file mode 100644index 0000000..9eaf5d7--- /dev/null+++ b/scripts/release-intent/lib.py@@ -0,0 +1,409 @@+#!/usr/bin/env python3+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0+"""Parse and validate PAIR pull request release-intent blocks (v1).++Three numbers, each with one job:++- the **release** version in `desktop/package.json`, which is what users+ install. It is never declared in an intent block: it patch-bumps+ automatically whenever an intent declares a release, and a minor or major+ release is a deliberate manual bump at cut time.+- **services** in `services/versions.json`, the services suite version that+ stamps the standalone installer and Go `main.Version`.+- **components.\\*** in `services/versions.json`, per-binary SemVer.++Only the last two are declared, because only they carry SemVer meaning that a+human has to judge.+"""++from __future__ import annotations++import json+import re+from dataclasses import dataclass+from pathlib import Path+from typing import Any, Literal++BumpKind = Literal['none', 'patch', 'minor', 'major']+BUMP_KINDS: tuple[BumpKind, ...] = ('none', 'patch', 'minor', 'major')+BUMP_RANK: dict[BumpKind, int] = {'none': 0, 'patch': 1, 'minor': 2, 'major': 3}++# How hard to be about the block's key set not matching versions.json.+#+# - 'strict' — any mismatch fails. Used on pull requests, where a typo+# should be corrected rather than silently absorbed.+# - 'reject-unknown' — an unknown key fails; a missing key warns and is treated+# as none. Used when applying. An unknown key means the+# block was edited to something a pull request check would+# have rejected, which is worth failing on. A *missing* key+# is the legitimate case of a concurrent pull request having+# added a component since this one was written, and reading+# it as none is what its author meant.+# - 'lenient' — both warn. Local inspection only.+KeyPolicy = Literal['strict', 'reject-unknown', 'lenient']++INTENT_VERSION = 'v1'+# Canonical forms (template / docs). Parsers also accept HTML comments with+# optional internal whitespace — GitLab often collapses `<!-- foo -->` to+# `<!--foo-->` when the description is saved or re-rendered.+INTENT_START = f'<!-- pair-release-intent:{INTENT_VERSION} -->'+INTENT_END = f'<!-- /pair-release-intent:{INTENT_VERSION} -->'+ALLOW_OWNED_FILES_MARKER = '<!-- pair-release-intent-allow-owned-files -->'+_INTENT_START_RE = re.compile(+ rf'<!--\s*pair-release-intent:{re.escape(INTENT_VERSION)}\s*-->'+)+_INTENT_END_RE = re.compile(+ rf'<!--\s*/pair-release-intent:{re.escape(INTENT_VERSION)}\s*-->'+)+_ALLOW_OWNED_FILES_RE = re.compile(+ r'<!--\s*pair-release-intent-allow-owned-files\s*-->'+)++BOT_COMMIT_PREFIX = '[release-intent]'+APPLIES_PR_TRAILER_PREFIX = 'Applies-PR: #'++# Path-granular, and check_forbidden_paths rejects any edit to a listed file.+# desktop/package.json is deliberately absent even though the bot writes its+# `version`: dependency work touches that file constantly, so listing it would+# block ordinary pull requests.+BOT_OWNED_MODIFY_PATHS = (+ 'services/versions.json',+ 'CHANGELOG.md',+)+SERVICES_CHANGELOG_PATH = 'services/changelog.md'++REPO_ROOT = Path(__file__).resolve().parents[2]+VERSIONS_PATH = REPO_ROOT / 'services' / 'versions.json'+CHANGELOG_PATH = REPO_ROOT / 'CHANGELOG.md'+PACKAGE_JSON_PATH = REPO_ROOT / 'desktop' / 'package.json'++VERSIONS_COMMENT = (+ 'Single source of truth for all version numbers. See VERSIONING.md for bump rules.'+)+++@dataclass(frozen=True)+class ReleaseIntent:+ changelog_title: str+ changelog_body: str+ bumps: dict[str, BumpKind]++ @property+ def has_release(self) -> bool:+ return any(kind != 'none' for kind in self.bumps.values())+++@dataclass(frozen=True)+class VersionsManifest:+ services: str+ components: dict[str, str]++ @property+ def bump_keys(self) -> list[str]:+ return ['services', *sorted(self.components)]+++def parse_versions(text: str, source: str) -> tuple[VersionsManifest, dict[str, Any]]:+ """Parse a versions manifest. `source` names it in errors."""+ raw_obj: Any = json.loads(text)+ if not isinstance(raw_obj, dict):+ raise ValueError(f'{source}: top-level value must be a JSON object')+ raw: dict[str, Any] = raw_obj+ components_raw = raw.get('components')+ if not isinstance(components_raw, dict) or not components_raw:+ raise ValueError(f'{source}: missing non-empty components object')+ components: dict[str, str] = {}+ for key, value in components_raw.items():+ if not isinstance(key, str) or not isinstance(value, str):+ raise ValueError(f'{source}: component entries must be string→string')+ components[key] = value+ services = raw.get('services')+ if not isinstance(services, str) or not services:+ raise ValueError(f'{source}: services must be a non-empty string')+ return (VersionsManifest(services=services, components=components), raw)+++def read_release_version(text: str, source: str) -> str:+ """The release version from a desktop/package.json body."""+ raw: Any = json.loads(text)+ if not isinstance(raw, dict):+ raise ValueError(f'{source}: top-level value must be a JSON object')+ version = raw.get('version')+ if not isinstance(version, str) or not version:+ raise ValueError(f'{source}: version must be a non-empty string')+ return version+++def load_release_version(path: Path = PACKAGE_JSON_PATH) -> str:+ return read_release_version(path.read_text(encoding='utf-8'), str(path))+++_PACKAGE_VERSION_RE = re.compile(r'^(?P<lead>\s*"version"\s*:\s*")[^"]*(?P<tail>")', re.M)+++def render_package_json(text: str, version: str) -> str:+ """Replace only the version value, leaving the rest byte-for-byte intact.++ desktop/package.json is hand-maintained, so it is rewritten surgically+ rather than re-serialized: a json.dumps round trip would reformat the whole+ file and bury the one-line bump in an unreviewable diff.+ """+ replaced, count = _PACKAGE_VERSION_RE.subn(+ lambda m: f'{m.group("lead")}{version}{m.group("tail")}', text, count=1+ )+ if count != 1:+ raise ValueError('Could not locate a single "version" field in package.json')+ return replaced+++def load_versions(path: Path = VERSIONS_PATH) -> tuple[VersionsManifest, dict[str, Any]]:+ return parse_versions(path.read_text(encoding='utf-8'), str(path))+++def extract_intent_block(description: str) -> str:+ start_match = _INTENT_START_RE.search(description)+ end_match = _INTENT_END_RE.search(description)+ if (+ start_match is None+ or end_match is None+ or end_match.start() <= start_match.start()+ ):+ raise ValueError(+ 'Pull request body is missing the exact release-intent fences:\n'+ f' {INTENT_START}\n'+ f' ...\n'+ f' {INTENT_END}\n'+ 'Copy them from the pull request template and fill them in.'+ )+ return description[start_match.end() : end_match.start()]+++def _parse_section(inner: str, heading: str) -> str:+ pattern = rf'(?m)^### {re.escape(heading)}\s*\n(.*?)(?=^### |\Z)'+ match = re.search(pattern, inner, flags=re.S)+ if not match:+ raise ValueError(f'Missing required section heading: ### {heading}')+ kept = [+ line+ for line in match.group(1).splitlines()+ if not _is_ignorable_line(line.strip())+ ]+ return '\n'.join(kept).strip()+++def _parse_bump_kind(key: str, value: str) -> BumpKind:+ for kind in BUMP_KINDS:+ if value == kind:+ return kind+ raise ValueError(f'{key}: expected one of {", ".join(BUMP_KINDS)}, got {value!r}')+++def _is_ignorable_line(line: str) -> bool:+ return line.startswith('#') or (line.startswith('<!--') and line.endswith('-->'))+++def _strip_bump_line(line: str) -> str:+ if line.startswith(('- ', '* ')):+ return line[2:].strip()+ return line+++def _parse_bumps(+ section: str,+ expected_keys: list[str],+ *,+ key_policy: KeyPolicy,+) -> dict[str, BumpKind]:+ lines = [+ _strip_bump_line(line.strip())+ for line in section.splitlines()+ if line.strip() and not _is_ignorable_line(line.strip())+ ]+ if not lines:+ raise ValueError('### Bumps section is empty')++ parsed: dict[str, BumpKind] = {}+ for line in lines:+ if ':' not in line:+ raise ValueError(+ f'Bump line must be "- key: none|patch|minor|major", got: {line!r}'+ )+ key, value = line.split(':', 1)+ key = key.strip()+ value = value.strip().lower()+ if key in parsed:+ raise ValueError(f'Duplicate bump key: {key}')+ kind = _parse_bump_kind(key, value)+ parsed[key] = kind++ expected = set(expected_keys)+ got = set(parsed)+ missing = sorted(expected - got)+ extra = sorted(got - expected)+ if missing or extra:+ fatal_missing = missing if key_policy == 'strict' else []+ fatal_extra = extra if key_policy in ('strict', 'reject-unknown') else []+ if fatal_missing or fatal_extra:+ parts: list[str] = []+ if fatal_missing:+ parts.append('missing keys: ' + ', '.join(fatal_missing))+ if fatal_extra:+ parts.append('unknown keys: ' + ', '.join(fatal_extra))+ raise ValueError(+ 'Bump keys must match services/versions.json exactly ('+ + '; '.join(parts)+ + ')'+ )+ for key in missing:+ print(+ f'warning: {key} absent from the intent block; treating as none',+ flush=True,+ )+ for key in extra:+ print(+ f'warning: ignoring unknown bump key {key} (not in versions.json)',+ flush=True,+ )+ return {key: parsed.get(key, 'none') for key in expected_keys}+ return {key: parsed[key] for key in expected_keys}+++def _is_na(text: str) -> bool:+ return text.strip().lower() == 'n/a'+++def parse_release_intent(+ description: str,+ expected_bump_keys: list[str],+ *,+ key_policy: KeyPolicy = 'strict',+) -> ReleaseIntent:+ inner = extract_intent_block(description)+ title = _parse_section(inner, 'Changelog title')+ body = _parse_section(inner, 'Changelog body')+ bumps = _parse_bumps(+ _parse_section(inner, 'Bumps'),+ expected_bump_keys,+ key_policy=key_policy,+ )++ if not title:+ raise ValueError('Changelog title must be non-empty (use n/a when there is no release)')+ if not body:+ raise ValueError('Changelog body must be non-empty (use n/a when there is no release)')++ component_keys = [key for key in expected_bump_keys if key != 'services']+ max_component = max((BUMP_RANK[bumps[key]] for key in component_keys), default=0)+ services_rank = BUMP_RANK[bumps['services']]++ if max_component > 0 and services_rank == 0:+ raise ValueError(+ 'services must be patch|minor|major when any component bump is not none'+ )+ if services_rank < max_component:+ raise ValueError(+ 'services bump severity must be >= the highest component bump '+ f'(services={bumps["services"]}, highest component rank requires >= '+ f'{next(k for k, r in BUMP_RANK.items() if r == max_component)})'+ )++ has_release = services_rank > 0 or max_component > 0+ if has_release:+ if _is_na(title) or _is_na(body):+ raise ValueError(+ 'Changelog title and body are required when any bump is not none '+ '(do not use n/a)'+ )+ else:+ if not _is_na(title) or not _is_na(body):+ raise ValueError(+ 'When every bump is none, Changelog title and body must both be exactly n/a'+ )++ return ReleaseIntent(changelog_title=title, changelog_body=body, bumps=bumps)+++def allows_owned_file_edits(description: str) -> bool:+ return _ALLOW_OWNED_FILES_RE.search(description) is not None+++def bump_semver(version: str, kind: BumpKind) -> str:+ if kind == 'none':+ return version+ parts = version.split('.')+ if len(parts) != 3 or not all(part.isdigit() for part in parts):+ raise ValueError(f'Version must be MAJOR.MINOR.PATCH, got {version!r}')+ major, minor, patch = (int(parts[0]), int(parts[1]), int(parts[2]))+ if kind == 'major':+ return f'{major + 1}.0.0'+ if kind == 'minor':+ return f'{major}.{minor + 1}.0'+ return f'{major}.{minor}.{patch + 1}'+++def apply_bumps(manifest: VersionsManifest, intent: ReleaseIntent) -> VersionsManifest:+ services = bump_semver(manifest.services, intent.bumps['services'])+ components = {+ name: bump_semver(version, intent.bumps[name])+ for name, version in manifest.components.items()+ }+ return VersionsManifest(services=services, components=components)+++def render_versions_json(manifest: VersionsManifest, original: dict[str, Any]) -> str:+ doc = dict(original)+ doc.pop('product', None)+ doc.pop('installer', None)+ doc['$comment'] = VERSIONS_COMMENT+ doc['services'] = manifest.services+ doc['components'] = dict(manifest.components)+ return json.dumps(doc, indent=2, ensure_ascii=False) + '\n'+++def format_changelog_entry(+ release_version: str, title: str, body: str, pr_ref: str+) -> str:+ """One changelog section. `pr_ref` is cited so an entry traces to its PR."""+ bullets = '\n'.join(+ line+ if line.lstrip().startswith(('-', '*'))+ else f'- {line}'+ for line in body.strip().splitlines()+ if line.strip()+ )+ suffix = f' (#{pr_ref})' if pr_ref else ''+ return f'## {release_version} — {title.strip()}{suffix}\n\n{bullets}\n'+++def prepend_changelog(existing: str, entry: str) -> str:+ match = re.search(r'(?m)^## ', existing)+ if not match:+ raise ValueError('CHANGELOG.md has no ## release headings to prepend before')+ insert_at = match.start()+ return existing[:insert_at] + entry + '\n' + existing[insert_at:]+++def applies_pr_trailer(pr_number: str) -> str:+ return f'{APPLIES_PR_TRAILER_PREFIX}{pr_number}'+++def check_forbidden_paths(changed_name_status: list[tuple[str, str]], description: str) -> None:+ if allows_owned_file_edits(description):+ return++ errors: list[str] = []+ for status, path in changed_name_status:+ status = status.upper()+ if path in BOT_OWNED_MODIFY_PATHS and status != 'D':+ errors.append(+ f'{path} is bot-owned; do not modify it in a pull request '+ f'(declare bumps in the release-intent block instead)'+ )+ if path == SERVICES_CHANGELOG_PATH and status != 'D':+ errors.append(+ f'{path} is retired; delete it if present, do not add or edit it. '+ 'Product notes go in root CHANGELOG.md via the release-intent bot.'+ )+ if errors:+ raise ValueError('Forbidden path changes:\n- ' + '\n- '.join(errors))diff --git a/scripts/release-intent/test_lib.py b/scripts/release-intent/test_lib.pynew file mode 100644index 0000000..664b775--- /dev/null+++ b/scripts/release-intent/test_lib.py@@ -0,0 +1,335 @@+#!/usr/bin/env python3+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0+"""Offline unit checks for ci/release-intent/lib.py."""++from __future__ import annotations++import json+import sys+import tempfile+import unittest+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parent))++from lib import ( # noqa: E402+ ALLOW_OWNED_FILES_MARKER,+ INTENT_END,+ INTENT_START,+ VERSIONS_PATH,+ VersionsManifest,+ apply_bumps,+ bump_semver,+ check_forbidden_paths,+ format_changelog_entry,+ load_versions,+ parse_release_intent,+ prepend_changelog,+ read_release_version,+ render_package_json,+ render_versions_json,+)++KEYS = [+ 'services',+ 'lmstudio-proxy',+ 'nvpair-cluster-manager',+ 'nvpair-engine-manager',+ 'nvpair-errors',+ 'nvpair-job-scheduler',+ 'nvpair-manual-nodes',+ 'nvpair-node-info',+ 'nvpair-node-scanner',+ 'nvpair-node-settings',+ 'nvpair-tui',+ 'nvpair-ui-broker',+ 'nvpair-workload-manager',+ 'ollama-proxy',+]+++def _block(title: str, body: str, bumps: dict[str, str], *, bullets: bool = True) -> str:+ if bullets:+ bump_lines = '\n'.join(f'- {key}: {bumps[key]}' for key in KEYS)+ else:+ bump_lines = '\n'.join(f'{key}: {bumps[key]}' for key in KEYS)+ return (+ f'{INTENT_START}\n'+ f'### Changelog title\n{title}\n\n'+ f'### Changelog body\n{body}\n\n'+ f'### Bumps\n{bump_lines}\n'+ f'{INTENT_END}\n'+ )+++class ReleaseVersionTests(unittest.TestCase):+ """The release version is read from desktop/package.json and patch-bumped.++ It is never declared in an intent block, so the only judgement a human makes+ is the services and component severity.+ """++ PACKAGE = '{\n "name": "pair",\n "version": "0.1.1",\n "private": true\n}\n'++ def test_read_release_version(self) -> None:+ self.assertEqual(read_release_version(self.PACKAGE, 'pkg'), '0.1.1')++ def test_release_patch_bump(self) -> None:+ self.assertEqual(bump_semver('0.1.1', 'patch'), '0.1.2')+ self.assertEqual(bump_semver('0.1.9', 'patch'), '0.1.10')++ def test_render_package_json_touches_only_the_version(self) -> None:+ rendered = render_package_json(self.PACKAGE, '0.1.2')+ self.assertIn('"version": "0.1.2"', rendered)+ # Every other byte is untouched, so the diff is one line.+ self.assertEqual(+ rendered.replace('"version": "0.1.2"', '"version": "0.1.1"'),+ self.PACKAGE,+ )++ def test_render_package_json_requires_a_version_field(self) -> None:+ with self.assertRaises(ValueError):+ render_package_json('{\n "name": "pair"\n}\n', '0.1.2')++ def test_missing_fences_rejected(self) -> None:+ with self.assertRaises(ValueError):+ parse_release_intent('## Summary\nno fences here', KEYS)+++class ReleaseIntentTests(unittest.TestCase):+ def test_all_none_requires_na(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ intent = parse_release_intent(_block('n/a', 'n/a', bumps), KEYS)+ self.assertFalse(intent.has_release)++ def test_all_none_rejects_prose(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ with self.assertRaises(ValueError):+ parse_release_intent(_block('Oops', 'n/a', bumps), KEYS)++ def test_component_requires_services(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ bumps['ollama-proxy'] = 'patch'+ with self.assertRaises(ValueError):+ parse_release_intent(_block('Title', '- body', bumps), KEYS)++ def test_services_must_dominate(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ bumps['ollama-proxy'] = 'major'+ bumps['services'] = 'patch'+ with self.assertRaises(ValueError):+ parse_release_intent(_block('Title', '- body', bumps), KEYS)++ def test_release_ok(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ bumps['services'] = 'minor'+ bumps['nvpair-engine-manager'] = 'minor'+ intent = parse_release_intent(+ _block('Engine load progress', '- Shows percent while pulling.', bumps),+ KEYS,+ )+ self.assertTrue(intent.has_release)+ manifest = VersionsManifest(+ services='0.82.0',+ components={key: '1.0.0' for key in KEYS if key != 'services'},+ )+ updated = apply_bumps(manifest, intent)+ self.assertEqual(updated.services, '0.83.0')+ self.assertEqual(updated.components['nvpair-engine-manager'], '1.1.0')+ self.assertEqual(updated.components['ollama-proxy'], '1.0.0')++ def test_inline_comments_are_ignored(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ block = _block('n/a', 'n/a', bumps)+ block = block.replace(+ '### Bumps\n',+ '### Bumps\n<!-- Set each value to: none | patch | minor | major -->\n',+ )+ block = block.replace(+ '### Changelog title\nn/a',+ '### Changelog title\n<!-- headline here -->\nn/a',+ )+ intent = parse_release_intent(block, KEYS)+ self.assertFalse(intent.has_release)++ def test_bullet_bumps_parse(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ bumps['services'] = 'patch'+ bumps['ollama-proxy'] = 'patch'+ intent = parse_release_intent(+ _block('Routing fix', '- Fixes routing.', bumps, bullets=True),+ KEYS,+ )+ self.assertTrue(intent.has_release)+ self.assertEqual(intent.bumps['ollama-proxy'], 'patch')++ def test_plain_bumps_still_parse(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ intent = parse_release_intent(_block('n/a', 'n/a', bumps, bullets=False), KEYS)+ self.assertFalse(intent.has_release)++ def _with_unknown_key(self) -> str:+ bumps = {key: 'none' for key in KEYS}+ return _block('n/a', 'n/a', bumps).replace(+ 'ollama-proxy: none\n',+ 'ollama-proxy: none\nextra-thing: none\n',+ )++ def _without_ollama_proxy(self) -> str:+ bumps = {key: 'none' for key in KEYS if key != 'ollama-proxy'}+ bump_lines = '\n'.join(f'- {key}: {bumps[key]}' for key in bumps)+ return (+ f'{INTENT_START}\n'+ f'### Changelog title\nn/a\n\n'+ f'### Changelog body\nn/a\n\n'+ f'### Bumps\n{bump_lines}\n'+ f'{INTENT_END}\n'+ )++ def test_unknown_key_strict(self) -> None:+ with self.assertRaises(ValueError):+ parse_release_intent(self._with_unknown_key(), KEYS, key_policy='strict')++ def test_missing_key_strict(self) -> None:+ with self.assertRaises(ValueError):+ parse_release_intent(self._without_ollama_proxy(), KEYS, key_policy='strict')++ def test_unknown_key_rejected_when_applying(self) -> None:+ """An unknown key at apply time means the block was edited past CI."""+ with self.assertRaises(ValueError):+ parse_release_intent(+ self._with_unknown_key(), KEYS, key_policy='reject-unknown'+ )++ def test_missing_key_tolerated_when_applying(self) -> None:+ """A concurrent pull request can add a component after this one is written."""+ intent = parse_release_intent(+ self._without_ollama_proxy(), KEYS, key_policy='reject-unknown'+ )+ self.assertEqual(intent.bumps['ollama-proxy'], 'none')++ def test_unknown_key_lenient(self) -> None:+ intent = parse_release_intent(+ self._with_unknown_key(), KEYS, key_policy='lenient'+ )+ self.assertFalse(intent.has_release)+ self.assertNotIn('extra-thing', intent.bumps)++ def test_missing_key_lenient(self) -> None:+ intent = parse_release_intent(+ self._without_ollama_proxy(), KEYS, key_policy='lenient'+ )+ self.assertEqual(intent.bumps['ollama-proxy'], 'none')++ def test_bump_semver(self) -> None:+ self.assertEqual(bump_semver('1.2.3', 'none'), '1.2.3')+ self.assertEqual(bump_semver('1.2.3', 'patch'), '1.2.4')+ self.assertEqual(bump_semver('1.2.3', 'minor'), '1.3.0')+ self.assertEqual(bump_semver('1.2.3', 'major'), '2.0.0')++ def test_changelog_prepend(self) -> None:+ existing = '# Changelog\n\nIntro\n\n## 0.1.0 — Old\n\n- old\n'+ entry = format_changelog_entry('0.1.2', 'New thing', '- bullet\n', '123')+ out = prepend_changelog(existing, entry)+ self.assertIn('## 0.1.2 — New thing (#123)', out)+ self.assertTrue(out.index('## 0.1.2') < out.index('## 0.1.0'))++ def test_changelog_entry_without_pr_ref_has_no_suffix(self) -> None:+ entry = format_changelog_entry('0.1.2', 'Local', '- bullet\n', '')+ self.assertIn('## 0.1.2 — Local\n', entry)+ self.assertNotIn('(#', entry)++ def test_changelog_mixed_prose_no_double_dash(self) -> None:+ entry = format_changelog_entry(+ '0.1.2',+ 'Mixed',+ 'Plain prose line\n- Already a bullet\nAnother prose',+ '7',+ )+ self.assertIn('- Plain prose line\n', entry)+ self.assertIn('- Already a bullet\n', entry)+ self.assertIn('- Another prose\n', entry)+ self.assertNotIn('- - ', entry)++ def test_forbidden_paths(self) -> None:+ with self.assertRaises(ValueError):+ check_forbidden_paths([('M', 'services/versions.json')], 'no marker')+ check_forbidden_paths(+ [('M', 'services/versions.json')],+ f'hello {ALLOW_OWNED_FILES_MARKER}',+ )+ check_forbidden_paths(+ [('M', 'services/versions.json')],+ 'hello <!--pair-release-intent-allow-owned-files-->',+ )+ check_forbidden_paths([('D', 'services/changelog.md')], 'no marker')+ with self.assertRaises(ValueError):+ check_forbidden_paths([('M', 'services/changelog.md')], 'no marker')++ def test_collapsed_html_comment_fences(self) -> None:+ bumps = {key: 'none' for key in KEYS}+ bump_lines = '\n'.join(f'- {key}: {bumps[key]}' for key in KEYS)+ text = (+ '<!--pair-release-intent-allow-owned-files-->\n'+ '<!--pair-release-intent:v1-->\n'+ '### Changelog title\nn/a\n\n'+ '### Changelog body\nn/a\n\n'+ f'### Bumps\n{bump_lines}\n'+ '<!--/pair-release-intent:v1-->\n'+ )+ intent = parse_release_intent(text, KEYS)+ self.assertFalse(intent.has_release)++ def test_render_versions_mutates_original_keys(self) -> None:+ original = {+ '$comment': 'keep me',+ 'services': '0.82.0',+ 'components': {+ 'ollama-proxy': '0.23.0',+ 'lmstudio-proxy': '0.13.1',+ },+ 'extra': 'preserved',+ }+ manifest = VersionsManifest(+ services='0.83.0',+ components={'ollama-proxy': '0.23.1', 'lmstudio-proxy': '0.13.1'},+ )+ text = render_versions_json(manifest, original)+ parsed = json.loads(text)+ self.assertEqual(parsed['services'], '0.83.0')+ self.assertEqual(parsed['extra'], 'preserved')+ self.assertEqual(parsed['components']['ollama-proxy'], '0.23.1')+ self.assertTrue(text.endswith('\n'))++ def test_render_versions_drops_retired_keys(self) -> None:+ """A manifest still carrying product/installer renders without them."""+ original = {+ 'product': '0.91.7',+ 'installer': '0.91.7',+ 'components': {'ollama-proxy': '0.26.2'},+ }+ manifest = VersionsManifest(+ services='0.91.8', components={'ollama-proxy': '0.26.3'}+ )+ parsed = json.loads(render_versions_json(manifest, original))+ self.assertEqual(parsed['services'], '0.91.8')+ self.assertNotIn('product', parsed)+ self.assertNotIn('installer', parsed)++ def test_repo_versions_roundtrip(self) -> None:+ manifest, raw = load_versions(VERSIONS_PATH)+ text = render_versions_json(manifest, raw)+ with tempfile.NamedTemporaryFile('w', encoding='utf-8', delete=False) as handle:+ handle.write(text)+ temp_path = Path(handle.name)+ try:+ again, _ = load_versions(temp_path)+ self.assertEqual(again.services, manifest.services)+ self.assertEqual(again.components, manifest.components)+ finally:+ temp_path.unlink(missing_ok=True)+++if __name__ == '__main__':+ unittest.main()diff --git a/scripts/release-intent/validate_pr.py b/scripts/release-intent/validate_pr.pynew file mode 100644index 0000000..4326f93--- /dev/null+++ b/scripts/release-intent/validate_pr.py@@ -0,0 +1,138 @@+#!/usr/bin/env python3+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0+"""Validate a pull request body against the PAIR release-intent contract."""++from __future__ import annotations++import argparse+import os+import subprocess+import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parent))++from lib import ( # noqa: E402+ INTENT_END,+ INTENT_START,+ REPO_ROOT,+ check_forbidden_paths,+ load_versions,+ parse_release_intent,+)+++def pull_request_body() -> str:+ """The pull request body, as the workflow passed it in.++ The workflow sets PR_BODY from github.event.pull_request.body through `env:`+ rather than interpolating it into a shell command, because the body is+ author-controlled and would otherwise be a shell injection.++ There is no API fallback: the webhook payload carries the whole body, so+ unlike GitLab's CI_MERGE_REQUEST_DESCRIPTION there is nothing to un-truncate+ and no token needed to read it. That is also why this script needs no+ secret, which is what lets it run on pull requests from forks.+ """+ body = os.environ.get('PR_BODY')+ if body is None:+ raise SystemExit(+ 'PR_BODY is not set. In CI the workflow must pass it via `env:` from '+ 'github.event.pull_request.body. Locally, use --description-file.'+ )+ return body+++def changed_name_status(base: str, head: str) -> list[tuple[str, str]]:+ result = subprocess.run(+ ['git', 'diff', '--name-status', f'{base}...{head}'],+ cwd=REPO_ROOT,+ check=True,+ capture_output=True,+ text=True,+ )+ rows: list[tuple[str, str]] = []+ for line in result.stdout.splitlines():+ if not line.strip():+ continue+ parts = line.split('\t')+ if len(parts) == 2:+ rows.append((parts[0], parts[1]))+ elif len(parts) == 3 and parts[0].startswith('R'):+ rows.append((parts[0], parts[2]))+ else:+ raise SystemExit(f'Unrecognized git name-status line: {line!r}')+ return rows+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument(+ '--description-file',+ type=Path,+ help='Read the body from a file instead of the PR_BODY environment variable',+ )+ parser.add_argument(+ '--skip-owned-files-check',+ action='store_true',+ help='Skip bot-owned path enforcement (local testing only)',+ )+ args = parser.parse_args()++ if args.description_file is not None:+ description = args.description_file.read_text(encoding='utf-8')+ else:+ description = pull_request_body()++ try:+ versions, _raw = load_versions()+ except ValueError as exc:+ # A traceback here reads as a script crash when it is really a malformed+ # manifest, which is the likely state mid-schema-change.+ print(f'services/versions.json could not be read: {exc}', file=sys.stderr)+ return 1++ try:+ intent = parse_release_intent(+ description, versions.bump_keys, key_policy='strict'+ )+ if not args.skip_owned_files_check:+ base = os.environ.get('PR_BASE_SHA')+ head = os.environ.get('PR_HEAD_SHA')+ if base and head:+ check_forbidden_paths(changed_name_status(base, head), description)+ elif os.environ.get('GITHUB_EVENT_NAME') == 'pull_request':+ # The merge-base diff is the only way to catch a hand edit to a+ # bot-owned file, so a pull request that cannot compute it must+ # fail rather than pass the check vacuously. Needs+ # actions/checkout with fetch-depth: 0.+ raise SystemExit(+ 'PR_BASE_SHA and PR_HEAD_SHA are required to enforce '+ 'bot-owned file rules on a pull request'+ )+ except ValueError as exc:+ print('release-intent validation failed:', file=sys.stderr)+ print(str(exc), file=sys.stderr)+ print(file=sys.stderr)+ print('Expected fences:', file=sys.stderr)+ print(f' {INTENT_START}', file=sys.stderr)+ print(f' {INTENT_END}', file=sys.stderr)+ return 1++ print('release-intent OK')+ print(f' services bump: {intent.bumps["services"]}')+ for key in versions.bump_keys:+ if key == 'services':+ continue+ print(f' {key}: {intent.bumps[key]}')+ if intent.has_release:+ print(f' changelog title: {intent.changelog_title}')+ print(' release version: patch-bumps automatically on merge')+ else:+ print(' no version release (all bumps none)')+ return 0+++if __name__ == '__main__':+ raise SystemExit(main())diff --git a/services/VERSIONING.md b/services/VERSIONING.mdindex 446bf4c..04c7425 100644--- a/services/VERSIONING.md+++ b/services/VERSIONING.md@@ -11,19 +11,30 @@ numbers. Build scripts read it and stamp every binary at build time via Go's```services/versions.json-├── product # umbrella / product release-├── installer # always equals product+├── services # the services suite as a whole└── components.* # per-binary versions (independent SemVer)```-Product release notes are maintained outside this tree. Do not add or edit-`services/changelog.md`.+Do not add or edit `services/changelog.md`.-`desktop/package.json` `version` is **out of scope** for automated service-bumps. Bump it manually when cutting an Electron / update-feed release.+## Three numbers, three jobs-`product` / `installer` follow the product release series (for example-`0.82.0`), not a separate services-only major line.+| Number | Lives in | Stamps | Bumped |+| ------ | -------- | ------ | ------ |+| release | `desktop/package.json` `version` | The app users install, the update feed, the GitHub release tag | Automatically: one PATCH forward whenever a release-intent block declares a release |+| `services` | `services/versions.json` | The standalone services installer and Go `main.Version` | Declared in the release-intent block |+| `components.*` | `services/versions.json` | Each binary's own `--version` | Declared in the release-intent block |++Only the last two are declared, because only they carry SemVer meaning a human+has to judge. The release version is a counter: it answers "which build is+this?", not "how compatible is it?".++A MINOR or MAJOR release version is a deliberate manual edit at cut time. The+automation only ever moves it one PATCH forward, so it cannot promote a release+on its own.++The release version and `services` are **not** held equal, and no attempt is+made to align them. They version different artifacts.## Bumping rules (SemVer meaning)@@ -41,24 +52,29 @@ We follow [SemVer](https://semver.org/) (`MAJOR.MINOR.PATCH`).Ask: would a user reading `--version` learn something useful? If not, leave it`none`.-### Product version (`product`)+### Services suite version (`services`)-| Change | Product bump |-| ------ | ------------ |-| No product-facing release | none |-| Only PATCH-level notes / component bumps | PATCH |-| At least one MINOR component bump, or user-visible product change | MINOR |+| Change | `services` bump |+| ------ | --------------- |+| No release | none |+| Only PATCH-level component bumps | PATCH |+| At least one MINOR component bump, or user-visible change | MINOR || At least one MAJOR component bump, or breaking UX/data change | MAJOR |-`installer` always equals `product` after a release apply.+`services` must be at least as severe as the highest component bump; CI rejects+a block where it is not.## Declaring a version change-Update `versions.json` in the same pull request that changes compiled output,-using the tables above to pick the severity. Say in the pull-request description-which components you bumped and why, and describe any user-facing change in plain-terms so it can be carried into the release notes. A reviewer should be able to-see the version decision without inferring it from the diff.+Declare bumps in the `pair-release-intent:v1` block in your pull request+description, using the tables above to pick the severity. **Do not edit+`services/versions.json` or `CHANGELOG.md` by hand** — they are written by+automation, and CI rejects a pull request that modifies them.++Describe any user-facing change in the block's changelog title and body in plain+terms; that text becomes the changelog entry verbatim, cited back to your pull+request number. A reviewer should be able to see the version decision without+inferring it from the diff.## Verifyingdiff --git a/services/build.bat b/services/build.batindex ee5e3a0..70ae595 100644--- a/services/build.bat+++ b/services/build.bat@@ -37,7 +37,7 @@ REM Parse versions.json with jq. We use --arg to pass each component key asREM a string variable, which sidesteps cmd's hostility toward embeddedREM double quotes inside the jq filter (component keys contain hyphens, soREM bare .components.nvpair-ui-broker would parse as subtraction).-for /f "delims=" %%V in ('jq -r ".product" "%VERSIONS_FILE%"') do set "V_PRODUCT=%%V"+for /f "delims=" %%V in ('jq -r ".services" "%VERSIONS_FILE%"') do set "V_SERVICES=%%V"for /f "delims=" %%V in ('jq -r --arg k "nvpair-proxy" ".components[$k]" "%VERSIONS_FILE%"') do set "V_PROXY=%%V"for /f "delims=" %%V in ('jq -r --arg k "nvpair-node-info" ".components[$k]" "%VERSIONS_FILE%"') do set "V_NINFO=%%V"for /f "delims=" %%V in ('jq -r --arg k "nvpair-node-scanner" ".components[$k]" "%VERSIONS_FILE%"') do set "V_NSCAN=%%V"@@ -51,13 +51,13 @@ for /f "delims=" %%V in ('jq -r --arg k "nvpair-cluster-manager" ".components[$for /f "delims=" %%V in ('jq -r --arg k "nvpair-job-scheduler" ".components[$k]" "%VERSIONS_FILE%"') do set "V_SCHED=%%V"for /f "delims=" %%V in ('jq -r --arg k "nvpair-tui" ".components[$k]" "%VERSIONS_FILE%"') do set "V_TUI=%%V"-if "%V_PRODUCT%"=="" (+if "%V_SERVICES%"=="" (echo ERROR: failed to parse versions.jsonendlocalexit /b 1)-echo product = %V_PRODUCT%+echo services = %V_SERVICES%echo nvpair-proxy = %V_PROXY%echo nvpair-node-info = %V_NINFO%echo nvpair-node-scanner = %V_NSCAN%@@ -163,7 +163,7 @@ copy /y "%ROOT%nvpair-tui\nvpair-tui.exe" "%BIN_OUT%\nvpair-tui.exe" >nul || gotecho.echo ========================================-echo Build complete (product v%V_PRODUCT%)+echo Build complete (services v%V_SERVICES%)echo ========================================echo.echo Proxy: %BIN_OUT%\nvpair-proxy.exe@@ -180,9 +180,9 @@ echo Job Scheduler: %BIN_OUT%\nvpair-job-scheduler.exeecho TUI: %BIN_OUT%\nvpair-tui.exeecho.-REM Surface the product version to any caller (e.g. installer_build.bat) so+REM Surface the services version to any caller (e.g. installer_build.bat) soREM they don't have to re-parse versions.json.-endlocal & set "NVPAIR_PRODUCT_VERSION=%V_PRODUCT%"+endlocal & set "NVPAIR_SERVICES_VERSION=%V_SERVICES%"exit /b 0:faildiff --git a/services/build.sh b/services/build.shindex ef314ec..316bb2c 100755--- a/services/build.sh+++ b/services/build.sh@@ -54,7 +54,7 @@ echo# Mirror build.bat's --arg trick: component keys contain hyphens, which jq's# bare-identifier syntax would parse as subtraction. Passing the key as a# string variable sidesteps the ambiguity.-V_PRODUCT=$(jq -r '.product' "$VERSIONS_FILE")+V_SERVICES=$(jq -r '.services' "$VERSIONS_FILE")V_PROXY=$( jq -r --arg k 'nvpair-proxy' '.components[$k]' "$VERSIONS_FILE")V_NINFO=$( jq -r --arg k 'nvpair-node-info' '.components[$k]' "$VERSIONS_FILE")V_NSCAN=$( jq -r --arg k 'nvpair-node-scanner' '.components[$k]' "$VERSIONS_FILE")@@ -68,12 +68,12 @@ V_CLUMGR=$( jq -r --arg k 'nvpair-cluster-manager' '.components[$k]' "$VERSIONS_V_SCHED=$( jq -r --arg k 'nvpair-job-scheduler' '.components[$k]' "$VERSIONS_FILE")V_TUI=$( jq -r --arg k 'nvpair-tui' '.components[$k]' "$VERSIONS_FILE")-if [[ -z "$V_PRODUCT" || "$V_PRODUCT" == "null" ]]; then+if [[ -z "$V_SERVICES" || "$V_SERVICES" == "null" ]]; thenecho "ERROR: failed to parse versions.json" >&2exit 1fi-printf ' product = %s\n' "$V_PRODUCT"+printf ' services = %s\n' "$V_SERVICES"printf ' nvpair-proxy = %s\n' "$V_PROXY"printf ' nvpair-node-info = %s\n' "$V_NINFO"printf ' nvpair-node-scanner = %s\n' "$V_NSCAN"@@ -142,7 +142,7 @@ cp "$ROOT/nvpair-tui/nvpair-tui" "$BIN_OUT/nvpair-tui"echoecho "========================================"-echo " Build complete (product v$V_PRODUCT)"+echo " Build complete (services v$V_SERVICES)"echo "========================================"echoprintf ' Proxy: %s\n' "$BIN_OUT/nvpair-proxy"diff --git a/services/installer_build.bat b/services/installer_build.batindex f5083f6..acb045f 100644--- a/services/installer_build.bat+++ b/services/installer_build.bat@@ -66,8 +66,7 @@ if not exist "%ROOT%dist" mkdir "%ROOT%dist"REM Resolve installer version. Precedence:REM 1. Explicit CLI arg: installer_build.bat 1.2.3-REM 2. versions.json "installer" field-REM 3. versions.json "product" field (fallback)+REM 2. versions.json "services" fieldREMREM build.bat (called above) already verified jq is on PATH, so we don'tREM re-check here. Using a :get_version subroutine keeps the for /f out of@@ -105,8 +104,6 @@ exit /b 0:get_versionif not exist "%VERSIONS_FILE%" exit /b 0-REM jq's `//` operator returns the right-hand side when the left is null or-REM false, giving us the installer-then-product fallback in one filter.-for /f "delims=" %%V in ('jq -r ".installer // .product" "%VERSIONS_FILE%"') do set "VERSION=%%V"+for /f "delims=" %%V in ('jq -r ".services" "%VERSIONS_FILE%"') do set "VERSION=%%V"if /i "%VERSION%"=="null" set "VERSION="exit /b 0diff --git a/services/installer_build.sh b/services/installer_build.shindex a6698cf..25d1e35 100755--- a/services/installer_build.sh+++ b/services/installer_build.sh@@ -23,8 +23,7 @@## Version precedence (same as installer_build.bat):# 1. Explicit CLI arg: installer_build.sh 1.2.3-# 2. versions.json "installer" field-# 3. versions.json "product" field (fallback)+# 2. versions.json "services" field## The tarball uses a nested layout — every entry lives under# NVIDIA-Personal-AI-Router-<version>/ — so `tar xf` produces a single clean@@ -89,9 +88,9 @@ resolve_version() {returnfi# `//` returns the right-hand side when the left is null or false,- # giving us the installer-then-product fallback in one filter.+ # The services suite version is the installer's version.local v- v=$(jq -r '.installer // .product' "$VERSIONS_FILE")+ v=$(jq -r '.services' "$VERSIONS_FILE")if [[ "$v" != "null" && -n "$v" ]]; thenecho "$v"fidiff --git a/services/nvpair-cluster-manager/spec.md b/services/nvpair-cluster-manager/spec.mdindex 36f35e3..ea65943 100644--- a/services/nvpair-cluster-manager/spec.md+++ b/services/nvpair-cluster-manager/spec.md@@ -587,7 +587,7 @@ From here every trusted inter-node call between A and B is mutually authenticateNo flag carries the node identity (self-generated, §7.4) or the cluster identity (`cluster:set-identity`, §7.0), keeping the binary self-bootstrapping under any supervisor.**Build wiring**: `nvpair-cluster-manager` is one of the Go binaries in the product bundle. Adding it requires, in the same change:-- a `components.nvpair-cluster-manager` entry in `versions.json`, an `installer` bump, and a `product` bump (see `VERSIONING.md`);+- a `components.nvpair-cluster-manager` entry in `versions.json` and a `services` bump, both declared in the pull request's release-intent block rather than edited by hand (see `VERSIONING.md`);- a build + copy step in **both** `build.bat` and `build.sh` (→ the repo-root `build/bin/` bundle), with the `-X main.Version=…` ldflag;- inclusion in the NSIS installer (`installer/nvpair-setup.nsi`) and any firewall-rule list (it opens TCP `14321`), plus `bom.md`;- a `product` bump declared in the pull request's release-intent block (see `VERSIONING.md`).diff --git a/services/readme.md b/services/readme.mdindex 1a3f1b8..a701adc 100644--- a/services/readme.md+++ b/services/readme.md@@ -230,7 +230,7 @@ A skip is not a pass. If you are relying on a test, check it actually ran.## Versioning-`services/versions.json` is the single source of truth for every component version and the umbrella `product` version. The build scripts read it and stamp each binary via `-ldflags "-X main.Version=..."`. Bump the components your change affects in the same pull request, and describe any user-facing change in the pull-request description so it reaches the release notes. [`VERSIONING.md`](VERSIONING.md) has the bump rules.+`services/versions.json` is the single source of truth for every component version and the `services` suite version. The build scripts read it and stamp each binary via `-ldflags "-X main.Version=..."`. Declare the bumps your change needs in the `pair-release-intent:v1` block in your pull-request description — automation writes `versions.json`, so do not edit it by hand — and describe any user-facing change there so it reaches the changelog. [`VERSIONING.md`](VERSIONING.md) has the bump rules.You can verify a built binary's stamped version at any time:diff --git a/services/versions.json b/services/versions.jsonindex a439186..89288be 100644--- a/services/versions.json+++ b/services/versions.json@@ -1,7 +1,6 @@{"$comment": "Single source of truth for all version numbers. See VERSIONING.md for bump rules.",- "product": "1.2.0",- "installer": "1.2.0",+ "services": "1.2.0","components": {"nvpair-proxy": "1.2.0","nvpair-node-info": "0.13.3",