@rizom/ops 0.2.0-alpha.371 → 0.2.0-alpha.372

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/ops",
-  "version": "0.2.0-alpha.371",
+  "version": "0.2.0-alpha.372",
   "description": "Operator CLI for managing private brain fleet registry repos",
   "keywords": [
     "brains",

package/templates/rover-pilot/.github/workflows/build.yml

@@ -4,11 +4,11 @@ on:
   workflow_dispatch:
     inputs:
       brain_version:
-        description: Force one explicit build at this brain version (skips the registry-derived resolve)
+        description: Build one Brain version with the full fleet package union
         required: false
         type: string
       site_packages:
-        description: "Space-separated exact site/theme packages for one explicit image build. Shared-fleet automatic builds derive the version-wide package union from desired state."
+        description: "Extra exact site/theme package pins for an explicit build. All builds include the full fleet package union; conflicting pins are rejected."
         required: false
         type: string
       overwrite:

package/templates/rover-pilot/.github/workflows/deploy.yml

@@ -134,6 +134,9 @@ jobs:
           echo "Timed out waiting for $IMAGE_TAG" >&2
           exit 1
 
+      - name: Verify runtime image packages
+        run: bun deploy/scripts/verify-runtime-image.ts
+
       - name: Install Kamal
         run: |
           gem install --user-install kamal

package/templates/rover-pilot/README.md

@@ -30,7 +30,7 @@ The repo also checks in its deploy contract:
 
 `.env.schema` is the single source of truth for required and sensitive deploy vars.
 Use separate GitHub tokens: `CONTENT_REPO_ADMIN_TOKEN` for operator-side content repo creation/checks, and `GIT_SYNC_TOKEN` for runtime directory-sync git access.
-The fleet publishes one `brain-${brainVersion}` image per effective Brain version and installs the union of exact site/theme package pins required by instances on that version.
+The fleet publishes one immutable `brain-${brainVersion}` image per effective Brain version. New images install the exact site/theme package union across the entire fleet, so smoke-to-fleet promotion reuses the tested image. Build and Deploy verify installed package versions before reusing existing images.
 When an effective brain version (`pilot.yaml.brainVersion`, or a cohort override) changes and you push, CI builds every missing version image, refreshes generated user env files, and redeploys affected users. Every external site and theme package keeps its own exact version pin; change that package set only together with a fresh Brain version so published tags remain immutable.
 When a push changes only deploy contract files, CI prints `No affected user configs; skipping deploy.` and stops before Kamal.
 

package/templates/rover-pilot/deploy/scripts/verify-runtime-image.ts

@@ -0,0 +1,18 @@
+import { loadPilotRegistry } from "@rizom/ops";
+import {
+  requireEnv,
+  runtimeImageTag,
+  sitePackagesFor,
+  verifyRuntimeImage,
+} from "@rizom/ops/deploy";
+
+const handle = requireEnv("HANDLE");
+const registry = await loadPilotRegistry(process.cwd());
+const user = registry.users.find((entry) => entry.handle === handle);
+if (!user) throw new Error(`Unknown fleet handle: ${handle}`);
+
+await verifyRuntimeImage(`ghcr.io/${requireEnv("GITHUB_REPOSITORY")}`, {
+  tag: runtimeImageTag(user.brainVersion),
+  brainVersion: user.brainVersion,
+  sitePackages: sitePackagesFor(user.siteOverride),
+});

package/templates/rover-pilot/docs/operator-playbook.md

@@ -19,7 +19,7 @@ The deploy scripts and workflows should read from that contract instead of inven
 The fleet has one image topology:
 
 - one immutable `brain-${brainVersion}` image is published for each effective Brain version
-- each image contains the union of exact site/theme package pins required by instances on that version
+- every new image contains the union of exact site/theme package pins across the whole fleet, regardless of current Brain versions
 - conflicting versions of one package fail image resolution before build
 - generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`
 - build and deploy derive the same effective image tag from the resolved registry
@@ -28,7 +28,7 @@ The fleet has one image topology:
 
 When `pilot.yaml.brainVersion` changes and you push:
 
-1. build publishes each missing version image with its declared package union
+1. build publishes each missing version image with the full fleet package union, and verifies existing images against their assigned instances
 2. reconcile refreshes generated `users/<handle>/.env`
 3. deploy runs for handles whose generated config changed
 4. generated file commits happen once in a final aggregation step after the deploy matrix finishes
@@ -37,6 +37,19 @@ Every external site and theme package has its own exact version pin. A cohort or
 pilot brain-version bump never changes those package versions implicitly; update each
 pin deliberately from reviewed package and image evidence.
 
+Smoke-first upgrades build the full fleet package union before promotion. Moving
+other cohorts onto the tested Brain version then reuses that same immutable image.
+Explicit Build dispatches also include the fleet union; `site_packages` only adds
+extra pins and cannot replace or conflict with declared pins.
+
+Deploy verifies the actual installed Brain and selected instance's site/theme
+versions on the CI runner after image readiness and before provisioning or
+container replacement. It reads manifests in a read-only, network-disabled
+container without starting the Brain or mounting fleet data. Missing packages,
+wrong versions, or verification failures block deployment, even on manual runs.
+Never bypass this gate or overwrite a deployed tag to recover an older incomplete
+image; review artifact recovery separately.
+
 When a push changes only deploy contract files and no generated `users/<handle>/.env` or `users/<handle>/brain.yaml` files, the deploy workflow exits through its explicit no-op path and prints `No affected user configs; skipping deploy.`
 
 They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.