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

package/dist/schema.d.ts

@@ -28,38 +28,34 @@ export declare const profileKindSchema: z.ZodEnum<{
     team: "team";
     organization: "organization";
 }>;
-export interface PilotConfig {
-    brainVersion: string;
-    bundleContract: typeof CAPABILITY_BUNDLE_CONTRACT;
-    bundles: CanonicalBundleId[];
-    add?: string[] | undefined;
-    remove?: string[] | undefined;
-    githubOrg: string;
-    contentRepoPrefix: string;
-    domainSuffix: string;
-    aiApiKey: string;
-    gitSyncToken: string;
-    contentRepoAdminToken: string;
-    agePublicKey: string;
-}
-export interface SiteOverrideConfig {
-    package: string;
-    version: string;
-    theme?: string | undefined;
-    themeVersion?: string | undefined;
-}
-export interface CohortConfig {
-    members: string[];
-    brainVersionOverride?: string | undefined;
-    bundlesOverride?: CanonicalBundleId[] | undefined;
-    addOverride?: string[] | undefined;
-    removeOverride?: string[] | undefined;
-    aiApiKeyOverride?: string | undefined;
-    gitSyncTokenOverride?: string | undefined;
-}
+declare const canonicalBundlesSchema: z.ZodArray<typeof canonicalBundleIdSchema>;
+declare const memberIdsSchema: z.ZodArray<z.ZodString>;
 /** Sole active desired-state contract for the canonical brain. */
-export declare const pilotSchema: z.ZodType<PilotConfig>;
-export declare const cohortSchema: z.ZodType<CohortConfig>;
+export declare const pilotSchema: z.ZodObject<{
+    brainVersion: z.ZodString;
+    bundleContract: z.ZodLiteral<typeof CAPABILITY_BUNDLE_CONTRACT>;
+    bundles: typeof canonicalBundlesSchema;
+    add: z.ZodOptional<typeof memberIdsSchema>;
+    remove: z.ZodOptional<typeof memberIdsSchema>;
+    githubOrg: z.ZodString;
+    contentRepoPrefix: z.ZodString;
+    domainSuffix: z.ZodString;
+    aiApiKey: z.ZodString;
+    gitSyncToken: z.ZodString;
+    contentRepoAdminToken: z.ZodString;
+    agePublicKey: z.ZodString;
+}, z.core.$strict>;
+export type PilotConfig = z.output<typeof pilotSchema>;
+export declare const cohortSchema: z.ZodObject<{
+    members: z.ZodArray<z.ZodString>;
+    brainVersionOverride: z.ZodOptional<z.ZodString>;
+    bundlesOverride: z.ZodOptional<typeof canonicalBundlesSchema>;
+    addOverride: z.ZodOptional<typeof memberIdsSchema>;
+    removeOverride: z.ZodOptional<typeof memberIdsSchema>;
+    aiApiKeyOverride: z.ZodOptional<z.ZodString>;
+    gitSyncTokenOverride: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type CohortConfig = z.output<typeof cohortSchema>;
 declare const anchorProfileSocialLinkSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         github: "github";
@@ -109,7 +105,13 @@ declare const atprotoSchema: z.ZodObject<{
     lexiconAuthority: z.ZodOptional<z.ZodBoolean>;
     jetstream: z.ZodOptional<typeof atprotoJetstreamSchema>;
 }>;
-export declare const siteOverrideSchema: z.ZodType<SiteOverrideConfig>;
+export declare const siteOverrideSchema: z.ZodObject<{
+    package: z.ZodString;
+    version: z.ZodString;
+    theme: z.ZodOptional<z.ZodString>;
+    themeVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SiteOverrideConfig = z.output<typeof siteOverrideSchema>;
 declare const playbooksSchema: z.ZodObject<{
     onboarding: z.ZodOptional<z.ZodBoolean>;
 }>;

package/dist/stage-legacy-crossover.d.ts

@@ -1,12 +1,14 @@
+import { z } from "@brains/utils/zod";
 import { type CapabilityBundleReview } from "./capability-bundle-migration";
-import { type SiteOverrideConfig } from "./schema";
+import { siteOverrideSchema } from "./schema";
 export interface StagedCrossover {
     outputDir: string;
     changedFiles: string[];
 }
-interface ReviewedSitePinManifest {
-    sites: Record<string, SiteOverrideConfig>;
-}
+declare const reviewedSitePinsSchema: z.ZodObject<{
+    sites: z.ZodRecord<z.ZodString, typeof siteOverrideSchema>;
+}, z.core.$strict>;
+type ReviewedSitePinManifest = z.output<typeof reviewedSitePinsSchema>;
 export type ReviewedSitePins = ReviewedSitePinManifest["sites"];
 export interface StageLegacyCrossoverOptions {
     sitePins?: ReviewedSitePins | undefined;

package/package.json

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

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

@@ -8,7 +8,7 @@ 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
       overwrite:

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.
+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.
+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.
 
 ## 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

@@ -6,8 +6,7 @@ export {
   requireEnv,
   writeGitHubOutput,
   writeGitHubEnv,
-  siteImageTag,
-  sitePackagesFor,
+  runtimeImageTag,
   runResolveMissingImages,
 } from "@rizom/ops/deploy";
 export type { EnvSchemaEntry } 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,7 @@ import { derivePreviewDomain, loadPilotRegistry } from "@rizom/ops";
 import {
   parseEnvFile,
   requireEnv,
-  sitePackagesFor,
-  siteImageTag,
+  runtimeImageTag,
   writeGitHubOutput,
 } from "./helpers";
 
@@ -43,12 +42,9 @@ 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.
-const sitePackages = sitePackagesFor(user.siteOverride);
-const imageTag = siteImageTag(brainVersion, sitePackages);
+// Build and Deploy share one tag function: every instance on a Brain version
+// runs the same immutable fleet image.
+const imageTag = runtimeImageTag(brainVersion);
 
 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,11 @@ 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 fleet has one image topology:
 
-- build publishes `brain-${brainVersion}` for users without a site override
-- a site override gets an isolated `brain-${brainVersion}-sites-${packageHash}` image
+- 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
+- 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
 
@@ -27,7 +28,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,21 +261,24 @@ 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
+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.
 
 ### 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.
 
-To roll back, remove or change `siteOverride`, reconcile, and redeploy that user.
-The default image and other users remain untouched.
+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.
 
 ## Setup email checklist