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

package/src/openapi/schemas.ts

@@ -64,7 +64,14 @@
  */
 
 import { EVIDENCE_KINDS } from '@kindgi/compliance';
-import { MAX_TOOL_ERROR_RETRIES, POLICY_KINDS, TOOL_ERROR_KINDS } from '@kindgi/policy-contract';
+import {
+  MAX_TOOL_ERROR_RETRIES,
+  POLICY_KINDS,
+  RETENTION_DOMAINS,
+  TOOL_ERROR_KINDS,
+} from '@kindgi/policy-contract';
+
+import { ERROR_CODE_TO_STATUS } from '../errors.js';
 
 export type JsonSchema = Record<string, unknown>;
 
@@ -74,6 +81,11 @@ export const WireErrorSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
   required: ['error'],
+  // Every code the API answers with, and its HTTP status. Not a closed
+  // list for clients (a newer server may add codes); the clients' tests
+  // read it to check that each 4xx code maps to a typed error, not to a
+  // server error. Generators and validators ignore `x-` keys.
+  'x-error-codes': ERROR_CODE_TO_STATUS,
   properties: {
     error: {
       type: 'object',
@@ -142,6 +154,430 @@ export const RunAgentSchema: JsonSchema = {
     id: { type: 'string', description: 'The agent id.' },
     version: { type: 'string', description: 'The agent version that ran (semver).' },
     conversationId: { type: 'string', format: 'uuid' },
+    via: {
+      type: 'string',
+      enum: ['explicit', 'flow-pin', 'conversation', 'live', 'latest'],
+      description:
+        "Why this version ran: named by the caller (`explicit`); held by the flow version a flow's agent step runs in (`flow-pin`: the node's `config.version`, else the version the flow version pinned when it was published); the conversation's own (`conversation`); the version live for the run's scope (`live`); or the latest, nothing being live (`latest`). Absent on runs from before Kindgi 0.1.4.",
+    },
+    liveScope: {
+      $ref: '#/components/schemas/LiveScope',
+      description: 'The pin that chose the version, when `via` is `live`.',
+    },
+  },
+};
+
+export const ScopeSegmentSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['key', 'value'],
+  properties: {
+    key: {
+      type: 'string',
+      pattern: '^[a-z][a-z0-9_-]{0,63}$',
+      description: 'Lowercase, like an identifier: `company`, `contact-role`.',
+    },
+    value: { type: 'string', minLength: 1, maxLength: 256 },
+  },
+};
+
+const liveScopeVariant = (
+  kind: string,
+  description: string,
+  properties: Record<string, JsonSchema>,
+): JsonSchema => ({
+  type: 'object',
+  additionalProperties: false,
+  required: ['kind', ...Object.keys(properties)],
+  description,
+  properties: { kind: { type: 'string', enum: [kind] }, ...properties },
+});
+
+export const LiveScopeTenantSchema = liveScopeVariant(
+  'tenant',
+  "The agent's default for the whole tenant.",
+  {},
+);
+export const LiveScopeOrgSchema = liveScopeVariant('org', "An org's projects.", {
+  orgId: { type: 'string', format: 'uuid' },
+});
+export const LiveScopeProjectSchema = liveScopeVariant('project', 'One project.', {
+  projectId: { type: 'string', format: 'uuid' },
+});
+export const LiveScopeSegmentSchema = liveScopeVariant(
+  'segment',
+  'A segment path within a project: it covers every run whose path starts with it.',
+  {
+    projectId: { type: 'string', format: 'uuid' },
+    path: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 8,
+      items: { $ref: '#/components/schemas/ScopeSegment' },
+    },
+  },
+);
+
+export const LiveScopeSchema: JsonSchema = {
+  description:
+    'Where a live version is pinned, from least to most specific: tenant, org, project, segment path. A run takes the most specific pin that covers it.',
+  oneOf: [
+    { $ref: '#/components/schemas/LiveScopeTenant' },
+    { $ref: '#/components/schemas/LiveScopeOrg' },
+    { $ref: '#/components/schemas/LiveScopeProject' },
+    { $ref: '#/components/schemas/LiveScopeSegment' },
+  ],
+  discriminator: { propertyName: 'kind' },
+};
+
+export const LiveVersionResolutionSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['agentId', 'version', 'via'],
+  properties: {
+    agentId: { type: 'string' },
+    version: { type: 'string', description: 'The version a run would use (semver).' },
+    via: {
+      type: 'string',
+      enum: ['live', 'latest'],
+      description: 'A live pin chose it, or nothing is live on the way up and it is the latest.',
+    },
+    liveScope: { $ref: '#/components/schemas/LiveScope' },
+  },
+};
+
+export const LivePinSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['agentId', 'scope', 'version', 'promotionId', 'setAt'],
+  properties: {
+    agentId: { type: 'string' },
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    version: { type: 'string' },
+    promotionId: { type: 'string', format: 'uuid', description: 'The promotion that set it.' },
+    setAt: { type: 'string', format: 'date-time' },
+  },
+};
+
+export const LivePinListSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data'],
+  properties: { data: { type: 'array', items: { $ref: '#/components/schemas/LivePin' } } },
+};
+
+export const PromotionSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'id',
+    'agentId',
+    'scope',
+    'action',
+    'fromVersion',
+    'toVersion',
+    'requestedBy',
+    'createdAt',
+  ],
+  description:
+    "One change of a scope's live version, kept for good: what was live before, what is after, who asked and why.",
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    agentId: { type: 'string' },
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    action: { type: 'string', enum: ['promote', 'rollback', 'unpin'] },
+    fromVersion: {
+      type: ['string', 'null'],
+      description: "The scope's own pin before; null when it had none.",
+    },
+    toVersion: {
+      type: ['string', 'null'],
+      description: "The scope's own pin after; null after an unpin.",
+    },
+    requestedBy: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'id'],
+      properties: {
+        kind: { type: 'string', enum: ['user', 'service'] },
+        id: { type: 'string' },
+      },
+    },
+    reason: { type: 'string' },
+    evalRunId: { type: 'string', description: 'The comparison the change was judged on.' },
+    createdAt: { type: 'string', format: 'date-time' },
+    status: {
+      type: 'string',
+      enum: ['promoted', 'pending-approval', 'refused', 'superseded', 'rejected', 'expired'],
+      description:
+        "A `promote` row's state: it changes once, from `pending-approval` to its final state. Absent on rollback and unpin rows, and on promotions made before gates (`promoted`).",
+    },
+    policy: {
+      oneOf: [{ $ref: '#/components/schemas/GatePolicyRef' }, { type: 'null' }],
+      description: 'The gate policy that applied; null when none did. Absent before gates.',
+    },
+    checks: { type: 'array', items: { $ref: '#/components/schemas/GateCheck' } },
+    approvalId: {
+      type: 'string',
+      description: 'The approval a `pending-approval` promotion waits on (kept once decided).',
+    },
+    resolvedAt: {
+      type: 'string',
+      format: 'date-time',
+      description: 'When a `pending-approval` promotion reached its final state.',
+    },
+  },
+};
+
+export const PromotionPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/Promotion' } },
+    hasMore: { type: 'boolean' },
+    nextCursor: { type: 'string' },
+  },
+};
+
+// ---------------- the promotion gate (evals step 4b) ----------------
+
+export const GateCheckSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['name', 'passed', 'message'],
+  description: "One of a gate's checks, as the promotion records it.",
+  properties: {
+    name: {
+      type: 'string',
+      description:
+        'Stable: `comparison.required`, `comparison.status`, `comparison.freshness`, `comparison.suite`, `sameContents`, `baselineIsLive`, `scopeCovered`, `evidence.<metric>.minCases|minWeight|baselineMinCases|baselineMinWeight`, `metric.<metric>.k|minCandidate|maxDrop`, `replay.maxDiverged|maxErrors|maxRefusedWrites|maxStopped`, `classWeights.restrictedOnly`.',
+    },
+    passed: { type: 'boolean' },
+    message: {
+      type: 'string',
+      description: 'A plain sentence: what was found against what the policy asks.',
+    },
+    value: { type: ['number', 'string'] },
+    threshold: { type: ['number', 'string'] },
+  },
+};
+
+export const GatePolicyRefSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version'],
+  properties: { id: { type: 'string' }, version: { type: 'string' } },
+};
+
+export const GateApprovalSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['role', 'count', 'separateApprover'],
+  description: 'The approval a passing promotion waits for.',
+  properties: {
+    role: { type: 'string', enum: ['standard', 'senior', 'admin'] },
+    count: { type: 'integer', minimum: 1 },
+    separateApprover: {
+      type: 'boolean',
+      description: 'Whoever asked for the promotion may not approve it.',
+    },
+  },
+};
+
+const GateMetricSpecSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['name'],
+  properties: {
+    name: { type: 'string', enum: ['weightedYesShare', 'judgedCoverage', 'weightedPrecisionAtK'] },
+    k: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 100,
+      description: "`weightedPrecisionAtK` only: the summary's `k` must be this.",
+    },
+    minCandidate: { type: 'number', minimum: 0, maximum: 1 },
+    maxDrop: {
+      type: 'number',
+      minimum: 0,
+      maximum: 1,
+      description: 'How far the candidate may fall below the baseline (the live version).',
+    },
+  },
+};
+
+export const GatePolicySpecSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  description:
+    'What a promotion must show. Every part is optional; an empty spec checks nothing. A promotion must name a comparison (`evalRunId`) exactly when the spec has `comparison`, `evidence`, `metrics`, `replay` or `onlyRestrictedClasses`. Unknown keys are refused.',
+  properties: {
+    comparison: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        maxAgeHours: { type: 'number', exclusiveMinimum: 0 },
+        suite: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['id'],
+          properties: { id: { type: 'string' }, version: { type: 'string' } },
+        },
+      },
+    },
+    evidence: {
+      type: 'object',
+      additionalProperties: false,
+      description:
+        "The judged evidence behind each gated metric; for a metric with `maxDrop`, the baseline's too.",
+      properties: {
+        minCases: { type: 'integer', minimum: 0 },
+        minWeight: { type: 'number', minimum: 0 },
+      },
+    },
+    metrics: { type: 'array', items: GateMetricSpecSchema },
+    replay: {
+      type: 'object',
+      additionalProperties: false,
+      description: 'Each knob left out of the block is 0. No block: no replay checks.',
+      properties: {
+        maxDiverged: { type: 'integer', minimum: 0 },
+        maxErrors: { type: 'integer', minimum: 0 },
+        maxRefusedWrites: { type: 'integer', minimum: 0 },
+        maxStopped: { type: 'integer', minimum: 0 },
+      },
+    },
+    approvals: {
+      type: 'object',
+      additionalProperties: false,
+      description: 'A passing promotion waits for a reviewer.',
+      properties: {
+        role: {
+          type: 'string',
+          enum: ['standard', 'senior', 'admin'],
+          description: 'Default `senior`.',
+        },
+        separateApprover: { type: 'boolean', description: 'Default `true`.' },
+      },
+    },
+    onlyRestrictedClasses: {
+      type: 'boolean',
+      description:
+        "Only restricted judge classes count: the comparison must be weighted `restricted-only`, so a class anyone may assert can't move the gate.",
+    },
+  },
+};
+
+export const GatePolicySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version', 'agentId', 'scope', 'spec', 'createdAt'],
+  properties: {
+    id: { type: 'string' },
+    version: { type: 'string' },
+    agentId: { type: 'string' },
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    spec: { $ref: '#/components/schemas/GatePolicySpec' },
+    description: { type: 'string' },
+    createdAt: { type: 'string', format: 'date-time' },
+    unregisteredAt: { type: 'string', format: 'date-time' },
+  },
+};
+
+export const GatePolicyPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/GatePolicy' } },
+    hasMore: { type: 'boolean' },
+    nextCursor: { type: 'string' },
+  },
+};
+
+export const PublishGatePolicyBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version', 'agentId', 'scope', 'spec'],
+  properties: {
+    id: {
+      type: 'string',
+      pattern: '^[a-z0-9][a-z0-9._-]{0,127}$',
+      description: 'Yours to choose, e.g. `acme.drafting-prod`.',
+    },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    agentId: { type: 'string' },
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    spec: { $ref: '#/components/schemas/GatePolicySpec' },
+    description: { type: 'string' },
+  },
+};
+
+export const GatePolicyResolutionSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['policy'],
+  properties: {
+    policy: {
+      oneOf: [{ $ref: '#/components/schemas/GatePolicy' }, { type: 'null' }],
+      description: 'The policy that gates a promotion for the scope; null when none does.',
+    },
+  },
+};
+
+export const PromotionCheckSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['outcome', 'policy', 'checks'],
+  description: 'What the gate would say about a promotion. Nothing is recorded.',
+  properties: {
+    outcome: { type: 'string', enum: ['would-promote', 'needs-approval', 'gate-failed'] },
+    policy: {
+      oneOf: [{ $ref: '#/components/schemas/GatePolicyRef' }, { type: 'null' }],
+      description: 'The policy that applies; null when none does.',
+    },
+    checks: { type: 'array', items: { $ref: '#/components/schemas/GateCheck' } },
+    approval: { $ref: '#/components/schemas/GateApproval' },
+  },
+};
+
+export const PromoteBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['version', 'scope'],
+  properties: {
+    version: {
+      type: 'string',
+      description: 'The agent version to make live (registered, active).',
+    },
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    reason: { type: 'string', maxLength: 2000 },
+    evalRunId: { type: 'string', description: 'The comparison this promotion was judged on.' },
+  },
+};
+
+export const RollbackBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['scope'],
+  properties: {
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    toVersion: {
+      type: 'string',
+      description: "An earlier version to go back to; omit → the scope's previous live version.",
+    },
+    reason: { type: 'string', maxLength: 2000 },
+  },
+};
+
+export const UnpinBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['scope'],
+  properties: {
+    scope: { $ref: '#/components/schemas/LiveScope' },
+    reason: { type: 'string', maxLength: 2000 },
   },
 };
 
