catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/domain/profile-rules.ts

@@ -1,30 +1,42 @@
 import type { OrchestrationHost } from "./host.ts";
+import { type Bars, barInversions, barOf, effectiveBars, percentilesOf } from "./bars.ts";
+import { type Catalog, capableFor, effortOffered, ROLE_NEEDS, rungInfo } from "./catalog.ts";
 import {
-  type Catalog,
-  type Dim,
-  capableFor,
-  effortOffered,
-  ROLE_NEEDS,
-  type RungInfo,
-  rungInfo,
-  scoresOf,
-} from "./catalog.ts";
-import {
-  catalogRungs,
+  catalogPairs,
   claudeBilled,
-  downgradeDims,
-  ladderDropDims,
+  downgrade,
+  intelligenceOf,
+  ladderDrop,
   quotaOf,
   rankStandIns,
 } from "./failover.ts";
-import { tryParseRung } from "./ids.ts";
-import { DIFFICULTIES, KINDS } from "./lane.ts";
+import { effortRank, tryParseRung } from "./ids.ts";
+import { DIFFICULTIES, type Difficulty } 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";
+import {
+  type Candidate,
+  candidates,
+  CODING_FLOOR,
+  CODING_ROLES,
+  clearsBar,
+  defaultLadder,
+  type RoutingProfile,
+  select,
+} from "./select.ts";
 
 export { quotaOf };
 
+/**
+ * `reach`: also warn about the difficulties no worker rung clears (spec 1.5 plan 24), which only an explicit
+ * `profile validate` asks for. `unindexed: "warning"` (doctor's) reads a rung with no Slopalytics index as a
+ * warning, since a profile can lose a pair overnight; everywhere else it is an error.
+ */
+export interface ValidateOptions {
+  reach?: boolean;
+  unindexed?: "error" | "warning";
+}
+
 /** One finding of `validate`: where in the profile, what is wrong, and the action that fixes it. */
 export interface Issue {
   path: string;
@@ -37,10 +49,8 @@ export interface Validation {
   warnings: Issue[];
 }
 
-const TREAT_LIKE_FIX = (rung: string) =>
-  `map it with: catherd catalog treat-like ${rung} <a scored rung>; catalog_query lists them`;
-const SUGGEST_FIX = (rung: string) =>
-  `confirm or replace it: catherd catalog treat-like --suggest ${rung}, then catherd catalog treat-like ${rung} <a rung>`;
+const SYNC_FIX = "catherd catalog sync";
+const unindexedMessage = (rung: string) => `${rung} has no Slopalytics intelligence index: routing skips it`;
 
 /** Spec 1.2 §6.2: two findings are the same one when they name the same path with the same message. */
 const sameIssue = (a: Issue, b: Issue): boolean => a.path === b.path && a.message === b.message;
@@ -57,89 +67,23 @@ export function repairs(before: Validation | null, after: Validation): boolean {
   return removed && !added;
 }
 
-/** Spec 1.2 §6.1 "stand-in to confirm": a rung whose values on some bar dimensions are an inferred stand-in's. */
-export interface StandInToConfirm {
-  canonical: string;
-  /** the profile's rungs that run it, and where the first one is */
-  rungs: string[];
-  path: string;
-  dims: { dim: Dim; like: string }[];
-}
-
-/**
- * Spec 1.2 §6.1: the profile's rungs that lean on an inferred stand-in, one entry per canonical rung. Only
- * where bars choose: rungs of a role with more than one usable rung, and failover stand-ins; a role with one
- * rung runs it whatever the bars say (plan 14 Ruling 13).
- */
-export function standInsToConfirm(p: Profile, c: Catalog, backends: readonly string[]): StandInToConfirm[] {
-  const seen = new Map<string, StandInToConfirm>();
-  const add = (rung: string, path: string) => {
-    const r = tryParseRung(rung);
-    if (!r || !backends.includes(r.backend)) return;
-    const info = rungInfo(c, rung);
-    const s = scoresOf(c, info.canonical);
-    if (!s || s.inferred.length === 0) return;
-    const had = seen.get(info.canonical);
-    if (had) {
-      if (!had.rungs.includes(rung)) had.rungs.push(rung);
-      return;
-    }
-    const dims = s.inferred.map((dim) => ({ dim, like: s.standIns[dim] as string }));
-    seen.set(info.canonical, { canonical: info.canonical, rungs: [rung], path, dims });
-  };
-  for (const role of ROLES) {
-    const rc = p.roles[role];
-    if (!rc.enabled || candidates(c, routingProfileOf(p, role), role).length < 2) continue;
-    for (const rung of rc.rungs) add(rung, `roles.${role}.rungs`);
-  }
-  for (const [from, to] of Object.entries(p.failover)) add(to, `failover.${from}`);
-  return [...seen.values()];
-}
-
-/** One "stand-in to confirm" warning's words. */
-export function standInMessage(x: StandInToConfirm): string {
-  const words = (xs: string[]) =>
-    xs.length < 3 ? xs.join(" or ") : `${xs.slice(0, -1).join(", ")} or ${xs.at(-1)}`;
-  const lent = x.dims.map((d) => `${d.like}'s ${d.dim}`).join(", ");
-  const also = x.rungs.length > 1 ? ` (${x.rungs.join(", ")})` : "";
-  return `stand-in to confirm: ${x.canonical}${also} has no ${words(x.dims.map((d) => d.dim))} value of its own; routing uses ${lent} (inferred)`;
-}
-
 export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
   objective: p.objective,
   billing: p.billing,
   role: p.roles[role],
+  maxEffort: p.maxEffort,
+  bars: { ...p.bars, ...p.roles[role].bars },
 });
 
