@kindgi/api 0.1.3 → 0.1.4-rc.0

package/src/cost-binding.ts

@@ -44,7 +44,10 @@ export interface CostBinding {
    * Multi-dimensional aggregate rollup. `groupBy` may combine any
    * subset of `COST_GROUP_DIMENSIONS`; the binding returns one group per
    * distinct key tuple within the required `from`..`to` window, with its
-   * cost and token sums.
+   * cost and token sums. With `limit`, a binding may return only the
+   * `limit` most expensive groups (`totalUsd` descending, ties by key)
+   * and the count before the cap in `totalGroups`; one that returns
+   * every group is capped by the route.
    */
   aggregate(input: CostAggregateInput): Promise<CostAggregateResult>;
 }
@@ -195,8 +198,20 @@ export interface CostAggregateInput {
    * shape uniformity.
    */
   readonly inherit?: boolean;
+  /**
+   * The most groups the caller wants (`?limit=`, 1..`COST_AGGREGATE_MAX_LIMIT`,
+   * default `COST_AGGREGATE_DEFAULT_LIMIT`): the most expensive ones. A
+   * binding may cap in its query; the window's totals stay over every
+   * record either way.
+   */
+  readonly limit?: number;
 }
 
+/** `GET /v1/cost/aggregate`'s `?limit=` when absent. */
+export const COST_AGGREGATE_DEFAULT_LIMIT = 1000;
+/** The largest `?limit=` the aggregate takes. */
+export const COST_AGGREGATE_MAX_LIMIT = 10_000;
+
 /**
  * One row of the aggregate result. `key` maps every requested `groupBy`
  * dimension to its value for this group — `null` when the underlying
@@ -226,6 +241,11 @@ export interface CostTokenTotals {
 
 export interface CostAggregateResult {
   readonly groups: readonly CostAggregateGroup[];
+  /**
+   * How many groups there were before a cap: set by a binding that caps
+   * (`CostAggregateInput.limit`). Absent: `groups` is every group.
+   */
+  readonly totalGroups?: number;
   readonly totalUsd: number;
   readonly totalRecords: number;
   readonly tokens: CostTokenTotals;

