@kindgi/api 0.1.4-rc.0 → 0.1.4-rc.2

package/src/routes/approvals.ts

@@ -406,6 +406,7 @@ export function approvalsRouter(
     // override it, when the resume payload must carry more than the
     // decision (an agent gate refuses one, above).
     let waitpointResolved = false;
+    let resume: ResumeReport | undefined;
     if (
       approval.waitTokenId !== undefined &&
       approval.provenanceRef?.runId !== undefined &&
@@ -440,15 +441,12 @@ export function approvalsRouter(
       // journaled `wait.resumed`. The approval-complete surface reports
       // the decision as successful; a run that stayed suspended because
       // the inline resume failed can be resumed later.
+      //
+      // The response says how the resume went (`resume`), so a decision
+      // whose run couldn't go on (a tool version it started with is gone,
+      // say) isn't reported as plain success.
       if (runHandler !== undefined) {
-        try {
-          await runHandler.resumeRun({
-            tenantId,
-            runId: approval.provenanceRef.runId as RunId,
-          });
-        } catch {
-          // Soft-fail — the decision is durable; the run can be resumed later.
-        }
+        resume = await resumeInline(runHandler, tenantId, approval.provenanceRef.runId as RunId);
       }
     }
 
@@ -461,6 +459,7 @@ export function approvalsRouter(
         nextApproval: serializeApproval(result.nextApproval),
       }),
       waitpointResolved,
+      ...(resume !== undefined && { resume }),
     });
   });
 
@@ -808,3 +807,32 @@ function parseAuditBundleBody(
     },
   };
 }
+
+/** How the inline resume after a decision went. */
+type ResumeReport =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'failed'; readonly code: string; readonly message: string };
+
+/**
+ * Resume the run a decision released, in the same request. A resume that
+ * fails is reported, not raised: the decision is durable either way, and
+ * the runtime ends a run that can't go on, or resumes it later.
+ */
+async function resumeInline(
+  runHandler: RunHandlerBinding,
+  tenantId: TenantId,
+  runId: RunId,
+): Promise<ResumeReport> {
+  try {
+    const outcome = await runHandler.resumeRun({ tenantId, runId });
+    return outcome.kind === 'ok'
+      ? { kind: 'ok' }
+      : { kind: 'failed', code: outcome.error.code, message: outcome.error.message };
+  } catch (cause) {
+    return {
+      kind: 'failed',
+      code: 'resume-failed',
+      message: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+}

package/src/routes/audit.ts

@@ -21,6 +21,7 @@
 //   ?from=<iso>&to=<iso>
 //   ?runId=<id>
 //   ?limit=<n>&cursor=<opaque>
+//   ?order=asc|desc   (asc, oldest first, by default)
 //
 
 import { Hono } from 'hono';
@@ -83,6 +84,14 @@ export function auditRouter(binding: AuditEventBinding, authorizer?: Authorizer)
     const from = c.req.query('from');
     const to = c.req.query('to');
     const runId = c.req.query('runId');
+    const orderRaw = c.req.query('order');
+
+    if (orderRaw !== undefined && orderRaw !== 'asc' && orderRaw !== 'desc') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: '`order` must be "asc" or "desc"' }, requestId),
+      );
+    }
 
     let outcome: 'allowed' | 'denied' | undefined;
     if (outcomeRaw === 'allowed' || outcomeRaw === 'denied') outcome = outcomeRaw;
@@ -130,6 +139,7 @@ export function auditRouter(binding: AuditEventBinding, authorizer?: Authorizer)
         ...(to !== undefined && to.length > 0 && { to }),
       },
       ...(cursor !== undefined && cursor.length > 0 && { cursor }),
+      ...(orderRaw !== undefined && { order: orderRaw }),
       limit,
     });
 

package/src/routes/auth.ts

