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

package/src/openapi/operations.ts

@@ -31,6 +31,12 @@ export interface ParameterSpec {
   readonly required?: boolean;
   readonly description?: string;
   readonly schema: JsonSchema;
+  /**
+   * A segment path, one `key:value` per repeated value, coarse to fine.
+   * Emitted as `x-kindgi-segment-path: true`; a generated client takes
+   * `{key, value}` steps and writes the values itself.
+   */
+  readonly segmentPath?: boolean;
 }
 
 export interface ResponseSpec {
@@ -158,6 +164,15 @@ const RunReplaysQueryParam: ParameterSpec = {
   schema: { type: 'string', enum: ['exclude', 'include', 'only'], default: 'exclude' },
 };
 
+const ConversationReplaysQueryParam: ParameterSpec = {
+  name: 'replays',
+  in: 'query',
+  required: false,
+  description:
+    "Replay conversations (opened by a comparison's replay turn; `metadata.replayOf` names the run it replays). `exclude` (default) leaves them out; `include` lists them with the others; `only` lists just them.",
+  schema: { type: 'string', enum: ['exclude', 'include', 'only'], default: 'exclude' },
+};
+
 const RunEvalRunIdQueryParam: ParameterSpec = {
   name: 'evalRunId',
   in: 'query',
@@ -167,6 +182,39 @@ const RunEvalRunIdQueryParam: ParameterSpec = {
   schema: { type: 'string', minLength: 1 },
 };
 
+const LiveProjectQueryParam: ParameterSpec = {
+  name: 'projectId',
+  in: 'query',
+  required: false,
+  description: "The run's project; omit → only the agent's tenant-wide pin applies.",
+  schema: { type: 'string', format: 'uuid' },
+};
+
+const SegmentQueryParam: ParameterSpec = {
+  name: 'segment',
+  in: 'query',
+  required: false,
+  description: 'One step of the segment path, `key:value`; repeat it in order, coarse to fine.',
+  schema: { type: 'array', items: { type: 'string' } },
+  segmentPath: true,
+};
+
+const PromotionScopeKindQueryParam: ParameterSpec = {
+  name: 'scopeKind',
+  in: 'query',
+  required: false,
+  description:
+    'Only one scope: `tenant`, `org` or `project` (with `scopeId`), or `segment` (with `scopeId` and `segment`).',
+  schema: { type: 'string', enum: ['tenant', 'org', 'project', 'segment'] },
+};
+
+const PromotionIdPathParam: ParameterSpec = {
+  name: 'promotionId',
+  in: 'path',
+  required: true,
+  schema: { type: 'string', format: 'uuid' },
+};
+
 const RunIncludeQueryParam: ParameterSpec = {
   name: 'include',
   in: 'query',
@@ -201,6 +249,22 @@ const LastEventIdParam: ParameterSpec = {
   schema: { type: 'string' },
 };
 
+const GatePolicyIdPathParam: ParameterSpec = {
+  name: 'policyId',
+  in: 'path',
+  required: true,
+  description: 'The gate policy id.',
+  schema: { type: 'string' },
+};
+
+const GatePolicyVersionPathParam: ParameterSpec = {
+  name: 'version',
+  in: 'path',
+  required: true,
+  description: 'A semver version of the gate policy.',
+  schema: { type: 'string' },
+};
+
 const AgentIdPathParam: ParameterSpec = {
   name: 'agentId',
   in: 'path',
@@ -321,6 +385,15 @@ const ApprovalRequiredRoleQueryParam: ParameterSpec = {
   schema: { $ref: '#/components/schemas/ReviewerRole' },
 };
 
+const WaitTokenIdQueryParam: ParameterSpec = {
+  name: 'waitTokenId',
+  in: 'query',
+  required: false,
+  description:
+    "Only approvals linked to one of these run waits (an approval's `waitTokenId`; a run's journal names its open waits in `wait.suspended` entries). Repeat it for several, at most 50.",
+  schema: { type: 'array', items: { type: 'string', minLength: 1 }, maxItems: 50 },
+};
+
 const CreatedAfterQueryParam: ParameterSpec = {
   name: 'createdAfter',
   in: 'query',
@@ -367,6 +440,38 @@ const SupervisorIdQueryParam: ParameterSpec = {
   schema: { type: 'string' },
 };
 
+const ObservationAgentVersionQueryParam: ParameterSpec = {
+  name: 'agentVersion',
+  in: 'query',
+  required: false,
+  description: 'Only the observations of this agent version (with `agentId`).',
+  schema: { type: 'string' },
+};
+
+const ObservationConversationIdQueryParam: ParameterSpec = {
+  name: 'conversationId',
+  in: 'query',
+  required: false,
+  description: 'Only the observations of turns in this conversation.',
+  schema: { type: 'string' },
+};
+
+const ObservationSinceQueryParam: ParameterSpec = {
+  name: 'since',
+  in: 'query',
+  required: false,
+  description: 'Only the observations at or after this time (ISO 8601).',
+  schema: { type: 'string', format: 'date-time' },
+};
+
+const ObservationUntilQueryParam: ParameterSpec = {
+  name: 'until',
+  in: 'query',
+  required: false,
+  description: 'Only the observations at or before this time (ISO 8601).',
+  schema: { type: 'string', format: 'date-time' },
+};
+
 const FactIdPathParam: ParameterSpec = {
   name: 'factId',
   in: 'path',
@@ -456,7 +561,7 @@ const ProvenanceAgentIdQueryParam: ParameterSpec = {
   in: 'query',
   required: false,
   description:
-    'Filter records to those with at least one DAG node whose `actor = <agentId>` (agent-driven turns tag their nodes with the agent id).',
+    "Only the records of this agent's turns, at any version: the agent the record's run names, as `GET /v1/runs?agentId=` matches it. Turns that ran before Kindgi 0.1.3 don't name their agent and aren't matched.",
   schema: { type: 'string' },
 };
 
@@ -769,7 +874,7 @@ const PolicyKindFilterQueryParam: ParameterSpec = {
   in: 'query',
   required: false,
   description:
-    'Filter to policies of a single kind. Values: `access-control | model-routing | adapter-allowlist | rate-limit | retention | compliance`.',
+    'Filter to policies of a single kind. Values: `access-control | model-routing | adapter-allowlist | rate-limit | retention | compliance | tool-errors | hitl`.',
   schema: { $ref: '#/components/schemas/PolicyKind' },
 };
 
@@ -781,6 +886,32 @@ const PolicyNameFilterQueryParam: ParameterSpec = {
   schema: { type: 'string' },
 };
 
+// Admin plane — retention.
+
+const RetentionDomainQueryParam: ParameterSpec = {
+  name: 'domain',
+  in: 'query',
+  required: false,
+  description: 'Only this domain. Absent: every domain.',
+  schema: { $ref: '#/components/schemas/RetentionDomain' },
+};
+
+const RetentionPastGraceOnlyQueryParam: ParameterSpec = {
+  name: 'pastGraceOnly',
+  in: 'query',
+  required: false,
+  description: '`true`: only rows past their grace, the ones a sweep would purge now.',
+  schema: { type: 'boolean', default: false },
+};
+
+const RetentionDomainPathParam: ParameterSpec = {
+  name: 'domain',
+  in: 'path',
+  required: true,
+  description: 'The domain to sweep (not `*`).',
+  schema: { $ref: '#/components/schemas/RetentionDomain' },
+};
+
 // Admin plane — eval suites.
 
 const EvalSuiteIdPathParam: ParameterSpec = {
@@ -1115,8 +1246,13 @@ export const OPERATIONS: readonly OperationSpec[] = [
         schema: ref('Run'),
       },
       ...CommonMutationErrors,
-      '404': ErrorResponse('Agent or flow not found.'),
+      '404': ErrorResponse(
+        'Agent or flow not found; or `projectId` names no project of this tenant (`project-not-found`).',
+      ),
       '422': ErrorResponse('Guardrail violation or budget exceeded.'),
+      '400': ErrorResponse(
+        "Malformed request body, or the body's `projectId` isn't a project id (a UUID).",
+      ),
     },
   },
   {
@@ -1386,6 +1522,12 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Token minted.', schema: ref('MintTokenResult') },
       ...CommonMutationErrors,
       '403': ErrorResponse('Not a tenant admin, or a capability the caller does not hold.'),
+      '400': ErrorResponse(
+        "Malformed request body, or the body's `projectId` isn't a project id (a UUID).",
+      ),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -1479,6 +1621,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ApprovalStatusQueryParam,
       ApprovalRequiredRoleQueryParam,
       CreatedAfterQueryParam,
+      WaitTokenIdQueryParam,
     ],
     responses: {
       '200': { description: 'Page of approvals.', schema: ref('ApprovalCollectionPage') },
@@ -1576,6 +1719,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Reviewer registered.', schema: ref('Reviewer') },
       ...CommonMutationErrors,
+      '403': ErrorResponse(
+        'With authorization enforced, the caller is not an admin of the tenant.',
+      ),
     },
   },
   {
@@ -1593,6 +1739,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Unregistered.', schema: ref('UnregisterReviewerResult') },
       ...CommonMutationErrors,
       '404': ErrorResponse('No reviewer with that id under this tenant.'),
+      '403': ErrorResponse(
+        'With authorization enforced, the caller is not an admin of the tenant.',
+      ),
     },
   },
   {
@@ -1697,9 +1846,11 @@ export const OPERATIONS: readonly OperationSpec[] = [
         "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
       ),
       '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`).",
+        "`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`); or `projectId` isn't a project id (a UUID).",
+      ),
+      '404': ErrorResponse(
+        '`agent-not-found`: no agent at `from`; or `projectId` names no project of this tenant (`project-not-found`).',
       ),
-      '404': ErrorResponse('`agent-not-found`: no agent at `from`.'),
     },
   },
   {
@@ -1732,10 +1883,15 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Agent published.', schema: ref('PublishAgentResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '400': ErrorResponse(
+        "Validation failed (see `details.issues`); or `projectId` isn't a project id (a UUID).",
+      ),
       '409': ErrorResponse(
         "Agent already registered at that (id, version). Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
       ),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -1751,7 +1907,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Unregistered.', schema: ref('UnregisterAgentResult') },
       ...CommonMutationErrors,
       '409': ErrorResponse(
-        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead. Or `agent-version-live`: the version is the live version of the scopes in `details.scopes`; roll back, unpin, or promote another version there first.",
       ),
       '404': ErrorResponse('No agent at that (id, version) under this tenant.'),
     },
@@ -1776,6 +1932,322 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '404': ErrorResponse('No agent at that (id, version) under this tenant.'),
     },
   },