package/src/deploy-versions.ts

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type PinChange, type PinSet, pinChanges } from '@kindgi/agents';
+import { canonicalize } from '@kindgi/schema';
+import { nextVersion } from '@kindgi/tools';
+import type { VersionDerivation, VersionDerivationReason } from '@kindgi/types';
+
+/** A version a deploy registers with pins: an agent's or a flow's. */
+export interface PinnedDefinition {
+  readonly version: string;
+  readonly pins?: PinSet;
+  readonly pinsDigest?: string;
+  readonly derivedFrom?: VersionDerivation;
+}
+
+/**
+ * How a deploy registered one of its agents or flows, given its pins.
+ * A deploy never keeps a version's old pins and never refuses a
+ * routine deploy:
+ *
+ * - `registered`: the definition's version was free, and is now
+ *   registered with these pins;
+ * - `unchanged`: it's registered with the same definition and pins (or
+ *   its project is gone, which a deploy has always left as it is);
+ * - `reused`: an earlier deploy already registered this definition and
+ *   these pins under another number (`version`), so a redeploy changes
+ *   nothing;
+ * - `renumbered`: the definition's version is registered with other
+ *   pins or other content, and versions never change, so this deploy
+ *   registered the next free version in its line (`nextVersion`).
+ */
+export type DeployedVersionOutcome =
+  | { readonly kind: 'registered' | 'unchanged'; readonly version: string }
+  | {
+      readonly kind: 'reused' | 'renumbered';
+      readonly version: string;
+      readonly reason: VersionDerivationReason;
+      readonly pinChanges?: readonly PinChange[];
+    };
+
+/** What registering one version did: stored it, found the number taken, or left it (no project). */
+export type PublishOutcome = 'ok' | 'taken' | 'skipped';
+
+export interface DeployVersionInput<T extends PinnedDefinition> {
+  /** Names the definition in an error, e.g. `agent "acme.matcher"`. */
+  readonly label: string;
+  /** The definition as the pack has it, with no pins. */
+  readonly definition: T;
+  readonly pins: PinSet;
+  readonly pinsDigest: string;
+  /** Every active version registered under the definition's id. */
+  readonly existing: readonly T[];
+  /** Register one version. */
+  readonly publish: (version: T) => Promise<PublishOutcome>;
+}
+
+/** How many versions after the definition's a deploy tries before it gives up. */
+const MAX_RENUMBER = 100;
+
+/**
+ * Register a deployed agent or flow with its pins (see
+ * `DeployedVersionOutcome`): one rule for both, so they can't drift
+ * apart. Each definition is registered at most once per deploy, and a
+ * new version derives from the definition's version only, never from a
+ * version the same deploy created, so a change cascading from a tool
+ * through an agent into a flow ends within the one deploy.
+ */
+export async function deployVersion<T extends PinnedDefinition>(
+  input: DeployVersionInput<T>,
+): Promise<DeployedVersionOutcome> {
+  const { definition, pins, pinsDigest, existing } = input;
+  const authored = definition.version;
+  const key = definitionKey(definition);
+  const same = (v: T) => definitionKey(v) === key && v.pinsDigest === pinsDigest;
+
+  const atAuthored = existing.find((v) => v.version === authored);
+  if (atAuthored !== undefined && same(atAuthored)) return { kind: 'unchanged', version: authored };
+  if (atAuthored === undefined) {
+    const outcome = await input.publish({ ...definition, pins, pinsDigest });
+    if (outcome !== 'taken') {
+      return { kind: outcome === 'ok' ? 'registered' : 'unchanged', version: authored };
+    }
+    // Taken with no active version: an unregistered version holds the
+    // number. Register the next one.
+  }
+
+  const reason = derivationReason(atAuthored, key);
+  const changes =
+    reason === 'pins-changed' ? { pinChanges: pinChanges(atAuthored?.pins, pins) } : {};
+  const earlier = existing.find(same);
+  if (earlier !== undefined) {
+    return {
+      kind: 'reused',
+      version: earlier.version,
+      // An expert's edit reused by a deploy reports the deploy's own reason.
+      reason:
+        earlier.derivedFrom !== undefined && earlier.derivedFrom.reason !== 'edited'
+          ? earlier.derivedFrom.reason
+          : reason,
+      ...changes,
+    };
+  }
+  const taken = new Set(existing.map((v) => v.version));
+  const version = await registerNextFree(input, reason, taken);
+  return version === undefined
+    ? { kind: 'unchanged', version: authored }
+    : { kind: 'renumbered', version, reason, ...changes };
+}
+
+/** Why the definition's version can't be registered as it is. */
+function derivationReason(
+  atAuthored: PinnedDefinition | undefined,
+  key: string,
+): VersionDerivationReason {
+  if (atAuthored === undefined || definitionKey(atAuthored) !== key) return 'version-taken';
+  return atAuthored.pins === undefined ? 'unpinned' : 'pins-changed';
+}
+
+/**
+ * Register the definition with its pins under the first free version
+ * after its own (`nextVersion`), recording where it came from.
+ * `undefined` when it was left as it is (its project is gone).
+ */
+async function registerNextFree<T extends PinnedDefinition>(
+  input: DeployVersionInput<T>,
+  reason: VersionDerivationReason,
+  taken: ReadonlySet<string>,
+): Promise<string | undefined> {
+  const { definition, pins, pinsDigest } = input;
+  const authored = definition.version;
+  let candidate = nextVersion(authored);
+  for (let tries = 0; candidate !== undefined && tries < MAX_RENUMBER; tries++) {
+    if (!taken.has(candidate)) {
+      const outcome = await input.publish({
+        ...definition,
+        version: candidate,
+        pins,
+        pinsDigest,
+        derivedFrom: { version: authored, reason },
+      });
+      if (outcome === 'ok') return candidate;
+      if (outcome === 'skipped') return undefined;
+      // Taken: an unregistered version holds this one too.
+    }
+    candidate = nextVersion(candidate);
+  }
+  throw new Error(
+    `${input.label}: no free version after ${authored} to register its new pins under`,
+  );
+}
+
+/** A definition: everything but its version and what the runtime sets. */
+function definitionKey(definition: PinnedDefinition): string {
+  const { version: _v, pins: _p, pinsDigest: _d, derivedFrom: _f, ...rest } = definition;
+  return canonicalize(rest);
+}