@@ -194,6 +630,13 @@ export const RunSchema: JsonSchema = {
       type: 'string',
       description: 'Set on a replay run: the eval run that started it.',
     },
+    versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
+    segments: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/ScopeSegment' },
+      description:
+        "The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.",
+    },
     publicAccessToken: {
       type: 'string',
       description:
@@ -252,12 +695,23 @@ export const StartRunBodySchema: JsonSchema = {
       required: ['agent', 'input'],
       properties: {
         agent: { type: 'string', description: 'AgentId.' },
-        agentVersion: { type: 'string', description: 'Semver; omit → latest.' },
+        agentVersion: {
+          type: 'string',
+          description:
+            "Semver. Omit → the conversation's own version for a follow-up turn, else the version live for the run's scope, else the latest.",
+        },
         projectId: {
           type: 'string',
           format: 'uuid',
           description: "Project to run under; omit → the tenant's Default project.",
         },
+        segments: {
+          type: 'array',
+          maxItems: 8,
+          items: { $ref: '#/components/schemas/ScopeSegment' },
+          description:
+            "The run's segment path below its project, coarse to fine (an app-defined finer scope, e.g. company then role). A version live on a prefix of it serves the run.",
+        },
         input: {
           description: 'Opaque payload forwarded to the agent binding.',
         },
@@ -276,6 +730,13 @@ export const StartRunBodySchema: JsonSchema = {
           format: 'uuid',
           description: "Project to run under; omit → the tenant's Default project.",
         },
+        segments: {
+          type: 'array',
+          maxItems: 8,
+          items: { $ref: '#/components/schemas/ScopeSegment' },
+          description:
+            "The run's segment path below its project, coarse to fine (an app-defined finer scope, e.g. company then role). A version live on a prefix of it serves the run.",
+        },
         input: {
           description: 'Opaque payload forwarded to the flow runtime.',
         },
@@ -794,6 +1255,28 @@ export const CompleteApprovalResultSchema: JsonSchema = {
       description:
         'True when the approval had a `waitTokenId` + terminal accept/reject and the run waitpoint was completed as part of this call.',
     },
+    resume: {
+      description:
+        "How the run went on, when this call resumed it (the runtime resumes inline): `ok`, or `failed` with the run's error, e.g. `tool-version-unresolvable` when a tool version the turn started with is gone. The decision stands either way.",
+      oneOf: [
+        {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind'],
+          properties: { kind: { type: 'string', const: 'ok' } },
+        },
+        {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind', 'code', 'message'],
+          properties: {
+            kind: { type: 'string', const: 'failed' },
+            code: { type: 'string' },
+            message: { type: 'string' },
+          },
+        },
+      ],
+    },
   },
 };
 
@@ -1287,6 +1770,21 @@ export const FlowPinsSchema: JsonSchema = {
   },
 };
 
