@opengeni/jev 0.1.0-canary.36199476632001

package/src/code-search/config.ts

@@ -0,0 +1,282 @@
+/**
+ * Every code_search threshold, budget and cap in one place. The defaults are scout-0.3.1's Jev
+ * configuration, tuned on the E1 DEV split (2026-09-24); change them only with a new evaluation.
+ */
+
+export interface CodeSearchConfig {
+  recall: {
+    /** Candidate files passed to wave 1. */
+    maxCandidates: number;
+    /** Matching lines kept per file per keyword. */
+    maxMatchesPerFile: number;
+    /** rg --max-filesize (bytes); also the read cap for candidate files. */
+    maxFileBytes: number;
+    /** rg --max-columns: lines longer than this (minified / generated / data blobs) are ignored entirely. */
+    maxLineColumns: number;
+    /** Multiplier for test files unless the question is about tests. */
+    testWeight: number;
+    /** Path-name match bonus as a fraction of the keyword's IDF. */
+    pathBonus: number;
+    /** Extra weight per log(1 + matching lines) (tie breaker). */
+    hitCountWeight: number;
+    /** Single plain words up to this length are searched with a leading word boundary (`\bturn`, not `return`). */
+    shortWordMaxLen: number;
+    /** Compound keywords with zero hits retry their 2-part fragments (e.g. shouldCompactContext -> compactContext). */
+    fragmentFallback: boolean;
+    /** If paths restrict the search and fewer candidates than this are found, widen to the whole workspace. */
+    minCandidatesBeforeWiden: number;
+    /** Extra rg exclude globs (on top of the built-in list). */
+    extraExcludes: string[];
+    /** Also search hidden files/dirs (.github/workflows, .env.example, .changeset); .git is always excluded. */
+    searchHidden: boolean;
+    /** Multiplier for release notes (CHANGELOG*, .changeset/) unless the question is about history/releases. */
+    changelogWeight: number;
+    /** Time limit per ripgrep call; a timed-out search continues with partial output. */
+    ripgrepTimeoutMs: number;
+  };
+  wave1: {
+    filesPerRequest: number;
+    hitLinesPerFile: number;
+    hitLineChars: number;
+    /** Hard cap on files selected for windowing. */
+    maxFiles: number;
+    /** Always take at least this many files by judge score (guards against an over-strict T1). */
+    minFiles: number;
+    /** Always keep the top-N lexical files (fusion guard against judge misses). */
+    lexicalGuard: number;
+  };
+  wave2: {
+    windowsPerFile: number;
+    /** How many of a file's strongest hit lines seed windows (before merging/splitting). */
+    seedHitsPerFile: number;
+    /** Max lines to walk up from a hit looking for the enclosing declaration. */
+    maxUp: number;
+    /** Max lines below a hit kept in its window. */
+    maxDown: number;
+    /** Windows longer than this are split around hit clusters. */
+    maxWindowLines: number;
+    /** Fallback context when no enclosing declaration is found within maxUp. */
+    fallbackBefore: number;
+    fallbackAfter: number;
+    /** Merge windows whose gap is at most this many lines. */
+    mergeGap: number;
+    /** Windows shorter than this get surrounding context. */
+    minWindowLines: number;
+    passagesPerRequest: number;
+    /** Max passage text chars per Jev request. */
+    maxRequestChars: number;
+    /** Max passages verified in wave 2. */
+    maxPassages: number;
+    /** Code lines longer than this are cut with an explicit marker. */
+    maxLineChars: number;
+    /** Same for prose files (md/mdx/txt/rst), which often have single-line paragraphs of 1-6k chars. */
+    maxProseLineChars: number;
+    /** Windows whose rendered text is longer are split into whole-line sub-windows around their hits. */
+    maxWindowChars: number;
+    /** Same for markdown (sections are long, paragraphs independent). */
+    maxProseWindowChars: number;
+  };
+  wave3: {
+    enabled: boolean;
+    maxLeadCandidates: number;
+    maxLeadsFollowed: number;
+    /** Leads are extracted from at most this many of the most relevant passages (all >= T2). */
+    seedPassages: number;
+    defsPerLead: number;
+  };
+  status: {
+    enabled: boolean;
+    /** Max evidence chars sent to the status check (best passages first); keeps the request under Jev's 32k-token limit. */
+    maxEvidenceChars: number;
+    /** sufficient: overall >= hi and every sub-question >= hi. */
+    hi: number;
+    /** partial: overall >= lo or any sub-question >= hi. */
+    lo: number;
+  };
+  pack: {
+    charsPerToken: number;
+    /** Include passages below T2 only if fewer than this many passed (top by score, above minRelevance). */
+    minPassages: number;
+    minRelevance: number;
+    /** Fill the remaining budget with passages below T2 (ranked). */
+    fillBudget: boolean;
+    moreCandidates: number;
+    leadsNotFollowed: number;
+    /** A trimmed passage must keep at least this many lines. */
+    minTrimLines: number;
+    /** File-diversity penalty: a second passage of one file must beat the first passage of another by this margin. */
+    filePenalty: number;
+    /** Passages whose rendered block is longer are trimmed around their hits to this many chars (0 = off). */
+    maxPassageChars: number;
+    /** Multiplier on the rel used for pack ORDERING of release-note passages; 1 = off. */
+    changelogPrior: number;
+    /** Same for prose docs (md/mdx/txt/rst, not release notes); 1 = off. */
+    docPrior: number;
+    /** Same for test files unless the question is about tests; 1 = off. */
+    testPrior: number;
+    /** Pack ordering score = (rel + lexWeight x lexical passage score) x prior. */
+    lexWeight: number;
+  };
+  jev: {
+    /** Inline the question text in every Jev question when it is at most this long; else reference `question`. */
+    inlineQuestionMaxChars: number;
+    /** Wave 1: put the true/false rubric on every file question instead of once in the state. */
+    fileCriteriaPerQuestion: boolean;
+    /** Keep-alive connections opened while recall runs (0 = off). */
+    warmConnections: number;
+  };
+  thresholds: {
+    /** Wave 1: file triage floor (p >= T1 selects, up to maxFiles). */
+    T1: number;
+    /** Wave 2: passage relevance floor for inclusion in the pack, lead seeding and sub-question coverage. */
+    T2: number;
+    /** Wave 3: lead floor (p >= T3 is followed, up to maxLeadsFollowed). */
+    T3: number;
+  };
+}
+
+export type CodeSearchConfigOverride = {
+  [K in keyof CodeSearchConfig]?: Partial<CodeSearchConfig[K]>;
+};
+
+export const DEFAULT_CODE_SEARCH_CONFIG: Readonly<CodeSearchConfig> = deepFreeze({
+  recall: {
+    maxCandidates: 240,
+    maxMatchesPerFile: 25,
+    maxFileBytes: 4_000_000,
+    maxLineColumns: 8000,
+    testWeight: 0.6,
+    pathBonus: 0.5,
+    hitCountWeight: 0.1,
+    shortWordMaxLen: 5,
+    fragmentFallback: true,
+    minCandidatesBeforeWiden: 5,
+    extraExcludes: [],
+    searchHidden: true,
+    changelogWeight: 0.6,
+    ripgrepTimeoutMs: 30_000,
+  },
+  wave1: {
+    filesPerRequest: 60,
+    hitLinesPerFile: 3,
+    hitLineChars: 160,
+    maxFiles: 16,
+    minFiles: 8,
+    lexicalGuard: 5,
+  },
+  wave2: {
+    windowsPerFile: 5,
+    seedHitsPerFile: 24,
+    maxUp: 40,
+    maxDown: 120,
+    maxWindowLines: 150,
+    fallbackBefore: 10,
+    fallbackAfter: 30,
+    mergeGap: 2,
+    minWindowLines: 12,
+    passagesPerRequest: 4,
+    maxRequestChars: 24_000,
+    maxPassages: 80,
+    maxLineChars: 400,
+    maxProseLineChars: 1600,
+    maxWindowChars: 8000,
+    maxProseWindowChars: 4000,
+  },
+  wave3: {
+    enabled: true,
+    maxLeadCandidates: 60,
+    maxLeadsFollowed: 6,
+    seedPassages: 12,
+    defsPerLead: 1,
+  },
+  status: { enabled: true, maxEvidenceChars: 60_000, hi: 0.7, lo: 0.4 },
+  pack: {
+    charsPerToken: 3.2,
+    minPassages: 4,
+    minRelevance: 0.1,
+    fillBudget: false,
+    moreCandidates: 10,
+    leadsNotFollowed: 8,
+    minTrimLines: 15,
+    filePenalty: 0.1,
+    maxPassageChars: 3200,
+    changelogPrior: 0.5,
+    docPrior: 0.85,
+    testPrior: 1,
+    lexWeight: 0,
+  },
+  jev: {
+    inlineQuestionMaxChars: 600,
+    fileCriteriaPerQuestion: false,
+    warmConnections: 12,
+  },
+  // calibrated on the DEV split from the observed score distributions (relevant files mostly 0.6-0.9;
+  // minFiles and the lexical guard keep recall when few files pass)
+  thresholds: { T1: 0.6, T2: 0.5, T3: 0.5 },
+});
+
+/** Defaults with a partial override merged on top (unknown keys and wrong types are rejected), validated. */
+export function codeSearchConfig(override: CodeSearchConfigOverride = {}): CodeSearchConfig {
+  const base = structuredClone(DEFAULT_CODE_SEARCH_CONFIG) as CodeSearchConfig;
+  const out = base as unknown as Record<string, Record<string, unknown>>;
+  for (const [section, values] of Object.entries(override as Record<string, unknown>)) {
+    const target = out[section];
+    if (!target) throw new Error(`unknown code_search config section: ${section}`);
+    if (!isPlainObject(values)) throw new Error(`code_search config ${section}: expected object`);
+    for (const [key, value] of Object.entries(values)) {
+      if (!(key in target)) throw new Error(`unknown code_search config key: ${section}.${key}`);
+      const current = target[key];
+      if (Array.isArray(current) ? !Array.isArray(value) : typeof current !== typeof value) {
+        throw new Error(
+          `code_search config ${section}.${key}: expected ${Array.isArray(current) ? "array" : typeof current}`,
+        );
+      }
+      target[key] = value;
+    }
+  }
+  validateCodeSearchConfig(base);
+  return base;
+}
+
+export function validateCodeSearchConfig(c: CodeSearchConfig): void {
+  const probs: string[] = [];
+  for (const [k, v] of Object.entries(c.thresholds))
+    if (!(v >= 0 && v <= 1)) probs.push(`thresholds.${k} must be in [0,1]`);
+  if (c.wave1.maxFiles < 1) probs.push("wave1.maxFiles must be >= 1");
+  if (c.wave1.minFiles > c.wave1.maxFiles) probs.push("wave1.minFiles must be <= wave1.maxFiles");
+  if (c.wave1.filesPerRequest < 1 || c.wave1.filesPerRequest > 250)
+    probs.push("wave1.filesPerRequest must be 1..250");
+  if (c.wave2.passagesPerRequest < 1) probs.push("wave2.passagesPerRequest must be >= 1");
+  if (c.wave2.maxWindowLines < 10) probs.push("wave2.maxWindowLines must be >= 10");
+  if (c.wave2.maxWindowChars < 4 * c.wave2.maxLineChars)
+    probs.push("wave2.maxWindowChars must be >= 4 x wave2.maxLineChars");
+  if (c.wave2.maxProseWindowChars < 2 * c.wave2.maxProseLineChars + 200) {
+    probs.push("wave2.maxProseWindowChars must be >= 2 x wave2.maxProseLineChars + 200");
+  }
+  if (c.wave3.maxLeadCandidates > 250) probs.push("wave3.maxLeadCandidates must be <= 250");
+  if (!(c.status.lo <= c.status.hi)) probs.push("status.lo must be <= status.hi");
+  if (c.pack.charsPerToken <= 0) probs.push("pack.charsPerToken must be > 0");
+  if (c.pack.filePenalty < 0) probs.push("pack.filePenalty must be >= 0");
+  if (c.pack.maxPassageChars !== 0 && c.pack.maxPassageChars < 600)
+    probs.push("pack.maxPassageChars must be 0 or >= 600");
+  for (const k of ["changelogPrior", "docPrior", "testPrior"] as const) {
+    if (!(c.pack[k] > 0 && c.pack[k] <= 1)) probs.push(`pack.${k} must be in (0,1]`);
+  }
+  if (!(c.pack.lexWeight >= 0)) probs.push("pack.lexWeight must be >= 0");
+  if (!(c.recall.changelogWeight > 0 && c.recall.changelogWeight <= 1))
+    probs.push("recall.changelogWeight must be in (0,1]");
+  if (!(c.recall.ripgrepTimeoutMs > 0)) probs.push("recall.ripgrepTimeoutMs must be > 0");
+  if (probs.length) throw new Error(`invalid code_search config: ${probs.join("; ")}`);
+}
+
+function isPlainObject(x: unknown): x is Record<string, unknown> {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value)) deepFreeze(v);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/code-search/judge.ts

