@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/discover-criteria.ts

@@ -0,0 +1,348 @@
+/**
+ * scripts/discover-criteria.ts — EV-041 `*discover-evals`.
+ * ---------------------------------------------------------------------------
+ * Derive emergent BINARY ACTIONABLE eval criteria from LABELED ✓/✗ traces.
+ *
+ * The clustering itself is the LLM error-analyst's job (deep-read each trace,
+ * note the FIRST thing that went wrong, assign an emergent category — never a
+ * pre-defined list; error-analysis CORE §2/§3). This is the PURE, deterministic
+ * remainder of `*discover-evals`:
+ *   - aggregate annotations → one criterion per emergent category (support)
+ *   - compute per-category failure rates (prioritize what matters)
+ *   - FLAG fixable (infra/dependency) vs eval-worthy (behavioral). Fixables are
+ *     ROUTED to diagnostics (EV-051), NEVER fixed and NEVER judged on the model.
+ *   - detect saturation: stop when no NEW category emerges across rounds.
+ *
+ * "a judge is only a judge" — this module FLAGS, it does not fix. There is no
+ * `resolve`/`fix` field on a DiscoveredCriterion by construction.
+ *
+ * PURE + deterministic: criteria ranked by support desc then id; no clock/random.
+ */
+import {
+  AssumptionKind,
+  CheckMethod,
+  CriterionFlag,
+  Generality,
+  Grounding,
+  JudgeKind,
+  MetricDimension,
+  MetricLevel,
+  MetricSubstrate,
+  OutcomeVerdict,
+  Severity,
+  assertGroundingHonest,
+  type CheckMethodValue,
+  type CriterionFlagValue,
+  type DiscoveredCriterion,
+  type DiscoveryRef,
+  type GeneralityValue,
+  type GroundingValue,
+  type JudgeKindValue,
+  type MetricDimensionValue,
+  type MetricLevelValue,
+  type MetricMetadata,
+  type MetricSubstrateValue,
+  type MinedCriterion,
+  type DiscoveryRationale,
+  type OutcomeVerdictValue,
+  type SeverityValue,
+} from "./contracts/eval-types.ts";
+import type { CodeEvalSpec } from "./code-eval.ts";
+
+/**
+ * One annotation: the error-analyst's deep-read of a single trace. For a
+ * failure it carries the first-thing-that-went-wrong `note` + the emergent
+ * `category` + a classification (`infra` => fixable, else behavioral).
+ * `statement`/`judgeKind`/`judgeInputs` are the analyst's criterion proposal,
+ * carried on the first annotation that defines a category.
+ */
+export interface TraceAnnotation {
+  traceId: string;
+  label: OutcomeVerdictValue;
+  category?: string;
+  note?: string;
+  failureClass?: "infra" | "behavioral";
+  judgeKind?: JudgeKindValue;
+  statement?: string;
+  judgeInputs?: string[];
+  /**
+   * §5c evidence ref — a concrete `trace-id/field` pointer the analyst cited for
+   * THIS trace's failure. When present it is used as the grounding ref; else the
+   * traceId itself is the ref. ADDITIVE (P2b).
+   */
+  evidencePointer?: string;
+  /**
+   * GA-1 — STRUCTURED grounding refs `{obs,path,value}` the `#mode-discover` leaf
+   * cited for THIS trace's failure. PREFERRED over `evidencePointer` (which is
+   * synthesized into a best-effort structured ref when `refs` is absent). The
+   * `value` is the EXACT cited text so the ref re-resolves against the trace.
+   */
+  refs?: DiscoveryRef[];
+  /**
+   * Optional §5b metadata PROPOSALS the `#mode-discover` leaf may emit (additive
+   * agent-contract extension). When present they override the generic defaults
+   * `deriveMinedCriteria` would otherwise compute; when absent, defaults apply.
+   */
+  dimension?: MetricDimensionValue;
+  level?: MetricLevelValue;
+  generality?: GeneralityValue;
+  severity?: SeverityValue;
+  appliesTo?: string[];
+  /**
+   * The UNIFORM-STANDARD executable code-check the `#mode-discover` leaf EMITS when
+   * a mined criterion is deterministically checkable (it picks a registry primitive
+   * + field/params and tags the category `code`/`hybrid`). Carried onto the
+   * `MinedCriterion.codeEval` so the tier-0 pre-pass runs it (zero judge tokens).
+   * Absent for a pure `llm-judge` category. ADDITIVE.
+   */
+  codeEval?: CodeEvalSpec;
+}
+
+/** Group annotations by their emergent category (uncategorized are dropped). */
+export function groupByCategory(
+  annotations: TraceAnnotation[],
+): Map<string, TraceAnnotation[]> {
+  const groups = new Map<string, TraceAnnotation[]>();
+  for (const a of annotations) {
+    if (a.category === undefined || a.category.length === 0) continue;
+    const list = groups.get(a.category) ?? [];
+    list.push(a);
+    groups.set(a.category, list);
+  }
+  return groups;
+}
+
+export interface CategoryRate {
+  category: string;
+  fails: number;
+  total: number;
+  rate: number;
+}
+
+/** Per-category failure rate, ranked by fails desc then category asc. */
+export function failureRates(annotations: TraceAnnotation[]): CategoryRate[] {
+  const groups = groupByCategory(annotations);
+  const rates: CategoryRate[] = [];
+  for (const [category, list] of groups) {
+    const fails = list.filter((a) => a.label === OutcomeVerdict.Fail).length;
+    const total = list.length;
+    rates.push({ category, fails, total, rate: total === 0 ? 0 : fails / total });
+  }
+  return rates.sort((a, b) =>
+    b.fails - a.fails !== 0 ? b.fails - a.fails : a.category.localeCompare(b.category),
+  );
+}
+
+/** Pick the first non-empty value of `key` across a category's annotations. */
+function firstDefined<K extends keyof TraceAnnotation>(
+  list: TraceAnnotation[],
+  key: K,
+): TraceAnnotation[K] | undefined {
+  for (const a of list) {
+    if (a[key] !== undefined) return a[key];
+  }
+  return undefined;
+}
+
+/** A category is FIXABLE iff any of its failures is classified infra. */
+function flagFor(list: TraceAnnotation[]): CriterionFlagValue {
+  const anyInfra = list.some(
+    (a) => a.label === OutcomeVerdict.Fail && a.failureClass === "infra",
+  );
+  return anyInfra ? CriterionFlag.Fixable : CriterionFlag.EvalWorthy;
+}
+
+/**
+ * Derive one BINARY ACTIONABLE criterion per emergent category. Ranked by
+ * support (member count) desc then id asc. PURE — no fix is applied; the
+ * returned objects carry no resolution field.
+ */
+export function deriveCriteria(annotations: TraceAnnotation[]): DiscoveredCriterion[] {
+  const groups = groupByCategory(annotations);
+  const out: DiscoveredCriterion[] = [];
+  for (const [category, list] of groups) {
+    const statement = firstDefined(list, "statement") ?? `behavior is correct for: ${category}`;
+    const judgeKind = firstDefined(list, "judgeKind") ?? JudgeKind.Llm;
+    const judgeInputs = firstDefined(list, "judgeInputs") ?? ["prompt", "trajectory", "response"];
+    out.push({
+      id: category,
+      statement,
+      judgeInputs,
+      judgeKind,
+      flag: flagFor(list),
+      supportCount: list.length,
+    });
+  }
+  return out.sort((a, b) =>
+    b.supportCount - a.supportCount !== 0
+      ? b.supportCount - a.supportCount
+      : a.id.localeCompare(b.id),
+  );
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// P2 / P2b — mined criteria with §5b metadata + §5c DR-2 (evidence-first)
+// ════════════════════════════════════════════════════════════════════════════
+
+/** Map the analyst's JudgeKind → the §5b check_method router (SF-2). */
+function checkMethodFor(judgeKind: JudgeKindValue): CheckMethodValue {
+  if (judgeKind === JudgeKind.Code) return CheckMethod.Deterministic;
+  if (judgeKind === JudgeKind.Hybrid) return CheckMethod.Hybrid;
+  return CheckMethod.LlmJudge;
+}
+
+/** §5b substrate is DERIVED from check_method: deterministic→code, else judge. */
+function substrateFor(checkMethod: CheckMethodValue): MetricSubstrateValue {
+  return checkMethod === CheckMethod.Deterministic ? MetricSubstrate.Code : MetricSubstrate.Judge;
+}
+
+/** Generic generality heuristic: a code/deterministic check is general-structural
+ *  (reusable on any pipeline); a judge check is specific-semantic. The leaf may
+ *  override via `annotation.generality`. */
+function generalityFor(checkMethod: CheckMethodValue): GeneralityValue {
+  return checkMethod === CheckMethod.Deterministic
+    ? Generality.GeneralStructural
+    : Generality.SpecificSemantic;
+}
+
+/** Generic severity heuristic from observed failure count (leaf may override). */
+function severityFor(fails: number): SeverityValue {
+  if (fails >= 2) return Severity.High;
+  if (fails === 1) return Severity.Med;
+  return Severity.Low;
+}
+
+/** Map the criterion flag → the §5c fix_or_eval routing string. */
+function fixOrEvalFor(flag: CriterionFlagValue): DiscoveryRationale["fix_or_eval"] {
+  return flag === CriterionFlag.Fixable ? "fixable->diagnostics" : "eval-worthy";
+}
+
+/** Synthesize a best-effort structured ref from a legacy `trace-id/field`
+ *  pointer string + note (GA-1 back-compat: the leaf may still emit a pointer). */
+function synthRef(a: TraceAnnotation): DiscoveryRef {
+  const ptr = a.evidencePointer ?? a.traceId;
+  const slash = ptr.indexOf("/");
+  const obs = slash >= 0 ? ptr.slice(0, slash) : a.traceId;
+  const path = slash >= 0 ? ptr.slice(slash + 1) : "";
+  // value = the exact cited text (note) when present, else the pointer itself.
+  const value = a.note !== undefined && a.note.length > 0 ? a.note : ptr;
+  return { obs, path, value };
+}
+
+/** GA-1 — the STRUCTURED evidence refs for a category = the failing annotations'
+ *  cited structured refs (preferred), else a synthesized ref from the legacy
+ *  pointer. REAL refs, in input order. */
+function refsFor(list: TraceAnnotation[]): DiscoveryRef[] {
+  const out: DiscoveryRef[] = [];
+  for (const a of list) {
+    if (a.label !== OutcomeVerdict.Fail) continue;
+    if (a.refs !== undefined && a.refs.length > 0) out.push(...a.refs);
+    else out.push(synthRef(a));
+  }
+  return out;
+}
+
+/**
+ * Derive the full set of MINED criteria from real annotations: the existing
+ * `deriveCriteria` output ENRICHED with the §5b unified metadata + the §5c DR-2
+ * discovery-rationale, grounded in the actual support set. EVIDENCE-FIRST:
+ *   - OBSERVED iff a failure was actually seen (fails>0) — cites the real failing
+ *     refs + an honest `k/n sampled` prevalence; never promotes inferred→observed.
+ *   - a pass-only category is INFERRED (good-practice guard, no failure yet).
+ * PURE + deterministic (same ranking as deriveCriteria: support desc, id asc).
+ */
+export function deriveMinedCriteria(annotations: TraceAnnotation[]): MinedCriterion[] {
+  const groups = groupByCategory(annotations);
+  const base = deriveCriteria(annotations); // ranked; carries id/statement/judgeKind/judgeInputs/flag/support
+  return base.map((c) => {
+    const list = groups.get(c.id) ?? [];
+    const fails = list.filter((a) => a.label === OutcomeVerdict.Fail).length;
+    const total = list.length;
+    const refs = refsFor(list);
+    const firstNote = firstDefined(list, "note");
+
+    const checkMethod = checkMethodFor(c.judgeKind);
+    const grounding: GroundingValue = fails > 0 && refs.length > 0 ? Grounding.Observed : Grounding.Inferred;
+    const severity = firstDefined(list, "severity") ?? severityFor(fails);
+
+    const metadata: MetricMetadata = {
+      generality: firstDefined(list, "generality") ?? generalityFor(checkMethod),
+      dimension: firstDefined(list, "dimension") ?? MetricDimension.OperationCorrectness,
+      level: firstDefined(list, "level") ?? MetricLevel.Output,
+      check_method: checkMethod,
+      substrate: substrateFor(checkMethod),
+      applies_to: firstDefined(list, "appliesTo") ?? [],
+      severity,
+      judge_inputs: c.judgeInputs,
+      flag: c.flag,
+    };
+
+    const discovery: DiscoveryRationale = {
+      targets: `the '${c.id}' behavior/failure mode`,
+      why_problem:
+        fails > 0
+          ? `failure mode observed${firstNote !== undefined ? ` (first-thing-wrong: ${firstNote})` : ""}`
+          : "good-practice guard — no failure observed in the sample yet",
+      evidence: {
+        grounding,
+        seen_in_traces: fails > 0,
+        prevalence: `${fails}/${total} sampled`,
+        refs: grounding === Grounding.Observed ? refs : [],
+      },
+      reasoning:
+        `${fails}/${total} trace(s) in category '${c.id}'` +
+        `${firstNote !== undefined ? `; first-thing-wrong: ${firstNote}` : ""} → criterion`,
+      assumptions:
+        grounding === Grounding.Observed
+          ? [
+              {
+                text: "the observed failure recurs under the same template",
+                status: "unverified",
+                kind: AssumptionKind.FactualIntent,
+              },
+            ]
+          : [
+              {
+                text: "preventive guard; no failure observed yet",
+                status: "hypothesis",
+                kind: AssumptionKind.Normative,
+              },
+            ],
+      expected_impact: {
+        severity,
+        coverage: `${total} sampled trace(s)`,
+        confidence: grounding === Grounding.Observed ? (fails >= 2 ? "high" : "med") : "low",
+      },
+      fix_or_eval: fixOrEvalFor(c.flag),
+    };
+
+    // UNIFORM STANDARD — carry the leaf-emitted executable code-check (when the
+    // category is deterministically checkable) onto the criterion so the tier-0
+    // pre-pass can run it. A pure judge category leaves it undefined.
+    const codeEval = firstDefined(list, "codeEval");
+
+    const mined: MinedCriterion = {
+      ...c,
+      metadata,
+      discovery,
+      ...(codeEval !== undefined ? { codeEval } : {}),
+    };
+    assertGroundingHonest(mined); // defensive — never ship inferred-as-observed
+    return mined;
+  });
+}
+
+/**
+ * Saturation: the next round surfaced NO new category. `prev` is the cumulative
+ * category set; `next` is the latest round's categories. Saturated iff every
+ * category in `next` is already in `prev`.
+ */
+export function isSaturated(prev: string[], next: string[]): boolean {
+  const seen = new Set(prev);
+  return next.every((c) => seen.has(c));
+}
+
+/** The error-analysis target band: aim for 5-10 distinct categories. */
+export function withinSaturationBand(categories: string[]): boolean {
+  return categories.length >= 5 && categories.length <= 10;
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/edd/change-request.ts

@@ -0,0 +1,232 @@
+/**
+ * scripts/edd/change-request.ts — F18 EDD CLOSURE (the spec↔impl↔eval triad).
+ * ---------------------------------------------------------------------------
+ * The Evaluator is JUDGE-ONLY (EV-051): it NEVER fixes the subject. To close the
+ * EDD loop it instead REQUESTS the AI-Engineer (the *build ACTOR from the SPEC
+ * stage) to amend the Agent / AgentSpec — wired over the `SendMessage` tool both
+ * agents carry. This module is the structured contract for that hand-off:
+ *
+ *   evaluator  --(EddChangeRequest)-->  ai-engineer        (the failing cases + remedy target)
+ *   ai-engineer --(ChangeRequestResponse)--> evaluator     (amended | rejected)
+ *   evaluator  re-evaluates  →  loop until full green OR a bounded STOP.
+ *
+ * The contract is the SEAM: the evaluator emits a request (validated here), the
+ * engineer consumes it (validated here), and the loop controller (also here)
+ * decides — using ONLY observable state — whether to swing again or terminate.
+ * The termination gate is afkloop-legal: full-green is the success terminator, and
+ * three bounds (max-swings · max-wallclock · no-improvement-streak) guarantee the
+ * loop is NEVER infinite.
+ *
+ * PURE — no clock / Math.random / network. The wall-clock bound is checked against
+ * an INJECTED elapsed value (the caller measures time; this module only decides),
+ * keeping the controller deterministic + unit-testable (C-PIN).
+ */
+import { Value } from "@sinclair/typebox/value";
+import {
+  ChangeRequestStatus,
+  EddPhase,
+  EddStopReason,
+  EddChangeRequestSchema,
+  ChangeRequestResponseSchema,
+  RemedyTarget,
+  type EddChangeRequestType,
+  type ChangeRequestResponseType,
+  type EddPhaseValue,
+  type EddStopReasonValue,
+  type RemedyTargetValue,
+} from "./edd-types.ts";
+
+// Re-export the Static types under their public names (edd-types declares the schemas).
+export type { EddChangeRequestType, ChangeRequestResponseType };
+
+// ── Validators (fail-loud over the SendMessage seam) ────────────────────────
+
+/**
+ * Validate an evaluator→engineer change-request. THROWS with the first TypeBox
+ * error path on any violation — a malformed request must never cross the seam
+ * silently (an ungrounded ask, a missing remedy target, etc. fail loud here).
+ */
+export function validateChangeRequest(req: unknown): EddChangeRequestType {
+  if (!Value.Check(EddChangeRequestSchema, req)) {
+    const first = [...Value.Errors(EddChangeRequestSchema, req)][0];
+    throw new Error(
+      `EddChangeRequest invalid${first ? ` at ${first.path}: ${first.message}` : ""}`,
+    );
+  }
+  // Belt-and-braces: every failing case must be GROUNDED (≥1 ref). The schema
+  // enforces minItems:1 on refs, but assert the intent explicitly for the seam.
+  for (const fc of req.failingCases) {
+    if (fc.refs.length === 0) {
+      throw new Error(
+        `EddChangeRequest invalid: failing case "${fc.caseId}" has no grounding refs (ungrounded ask — EV-051/GA-1)`,
+      );
+    }
+  }
+  return req;
+}
+
+/**
+ * Validate an engineer→evaluator response. THROWS on a malformed reply. A
+ * `rejected` status MUST carry a `note` (the reason) — enforced by the schema's
+ * minLength on `note`; an `amended` status SHOULD echo `amendedTarget`.
+ */
+export function validateChangeResponse(res: unknown): ChangeRequestResponseType {
+  if (!Value.Check(ChangeRequestResponseSchema, res)) {
+    const first = [...Value.Errors(ChangeRequestResponseSchema, res)][0];
+    throw new Error(
+      `ChangeRequestResponse invalid${first ? ` at ${first.path}: ${first.message}` : ""}`,
+    );
+  }
+  return res;
+}
+
+/**
+ * Does this response warrant a re-eval? Only an `amended` response does — a
+ * `rejected` one means the engineer declined (the evaluator must re-target or
+ * escalate, NOT re-eval an unchanged subject). There is no "trust me, skip
+ * re-eval" path: an amend ALWAYS triggers a fresh evaluation swing.
+ */
+export function reEvalWarranted(res: ChangeRequestResponseType): boolean {
+  return res.status === ChangeRequestStatus.Amended;
+}
+
+// ── F18 loop control — the bounded EDD terminator ───────────────────────────
+
+export interface EddLoopBudget {
+  /** hard cap on evaluator→engineer→re-eval swings. */
+  maxSwings: number;
+  /** hard wall-clock budget in ms (checked against an injected elapsed). */
+  maxWallclockMs: number;
+  /** stop after this many consecutive swings with no measurable improvement. */
+  noImprovementStreakLimit: number;
+}
+
+export const DEFAULT_EDD_LOOP_BUDGET: EddLoopBudget = {
+  maxSwings: 6,
+  maxWallclockMs: 30 * 60 * 1000, // 30 min
+  noImprovementStreakLimit: 2,
+};
+
+/**
+ * The observable loop state the controller reasons over. ALL fields are measured
+ * by the caller (the evaluator parent session) and handed in — the controller is
+ * a PURE decision function, so the same state always yields the same decision.
+ */
+export interface EddLoopState {
+  /** the current EDD phase (variance vs accuracy vs build). */
+  phase: EddPhaseValue;
+  /** 1-based count of swings COMPLETED so far. */
+  swing: number;
+  /** F19 — is the per-case variance gate currently passing? */
+  varianceStable: boolean;
+  /** is accuracy ≥ target over the dataset? (meaningful only post-variance). */
+  accuracyMet: boolean;
+  /** measured elapsed wall-clock for the whole loop, ms (injected — not read here). */
+  elapsedMs: number;
+  /**
+   * consecutive swings with no measurable improvement (the caller computes this
+   * from a monotone progress metric — e.g. fewer flapping/failing cases). 0 ⇒
+   * the last swing improved something.
+   */
+  noImprovementStreak: number;
+}
+
+export interface EddLoopDecision {
+  /** true ⇒ terminate now; false ⇒ swing again. */
+  done: boolean;
+  /** WHY it stopped — set iff done; null while the loop should continue. */
+  reason: EddStopReasonValue | null;
+  /** the next phase to run (DONE/STOPPED when terminating). */
+  nextPhase: EddPhaseValue;
+  /** human one-liner — the convergence delta when bounded, the green when done. */
+  detail: string;
+}
+
+/**
+ * THE termination gate (afkloop-legal — observable + bounded + no infinite loop).
+ *
+ * Order of checks (success first, then the three bounds):
+ *   1. FULL GREEN   — varianceStable AND accuracyMet ⇒ DONE (success).
+ *   2. MAX SWINGS   — swing ≥ budget.maxSwings ⇒ STOP (report delta).
+ *   3. MAX WALLCLOCK— elapsedMs ≥ budget.maxWallclockMs ⇒ STOP.
+ *   4. NO-IMPROVE   — noImprovementStreak ≥ budget.noImprovementStreakLimit ⇒ STOP.
+ *   else CONTINUE — keep swinging; the next phase is variance until it's stable,
+ *   then accuracy (F19 ordering is preserved by `nextPhaseAfterVariance`, but the
+ *   loop controller mirrors it: not-stable ⇒ variance, stable ⇒ accuracy).
+ *
+ * PURE: no clock read — `elapsedMs` is injected. Same state → same decision.
+ */
+export function decideEddLoop(
+  state: EddLoopState,
+  budget: EddLoopBudget = DEFAULT_EDD_LOOP_BUDGET,
+): EddLoopDecision {
+  // 1. SUCCESS terminator — full green.
+  if (state.varianceStable && state.accuracyMet) {
+    return {
+      done: true,
+      reason: EddStopReason.FullGreen,
+      nextPhase: EddPhase.Done,
+      detail: `full green after ${state.swing} swing(s): variance stable AND accuracy met`,
+    };
+  }
+  // 2-4. Bounded non-convergence terminators (each reports the convergence delta).
+  if (state.swing >= budget.maxSwings) {
+    return stopped(
+      EddStopReason.MaxSwings,
+      `hit max swings (${state.swing}/${budget.maxSwings}); varianceStable=${state.varianceStable} accuracyMet=${state.accuracyMet}`,
+    );
+  }
+  if (state.elapsedMs >= budget.maxWallclockMs) {
+    return stopped(
+      EddStopReason.MaxWallclock,
+      `hit wall-clock budget (${state.elapsedMs}ms/${budget.maxWallclockMs}ms); varianceStable=${state.varianceStable} accuracyMet=${state.accuracyMet}`,
+    );
+  }
+  if (state.noImprovementStreak >= budget.noImprovementStreakLimit) {
+    return stopped(
+      EddStopReason.NoImprovementStreak,
+      `no improvement for ${state.noImprovementStreak} consecutive swing(s) (limit ${budget.noImprovementStreakLimit})`,
+    );
+  }
+  // CONTINUE — preserve F19 ordering: stabilize variance before accuracy.
+  const nextPhase = state.varianceStable ? EddPhase.Accuracy : EddPhase.Variance;
+  return {
+    done: false,
+    reason: null,
+    nextPhase,
+    detail: `continue: next phase ${nextPhase} (swing ${state.swing}, variance ${state.varianceStable ? "stable" : "flapping"})`,
+  };
+}
+
+function stopped(reason: EddStopReasonValue, detail: string): EddLoopDecision {
+  return { done: true, reason, nextPhase: EddPhase.Stopped, detail };
+}
+
+/**
+ * Build a well-formed change-request for the evaluator to SendMessage. Validates
+ * before returning so a malformed request can never leave the evaluator. The
+ * caller supplies the swing index + the grounded failing cases + the proposed
+ * remedy + the target; this stamps `status: requested`.
+ */
+export function buildChangeRequest(input: {
+  requestId: string;
+  swing: number;
+  subject: string;
+  remedyTarget: RemedyTargetValue;
+  failingCases: EddChangeRequestType["failingCases"];
+  proposedRemedy: string;
+}): EddChangeRequestType {
+  const req: EddChangeRequestType = {
+    requestId: input.requestId,
+    swing: input.swing,
+    subject: input.subject,
+    remedyTarget: input.remedyTarget,
+    failingCases: input.failingCases,
+    proposedRemedy: input.proposedRemedy,
+    status: ChangeRequestStatus.Requested,
+  };
+  return validateChangeRequest(req);
+}
+
+/** Convenience: the two remedy targets, re-exported for callers building requests. */
+export { RemedyTarget };