wicked-crew-api-types 0.138.0 → 0.143.0

package/index.d.ts

@@ -292,6 +292,14 @@ export interface HealthCapabilities {
    * ({@link SystemSnapshot}). ABSENT on an older daemon — show the older Health cards instead.
    */
   system?: boolean;
+  /**
+   * (api-types 0.140.0) `GET /system.attention[]` follows the one "needs you" rule (root causes with
+   * `blockedRunIds`, `kind`, `waitedSince`, ranked by impact) and the snapshot carries
+   * `unresolved[]` + `toReview`; `POST /runs/:id/resolve` is served. A skin shows
+   * `attention.length` as its "needs you" number only when this is true; ABSENT on an older daemon,
+   * which keeps its own fold.
+   */
+  attentionRanked?: boolean;
   /**
    * (api-types 0.137.0, DES-SYSTEM-CHAT) The chat history is served: `GET /chats` carries `items` +
    * `nextCursor`, `GET /chats/:id/messages` reopens a chat, `POST /chats/:id/close` ends one and keeps
@@ -303,6 +311,13 @@ export interface HealthCapabilities {
    * ABSENT on an older daemon — hide upload.
    */
   chatAttachments?: boolean;
+  /**
+   * (api-types 0.141.0, crew#1157) The read-only workflows `ChatOpenBody.workflow` runs on this
+   * daemon's engine — `['analyze']` on a core-ts that carries the built-in `analyze` preset, `[]` on
+   * one that does not. ABSENT on an older daemon (its strict schema refuses `workflow`): open a plain
+   * chat instead.
+   */
+  chatWorkflows?: string[];
 }
 
 /** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
@@ -1757,6 +1772,17 @@ export interface GateDecision {
      *  deliver step and at every other gate. QE acceptance is never waived by it — a run that
      *  requires it still needs its PASS before delivery. Engine: wicked-core-ts after 0.15.6. */
     | 'operator_judgment'
+    /** (j4-gates) SKIP QE ACCEPTANCE at a gate, with `approve: true` and the written reason in
+     *  `amend` — required, non-empty (a 400 otherwise); no `amendScope` or `plan`. The launch's
+     *  `skipQeAcceptance`, given later: the run's QE decision becomes `skipped` by the operator
+     *  ("QE acceptance skipped by operator: <reason>"), labelled on the run, every later gate and the
+     *  delivery. The engine answers three gates: the gate before the deliver step (the delivery goes
+     *  without a QE PASS; {@link GateDecisionResult} `delivery.qeAcceptance.status: 'skipped'`), the
+     *  escalation gate of a unit only the isolated QE reviewer denied (the unit counts), and a failed
+     *  repo-checks floor's gate with a QE layer behind it (the gate re-opens on the floor alone, where
+     *  `operator_judgment` then applies). Refused (409, gate left open) at every other gate and on a
+     *  run that does not require QE acceptance. Engine: wicked-core-ts after 0.16.3. */
+    | 'skip_qe'
     /** (core#820) A `consent` gate's choice from its dry-run plan (`awaitingHuman.choices`), with
      *  `approve: true`: `consent:worker` (the default), `consent:operator`, …; `reject` declines. */
     | `consent:${string}`;
@@ -6684,6 +6710,14 @@ export interface ChatOpenBody {
   primary?: string;
   /** (api-types 0.137.0, DES-SYSTEM-CHAT) The page the chat was started on, for the history list. */
   startedOn?: ChatStartedOn;
+  /**
+   * (api-types 0.141.0, crew#1157) Run every turn of this chat as a READ-ONLY workflow: `analyze`
+   * answers questions about the repositories in scope from the code graph and the files, each claim
+   * cited, changing nothing. The chat seats ONE helper (`primary`, else the first eligible), asks for
+   * no reviewer, never delivers, and its seats propose no work. A name chats do not run is a 400; an
+   * engine without it is a 409. Send it only when `GET /health.capabilities.chatWorkflows` names it.
+   */
+  workflow?: string;
 }
 
 /** The scope a `POST /chats` caller may name (api-types 0.39.0, studio#323 R4). */
