catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/routing-service.ts

@@ -1,4 +1,5 @@
 import { assertNativeHost } from "./backends.ts";
+import { percentilesOf } from "../domain/bars.ts";
 import { BUDGET_CHEAP_AT } from "../domain/budget.ts";
 import { errorMessage } from "../domain/errors.ts";
 import {
@@ -13,27 +14,38 @@ import {
 import { type Difficulty, type Kind, parseLaneHeader } from "../domain/lane.ts";
 import type { Role } from "../domain/roles.ts";
 import type { RouteJev } from "../domain/route.ts";
+import type { Catalog } from "../domain/catalog.ts";
 import {
   candidates,
   defaultDifficulty,
   defaultLadder,
   type Pick,
+  quotaUsage,
   type RoutingProfile,
+  rolesWithoutRung,
   select,
 } from "../domain/select.ts";
 import { log } from "../infra/log.ts";
-import { catalogQuery, freshenDiscovery, loadCatalog } from "./catalog-service.ts";
+import { catalogQuery, freshenDiscovery, loadCatalog, startIndex } from "./catalog-service.ts";
 import { type Asked, askJev, type JevOpts, jevQuestions, logJev } from "./jev-service.ts";
 import type { ProfileView, RouteAnswer, RouteRequest, RoutingPort, Verdict } from "./ports.ts";
 import { provenanceOf } from "./provenance.ts";
-import { runEvidence } from "./run-evidence.ts";
+import { type EvidenceTable, runEvidence } from "./run-evidence.ts";
 
-function routingProfile(v: ProfileView, role: Role, spentFraction: number): RoutingProfile {
+function routingProfile(
+  v: ProfileView,
+  role: Role,
+  spentFraction: number,
+  usage: Record<string, number> = {},
+): RoutingProfile {
   const rc = v.roles[role];
   return {
+    usage,
     // spec §4.6: from 80 % of the budget on, start at the cheapest rung that clears the bar
     objective: spentFraction >= BUDGET_CHEAP_AT ? "cost" : v.objective,
     billing: v.billing,
+    maxEffort: v.maxEffort ?? {},
+    bars: { ...v.bars, ...rc?.bars },
     role: {
       enabled: rc?.enabled ?? false,
       rungs: rc?.rungs ?? [],
@@ -50,14 +62,60 @@ const answer = (
   asked: Asked | null,
   jev: RouteJev | null,
 ): RouteAnswer => ({
-  ...pick,
+  rung: pick.rung,
+  ladder: pick.ladder,
   source,
   kind,
   difficulty,
   questionSet: asked?.answers ? asked.meta.questionSet : null,
   jev,
+  jevSaid: null,
+  why: "",
+  ...(pick.noClear ? { noClear: pick.noClear } : {}),
+  ...(pick.tie ? { tie: pick.tie } : {}),
 });
 
+/** Spec 1.5 plan 24: what Jev said when it differs from the kind and difficulty the route used, else null. */
+function jevSaid(
+  judged: ReturnType<typeof judgeRoute> | null,
+  kind: Kind | null,
+  difficulty: Difficulty | null,
+): string | null {
+  if (!judged) return null;
+  const k = judged.kind;
+  const d = judged.track ? judged.difficulty : null;
+  if ((k === null || k === kind) && (d === null || d === difficulty)) return null;
+  return `Jev said ${k ?? "no sure kind"}/${d ?? "no sure difficulty"}`;
+}
+
+/** Spec 1.5 plan 24: the route's one-line why, for the coordinator; the provenance goes to routes.jsonl. */
+function whyOf(a: RouteAnswer, hasLane: boolean): string {
+  const what = `${a.kind}/${a.difficulty}`;
+  const head =
+    a.source === "lane"
+      ? `the lane's Kind/Difficulty, ${what}`
+      : a.source === "jev"
+        ? `Jev: ${what}`
+        : a.source === "jev-kind"
+          ? `Jev's kind with ${what}`
+          : hasLane
+            ? "the role's default rung: neither Jev nor the lane file gave a kind and difficulty"
+            : "the role's default rung";
+  const start =
+    a.noClear ?? (a.source === "default" ? null : "the first rung in objective order that clears it");
+  return [head, a.jevSaid, start, a.tie].filter((x): x is string => Boolean(x)).join("; ");
+}
+
+/** Spec 1.2 §8 evidence is display only: an unreadable run on this machine never fails a route. */
+function evidenceOrNone(c: Catalog): EvidenceTable | null {
+  try {
+    return runEvidence(c);
+  } catch (e) {
+    log("debug", "route", { evidence: errorMessage(e) });
+    return null;
+  }
+}
+
 /** How long `route` waits on the daily discovery refresh before routing on the cached listing. */
 const DISCOVERY_BUDGET_MS = 5_000;
 
@@ -79,53 +137,78 @@ async function freshenWithin(rungs: string[], repo: string, ms: number): Promise
   clearTimeout(timer);
 }
 
+/** What every route of one call shares: the role's routing profile and the catalog. */
+interface Prepared {
+  p: RoutingProfile;
+  c: Catalog;
+}
+
+async function prepare(req: RouteRequest, o: RoutingOpts): Promise<Prepared> {
+  const p = routingProfile(req.profile, req.role, req.spentFraction, req.usage);
+  await freshenWithin(p.role.rungs, req.repo, o.discoveryBudgetMs ?? DISCOVERY_BUDGET_MS);
+  return { p, c: loadCatalog({ repo: req.repo, runDir: req.runDir }) };
+}
+
+/** Jev's answer about a lane; null when the route reads no lane, empty when it asks nothing (Jev off, one usable rung). */
+interface Judged {
+  asked: Asked | null;
+  judged: ReturnType<typeof judgeRoute> | null;
+}
+
+async function judge(req: RouteRequest, { p, c }: Prepared, o: RoutingOpts): Promise<Judged | null> {
+  if (req.laneText === null) return null;
+  // one usable rung: nothing for Jev to choose, but the lane's header still names its kind and difficulty
+  if (req.profile.jev.use === "off" || candidates(c, p, req.role).length <= 1)
+    return { asked: null, judged: null };
+  const asked = await askJev(req.runDir, "route-v2", laneState(req.laneText), o);
+  const judged = asked.answers ? judgeRoute(jevQuestions().sets["route-v2"].rule, asked.answers) : null;
+  return { asked, judged };
+}
+
 /**
- * Spec §5.4: kind and difficulty from Jev (§5.5's rule), else the lane file's `Kind:`/`Difficulty:`,
- * else the role's default rung. A kind Jev is sure of survives a difficulty in the dead band: the
- * difficulty then comes from the lane, else the role's default difficulty (`jev-kind`). A role with one
- * usable rung never asks Jev.
+ * Spec §5.4: kind and difficulty from the lane file's `Kind:`/`Difficulty:` when it declares both (spec 1.5
+ * plan 24: a declared header wins, and `jevSaid` names where Jev disagreed), else from Jev (§5.5's rule), else
+ * the role's default rung. A kind Jev is sure of survives a difficulty in the dead band: the difficulty then
+ * comes from the lane, else the role's default difficulty (`jev-kind`). A role with one usable rung never asks
+ * Jev.
  */
-async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
-  const p = routingProfile(req.profile, req.role, req.spentFraction);
-  await freshenWithin(p.role.rungs, req.repo, o.discoveryBudgetMs ?? DISCOVERY_BUDGET_MS);
-  const c = loadCatalog({ repo: req.repo });
+function decide(req: RouteRequest, { p, c }: Prepared, j: Judged | null): RouteAnswer {
   const fallback = () => defaultLadder(c, p, req.role);
-  if (req.laneText === null || candidates(c, p, req.role).length <= 1) {
-    const out = answer(fallback(), "default", null, null, null, null);
-    return { ...out, provenance: provenanceOf(c, out.rung, null, null, p.billing, runEvidence(c)) };
-  }
+  const finish = (out: RouteAnswer): RouteAnswer => {
+    out.why = whyOf(out, req.laneText !== null);
+    out.provenance = provenanceOf(
+      c,
+      out.rung,
+      out.kind,
+      out.difficulty,
+      p.billing,
+      evidenceOrNone(c),
+      percentilesOf(p),
+    );
+    return out;
+  };
+  if (req.laneText === null || j === null)
+    return finish(answer(fallback(), "default", null, null, null, null));
   const lane = parseLaneHeader(req.laneText);
-  let asked: Asked | null = null;
-  let judged: ReturnType<typeof judgeRoute> | null = null;
-  if (req.profile.jev.use !== "off") {
-    asked = await askJev(req.runDir, "route-v2", laneState(req.laneText), o);
-    if (asked.answers) judged = judgeRoute(jevQuestions().sets["route-v2"].rule, asked.answers);
-  }
+  const { asked, judged } = j;
   const jev: RouteJev | null = judged
     ? { pKind: judged.pKind, pA: judged.pA, pB: judged.pB, nouls: judged.nouls }
     : null;
   let out: RouteAnswer;
-  if (judged?.track && judged.difficulty) {
-    const kind = judged.kind ?? lane.kind ?? "repo_code";
-    out = answer(select(c, p, req.role, kind, judged.difficulty), "jev", kind, judged.difficulty, asked, jev);
-  } else if (judged?.kind) {
-    const difficulty = lane.difficulty ?? defaultDifficulty(c, p, req.role, judged.kind);
-    out = answer(
-      select(c, p, req.role, judged.kind, difficulty),
-      "jev-kind",
-      judged.kind,
-      difficulty,
-      asked,
-      jev,
-    );
+  if (lane.kind && lane.difficulty) {
+    out = answer(select(c, p, req.role, lane.difficulty), "lane", lane.kind, lane.difficulty, asked, jev);
+  } else if (judged?.track && judged.difficulty) {
+    const kind = lane.kind ?? judged.kind ?? "repo_code";
+    out = answer(select(c, p, req.role, judged.difficulty), "jev", kind, judged.difficulty, asked, jev);
+  } else if (judged?.kind || (judged && lane.kind)) {
+    const kind = (lane.kind ?? judged.kind) as Kind;
+    const difficulty = lane.difficulty ?? defaultDifficulty(c, p, req.role);
+    out = answer(select(c, p, req.role, difficulty), "jev-kind", kind, difficulty, asked, jev);
   } else {
-    const kind = lane.kind;
-    out =
-      kind && lane.difficulty
-        ? answer(select(c, p, req.role, kind, lane.difficulty), "lane", kind, lane.difficulty, asked, jev)
-        : answer(fallback(), "default", null, null, asked, jev);
+    out = answer(fallback(), "default", null, null, asked, jev);
   }
-  out.provenance = provenanceOf(c, out.rung, out.kind, out.difficulty, p.billing, runEvidence(c));
+  out.jevSaid = out.source === "default" ? null : jevSaid(judged, out.kind, out.difficulty);
+  finish(out);
   if (asked) {
     logJev(req.runDir, {
       ...asked.meta,
@@ -143,9 +226,34 @@ async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
   return out;
 }
 
+async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
+  const prep = await prepare(req, o);
+  return decide(req, prep, await judge(req, prep, o));
+}
+
+/**
+ * Spec 1.5 plan 24, batch `route`: the lanes of one role (one run, one profile) share one discovery refresh and
+ * one catalog, and Jev is asked about all of them at once (Ruling 6: one request per lane, all in flight
+ * together, so each keeps its own cache key and jev.jsonl row). Then each lane is decided in order, every
+ * routed start counting as a use of its quota, so lanes that tie spread over the quotas.
+ */
+async function routeMany(reqs: RouteRequest[], o: RoutingOpts): Promise<RouteAnswer[]> {
+  const first = reqs[0];
+  if (!first) return [];
+  const prep = await prepare(first, o);
+  const judged = await Promise.all(reqs.map((r) => judge(r, prep, o)));
+  const usage: Record<string, number> = { ...first.usage };
+  return reqs.map((req, i) => {
+    const out = decide(req, { ...prep, p: { ...prep.p, usage: { ...usage } } }, judged[i] ?? null);
+    const q = quotaUsage([out.rung]);
+    for (const [k, n] of Object.entries(q)) usage[k] = (usage[k] ?? 0) + n;
+    return out;
+  });
+}
+
 async function verdict<T extends string>(
   runDir: string,
-  set: Extract<SetName, "finding" | "same-defect">,
+  set: Extract<SetName, "finding" | "same-defect" | "stop">,
   state: Record<string, unknown>,
   options: readonly T[],
   use: "auto" | "off",
@@ -177,6 +285,11 @@ export function routingService(o: RoutingOpts = {}): RoutingPort {
       assertNativeHost(result.rung, req.host ?? "unknown");
       return result;
     },
+    routeMany: async (reqs) => {
+      const results = await routeMany(reqs, o);
+      results.forEach((r, i) => assertNativeHost(r.rung, reqs[i]?.host ?? "unknown"));
+      return results;
+    },
     finding: (runDir, laneText, finding, use) =>
       verdict(
         runDir,
@@ -195,6 +308,12 @@ export function routingService(o: RoutingOpts = {}): RoutingPort {
         use,
         o,
       ),
+    stopCause: (runDir, status, reply, use) =>
+      verdict(runDir, "stop", { status, reply: scrubFree(reply.slice(-4000)) }, VERDICT_OPTIONS.stop, use, o),
+    checkStart: async (view, repo) => {
+      const { catalog, index } = await startIndex(repo);
+      return { unusable: rolesWithoutRung(catalog, view), index };
+    },
     catalog: (filter, billing) => catalogQuery(filter, billing),
   };
 }