+export const FlowVersionOverridesSchema: JsonSchema = {
+  description:
+    "Agents and tools a flow runs at other exact versions than the flow version's pins (\"this flow, with `acme.scorer` at 0.4.0\"), without publishing a new flow version: a comparison's flow candidate (`versions` on the start body and the run's `comparison`), and the flow runs that replay it (a run's `versions`). Each id must be an agent or tool the flow uses.",
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    tools: { ...PinMapSchema, description: 'Tool id → exact version.' },
+    agents: {
+      ...PinMapSchema,
+      description:
+        'Agent id → exact version, for agent nodes with or without a version of their own.',
+    },
+  },
+};
+
 export const PublishFlowBodySchema: JsonSchema = {
   description:
     'Full flow definition. Validated server-side via `@kindgi/flow.loadFlow` — validation failures return `400 validation-failed` with the issue list under `details.issues`.',
@@ -2086,6 +2584,34 @@ export const JudgeClassScopeSchema: JsonSchema = {
   ],
 };
 
+export const JudgeClassAssertableBySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  minProperties: 1,
+  description:
+    'Who may assert the class: every part that is set must hold. A class with one is restricted: a judgment recorded while it is carries `restricted`, and a comparison weighted `restricted-only` counts only those.',
+  properties: {
+    minReviewerRole: {
+      type: 'string',
+      enum: ['standard', 'senior', 'admin'],
+      description: "The caller's reviewer role is at least this (its token's, or the roster's).",
+    },
+    principalKinds: {
+      type: 'array',
+      minItems: 1,
+      items: { type: 'string', enum: ['user', 'service'] },
+      description: 'Users, service tokens, or both.',
+    },
+    principalIds: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 100,
+      items: { type: 'string', minLength: 1 },
+      description: 'Only these principals: user ids, or service token ids.',
+    },
+  },
+};
+
 export const JudgeClassSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
@@ -2104,6 +2630,7 @@ export const JudgeClassSchema: JsonSchema = {
       description: 'How much a judgment of this class counts, relative to the others.',
     },
     description: { type: 'string' },
+    assertableBy: { $ref: '#/components/schemas/JudgeClassAssertableBy' },
     createdAt: { type: 'string', format: 'date-time' },
     updatedAt: { type: 'string', format: 'date-time' },
     unregisteredAt: {
@@ -2134,6 +2661,7 @@ export const CreateJudgeClassBodySchema: JsonSchema = {
     name: { type: 'string', minLength: 1, maxLength: 100 },
     weight: { type: 'number', minimum: 0 },
     description: { type: 'string' },
+    assertableBy: { $ref: '#/components/schemas/JudgeClassAssertableBy' },
   },
 };
 
