catherd-cli 0.2.1 → 1.1.0

package/src/domain/profile-rules.ts

@@ -0,0 +1,239 @@
+import {
+  type Catalog,
+  capableFor,
+  effortOffered,
+  ROLE_NEEDS,
+  type RungInfo,
+  rungInfo,
+  scoresOf,
+} from "./catalog.ts";
+import {
+  catalogRungs,
+  claudeBilled,
+  downgradeDims,
+  ladderDropDims,
+  quotaOf,
+  rankStandIns,
+} from "./failover.ts";
+import { tryParseRung } from "./ids.ts";
+import { DIFFICULTIES, KINDS } from "./lane.ts";
+import { type Profile, type ProfileDoc, unknownValues } from "./profile.ts";
+import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
+import { candidates, clearsBar, type RoutingProfile } from "./select.ts";
+
+export { quotaOf };
+
+/** One finding of `validate`: where in the profile, what is wrong, and the action that fixes it. */
+export interface Issue {
+  path: string;
+  message: string;
+  fix?: string;
+}
+
+export interface Validation {
+  errors: Issue[];
+  warnings: Issue[];
+}
+
+const TREAT_LIKE_FIX = (rung: string) =>
+  `map it with: catherd catalog treat-like ${rung} <a scored rung>; catalog_query lists them`;
+
+export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
+  objective: p.objective,
+  billing: p.billing,
+  role: p.roles[role],
+});
+
+/** Whether a rung's scores are catherd's guess: borrowed through a treat-like, or only `inferred` ones. */
+export function inferredScores(c: Catalog, info: RungInfo): { inferred: boolean; via: string | null } {
+  const s = scoresOf(c, info.canonical);
+  if (!s) return { inferred: false, via: null };
+  const records = Object.values(s.records);
+  return { inferred: s.via !== null || records.every((r) => r.confidence === "inferred"), via: s.via };
+}
+
+/**
+ * Spec §7.1. Errors: the worker disabled; an enabled role with no usable rung; an unscored rung without a
+ * treat-like; a failover stand-in unscored or on the same quota; a rung whose backend catherd cannot run
+ * (`backends` lists those it can, `claude` included). Everything else worth knowing is a warning: an access
+ * mode other than the role's default, an effort or model the last listing does not offer, a stand-in
+ * that never runs, and (spec 1.1 §11) a stand-in that downgrades its rung, one that spends Claude quota
+ * while another plan could stand in, and a ladder that goes down. With the stored `doc` `p` came from, a value this catherd does not know is also a
+ * warning, one that says how the value is read.
+ */
+export function validateProfile(
+  p: Profile,
+  c: Catalog,
+  backends: readonly string[],
+  doc?: ProfileDoc,
+): Validation {
+  const errors: Issue[] = [];
+  const warnings: Issue[] = [];
+  for (const u of doc ? unknownValues(doc) : [])
+    warnings.push({
+      path: u.path,
+      message: `"${u.value}" is not a value this catherd knows (a newer one wrote it?); it is read as ${u.readAs}`,
+      fix: "upgrade catherd (bun add -g catherd-cli@latest), or set a value this version knows",
+    });
+  if (!p.roles.worker.enabled)
+    errors.push({
+      path: "roles.worker.enabled",
+      message: "the worker cannot be disabled",
+      fix: "catherd profile set roles.worker.enabled true",
+    });
+
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    const at = `roles.${role}`;
+    if (rc.access !== DEFAULT_ACCESS[role])
+      warnings.push({
+        path: `${at}.access`,
+        message: `${role} runs ${rc.access}; catherd's default for it is ${DEFAULT_ACCESS[role]}`,
+      });
+    if (!rc.enabled) continue;
+    for (const rung of rc.rungs) {
+      const r = tryParseRung(rung);
+      if (!r) {
+        errors.push({
+          path: `${at}.rungs`,
+          message: `"${rung}" is not a rung`,
+          fix: "write it as <backend>:<model>#<effort>",
+        });
+        continue;
+      }
+      if (!backends.includes(r.backend)) {
+        errors.push({
+          path: `${at}.rungs`,
+          message: `${rung}: catherd cannot run ${r.backend} yet`,
+          fix: `use a rung on ${backends.join(", ")}`,
+        });
+        continue;
+      }
+      const info = rungInfo(c, rung);
+      if (!capableFor(c, info, role))
+        errors.push({
+          path: `${at}.rungs`,
+          message: `${rung} cannot fill the ${role} role (it needs ${Object.keys(ROLE_NEEDS[role]).join(" + ")})`,
+          fix: `catalog_query({ role: "${role}" }) lists the models that can`,
+        });
+      if (info.efforts.length > 0 && !effortOffered(info))
+        errors.push({
+          path: `${at}.rungs`,
+          message: `${r.model} has no effort "${r.effort}" on ${r.backend} (it has ${info.efforts.join(", ")})`,
+        });
+      else if (info.efforts.length === 0 && r.effort !== "default")
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `${rung}: catherd cannot check its effort until ${r.backend} lists its models`,
+          fix: "catherd catalog refresh",
+        });
+      if (info.listed === false)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `${r.backend}'s last listing does not offer ${r.model}; routing skips it`,
+        });
+      if (!scoresOf(c, info.canonical))
+        errors.push({ path: `${at}.rungs`, message: `${rung} is unscored`, fix: TREAT_LIKE_FIX(rung) });
+    }
+    rc.rungs.forEach((rung, i) => {
+      const prev = rc.rungs[i - 1];
+      const down = prev === undefined ? [] : ladderDropDims(c, prev, rung);
+      if (down.length)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `the ladder goes down at ${rung}: it scores below ${prev} on ${down.join(", ")}`,
+          fix: `order ${at}.rungs weakest first`,
+        });
+    });
+    if (rc.defaultRung !== undefined && !rc.rungs.includes(rc.defaultRung))
+      errors.push({
+        path: `${at}.defaultRung`,
+        message: `${rc.defaultRung} is not one of the ${role}'s rungs`,
+        fix: `catherd profile set ${at}.defaultRung null, or add it to ${at}.rungs`,
+      });
+    const usable = candidates(c, routingProfileOf(p, role), role);
+    if (usable.length === 0)
+      errors.push({
+        path: `${at}.rungs`,
+        message: `the ${role} role has no usable rung`,
+        fix: `enable a scored rung its backend offers, or turn the role off with: catherd profile set ${at}.enabled false`,
+      });
+    if (usable.length > 1)
+      // Claude rungs have no honesty score, so they clear no shipped bar: select() starts on one only as the
+      // default rung (when nothing clears) and never climbs onto it
+      for (const x of usable)
+        if (
+          quotaOf(x.info.parsed) === "claude-code" &&
+          !KINDS.some((k) => DIFFICULTIES.some((d) => clearsBar(c, x, k, d)))
+        )
+          warnings.push({
+            path: `${at}.rungs`,
+            message: `${x.rung} clears no routing bar, so a lane starts on it only as the role's default rung and never climbs onto it`,
+          });
+    if (role === "worker" && usable.length > 1) {
+      const missed = KINDS.flatMap((k) =>
+        DIFFICULTIES.filter((d) => !usable.some((x) => clearsBar(c, x, k, d))).map((d) => `${k}/${d}`),
+      );
+      if (missed.length)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `no worker rung clears the bar for ${missed.join(", ")}; those lanes start at the default rung`,
+        });
+    }
+  }
+
+  const ladders = new Set(ROLES.filter((r) => p.roles[r].enabled).flatMap((r) => p.roles[r].rungs));
+  // the stand-ins catherd could run here, for the fixes below
+  const pool = catalogRungs(c).filter((x) => {
+    const r = tryParseRung(x);
+    return r !== null && backends.includes(r.backend);
+  });
+  for (const [from, to] of Object.entries(p.failover)) {
+    const at = `failover.${from}`;
+    const a = tryParseRung(from);
+    const b = tryParseRung(to);
+    if (!a || !b) {
+      errors.push({
+        path: at,
+        message: `"${!a ? from : to}" is not a rung`,
+        fix: "write it as <backend>:<model>#<effort>",
+      });
+      continue;
+    }
+    if (!backends.includes(b.backend)) {
+      errors.push({ path: at, message: `stand-in ${to}: catherd cannot run ${b.backend} yet` });
+      continue;
+    }
+    if (!scoresOf(c, rungInfo(c, to).canonical))
+      errors.push({ path: at, message: `stand-in ${to} is unscored`, fix: TREAT_LIKE_FIX(to) });
+    if (quotaOf(a) === quotaOf(b))
+      errors.push({
+        path: at,
+        message: `stand-in ${to} draws on the same quota as ${from}, which is out when ${from} hits its limit`,
+        fix: "name a stand-in on another backend or plan",
+      });
+    const ranked = rankStandIns(c, p.billing, from, pool);
+    const down = downgradeDims(c, from, to);
+    if (down.length)
+      warnings.push({
+        path: at,
+        message: `downgrade: ${to} stands in for ${from}, scoring below it on ${down.join(", ")}`,
+        fix: `catherd profile set failover.${from} ${ranked[0] ?? "null"}`,
+      });
+    const other = ranked.find((x) => !claudeBilled(x));
+    if (claudeBilled(to) && other)
+      warnings.push({
+        path: at,
+        message: `stand-in ${to} spends Claude quota, while ${other} could stand in on another plan`,
+        fix: `catherd profile set failover.${from} ${other}`,
+      });
+    if (b.backend === "claude")
+      warnings.push({
+        path: at,
+        message: `stand-in ${to} is a native subagent: the orchestrator must start it, dispatch cannot`,
+      });
+    if (!ladders.has(from))
+      warnings.push({ path: at, message: `${from} is on no enabled role's ladder, so this never runs` });
+  }
+  return { errors, warnings };
+}