@@ -6831,6 +6865,8 @@ export interface ChatOpenResponse {
    * field; a daemon between #641 and #650 emitted it only when `refused` was non-empty.
    */
   singleSeat?: ChatSingleSeatDegradation;
+  /** (api-types 0.141.0, crew#1157) The workflow every turn runs, when the open named one. */
+  workflow?: string;
 }
 
 /** `POST /chats/:id/messages` → 202. */
@@ -8277,7 +8313,9 @@ export interface NoEligibleSeatBody {
 export type SystemState = 'ok' | 'degraded' | 'down' | 'unknown' | 'off';
 
 /** The Nerve Center light: `red` when work is blocked, `yellow` when something needs a look but
- *  work still flows, `green` when `attention[]` is empty. Derived from `attention[]` only. */
+ *  work still flows, `green` when `attention[]` is empty. Derived from `attention[]` only.
+ *  (api-types 0.140.0, `capabilities.attentionRanked`) `green` ONLY when `attention[]` AND
+ *  `unresolved[]` are both empty: unresolved work alone reads `yellow`. */
 export type SystemLevel = 'green' | 'yellow' | 'red';
 
 /** The existing action an attention item or row offers (the snapshot itself is read-only):
@@ -8307,11 +8345,36 @@ export interface SystemSnapshot {
   budgetMs: number;
   /** How long assembling it took, in ms. */
   tookMs: number;
-  /** `red` iff some attention item is `red`, else `yellow` iff any item, else `green`. */
+  /** `red` iff some attention item is `red`, else `yellow` iff any item, else `green`. (api-types
+   *  0.140.0, `capabilities.attentionRanked`) `yellow` also when `unresolved[]` is not empty: `green`
+   *  only when both are empty. */
   level: SystemLevel;
   /** Every item that needs a look, worst first (red before yellow, then by how many runs it
-   *  blocks, then infra › cli › run › governance). Empty when all is clear. */
+   *  blocks, then infra › cli › run › governance). Empty when all is clear.
+   *
+   *  (api-types 0.140.0, `capabilities.attentionRanked`) The ONE "needs you" list: each item is one
+   *  root cause holding work up right now, either because work cannot move until a person acts
+   *  (`kind: 'prevents'`) or because the system itself slows it (`kind: 'slows'`). One cause that
+   *  holds several runs is ONE item naming them in `blockedRunIds`. Superseded runs, answered asks,
+   *  failed runs older than 7 days, benches with an alternative and pending proposals are not in it
+   *  (the first three move to `unresolved[]`; proposals are `toReview`). Sorted by runs held, then
+   *  prevents before slows, then a component (infra, or no seat at all) before one run's own cause,
+   *  then the longest wait, then the units left. Its length is the number. */
   attention: SystemAttentionItem[];
+  /**
+   * (api-types 0.140.0) Work nobody has resolved: failed runs not retried and not archived,
+   * superseded runs still open, asks parked at their turn gate past a day. Each carries what it cost
+   * and how to resolve it (retry, archive with a reason, or close as superseded). Never counted in
+   * `attention[]`, never dropped by age. ABSENT on an older daemon.
+   */
+  unresolved?: SystemUnresolvedItem[];
+  /** (api-types 0.140.0) `unresolved[]`'s summed cost: `costUsd` is `null` when no item's cost is
+   *  known; `costKnown` says how many items carried one. ABSENT on an older daemon. */
+  unresolvedSpend?: { costUsd: number | null; tokens: { input: number; output: number } | null; costKnown: number };
+  /** (api-types 0.140.0) Pending proposals waiting on review: shown as "N to review", never in the
+   *  "needs you" number (no run waits on them). `null` when the queue did not answer in time. ABSENT
+   *  on an older daemon. */
+  toReview?: number | null;
   /** One entry per CLI on the roster, in roster order. */
   clis: SystemCli[];
   /** Every unfinished run (not completed / cancelled / failed), worst first:
@@ -8338,6 +8401,72 @@ export interface SystemAttentionItem {
   target: SystemTarget;
   /** The one existing action that helps, or `null`. */
   action: SystemAction | null;