@@ -2144,6 +2672,10 @@ export const UpdateJudgeClassBodySchema: JsonSchema = {
   properties: {
     weight: { type: 'number', minimum: 0 },
     description: { type: 'string' },
+    assertableBy: {
+      oneOf: [{ $ref: '#/components/schemas/JudgeClassAssertableBy' }, { type: 'null' }],
+      description: 'Who may assert the class; `null` lifts the restriction.',
+    },
   },
 };
 
@@ -2231,6 +2763,12 @@ export const JudgmentSchema: JsonSchema = {
       description:
         'The judge class the judgment is recorded under. Absent when unclassified (counts with weight 1).',
     },
+    restricted: {
+      type: 'boolean',
+      enum: [true],
+      description:
+        "Present (true) when the judge class was restricted (`assertableBy`) when the judgment was recorded, so the judge was checked against it. A restriction added or lifted later doesn't change it.",
+    },
     assertedBy: { $ref: '#/components/schemas/JudgmentAssertedBy' },
     participantId: {
       type: 'string',
@@ -2421,6 +2959,14 @@ export const JudgedItemSummarySchema: JsonSchema = {
       description: 'The weight behind "yes" (an unclassified judgment counts 1).',
     },
     totalWeight: { type: 'number', description: 'The weight behind all judgments of the item.' },
+    restricted: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['yesWeight', 'totalWeight'],
+      description:
+        'The same weights, counting only judgments recorded while their class was restricted (`Judgment.restricted`), for a comparison weighted `restricted-only`. Absent from a test set built before restrictions.',
+      properties: { yesWeight: { type: 'number' }, totalWeight: { type: 'number' } },
+    },
     reasons: {
       type: 'array',
       description: 'The reasons given, newest first.',
@@ -4342,7 +4888,7 @@ export const PolicySchema: JsonSchema = {
       type: 'object',
       additionalProperties: true,
       description:
-        "Kind-specific policy body. For `access-control`, matches `@kindgi/specs/policy.schema.json` (rules + defaults). For `model-routing`, matches `TenantPolicy` from `@kindgi/capabilities` (providers.allow / providers.deny / models.allow / models.deny / regionAllow / maxCostPerCallUsd / maxTokensPerCall). For `tool-errors`, `ToolErrorsSpec` (maxRetries / retryOn). For `hitl`, `HitlSpec` from `@kindgi/policy-contract` (maxTimeoutMs / minReviewerRole / tools — per tool id a mode or `{ mode, requiredRole }`); it only tightens an agent's approvals. `tool-errors` and `hitl` specs are validated on publish. For other kinds, the shape is defined by the runtime consumer.",
+        "Kind-specific policy body. For `access-control`, matches `@kindgi/specs/policy.schema.json` (rules + defaults). For `model-routing`, matches `TenantPolicy` from `@kindgi/capabilities` (providers.allow / providers.deny / models.allow / models.deny / regionAllow / maxCostPerCallUsd / maxTokensPerCall). For `tool-errors`, `ToolErrorsSpec` (maxRetries / retryOn). For `hitl`, `HitlSpec` from `@kindgi/policy-contract` (maxTimeoutMs / minReviewerRole / tools — per tool id a mode or `{ mode, requiredRole }`); it only tightens an agent's approvals. For `retention`, `{ v: 1, doc: RetentionSpec }` from `@kindgi/policy-contract` (domain / graceSeconds / mode, which must be `purge`); a tenant has one retention policy per domain, plus one for `*`. `tool-errors`, `hitl` and `retention` specs are validated on publish. For other kinds, the shape is defined by the runtime consumer.",
     },
   },
 };
@@ -4392,59 +4938,233 @@ export const PolicyVersionCollectionPageSchema: JsonSchema = {
       type: 'array',
       items: { $ref: '#/components/schemas/PolicyVersionRow' },
     },
-    nextCursor: { type: 'string' },
-    hasMore: { type: 'boolean' },
+    nextCursor: { type: 'string' },
+    hasMore: { type: 'boolean' },
+  },
+};
+
+export const PublishPolicyBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version', 'kind', 'spec'],
+  properties: {
+    id: { type: 'string', minLength: 1 },
+    tenantId: {
+      type: 'string',
+      format: 'uuid',
+      description:
+        'Optional. When present, must match the caller tenant (server-derived from the token). Cross-tenant publish is rejected.',
+    },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    kind: { $ref: '#/components/schemas/PolicyKind' },
+    description: { type: 'string' },
+    spec: { type: 'object', additionalProperties: true },
+  },
+};
+
+export const PublishPolicyResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['policyId', 'version'],
+  properties: {
+    policyId: { type: 'string' },
+    version: { type: 'string' },
+  },
+};
+
+export const UnregisterPolicyResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['policyId', 'version', 'unregistered'],
+  properties: {
+    policyId: { type: 'string' },
+    version: { type: 'string' },
+    unregistered: { type: 'boolean', const: true },
+  },
+};
+
+export const ReinstatePolicyVersionResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['policyId', 'version', 'wasTombstoned'],
+  properties: {
+    policyId: { type: 'string' },
+    version: { type: 'string' },
+    wasTombstoned: { type: 'boolean' },
+  },
+};
+
+// ---------------- retention (admin plane) ----------------
+
+/** A tombstoning domain a retention policy can cover; `*` is the tenant-wide default. */
+export const RetentionDomainSchema: JsonSchema = {
+  type: 'string',
+  enum: [...RETENTION_DOMAINS],
+};
+
+/**
+ * A domain more than one retention policy covers. Publishing refuses a
+ * second policy for a domain, so only policies stored before that rule
+ * can do this.
+ */
+export const RetentionPolicyConflictSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['domain', 'policyIds', 'appliedPolicyId'],
+  properties: {
+    domain: { $ref: '#/components/schemas/RetentionDomain' },
+    policyIds: {
+      type: 'array',
+      items: { type: 'string' },
+      minItems: 2,
+      description: 'Every policy id that covers the domain, sorted.',
+    },
+    appliedPolicyId: {
+      type: 'string',
+      description:
+        'The one that applies: the policy whose latest version is highest, and on equal versions the lower policy id. Unregister the others.',
+    },
+  },
+};
+
+export const RetentionScheduledItemSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'domain',
+    'id',
+    'unregisteredAt',
+    'purgeAt',
+    'pastGrace',
+    'policyId',
+    'policyVersion',
+    'graceSeconds',
+  ],
+  properties: {
+    domain: { $ref: '#/components/schemas/RetentionDomain' },
+    id: { type: 'string', description: "The tombstoned row's id in its domain." },
+    unregisteredAt: { type: 'string', format: 'date-time' },
+    purgeAt: {
+      type: 'string',
+      format: 'date-time',
+      description: "`unregisteredAt` plus the policy's grace: when a sweep purges the row.",
+    },
+    pastGrace: {
+      type: 'boolean',
+      description: 'Whether a sweep would purge the row now.',
+    },
+    policyId: { type: 'string', description: 'The retention policy that applies.' },
+    policyVersion: { type: 'string' },
+    graceSeconds: {
+      type: 'integer',
+      description: "The policy's grace, in seconds (`-1`: a hold, never purged).",
+    },
   },
 };
 