+  {
+    method: 'get',
+    honoPath: '/v1/agents/:agentId/live',
+    openapiPath: '/v1/agents/{agentId}/live',
+    operationId: 'agents.live.resolve',
+    summary: 'The version a run would use',
+    description:
+      "Resolves the version a run of this agent would use for a project and segment path: the most specific live version (segment path, project, org, tenant), else the latest registered. A run that names its version, or a follow-up turn in a conversation, isn't resolved this way.",
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam, LiveProjectQueryParam, SegmentQueryParam],
+    responses: {
+      '200': { description: 'The resolved version.', schema: ref('LiveVersionResolution') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('A malformed project id or segment, or a segment without a project.'),
+      '404': ErrorResponse('No agent with that id.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/agents/:agentId/live-versions',
+    openapiPath: '/v1/agents/{agentId}/live-versions',
+    operationId: 'agents.live.list',
+    summary: "List an agent's live versions",
+    description: 'Every scope with a live version pinned, and the promotion that set it.',
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam],
+    responses: {
+      '200': { description: 'The pins.', schema: ref('LivePinList') },
+      ...CommonAuthErrors,
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/agents/:agentId/promotions',
+    openapiPath: '/v1/agents/{agentId}/promotions',
+    operationId: 'agents.promotions.create',
+    summary: 'Make a version live for a scope',
+    description:
+      "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.",
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam, IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('PromoteBody') },
+    responses: {
+      '201': { description: 'Promoted.', schema: ref('Promotion') },
+      '202': {
+        description: 'The gate passed; the promotion waits for an approval (`approvalId`).',
+        schema: ref('Promotion'),
+      },
+      ...CommonMutationErrors,
+      '404': ErrorResponse(
+        'The version is not registered, or was unregistered; or the eval run is not found.',
+      ),
+      '409': ErrorResponse(
+        "`promotion-superseded`: the scope's live version changed while the gate ran; check again.",
+      ),
+      '422': ErrorResponse(
+        '`gate-failed`: the gate refused it. `details.checks` has every check; the refusal is recorded (`details.promotionId`).',
+      ),
+      '501': ErrorResponse(
+        "`promotion-gate-unsupported`: a gate policy applies, and the deployment can't record a gated promotion.",
+      ),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/agents/:agentId/promotions/check',
+    openapiPath: '/v1/agents/{agentId}/promotions/check',
+    operationId: 'agents.promotions.check',
+    summary: 'Check a promotion against its gate',
+    description:
+      'What `POST …/promotions` with the same body would do, with nothing recorded: `would-promote`, `needs-approval` (with the approval it needs) or `gate-failed`, with every check. For a pipeline: evaluate, check, promote. Needs `read` on the agent.',
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam],
+    requestBody: { required: true, schema: ref('PromoteBody') },
+    responses: {
+      '200': { description: "The gate's answer.", schema: ref('PromotionCheck') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('Malformed body, or the eval run is not a finished comparison.'),
+      '404': ErrorResponse('The version, the agent or the eval run is not found.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/agents/:agentId/gate-policy',
+    openapiPath: '/v1/agents/{agentId}/gate-policy',
+    operationId: 'agents.gatePolicy.resolve',
+    summary: 'The gate policy for a scope',
+    description:
+      "The gate policy a promotion of the agent for the scope would be checked against: the most specific scope with an active policy (a segment path's longer prefixes first, then its project, the project's org, the tenant), at its latest active version. `policy: null` when none applies.",
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [
+      AgentIdPathParam,
+      PromotionScopeKindQueryParam,
+      ScopeIdQueryParam,
+      SegmentQueryParam,
+    ],
+    responses: {
+      '200': { description: 'The policy, or null.', schema: ref('GatePolicyResolution') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('Missing or malformed scope.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/gate-policies',
+    openapiPath: '/v1/gate-policies',
+    operationId: 'gatePolicies.list',
+    summary: 'List gate policies',
+    description:
+      "Each gate policy's latest active version. `agentId` narrows it to one agent's; `scopeKind` (with `scopeId` and `segment`) to one scope's.",
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [
+      LimitQueryParam,
+      CursorQueryParam,
+      {
+        name: 'agentId',
+        in: 'query',
+        required: false,
+        description: 'Only the policies gating this agent.',
+        schema: { type: 'string' },
+      },
+      PromotionScopeKindQueryParam,
+      ScopeIdQueryParam,
+      SegmentQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Page of gate policies.', schema: ref('GatePolicyPage') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('Malformed scope or cursor.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/gate-policies',
+    openapiPath: '/v1/gate-policies',
+    operationId: 'gatePolicies.publish',
+    summary: 'Publish a gate policy',
+    description:
+      "Registers a gate policy, or a new version of one: what a promotion of `agentId` for `scope` must show. One policy per agent and scope: another policy id for a scope that has one is refused with `409 gate-policy-scope-taken` (`details.heldBy` names it; publish a new version of that one instead), and a new version can't change the agent or scope (`409 gate-policy-scope-changed`). The `spec` is checked strictly: an unknown key is refused (`400 validation-failed`, `details.issues`). Needs `admin` on the tenant: whoever may promote can't loosen their own gate.",
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('PublishGatePolicyBody') },
+    responses: {
+      '201': { description: 'Gate policy published.', schema: ref('GatePolicy') },
+      ...CommonMutationErrors,
+      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '409': ErrorResponse(
+        '`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: nothing covering the scope is pinned, so a published version would go live there ungated; pin a version for the scope, or one above it, first.',
+      ),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/gate-policies/:policyId',
+    openapiPath: '/v1/gate-policies/{policyId}',
+    operationId: 'gatePolicies.get',
+    summary: 'Get a gate policy',
+    description: "The policy's latest active version.",
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [GatePolicyIdPathParam],
+    responses: {
+      '200': { description: 'The gate policy.', schema: ref('GatePolicy') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No active gate policy with that id.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/gate-policies/:policyId/versions',
+    openapiPath: '/v1/gate-policies/{policyId}/versions',
+    operationId: 'gatePolicies.versions.list',
+    summary: "List a gate policy's versions",
+    description: 'Every version, oldest first, unregistered ones too (with `unregisteredAt`).',
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [GatePolicyIdPathParam],
+    responses: {
+      '200': { description: 'The versions.', schema: ref('GatePolicyPage') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No gate policy with that id.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/gate-policies/:policyId/versions/:version',
+    openapiPath: '/v1/gate-policies/{policyId}/versions/{version}',
+    operationId: 'gatePolicies.versions.get',
+    summary: 'Get a gate policy version',
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [GatePolicyIdPathParam, GatePolicyVersionPathParam],
+    responses: {
+      '200': { description: 'The version.', schema: ref('GatePolicy') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No such version.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/gate-policies/:policyId/versions/:version/unregister',
+    openapiPath: '/v1/gate-policies/{policyId}/versions/{version}/unregister',
+    operationId: 'gatePolicies.versions.unregister',
+    summary: 'Unregister a gate policy version',
+    description:
+      "The version stops applying; the policy's latest remaining active version applies, or, with none, the scope above's policy. Promotions keep the version they were checked against. Needs `admin` on the tenant.",
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [GatePolicyIdPathParam, GatePolicyVersionPathParam],
+    responses: {
+      '200': { description: 'The unregistered version.', schema: ref('GatePolicy') },
+      ...CommonMutationErrors,
+      '404': ErrorResponse('No such version.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/gate-policies/:policyId/versions/:version/reinstate',
+    openapiPath: '/v1/gate-policies/{policyId}/versions/{version}/reinstate',
+    operationId: 'gatePolicies.versions.reinstate',
+    summary: 'Reinstate a gate policy version',
+    description: 'Needs `admin` on the tenant.',
+    tags: ['gate-policies'],
+    security: 'bearer',
+    parameters: [GatePolicyIdPathParam, GatePolicyVersionPathParam],
+    responses: {
+      '200': { description: 'The reinstated version.', schema: ref('GatePolicy') },
+      ...CommonMutationErrors,
+      '404': ErrorResponse('No such version.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/agents/:agentId/promotions',
+    openapiPath: '/v1/agents/{agentId}/promotions',
+    operationId: 'agents.promotions.list',
+    summary: "List an agent's promotions",
+    description:
+      'The history of live-version changes (promotions, rollbacks, unpins), newest first. `scopeKind` (`tenant`, `org`, `project`, `segment`) with `scopeId` and `segment` narrows it to one scope.',
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [
+      AgentIdPathParam,
+      LimitQueryParam,
+      CursorQueryParam,
+      PromotionScopeKindQueryParam,
+      ScopeIdQueryParam,
+      SegmentQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Page of promotions.', schema: ref('PromotionPage') },
+      ...CommonAuthErrors,
+      '400': ErrorResponse('Malformed scope or cursor.'),
+    },
+  },
+  {
+    method: 'get',
+    honoPath: '/v1/agents/:agentId/promotions/:promotionId',
+    openapiPath: '/v1/agents/{agentId}/promotions/{promotionId}',
+    operationId: 'agents.promotions.get',
+    summary: 'Get a promotion',
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam, PromotionIdPathParam],
+    responses: {
+      '200': { description: 'The promotion.', schema: ref('Promotion') },
+      ...CommonAuthErrors,
+      '404': ErrorResponse('No such promotion for this agent.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/agents/:agentId/live/rollback',
+    openapiPath: '/v1/agents/{agentId}/live/rollback',
+    operationId: 'agents.live.rollback',
+    summary: 'Roll a scope back to its previous live version',
+    description:
+      "Back to the scope's previous live version, or `toVersion`. Recorded like a promotion. Needs `promote` on the agent.",
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam, IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('RollbackBody') },
+    responses: {
+      '200': { description: 'Rolled back.', schema: ref('Promotion') },
+      ...CommonMutationErrors,
+      '404': ErrorResponse('`toVersion` is not registered, or was unregistered.'),
+      '409': ErrorResponse('The scope has no pin, or no earlier version to go back to.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/agents/:agentId/live/unpin',
+    openapiPath: '/v1/agents/{agentId}/live/unpin',
+    operationId: 'agents.live.unpin',
+    summary: "Remove a scope's live version",
+    description:
+      "Removes the scope's own pin: its runs use the next scope up (and the latest when nothing is pinned). Recorded like a promotion. Needs `promote` on the agent.",
+    tags: ['agents'],
+    security: 'bearer',
+    parameters: [AgentIdPathParam, IdempotencyKeyParam],
+    requestBody: { required: true, schema: ref('UnpinBody') },
+    responses: {
+      '200': { description: 'Unpinned.', schema: ref('Promotion') },
+      ...CommonMutationErrors,
+      '409': ErrorResponse(
+        '`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: unpinning would leave a scope a gate policy applies to on the latest version, where publishing goes live ungated.',
+      ),
+    },
+  },
 
   // ---------- flows ----------
   {
@@ -1863,10 +2335,15 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Flow published.', schema: ref('PublishFlowResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '400': ErrorResponse(
+        "Validation failed (see `details.issues`); or `projectId` isn't a project id (a UUID).",
+      ),
       '409': ErrorResponse(
         "Flow already registered at that (id, version). Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
       ),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -1998,10 +2475,15 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Tool registered.', schema: ref('RegisterToolResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '400': ErrorResponse(
+        "Validation failed (see `details.issues`); or `projectId` isn't a project id (a UUID).",
+      ),
       '409': ErrorResponse(
         "Tool already registered at that id. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
       ),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -2098,10 +2580,15 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Guardrail registered.', schema: ref('RegisterGuardrailResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '400': ErrorResponse(
+        "Validation failed (see `details.issues`); or `projectId` isn't a project id (a UUID).",
+      ),
       '409': ErrorResponse(
         "Guardrail already registered at that id. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
       ),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -2131,7 +2618,7 @@ 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`, 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.",
+      "Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`, `?replays=exclude|include|only` (default `exclude`: a comparison's replay conversations are left out), 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: [
@@ -2141,6 +2628,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ScopeIdQueryParam,
       AgentIdQueryParam,
       ConversationStatusQueryParam,
+      ConversationReplaysQueryParam,
     ],
     responses: {
       '200': {
@@ -2163,6 +2651,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Conversation.', schema: ref('Conversation') },
       ...CommonAuthErrors,
+      '400': ErrorResponse('`conversationId` is not a conversation id (a UUID).'),
       '404': ErrorResponse('No conversation with that id under this tenant.'),
     },
   },
@@ -2200,6 +2689,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
         schema: ref('Conversation'),
       },
       ...CommonMutationErrors,
+      '400': ErrorResponse('`conversationId` is not a conversation id (a UUID).'),
       '404': ErrorResponse('No conversation with that id under this tenant.'),
     },
   },
@@ -2220,7 +2710,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
         schema: ref('ConversationMessageCollectionPage'),
       },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed cursor.'),
+      '400': ErrorResponse(
+        'Malformed cursor, or `conversationId` is not a conversation id (a UUID).',
+      ),
       '404': ErrorResponse('No conversation with that id under this tenant.'),
     },
   },
@@ -2712,7 +3204,11 @@ export const OPERATIONS: readonly OperationSpec[] = [
       CursorQueryParam,
       ObservationStatusQueryParam,
       AgentIdQueryParam,
+      ObservationAgentVersionQueryParam,
       SupervisorIdQueryParam,
+      ObservationConversationIdQueryParam,
+      ObservationSinceQueryParam,
+      ObservationUntilQueryParam,
     ],
     responses: {
       '200': {
@@ -2872,7 +3368,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '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.'),
+      '403': ErrorResponse(
+        '`permission-denied`: not allowed to judge this run. `judge-class-not-allowed`: the judge class is restricted (`assertableBy`) and the caller may not assert it.',
+      ),
       '404': ErrorResponse('`run-not-found`.'),
       '409': ErrorResponse('`run-not-finished`: the run has no output to judge yet.'),
     },
@@ -3441,7 +3939,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`. 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).",
+      "Body is a full `Policy` — the server validates top-level shape (id, tenantId, semver version, kind ∈ closed enum, spec is an object), and `spec` for `tool-errors`, `hitl` and `retention` (a retention policy with an unknown domain or `mode: archive` is refused with `400 validation-failed`, naming the field). Other kinds' specs are their runtime consumer's to validate. Re-publishing an existing `(policyId, version)` returns `409 policy-already-registered`. A tenant has one retention policy per domain, plus one for `*`: a second policy id for a covered domain is refused with `409 policy-scope-taken` (`details.heldBy` names the policy that covers it; publish a new version of that one instead), and a new version can't move a policy to another domain (`409 policy-scope-changed`). 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],
@@ -3452,7 +3950,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '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).'),
+      '409': ErrorResponse(
+        '`policy-already-registered`: that (id, version) exists. `policy-scope-taken`: another policy covers the retention domain (`details.heldBy`). `policy-scope-changed`: the version would move the policy to another domain.',
+      ),
     },
   },
   {
@@ -3485,6 +3985,70 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Reinstated.', schema: ref('ReinstatePolicyVersionResult') },
       ...CommonMutationErrors,
       '404': ErrorResponse('No policy at that (id, version) under this tenant.'),
+      '409': ErrorResponse(
+        "`policy-scope-taken`: another policy now covers the version's retention domain (`details.heldBy`); unregister it first. `policy-scope-changed`: the version covers a different domain from the policy's other versions.",
+      ),
+    },
+  },
+
+  // ---------- retention (admin plane) ----------
+  {
+    method: 'get',
+    honoPath: '/v1/retention/scheduled',
+    openapiPath: '/v1/retention/scheduled',
+    operationId: 'retention.scheduled',
+    summary: 'List deleted rows scheduled for purging',
+    description:
+      "Tombstoned rows in every domain a retention policy covers, with when each is purged (`purgeAt`) and the policy that decides it. `domainsMissingAdapter` names the covered domains this deployment can't purge; `unpolicedDomains` the ones no policy covers, whose tombstones are kept; `conflicts` the domains two policies cover (stored before one policy per domain was enforced). `limit` caps the rows **per domain**; `hasMore` says some domain has more than it returned, and `nextCursor` (when the runtime can continue) is the `cursor` for the next page. Requires `admin` on the tenant.",
+    tags: ['retention'],
+    security: 'bearer',
+    parameters: [
+      RetentionDomainQueryParam,
+      RetentionPastGraceOnlyQueryParam,
+      LimitQueryParam,
+      CursorQueryParam,
+    ],
+    responses: {
+      '200': { description: 'Scheduled rows.', schema: ref('RetentionScheduledPage') },
+      ...CommonAuthErrors,
+      '403': ErrorResponse('Not a tenant admin.'),
+      '400': ErrorResponse('Unknown `domain`.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/retention/sweep',
+    openapiPath: '/v1/retention/sweep',
+    operationId: 'retention.sweep',
+    summary: 'Purge the deleted rows past their grace',
+    description:
+      "Purges, for good, every tombstoned row past the grace of the retention policy that covers its domain (or only `domain`'s), up to `maxPerDomain` per domain; `remaining` counts what is left for the next call. Nothing sweeps on its own: call this (or `POST /v1/retention/sweep/{domain}`) from a schedule. A hold (`graceSeconds: -1`) keeps its domain's rows. Idempotent: a second call purges nothing new. Requires `admin` on the tenant.",
+    tags: ['retention'],
+    security: 'bearer',
+    requestBody: { required: false, schema: ref('RetentionSweepBody') },
+    responses: {
+      '200': { description: 'What was purged, per domain.', schema: ref('RetentionSweepResult') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('Not a tenant admin.'),
+      '400': ErrorResponse('Unknown `domain`, or `maxPerDomain` outside 1..10000.'),
+    },
+  },
+  {
+    method: 'post',
+    honoPath: '/v1/retention/sweep/:domain',
+    openapiPath: '/v1/retention/sweep/{domain}',
+    operationId: 'retention.sweepDomain',
+    summary: "Purge one domain's deleted rows past their grace",
+    description: 'As `POST /v1/retention/sweep`, for one domain. Requires `admin` on the tenant.',
+    tags: ['retention'],
+    security: 'bearer',
+    parameters: [RetentionDomainPathParam],
+    requestBody: { required: false, schema: ref('RetentionSweepDomainBody') },
+    responses: {
+      '200': { description: 'What was purged.', schema: ref('RetentionSweepResult') },
+      ...CommonMutationErrors,
+      '403': ErrorResponse('Not a tenant admin.'),
+      '400': ErrorResponse('Unknown `domain` (or `*`), or `maxPerDomain` outside 1..10000.'),
     },
   },
 
@@ -3578,8 +4142,13 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Eval suite published.', schema: ref('PublishEvalSuiteResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Validation failed (see `details.issues`).'),
+      '400': ErrorResponse(
+        "Validation failed (see `details.issues`); or `projectId` isn't a project id (a UUID).",
+      ),
       '409': ErrorResponse('Eval suite already registered at that (id, version).'),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -3597,10 +4166,13 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Version published.', schema: ref('BuildJudgedSuiteResult') },
       ...CommonMutationErrors,
-      '400': ErrorResponse('Malformed body.'),
+      '400': ErrorResponse("Malformed body; or `projectId` isn't a project id (a UUID)."),
       '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.'),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -3750,10 +4322,13 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Published.', schema: ref('PublishBlockResult') },
       ...CommonMutationErrors,
       '400': ErrorResponse(
-        '`validation-failed` (see `details.issues`), or an unknown `projectId`.',
+        "`validation-failed` (see `details.issues`), or an unknown `projectId`; or `projectId` isn't a project id (a UUID).",
       ),
       '403': ErrorResponse('`permission-denied`: no `write` on the project.'),
       '409': ErrorResponse('`block-already-registered` or `block-project-mismatch`.'),
+      '404': ErrorResponse(
+        "The body's `projectId` names no project of this tenant (`project-not-found`).",
+      ),
     },
   },
   {
@@ -3807,9 +4382,11 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Eval run started.', schema: ref('StartEvalRunResult') },
       ...CommonMutationErrors,
       '400': ErrorResponse(
-        'Malformed body (both / neither of `agentRef` / `flowRef`, dispatcher-input-invalid).',
+        "Malformed body (both / neither of `agentRef` / `flowRef`, dispatcher-input-invalid); or `projectId` isn't a project id (a UUID).",
+      ),
+      '404': ErrorResponse(
+        'No eval suite with that id under this tenant; or `projectId` names no project of this tenant (`project-not-found`).',
       ),
-      '404': ErrorResponse('No eval suite with that id under this tenant.'),
       '422': ErrorResponse('No dispatcher registered for the suite kind.'),
     },
   },
@@ -4392,7 +4969,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'audit.authz.list',
     summary: 'List authz decision audit events',
     description:
-      'Cursor-paginated read of `authz-decision` audit events for the tenant. Filters (all AND-composed): `?actorSubject=` / `?onBehalfOf=` / `?action=` / `?resource=` / `?outcome=` / `?runId=` / `?from=` / `?to=`. Admin@tenant only. Only mounted when `CreateAppInput.auditEvents` is wired.',
+      'Cursor-paginated read of `authz-decision` audit events for the tenant. Filters (all AND-composed): `?actorSubject=` / `?onBehalfOf=` / `?action=` / `?resource=` / `?outcome=` / `?runId=` / `?from=` / `?to=`. Oldest first; `?order=desc` for newest first. Admin@tenant only. Only mounted when `CreateAppInput.auditEvents` is wired.',
     tags: ['audit'],
     security: 'bearer',
     parameters: [
@@ -4454,6 +5031,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
         description: 'ISO 8601 upper bound (inclusive) on `timestamp`.',
         schema: { type: 'string', format: 'date-time' },
       },
+      {
+        name: 'order',
+        in: 'query',
+        required: false,
+        description:
+          '`asc` (the default): oldest first. `desc`: newest first. `nextCursor` continues in the same order.',
+        schema: { type: 'string', enum: ['asc', 'desc'] },
+      },
     ],
     responses: {
       '200': {
@@ -4500,7 +5085,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
         },
       },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed cursor, `from`, `to`, or `outcome`.'),
+      '400': ErrorResponse('Malformed cursor, `from`, `to`, `outcome`, or `order`.'),
     },
   },
 
@@ -4835,6 +5420,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '204': { description: 'Removed (or already absent). No body.' },
       ...CommonAuthErrors,
+      '501': ErrorResponse(
+        "With authorization enforced, a runtime whose tenant-hierarchy binding can't change the membership together with its authorization tuple refuses with `authz-membership-unsupported`; nothing is changed.",
+      ),
     },
   },
   {
@@ -4869,6 +5457,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '404': ErrorResponse(
         'No membership for that (team, user) pair, or no such team under this tenant.',
       ),
+      '501': ErrorResponse(
+        "With authorization enforced, a runtime whose tenant-hierarchy binding can't change the membership together with its authorization tuple refuses with `authz-membership-unsupported`; nothing is changed.",
+      ),
     },
   },
 
@@ -5106,6 +5697,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '204': { description: 'Removed (or already absent). No body.' },
       ...CommonAuthErrors,
+      '501': ErrorResponse(
+        "With authorization enforced, a runtime whose tenant-hierarchy binding can't change the membership together with its authorization tuple refuses with `authz-membership-unsupported`; nothing is changed.",
+      ),
     },
   },
   {
@@ -5140,6 +5734,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '404': ErrorResponse(
         'No membership for that (project, user) pair, or no such project under this tenant.',
       ),
+      '501': ErrorResponse(
+        "With authorization enforced, a runtime whose tenant-hierarchy binding can't change the membership together with its authorization tuple refuses with `authz-membership-unsupported`; nothing is changed.",
+      ),
     },
   },