+  /** (api-types 0.140.0) `prevents`: work cannot move until someone acts; `slows`: the system
+   *  slows it (host load). ABSENT on an older daemon. */
+  kind?: 'prevents' | 'slows';
+  /** (api-types 0.140.0) The runs this one cause holds (`blocks` is its length). For a `slows`
+   *  item, the runs whose next step it slows. ABSENT on an older daemon. */
+  blockedRunIds?: string[];
+  /** (api-types 0.140.0) ISO-8601 of the oldest open gate among the held runs (the gate's
+   *  arrival, never the run's launch); a failed run's end; `null` when unknown. ABSENT on an older
+   *  daemon. */
+  waitedSince?: string | null;
+  /** (api-types 0.140.0) Units not yet done across the held runs. ABSENT on an older daemon. */
+  unitsLeft?: number;
+}
+
+/** (api-types 0.140.0) Why a run is in `unresolved[]`. `failed`: it failed and was neither retried
+ *  (`retry_of`) nor archived; `superseded`: a retry or a later completed run with the same repo,
+ *  workflow and title replaced it, but it is still open or unarchived; `parked`: an ask waits at its
+ *  turn gate past a day. */
+export type SystemUnresolvedWhy = 'failed' | 'superseded' | 'parked';
+
+/** (api-types 0.140.0) The ways to resolve an unresolved run: `retry` (`POST /runs {retryOf}`),
+ *  `archive` (`POST /runs/:id/resolve {action: 'archive', reason}`, a reason is required) and
+ *  `close_superseded` (`POST /runs/:id/resolve {action: 'superseded', by}`). */
+export type SystemResolveKind = 'retry' | 'archive' | 'close_superseded';
+
+/** (api-types 0.140.0) One run nobody has resolved (`SystemSnapshot.unresolved[]`). */
+export interface SystemUnresolvedItem {
+  /** `unresolved:<runId>`. */
+  id: string;
+  runId: string;
+  title: string;
+  /** (api-types 0.142.0) The run's repo (`repo_ref`) and workflow, so a skin can group look-alike items; `null` when none. ABSENT before. */
+  repo?: string | null;
+  workflow?: string | null;
+  /** The engine's status. */
+  status: string;
+  why: SystemUnresolvedWhy;
+  /** Plain words ("failed 9 days ago", "superseded by 6f11390c, which delivered"). */
+  reason: string;
+  /** The run that superseded it, for `why: 'superseded'`. */
+  supersededBy?: string;
+  /** ISO-8601 of when it stopped moving (its end, or its gate's arrival); `null` when unknown. */
+  since: string | null;
+  /** What it cost. `costUsd`/`tokens` are `null` when the run's log carried no usage frame (or was
+   *  not read yet); `wallMs` is launch to end (or to now while open), `null` for an undated run. */
+  cost: { costUsd: number | null; tokens: { input: number; output: number } | null; wallMs: number | null };
+  /** The resolutions that apply, best first. */
+  actions: SystemResolveKind[];
+}
+
+/** (api-types 0.140.0) `POST /runs/:id/resolve`: resolve an unresolved run. `archive` needs a
+ *  non-blank `reason` (a blank or missing one is a 400); `superseded` names the run that replaced it
+ *  in `by` (an existing run, not itself). A run parked at a gate is stopped first, then archived; a
+ *  run that is executing is refused (409). The archive note keeps the reason. */
+export type ResolveRunRequest =
+  | { action: 'archive'; reason: string }
+  | { action: 'superseded'; by: string; reason?: string };
+
+export interface ResolveRunResponse {
+  runId: string;
+  action: 'archive' | 'superseded';
+  archived: true;
+  /** The run was parked at a gate and was stopped before it was archived. */
+  cancelled: boolean;
+  /** The archive note written (`resolved: <reason>` or `superseded by <id>[: <reason>]`). */
+  note: string;
 }
 
 // ── clis[] ──
@@ -8464,8 +8593,9 @@ export interface SystemRun {
   /** The thresholds the verdict used (from `workerStallMinutes`). */
   quietAfterMs: number;
   stallAfterMs: number;
-  /** The open gate or question, when the run waits on one. */
-  gate?: { interactionId: string | null; ord: number | null; kind: string | null; prompt: string | null };
+  /** The open gate or question, when the run waits on one. `receivedAt` (api-types 0.140.0): ISO-8601
+   *  of the gate's arrival; `null`/ABSENT when unknown. */
+  gate?: { interactionId: string | null; ord: number | null; kind: string | null; prompt: string | null; receivedAt?: string | null };
   /** ISO-8601 the run was launched, when known. */
   createdAt: string | null;
 }