-export const PublishPolicyBodySchema: JsonSchema = {
+export const RetentionScheduledPageSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['id', 'version', 'kind', 'spec'],
+  required: ['data', 'domainsMissingAdapter', 'unpolicedDomains'],
   properties: {
-    id: { type: 'string', minLength: 1 },
-    tenantId: {
+    data: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/RetentionScheduledItem' },
+    },
+    hasMore: {
+      type: 'boolean',
+      description:
+        'Some domain has more scheduled rows than this page returned (`limit` is per domain). Always sent from 0.1.4; a runtime before it sends none.',
+    },
+    nextCursor: {
       type: 'string',
-      format: 'uuid',
       description:
-        'Optional. When present, must match the caller tenant (server-derived from the token). Cross-tenant publish is rejected.',
+        'The `cursor` for the next page. Absent when `hasMore: false`, or when the runtime cannot continue a page.',
+    },
+    domainsMissingAdapter: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/RetentionDomain' },
+      description:
+        "Domains a retention policy covers that this deployment can't purge (no adapter is wired).",
+    },
+    unpolicedDomains: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/RetentionDomain' },
+      description: 'Domains no retention policy covers: their tombstones are kept.',
+    },
+    conflicts: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/RetentionPolicyConflict' },
+      description: 'Domains more than one retention policy covers. Absent or empty: none.',
     },
-    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
-    kind: { $ref: '#/components/schemas/PolicyKind' },
-    description: { type: 'string' },
-    spec: { type: 'object', additionalProperties: true },
   },
 };
 
-export const PublishPolicyResultSchema: JsonSchema = {
+export const RetentionSweepBodySchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['policyId', 'version'],
   properties: {
-    policyId: { type: 'string' },
-    version: { type: 'string' },
+    domain: {
+      $ref: '#/components/schemas/RetentionDomain',
+      description: 'Sweep only this domain. Absent: every domain.',
+    },
+    maxPerDomain: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 10000,
+      description:
+        'The most rows one call purges per domain (default 500); the rest are `remaining`.',
+    },
   },
 };
 
-export const UnregisterPolicyResultSchema: JsonSchema = {
+export const RetentionSweepDomainBodySchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['policyId', 'version', 'unregistered'],
   properties: {
-    policyId: { type: 'string' },
-    version: { type: 'string' },
-    unregistered: { type: 'boolean', const: true },
+    maxPerDomain: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 10000,
+      description: 'The most rows this call purges (default 500); the rest are `remaining`.',
+    },
   },
 };
 
-export const ReinstatePolicyVersionResultSchema: JsonSchema = {
+export const RetentionSweepResultSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['policyId', 'version', 'wasTombstoned'],
+  required: ['perDomain', 'totalPurged'],
   properties: {
-    policyId: { type: 'string' },
-    version: { type: 'string' },
-    wasTombstoned: { type: 'boolean' },
+    perDomain: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['domain', 'purged', 'remaining'],
+        properties: {
+          domain: { $ref: '#/components/schemas/RetentionDomain' },
+          purged: { type: 'integer', minimum: 0 },
+          remaining: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Rows past grace this call left (the `maxPerDomain` cap); sweep again.',
+          },
+          policyId: { type: 'string', description: 'The retention policy that applied.' },
+          missingAdapter: {
+            type: 'boolean',
+            const: true,
+            description: "Present when this deployment can't purge the domain (no adapter).",
+          },
+        },
+      },
+    },
+    totalPurged: { type: 'integer', minimum: 0 },
+    conflicts: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/RetentionPolicyConflict' },
+      description: 'Domains more than one retention policy covers. Absent or empty: none.',
+    },
   },
 };
 