package/src/deployment-binding.ts

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { Cursor, SigningKeyId, TenantId } from '@kindgi/types';
+import type { PinChange } from '@kindgi/agents';
+import type { Cursor, SigningKeyId, TenantId, VersionDerivationReason } from '@kindgi/types';
 
 /**
  * Caller-plugged surface for the deployment ledger — the audit anchor
@@ -127,11 +128,34 @@ export interface DeployedPrimitive {
   readonly version?: string;
 }
 
+/**
+ * An agent or flow a deployment shipped, under the version it's
+ * registered as. A deploy registers one under another version than its
+ * definition's when that version is registered already with other pins
+ * or content (versions never change); then `authoredVersion` is the
+ * definition's and `reason` says why.
+ */
+export interface DeployedVersion extends DeployedPrimitive {
+  /** The version the agent's definition names, when it differs from `version`. */
+  readonly authoredVersion?: string;
+  readonly reason?: VersionDerivationReason;
+  /** `true`: this deploy registered `version`; `false`: an earlier deploy did. */
+  readonly newVersion?: boolean;
+  /** For `pins-changed`: the pins that differ from `authoredVersion`'s. */
+  readonly pinChanges?: readonly PinChange[];
+}
+
+/** An agent a deployment shipped (`DeployedVersion`). */
+export type DeployedAgent = DeployedVersion;
+
+/** A flow a deployment shipped (`DeployedVersion`). */
+export type DeployedFlow = DeployedVersion;
+
 export interface DeploymentContents {
   readonly tools: readonly DeployedPrimitive[];
   readonly guardrails: readonly DeployedPrimitive[];
-  readonly agents: readonly DeployedPrimitive[];
-  readonly flows: readonly DeployedPrimitive[];
+  readonly agents: readonly DeployedAgent[];
+  readonly flows: readonly DeployedFlow[];
 }
 
 export interface DeploymentPrimitiveCounts {

package/src/derive-agent-version.ts

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import {
+  type Agent,
+  type AgentId,
+  type AgentPins,
+  MODEL_SETTINGS_SCHEMA,
+  pinsDigest,
+  settingsSchemaIssues,
+} from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import { latestVersion, nextVersion } from '@kindgi/tools';
+import type { ProjectId, Semver, TenantId } from '@kindgi/types';
+
+import type { AgentRegistryBinding, AgentVersionRecord } from './agent-binding.js';
+import { activeAgentVersions } from './agent-pins.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+
+/** Which data-block pins to swap, by kind then block id → exact version. */
+export interface PinSwaps {
+  readonly prompts?: Readonly<Record<string, string>>;
+  readonly settings?: Readonly<Record<string, string>>;
+}
+
+export interface DeriveAgentVersionInput {
+  readonly agents: AgentRegistryBinding;
+  readonly blocks: BlockRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  /** The version to derive from: it must be pinned. */
+  readonly from: string;
+  readonly swaps: PinSwaps;
+  /** A short label for the new version. */
+  readonly label?: string;
+  /** Who derived it (`user:<id>`). */
+  readonly by?: string;
+  /** The project, when the store doesn't record one on the version. */
+  readonly projectId?: ProjectId;
+  /** The authorization tuples for the new version, in the project it lands in. */
+  readonly tuplesFor: (projectId: ProjectId) => TupleEnqueueHook;
+}
+
+export interface SwapIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+export type DeriveAgentVersionOutcome =
+  | { readonly kind: 'ok'; readonly agent: Agent }
+  | { readonly kind: 'not-found' }
+  | { readonly kind: 'unpinned' }
+  | { readonly kind: 'invalid'; readonly issues: readonly SwapIssue[] }
+  | { readonly kind: 'no-project' }
+  | { readonly kind: 'project-not-found'; readonly projectId: ProjectId };
+
+/** How many numbers after the highest a derive tries before it gives up. */
+const MAX_TRIES = 100;
+
+/**
+ * Derive a new agent version from a pinned one with some data-block
+ * pins swapped: an expert's edit (a new prompt or settings version)
+ * reaching an agent without a code change. The new version is the old
+ * one's bag with those pins swapped (`derivedFrom: { version, reason:
+ * 'edited', label, by }`), numbered the next free patch after the
+ * agent's highest version (versions never change).
+ *
+ * Only data-block pins swap: a swap must name a block the version
+ * already references (adding one is a code change), at a published,
+ * active version of the right kind (and, for the model-settings block,
+ * model settings). Tool pins come from code.
+ */
+export async function deriveAgentVersion(
+  input: DeriveAgentVersionInput,
+): Promise<DeriveAgentVersionOutcome> {
+  const { agents, tenantId, agentId } = input;
+  const from = await agents.getVersion({ tenantId, agentId, version: input.from as Semver });
+  if (from === null) return { kind: 'not-found' };
+  if (from.pins === undefined) return { kind: 'unpinned' };
+
+  const issues = await swapIssues(input, from, from.pins);
+  if (issues.length > 0) return { kind: 'invalid', issues };
+  const pins: AgentPins = {
+    tools: from.pins.tools,
+    prompts: { ...from.pins.prompts, ...(input.swaps.prompts ?? {}) },
+    settings: { ...from.pins.settings, ...(input.swaps.settings ?? {}) },
+  };
+  const digest = pinsDigest(pins);
+  if (digest === from.pinsDigest) {
+    return { kind: 'invalid', issues: [{ path: '/pins', message: 'no pin changes' }] };
+  }
+
+  const projectId = from.projectId ?? input.projectId;
+  if (projectId === undefined) return { kind: 'no-project' };
+  const { unregisteredAt: _u, projectId: _p, derivedFrom: _d, ...definition } = from;
+  return publishNextFree(input, projectId, {
+    ...definition,
+    pins,
+    pinsDigest: digest,
+    derivedFrom: {
+      version: from.version,
+      reason: 'edited',
+      ...(input.label !== undefined && { label: input.label }),
+      ...(input.by !== undefined && { by: input.by }),
+    },
+  });
+}
+
+/** Publish the derived version under the first free patch after the agent's highest. */
+async function publishNextFree(
+  input: DeriveAgentVersionInput,
+  projectId: ProjectId,
+  derived: Agent,
+): Promise<DeriveAgentVersionOutcome> {
+  const { agents, tenantId, agentId } = input;
+  const active = await activeAgentVersions(agents, tenantId, agentId);
+  const highest =
+    latestVersion(active.map((a) => a.version as unknown as string)) ??
+    (derived.version as unknown as string);
+  let candidate = nextVersion(highest);
+  for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+    const agent: Agent = { ...derived, version: candidate as Semver };
+    const outcome = await agents.publish({
+      tenantId,
+      projectId,
+      agent,
+      enqueueTuples: input.tuplesFor(projectId),
+    });
+    if (outcome.kind === 'ok') return { kind: 'ok', agent };
+    if (outcome.kind === 'project-not-found') return { kind: 'project-not-found', projectId };
+    candidate = nextVersion(candidate);
+  }
+  throw new Error(`agent "${agentId as unknown as string}": no free version after ${highest}`);
+}
+
+/** What's wrong with the swaps, against the version's references and the block store. */
+async function swapIssues(
+  input: DeriveAgentVersionInput,
+  from: AgentVersionRecord,
+  pins: AgentPins,
+): Promise<SwapIssue[]> {
+  const issues: SwapIssue[] = [];
+  const swaps = [
+    ...Object.entries(input.swaps.prompts ?? {}).map(([id, v]) => ['prompts', id, v] as const),
+    ...Object.entries(input.swaps.settings ?? {}).map(([id, v]) => ['settings', id, v] as const),
+  ];
+  if (swaps.length === 0)
+    return [{ path: '/pins', message: 'name at least one prompt or settings pin to swap' }];
+  for (const [kind, id, version] of swaps) {
+    const path = `/pins/${kind}/${id}`;
+    if (pins[kind][id] === undefined) {
+      issues.push({
+        path,
+        message: `agent version ${from.version} doesn't reference ${kind === 'prompts' ? 'prompt' : 'settings'} block "${id}"; adding a block is a code change`,
+      });
+      continue;
+    }
+    const problem = await blockProblem(input, from, kind, id, version);
+    if (problem !== undefined) issues.push({ path, message: problem });
+  }
+  return issues;
+}
+
+async function blockProblem(
+  input: DeriveAgentVersionInput,
+  from: AgentVersionRecord,
+  kind: 'prompts' | 'settings',
+  id: string,
+  version: string,
+): Promise<string | undefined> {
+  if (input.blocks === undefined) return 'this runtime serves no data blocks';
+  const block = await input.blocks.getVersion({ tenantId: input.tenantId, blockId: id, version });
+  const what = `block "${id}" version ${version}`;
+  if (block === null) return `${what} isn't published`;
+  if (block.unregisteredAt !== undefined) return `${what} is unregistered`;
+  const wanted = kind === 'prompts' ? 'prompt' : 'settings';
+  if (block.kind !== wanted) return `${what} is a ${block.kind} block, not ${wanted}`;
+  if (block.kind === 'settings' && from.modelSettings?.id === id) {
+    const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+    if (issues.length > 0) {
+      return `${what} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The first version after `after` that no version of the agent holds,
+ * active or unregistered (versions never change): what a refused
+ * publish of a taken number suggests, by the deploy rule's numbering.
+ * `undefined` when none is free within the tries.
+ */
+export async function nextFreeAgentVersion(
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  agentId: AgentId,
+  after: string,
+): Promise<string | undefined> {
+  let candidate = nextVersion(after);
+  for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+    const held = await agents.getVersion({ tenantId, agentId, version: candidate as Semver });
+    if (held === null) return candidate;
+    candidate = nextVersion(candidate);
+  }
+  return undefined;
+}

package/src/errors.ts

@@ -31,6 +31,7 @@ export interface WireError {
 export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   // 400 — bad request
   'validation-failed': 400,
+  'kind-not-applied': 400,
   'unknown-field': 400,
   'bad-input': 400,
   'unresolved-tool': 400,
@@ -160,10 +161,22 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'policy-not-found': 404,
   'policy-already-registered': 409,
   // Admin plane — eval suites.
+  'block-not-found': 404,
+  'block-already-registered': 409,
+  'block-project-mismatch': 409,
   'eval-suite-not-found': 404,
   'eval-suite-already-registered': 409,
   // Admin plane — eval-run dispatch.
   'eval-run-not-found': 404,
+  // Judgments (yes/no on a run's output items) and judge classes.
+  'judgment-not-found': 404,
+  'judge-class-not-found': 404,
+  'judge-class-name-taken': 409,
+  'judge-class-not-applicable': 400,
+  'run-not-finished': 409,
+  'item-not-found': 400,
+  // The judgment binding can't list judged runs, so no test sets from judgments.
+  'test-sets-not-supported': 501,
   'eval-run-already-terminal': 409,
   'dispatcher-not-registered': 422,
   'dispatcher-input-invalid': 400,
@@ -215,6 +228,10 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'project-not-found': 404,
   'team-membership-not-found': 404,
   'project-membership-not-found': 404,
+  // A slug another org, team or project in the tenant already has; a
+  // second Default project.
+  'slug-conflict': 409,
+  'project-default-already-exists': 409,
   'tenant-not-found': 404,
   'tenant-config-not-found': 404,
   'tenant-config-revision-conflict': 409,

package/src/eval-case-binding.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import type { JudgedItem, JudgedRunContext, JudgedSubject } from './judgment-binding.js';
+
+/**
+ * Caller-plugged storage for the cases of an eval-suite version, kept
+ * apart from the version's `spec` because a set can hold hundreds of
+ * cases. A `judged` suite version's cases are built from judgments: each
+ * is a copy of one judged run (its input, what it read, the output that
+ * was judged) with the judgments of its items summed up. Copies, so a
+ * test set stays the same when judgments are removed or runs purged.
+ *
+ * Cases are written once, when the version is published, and removed
+ * with it.
+ */
+export interface EvalCaseStoreBinding {
+  /** Store a version's cases. Called once, right after the version is published. */
+  putCases(input: EvalCasePutInput): Promise<void>;
+  /** A version's cases, in the order they were stored, cursor-paginated. */
+  listCases(input: EvalCaseListInput): Promise<EvalCasePage>;
+}
+
+/** The judgments of one item of a case's output, summed up. */
+export interface JudgedItemSummary extends JudgedItem {
+  readonly yes: number;
+  readonly no: number;
+  /** The weight behind "yes" (an unclassified judgment counts 1). */
+  readonly yesWeight: number;
+  /** The weight behind all judgments of the item. */
+  readonly totalWeight: number;
+  /** The reasons given, newest first. */
+  readonly reasons: readonly { readonly verdict: 'yes' | 'no'; readonly reason: string }[];
+}
+
+/** One case of a `judged` suite: a copy of a judged run and what people said about it. */
+export interface JudgedEvalCase {
+  /** The judged run's id. */
+  readonly caseId: string;
+  /** What ran: the agent or flow at a version (the baseline when comparing to the recording). */
+  readonly subject: JudgedSubject;
+  readonly input: unknown;
+  /** What the turn read besides its input; absent when it wasn't captured. */
+  readonly context?: JudgedRunContext;
+  /** The output that was judged. */
+  readonly output: unknown;
+  readonly items: readonly JudgedItemSummary[];
+}
+
+export interface EvalCasePutInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+  readonly cases: readonly JudgedEvalCase[];
+}
+
+export interface EvalCaseListInput {
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly version: string;
+  readonly cursor?: Cursor;
+  readonly limit: number;
+}
+
+export interface EvalCasePage {
+  readonly data: readonly JudgedEvalCase[];
+  readonly hasMore: boolean;
+  readonly nextCursor?: Cursor;
+}

package/src/eval-run-binding.ts

@@ -105,6 +105,8 @@ export interface EvalRun {
   readonly result?: Readonly<Record<string, unknown>>;
   readonly error?: string;
   readonly correlationId?: string;
+  /** A comparison eval run's baseline, reads and repetitions. */
+  readonly comparison?: EvalComparison;
 }
 
 export interface EvalRunFilter {
@@ -116,6 +118,35 @@ export interface EvalRunFilter {
   readonly to?: Timestamp;
 }
 
+/**
+ * What a comparison eval run compares the candidate against:
+ *   - `'recorded'`: the output each case recorded (what was judged);
+ *   - `{ agentId, version }`: that version, replayed under the same rules;
+ *   - `{ live }`: the version live in a scope (a project, segments).
+ */
+export type EvalBaseline =
+  | 'recorded'
+  | { readonly agentId: AgentId; readonly version: Semver }
+  | {
+      readonly live: {
+        readonly projectId?: ProjectId;
+        readonly segments?: Readonly<Record<string, string>>;
+      };
+    };
+
+/** Whether replayed reads use the past run's results when it has them, or run live. */
+export type EvalReads = 'recorded' | 'live';
+
+/** How a comparison eval run runs its cases (absent: the run isn't a comparison). */
+export interface EvalComparison {
+  readonly baseline: EvalBaseline;
+  readonly reads: EvalReads;
+  /** How many times each case runs (1–10); with more than 1, the summary shows the spread. */
+  readonly repetitions: number;
+  /** How many ranked items `weightedPrecisionAtK` looks at (1–100). */
+  readonly k: number;
+}
+
 export interface EvalRunStartInput {
   readonly tenantId: TenantId;
   /**
@@ -130,6 +161,8 @@ export interface EvalRunStartInput {
   readonly flowRef?: FlowRef;
   readonly dryRun?: boolean;
   readonly correlationId?: string;
+  /** Set for a comparison eval run (a `judged` suite): its baseline, reads and repetitions. */
+  readonly comparison?: EvalComparison;
 }
 
 /**