@@ -11713,6 +11843,187 @@ export interface LearnTopicsResponse {
   topics: LearnTopic[];
 }
 
+// ── workflow schedules + the run review (DES-RUNS-REVIEW-001) ─────────────────────────────────
+// `/api/v1/schedules`: any workflow on a cadence (the default entry reviews recent work every 48 h).
+// `/api/v1/insights`: every review of recent work, its numbers and what happened to each recommendation.
+
+/** A schedule's last outcome: `launched` while its run is open; `refused` = the launch failed. */
+/** `launching` = the run id is reserved and the engine is being asked; it holds the slot across a restart. */
+export type ScheduleOutcome = 'launching' | 'launched' | 'refused' | 'completed' | 'failed' | 'cancelled' | 'skipped';
+
+/** One workflow schedule (`GET /schedules`). */
+export interface WorkflowSchedule {
+  /** Kebab-case; the default entry is `review-recent-work`. */
+  id: string;
+  workflow: string;
+  /** Interval, 24..2160 hours. */
+  everyHours: number;
+  enabled: boolean;
+  /** Projects the run covers; empty = all. */
+  projectIds: string[];
+  repoRef: string | null;
+  problem: string | null;
+  /** ISO-8601. Missed intervals coalesce into one launch; a schedule whose last run is open is skipped. */
+  nextDueAt: string;
+  lastRunId: string | null;
+  lastRunAt: string | null;
+  lastOutcome: ScheduleOutcome | null;
+  /** Why the last attempt was skipped or refused, in plain words; null after a launch. */
+  lastNote: string | null;
+  /** Consecutive refused launches (backoff = min(2^failures, 24) h). */
+  failures: number;
+  createdAt: string;
+  updatedAt: string;
+  /** The `review-recent-work` schedule only: the latest review's date and outcome. */
+  lastReview?: { runId: string; launchedAt: string; endedAt: string | null; status: InsightsReviewStatus } | null;
+}
+
+export interface SchedulesResponse {
+  schedules: WorkflowSchedule[];
+}
+
+/** `PUT /schedules/:id` (human-only). */
+export interface SchedulePutBody {
+  workflow: string;
+  everyHours: number;
+  enabled?: boolean;
+  projectIds?: string[];
+  repoRef?: string | null;
+  problem?: string | null;
+}
+
+/** `POST /schedules/:id/run` ("Run it now", human-only): 409 when its last run is still going or another run works. */
+export interface ScheduleRunResponse {
+  runId: string;
+  schedule: WorkflowSchedule;
+}
+
+export type InsightsMetricId = 'pass_rate' | 'override_rate' | 'unresolved_rate' | 'time_to_pr' | 'floor_minutes' | 'wait_on_people' | 'spend' | 'retries';
+/** `too-few` = below the minimum sample (n < 5) in the window or the baseline: no trend is called. */
+export type InsightsVerdict = 'too-few' | 'no-change' | 'improved' | 'regressed';
+export type InsightsRecommendationKind = 'steering-rule' | 'memory' | 'setting' | 'issue' | 'resolve-stale';
+export type InsightsReviewStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+
+export interface InsightsInterval {
+  lo: number;
+  hi: number;
+}
+
+/** A sample: a rate (Wilson 95 % interval) or a median (bootstrap 95 % interval, with p75/p90). */
+export interface InsightsSampleStat {
+  n: number;
+  value: number | null;
+  interval: InsightsInterval | null;
+  p75?: number | null;
+  p90?: number | null;
+}
+
+export interface InsightsMetricDef {
+  id: InsightsMetricId;
+  label: string;
+  kind: 'rate' | 'median';
+  unit: 'ratio' | 'minutes' | 'usd' | 'count';
+  higherIsBetter: boolean;
+}
+
+export interface InsightsRecommendation {
+  /** `<review run id>:<candidate id>`. */
+  id: string;
+  candidate: string;
+  kind: InsightsRecommendationKind;
+  title: string;
+  evidence: {
+    line: string;
+    runs: Array<{ id: string; title: string }>;
+    metric?: InsightsMetricId;
+    segment?: string;
+    n: number;
+    value?: number | null;
+    baseline?: number | null;
+    interval?: InsightsInterval | null;
+  };
+  expectedEffect: string;
+  confidence: 'high' | 'medium' | 'low';
+  /** What evidence would change our mind. */
+  changeMind: string;
+  /** Crew's ranking key: runs affected + hours at stake + dollars at stake. */
+  impact: number;
+  basis: 'notable' | 'pattern';
+  action: {
+    setting?: string;
+    issue?: { repoRef: string | null; title: string; body: string };
+    runs?: string[];
+    proposal?: { kindType: string; content: string; severity?: string };
+  };
+  state: 'new' | 'accepted' | 'dismissed';
+  reason: string | null;
+  decidedAt: string | null;
+  /** The approve-queue proposal filed for a steering-rule or memory recommendation. */
+  proposalId: string | null;
+  proposalError: string | null;
+}
+
+export interface InsightsReview {
+  runId: string;
+  trigger: 'schedule' | 'manual';
+  scheduleId: string | null;
+  launchedAt: string;
+  endedAt: string | null;
+  status: InsightsReviewStatus;
+  window: { startMs: number; endMs: number };
+  baselineWindows: Array<{ startMs: number; endMs: number }>;
+  projectIds: string[];
+  summary: string | null;
+  /** false = the seat wrote no usable report; crew's own wording is shown, labelled "not interpreted". */
+  interpreted: boolean;
+  totals: Record<string, number> | null;
+  /** The all-runs metrics of this review: one point per metric on the trend lines. */
+  series: Array<{ metric: InsightsMetricId; window: InsightsSampleStat; baseline: InsightsSampleStat; verdict: InsightsVerdict }>;
+  /** What got better, and what is working. */
+  improvements: Array<{ metric: InsightsMetricId; segment: string; line: string }>;
+  regressions: Array<{ metric: InsightsMetricId; segment: string; line: string }>;
+  /** At most five, ranked by impact. */
+  recommendations: InsightsRecommendation[];
+  watching: Array<{ id: string; title: string; line: string }>;
+  error: string | null;
+}
+
+/** `GET /insights`: the review history, newest first. */
+export interface InsightsResponse {
+  reviews: InsightsReview[];
+  /** Recommendations nobody has accepted or dismissed yet, across the history. */
+  newRecommendations: number;
+  running: boolean;
+  lastReview: { runId: string; launchedAt: string; endedAt: string | null; status: InsightsReviewStatus } | null;
+  metrics: InsightsMetricDef[];
+  /** Below this n no trend is called. */
+  minSample: number;
+}
+
+/** What studio opens on Accept: the proposal (approval stays in the approve queue), a settings section, a
+ *  prefilled new-issue page, or the runs list filtered to these runs. */
+export type InsightsAcceptTarget =
+  | { kind: 'proposal'; proposalId: string }
+  | { kind: 'settings'; section: string }
+  | { kind: 'issue'; repoRef: string | null; title: string; body: string; url: string | null }
+  | { kind: 'runs'; runIds: string[] }
+  | { kind: 'none' };
+
+/** `POST /insights/recommendations/:id/accept` (human-only). */
+export interface AcceptRecommendationResponse {
+  recommendation: InsightsRecommendation;
+  open: InsightsAcceptTarget;
+}
+
+/** `POST /insights/recommendations/:id/dismiss` (human-only). A proposal-backed one rejects its proposal. */
+export interface DismissRecommendationBody {
+  reason: string;
+}
+
+export interface DismissRecommendationResponse {
+  recommendation: InsightsRecommendation;
+}
+
 // ── MCP inspector bridge (DES-MCP-INSPECTOR-001 §3) ───────────────────────────────────────────
 // `/api/v1/mcp-inspect/sessions`: one live connection to an MCP server per session, driven by
 // studio's host for an `mcp-server` editor. Start, send and delete are human-only; the log is
