@rizom/ops 0.2.0-alpha.482 → 0.2.0-alpha.484

package/package.json

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

package/templates/rover-pilot/README.md

@@ -30,8 +30,8 @@ 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 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.
+The fleet publishes one immutable image per effective Brain version and site pin set: `brain-${brainVersion}` for instances without a site override, `brain-${brainVersion}--<pins>` for instances with one (the pins spelled out and sorted, or a digest of them when too long). Instances with the same version and pins share an image; a site's pin change builds that site's image and no other, and smoke-to-fleet promotion reuses the tested image because its name already carries its pins. Build and Deploy verify installed package versions against an image's name before reusing it.
+When an effective brain version (`pilot.yaml.brainVersion`, or a cohort override) or a site pin changes and you push, CI builds every missing image, refreshes generated user env files (an instance with site pins names its image there as `IMAGE_TAG`), and redeploys affected users. Every external site and theme package keeps its own exact version pin. Published tags remain immutable: a new pin set is a new tag.
 When a push changes only deploy contract files, CI prints `No affected user configs; skipping deploy.` and stops before Kamal.
 
 ## Commands

package/templates/rover-pilot/deploy/scripts/helpers.ts

@@ -7,6 +7,7 @@ export {
   writeGitHubOutput,
   writeGitHubEnv,
   runtimeImageTag,
+  sitePackagesFor,
   runResolveMissingImages,
 } from "@rizom/ops/deploy";
 export type { EnvSchemaEntry } from "@rizom/ops/deploy";

package/templates/rover-pilot/deploy/scripts/resolve-user-config.ts

@@ -6,6 +6,7 @@ import {
   parseEnvFile,
   requireEnv,
   runtimeImageTag,
+  sitePackagesFor,
   writeGitHubOutput,
 } from "./helpers";
 
@@ -42,9 +43,19 @@ const wwwDomain = isFleetDomain(
 
 const brainVersion = envEntries["BRAIN_VERSION"] ?? "";
 
-// Build and Deploy share one tag function: every instance on a Brain version
-// runs the same immutable fleet image.
-const imageTag = runtimeImageTag(brainVersion);
+// Build and Deploy share one tag function: an instance runs the immutable
+// image named by its Brain version and its own site pins. The generated env
+// names the same image; a disagreement means the registry moved under it.
+const imageTag = runtimeImageTag(
+  brainVersion,
+  sitePackagesFor(user.siteOverride),
+);
+const generatedTag = envEntries["IMAGE_TAG"];
+if (generatedTag && generatedTag !== imageTag) {
+  throw new Error(
+    `${envPath} names ${generatedTag} but the registry resolves ${imageTag}; reconcile first`,
+  );
+}
 
 const outputs: Record<string, string> = {
   brain_version: brainVersion,

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

@@ -12,7 +12,7 @@ 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),
+  tag: runtimeImageTag(user.brainVersion, sitePackagesFor(user.siteOverride)),
   brainVersion: user.brainVersion,
   sitePackages: sitePackagesFor(user.siteOverride),
 });

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

@@ -19,17 +19,16 @@ 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
-- 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>`
+- one immutable image is published for each effective Brain version and site pin set: `brain-${brainVersion}` for instances without a site override, `brain-${brainVersion}--<pins>` for instances with one (pins spelled out and sorted, or a digest when too long)
+- instances with the same version and pins share an image; a site's pin change builds that site's image and no other
+- generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`, and `IMAGE_TAG=<tag>` for an instance with site pins
 - build and deploy derive the same effective image tag from the resolved registry
 
 ## Version bump flow
 
 When `pilot.yaml.brainVersion` changes and you push:
 
-1. build publishes each missing version image with the full fleet package union, and verifies existing images against their assigned instances
+1. build publishes each missing image, named by Brain version and site pins, and verifies existing images against what their names say they hold
 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
@@ -38,10 +37,10 @@ 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.
+Smoke-first upgrades build the canary's image, named by its pins, before promotion.
+Moving other instances onto the tested Brain version reuses that image where their
+pins match it and builds their own where they do not. Explicit Build dispatches build
+exactly the dispatched version and `site_packages` 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
@@ -307,24 +306,22 @@ siteOverride:
   themeVersion: <exact-theme-version>
 ```
 
-Missing external package versions fail desired-state validation. Every instance on one
-Brain version uses the same image and exact package union. Change a site/theme package
-pin only together with a fresh Brain version; published `brain-${brainVersion}` tags
-remain immutable. Conflicting pins for one package on the same Brain version fail before
-build. Bundled `@brains/*` themes omit `themeVersion` because they are not installed as
-separate packages.
+Missing external package versions fail desired-state validation. An instance runs the
+image named by its Brain version and its own pins, so a site/theme pin can change on its
+own: the push builds that image and redeploys that instance. Published tags remain
+immutable; a new pin set is a new tag. Bundled `@brains/*` themes omit `themeVersion`
+because they are not installed as separate packages.
 
 ### Custom-package canary and rollback
 
 1. Confirm the exact site/theme versions are public-installable without npm credentials.
-2. Apply the exact package names and versions to one healthy canonical site canary and select a fresh Brain version for that package set.
-3. Push desired state and let the normal Build → Reconcile → Deploy chain create the shared version image and update the canary.
+2. Apply the exact package names and versions to one healthy canonical site canary.
+3. Push desired state and let the normal Build → Reconcile → Deploy chain create the canary's image and update the canary.
 4. Run `bunx brains-ops verify-user . <handle>`.
 5. Manually verify the site, theme, Studio, content sync, and passkey sign-in before adding more users.
 
-To roll back, remove or change `siteOverride` while selecting a fresh Brain version,
-then reconcile and redeploy that user. Never mutate an existing image tag; coordinate any
-other users intentionally sharing the selected version.
+To roll back, remove or change `siteOverride`, then reconcile and redeploy that user.
+Never mutate an existing image tag.
 
 ## Setup email checklist