@@ -76,7 +76,7 @@ export function authRouters(options: AuthRouterOptions): {
   authed.get('/providers', async (c) => {
     const tenantId = c.get('tenantId') as TenantId;
     const page = await identityProvider.list({ tenantId });
-    return c.json({ data: page.data.map(serializeProviderConfig) });
+    return c.json({ data: page.data.map(serializeProviderConfig), hasMore: false });
   });
 
   // ---------- POST /providers ----------

package/src/routes/blocks.ts

@@ -184,14 +184,20 @@ export function blocksRouter(binding: BlockRegistryBinding, authorizer?: Authori
       return validationFailed(c, validated.error.message, validated.error.issues);
     const block = validated.value;
 
-    // A block keeps its kind, and a settings block's latest schema holds.
+    // A block keeps its kind. A settings version without a schema keeps
+    // the latest version's (stored on it, so the check carries forward to
+    // every later version); one that gives a schema replaces it.
     const latest = await binding.get({ tenantId, blockId: block.id });
     const continuity = continuityIssues(latest, block);
     if (continuity.length > 0) {
       return validationFailed(c, `Block "${block.id}" can't take this version`, continuity);
     }
 
-    const outcome = await binding.publish({ tenantId, projectId: projectId as ProjectId, block });
+    const outcome = await binding.publish({
+      tenantId,
+      projectId: projectId as ProjectId,
+      block: withCarriedSchema(latest, block),
+    });
     return published(c, outcome);
   });
 
@@ -243,7 +249,11 @@ function isBlockKind(value: string): value is BlockKind {
   return (BLOCK_KINDS as readonly string[]).includes(value);
 }
 
-/** A new version against the block's latest: same kind, and a settings block's schema holds. */
+/**
+ * A new version against the block's latest: the same kind, and a
+ * settings version without a schema of its own satisfies the schema it
+ * keeps (`carriedSchema`).
+ */
 function continuityIssues(
   latest: BlockRecord | null,
   block: BlockDefinition,
@@ -257,17 +267,32 @@ function continuityIssues(
       },
     ];
   }
-  if (
-    latest.kind === 'settings' &&
-    block.kind === 'settings' &&
-    latest.content.schema !== undefined
-  ) {
-    return settingsSchemaIssues(block.content.values, latest.content.schema).map((i) => ({
-      ...i,
-      message: `${i.message} (the schema of version ${latest.version})`,
-    }));
-  }
-  return [];
+  const carried = carriedSchema(latest, block);
+  if (block.kind !== 'settings' || carried === undefined) return [];
+  return settingsSchemaIssues(block.content.values, carried).map((i) => ({
+    ...i,
+    message: `${i.message} (the schema of version ${latest.version})`,
+  }));
+}
+
+/**
+ * The schema a settings version that gives none keeps: the latest
+ * version's. A version that gives a schema replaces it (`{}` drops the
+ * check on purpose).
+ */
+function carriedSchema(
+  latest: BlockRecord | null,
+  block: BlockDefinition,
+): Readonly<Record<string, unknown>> | undefined {
+  if (latest?.kind !== 'settings' || block.kind !== 'settings') return undefined;
+  return block.content.schema === undefined ? latest.content.schema : undefined;
+}
+
+/** The version as stored: with the schema it keeps, if any. */
+function withCarriedSchema(latest: BlockRecord | null, block: BlockDefinition): BlockDefinition {
+  const schema = carriedSchema(latest, block);
+  if (schema === undefined || block.kind !== 'settings') return block;
+  return { ...block, content: { ...block.content, schema } };
 }
 
 /** The response to a publish outcome. */

package/src/routes/conversations.ts

@@ -18,6 +18,7 @@ import { statusFor, toWireError } from '../errors.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
 import { parseListScope } from './scope-params.js';
+import { refuseMalformedUuidParam } from './uuid-param.js';
 
 const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -28,6 +29,15 @@ const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]
  * order); conversation list sort is `openedAt DESC, id DESC`
  * (most-recently-opened first).
  */