@@ -11899,3 +12210,208 @@ export interface SearchResponse {
   partial: boolean;
   took_ms: number;
 }
+
+// ── Default evals (DES-DEFAULT-EVALS-001; api-types 0.143.0) ─────────────────────────────────────────────
+// `/api/v1/testing/default-evals*`: the system's own judgments (needs-you, floor class, QE verdict, attribution,
+// steering firing, recall, prompt routing, normalization) scored against what really happened. One case shape for
+// every suite; real, synthetic, combined and model-labelled figures are always reported apart.
+
+/** The eight inference points. */
+export type DefaultEvalSuiteId =
+  | 'needs-you'
+  | 'floor-class'
+  | 'qe-verdict'
+  | 'attribution'
+  | 'steering'
+  | 'recall'
+  | 'archetype'
+  | 'normalization';
+
+export type DefaultEvalCaseSource = 'real' | 'synthetic';
+
+/**
+ * Who said what the answer should be. `operator`: the person's choice at a gate (or a ruling); `rule`: a
+ * deterministic consistency rule over the case's own evidence; `fixture`: written into a corpus or the generator;
+ * `model:<seat>`: a model labelled it because nothing else could. Model labels are reported in their own row and
+ * never in the headline (DES §3, determinism).
+ */
+export type DefaultEvalLabelBy = 'operator' | 'rule' | 'fixture' | `model:${string}`;
+
+/** What the system answered: a class, a set (attribution), or a cluster key (needs-you merge). */
+export interface DefaultEvalAnswer {
+  label?: string;
+  labels?: string[];
+  cluster?: string;
+}
+
+export interface DefaultEvalObserved extends DefaultEvalAnswer {
+  /** The classifier's own confidence in `label`, in [0, 1], when it gives one (calibration). */
+  confidence?: number;
+  /** `recorded`: read from the run store as the system said it then. `replay`: the current classifier, run now. */
+  by: 'recorded' | 'replay';
+}
+
+export interface DefaultEvalExpected extends DefaultEvalAnswer {
+  by: DefaultEvalLabelBy;
+  /** Why this is the answer, in a line (the operator's words, or the rule that fired). */
+  why?: string;
+}
+
+export interface DefaultEvalCaseEvidence {
+  runId?: string;
+  ord?: number;
+  seq?: number;
+  decisionId?: string;
+  /** A repo-relative or program-relative file the case was read from (seed cases). */
+  file?: string;
+}
+
+export interface DefaultEvalCase {
+  /** Stable identity: capture is idempotent by it. */
+  id: string;
+  suite: DefaultEvalSuiteId;
+  source: DefaultEvalCaseSource;
+  /** The project (or repo, when the run has no project) the case belongs to; `null` when neither is known. */
+  project: string | null;
+  /** The surface that produced `observed`, when several surfaces answer one question (needs-you). */
+  surface?: string;
+  /**
+   * The canonical input fingerprint: two cases with the same key asked the system the same question. The
+   * normalization suite compares observations per key across projects and surfaces.
+   */
+  inputKey: string;
+  /** The case's input, small and scrubbed (no paths, no prompts beyond a title). */
+  input: Record<string, unknown>;
+  /** `null` when the system's answer is not known yet: a synthetic case waiting on a replay adapter. */
+  observed: DefaultEvalObserved | null;
+  expected: DefaultEvalExpected;
+  evidence?: DefaultEvalCaseEvidence;
+  /** A case from the shipped baseline (the 2026-10-27 rig capture and the needs-you ruling), not this daemon's own
+   *  run store. Only counted when a run asks for the baseline; always disclosed in the counts. */
+  baseline?: true;
+}
+
+/** A proportion with its Wilson 95 % interval. `tooFew` when n is below the minimum (DES §6). */
+export interface DefaultEvalRate {
+  k: number;
+  n: number;
+  value: number | null;
+  lo: number | null;
+  hi: number | null;
+  tooFew: boolean;
+}
+
+export interface DefaultEvalClassScore {
+  label: string;
+  precision: DefaultEvalRate;
+  recall: DefaultEvalRate;
+}
+
+export interface DefaultEvalCalibration {
+  n: number;
+  /** DefaultEvalExpected calibration error over 10 equal-width bins. `null` below the calibration minimum. */
+  ece: number | null;
+  brier: number | null;
+  tooFew: boolean;
+}
+
+/** One slice of a suite's cases (real, synthetic, combined, model-labelled, or one project). */
+export interface DefaultEvalSliceScore {
+  /** Cases in the slice, including those that could not be scored. */
+  cases: number;
+  /** Cases with no observation (a synthetic case with no replay adapter). Never counted as right or wrong. */
+  unscored: number;
+  /** DefaultEvalObserved matched expected: exact class, set equality, or the pair agreement for merges. */
+  agreement: DefaultEvalRate;
+  perClass: DefaultEvalClassScore[];
+  /** Set-valued suites (attribution): micro precision / recall over the set members. */
+  members?: { precision: DefaultEvalRate; recall: DefaultEvalRate };
+  /** Cluster suites (needs-you merge): pairwise precision / recall over "these two are one item". */
+  pairs?: { precision: DefaultEvalRate; recall: DefaultEvalRate };
+  calibration?: DefaultEvalCalibration;
+}
+
+export type DefaultEvalTrend = 'too-few' | 'no-change' | 'improved' | 'regressed' | 'first-run';
+
+export interface DefaultEvalSuiteScore {
+  suite: DefaultEvalSuiteId;
+  title: string;
+  /** Slices that always appear. `model` holds only model-labelled cases; the other three exclude them. */
+  real: DefaultEvalSliceScore;
+  synthetic: DefaultEvalSliceScore;
+  combined: DefaultEvalSliceScore;
+  model: DefaultEvalSliceScore;
+  /** Per project (cross-project runs only), over real + synthetic. */
+  byProject?: Record<string, DefaultEvalSliceScore>;
+  /** Per answerer, when several surfaces answer the same question (needs-you). */
+  bySurface?: Record<string, DefaultEvalSliceScore>;
+  /** Against the last stored run of the same suite and scope, on the combined agreement. */
+  trend: { word: DefaultEvalTrend; previous: number | null; previousRunId: string | null };
+  /** Plain-words notes the suite must carry (why synthetic is unscored, which adapter is missing, …). */
+  notes: string[];
+}
+
+/** One input judged differently by place: the normalization drift a cross-project run surfaces. */
+export interface DefaultEvalDriftKey {
+  inputKey: string;
+  suite: DefaultEvalSuiteId;
+  /** `project` or `surface`: what differed. */
+  axis: 'project' | 'surface';
+  /** place → the observed labels there (sorted, distinct). */
+  observed: Record<string, string[]>;
+  caseIds: string[];
+}
+
+export interface DefaultEvalReport {
+  id: string;
+  createdAt: string;
+  /** `null` = every project (a cross-project run). */
+  project: string | null;
+  suites: DefaultEvalSuiteScore[];
+  drift: DefaultEvalDriftKey[];
+  counts: { real: number; synthetic: number; modelLabelled: number; unscored: number; baseline: number };
+  /** The minimum n a figure needs before it is called (and the calibration minimum). */
+  minimums: { rate: number; calibration: number };
+}
+
+export interface DefaultEvalSummary {
+  id: string;
+  createdAt: string;
+  project: string | null;
+  suites: Array<{ suite: DefaultEvalSuiteId; agreement: number | null; n: number; tooFew: boolean; trend: DefaultEvalTrend }>;
+  drift: number;
+  counts: DefaultEvalReport['counts'];
+}
+
+/** `GET /testing/default-evals/suites`. */
+export interface DefaultEvalSuitesResponse {
+  suites: Array<{
+    id: DefaultEvalSuiteId;
+    title: string;
+    /** Crew can run the current classifier on a case's input (so synthetic cases are scored). */
+    replay: boolean;
+    /** The generator makes synthetic cases for it. */
+    synthetic: boolean;
+    /** Why it cannot replay, when it cannot. */
+    note: string | null;
+  }>;
+}
+
+/** `POST /testing/default-evals/run` body. `project`: one project (or repo) id, or `"all"` (the default). */
+export interface RunDefaultEvalsBody {
+  project?: string;
+  suites?: DefaultEvalSuiteId[];
+  /** Count the shipped baseline cases too (the 2026-10-27 rig capture and the needs-you ruling). */
+  baseline?: boolean;
+}
+
+/** `GET /testing/default-evals`. Newest first. */
+export interface ListDefaultEvalRunsResponse {
+  runs: DefaultEvalSummary[];
+}
+
+/** `GET /testing/default-evals/:id`. */
+export interface DefaultEvalDetail {
+  report: DefaultEvalReport;
+  cases: DefaultEvalCase[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.138.0",
+  "version": "0.143.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",