@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/openapi/operations.ts

@@ -140,6 +140,33 @@ const TopLevelQueryParam: ParameterSpec = {
   schema: { type: 'boolean' },
 };
 
+const RunAgentIdQueryParam: ParameterSpec = {
+  name: 'agentId',
+  in: 'query',
+  required: false,
+  description:
+    "Only this agent's turns, at any version. Turns that ran before Kindgi 0.1.3 don't name their agent and aren't matched.",
+  schema: { type: 'string', minLength: 1 },
+};
+
+const RunReplaysQueryParam: ParameterSpec = {
+  name: 'replays',
+  in: 'query',
+  required: false,
+  description:
+    'Replay runs (an eval run re-running a past run). `exclude` (default) leaves them out; `include` lists them with the other runs; `only` lists just them.',
+  schema: { type: 'string', enum: ['exclude', 'include', 'only'], default: 'exclude' },
+};
+
+const RunEvalRunIdQueryParam: ParameterSpec = {
+  name: 'evalRunId',
+  in: 'query',
+  required: false,
+  description:
+    'Only the replay runs of this eval run. Implies replays are included; cannot be combined with `replays=exclude`.',
+  schema: { type: 'string', minLength: 1 },
+};
+
 const RunIncludeQueryParam: ParameterSpec = {
   name: 'include',
   in: 'query',
@@ -532,7 +559,7 @@ const CostToQueryParam: ParameterSpec = {
   in: 'query',
   required: false,
   description:
-    'ISO 8601 timestamp; records with `occurredAt <= to`. Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window).',
+    'ISO 8601 timestamp; records with `occurredAt < to` (exclusive). Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window).',
   schema: { type: 'string', format: 'date-time' },
 };
 
@@ -541,10 +568,62 @@ const CostGroupByQueryParam: ParameterSpec = {
   in: 'query',
   required: true,
   description:
-    'Comma-separated list of dimensions to aggregate over. Each value must be one of `agentId | runId | category | providerId | day | month | tenant | conversationId`. Duplicates collapse.',
+    "Comma-separated list of dimensions to aggregate over. Each value must be one of `agentId | runId | category | providerId | day | month | tenant | conversationId | model | servedModel | projectId | orgId | rootRunId | flowId`. `model` is the model actually called; `servedModel` the exact version the vendor reported; `orgId` the org of the record's project. Duplicates collapse.",
+  schema: { type: 'string' },
+};
+
+const CostAggregateLimitQueryParam: ParameterSpec = {
+  name: 'limit',
+  in: 'query',
+  required: false,
+  description:
+    'The most groups to return: the most expensive ones (`groups` is ordered by `totalUsd`, highest first). 1 to 10000, default 1000. When there were more, `truncated` is `true` and `totalGroups` says how many; the totals still cover every record.',
+  schema: { type: 'integer', minimum: 1, maximum: 10000, default: 1000 },
+};
+
+const CostModelQueryParam: ParameterSpec = {
+  name: 'model',
+  in: 'query',
+  required: false,
+  description: 'Filter model calls to this model, the one actually called (exact match).',
   schema: { type: 'string' },
 };
 
+const CostServedModelQueryParam: ParameterSpec = {
+  name: 'servedModel',
+  in: 'query',
+  required: false,
+  description: 'Filter model calls to the exact model version the vendor reported (exact match).',
+  schema: { type: 'string' },
+};
+
+const CostRootRunIdQueryParam: ParameterSpec = {
+  name: 'rootRunId',
+  in: 'query',
+  required: false,
+  description:
+    'Every record of the run tree whose root is this run: a flow run and the agent turns and sub-flows it started.',
+  schema: { type: 'string', format: 'uuid' },
+};
+
+const CostIncludeDescendantsQueryParam: ParameterSpec = {
+  name: 'includeDescendants',
+  in: 'query',
+  required: false,
+  description:
+    "With `runId`: the run's records and those of every run it started, at any depth. `true` or `false` (default).",
+  schema: { type: 'boolean', default: false },
+};
+
+const CostIncludeQueryParam: ParameterSpec = {
+  name: 'include',
+  in: 'query',
+  required: false,
+  description:
+    "Extra fields, comma-separated. `rawUsage`: each model call's usage object exactly as the vendor reported it.",
+  schema: { type: 'string', enum: ['rawUsage'] },
+};
+
 const ProviderIdPathParam: ParameterSpec = {
   name: 'providerId',
   in: 'path',
@@ -725,7 +804,7 @@ const EvalSuiteKindFilterQueryParam: ParameterSpec = {
   in: 'query',
   required: false,
   description:
-    'Filter to eval suites of a single kind. Values: `accuracy | pairwise | regression | human-review | benchmark | custom`.',
+    'Filter to eval suites of a single kind. Values: `accuracy | pairwise | regression | human-review | benchmark | custom | judged`.',
   schema: { $ref: '#/components/schemas/EvalKind' },
 };
 
@@ -737,6 +816,38 @@ const EvalSuiteNameFilterQueryParam: ParameterSpec = {
   schema: { type: 'string' },
 };
 
+const BlockIdPathParam: ParameterSpec = {
+  name: 'blockId',
+  in: 'path',
+  required: true,
+  description: 'Block id: dotted lowercase (e.g. `acme.intake-prompt`).',
+  schema: { type: 'string', minLength: 1 },
+};
+
+const BlockVersionPathParam: ParameterSpec = {
+  name: 'version',
+  in: 'path',
+  required: true,
+  description: 'Exact block version (`major.minor.patch`).',
+  schema: { type: 'string', minLength: 1 },
+};
+
+const BlockKindFilterQueryParam: ParameterSpec = {
+  name: 'kind',
+  in: 'query',
+  required: false,
+  description: 'Only blocks of this kind: `prompt` or `settings`.',
+  schema: { $ref: '#/components/schemas/BlockKind' },
+};
+
+const BlockNameFilterQueryParam: ParameterSpec = {
+  name: 'name',
+  in: 'query',
+  required: false,
+  description: 'Prefix match on the block id.',
+  schema: { type: 'string' },
+};
+
 // Admin plane — eval-run data plane.
 
 const EvalRunIdPathParam: ParameterSpec = {
@@ -858,6 +969,75 @@ const SecretNamePathParam: ParameterSpec = {
   schema: { type: 'string', minLength: 1 },
 };
 
+// ---------------- judgments + judge classes: parameters ----------------
+
+const JudgmentIdPathParam: ParameterSpec = {
+  name: 'judgmentId',
+  in: 'path',
+  required: true,
+  description: 'Judgment id.',
+  schema: { type: 'string', minLength: 1 },
+};
+
+const JudgeClassIdPathParam: ParameterSpec = {
+  name: 'judgeClassId',
+  in: 'path',
+  required: true,
+  description: 'Judge class id.',
+  schema: { type: 'string', minLength: 1 },
+};
+
+const judgmentQuery = (name: string, description: string, schema: JsonSchema): ParameterSpec => ({
+  name,
+  in: 'query',
+  required: false,
+  description,
+  schema,
+});
+
+const JudgmentListQueryParams: readonly ParameterSpec[] = [
+  judgmentQuery('runId', 'Only judgments of this run.', { type: 'string', minLength: 1 }),
+  judgmentQuery('agentId', 'Only judgments of runs of this agent.', {
+    type: 'string',
+    minLength: 1,
+  }),
+  judgmentQuery('agentVersion', 'Only judgments of runs of this agent version. Needs `agentId`.', {
+    type: 'string',
+    minLength: 1,
+  }),
+  judgmentQuery('flowId', 'Only judgments of runs of this flow.', { type: 'string', minLength: 1 }),
+  judgmentQuery('verdict', 'Only judgments with this verdict.', {
+    type: 'string',
+    enum: ['yes', 'no'],
+  }),
+  judgmentQuery('judgeClassId', 'Only judgments recorded under this judge class.', {
+    type: 'string',
+    minLength: 1,
+  }),
+  judgmentQuery('participantId', "Only judgments made for this app end user's opaque id.", {
+    type: 'string',
+    minLength: 1,
+  }),
+];
+
+const JudgeClassScopeKindQueryParam: ParameterSpec = judgmentQuery(
+  'scopeKind',
+  'Only classes of this scope kind. `project` and `agent` need `projectId`; `agent` also needs `agentId`.',
+  { type: 'string', enum: ['tenant', 'project', 'agent'] },
+);
+
+const JudgeClassProjectIdQueryParam: ParameterSpec = judgmentQuery(
+  'projectId',
+  'Project of the scope, for `scopeKind=project|agent`.',
+  { type: 'string', minLength: 1 },
+);
+
+const JudgeClassAgentIdQueryParam: ParameterSpec = judgmentQuery(
+  'agentId',
+  'Agent of the scope, for `scopeKind=agent`.',
+  { type: 'string', minLength: 1 },
+);
+
 // ---------------- shared responses ----------------
 
 const ErrorResponse = (description: string): ResponseSpec => ({
@@ -951,14 +1131,19 @@ export const OPERATIONS: readonly OperationSpec[] = [
     parameters: [
       LimitQueryParam,
       CursorQueryParam,
+      ScopeKindQueryParam,
+      ScopeIdQueryParam,
       ParentRunIdQueryParam,
       TopLevelQueryParam,
+      RunAgentIdQueryParam,
+      RunReplaysQueryParam,
+      RunEvalRunIdQueryParam,
       RunIncludeQueryParam,
     ],
     responses: {
       '200': { description: 'Page of runs.', schema: ref('RunCollectionPage') },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed cursor or filter.'),
+      '400': ErrorResponse('Malformed cursor, filter or scope.'),
     },
   },
   {
@@ -971,6 +1156,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     security: 'bearer',
     parameters: [RunIdPathParam],
     responses: {
+      '400': ErrorResponse('`runId` is not a run id (a UUID).'),
       '200': { description: 'Run row.', schema: ref('Run') },
       ...CommonAuthErrors,
       '404': ErrorResponse('No run with that id under this tenant.'),
@@ -1022,6 +1208,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     security: 'bearer',
     parameters: [RunIdPathParam, JournalSinceQueryParam],
     responses: {
+      '400': ErrorResponse('`runId` is not a run id (a UUID).'),
       '200': { description: 'Journal page.', schema: ref('RunJournalPage') },
       ...CommonAuthErrors,
       '404': ErrorResponse('No run with that id under this tenant.'),
@@ -1039,6 +1226,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     security: 'bearer',
     parameters: [RunIdPathParam, LastEventIdParam],
     responses: {
+      '400': ErrorResponse('`runId` is not a run id (a UUID).'),
       '200': {
         description: 'text/event-stream. Each frame is one RunEvent.',
         contentType: 'text/event-stream',
@@ -1060,6 +1248,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     security: 'bearer-or-public-run',
     parameters: [RunIdPathParam],
     responses: {
+      '400': ErrorResponse('`runId` is not a run id (a UUID).'),
       '200': { description: "The run's progress.", schema: ref('RunProgress') },
       ...CommonAuthErrors,
       '404': ErrorResponse('No run with that id that the token may read.'),
@@ -1077,6 +1266,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     security: 'bearer-or-public-run',
     parameters: [RunIdPathParam, LastEventIdParam],
     responses: {
+      '400': ErrorResponse('`runId` is not a run id (a UUID).'),
       '200': {
         description: 'text/event-stream. Each frame is one RunProgressEvent.',
         contentType: 'text/event-stream',
@@ -1278,12 +1468,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'approvals.list',
     summary: 'List approvals visible to the caller',
     description:
-      'Requires the token to carry a `reviewerRole`. Role-scoped: reviewers only see approvals whose `requiredRole` rank ≤ their rank (standard < senior < admin).',
+      "Requires a reviewer: a token that carries a `reviewerRole`, or whose user is a registered reviewer (the roster gives the role). Role-scoped: reviewers only see approvals whose `requiredRole` rank ≤ their rank (standard < senior < admin). `scopeKind`/`scopeId` narrow to one project's approvals, or every project's in an org; approvals from before Kindgi 0.1.3 have no project and are listed only without a scope.",
     tags: ['approvals'],
     security: 'bearer',
     parameters: [
       LimitQueryParam,
       CursorQueryParam,
+      ScopeKindQueryParam,
+      ScopeIdQueryParam,
       ApprovalStatusQueryParam,
       ApprovalRequiredRoleQueryParam,
       CreatedAfterQueryParam,
@@ -1291,8 +1483,8 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Page of approvals.', schema: ref('ApprovalCollectionPage') },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed query parameter.'),
-      '403': ErrorResponse('Token lacks a reviewer role or asked for a tier above the caller.'),
+      '400': ErrorResponse('Malformed query parameter or scope.'),
+      '403': ErrorResponse("The caller isn't a reviewer, or asked for a tier above its own."),
     },
   },
   {
@@ -1302,14 +1494,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'approvals.get',
     summary: 'Fetch a single approval',
     description:
-      'Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4).',
+      'Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4). A decided approval carries its `decision`: what the reviewer decided, why, and who (`decidedBy`, `user:<userId>`).',
     tags: ['approvals'],
     security: 'bearer',
     parameters: [ApprovalIdPathParam],
     responses: {
       '200': { description: 'Approval.', schema: ref('Approval') },
       ...CommonAuthErrors,
-      '403': ErrorResponse('Token lacks a reviewer role.'),
+      '403': ErrorResponse("The caller isn't a reviewer."),
       '404': ErrorResponse('No approval with that id — or the caller cannot see it.'),
     },
   },
@@ -1320,7 +1512,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'approvals.complete',
     summary: 'Submit a decision on an approval',
     description:
-      'Records the decision (`HitlBinding.submitReview`). When the approval carries a `waitTokenId` and the decision is `approve` or `reject`, also completes the waitpoint so the suspended run resumes.',
+      "Records the decision (`HitlBinding.submitReview`). When the approval carries a `waitTokenId` and the decision is `approve` or `reject`, also completes the waitpoint so the suspended run resumes, with `{ decided, rationale?, decidedBy, approvalId }`: the run's journal records who decided which approval (`decidedBy` is `user:<userId>`).",
     tags: ['approvals'],
     security: 'bearer',
     parameters: [ApprovalIdPathParam, IdempotencyKeyParam],
@@ -1418,7 +1610,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Signed audit bundle.', schema: ref('ExportAuditBundleResult') },
       ...CommonMutationErrors,
-      '403': ErrorResponse('Token lacks a reviewer role.'),
+      '403': ErrorResponse("The caller isn't a reviewer."),
       '404': ErrorResponse(
         'Approval not found, signing key id unknown, or signing not configured on this deployment.',
       ),
@@ -1481,6 +1673,27 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '404': ErrorResponse('No agent with that id under this tenant.'),
     },
   },
+  {
+    method: 'post',
+    honoPath: '/v1/agents/:agentId/versions',
+    openapiPath: '/v1/agents/{agentId}/versions',
+    operationId: 'agents.deriveVersion',
+    summary: 'Derive an agent version with data-block pins swapped',
+    description:
+      "An expert's edit, without a code change: a new agent version that is `from`'s bag with some prompt or settings pins swapped (`derivedFrom: { version, reason: 'edited', label, by }`), numbered the next free patch after the agent's highest version. Only blocks `from` already references swap, to a published, active version of the right kind (model settings for the model-settings block); tool pins come from code. Needs `publish` on the agent.",
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam, IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('DeriveAgentVersionBody') },
+    responses: {
+      '201': { description: 'The derived agent version.', schema: ref('Agent') },
+      ...CommonMutationErrors,
+      '400': ErrorResponse(
+        "`validation-failed`: `from` has no pins, a swap names a block it doesn't reference, or a version that isn't published, active or the right kind (see `details.issues`).",
+      ),
+      '404': ErrorResponse('`agent-not-found`: no agent at `from`.'),
+    },
+  },
   {
     method: 'get',
     honoPath: '/v1/agents/:agentId/versions/:version',
@@ -1881,12 +2094,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'conversations.list',
     summary: 'List conversations',
     description:
-      'Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`.',
+      "Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`, and `scopeKind`/`scopeId` for one project's conversations, or every project's in an org. Conversations from before Kindgi 0.1.3 have no project and are listed only without a scope.",
     tags: ['conversations'],
     security: 'bearer',
     parameters: [
       LimitQueryParam,
       CursorQueryParam,
+      ScopeKindQueryParam,
+      ScopeIdQueryParam,
       AgentIdQueryParam,
       ConversationStatusQueryParam,
     ],
@@ -1896,7 +2111,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
         schema: ref('ConversationCollectionPage'),
       },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed query parameter.'),
+      '400': ErrorResponse('Malformed query parameter or scope.'),
     },
   },
   {
@@ -1921,7 +2136,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'conversations.open',
     summary: 'Open a conversation',
     description:
-      'Pins `(agentId, agentVersion)` at open time. `title` defaults to `"Untitled conversation"` when omitted; `scope` accepts arbitrary JSON.',
+      'Pins `(agentId, agentVersion)` at open time. `title` defaults to `"Untitled conversation"` when omitted; `projectId` puts it in a project (lists filter by it; omitted, the Default project); `scope` accepts arbitrary JSON.',
     tags: ['conversations'],
     security: 'bearer',
     parameters: [IdempotencyKeyParam],
@@ -2243,12 +2458,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'provenance.list',
     summary: 'List provenance records',
     description:
-      'Cursor-paginated. Metadata rows only — clients fetch the DAG payload via `GET /v1/provenance/{runId}`. Fixed sort: `createdAt desc, id desc`. Filters: `?runId=`, `?agentId=`, `?createdAfter=`.',
+      "Cursor-paginated. Metadata rows only — clients fetch the DAG payload via `GET /v1/provenance/{runId}`. Fixed sort: `createdAt desc, id desc`. Filters: `?runId=`, `?agentId=`, `?createdAfter=`, and `scopeKind`/`scopeId` for one project's records, or every project's in an org (records from before Kindgi 0.1.3 have no project and are listed only without a scope).",
     tags: ['provenance'],
     security: 'bearer',
     parameters: [
       LimitQueryParam,
       CursorQueryParam,
+      ScopeKindQueryParam,
+      ScopeIdQueryParam,
       ProvenanceRunIdQueryParam,
       ProvenanceAgentIdQueryParam,
       ProvenanceCreatedAfterQueryParam,
@@ -2256,7 +2473,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Page of records.', schema: ref('ProvenanceCollectionPage') },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed cursor or `createdAfter` timestamp.'),
+      '400': ErrorResponse('Malformed cursor, `createdAfter` timestamp or scope.'),
     },
   },
   {
@@ -2569,7 +2786,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'providers.register',
     summary: 'Register a model provider',
     description:
-      'Body is a full `ProviderMetadata`. Server validates shape: provider-level `id` + `region` non-empty; `models[]` non-empty with unique `name` per entry; per-model `contextWindow` positive integer; per-model `features` against the closed enum; per-model `cost` non-negative; optional per-model `p95LatencyMs` / `maxOutputTokens` well-shaped — same rules as `@kindgi/capabilities.createProviderRegistry`. Secrets (API keys, endpoints) are NOT part of the wire shape; deployments store them inside the binding.',
+      'Body is a full `ProviderMetadata`. Server validates shape: provider-level `id` + `region` non-empty; `models[]` non-empty with unique `name` per entry; per-model `contextWindow` positive integer; per-model `features` against the closed enum; per-model `cost` non-negative; optional per-model `p95LatencyMs` / `maxOutputTokens` well-shaped; optional `labels` within their limits — same rules as `@kindgi/capabilities.createProviderRegistry`. Secrets (API keys, endpoints) are NOT part of the wire shape; deployments store them inside the binding.',
     tags: ['providers'],
     security: 'bearer',
     parameters: [IdempotencyKeyParam],
@@ -2587,13 +2804,193 @@ export const OPERATIONS: readonly OperationSpec[] = [
     openapiPath: '/v1/providers/{providerId}/unregister',
     operationId: 'providers.unregister',
     summary: 'Unregister a model provider',
+    description:
+      'A tombstone, not an erase: from then on the provider is gone from list, get and capabilities, and the router never picks it. Its id is free to register again. A retention policy on the `provider` domain purges the row.',
     tags: ['providers'],
     security: 'bearer',
     parameters: [ProviderIdPathParam, IdempotencyKeyParam],
     responses: {
       '200': { description: 'Unregistered.', schema: ref('UnregisterProviderResult') },
       ...CommonMutationErrors,
-      '404': ErrorResponse('No provider with that id under this tenant.'),
+      '404': ErrorResponse('No provider with that id under this tenant, or already unregistered.'),
+    },
+  },
+
+  // ---------- judgments ----------
+  {
+    method: 'post',
+    honoPath: '/v1/judgments',
+    openapiPath: '/v1/judgments',
+    operationId: 'judgments.create',
+    summary: "Judge an item of a run's output",
+    description:
+      "Records yes or no, with an optional reason, about one item of a finished run's output, optionally under a judge class that applies to the run's project or agent (unclassified judgments count with weight 1). `item.pointer` (a JSON Pointer) must resolve in the run's output; its value is kept as `itemValue`. The first judgment of a run also stores a copy of the run's input and output. `assertedBy` is the authenticated caller, never the body. Judging again as the same caller for the same run, item key and `participantId` supersedes the earlier judgment. Needs `judge` on the run.",
+    tags: ['judgments'],
+    security: 'bearer',
+    parameters: [IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('CreateJudgmentBody') },
+    responses: {
+      '201': { description: 'Judgment recorded.', schema: ref('Judgment') },
+      ...CommonMutationErrors,
+      '400': ErrorResponse(
+        'Malformed body, or `item-not-found` (the pointer resolves to nothing in the output), or `judge-class-not-applicable`.',
+      ),
+      '403': ErrorResponse('`permission-denied`: not allowed to judge this run.'),
+      '404': ErrorResponse('`run-not-found`.'),
+      '409': ErrorResponse('`run-not-finished`: the run has no output to judge yet.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/judgments',
+    openapiPath: '/v1/judgments',
+    operationId: 'judgments.list',
+    summary: 'List judgments',
+    description:
+      'Live judgments (not removed or superseded), newest first, cursor-paginated. Filter by run, agent (and version), flow, verdict, judge class or participant; `?scopeKind + ?scopeId` narrow to a project.',
+    tags: ['judgments'],
+    security: 'bearer',
+    parameters: [
+      LimitQueryParam,
+      CursorQueryParam,
+      ...JudgmentListQueryParams,
+      ScopeKindQueryParam,
+      ScopeIdQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Page of judgments.', schema: ref('JudgmentCollectionPage') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('Malformed query parameter.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/judgments/:judgmentId',
+    openapiPath: '/v1/judgments/{judgmentId}',
+    operationId: 'judgments.get',
+    summary: 'Fetch a judgment with its copies',
+    description:
+      "Returns the judgment (live or not) with the stored copy of the run's input and output and, when the judgment pointed at an item, its value.",
+    tags: ['judgments'],
+    security: 'bearer',
+    parameters: [JudgmentIdPathParam],
+    responses: {
+      '200': { description: 'Judgment with copies.', schema: ref('JudgmentWithCopies') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No judgment with that id under this tenant.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/judgments/:judgmentId/unregister',
+    openapiPath: '/v1/judgments/{judgmentId}/unregister',
+    operationId: 'judgments.unregister',
+    summary: 'Remove a judgment',
+    description:
+      'Soft delete: the judgment stops listing; retention policy decides when it is purged.',
+    tags: ['judgments'],
+    security: 'bearer',
+    parameters: [JudgmentIdPathParam, IdempotencyKeyParam],
+    responses: {
+      '200': { description: 'Removed.', schema: ref('UnregisterJudgmentResult') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('`permission-denied`.'),
+      '404': ErrorResponse('No live judgment with that id under this tenant.'),
+    },
+  },
+
+  // ---------- judge classes ----------
+  {
+    method: 'post',
+    honoPath: '/v1/judge-classes',
+    openapiPath: '/v1/judge-classes',
+    operationId: 'judgeClasses.create',
+    summary: 'Create a judge class',
+    description:
+      'A named kind of judge with a weight, scoped to the tenant, a project, or an agent in a project. Names are unique among the live classes of a scope. Needs `admin` on the tenant (tenant scope) or the project.',
+    tags: ['judge-classes'],
+    security: 'bearer',
+    parameters: [IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('CreateJudgeClassBody') },
+    responses: {
+      '201': { description: 'Judge class created.', schema: ref('JudgeClass') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('`permission-denied`.'),
+      '409': ErrorResponse('`judge-class-name-taken`, or an idempotency conflict.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/judge-classes',
+    openapiPath: '/v1/judge-classes',
+    operationId: 'judgeClasses.list',
+    summary: 'List judge classes',
+    description:
+      'Live classes, newest first, cursor-paginated. `?scopeKind=tenant|project|agent` (with `projectId` / `agentId`) narrows to one scope.',
+    tags: ['judge-classes'],
+    security: 'bearer',
+    parameters: [
+      LimitQueryParam,
+      CursorQueryParam,
+      JudgeClassScopeKindQueryParam,
+      JudgeClassProjectIdQueryParam,
+      JudgeClassAgentIdQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Page of judge classes.', schema: ref('JudgeClassCollectionPage') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('Malformed scope parameters.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/judge-classes/:judgeClassId',
+    openapiPath: '/v1/judge-classes/{judgeClassId}',
+    operationId: 'judgeClasses.get',
+    summary: 'Fetch a judge class',
+    description:
+      'Also returns a retired class (`unregisteredAt` set): judgments keep naming theirs.',
+    tags: ['judge-classes'],
+    security: 'bearer',
+    parameters: [JudgeClassIdPathParam],
+    responses: {
+      '200': { description: 'Judge class.', schema: ref('JudgeClass') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No judge class with that id under this tenant.'),
+    },
+  },
+  {
+    method: 'patch',
+    honoPath: '/v1/judge-classes/:judgeClassId',
+    openapiPath: '/v1/judge-classes/{judgeClassId}',
+    operationId: 'judgeClasses.update',
+    summary: "Change a judge class's weight or description",
+    tags: ['judge-classes'],
+    security: 'bearer',
+    parameters: [JudgeClassIdPathParam, IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('UpdateJudgeClassBody') },
+    responses: {
+      '200': { description: 'Updated judge class.', schema: ref('JudgeClass') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('`permission-denied`.'),
+      '404': ErrorResponse('No live judge class with that id under this tenant.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/judge-classes/:judgeClassId/unregister',
+    openapiPath: '/v1/judge-classes/{judgeClassId}/unregister',
+    operationId: 'judgeClasses.unregister',
+    summary: 'Retire a judge class',
+    description: 'No new judgments may name it; existing judgments keep it.',
+    tags: ['judge-classes'],
+    security: 'bearer',
+    parameters: [JudgeClassIdPathParam, IdempotencyKeyParam],
+    responses: {
+      '200': { description: 'Retired.', schema: ref('UnregisterJudgeClassResult') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('`permission-denied`.'),
+      '404': ErrorResponse('No live judge class with that id under this tenant.'),
     },
   },
 
@@ -2764,7 +3161,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'cost.records.list',
     summary: 'List cost records',
     description:
-      'Cursor-paginated. Filters (all AND): `runId`, `agentId`, `conversationId`, `category`, `providerId`, `from`, `to`. Sort order is fixed: `occurredAt desc, id desc`. Records represent one accounted resource event each — LLM inference, tool invocation, storage write, sandbox execution, etc.',
+      "Cursor-paginated. Filters (all AND): `runId` (with `includeDescendants`, its whole subtree), `rootRunId`, `agentId`, `conversationId`, `category`, `providerId`, `model`, `servedModel`, `from`, `to`. Sort order is fixed: `occurredAt desc, id desc`. Records represent one accounted resource event each — a model call (`category` `llm.inference`: one record per call, with its model, usage and what the vendor said about it), tool invocation, storage write, sandbox execution, etc. `include=rawUsage` adds each model call's usage as the vendor reported it.",
     tags: ['cost'],
     security: 'bearer',
     parameters: [
@@ -2775,11 +3172,16 @@ export const OPERATIONS: readonly OperationSpec[] = [
       CostConversationIdQueryParam,
       CostCategoryQueryParam,
       CostProviderIdQueryParam,
+      CostModelQueryParam,
+      CostServedModelQueryParam,
+      CostRootRunIdQueryParam,
+      CostIncludeDescendantsQueryParam,
       CostFromQueryParam,
       CostToQueryParam,
       ScopeKindQueryParam,
       ScopeIdQueryParam,
       InheritQueryParam,
+      CostIncludeQueryParam,
     ],
     responses: {
       '200': { description: 'Page of cost records.', schema: ref('CostRecordCollectionPage') },
@@ -2795,7 +3197,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     summary: 'Fetch a cost record',
     tags: ['cost'],
     security: 'bearer',
-    parameters: [CostRecordIdPathParam],
+    parameters: [CostRecordIdPathParam, CostIncludeQueryParam],
     responses: {
       '200': { description: 'Cost record.', schema: ref('CostRecord') },
       ...CommonAuthErrors,
@@ -2809,11 +3211,12 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'cost.aggregate',
     summary: 'Aggregate cost across a time window',
     description:
-      'Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId + ?inherit` narrow the aggregate to a specific scope — reconciles byte-for-byte with the same scoped `/records` list.',
+      "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. Each group, and the total, carries its cost and its token sums (`tokens`). `groups` is ordered by `totalUsd`, highest first (ties by key), and capped at `limit` (default 1000): `truncated` and `totalGroups` say when there were more, and the totals still cover every record. For every record, page through `/v1/cost/records`. `inherit` has no effect on cost records, which always belong to a project.",
     tags: ['cost'],
     security: 'bearer',
     parameters: [
       CostGroupByQueryParam,
+      CostAggregateLimitQueryParam,
       CostFromQueryParam,
       CostToQueryParam,
       CostCategoryQueryParam,
@@ -2821,6 +3224,10 @@ export const OPERATIONS: readonly OperationSpec[] = [
       CostAgentIdQueryParam,
       CostRunIdQueryParam,
       CostConversationIdQueryParam,
+      CostModelQueryParam,
+      CostServedModelQueryParam,
+      CostRootRunIdQueryParam,
+      CostIncludeDescendantsQueryParam,
       ScopeKindQueryParam,
       ScopeIdQueryParam,
       InheritQueryParam,
@@ -2997,7 +3404,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'policies.publish',
     summary: 'Publish a policy',
     description:
-      "Body is a full `Policy` — the server validates top-level shape (id, tenantId, semver version, kind ∈ closed enum, spec is an object). Deeper `spec` validation is the runtime consumer's responsibility per kind. Re-publishing an existing `(policyId, version)` returns `409 policy-already-registered`. Idempotency-Key applies (retries with the same key replay the original 201).",
+      "Body is a full `Policy` — the server validates top-level shape (id, tenantId, semver version, kind ∈ closed enum, spec is an object). Deeper `spec` validation is the runtime consumer's responsibility per kind. Re-publishing an existing `(policyId, version)` returns `409 policy-already-registered`. A known kind that no runtime consumer applies yet (`access-control`, `adapter-allowlist`, `rate-limit`, `compliance`) is refused with `400 kind-not-applied` (`details.appliedKinds` lists the ones that are): publishing it would change nothing. Idempotency-Key applies (retries with the same key replay the original 201).",
     tags: ['policies'],
     security: 'bearer',
     parameters: [IdempotencyKeyParam],
@@ -3005,7 +3412,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Policy published.', schema: ref('PublishPolicyResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '400': ErrorResponse(
+        'Validation failed (see `details.issues`), or `kind-not-applied`: no runtime consumer applies that kind yet.',
+      ),
       '409': ErrorResponse('Policy already registered at that (id, version).'),
     },
   },
@@ -3136,6 +3545,48 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '409': ErrorResponse('Eval suite already registered at that (id, version).'),
     },
   },
+  {
+    method: 'post',
+    honoPath: '/v1/eval-suites/:suiteId/versions/from-judgments',
+    openapiPath: '/v1/eval-suites/{suiteId}/versions/from-judgments',
+    operationId: 'evalSuites.buildFromJudgments',
+    summary: 'Build a test set from judgments',
+    description:
+      "Publishes a `judged` eval suite version whose cases are copies of judged runs of one agent (optionally one version) or flow, newest first, at most 1000. Each case holds the run's input, what the turn read (`context`), the judged output, and each item's judgments summed up: yes and no counts, the weight behind yes and behind all judgments (an unclassified judgment counts 1), and the reasons. `judgeClassIds` counts only judgments of those classes; `minJudgments` leaves out runs with fewer. Needs `admin` on the project.",
+    tags: ['eval-suites'],
+    security: 'bearer',
+    parameters: [EvalSuiteIdPathParam, IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('BuildJudgedSuiteBody') },
+    responses: {
+      '201': { description: 'Version published.', schema: ref('BuildJudgedSuiteResult') },
+      ...CommonMutationErrors,
+      '400': ErrorResponse('Malformed body.'),
+      '403': ErrorResponse('`permission-denied`.'),
+      '409': ErrorResponse('Eval suite already registered at that (id, version).'),
+      '501': ErrorResponse('`test-sets-not-supported`: this deployment cannot build test sets.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/eval-suites/:suiteId/versions/:version/cases',
+    openapiPath: '/v1/eval-suites/{suiteId}/versions/{version}/cases',
+    operationId: 'evalSuites.listCases',
+    summary: 'List the cases of a judged eval suite version',
+    description: 'Cursor-paginated, in the order the cases were stored (newest judged run first).',
+    tags: ['eval-suites'],
+    security: 'bearer',
+    parameters: [
+      EvalSuiteIdPathParam,
+      EvalSuiteVersionPathParam,
+      LimitQueryParam,
+      CursorQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Page of cases.', schema: ref('JudgedEvalCaseCollectionPage') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No eval suite with that id.'),
+    },
+  },
   {
     method: 'post',
     honoPath: '/v1/eval-suites/:suiteId/versions/:version/unregister',
@@ -3170,6 +3621,139 @@ export const OPERATIONS: readonly OperationSpec[] = [
   },
 
   // ---------- eval runs (data plane) ----------
+  {
+    method: 'get',
+    honoPath: '/v1/blocks',
+    openapiPath: '/v1/blocks',
+    operationId: 'blocks.list',
+    summary: 'List data blocks (latest version of each)',
+    description:
+      'Cursor-paginated. Only the blocks of projects the caller can read. `?kind=` narrows to prompts or settings, `?name=` is a prefix match on the id, and `?scopeKind=` + `?scopeId=` narrow to a project or an org, as the other lists do.',
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [
+      LimitQueryParam,
+      CursorQueryParam,
+      BlockKindFilterQueryParam,
+      BlockNameFilterQueryParam,
+      ScopeKindQueryParam,
+      ScopeIdQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Page of blocks.', schema: ref('BlockCollectionPage') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse(
+        'Malformed query parameter: an unknown `kind`, or `scope-invalid` for a malformed scope.',
+      ),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/blocks/:blockId',
+    openapiPath: '/v1/blocks/{blockId}',
+    operationId: 'blocks.get',
+    summary: 'Fetch a data block (latest version)',
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [BlockIdPathParam],
+    responses: {
+      '200': { description: 'Latest active version.', schema: ref('Block') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse(
+        "`block-not-found`: no such block, or one in a project the caller can't read.",
+      ),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/blocks/:blockId/versions',
+    openapiPath: '/v1/blocks/{blockId}/versions',
+    operationId: 'blocks.versions.list',
+    summary: 'List versions of a data block',
+    description:
+      'Newest published first. `?includeTombstoned=true` includes unregistered versions, each with `unregisteredAt`.',
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [BlockIdPathParam, LimitQueryParam, CursorQueryParam, IncludeTombstonedQueryParam],
+    responses: {
+      '200': { description: 'Page of versions.', schema: ref('BlockCollectionPage') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('`block-not-found`.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/blocks/:blockId/versions/:version',
+    openapiPath: '/v1/blocks/{blockId}/versions/{version}',
+    operationId: 'blocks.versions.get',
+    summary: 'Fetch a specific data block version',
+    description: 'An unregistered version is returned too, with `unregisteredAt`.',
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [BlockIdPathParam, BlockVersionPathParam],
+    responses: {
+      '200': { description: 'The block at that version.', schema: ref('Block') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('`block-not-found`.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/blocks',
+    openapiPath: '/v1/blocks',
+    operationId: 'blocks.publish',
+    summary: 'Publish a data block version',
+    description:
+      "Needs `write` on the project. A prompt's template must parse as Liquid; a settings block's `values` must satisfy its `schema` and the latest version's. A taken version is `409 block-already-registered` (versions never change); a block keeps its kind, and its versions stay in its first version's project (`409 block-project-mismatch`). Idempotency-Key applies.",
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('PublishBlockBody') },
+    responses: {
+      '201': { description: 'Published.', schema: ref('PublishBlockResult') },
+      ...CommonMutationErrors,
+      '400': ErrorResponse(
+        '`validation-failed` (see `details.issues`), or an unknown `projectId`.',
+      ),
+      '403': ErrorResponse('`permission-denied`: no `write` on the project.'),
+      '409': ErrorResponse('`block-already-registered` or `block-project-mismatch`.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/blocks/:blockId/versions/:version/unregister',
+    openapiPath: '/v1/blocks/{blockId}/versions/{version}/unregister',
+    operationId: 'blocks.versions.unregister',
+    summary: 'Unregister a data block version',
+    description:
+      'Soft: no range picks it any more, but the agent versions that pin it keep running it, and GET still reads it. Needs `write` on the project.',
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [BlockIdPathParam, BlockVersionPathParam, IdempotencyKeyParam],
+    responses: {
+      '200': { description: 'Unregistered.', schema: ref('UnregisterBlockResult') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('`permission-denied`: no `write` on the project.'),
+      '404': ErrorResponse('`block-not-found`, or already unregistered.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/blocks/:blockId/versions/:version/reinstate',
+    openapiPath: '/v1/blocks/{blockId}/versions/{version}/reinstate',
+    operationId: 'blocks.versions.reinstate',
+    summary: 'Reinstate an unregistered data block version',
+    description: 'Unchanged, as published. Idempotent. Needs `write` on the project.',
+    tags: ['blocks'],
+    security: 'bearer',
+    parameters: [BlockIdPathParam, BlockVersionPathParam, IdempotencyKeyParam],
+    responses: {
+      '200': { description: 'Reinstated.', schema: ref('ReinstateBlockResult') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('`permission-denied`: no `write` on the project.'),
+      '404': ErrorResponse('`block-not-found`.'),
+    },
+  },
   {
     method: 'post',
     honoPath: '/v1/eval-suites/:suiteId/runs',
@@ -3978,7 +4562,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'orgs.delete',
     summary: 'Delete an org (idempotent)',
     description:
-      'Idempotent — deleting an unknown or already-deleted org returns 204 per the binding contract.',
+      "A tombstone, not an erase: from then on the org is gone from get and list, and its slug is free for a new org. Its projects and teams stay, without an org; when one of those projects has the slug of a project that has none, nothing is deleted: `409 slug-conflict` names the slugs (rename or move those projects first). In the Kindgi runtime, the org's own secrets and secret mappings are deleted with it, for good, and its own environments and MCP endpoints are unregistered. A retention policy on the `org` domain purges the org's row. Idempotent: deleting an unknown or already-deleted org returns 204.",
     tags: ['orgs'],
     security: 'bearer',
     parameters: [
@@ -3994,6 +4578,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '204': { description: 'Deleted (or already absent). No body.' },
       ...CommonAuthErrors,
+      '409': ErrorResponse(
+        "slug-conflict: the org's projects would leave it with slugs that projects without an org already have.",
+      ),
     },
   },
 
@@ -4297,6 +4884,8 @@ export const OPERATIONS: readonly OperationSpec[] = [
     openapiPath: '/v1/projects',
     operationId: 'projects.create',
     summary: 'Create a project',
+    description:
+      "A project's slug is unique within its org, and a project without an org's among the tenant's projects without one: two orgs may each have a project with the same slug. A taken slug answers `409 slug-conflict`; a second Default, `409 project-default-already-exists`.",
     tags: ['projects'],
     security: 'bearer',
     parameters: [IdempotencyKeyParam],
@@ -4335,6 +4924,8 @@ export const OPERATIONS: readonly OperationSpec[] = [
     openapiPath: '/v1/projects/{projectId}',
     operationId: 'projects.update',
     summary: 'Partially update a project',
+    description:
+      'A new `slug`, or a move to another org (`orgId`, or `null` for none), answers `409 slug-conflict` when the slug is taken where the project ends up.',
     tags: ['projects'],
     security: 'bearer',
     parameters: [