+/**
+ * A `:conversationId` that isn't a conversation id is a 400
+ * (`uuid-param.ts`), not a 500 from the uuid cast (as `runs` does).
+ */
+const refuseMalformedConversationId = refuseMalformedUuidParam(
+  'conversationId',
+  'a conversation id',
+);
+
 export function conversationsRouter(
   conversationBinding: ConversationBinding,
   runBinding: RunBinding,
@@ -62,6 +72,23 @@ export function conversationsRouter(
 
     const agentIdRaw = c.req.query('agentId');
 
+    // Replay conversations (a comparison's replays) are left out unless asked for.
+    const replaysRaw = c.req.query('replays');
+    if (
+      replaysRaw !== undefined &&
+      replaysRaw !== 'exclude' &&
+      replaysRaw !== 'include' &&
+      replaysRaw !== 'only'
+    ) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          { code: 'bad-input', message: '`replays` must be `exclude`, `include` or `only`' },
+          requestId,
+        ),
+      );
+    }
+
     const scopeParsed = parseListScope(c.req.query(), { tenantId });
     if (scopeParsed.kind === 'err') {
       c.status(statusFor('scope-invalid') as never);
@@ -88,6 +115,7 @@ export function conversationsRouter(
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw as AgentId }),
       ...(statusFilter !== undefined && { status: statusFilter }),
+      replays: replaysRaw ?? 'exclude',
       ...(before !== undefined && { before }),
       limit,
     });
@@ -112,7 +140,7 @@ export function conversationsRouter(
   });
 
   // ---------- GET /:conversationId ----------