@@ -4724,7 +5444,7 @@ export const EvalRunFlowRefSchema: JsonSchema = {
 
 export const EvalBaselineSchema: JsonSchema = {
   description:
-    "What a comparison compares the candidate against: `'recorded'` (each case's recorded output, what was judged), a version (`{ agentId, version }`, replayed under the same rules), or the version live in a scope (`{ live: { projectId?, segments? } }`). Only `'recorded'` runs today; the others are refused when the run starts.",
+    "What a comparison compares the candidate against: `'recorded'` (each case's recorded output, what was judged), a version (`{ agentId, version }`, replayed under the same rules), or the version live in a scope (`{ live: { projectId?, segments? } }`, `segments` a path in the project, coarse to fine). Only `'recorded'` runs today; the others are refused when the run starts.",
   oneOf: [
     { type: 'string', enum: ['recorded'] },
     {
@@ -4743,7 +5463,13 @@ export const EvalBaselineSchema: JsonSchema = {
           additionalProperties: false,
           properties: {
             projectId: { type: 'string' },
-            segments: { type: 'object', additionalProperties: { type: 'string' } },
+            segments: {
+              type: 'array',
+              items: { $ref: '#/components/schemas/ScopeSegment' },
+              maxItems: 8,
+              description:
+                'A segment path in `projectId`, coarse to fine, as live versions resolve it. Needs `projectId`.',
+            },
           },
         },
       },
@@ -4766,6 +5492,359 @@ export const EvalComparisonSchema: JsonSchema = {
     },
     repetitions: { type: 'integer', minimum: 1, maximum: 10 },
     k: { type: 'integer', minimum: 1, maximum: 100 },
+    versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
+    classWeights: {
+      type: 'string',
+      enum: ['as-recorded', 'restricted-only'],
+      description:
+        "Which judgments count: each at its class's weight (`as-recorded`, the default), or only those recorded while their class was restricted (`Judgment.restricted`), the others weighing 0 (`restricted-only`).",
+    },
+  },
+};
+
+// ---------------- comparison results (a `judged` eval run's `result`) ----------------
+
+const nullableNumber = { type: ['number', 'null'] } as const;
+
+export const ComparisonMetricSchema: JsonSchema = {
+  description:
+    "One metric, the recorded runs beside the candidate. `null` where a side had no judged evidence; `n` / `weight` are the candidate's evidence (cases with judged items, and the judgment weight behind them), `baselineN` / `baselineWeight` the recorded side's.",
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'baseline',
+    'candidate',
+    'delta',
+    'n',
+    'weight',
+    'baselineN',
+    'baselineWeight',
+    'direction',
+  ],
+  properties: {
+    baseline: nullableNumber,
+    candidate: nullableNumber,
+    delta: nullableNumber,
+    n: { type: 'integer', minimum: 0 },
+    weight: { type: 'number', minimum: 0 },
+    baselineN: { type: 'integer', minimum: 0 },
+    baselineWeight: { type: 'number', minimum: 0 },
+    direction: { type: 'string', enum: ['higher'] },
+    k: {
+      type: 'integer',
+      minimum: 1,
+      description: '`weightedPrecisionAtK`: the ranked items it looked at.',
+    },
+    spread: {
+      type: 'number',
+      description: "With more than one repetition: the candidate's max − min across them.",
+    },
+  },
+};
+
+export const ComparisonCandidateSchema: JsonSchema = {
+  description:
+    'What ran on the cases: an agent version, or a flow version (with any versions it swapped in).',
+  oneOf: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'agentId', 'version'],
+      properties: {
+        kind: { type: 'string', enum: ['agent'] },
+        agentId: { type: 'string' },
+        version: { type: 'string' },
+        pinsDigest: {
+          type: 'string',
+          description:
+            "The version's pinsDigest: what it ran, as a promotion gate checks. Absent for a version published before pins, and from a comparison recorded before it.",
+        },
+      },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'flowId', 'version'],
+      properties: {
+        kind: { type: 'string', enum: ['flow'] },
+        flowId: { type: 'string' },
+        version: { type: 'string' },
+        versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
+      },
+    },
+  ],
+};
+
+export const JudgedComparisonSummarySchema: JsonSchema = {
+  description:
+    'What a comparison concluded: the candidate beside the recorded runs, the case counts, and the metrics. What a promotion gate reads.',
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'evalRunId',
+    'status',
+    'completedAt',
+    'suite',
+    'candidate',
+    'baseline',
+    'scope',
+    'cases',
+    'diverged',
+    'refusedWrites',
+    'errors',
+    'stopped',
+    'reads',
+    'sampling',
+    'repetitions',
+    'metrics',
+  ],
+  properties: {
+    evalRunId: { type: 'string' },
+    status: { type: 'string', enum: ['completed', 'partial', 'failed'] },
+    completedAt: { type: 'string', format: 'date-time' },
+    suite: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id', 'version'],
+      properties: { id: { type: 'string' }, version: { type: 'string' } },
+    },
+    candidate: { $ref: '#/components/schemas/ComparisonCandidate' },
+    baseline: {
+      description:
+        "What the candidate was compared with: `recorded` (the test set's recorded runs, with the versions that served them), or another version.",
+      oneOf: [
+        {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind', 'versions'],
+          properties: {
+            kind: { type: 'string', enum: ['recorded'] },
+            versions: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['version', 'cases'],
+                properties: {
+                  agentId: { type: 'string' },
+                  flowId: { type: 'string' },
+                  version: { type: 'string' },
+                  cases: { type: 'integer', minimum: 0 },
+                },
+              },
+            },
+          },
+        },
+        {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind', 'agentId', 'version', 'via'],
+          properties: {
+            kind: { type: 'string', enum: ['version'] },
+            agentId: { type: 'string' },
+            version: { type: 'string' },
+            via: { type: 'string', enum: ['explicit', 'live'] },
+            liveScope: { type: 'object', additionalProperties: true },
+          },
+        },
+      ],
+    },
+    scope: {
+      type: 'object',
+      additionalProperties: false,
+      description: "Where the test set's judgments came from.",
+      properties: { projectId: { type: 'string' } },
+    },
+    cases: { type: 'integer', minimum: 0 },
+    diverged: {
+      type: 'integer',
+      minimum: 0,
+      description: "Cases where a read with no recording ran live under `reads: 'recorded'`.",
+    },
+    refusedWrites: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Tool calls refused across the cases (what the candidate would have done).',
+    },
+    errors: { type: 'integer', minimum: 0, description: 'Cases none of whose repetitions ran.' },
+    stopped: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        "Flow cases that stopped at a write the replay refused: no output to score, so they're left out of the metrics.",
+    },
+    reads: { type: 'string', enum: ['recorded', 'live'] },
+    classWeights: {
+      type: 'string',
+      enum: ['as-recorded', 'restricted-only'],
+      description:
+        'Which judgments counted. Absent from a comparison recorded before restricted classes: `as-recorded`.',
+    },
+    sampling: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['models'],
+      properties: {
+        models: {
+          type: 'array',
+          description:
+            "The models that answered the candidate's replays, and how many replays each.",
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['providerId', 'model', 'runs'],
+            properties: {
+              providerId: { type: 'string' },
+              model: { type: 'string' },
+              runs: { type: 'integer', minimum: 0 },
+            },
+          },
+        },
+      },
+    },
+    repetitions: { type: 'integer', minimum: 1 },
+    metrics: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['weightedYesShare', 'judgedCoverage', 'weightedPrecisionAtK'],
+      properties: {
+        weightedYesShare: { $ref: '#/components/schemas/ComparisonMetric' },
+        judgedCoverage: { $ref: '#/components/schemas/ComparisonMetric' },
+        weightedPrecisionAtK: { $ref: '#/components/schemas/ComparisonMetric' },
+      },
+    },
+  },
+};
+
+const outputScore = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['yesWeight', 'totalWeight', 'items', 'judgedItems', 'topK'],
+  description:
+    "An output's score: Σ yesWeight and Σ totalWeight over its judged items, and over those among the first `k` ranked items.",
+  properties: {
+    yesWeight: { type: 'number' },
+    totalWeight: { type: 'number' },
+    items: { type: 'integer', minimum: 0 },
+    judgedItems: { type: 'integer', minimum: 0 },
+    topK: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['yesWeight', 'totalWeight'],
+      properties: { yesWeight: { type: 'number' }, totalWeight: { type: 'number' } },
+    },
+  },
+} as const;
+
+export const ComparisonCaseResultSchema: JsonSchema = {
+  description:
+    "One case of a comparison: its replay runs, the scores, the items kept, dropped and new, the tool calls, and why it didn't run when it didn't.",
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'caseId',
+    'runIds',
+    'baseline',
+    'candidate',
+    'diverged',
+    'refusedWrites',
+    'noContext',
+    'approvalSkipped',
+  ],
+  properties: {
+    caseId: { type: 'string' },
+    runIds: {
+      type: 'array',
+      items: { type: 'string' },
+      description: "The candidate's replay runs, one per repetition.",
+    },
+    baseline: outputScore,
+    candidate: { type: 'array', items: outputScore, description: 'One per repetition that ran.' },
+    changes: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kept', 'dropped', 'new'],
+      description: "The first repetition's items against the judged ones.",
+      properties: {
+        kept: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['key'],
+            properties: {
+              key: { type: 'string' },
+              rankBefore: { type: 'integer' },
+              rank: { type: 'integer' },
+            },
+          },
+        },
+        dropped: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['key'],
+            properties: { key: { type: 'string' }, rankBefore: { type: 'integer' } },
+          },
+        },
+        new: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['key', 'pointer'],
+            properties: {
+              key: { type: 'string' },
+              pointer: { type: 'string' },
+              rank: { type: 'integer' },
+            },
+          },
+        },
+      },
+    },
+    tools: {
+      type: 'array',
+      description: "The first repetition's tool calls, and what happened to each.",
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['step', 'callId', 'toolId', 'toolVersion', 'arguments', 'source'],
+        properties: {
+          step: { type: 'integer', minimum: 0 },
+          callId: { type: 'string' },
+          toolId: { type: 'string' },
+          toolVersion: { type: 'string' },
+          arguments: {},
+          source: { type: 'string', enum: ['live', 'recorded', 'refused'] },
+          reason: { type: 'string' },
+        },
+      },
+    },
+    diverged: { type: 'boolean' },
+    refusedWrites: { type: 'integer', minimum: 0 },
+    noContext: { type: 'boolean' },
+    approvalSkipped: { type: 'boolean' },
+    error: { type: 'string' },
+    stopped: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['toolId', 'arguments'],
+      description: 'Set when the replay stopped at a refused write: what it would have done.',
+      properties: { toolId: { type: 'string' }, arguments: {}, reason: { type: 'string' } },
+    },
+  },
+};
+
+export const JudgedComparisonResultSchema: JsonSchema = {
+  description:
+    "A comparison's `result` (a `judged` eval run's): the summary and each case. `EvalRun.result` stays an open object, since each kind has its own; the clients read it as this (TS `comparisonOf(run)`, Python `comparison_of(run)`).",
+  type: 'object',
+  additionalProperties: false,
+  required: ['summary', 'perCase'],
+  properties: {
+    summary: { $ref: '#/components/schemas/JudgedComparisonSummary' },
+    perCase: { type: 'array', items: { $ref: '#/components/schemas/ComparisonCaseResult' } },
   },
 };
 
