@rizom/ops 0.2.0-alpha.350 → 0.2.0-alpha.351

package/dist/schema.d.ts

@@ -4,6 +4,13 @@ export declare const handleSchema: z.ZodString;
 export declare const secretNameSchema: z.ZodString;
 export declare const agePublicKeySchema: z.ZodString;
 export declare const CAPABILITY_BUNDLE_CONTRACT: "capability-bundles-v1";
+export declare const SHARED_FLEET_IMAGE_CONTRACT: "shared-fleet-v1";
+export declare const ISOLATED_SITE_IMAGE_CONTRACT: "isolated-sites-v1";
+export declare const imageContractSchema: z.ZodEnum<{
+    "shared-fleet-v1": "shared-fleet-v1";
+    "isolated-sites-v1": "isolated-sites-v1";
+}>;
+export type ImageContract = z.output<typeof imageContractSchema>;
 export declare const canonicalBundleIdSchema: z.ZodEnum<{
     core: "core";
     media: "media";
@@ -31,6 +38,7 @@ export declare const profileKindSchema: z.ZodEnum<{
 export interface PilotConfig {
     brainVersion: string;
     bundleContract: typeof CAPABILITY_BUNDLE_CONTRACT;
+    imageContract: ImageContract;
     bundles: CanonicalBundleId[];
     add?: string[] | undefined;
     remove?: string[] | undefined;

package/package.json

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

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

@@ -8,9 +8,17 @@ on:
         required: false
         type: string
       site_packages:
-        description: 'Space-separated site packages for a per-instance site image (e.g. "@rizom/site-rizom-ai@0.2.0-alpha.148"). Empty builds the default fleet image.'
+        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."
         required: false
         type: string
+      image_contract:
+        description: Image contract for an explicit version build
+        required: false
+        type: choice
+        options:
+          - isolated-sites-v1
+          - shared-fleet-v1
+        default: isolated-sites-v1
       overwrite:
         description: Rebuild an existing tag in place. Published tags are immutable; confirm only when replacing a tag whose containers were never deployed.
         required: false
@@ -59,6 +67,7 @@ jobs:
         env:
           BRAIN_VERSION_INPUT: ${{ inputs.brain_version || '' }}
           SITE_PACKAGES_INPUT: ${{ inputs.site_packages || '' }}
+          IMAGE_CONTRACT_INPUT: ${{ inputs.image_contract || 'isolated-sites-v1' }}
           ALLOW_TAG_OVERWRITE: ${{ inputs.overwrite && 'true' || 'false' }}
         run: bun deploy/scripts/resolve-missing-images.ts
 

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 default pilot image tag is `brain-${brainVersion}` end to end. A user with `siteOverride` gets an isolated `brain-${brainVersion}-sites-${packageHash}` image instead.
-When the effective brain version (`pilot.yaml.brainVersion`, or a cohort override) changes and you push, CI rebuilds the required default/site tags, refreshes generated user env files, and redeploys affected users. Every external site and theme package uses its own required exact version pin; ops never infers either version from the brain or from another package.
+`pilot.yaml.imageContract` makes image topology explicit. The default `shared-fleet-v1` contract 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. `isolated-sites-v1` remains available only for fleets that deliberately require package-isolated images.
+When an effective brain version (`pilot.yaml.brainVersion`, or a cohort override) changes and you push, CI builds every missing shared version image, refreshes generated user env files, and redeploys affected users. Every external site and theme package keeps its own exact version pin; under the shared contract, 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.
 
 ## Commands

package/templates/rover-pilot/deploy/scripts/create-predeploy-backup.ts

@@ -1,6 +1,22 @@
 import { Database } from "bun:sqlite";
 import { Buffer } from "node:buffer";
 import { appendFileSync } from "node:fs";
+import { isPlainRecord } from "@brains/utils/predicates";
+
+/**
+ * The slice of `@libsql/client` this script uses.
+ *
+ * Declared here because the import is dynamic — the package is optional, and
+ * only the libsql quick-check driver needs it.
+ */
+interface LibsqlModule {
+  createClient(options: { url: string }): {
+    execute(sql: string): Promise<{
+      rows: Array<Record<string | number, unknown>>;
+    }>;
+    close(): void;
+  };
+}
 
 export const DEFAULT_PREDEPLOY_BACKUP_RETENTION_COUNT = 5;
 export const PREDEPLOY_BACKUP_TOOL_VERSION = "brains-predeploy-backup-v1";
@@ -157,10 +173,8 @@ async function quickCheck(
   if (driver === "bun") {
     const database = new Database(path, { readonly: true });
     try {
-      const row = database.query("PRAGMA quick_check").get() as Record<
-        string,
-        unknown
-      > | null;
+      const result: unknown = database.query("PRAGMA quick_check").get();
+      const row = isPlainRecord(result) ? result : null;
       return String(row?.["quick_check"] ?? row?.["0"] ?? "");
     } finally {
       database.close(false);
@@ -168,14 +182,10 @@ async function quickCheck(
   }
 
   const moduleName = "@libsql/client";
-  const libsql = (await import(moduleName)) as {
-    createClient(options: { url: string }): {
-      execute(sql: string): Promise<{
-        rows: Array<Record<string | number, unknown>>;
-      }>;
-      close(): void;
-    };
-  };
+  // Annotated rather than asserted: a dynamic import of an optional dependency
+  // resolves to `any`, so naming the slice this script uses is a checked
+  // assignment instead of a claim about the whole module.
+  const libsql: LibsqlModule = await import(moduleName);
   const client = libsql.createClient({ url: `file:${path}` });
   try {
     const result = await client.execute("PRAGMA quick_check");
@@ -198,9 +208,10 @@ function vectorDigestDatabase(database: Database): {
   const counts: Record<string, number> = {};
   for (const [table, order] of tables) {
     hasher.update(`table:${table}\n`);
-    const rows = database
+    const selected: unknown[] = database
       .query(`SELECT * FROM ${table} ORDER BY ${order}`)
-      .all() as Array<Record<string, unknown>>;
+      .all();
+    const rows = selected.filter(isPlainRecord);
     counts[table] = rows.length;
     for (const row of rows) {
       for (const [key, value] of Object.entries(row)) {

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

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

package/templates/rover-pilot/deploy/scripts/provision-server.ts

@@ -30,19 +30,54 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * These scripts are copied verbatim into generated projects, so they stay
+ * dependency-free: the API payloads are checked by hand rather than with a
+ * schema library. readJsonResponse returns unknown; asserting the Hetzner
+ * response shape onto it meant a changed or error payload surfaced as an
+ * undefined field later instead of a failed lookup here.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isHetznerServer(value: unknown): value is HetznerServer {
+  if (!isRecord(value)) return false;
+  if (typeof value["id"] !== "number") return false;
+  if (typeof value["status"] !== "string") return false;
+  const publicNet = value["public_net"];
+  if (publicNet === undefined) return true;
+  if (!isRecord(publicNet)) return false;
+  const ipv4 = publicNet["ipv4"];
+  if (ipv4 === undefined) return true;
+  if (!isRecord(ipv4)) return false;
+  const ip = ipv4["ip"];
+  return ip === undefined || typeof ip === "string";
+}
+
+function readServer(payload: unknown): HetznerServer | undefined {
+  if (!isRecord(payload)) return undefined;
+  const server = payload["server"];
+  return isHetznerServer(server) ? server : undefined;
+}
+
+function readServers(payload: unknown): HetznerServer[] | undefined {
+  if (!isRecord(payload)) return undefined;
+  const servers = payload["servers"];
+  return Array.isArray(servers) && servers.every(isHetznerServer)
+    ? servers
+    : undefined;
+}
+
 async function listServers(): Promise<HetznerServer[]> {
   const url = `${baseUrl}/servers?label_selector=${encodeURIComponent(labelSelector)}`;
   const response = await fetch(url, { headers });
-  const payload = (await readJsonResponse(
-    response,
-    "Hetzner server lookup",
-  )) as {
-    servers?: HetznerServer[];
-  };
-  if (!response.ok || !payload.servers) {
+  const payload = await readJsonResponse(response, "Hetzner server lookup");
+  const servers = readServers(payload);
+  if (!response.ok || !servers) {
     throw new Error(`Hetzner server lookup failed: ${JSON.stringify(payload)}`);
   }
-  return payload.servers;
+  return servers;
 }
 
 async function createServer(): Promise<HetznerServer> {
@@ -58,27 +93,22 @@ async function createServer(): Promise<HetznerServer> {
       labels: { brain: instanceName },
     }),
   });
-  const payload = (await readJsonResponse(
-    response,
-    "Hetzner server create",
-  )) as {
-    server?: HetznerServer;
-  };
-  if (!response.ok || !payload.server) {
+  const payload = await readJsonResponse(response, "Hetzner server create");
+  const server = readServer(payload);
+  if (!response.ok || !server) {
     throw new Error(`Hetzner server create failed: ${JSON.stringify(payload)}`);
   }
-  return payload.server;
+  return server;
 }
 
 async function getServer(id: number): Promise<HetznerServer> {
   const response = await fetch(`${baseUrl}/servers/${id}`, { headers });
-  const payload = (await readJsonResponse(response, "Hetzner server poll")) as {
-    server?: HetznerServer;
-  };
-  if (!response.ok || !payload.server) {
+  const payload = await readJsonResponse(response, "Hetzner server poll");
+  const server = readServer(payload);
+  if (!response.ok || !server) {
     throw new Error(`Hetzner server poll failed: ${JSON.stringify(payload)}`);
   }
-  return payload.server;
+  return server;
 }
 
 let server: HetznerServer | undefined = (await listServers())[0];

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

@@ -5,8 +5,8 @@ import { derivePreviewDomain, loadPilotRegistry } from "@rizom/ops";
 import {
   parseEnvFile,
   requireEnv,
+  runtimeImageTag,
   sitePackagesFor,
-  siteImageTag,
   writeGitHubOutput,
 } from "./helpers";
 
@@ -43,12 +43,15 @@ const wwwDomain = isFleetDomain(
 
 const brainVersion = envEntries["BRAIN_VERSION"] ?? "";
 
-// The image tag is a pure function of this instance's own config: plain
-// `brain-{version}` for a default instance, or its own `brain-{version}-sites-
-// {hash}` when it declares a siteOverride. Resolved through the same helper the
-// build uses so the tag we wait for and run matches exactly what was pushed.
+// Build and deploy share one tag function. A shared fleet always resolves to
+// `brain-{version}`; an explicitly isolated fleet may include the instance's
+// exact site package set in its tag.
 const sitePackages = sitePackagesFor(user.siteOverride);
-const imageTag = siteImageTag(brainVersion, sitePackages);
+const imageTag = runtimeImageTag(
+  registry.pilot.imageContract,
+  brainVersion,
+  sitePackages,
+);
 
 const outputs: Record<string, string> = {
   brain_version: brainVersion,

package/templates/rover-pilot/deploy/scripts/update-dns.ts

@@ -16,18 +16,43 @@ interface CloudflareResult {
   result?: Array<{ id: string }>;
 }
 
+/**
+ * Copied verbatim into generated projects, so this stays dependency-free and
+ * checks the payload by hand. readJsonResponse returns unknown; asserting
+ * CloudflareResult onto it meant an error body read as `success: undefined`
+ * rather than failing here.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readCloudflareResult(payload: unknown): CloudflareResult | undefined {
+  if (!isRecord(payload)) return undefined;
+  if (typeof payload["success"] !== "boolean") return undefined;
+  const result = payload["result"];
+  if (result === undefined) return { success: payload["success"] };
+  if (
+    !Array.isArray(result) ||
+    !result.every(
+      (entry): entry is { id: string } =>
+        isRecord(entry) && typeof entry["id"] === "string",
+    )
+  ) {
+    return undefined;
+  }
+  return { success: payload["success"], result };
+}
+
 async function findRecordId(
   name: string,
   type: "A" | "CNAME",
 ): Promise<string | undefined> {
   const lookupUrl = `${baseUrl}/zones/${zoneId}/dns_records?type=${type}&name=${encodeURIComponent(name)}`;
   const lookup = await fetch(lookupUrl, { headers });
-  const payload = (await readJsonResponse(
-    lookup,
-    "Cloudflare DNS lookup",
-  )) as CloudflareResult;
-  if (!lookup.ok || !payload.success) {
-    throw new Error(`Cloudflare DNS lookup failed: ${JSON.stringify(payload)}`);
+  const raw = await readJsonResponse(lookup, "Cloudflare DNS lookup");
+  const payload = readCloudflareResult(raw);
+  if (!lookup.ok || !payload?.success) {
+    throw new Error(`Cloudflare DNS lookup failed: ${JSON.stringify(raw)}`);
   }
 
   return payload.result?.[0]?.id;
@@ -53,12 +78,10 @@ async function upsertRecord(name: string): Promise<void> {
       proxied: true,
     }),
   });
-  const result = (await readJsonResponse(
-    response,
-    "Cloudflare DNS upsert",
-  )) as CloudflareResult;
-  if (!response.ok || !result.success) {
-    throw new Error(`Cloudflare DNS upsert failed: ${JSON.stringify(result)}`);
+  const raw = await readJsonResponse(response, "Cloudflare DNS upsert");
+  const result = readCloudflareResult(raw);
+  if (!response.ok || !result?.success) {
+    throw new Error(`Cloudflare DNS upsert failed: ${JSON.stringify(raw)}`);
   }
 }
 

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

@@ -16,10 +16,12 @@ Treat these as checked-in deploy artifacts in the pilot repo:
 `.env.schema` is the single source of truth for required and sensitive deploy vars.
 The deploy scripts and workflows should read from that contract instead of inventing a second list.
 
-The default pilot image tag is `brain-${brainVersion}`:
+The pilot declares its image topology with `pilot.yaml.imageContract`:
 
-- build publishes `brain-${brainVersion}` for users without a site override
-- a site override gets an isolated `brain-${brainVersion}-sites-${packageHash}` image
+- `shared-fleet-v1` publishes one `brain-${brainVersion}` image for each effective Brain version
+- each shared image contains the union of exact site/theme package pins required by instances on that version
+- conflicting versions of one package fail image resolution before build
+- `isolated-sites-v1` is an explicit alternative for fleets that require package-isolated tags
 - generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`
 - build and deploy derive the same effective image tag from the resolved registry
 
@@ -27,7 +29,7 @@ The default pilot image tag is `brain-${brainVersion}`:
 
 When `pilot.yaml.brainVersion` changes and you push:
 
-1. build publishes the new default image and any required site images
+1. build publishes each missing version image with its declared package union
 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
@@ -260,16 +262,18 @@ siteOverride:
   themeVersion: <exact-theme-version>
 ```
 
-Missing external package versions fail desired-state validation. A site override
-produces an isolated per-instance image; it never changes the fleet's shared default
-image. Bundled `@brains/*` themes omit `themeVersion` because they are not installed as
-separate packages.
+Missing external package versions fail desired-state validation. Under
+`shared-fleet-v1`, 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.
 
 ### 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.
-3. Reconcile the canary, push the generated output, and let build/deploy create its site image.
+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.
 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.
 

package/templates/rover-pilot/pilot.yaml

@@ -1,5 +1,6 @@
 brainVersion: 0.1.1-alpha.14
 bundleContract: capability-bundles-v1
+imageContract: shared-fleet-v1
 githubOrg: <github-org>
 contentRepoPrefix: rover-
 domainSuffix: .rizom.ai