package/src/domain/profile.ts

@@ -0,0 +1,389 @@
+import { z } from "zod";
+import type { Budget } from "./budget.ts";
+import { BILLING_KEYS, type BillingKey } from "./catalog.ts";
+import { BILLING_MODES, type BillingMode, DEFAULT_BILLING } from "./cost.ts";
+import { CatherdError } from "./errors.ts";
+import { ADAPTER_IDS, parseRung, tryParseRung } from "./ids.ts";
+import { ACCESS, type Access } from "./record.ts";
+import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
+import { isPlain, slug } from "./util.ts";
+
+/** Spec §3.4: every file carries its schema version; a profile is schema 1. */
+const PROFILE_SCHEMA = 1;
+
+/** Profile names end up in agent names (`catherd-<profile>-…`), which Claude Code wants lowercase. */
+export const PROFILE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+export function assertProfileName(name: string): string {
+  if (!PROFILE_NAME.test(name))
+    throw new CatherdError("E_INPUT_INVALID", `bad profile name "${name}"`, {
+      fix: "use lowercase letters, digits and '-', at most 32, starting with a letter or digit",
+    });
+  return name;
+}
+
+export const NOTIFY = ["milestone", "finish", "blocked"] as const;
+export type NotifyMoment = (typeof NOTIFY)[number];
+
+/** The harnesses a profile can isolate (spec §7.1 `harness`); the native `claude` path has none. */
+export const HARNESS_KEYS = ADAPTER_IDS;
+
+const isRung = (s: string): boolean => tryParseRung(s) !== null;
+/** A `<backend>:<model>#<effort>` rung, for input schemas; stored profiles keep any string and validate. */
+const RungSchema = z.string().refine(isRung, "a rung is <backend>:<model>#<effort>");
+
+const positive = z.number().positive();
+
+// Stored files: every level is loose, so fields a newer catherd wrote survive a rewrite (spec §3.4), and
+// rung strings are checked by validateProfile rather than making the whole file unreadable. The same holds
+// for values: a stored enum takes any string, resolveProfile reads one it does not know as STORED_FALLBACK
+// says, validateProfile warns, and the file keeps it.
+const RoleDocSchema = z.looseObject({
+  enabled: z.boolean().optional(),
+  access: z.string().optional(),
+  rungs: z.array(z.string()).optional(),
+  defaultRung: z.string().optional(),
+  network: z.boolean().optional(),
+});
+
+export const ProfileDocSchema = z.looseObject({
+  schema: z.literal(PROFILE_SCHEMA),
+  name: z.string().optional(),
+  objective: z.string().optional(),
+  jev: z.looseObject({ use: z.string().optional() }).optional(),
+  billing: z.record(z.string(), z.string()).optional(),
+  roles: z.record(z.string(), RoleDocSchema).optional(),
+  harness: z.record(z.string(), z.looseObject({ isolated: z.boolean().optional() })).optional(),
+  failover: z.record(z.string(), z.string()).optional(),
+  budget: z
+    .looseObject({ minutes: positive.optional(), tokens: positive.optional(), usd: positive.optional() })
+    .optional(),
+  timeouts: z.looseObject({ idleMin: positive.optional(), wallMin: positive.optional() }).optional(),
+  preflight: z.looseObject({ confirm: z.boolean().optional() }).optional(),
+  lock: z
+    .looseObject({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]).optional() })
+    .optional(),
+  notify: z.array(z.string()).optional(),
+});
+export type ProfileDoc = z.infer<typeof ProfileDocSchema>;
+
+const OBJECTIVES = ["cost", "speed"] as const;
+const JEV_USES = ["auto", "off"] as const;
+const known = <T extends string>(values: readonly T[], v: string | undefined): v is T =>
+  v !== undefined && (values as readonly string[]).includes(v);
+
+/**
+ * How a stored value this catherd does not know (a newer one wrote it) is read, always the cautious way:
+ * access as read-only, billing as the key's default mode, Jev as off, so nothing is sent or written that
+ * the value may not allow; an unknown notify moment is skipped.
+ */
+const STORED_FALLBACK = {
+  objective: "cost",
+  jevUse: "off",
+  access: "read-only",
+  billing: (key: string): BillingMode => DEFAULT_BILLING[key as BillingKey] ?? "metered",
+} as const;
+
+/** A stored value this catherd does not know, with what it is read as. */
+export interface UnknownValue {
+  path: string;
+  value: string;
+  readAs: string;
+}
+
+/** Every stored enum value in `doc` this catherd does not know (spec §3.4: newer files stay readable). */
+export function unknownValues(doc: ProfileDoc): UnknownValue[] {
+  const out: UnknownValue[] = [];
+  const check = (path: string, values: readonly string[], v: string | undefined, readAs: string) => {
+    if (v !== undefined && !values.includes(v)) out.push({ path, value: v, readAs });
+  };
+  check("objective", OBJECTIVES, doc.objective, STORED_FALLBACK.objective);
+  check("jev.use", JEV_USES, doc.jev?.use, STORED_FALLBACK.jevUse);
+  for (const [k, v] of Object.entries(doc.billing ?? {}))
+    check(`billing.${k}`, BILLING_MODES, v, STORED_FALLBACK.billing(k));
+  for (const role of ROLES)
+    check(`roles.${role}.access`, ACCESS, doc.roles?.[role]?.access, STORED_FALLBACK.access);
+  for (const n of doc.notify ?? []) check("notify", NOTIFY, n, "skipped");
+  return out;
+}
+
+// a type, not an interface, so the built-in roles can be written into a loose (indexed) document
+export type RoleConfig = {
+  enabled: boolean;
+  access: Access;
+  /** in ladder order, each `backend:model#effort`; `claude:` runs as a native subagent, `claude-code:` headless */
+  rungs: string[];
+  defaultRung?: string;
+  /** spec §5: false drops a workspace-write role's network, loopback and Docker grants; absent means granted */
+  network?: false;
+};
+
+/** A profile with every default filled in: what the run engine, the CLI and the agent files read. */
+export interface Profile {
+  name: string;
+  objective: "cost" | "speed";
+  jev: { use: "auto" | "off" };
+  billing: Record<string, BillingMode>;
+  roles: Record<Role, RoleConfig>;
+  harness: Record<string, { isolated: boolean }>;
+  failover: Record<string, string>;
+  budget: Budget;
+  timeouts: { idleMin: number; wallMin: number };
+  preflight: { confirm: boolean };
+  lock: { heavy: number | "cpus/2" };
+  notify: NotifyMoment[];
+}
+
+const LUNA_HIGH = "codex:gpt-6-luna#high";
+const SOL = (effort: string) => `codex:gpt-6-sol#${effort}`;
+
+/**
+ * Spec §7.2, the owner's setup (Codex on a ChatGPT plan, a Claude plan, OpenCode Go). A role missing
+ * from a profile takes its entry here. Architect and verifier run as native Claude subagents (D3).
+ */
+export const BUILTIN_ROLES: Record<Role, RoleConfig> = {
+  architect: { enabled: true, access: DEFAULT_ACCESS.architect, rungs: ["claude:claude-opus-5-5#high"] },
+  verifier: { enabled: true, access: DEFAULT_ACCESS.verifier, rungs: ["claude:claude-opus-5-5#low"] },
+  worker: {
+    enabled: true,
+    access: DEFAULT_ACCESS.worker,
+    rungs: [LUNA_HIGH, SOL("medium"), SOL("high"), SOL("xhigh")],
+    defaultRung: SOL("medium"),
+  },
+  reviewer: { enabled: true, access: DEFAULT_ACCESS.reviewer, rungs: [SOL("high")] },
+  "ui-reviewer": { enabled: true, access: DEFAULT_ACCESS["ui-reviewer"], rungs: [SOL("medium")] },
+  artist: { enabled: true, access: DEFAULT_ACCESS.artist, rungs: [SOL("medium")] },
+  writer: { enabled: true, access: DEFAULT_ACCESS.writer, rungs: [LUNA_HIGH] },
+  researcher: { enabled: true, access: DEFAULT_ACCESS.researcher, rungs: [LUNA_HIGH] },
+};
+
+/**
+ * Spec 1.1 §11: each shipped worker rung fails over to the best stand-in the shipped catalog offers
+ * (`rankStandIns` over `catalogRungs`, pinned by test/domain/failover.test.ts): on another quota, paid
+ * from a plan, and no downgrade on the dims the rung's bars use. Go serves GPT-6 Luna itself; Kimi K3
+ * borrows Sol medium's scores (a shipped treat-like). Sol high and xhigh have no such stand-in on the
+ * owner's plans, so they have none: a limit on them pauses the lane instead of dropping it a tier.
+ */
+export const DEFAULT_FAILOVER: Record<string, string> = {
+  [LUNA_HIGH]: "opencode:opencode-go/gpt-6-luna#high",
+  [SOL("medium")]: "opencode:opencode-go/kimi-k3#max",
+};
+
+/** The five billing keys spec §7.1 writes out; cursor and grok arrive with their backends. */
+const WRITTEN_BILLING: BillingKey[] = ["codex", "claude", "claude-code", "opencode-go", "opencode"];
+
+/** The full default profile document, every field written out: what `init` and `profile new` save. */
+export function defaultProfileDoc(name = "default"): ProfileDoc {
+  return {
+    schema: PROFILE_SCHEMA,
+    name,
+    objective: "cost",
+    jev: { use: "auto" },
+    billing: Object.fromEntries(WRITTEN_BILLING.map((k) => [k, DEFAULT_BILLING[k]])),
+    roles: structuredClone(BUILTIN_ROLES),
+    harness: {
+      codex: { isolated: false },
+      "claude-code": { isolated: false },
+      opencode: { isolated: false },
+    },
+    failover: { ...DEFAULT_FAILOVER },
+    budget: {},
+    timeouts: { idleMin: 15, wallMin: 90 },
+    preflight: { confirm: false },
+    lock: { heavy: "cpus/2" },
+    notify: [...NOTIFY],
+  };
+}
+
+/** Spec §7.1: every field a document leaves out takes its default; a missing role takes the built-in one. */
+export function resolveProfile(doc: ProfileDoc, name: string): Profile {
+  const roles = {} as Record<Role, RoleConfig>;
+  for (const role of ROLES) {
+    const d = doc.roles?.[role];
+    const b = BUILTIN_ROLES[role];
+    // a role that lists its own rungs never inherits the built-in default rung, which may not be among them
+    const defaultRung = d?.defaultRung ?? (d?.rungs === undefined ? b.defaultRung : undefined);
+    roles[role] = {
+      enabled: d?.enabled ?? b.enabled,
+      access:
+        d?.access === undefined
+          ? DEFAULT_ACCESS[role]
+          : known(ACCESS, d.access)
+            ? d.access
+            : STORED_FALLBACK.access,
+      rungs: [...(d?.rungs ?? b.rungs)],
+      ...(defaultRung ? { defaultRung } : {}),
+      ...(d?.network === false ? { network: false as const } : {}),
+    };
+  }
+  const harness: Profile["harness"] = {};
+  for (const k of new Set([...HARNESS_KEYS, ...Object.keys(doc.harness ?? {})]))
+    harness[k] = { isolated: doc.harness?.[k]?.isolated ?? false };
+  const budget: Budget = {};
+  for (const k of ["minutes", "tokens", "usd"] as const) {
+    const v = doc.budget?.[k];
+    if (v !== undefined) budget[k] = v;
+  }
+  const billing: Record<string, BillingMode> = { ...DEFAULT_BILLING };
+  for (const [k, v] of Object.entries(doc.billing ?? {}))
+    billing[k] = known(BILLING_MODES, v) ? v : STORED_FALLBACK.billing(k);
+  const use = doc.jev?.use;
+  return {
+    name,
+    objective: known(OBJECTIVES, doc.objective) ? doc.objective : STORED_FALLBACK.objective,
+    jev: { use: use === undefined ? "auto" : known(JEV_USES, use) ? use : STORED_FALLBACK.jevUse },
+    billing,
+    roles,
+    harness,
+    failover: { ...doc.failover },
+    budget,
+    timeouts: { idleMin: doc.timeouts?.idleMin ?? 15, wallMin: doc.timeouts?.wallMin ?? 90 },
+    preflight: { confirm: doc.preflight?.confirm ?? false },
+    lock: { heavy: doc.lock?.heavy ?? "cpus/2" },
+    notify: doc.notify === undefined ? [...NOTIFY] : doc.notify.filter((n) => known(NOTIFY, n)),
+  };
+}
+
+/** Spec §7.3: `catherd-<profile>-<role>-<model slug>-<effort>`, the native subagent for a `claude:` rung. */
+export function agentName(profile: string, role: Role, rung: string): string {
+  const r = parseRung(rung);
+  return `catherd-${profile}-${role}-${slug(r.model)}-${slug(r.effort)}`;
+}
+
+// Patches: what profile_set and `catherd profile set` accept. Strict at every level, so a misspelt key is
+// refused with E_INPUT_INVALID instead of dropped (plan-2 review m9). `null` removes a map entry or a nullable
+// field (a role's `network` among them: absent means granted).
+const RolePatchSchema = z
+  .strictObject({
+    enabled: z.boolean(),
+    access: z.enum(ACCESS),
+    rungs: z.array(RungSchema),
+    defaultRung: RungSchema.nullable(),
+    network: z.boolean().nullable(),
+  })
+  .partial();
+
+export const ProfilePatchSchema = z.strictObject({
+  objective: z.enum(["cost", "speed"]).optional(),
+  jev: z.strictObject({ use: z.enum(["auto", "off"]) }).optional(),
+  billing: z.partialRecord(z.enum(BILLING_KEYS), z.enum(BILLING_MODES).nullable()).optional(),
+  roles: z.partialRecord(z.enum(ROLES), RolePatchSchema).optional(),
+  harness: z.partialRecord(z.enum(HARNESS_KEYS), z.strictObject({ isolated: z.boolean() })).optional(),
+  failover: z.record(RungSchema, RungSchema.nullable()).optional(),
+  budget: z
+    .strictObject({ minutes: positive.nullable(), tokens: positive.nullable(), usd: positive.nullable() })
+    .partial()
+    .optional(),
+  timeouts: z.strictObject({ idleMin: positive, wallMin: positive }).partial().optional(),
+  preflight: z.strictObject({ confirm: z.boolean() }).optional(),
+  lock: z.strictObject({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]) }).optional(),
+  notify: z.array(z.enum(NOTIFY)).optional(),
+});
+export type ProfilePatch = z.infer<typeof ProfilePatchSchema>;
+
+/** RFC 7396 merge: objects merge key by key, `null` deletes, anything else (arrays too) replaces. */
+function mergePatch(target: unknown, patch: unknown): unknown {
+  if (!isPlain(patch)) return patch;
+  const out: Record<string, unknown> = isPlain(target) ? { ...target } : {};
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null) delete out[k];
+    else out[k] = mergePatch(out[k], v);
+  }
+  return out;
+}
+
+/** The document with `patch` applied; every field the patch does not name, known or not, is kept. */
+export function applyPatch(doc: ProfileDoc, patch: ProfilePatch): ProfileDoc {
+  return ProfileDocSchema.parse(mergePatch(doc, patch));
+}
+
+/** Map fields whose keys are rungs or billing keys, which may hold dots: the rest of the path is one key. */
+const MAP_FIELDS = new Set(["failover", "billing"]);
+const LIST_FIELDS = (keys: string[]) =>
+  (keys[0] === "roles" && keys[2] === "rungs") || (keys[0] === "notify" && keys.length === 1);
+
+/**
+ * `catherd profile set <path> <value>` as a patch. The value is JSON when it parses (numbers, booleans,
+ * `null`, arrays), else the plain word; a rung list may also be comma-separated.
+ */
+export function patchAt(path: string, raw: string): ProfilePatch {
+  const segs = path.split(".");
+  const keys =
+    MAP_FIELDS.has(segs[0] ?? "") && segs.length > 1 ? [segs[0] as string, segs.slice(1).join(".")] : segs;
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    value = raw;
+  }
+  if (LIST_FIELDS(keys) && typeof value === "string")
+    value = value
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  const patch = keys.reduceRight<unknown>((inner, k) => ({ [k]: inner }), value);
+  const r = keys.some((k) => !k) ? null : ProfilePatchSchema.safeParse(patch);
+  if (!r?.success)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `cannot set ${path} to ${raw}${r ? `: ${z.prettifyError(r.error).replace(/\n\s*/g, " ")}` : ""}`,
+      {
+        fix: "catherd profile show --json lists the fields; e.g. catherd profile set roles.worker.access read-only",
+      },
+    );
+  return r.data;
+}
+
+export interface Change {
+  path: string;
+  before: unknown;
+  after: unknown;
+}
+
+/** Leaves by dotted path; an empty object has none, so `budget: {}` → `budget.usd: 5` is one change. */
+function flatten(v: unknown, prefix: string, out: Map<string, unknown>): void {
+  if (isPlain(v)) for (const [k, x] of Object.entries(v)) flatten(x, prefix ? `${prefix}.${k}` : k, out);
+  else if (v !== undefined) out.set(prefix, v);
+}
+
+/** Every leaf that differs between two profiles; lists compare whole. */
+export function diffProfiles(a: Profile, b: Profile): Change[] {
+  const fa = new Map<string, unknown>();
+  const fb = new Map<string, unknown>();
+  flatten({ ...a, name: undefined }, "", fa);
+  flatten({ ...b, name: undefined }, "", fb);
+  const changes: Change[] = [];
+  for (const path of [...new Set([...fa.keys(), ...fb.keys()])].sort()) {
+    const before = fa.get(path) ?? null;
+    const after = fb.get(path) ?? null;
+    if (JSON.stringify(before) !== JSON.stringify(after)) changes.push({ path, before, after });
+  }
+  return changes;
+}
+
+/**
+ * The patch that turns `a` into `b`: the leaves that differ, lists whole, a removed key as `null`. Fields
+ * both documents share unchanged, known or not, are left out, so applying it over a newer copy of `a`
+ * keeps whatever else changed there. Throws E_INPUT_INVALID when `b` holds what no patch may set.
+ */
+export function patchBetween(a: ProfileDoc, b: ProfileDoc): ProfilePatch {
+  const diff = (x: unknown, y: unknown): unknown => {
+    if (!isPlain(x) || !isPlain(y)) return y;
+    const out: Record<string, unknown> = {};
+    for (const k of new Set([...Object.keys(x), ...Object.keys(y)])) {
+      if (!(k in y)) out[k] = null;
+      else if (JSON.stringify(x[k]) !== JSON.stringify(y[k])) out[k] = diff(x[k], y[k]);
+    }
+    return out;
+  };
+  const r = ProfilePatchSchema.safeParse(diff(a, b));
+  if (!r.success)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `these changes cannot be saved: ${z.prettifyError(r.error).replace(/\n\s*/g, " ")}`,
+      {
+        fix: "undo the last change, or edit the field with catherd profile set",
+      },
+    );
+  return r.data;
+}