-  r.get('/:conversationId', async (c) => {
+  r.get('/:conversationId', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const conversationId = c.req.param('conversationId') as ConversationId;
@@ -186,7 +214,7 @@ export function conversationsRouter(
   });
 
   // ---------- POST /:conversationId/close (idempotent) ----------
-  r.post('/:conversationId/close', async (c) => {
+  r.post('/:conversationId/close', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const conversationId = c.req.param('conversationId') as ConversationId;
@@ -214,7 +242,7 @@ export function conversationsRouter(
   });
 
   // ---------- GET /:conversationId/messages (cursor-paginated, sequence asc) ----------
-  r.get('/:conversationId/messages', async (c) => {
+  r.get('/:conversationId/messages', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const conversationId = c.req.param('conversationId') as ConversationId;

package/src/routes/deployments.ts

@@ -38,9 +38,12 @@ import type {
 } from '../deployment-binding.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { FlowRegistryBinding } from '../flow-binding.js';
-import { publishDeployedFlow, resolveFlowPins } from '../flow-pins.js';
+import { type FlowPinsLive, publishDeployedFlow, resolveFlowPins } from '../flow-pins.js';
 import type { GuardrailRegistryBinding } from '../guardrail-binding.js';
 import type { ImageRegistryBinding } from '../image-registry-binding.js';
+import type { LiveVersionBinding } from '../live-version-binding.js';
+import { PublishRefused } from '../publish-refused.js';
+import { type RegistryReadOnly, refuseReadOnly } from '../registry-read-only.js';
 import type { SecretBinding } from '../secrets-binding.js';
 import type { SigningKeyBinding as SigningKeyRegistryBinding } from '../signing-key-binding.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
@@ -121,6 +124,11 @@ export interface DeploymentsRouterBindings {
   readonly guardrailRegistry?: GuardrailRegistryBinding;
   readonly agentRegistry?: AgentRegistryBinding;
   readonly flowRegistry?: FlowRegistryBinding;
+  /**
+   * The agents' live versions: a deployed flow's agent step that names no
+   * version pins the one live for the deploy's project, else the latest.
+   */
+  readonly liveVersions?: LiveVersionBinding;
   /** Data blocks: an agent's block references are pinned at deploy with its tools. */
   readonly blockRegistry?: BlockRegistryBinding;
   /**
@@ -487,6 +495,11 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
     }
     const validated = validation.value;
 
+    // A read-only registry (under `kindgi dev`, the pack's files) takes
+    // nothing a deployment brings: refuse before any write.
+    const readOnly = readOnlyTarget(validated, bindings);
+    if (readOnly !== undefined) return refuseReadOnly(c, readOnly);
+
     // ---- Registry upserts (with rollback tracking) ----
     //
     // Agent-registry, flow-registry, tool-registry, and
@@ -566,6 +579,8 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             rolled.push(async () => {
               await bindings.toolRegistry?.unregister({ tenantId, toolId, version });
             });
+          } else if (outcome.kind !== 'already-registered') {
+            throw new PublishRefused('tool', `${tool.id}@${tool.version}`, outcome.kind);
           }
         }
       }
@@ -589,6 +604,8 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             rolled.push(async () => {
               await bindings.guardrailRegistry?.unregister({ tenantId, guardrailId });
             });
+          } else if (outcome.kind !== 'already-registered') {
+            throw new PublishRefused('guardrail', guardrail.id, outcome.kind);
           }
         }
       }
@@ -613,6 +630,7 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             flows: bindings.flowRegistry,
             tools: bindings.toolRegistry,
             agents: bindings.agentRegistry,
+            ...(bindings.liveVersions !== undefined && { live: bindings.liveVersions }),
             tenantId,
             projectId: defaultProjectId,
             defined: validated.flows,
@@ -624,6 +642,22 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
       }
     } catch (cause) {
       await rollback(rolled);
+      // A primitive refused with a typed outcome is the caller's to fix:
+      // that outcome's own status and code. Anything thrown is a 500.
+      if (cause instanceof PublishRefused) {
+        c.status(statusFor(cause.code) as never);
+        return c.json(
+          toWireError(
+            {
+              code: cause.code,
+              message: `${cause.message}; nothing was deployed`,
+              primitive: cause.primitive,
+              id: cause.id,
+            },
+            requestId,
+          ),
+        );
+      }
       if (cause instanceof UnpinnableDeploy) {
         c.status(statusFor('invalid-agent') as never);
         return c.json(
@@ -1489,6 +1523,9 @@ async function registerAgents(input: {
     for (const agent of input.defined) {
       const outcome = await agents.publish({ tenantId, projectId, agent, enqueueTuples });
       if (outcome.kind === 'ok') written(outcome.agentId, outcome.version);
+      else if (outcome.kind !== 'already-registered') {
+        throw new PublishRefused('agent', `${agent.id}@${agent.version}`, outcome.kind);
+      }
     }
     return input.defined.map(deployedPrimitive);
   }
@@ -1518,7 +1555,10 @@ async function registerAgents(input: {
  * as, pushing a rollback for each version it writes. Runs after the
  * agents, so a flow's agent pins see the versions this deploy
  * registered: a tool change cascades through an agent into a flow
- * within the one deploy, each derived once.
+ * within the one deploy, each derived once. An agent step that names no
+ * version pins what a run in the project gets: the agent's live version
+ * there, with `live`, else the latest (this deploy's, when it registered
+ * one).
  *
  * With the tool and agent registries, every flow is pinned first; one
  * that runs a tool or agent with no published version throws
@@ -1529,12 +1569,13 @@ async function registerFlows(input: {
   readonly flows: FlowRegistryBinding;
   readonly tools: ToolRegistryBinding | undefined;
   readonly agents: AgentRegistryBinding | undefined;
+  readonly live?: LiveVersionBinding;
   readonly tenantId: TenantId;
   readonly projectId: ProjectId;
   readonly defined: readonly Flow[];
   readonly rolled: RollbackAction[];
 }): Promise<DeployedFlow[]> {
-  const { flows, tools, agents, tenantId, projectId, rolled } = input;
+  const { flows, tools, agents, live, tenantId, projectId, rolled } = input;
   const enqueueTuples = (flowId: string) =>
     tuplesForCreate({ kind: 'flow', id: flowId as FlowId, tenantId, projectId });
   const written = (flowId: FlowId, version: string) =>
@@ -1546,11 +1587,20 @@ async function registerFlows(input: {
     for (const flow of input.defined) {
       const outcome = await flows.publish({ tenantId, projectId, flow, enqueueTuples });
       if (outcome.kind === 'ok') written(outcome.flowId, outcome.version as unknown as string);
+      else if (outcome.kind !== 'already-registered') {
+        throw new PublishRefused('flow', `${flow.id}@${flow.version}`, outcome.kind);
+      }
     }
     return input.defined.map(deployedPrimitive);
   }
 
-  const pinsOf = await pinFlows(tools, agents, tenantId, input.defined);
+  const pinsOf = await pinFlows(
+    tools,
+    agents,
+    tenantId,
+    input.defined,
+    live !== undefined ? { binding: live, projectId } : undefined,
+  );
   const deployed: DeployedFlow[] = [];
   for (const [i, flow] of input.defined.entries()) {
     const outcome = await publishDeployedFlow({
@@ -1575,11 +1625,12 @@ async function pinFlows(
   agents: AgentRegistryBinding,
   tenantId: TenantId,
   defined: readonly Flow[],
+  live: FlowPinsLive | undefined,
 ): Promise<FlowPins[]> {
   const pins: FlowPins[] = [];
   const unpinnable: UnpinnableRef[] = [];
   for (const [i, flow] of defined.entries()) {
-    const resolved = await resolveFlowPins(tools, agents, tenantId, flow);
+    const resolved = await resolveFlowPins(tools, agents, tenantId, flow, live);
     if (resolved.kind === 'ok') {
       pins.push(resolved.pins);
       continue;
@@ -1701,3 +1752,22 @@ export function sha256HexPrefixed(bytes: Uint8Array): string {
   const hex = createHash('sha256').update(bytes).digest('hex');
   return `sha256:${hex}`;
 }
+
+/** The first read-only registry a deployment would publish into, if any. */
+function readOnlyTarget(
+  validated: {
+    readonly tools: readonly unknown[];
+    readonly agents: readonly unknown[];
+    readonly flows: readonly unknown[];
+    readonly guardrails: readonly unknown[];
+  },
+  bindings: DeploymentsRouterBindings,
+): RegistryReadOnly | undefined {
+  const targets = [
+    [validated.tools, bindings.toolRegistry?.readOnly],
+    [validated.agents, bindings.agentRegistry?.readOnly],
+    [validated.flows, bindings.flowRegistry?.readOnly],
+    [validated.guardrails, bindings.guardrailRegistry?.readOnly],
+  ] as const;
+  return targets.find(([brought, readOnly]) => brought.length > 0 && readOnly !== undefined)?.[1];
+}

package/src/routes/env.ts

@@ -87,6 +87,7 @@ export function envRouter(envBinding: EnvBinding, authorizer?: Authorizer): Hono
     });
     return c.json({
       data: page.data.map(serializeEnvRecord),
+      hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
   });

package/src/routes/eval-comparison.ts

@@ -2,10 +2,12 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { ProjectId, Semver } from '@kindgi/types';
 
 import type { EvalBaseline, EvalComparison } from '../eval-run-binding.js';
 import { DEFAULT_COMPARISON } from '../judged-dispatcher.js';
+import { parseSegmentsBody } from './segments.js';
 
 const MAX_REPETITIONS = 10;
 const MAX_K = 100;
@@ -19,19 +21,18 @@ function obj(value: unknown): Record<string, unknown> | undefined {
 function parseLive(raw: unknown): EvalBaseline | string {
   const live = obj(raw);
   if (live === undefined) return '`baseline.live` must be an object';
-  const segments = live.segments === undefined ? undefined : obj(live.segments);
-  const stringsOnly =
-    segments !== undefined && Object.values(segments).every((v) => typeof v === 'string');
-  if (live.segments !== undefined && !stringsOnly) {
-    return '`baseline.live.segments` must be an object of strings';
-  }
   if (live.projectId !== undefined && typeof live.projectId !== 'string') {
     return '`baseline.live.projectId` must be a string';
   }
+  const path = parseSegmentsBody(live.segments, 'baseline.live.segments');
+  if (path.kind === 'err') return path.message;
+  if (path.segments !== undefined && live.projectId === undefined) {
+    return '`baseline.live.segments` is a segment path in a project: it needs `baseline.live.projectId`';
+  }
   return {
     live: {
       ...(typeof live.projectId === 'string' && { projectId: live.projectId as ProjectId }),
-      ...(segments !== undefined && { segments: segments as Record<string, string> }),
+      ...(path.segments !== undefined && { segments: path.segments }),
     },
   };
 }
@@ -49,6 +50,34 @@ function parseBaseline(raw: unknown): EvalBaseline | string {
   return { agentId: o.agentId as AgentId, version: o.version as Semver };
 }
 
+/** `{ id: version }` with non-empty strings; an error message otherwise. */
+function versionMap(raw: unknown, name: string): Readonly<Record<string, string>> | string {
+  const o = obj(raw);
+  const valid =
+    o !== undefined &&
+    Object.entries(o).every(([id, v]) => id !== '' && typeof v === 'string' && v !== '');
+  return valid
+    ? (o as Record<string, string>)
+    : `\`${name}\` must be an object of { id: version } with non-empty strings`;
+}
+
+/** `versions: { agents?, tools? }`; `undefined` when it names nothing. */
+function parseVersions(raw: unknown): FlowVersionOverrides | undefined | string {
+  const o = obj(raw);
+  if (o === undefined) return '`versions` must be an object: { agents?, tools? }';
+  const extra = Object.keys(o).filter((key) => key !== 'agents' && key !== 'tools');
+  if (extra.length > 0) return `\`versions\` takes \`agents\` and \`tools\`, not \`${extra[0]}\``;
+  const agents = o.agents === undefined ? {} : versionMap(o.agents, 'versions.agents');
+  if (typeof agents === 'string') return agents;
+  const tools = o.tools === undefined ? {} : versionMap(o.tools, 'versions.tools');
+  if (typeof tools === 'string') return tools;
+  if (Object.keys(agents).length === 0 && Object.keys(tools).length === 0) return undefined;
+  return {
+    ...(Object.keys(agents).length > 0 && { agents }),
+    ...(Object.keys(tools).length > 0 && { tools }),
+  };
+}
+
 function integerIn(raw: unknown, name: string, max: number): number | string {
   return typeof raw === 'number' && Number.isInteger(raw) && raw >= 1 && raw <= max
     ? raw
@@ -57,23 +86,40 @@ function integerIn(raw: unknown, name: string, max: number): number | string {
 
 /**
  * A comparison eval run's settings from the start body: `baseline`,
- * `reads`, `repetitions` and `k`. `undefined` when none is given (the
- * defaults apply); an error message for a bad one.
+ * `reads`, `repetitions`, `k`, `classWeights` and a flow candidate's
+ * `versions`.
+ * `undefined` when none is given (the defaults apply); an error message
+ * for a bad one.
  */
 export function parseComparison(
   b: Readonly<Record<string, unknown>>,
 ):
   | { readonly kind: 'ok'; readonly value?: EvalComparison }
   | { readonly kind: 'err'; readonly message: string } {
-  const { baseline, reads, repetitions, k } = b;
+  const { baseline, reads, repetitions, k, classWeights } = b;
+  const versions = b.versions === undefined ? undefined : parseVersions(b.versions);
+  if (typeof versions === 'string') return { kind: 'err', message: versions };
   if (
     baseline === undefined &&
     reads === undefined &&
     repetitions === undefined &&
-    k === undefined
+    k === undefined &&
+    versions === undefined &&
+    classWeights === undefined
   ) {
     return { kind: 'ok' };
   }
+  if (
+    classWeights !== undefined &&
+    classWeights !== 'as-recorded' &&
+    classWeights !== 'restricted-only'
+  ) {
+    return {
+      kind: 'err',
+      message:
+        "`classWeights` must be 'as-recorded' (every judgment at its class's weight) or 'restricted-only' (only judgments recorded under a restricted class)",
+    };
+  }
   const parsedBaseline =
     baseline === undefined ? DEFAULT_COMPARISON.baseline : parseBaseline(baseline);
   if (typeof parsedBaseline === 'string' && parsedBaseline !== 'recorded') {
@@ -96,6 +142,8 @@ export function parseComparison(
       reads: reads ?? DEFAULT_COMPARISON.reads,
       repetitions: reps,
       k: topK,
+      ...(versions !== undefined && { versions }),
+      ...(classWeights !== undefined && { classWeights }),
     },
   };
 }

package/src/routes/eval-runs.ts

@@ -17,8 +17,10 @@ import {
   type EvalRunStatus,
   type FlowRef,
 } from '../eval-run-binding.js';
+import { VERSIONS_NEED_A_FLOW } from '../judged-dispatcher.js';
 import type { AppEnv } from '../types.js';
 import { parseComparison } from './eval-comparison.js';
+import { type FlowVersionsCheck, checkFlowVersions } from './eval-versions.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
 import { formatSseFrame } from './sse.js';
@@ -47,16 +49,49 @@ export interface EvalRunsRouters {
   readonly readback: Hono<AppEnv>;
 }
 
-export function evalRunsRouters(binding: EvalRunBinding): EvalRunsRouters {
+/**
+ * `versionsCheck`: where a flow candidate's `versions` are checked
+ * against the flow version at start (without it, they're applied as
+ * given).
+ */
+export function evalRunsRouters(
+  binding: EvalRunBinding,
+  versionsCheck?: FlowVersionsCheck,
+): EvalRunsRouters {
   return {
-    start: startRouter(binding),
+    start: startRouter(binding, versionsCheck),
     readback: readbackRouter(binding),
   };
 }
 
 // ---------- POST /v1/eval-suites/:suiteId/runs ----------
 
-function startRouter(binding: EvalRunBinding): Hono<AppEnv> {
+/** The `validation-failed` error for a flow candidate's `versions` that don't fit the flow; `undefined` when they do. */
+async function versionsRefusal(
+  check: FlowVersionsCheck | undefined,
+  tenantId: TenantId,
+  start: ParsedStartBody,
+) {
+  const versions = start.comparison?.versions;
+  const flowRef = start.flowRef;
+  if (check === undefined || versions === undefined || flowRef?.version === undefined) {
+    return undefined;
+  }
+  const issues = await checkFlowVersions(
+    check,
+    tenantId,
+    { flowId: flowRef.flowId as unknown as string, version: flowRef.version },
+    versions,
+  );
+  if (issues.length === 0) return undefined;
+  return {
+    code: 'validation-failed' as const,
+    message: `The versions don't fit flow ${flowRef.flowId as unknown as string} ${flowRef.version} (${issues.length} issue${issues.length === 1 ? '' : 's'})`,
+    issues: issues as unknown as Record<string, unknown>[],
+  };
+}
+
+function startRouter(binding: EvalRunBinding, versionsCheck?: FlowVersionsCheck): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
   r.post('/:suiteId/runs', async (c) => {
@@ -84,6 +119,11 @@ function startRouter(binding: EvalRunBinding): Hono<AppEnv> {
       c.status(statusFor(parsed.error.code) as never);
       return c.json(toWireError(parsed.error, requestId));
     }
+    const refusal = await versionsRefusal(versionsCheck, tenantId, parsed.value);
+    if (refusal !== undefined) {
+      c.status(statusFor(refusal.code) as never);
+      return c.json(toWireError(refusal, requestId));
+    }
 
     const outcome = await binding.start({
       tenantId,
@@ -627,6 +667,9 @@ function parseStartBody(
   if (comparison.kind === 'err') {
     return { kind: 'err', error: { code: 'bad-input', message: comparison.message } };
   }
+  if (comparison.value?.versions !== undefined && agentRef !== undefined) {
+    return { kind: 'err', error: { code: 'bad-input', message: VERSIONS_NEED_A_FLOW } };
+  }
 
   return {
     kind: 'ok',