-/**
- * Whether a rung's scores are catherd's guess: borrowed through a treat-like, filled by an inferred stand-in
- * (spec 1.2 §6.1), or only `inferred` ones. `note` says what a treat-like lends: "scores borrowed from X"
- * when the rung has no value of its own, else the dimensions it borrows (a rung a sync scored on some).
- */
-export function inferredScores(
-  c: Catalog,
-  info: RungInfo,
-): { inferred: boolean; via: string | null; note: string | null } {
-  const s = scoresOf(c, info.canonical);
-  if (!s) return { inferred: false, via: null, note: null };
-  const records = Object.values(s.records);
-  const guessed =
-    s.via !== null || s.inferred.length > 0 || records.every((r) => r.confidence === "inferred");
-  const all = s.borrowed.length + s.inferred.length === records.length;
-  const note = s.via ? `${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}` : null;
-  return { inferred: guessed, via: s.via, note };
-}
-
 /**
  * Spec §7.1. Errors: the worker disabled; an enabled role with no usable rung; a failover stand-in 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, (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, and (spec 1.2 §6.1) an unscored rung or stand-in, never an error: a rung that leans on an inferred
- * stand-in is a "stand-in to confirm", and one with no value and no stand-in is skipped by routing. 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.
+ * down. A rung or stand-in with no Slopalytics index is an error (spec 2.0 decision 12; a warning with
+ * `o.unindexed: "warning"`): routing skips it. 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,
@@ -147,6 +91,7 @@ export function validateProfile(
   backends: readonly string[],
   doc?: ProfileDoc,
   host: OrchestrationHost = "unknown",
+  o: ValidateOptions = {},
 ): Validation {
   const errors: Issue[] = [];
   const warnings: Issue[] = [];
@@ -163,6 +108,21 @@ export function validateProfile(
       fix: "catherd profile set roles.worker.enabled true",
     });
 
+  // a harder difficulty's percentile below an easier one's would route a harder lane to a weaker rung
+  const barOrder = (at: string, bars: Bars): void => {
+    const eff = effectiveBars({ bars });
+    for (const [easier, harder] of barInversions(eff))
+      errors.push({
+        path: at,
+        message: `the ${harder} bar (${eff[harder]}) is below the ${easier} bar (${eff[easier]})`,
+        fix: `catherd profile set ${at}.${harder} ${eff[easier]}, or lower ${at}.${easier} to ${eff[harder]} or less`,
+      });
+  };
+  barOrder("bars", p.bars);
+  for (const role of ROLES)
+    if (Object.keys(p.roles[role].bars ?? {}).length > 0)
+      barOrder(`roles.${role}.bars`, { ...p.bars, ...p.roles[role].bars });
+
   for (const role of ROLES) {
     const rc = p.roles[role];
     const at = `roles.${role}`;
@@ -172,6 +132,14 @@ export function validateProfile(
         message: `${role} runs ${rc.access}; catherd's default for it is ${DEFAULT_ACCESS[role]}`,
       });
     if (!rc.enabled) continue;
+    // spec §5: network: false takes a workspace-write role's network grants; read-only and full have none to take
+    if (rc.network === false && rc.access !== "workspace-write")
+      warnings.push({
+        path: `${at}.network`,
+        message: `network: false does nothing here: it applies to workspace-write roles, and ${role} runs ${rc.access}`,
+        fix: `catherd profile set ${at}.network null`,
+      });
+    let unindexed = 0;
     for (const rung of rc.rungs) {
       const native = nativeClaudeIssue(rung, host, `${at}.rungs`);
       if (native) errors.push(native);
@@ -184,6 +152,18 @@ export function validateProfile(
         });
         continue;
       }
+      const above = aboveCeiling(p.maxEffort, rung, `${at}.rungs`);
+      if (above) warnings.push(above);
+      if (
+        CODING_ROLES.includes(role) &&
+        effortRank(r.effort) >= 0 &&
+        effortRank(r.effort) < effortRank(CODING_FLOOR)
+      )
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `${rung} is below ${CODING_FLOOR} effort: a coding worker never runs it`,
+          fix: `pick #${CODING_FLOOR} or above: catherd catalog list --role ${role}`,
+        });
       if (!backends.includes(r.backend)) {
         errors.push({
           path: `${at}.rungs`,
@@ -199,36 +179,31 @@ export function validateProfile(
           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))
+      if (info.listed === true && !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({
+      else if (!info.pair) {
+        unindexed++;
+        (o.unindexed === "warning" ? warnings : errors).push({
           path: `${at}.rungs`,
-          message: `${rung}: catherd cannot check its effort until ${r.backend} lists its models`,
-          fix: "catherd catalog refresh",
+          message: unindexedMessage(rung),
+          fix: c.indexedAt === null ? SYNC_FIX : `pick an indexed pair: catherd catalog list --role ${role}`,
         });
+      }
       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))
-        warnings.push({
-          path: `${at}.rungs`,
-          message: `${rung} is unscored and no rung is near enough to stand in for it: routing skips it`,
-          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)
+      if (prev !== undefined && ladderDrop(c, prev, rung))
         warnings.push({
           path: `${at}.rungs`,
-          message: `the ladder goes down at ${rung}: it scores below ${prev} on ${down.join(", ")}`,
+          message: `the ladder goes down at ${rung}: intelligence ${(intelligenceOf(c, rung) as number).toFixed(1)} below ${prev}'s ${(intelligenceOf(c, prev) as number).toFixed(1)}`,
           fix: `order ${at}.rungs weakest first`,
         });
     });
@@ -240,41 +215,62 @@ export function validateProfile(
       });
     const usable = candidates(c, routingProfileOf(p, role), role);
     if (usable.length === 0)
-      errors.push({
+      // doctor's mode: rungs that are only unindexed are the same warning, so the role's total is one too, but
+      // only when an index exists: with none (not fetched, corrupt, empty) nothing can route, which is an error
+      (o.unindexed === "warning" &&
+      c.indexedAt !== null &&
+      Object.keys(c.index).length > 0 &&
+      unindexed > 0 &&
+      unindexed === rc.rungs.length
+        ? warnings
+        : 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`,
+        fix: `enable an indexed 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`,
-          });
-    // spec 1.2 §5.2: the logic and hard bars sit at the 60th and 75th percentiles, which a cost-minded ladder
-    // may never reach, and those lanes start at the default rung and climb; only a kind whose every bar the
-    // ladder misses routes blind (plan 14 Ruling 12)
+    // spec 1.5 plan 24: every difficulty no worker rung clears, in one warning; those lanes start at the
+    // default rung (or an easier difficulty's start) and climb only onto rungs at least as intelligent. Only an
+    // explicit validate says it (Ruling 3): the shipped bars put logic and hard above every Sol rung, the
+    // owner's call, so every save and doctor would repeat it
+    if (o.reach && role === "worker" && usable.length > 1) {
+      const unreached = unreachable(c, usable, percentilesOf(routingProfileOf(p, role)));
+      if (unreached.length)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `no worker rung clears ${unreached.join(", ")}: those lanes start at the default rung and climb only onto rungs at least as intelligent (route names the closest)`,
+        });
+    }
+    // spec 1.5 plan 24: a quota whose rungs never start a lane sits idle but for climbs (the identity run's Go).
+    // Only the worker routes lanes and climbs (Ruling 9); another role routes lane-less to one rung, so a rung
+    // on a second quota is a deliberate spare there, not an idle quota (final review Important 4, Ruling 8)
     if (role === "worker" && usable.length > 1) {
-      const blind = KINDS.filter((k) => !DIFFICULTIES.some((d) => usable.some((x) => clearsBar(c, x, k, d))));
-      if (blind.length)
+      const idle = idleQuotas(c, p, role, usable);
+      for (const [q, rungs] of idle) {
+        // the billing key, not the quota, is what billing is set on (`claude:` and `claude-code:` share one)
+        const keys = [...new Set(usable.filter((x) => rungs.includes(x.rung)).map((x) => x.info.key))];
         warnings.push({
           path: `${at}.rungs`,
-          message: `no worker rung clears any bar for ${blind.join(", ")}; those lanes always start at the default rung`,
+          message: `${q} never starts a ${role} lane: ${rungs.join(", ")} ${rungs.length > 1 ? "run" : "runs"} only on a climb, since another rung starts every lane`,
+          fix: `check ${keys.map((k) => `billing.${k}`).join(" and ")} (a metered rung starts only where nothing paid from a plan clears the bar), or order ${at}.rungs so its rungs come first among equals`,
         });
+      }
     }
   }
 
   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) => {
+  // the stand-ins the fixes below may suggest: on a backend catherd runs and the profile already names (a
+  // ladder or a failover entry), never one this machine may not have (Cursor on a machine without it); a
+  // native claude: rung names claude-code too, the same Claude Code CLI
+  const named = new Set(
+    [...ladders, ...Object.keys(p.failover), ...Object.values(p.failover)].flatMap((x) => {
+      const b = tryParseRung(x)?.backend;
+      return b === undefined ? [] : b === "claude" ? [b, "claude-code"] : [b];
+    }),
+  );
+  const pool = catalogPairs(c).filter((x) => {
     const r = tryParseRung(x);
-    return r !== null && backends.includes(r.backend);
+    return r !== null && backends.includes(r.backend) && named.has(r.backend);
   });
   for (const [from, to] of Object.entries(p.failover)) {
     const at = `failover.${from}`;
@@ -290,15 +286,19 @@ export function validateProfile(
       });
       continue;
     }
+    const above = aboveCeiling(p.maxEffort, to, at);
+    if (above) warnings.push(above);
     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))
-      warnings.push({
+    const ranked = rankStandIns(c, p.billing, from, pool);
+    const unindexed = intelligenceOf(c, to) === null;
+    if (unindexed)
+      (o.unindexed === "warning" ? warnings : errors).push({
         path: at,
-        message: `stand-in ${to} is unscored and no rung is near enough to stand in for it`,
-        fix: TREAT_LIKE_FIX(to),
+        message: unindexedMessage(to),
+        fix: c.indexedAt === null ? SYNC_FIX : `catherd profile set failover.${from} ${ranked[0] ?? "null"}`,
       });
     if (quotaOf(a) === quotaOf(b))
       errors.push({
@@ -306,12 +306,11 @@ export function validateProfile(
         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)
+    // an unindexed stand-in has its own finding above: no "downgrade" besides
+    if (!unindexed && downgrade(c, from, to))
       warnings.push({
         path: at,
-        message: `downgrade: ${to} stands in for ${from}, scoring below it on ${down.join(", ")}`,
+        message: `downgrade: ${to} stands in for ${from} at intelligence ${(intelligenceOf(c, to) as number).toFixed(1)}, below its ${(intelligenceOf(c, from) as number).toFixed(1)}`,
         fix: `catherd profile set failover.${from} ${ranked[0] ?? "null"}`,
       });
     const other = ranked.find((x) => !claudeBilled(x));
@@ -329,11 +328,49 @@ export function validateProfile(
     if (!ladders.has(from))
       warnings.push({ path: at, message: `${from} is on no enabled role's ladder, so this never runs` });
   }
-  for (const x of standInsToConfirm(p, c, backends))
-    warnings.push({ path: x.path, message: standInMessage(x), fix: SUGGEST_FIX(x.rungs[0] as string) });
   return { errors, warnings };
 }
 
+/** Plan 33: a warning for a rung above its model's `maxEffort`, null for any other. */
+function aboveCeiling(maxEffort: Readonly<Record<string, string>>, rung: string, path: string): Issue | null {
+  const r = tryParseRung(rung);
+  const key = r ? `${r.backend}:${r.model}` : "";
+  const cap = maxEffort[key];
+  if (!r || cap === undefined || effortRank(r.effort) <= effortRank(cap) || effortRank(r.effort) < 0)
+    return null;
+  return {
+    path,
+    message: `${rung} is above maxEffort ${cap} for ${key}: routing skips it`,
+    fix: `catherd profile set maxEffort.${key} ${r.effort}, or remove the rung`,
+  };
+}
+
+/** The difficulties no rung of `usable` clears, as `logic, hard`. */
+function unreachable(c: Catalog, usable: Candidate[], at: Record<Difficulty, number>): string[] {
+  return DIFFICULTIES.filter((d) => !usable.some((x) => clearsBar(x, barOf(c, d, at))));
+}
+
+/**
+ * Spec 1.5 plan 24: each quota of the role's usable rungs that no kind and difficulty (nor a lane-less route)
+ * ever starts on, whichever quota the run has used least, with its rungs.
+ */
+function idleQuotas(c: Catalog, p: Profile, role: Role, usable: Candidate[]): [string, string[]][] {
+  const quotas = [...new Set(usable.map((x) => quotaOf(x.info.parsed)))];
+  if (quotas.length < 2) return [];
+  const starts = new Set<string>();
+  // every quota gets its turn as the least used, so a tie it could win counts as a start
+  for (const fresh of [null, ...quotas]) {
+    const usage = Object.fromEntries(quotas.map((q) => [q, q === fresh ? 0 : 1]));
+    const rp = { ...routingProfileOf(p, role), usage };
+    starts.add(defaultLadder(c, rp, role).rung);
+    for (const d of DIFFICULTIES) starts.add(select(c, rp, role, d).rung);
+  }
+  const started = new Set(usable.filter((x) => starts.has(x.rung)).map((x) => quotaOf(x.info.parsed)));
+  return quotas
+    .filter((q) => !started.has(q))
+    .map((q) => [q, usable.filter((x) => quotaOf(x.info.parsed) === q).map((x) => x.rung)]);
+}
+
 export function nativeClaudeIssue(rung: string, host: OrchestrationHost, path: string): Issue | null {
   const r = tryParseRung(rung);
   return host !== "claude-code" && r?.backend === "claude"