@@ -4798,7 +5877,7 @@ export const EvalRunSchema: JsonSchema = {
       type: 'object',
       additionalProperties: true,
       description:
-        'Kind-specific opaque JSON. For `accuracy`, contains `{ passCount, totalCount, meanScore, perCase[] }`. For `judged` (a comparison), `{ summary, perCase[] }`: the summary has the baseline (the versions behind the recorded runs) and the candidate (`{ kind: "agent", agentId, version }` or `{ kind: "flow", flowId, version }`), the case counts (`cases`, `diverged`, `refusedWrites`, `errors`, and `stopped`: flow cases that stopped at a write the replay refused, left out of the metrics), the models that answered, and `metrics` (`weightedYesShare`, `judgedCoverage`, `weightedPrecisionAtK`, each `{ baseline, candidate, delta, n, weight, baselineN, baselineWeight, direction, k?, spread? }`); each case has its replay runs, the scores, the items kept, dropped and new, the tool calls with what happened to each, and `stopped` (what it would have done) when it stopped. Other kinds define their own shapes as their dispatchers ship.',
+        'Kind-specific opaque JSON. For `accuracy`, contains `{ passCount, totalCount, meanScore, perCase[] }`. For `judged` (a comparison), `{ summary, perCase[] }`: the summary has the baseline (the versions behind the recorded runs) and the candidate (`{ kind: "agent", agentId, version }` or `{ kind: "flow", flowId, version, versions? }`), the case counts (`cases`, `diverged`, `refusedWrites`, `errors`, and `stopped`: flow cases that stopped at a write the replay refused, left out of the metrics), the models that answered, and `metrics` (`weightedYesShare`, `judgedCoverage`, `weightedPrecisionAtK`, each `{ baseline, candidate, delta, n, weight, baselineN, baselineWeight, direction, k?, spread? }`); each case has its replay runs, the scores, the items kept, dropped and new, the tool calls with what happened to each, and `stopped` (what it would have done) when it stopped. Other kinds define their own shapes as their dispatchers ship.',
     },
     error: { type: 'string' },
     correlationId: { type: 'string' },
@@ -4831,9 +5910,16 @@ export const StartEvalRunBodySchema: JsonSchema = {
     reads: { type: 'string', enum: ['recorded', 'live'] },
     repetitions: { type: 'integer', minimum: 1, maximum: 10 },
     k: { type: 'integer', minimum: 1, maximum: 100 },
+    versions: { $ref: '#/components/schemas/FlowVersionOverrides' },
+    classWeights: {
+      type: 'string',
+      enum: ['as-recorded', 'restricted-only'],
+      description:
+        "Which judgments count: each at its class's weight (`as-recorded`, the default), or only those recorded while their class was restricted (`Judgment.restricted`), the others weighing 0 (`restricted-only`).",
+    },
   },
   description:
