catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/domain/profile-rules.ts

@@ -1,29 +1,24 @@
 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 {
   type Candidate,
   candidates,
+  CODING_FLOOR,
+  CODING_ROLES,
   clearsBar,
   defaultLadder,
   type RoutingProfile,
@@ -33,11 +28,13 @@ import {
 export { quotaOf };
 
 /**
- * `reach`: also warn about the kinds and difficulties no worker rung clears (spec 1.5 plan 24), which only an
- * explicit `profile validate` asks for.
+ * `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. */
@@ -52,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;
@@ -72,98 +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 every value is borrowed, else the dimensions it borrows (a rung a sync scored on some); and (1.2
- * minor) what each inferred stand-in lends: "honesty inferred from Y".
- */
-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 === records.length;
-  const byStandIn = new Map<string, Dim[]>();
-  for (const d of s.inferred) {
-    const like = s.standIns[d] as string;
-    byStandIn.set(like, [...(byStandIn.get(like) ?? []), d]);
-  }
-  const parts = [
-    ...(s.via ? [`${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}`] : []),
-    ...[...byStandIn].map(([like, dims]) => `${dims.join(", ")} inferred from ${like}`),
-  ];
-  return { inferred: guessed, via: s.via, note: parts.length ? parts.join("; ") : null };
-}
-
 /**
  * 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,
@@ -188,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}`;
@@ -204,6 +139,7 @@ export function validateProfile(
         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);
@@ -216,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`,
@@ -231,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${rung === rc.defaultRung ? `; it is the ${role}'s default rung, so ${defaultFallback(c, p, role)}` : ""}`,
-          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`,
         });
     });
@@ -272,33 +215,30 @@ 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.5 plan 24: every kind and 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 strong. Only an
+    // 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);
+      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 strong (route names the closest)`,
+          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).
@@ -328,7 +268,7 @@ export function validateProfile(
       return b === undefined ? [] : b === "claude" ? [b, "claude-code"] : [b];
     }),
   );
-  const pool = catalogRungs(c).filter((x) => {
+  const pool = catalogPairs(c).filter((x) => {
     const r = tryParseRung(x);
     return r !== null && backends.includes(r.backend) && named.has(r.backend);
   });
@@ -346,16 +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;
     }
-    const unscored = !scoresOf(c, rungInfo(c, to).canonical);
-    if (unscored)
-      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({
@@ -363,13 +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);
-    // an unscored stand-in has its own warning above: no "downgrade" on every bar dim besides
-    const down = unscored ? [] : 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));
@@ -387,26 +328,26 @@ 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 };
 }
 
-/** The role's default rung when it is unscored: what routing starts on instead. */
-function defaultFallback(c: Catalog, p: Profile, role: Role): string {
-  try {
-    return `routing falls back to ${defaultLadder(c, routingProfileOf(p, role), role).rung}`;
-  } catch {
-    return "routing has no rung to fall back to";
-  }
+/** 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`,
+  };
 }
 
-/** `repo_code logic, hard` per kind: the kinds and difficulties no rung of `usable` clears. */
-function unreachable(c: Catalog, usable: Candidate[]): string[] {
-  return KINDS.flatMap((k) => {
-    const ds = DIFFICULTIES.filter((d) => !usable.some((x) => clearsBar(c, x, k, d)));
-    return ds.length ? [`${k} ${ds.join(", ")}`] : [];
-  });
+/** 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))));
 }
 
 /**
@@ -422,7 +363,7 @@ function idleQuotas(c: Catalog, p: Profile, role: Role, usable: Candidate[]): [s
     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 k of KINDS) for (const d of DIFFICULTIES) starts.add(select(c, rp, role, k, d).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