@kindgi/api 0.1.4-rc.1 → 0.1.4-rc.3

package/dist/openapi/schemas.js

@@ -62,12 +62,18 @@
  * per-route parsers in `routes/*.ts` validate ad hoc.
  */
 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';
 // ---------------- shared shapes ----------------
 export const WireErrorSchema = {
     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',
@@ -128,6 +134,387 @@ export const RunAgentSchema = {
         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 = {
+    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, description, properties) => ({
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['data'],
+    properties: { data: { type: 'array', items: { $ref: '#/components/schemas/LivePin' } } },
+};
+export const PromotionSchema = {
+    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 = {
+    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 = {
+    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 = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'version'],
+    properties: { id: { type: 'string' }, version: { type: 'string' } },
+};
+export const GateApprovalSchema = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['scope'],
+    properties: {
+        scope: { $ref: '#/components/schemas/LiveScope' },
+        reason: { type: 'string', maxLength: 2000 },
     },
 };
 export const RunSchema = {
@@ -178,6 +565,11 @@ export const RunSchema = {
             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: 'Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.',
@@ -228,12 +620,21 @@ export const StartRunBodySchema = {
             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.',
                 },
@@ -252,6 +653,12 @@ export const StartRunBodySchema = {
                     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.',
                 },
@@ -719,6 +1126,27 @@ export const CompleteApprovalResultSchema = {
             type: 'boolean',
             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' },
+                    },
+                },
+            ],
+        },
     },
 };
 // ---------------- agents ----------------
@@ -1898,6 +2326,32 @@ export const JudgeClassScopeSchema = {
         },
     ],
 };
+export const JudgeClassAssertableBySchema = {
+    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 = {
     type: 'object',
     additionalProperties: false,
@@ -1916,6 +2370,7 @@ export const JudgeClassSchema = {
             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: {
@@ -1944,6 +2399,7 @@ export const CreateJudgeClassBodySchema = {
         name: { type: 'string', minLength: 1, maxLength: 100 },
         weight: { type: 'number', minimum: 0 },
         description: { type: 'string' },
+        assertableBy: { $ref: '#/components/schemas/JudgeClassAssertableBy' },
     },
 };
 export const UpdateJudgeClassBodySchema = {
@@ -1953,6 +2409,10 @@ export const UpdateJudgeClassBodySchema = {
     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.',
+        },
     },
 };
 export const UnregisterJudgeClassResultSchema = {
@@ -2033,6 +2493,11 @@ export const JudgmentSchema = {
             type: 'string',
             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',
@@ -2209,6 +2674,13 @@ export const JudgedItemSummarySchema = {
             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.',
@@ -3957,7 +4429,7 @@ export const PolicySchema = {
         spec: {
             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.",
+            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. 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.",
         },
     },
 };
@@ -4053,6 +4525,167 @@ export const ReinstatePolicyVersionResultSchema = {
         wasTombstoned: { type: 'boolean' },
     },
 };
+// ---------------- retention (admin plane) ----------------
+/** A tombstoning domain a retention policy can cover; `*` is the tenant-wide default. */
+export const RetentionDomainSchema = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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) ----------------
 /**
  * Closed set of eval kinds the framework knows about. Extended
@@ -4298,7 +4931,7 @@ export const EvalRunFlowRefSchema = {
     },
 };
 export const EvalBaselineSchema = {
-    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.",
+    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? } }`, `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'] },
         {
@@ -4317,7 +4950,12 @@ export const EvalBaselineSchema = {
                     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`.',
+                        },
                     },
                 },
             },
@@ -4339,6 +4977,11 @@ export const EvalComparisonSchema = {
         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`) ----------------
@@ -4388,6 +5031,10 @@ export const ComparisonCandidateSchema = {
                 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.",
+                },
             },
         },
         {
@@ -4499,6 +5146,11 @@ export const JudgedComparisonSummarySchema = {
             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,
@@ -4719,6 +5371,11 @@ export const StartEvalRunBodySchema = {
         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`).",
 };
@@ -4799,6 +5456,10 @@ export const IdentityProviderCollectionPageSchema = {
     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.',
+        },
     },
 };
 export const RegisterIdentityProviderResultSchema = {
@@ -6054,6 +6715,10 @@ export const EnvCollectionPageSchema = {
     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' },
     },
 };
@@ -6088,6 +6753,10 @@ export const SecretCollectionPageSchema = {
     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' },
     },
 };
@@ -6097,6 +6766,10 @@ export const SecretVersionCollectionPageSchema = {
     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' },
     },
 };
@@ -6796,6 +7469,29 @@ export const COMPONENT_SCHEMAS = [
     ['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],
@@ -6854,6 +7550,7 @@ export const COMPONENT_SCHEMAS = [
     ['CreateJudgmentBody', CreateJudgmentBodySchema],
     ['UnregisterJudgmentResult', UnregisterJudgmentResultSchema],
     ['JudgedItemSummary', JudgedItemSummarySchema],
+    ['JudgeClassAssertableBy', JudgeClassAssertableBySchema],
     ['JudgedEvalCase', JudgedEvalCaseSchema],
     ['JudgedEvalCaseCollectionPage', JudgedEvalCaseCollectionPageSchema],
     ['BuildJudgedSuiteBody', BuildJudgedSuiteBodySchema],
@@ -7018,6 +7715,13 @@ export const COMPONENT_SCHEMAS = [
     ['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],