@@ -0,0 +1,413 @@
+/**
+ * judge.ts - the only place where scores come from: Jev answers one probability per judged item.
+ *
+ * All Jev wording lives in PROMPTS below (one place to review). Design rules followed:
+ *  - one state + many narrow Nouls per request (fan-out); one Noul per candidate (multi-select)
+ *  - criteria text is explicit (in the state for 60-file triage batches, per question for passages)
+ *  - the literal question text is inlined in every question (no `collections[i]`-style indirection)
+ *  - state holds only the candidates being judged (filtered by code first)
+ *  - no counting, math or dates asked of Jev; code combines answers
+ * A Jev failure is not replaced by lexical scores: it propagates and the whole search fails.
+ */
+import { noul, type JevAnswer, type JevClient, type JevNoulQuestion } from "../client";
+import type { CodeSearchConfig } from "./config";
+
+export interface JudgeContext {
+  question: string;
+  subQuestions: string[];
+}
+
+export interface FileItem {
+  id: string;
+  path: string;
+  /** path + best hit lines, as shown to the judge */
+  descriptor: string;
+  /** Normalized lexical score; used only if Jev returns no usable number for this item. */
+  lex: number;
+}
+
+export interface PassageItem {
+  id: string;
+  path: string;
+  start: number;
+  end: number;
+  /** rendered `N| text` */
+  text: string;
+  label?: string | undefined;
+  lex: number;
+  lexCov: number[];
+}
+
+export interface LeadItem {
+  id: string;
+  name: string;
+  seenAt: string;
+  context: string;
+  lex: number;
+}
+
+export interface PassageScore {
+  rel: number;
+  cov: number[];
+}
+
+export interface StatusScore {
+  overall: number;
+  subs: number[];
+}
+
+export interface StageStats {
+  requests: number;
+  inputTokens: number;
+  costUsd: number;
+  ms: number;
+}
+
+export type JudgeEvent = (stage: string, data: Record<string, unknown>) => void;
+
+// ---------------------------------------------------------------------------
+// Prompts (all Jev wording; identical to scout-0.3.1)
+// ---------------------------------------------------------------------------
+
+export const PROMPTS = {
+  fileTask:
+    "Code search triage for a software repository. A developer asked `question`. `files` lists candidate files found by keyword search; each entry is the file path followed by up to 3 matching lines as `line: text`. Judge each file independently by its path and matching lines.",
+  fileCriteria: {
+    yes: "Reading this file would likely help answer the question: it probably implements, decides, computes, configures, enforces or documents the asked behavior. A doc or design note that explains the behavior counts.",
+    no: "The file probably only mentions the same words, imports or passes values through, belongs to an unrelated feature that shares keywords, or is a test that is not about the asked behavior.",
+  },
+  fileQuestion: (id: string, path: string, q: string) =>
+    `Would reading file \`files.${id}\` (${path}) help answer the question${q}? Apply \`criteria\`.`,
+  fileQuestionPerQ: (id: string, path: string, q: string) =>
+    `Would reading file \`files.${id}\` (${path}) help answer the question${q}?`,
+
+  passageTask:
+    "Evidence check for a question about a software repository. Each entry in `passages` is a verbatim excerpt of one repository file with its original line numbers (`N| text`). `in` names the enclosing declaration when the excerpt starts inside one. Judge each passage on its own content only.",
+  passageQuestion: (id: string, path: string, a: number, b: number, q: string) =>
+    `Does \`passages.${id}\` (${path} lines ${a}-${b}) contain code or text needed to answer the question${q}?`,
+  passageCriteria: {
+    true: "The passage implements, decides, computes, configures, enforces or documents part of the asked behavior. A helper that performs one asked step counts, and so does a doc passage that states the behavior.",
+    false:
+      "The passage only mentions, imports, calls or passes through names related to the question, is a test or type declaration that does not show the behavior, or is unrelated code that shares keywords.",
+  },
+  coverageQuestion: (id: string, path: string, a: number, b: number, sub: string) =>
+    `Does \`passages.${id}\` (${path} lines ${a}-${b}) show the answer to this part of the question: "${sub}"?`,
+  coverageCriteria: {
+    true: "The passage itself states or implements the answer to this part.",
+    false:
+      "The passage does not address this part, or only mentions it without showing the answer.",
+  },
+
+  leadTask:
+    "Follow-up selection for a question about a software repository. Evidence passages already found reference the identifiers in `leads`, whose definitions have not been read yet. Each lead shows the identifier, where it was seen, and the line it appears on.",
+  leadCriteria: {
+    yes: "The definition likely computes, decides, configures or enforces part of the asked behavior, or holds a constant, setting or rule that the answer depends on.",
+    no: "It is a generic helper (logging, formatting, errors, type plumbing, database or HTTP plumbing) or it is unrelated to the question.",
+  },
+  leadQuestion: (id: string, name: string, q: string) =>
+    `Would reading where \`${name}\` (\`leads.${id}\`) is defined help answer the question${q}? Apply \`criteria\`.`,
+
+  statusTask:
+    "Sufficiency check. `evidence` is a set of verbatim excerpts of repository files (with original line numbers) collected to answer `question`.",
+  statusQuestion: (q: string) =>
+    `Do the \`evidence\` passages show the answer to the question${q}?`,
+  statusSubQuestion: (sub: string) =>
+    `Do the \`evidence\` passages show the answer to this part of the question: "${sub}"?`,
+  statusCriteria: {
+    true: "Together the passages state or implement the answer concretely enough to cite file and line.",
+    false:
+      "Some part of the answer is missing: the passages only mention the topic, or the deciding code is elsewhere.",
+  },
+};
+
+function inlineQ(question: string, maxChars: number): string {
+  return question.length <= maxChars ? `: "${question}"` : " in `question`";
+}
+
+function withSubs(ctx: JudgeContext): Record<string, unknown> {
+  return ctx.subQuestions.length
+    ? { sub_questions: Object.fromEntries(ctx.subQuestions.map((s, i) => [`s${i + 1}`, s])) }
+    : {};
+}
+
+// ---------------------------------------------------------------------------
+// Request builders (exported for tests)
+// ---------------------------------------------------------------------------
+
+export function buildFileRequest(items: FileItem[], ctx: JudgeContext, cfg: CodeSearchConfig) {
+  const q = inlineQ(ctx.question, cfg.jev.inlineQuestionMaxChars);
+  // default: the rubric is stated once in the state and referenced (~65% fewer question tokens);
+  // fileCriteriaPerQuestion puts it on every Noul instead
+  const perQ = cfg.jev.fileCriteriaPerQuestion;
+  const state = {
+    task: PROMPTS.fileTask,
+    question: ctx.question,
+    ...withSubs(ctx),
+    ...(perQ ? {} : { criteria: PROMPTS.fileCriteria }),
+    files: Object.fromEntries(items.map((f) => [f.id, f.descriptor])),
+  };
+  const questions: Record<string, JevNoulQuestion> = Object.fromEntries(
+    items.map((f) => [
+      f.id,
+      perQ
+        ? noul(PROMPTS.fileQuestionPerQ(f.id, f.path, q), {
+            true: PROMPTS.fileCriteria.yes,
+            false: PROMPTS.fileCriteria.no,
+          })
+        : noul(PROMPTS.fileQuestion(f.id, f.path, q)),
+    ]),
+  );
+  return { state, questions };
+}
+
+export function buildPassageRequest(
+  items: PassageItem[],
+  ctx: JudgeContext,
+  cfg: CodeSearchConfig,
+) {
+  const q = inlineQ(ctx.question, cfg.jev.inlineQuestionMaxChars);
+  const state = {
+    task: PROMPTS.passageTask,
+    question: ctx.question,
+    ...withSubs(ctx),
+    passages: Object.fromEntries(
+      items.map((p) => [
+        p.id,
+        {
+          file: p.path,
+          lines: `${p.start}-${p.end}`,
+          ...(p.label ? { in: p.label } : {}),
+          text: p.text,
+        },
+      ]),
+    ),
+  };
+  const questions: Record<string, JevNoulQuestion> = {};
+  for (const p of items) {
+    questions[`rel::${p.id}`] = noul(
+      PROMPTS.passageQuestion(p.id, p.path, p.start, p.end, q),
+      PROMPTS.passageCriteria,
+    );
+    ctx.subQuestions.forEach((sub, j) => {
+      questions[`cov::${p.id}::${j}`] = noul(
+        PROMPTS.coverageQuestion(p.id, p.path, p.start, p.end, sub),
+        PROMPTS.coverageCriteria,
+      );
+    });
+  }
+  return { state, questions };
+}
+
+export function buildLeadRequest(items: LeadItem[], ctx: JudgeContext, cfg: CodeSearchConfig) {
+  const q = inlineQ(ctx.question, cfg.jev.inlineQuestionMaxChars);
+  const state = {
+    task: PROMPTS.leadTask,
+    question: ctx.question,
+    ...withSubs(ctx),
+    criteria: PROMPTS.leadCriteria,
+    leads: Object.fromEntries(
+      items.map((l) => [l.id, `${l.name}  (seen at ${l.seenAt})  ${l.context}`]),
+    ),
+  };
+  const questions: Record<string, JevNoulQuestion> = Object.fromEntries(
+    items.map((l) => [l.id, noul(PROMPTS.leadQuestion(l.id, l.name, q))]),
+  );
+  return { state, questions };
+}
+
+export function buildStatusRequest(evidence: string, ctx: JudgeContext, cfg: CodeSearchConfig) {
+  const q = inlineQ(ctx.question, cfg.jev.inlineQuestionMaxChars);
+  const state = { task: PROMPTS.statusTask, question: ctx.question, ...withSubs(ctx), evidence };
+  const questions: Record<string, JevNoulQuestion> = {
+    overall: noul(PROMPTS.statusQuestion(q), PROMPTS.statusCriteria),
+  };
+  ctx.subQuestions.forEach((sub, j) => {
+    questions[`sub::${j}`] = noul(PROMPTS.statusSubQuestion(sub), PROMPTS.statusCriteria);
+  });
+  return { state, questions };
+}
+
+/** Group passages into requests: consecutive (same-file first) up to perRequest items and maxChars of text. */
+export function chunkPassages(
+  items: PassageItem[],
+  perRequest: number,
+  maxChars: number,
+): PassageItem[][] {
+  const out: PassageItem[][] = [];
+  let cur: PassageItem[] = [];
+  let chars = 0;
+  for (const p of items) {
+    const c = p.text.length;
+    if (cur.length && (cur.length >= perRequest || chars + c > maxChars)) {
+      out.push(cur);
+      cur = [];
+      chars = 0;
+    }
+    cur.push(p);
+    chars += c;
+  }
+  if (cur.length) out.push(cur);
+  return out;
+}
+
+/** Split into the fewest groups of at most n items, as equal in size as possible (69 -> 35 + 34, not 60 + 9). */
+export function chunkEven<T>(xs: T[], n: number): T[][] {
+  if (!xs.length) return [];
+  const groups = Math.ceil(xs.length / n);
+  const size = Math.ceil(xs.length / groups);
+  return chunk(xs, size);
+}
+
+function chunk<T>(xs: T[], n: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < xs.length; i += n) out.push(xs.slice(i, i + n));
+  return out;
+}
+
+const noulOf = (a: JevAnswer | undefined): number =>
+  a && a.type === "noul" && Number.isFinite(a.probability) ? a.probability : Number.NaN;
+
+function orLex(p: number, lex: number): number {
+  return Number.isFinite(p) ? p : lex;
+}
+
+// ---------------------------------------------------------------------------
+// Jev judge
+// ---------------------------------------------------------------------------
+
+export class JevJudge {
+  private readonly stageStats: Record<string, StageStats> = {};
+  private jevModel: string | null = null;
+
+  constructor(
+    private readonly o: {
+      client: JevClient;
+      config: CodeSearchConfig;
+      signal: AbortSignal;
+      onEvent?: JudgeEvent | undefined;
+    },
+  ) {}
+
+  stats(): Record<string, StageStats> {
+    return this.stageStats;
+  }
+
+  model(): string | null {
+    return this.jevModel;
+  }
+
+  private stat(stage: string): StageStats {
+    return (this.stageStats[stage] ??= { requests: 0, inputTokens: 0, costUsd: 0, ms: 0 });
+  }
+
+  /** One logical request (the client may split its questions into several HTTP requests). */
+  private async ask(
+    stage: string,
+    state: unknown,
+    questions: Record<string, JevNoulQuestion>,
+  ): Promise<Record<string, JevAnswer>> {
+    const t0 = performance.now();
+    const r = await this.o.client.ask(state, questions, {
+      tag: stage,
+      signal: this.o.signal,
+    });
+    const st = this.stat(stage);
+    st.requests += r.requests;
+    st.inputTokens += r.usage.inputTokens;
+    st.costUsd += r.costUsd;
+    this.jevModel = r.model || this.jevModel;
+    this.o.onEvent?.("jev", {
+      jevStage: stage,
+      ms: Math.round(performance.now() - t0),
+      requests: r.requests,
+      model: r.model,
+      inputTokens: r.usage.inputTokens,
+      costUsd: r.costUsd,
+      state,
+      questions,
+      answers: r.answers,
+    });
+    return r.answers;
+  }
+
+  /** Run a stage's batches in parallel; the first failure rejects the stage. */
+  private async stage<I, R>(
+    stage: string,
+    batches: I[][],
+    build: (b: I[]) => { state: unknown; questions: Record<string, JevNoulQuestion> },
+    read: (b: I[], answers: Record<string, JevAnswer>) => Array<[string, R]>,
+  ): Promise<Map<string, R>> {
+    const t0 = performance.now();
+    try {
+      const results = await Promise.all(
+        batches.map(async (b) => {
+          const req = build(b);
+          return read(b, await this.ask(stage, req.state, req.questions));
+        }),
+      );
+      return new Map(results.flat());
+    } finally {
+      this.stat(stage).ms += Math.round(performance.now() - t0);
+    }
+  }
+
+  async scoreFiles(items: FileItem[], ctx: JudgeContext): Promise<Map<string, number>> {
+    if (!items.length) return new Map();
+    return this.stage(
+      "wave1",
+      chunkEven(items, this.o.config.wave1.filesPerRequest),
+      (b) => buildFileRequest(b, ctx, this.o.config),
+      (b, a) => b.map((f) => [f.id, orLex(noulOf(a[f.id]), f.lex)]),
+    );
+  }
+
+  async scorePassages(
+    items: PassageItem[],
+    ctx: JudgeContext,
+    stage = "wave2",
+  ): Promise<Map<string, PassageScore>> {
+    if (!items.length) return new Map();
+    const w = this.o.config.wave2;
+    return this.stage(
+      stage,
+      chunkPassages(items, w.passagesPerRequest, w.maxRequestChars),
+      (b) => buildPassageRequest(b, ctx, this.o.config),
+      (b, a) =>
+        b.map((p) => [
+          p.id,
+          {
+            rel: orLex(noulOf(a[`rel::${p.id}`]), p.lex),
+            cov: ctx.subQuestions.map((_, j) =>
+              orLex(noulOf(a[`cov::${p.id}::${j}`]), p.lexCov[j] ?? 0),
+            ),
+          },
+        ]),
+    );
+  }
+
+  async scoreLeads(items: LeadItem[], ctx: JudgeContext): Promise<Map<string, number>> {
+    if (!items.length) return new Map();
+    return this.stage(
+      "leads",
+      chunk(items, 250),
+      (b) => buildLeadRequest(b, ctx, this.o.config),
+      (b, a) => b.map((l) => [l.id, orLex(noulOf(a[l.id]), l.lex)]),
+    );
+  }
+
+  /** null = nothing to check (empty evidence). */
+  async status(evidence: string, ctx: JudgeContext): Promise<StatusScore | null> {
+    if (!evidence.trim()) return null;
+    const req = buildStatusRequest(evidence, ctx, this.o.config);
+    const t0 = performance.now();
+    try {
+      const a = await this.ask("status", req.state, req.questions);
+      return {
+        overall: noulOf(a.overall),
+        subs: ctx.subQuestions.map((_, j) => noulOf(a[`sub::${j}`])),
+      };
+    } finally {
+      this.stat("status").ms += Math.round(performance.now() - t0);
+    }
+  }
+}