-    "Exactly one of `agentRef` or `flowRef` MUST be supplied. `dryRun: true` returns a plan preview without invoking the subject. For a `judged` suite (a test set), the run is a comparison: `agentRef` or `flowRef` with its `version` is the candidate, replayed on each case without doing anything the past run didn't (a flow stops at a write the replay refuses); `baseline` (default `'recorded'`), `reads` (default `recorded`), `repetitions` (default 1) and `k` (default 10) set how.",
+    "Exactly one of `agentRef` or `flowRef` MUST be supplied. `dryRun: true` returns a plan preview without invoking the subject. For a `judged` suite (a test set), the run is a comparison: `agentRef` or `flowRef` with its `version` is the candidate, replayed on each case without doing anything the past run didn't (a flow stops at a write the replay refuses); `baseline` (default `'recorded'`), `reads` (default `recorded`), `repetitions` (default 1) and `k` (default 10) set how. With `flowRef`, `versions` runs the flow with some of its agents or tools at other versions; an id the flow doesn't use, or a version that isn't published, is refused (`400 validation-failed`, each under `details.issues`).",
 };
 
 export const StartEvalRunResultSchema: JsonSchema = {
@@ -4923,6 +6009,10 @@ export const IdentityProviderCollectionPageSchema: JsonSchema = {
   required: ['data'],
   properties: {
     data: { type: 'array', items: { $ref: '#/components/schemas/IdentityProviderConfig' } },
+    hasMore: {
+      type: 'boolean',
+      description: 'Always `false`: the list comes whole. Absent from older servers.',
+    },
   },
 };
 
@@ -6298,6 +7388,11 @@ export const EnvCollectionPageSchema: JsonSchema = {
   required: ['data'],
   properties: {
     data: { type: 'array', items: { $ref: '#/components/schemas/EnvRecord' } },
+    hasMore: {
+      type: 'boolean',
+      description:
+        "Whether there's another page. Absent from older servers: there is one when `nextCursor` is set.",
+    },
     nextCursor: { type: 'string' },
   },
 };
@@ -6335,6 +7430,11 @@ export const SecretCollectionPageSchema: JsonSchema = {
   required: ['data'],
   properties: {
     data: { type: 'array', items: { $ref: '#/components/schemas/SecretRecord' } },
+    hasMore: {
+      type: 'boolean',
+      description:
+        "Whether there's another page. Absent from older servers: there is one when `nextCursor` is set.",
+    },
     nextCursor: { type: 'string' },
   },
 };
@@ -6345,6 +7445,11 @@ export const SecretVersionCollectionPageSchema: JsonSchema = {
   required: ['data'],
   properties: {
     data: { type: 'array', items: { $ref: '#/components/schemas/SecretVersionRecord' } },
+    hasMore: {
+      type: 'boolean',
+      description:
+        "Whether there's another page. Absent from older servers: there is one when `nextCursor` is set.",
+    },
     nextCursor: { type: 'string' },
   },
 };
@@ -7110,6 +8215,29 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['HealthResult', HealthResultSchema],
   ['RunStatus', RunStatusSchema],
   ['RunAgent', RunAgentSchema],
+  ['ScopeSegment', ScopeSegmentSchema],
+  ['LiveScopeTenant', LiveScopeTenantSchema],
+  ['LiveScopeOrg', LiveScopeOrgSchema],
+  ['LiveScopeProject', LiveScopeProjectSchema],
+  ['LiveScopeSegment', LiveScopeSegmentSchema],
+  ['LiveScope', LiveScopeSchema],
+  ['LiveVersionResolution', LiveVersionResolutionSchema],
+  ['LivePin', LivePinSchema],
+  ['LivePinList', LivePinListSchema],
+  ['Promotion', PromotionSchema],
+  ['PromotionPage', PromotionPageSchema],
+  ['GateCheck', GateCheckSchema],
+  ['GatePolicyRef', GatePolicyRefSchema],
+  ['GateApproval', GateApprovalSchema],
+  ['GatePolicySpec', GatePolicySpecSchema],
+  ['GatePolicy', GatePolicySchema],
+  ['GatePolicyPage', GatePolicyPageSchema],
+  ['PublishGatePolicyBody', PublishGatePolicyBodySchema],
+  ['GatePolicyResolution', GatePolicyResolutionSchema],
+  ['PromotionCheck', PromotionCheckSchema],
+  ['PromoteBody', PromoteBodySchema],
+  ['RollbackBody', RollbackBodySchema],
+  ['UnpinBody', UnpinBodySchema],
   ['Run', RunSchema],
   ['StartRunOptions', StartRunOptionsSchema],
   ['StartRunBody', StartRunBodySchema],
@@ -7168,6 +8296,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['CreateJudgmentBody', CreateJudgmentBodySchema],
   ['UnregisterJudgmentResult', UnregisterJudgmentResultSchema],
   ['JudgedItemSummary', JudgedItemSummarySchema],
+  ['JudgeClassAssertableBy', JudgeClassAssertableBySchema],
   ['JudgedEvalCase', JudgedEvalCaseSchema],
   ['JudgedEvalCaseCollectionPage', JudgedEvalCaseCollectionPageSchema],
   ['BuildJudgedSuiteBody', BuildJudgedSuiteBodySchema],
@@ -7189,6 +8318,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['DeriveAgentVersionBody', DeriveAgentVersionBodySchema],
   ['AgentPinSwaps', AgentPinSwapsSchema],
   ['FlowPins', FlowPinsSchema],
+  ['FlowVersionOverrides', FlowVersionOverridesSchema],
   ['PublishAgentBody', PublishAgentBodySchema],
   ['PublishAgentResult', PublishAgentResultSchema],
   ['UnregisterAgentResult', UnregisterAgentResultSchema],
@@ -7331,6 +8461,13 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['PublishPolicyResult', PublishPolicyResultSchema],
   ['UnregisterPolicyResult', UnregisterPolicyResultSchema],
   ['ReinstatePolicyVersionResult', ReinstatePolicyVersionResultSchema],
+  ['RetentionDomain', RetentionDomainSchema],
+  ['RetentionPolicyConflict', RetentionPolicyConflictSchema],
+  ['RetentionScheduledItem', RetentionScheduledItemSchema],
+  ['RetentionScheduledPage', RetentionScheduledPageSchema],
+  ['RetentionSweepBody', RetentionSweepBodySchema],
+  ['RetentionSweepDomainBody', RetentionSweepDomainBodySchema],
+  ['RetentionSweepResult', RetentionSweepResultSchema],
   ['EvalKind', EvalKindSchema],
   ['EvalSuite', EvalSuiteSchema],
   ['EvalSuiteCollectionPage', EvalSuiteCollectionPageSchema],
@@ -7352,6 +8489,11 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['EvalRunFlowRef', EvalRunFlowRefSchema],
   ['EvalBaseline', EvalBaselineSchema],
   ['EvalComparison', EvalComparisonSchema],
+  ['ComparisonMetric', ComparisonMetricSchema],
+  ['ComparisonCandidate', ComparisonCandidateSchema],
+  ['JudgedComparisonSummary', JudgedComparisonSummarySchema],
+  ['ComparisonCaseResult', ComparisonCaseResultSchema],
+  ['JudgedComparisonResult', JudgedComparisonResultSchema],
   ['EvalRun', EvalRunSchema],
   ['EvalRunCollectionPage', EvalRunCollectionPageSchema],
   ['StartEvalRunBody', StartEvalRunBodySchema],