@kindgi/api 0.1.4-rc.1 → 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 },
   },
 };
 
@@ -195,6 +631,12 @@ export const RunSchema: JsonSchema = {
       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:
@@ -253,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.',
         },
@@ -277,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.',
         },
@@ -795,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' },
+          },
+        },
+      ],
+    },
   },
 };
 
@@ -2102,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,
@@ -2120,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: {
@@ -2150,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' },
   },
 };
 
@@ -2160,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.',
+    },
   },
 };
 
@@ -2247,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',
@@ -2437,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.',
@@ -4358,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.",
     },
   },
 };
@@ -4464,6 +4994,180 @@ export const ReinstatePolicyVersionResultSchema: JsonSchema = {
   },
 };
 
+// ---------------- 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 RetentionScheduledPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'domainsMissingAdapter', 'unpolicedDomains'],
+  properties: {
+    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',
+      description:
+        '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.',
+    },
+  },
+};
+
+export const RetentionSweepBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    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 RetentionSweepDomainBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    maxPerDomain: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 10000,
+      description: 'The most rows this call purges (default 500); the rest are `remaining`.',
+    },
+  },
+};
+
+export const RetentionSweepResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['perDomain', 'totalPurged'],
+  properties: {
+    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.',
+    },
+  },
+};
+
 // ---------------- eval suites (admin plane) ----------------
 
 /**
@@ -4740,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'] },
     {
@@ -4759,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`.',
+            },
           },
         },
       },
@@ -4783,6 +5493,12 @@ 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`).",
+    },
   },
 };
 
@@ -4838,6 +5554,11 @@ export const ComparisonCandidateSchema: JsonSchema = {
         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.",
+        },
       },
     },
     {
@@ -4953,6 +5674,12 @@ export const JudgedComparisonSummarySchema: JsonSchema = {
         "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,
@@ -5184,6 +5911,12 @@ export const StartEvalRunBodySchema: 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`).",
+    },
   },
   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. 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`).",
@@ -5276,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.',
+    },
   },
 };
 
@@ -6651,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' },
   },
 };
@@ -6688,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' },
   },
 };
@@ -6698,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' },
   },
 };
@@ -7463,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],
@@ -7521,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],
@@ -7685,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],