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

package/dist/openapi/operations.js

@@ -91,6 +91,13 @@ const RunReplaysQueryParam = {
     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 ConversationReplaysQueryParam = {
+    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 = {
     name: 'evalRunId',
     in: 'query',
@@ -98,6 +105,34 @@ const RunEvalRunIdQueryParam = {
     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 LiveProjectQueryParam = {
+    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 = {
+    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 = {
+    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 = {
+    name: 'promotionId',
+    in: 'path',
+    required: true,
+    schema: { type: 'string', format: 'uuid' },
+};
 const RunIncludeQueryParam = {
     name: 'include',
     in: 'query',
@@ -126,6 +161,20 @@ const LastEventIdParam = {
     description: 'Resume marker (`<runId>:<sequence>`). Server replays events with `sequence > lastSeen` before entering live-poll.',
     schema: { type: 'string' },
 };
+const GatePolicyIdPathParam = {
+    name: 'policyId',
+    in: 'path',
+    required: true,
+    description: 'The gate policy id.',
+    schema: { type: 'string' },
+};
+const GatePolicyVersionPathParam = {
+    name: 'version',
+    in: 'path',
+    required: true,
+    description: 'A semver version of the gate policy.',
+    schema: { type: 'string' },
+};
 const AgentIdPathParam = {
     name: 'agentId',
     in: 'path',
@@ -271,6 +320,34 @@ const SupervisorIdQueryParam = {
     required: false,
     schema: { type: 'string' },
 };
+const ObservationAgentVersionQueryParam = {
+    name: 'agentVersion',
+    in: 'query',
+    required: false,
+    description: 'Only the observations of this agent version (with `agentId`).',
+    schema: { type: 'string' },
+};
+const ObservationConversationIdQueryParam = {
+    name: 'conversationId',
+    in: 'query',
+    required: false,
+    description: 'Only the observations of turns in this conversation.',
+    schema: { type: 'string' },
+};
+const ObservationSinceQueryParam = {
+    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 = {
+    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 = {
     name: 'factId',
     in: 'path',
@@ -345,7 +422,7 @@ const ProvenanceAgentIdQueryParam = {
     name: 'agentId',
     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).',
+    description: "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' },
 };
 const ProvenanceCreatedAfterQueryParam = {
@@ -603,7 +680,7 @@ const PolicyKindFilterQueryParam = {
     name: 'kind',
     in: 'query',
     required: false,
-    description: 'Filter to policies of a single kind. Values: `access-control | model-routing | adapter-allowlist | rate-limit | retention | compliance`.',
+    description: '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' },
 };
 const PolicyNameFilterQueryParam = {
@@ -613,6 +690,28 @@ const PolicyNameFilterQueryParam = {
     description: 'Prefix match on `Policy.id`. Dotted namespaces are the natural filter shape.',
     schema: { type: 'string' },
 };
+// Admin plane — retention.
+const RetentionDomainQueryParam = {
+    name: 'domain',
+    in: 'query',
+    required: false,
+    description: 'Only this domain. Absent: every domain.',
+    schema: { $ref: '#/components/schemas/RetentionDomain' },
+};
+const RetentionPastGraceOnlyQueryParam = {
+    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 = {
+    name: 'domain',
+    in: 'path',
+    required: true,
+    description: 'The domain to sweep (not `*`).',
+    schema: { $ref: '#/components/schemas/RetentionDomain' },
+};
 // Admin plane — eval suites.
 const EvalSuiteIdPathParam = {
     name: 'suiteId',
@@ -887,8 +986,9 @@ export const OPERATIONS = [
                 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)."),
         },
     },
     {
@@ -1144,6 +1244,8 @@ export const OPERATIONS = [
             '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`)."),
         },
     },
     {
@@ -1326,6 +1428,7 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Reviewer registered.', schema: ref('Reviewer') },
             ...CommonMutationErrors,
+            '403': ErrorResponse('With authorization enforced, the caller is not an admin of the tenant.'),
         },
     },
     {
@@ -1342,6 +1445,7 @@ export const OPERATIONS = [
             '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.'),
         },
     },
     {
@@ -1429,10 +1533,15 @@ export const OPERATIONS = [
         parameters: [AgentIdPathParam, IdempotencyKeyParam],
         requestBody: { required: true, schema: ref('DeriveAgentVersionBody') },
         responses: {
+            '200': {
+                description: 'An active version already holds this definition and these pins (the same swap derived before, or a deploy that registered it): that version, unchanged.',
+                schema: ref('Agent'),
+            },
             '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`.'),
+            '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."),
+            '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`); 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`).'),
         },
     },
     {
@@ -1464,8 +1573,9 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Agent published.', schema: ref('PublishAgentResult') },
             ...CommonMutationErrors,
-            '400': ErrorResponse('Validation failed (see `details.issues`).'),
-            '409': ErrorResponse('Agent already registered at that (id, version).'),
+            '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`)."),
         },
     },
     {
@@ -1480,6 +1590,7 @@ export const OPERATIONS = [
         responses: {
             '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. 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.'),
         },
     },
@@ -1496,9 +1607,304 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Reinstated.', schema: ref('ReinstateAgentVersionResult') },
             ...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."),
             '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 ----------
     {
         method: 'get',
@@ -1583,8 +1989,9 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Flow published.', schema: ref('PublishFlowResult') },
             ...CommonMutationErrors,
-            '400': ErrorResponse('Validation failed (see `details.issues`).'),
-            '409': ErrorResponse('Flow already registered at that (id, version).'),
+            '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`)."),
         },
     },
     {
@@ -1599,6 +2006,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Unregistered.', schema: ref('UnregisterFlowResult') },
             ...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."),
             '404': ErrorResponse('No flow at that (id, version) under this tenant.'),
         },
     },
@@ -1615,6 +2023,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Reinstated.', schema: ref('ReinstateFlowVersionResult') },
             ...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."),
             '404': ErrorResponse('No flow at that (id, version) under this tenant.'),
         },
     },
@@ -1704,8 +2113,9 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Tool registered.', schema: ref('RegisterToolResult') },
             ...CommonMutationErrors,
-            '400': ErrorResponse('Validation failed (see `details.issues`).'),
-            '409': ErrorResponse('Tool already registered at that id.'),
+            '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`)."),
         },
     },
     {
@@ -1720,6 +2130,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Unregistered.', schema: ref('UnregisterToolResult') },
             ...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."),
             '404': ErrorResponse('No tool at that (id, version) under this tenant.'),
         },
     },
@@ -1736,6 +2147,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Reinstated.', schema: ref('ReinstateToolVersionResult') },
             ...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."),
             '404': ErrorResponse('No tool at that (id, version) under this tenant.'),
         },
     },
@@ -1792,8 +2204,9 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Guardrail registered.', schema: ref('RegisterGuardrailResult') },
             ...CommonMutationErrors,
-            '400': ErrorResponse('Validation failed (see `details.issues`).'),
-            '409': ErrorResponse('Guardrail already registered at that id.'),
+            '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`)."),
         },
     },
     {
@@ -1808,6 +2221,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Unregistered.', schema: ref('UnregisterGuardrailResult') },
             ...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."),
             '404': ErrorResponse('No guardrail with that id under this tenant.'),
         },
     },
@@ -1818,7 +2232,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/conversations',
         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.",
+        description: "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: [
@@ -1828,6 +2242,7 @@ export const OPERATIONS = [
             ScopeIdQueryParam,
             AgentIdQueryParam,
             ConversationStatusQueryParam,
+            ConversationReplaysQueryParam,
         ],
         responses: {
             '200': {
@@ -1850,6 +2265,7 @@ export const OPERATIONS = [
         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.'),
         },
     },
@@ -1885,6 +2301,7 @@ export const OPERATIONS = [
                 schema: ref('Conversation'),
             },
             ...CommonMutationErrors,
+            '400': ErrorResponse('`conversationId` is not a conversation id (a UUID).'),
             '404': ErrorResponse('No conversation with that id under this tenant.'),
         },
     },
@@ -1904,7 +2321,7 @@ export const OPERATIONS = [
                 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.'),
         },
     },
@@ -2361,7 +2778,11 @@ export const OPERATIONS = [
             CursorQueryParam,
             ObservationStatusQueryParam,
             AgentIdQueryParam,
+            ObservationAgentVersionQueryParam,
             SupervisorIdQueryParam,
+            ObservationConversationIdQueryParam,
+            ObservationSinceQueryParam,
+            ObservationUntilQueryParam,
         ],
         responses: {
             '200': {
@@ -2509,7 +2930,7 @@ export const OPERATIONS = [
             '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.'),
+            '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.'),
         },
@@ -3044,7 +3465,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/policies',
         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).",
+        description: "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],
@@ -3053,7 +3474,7 @@ export const OPERATIONS = [
             '201': { description: 'Policy published.', schema: ref('PublishPolicyResult') },
             ...CommonMutationErrors,
             '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.'),
         },
     },
     {
@@ -3085,6 +3506,65 @@ export const OPERATIONS = [
             '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.'),
         },
     },
     // ---------- eval suites (admin plane) ----------
@@ -3175,8 +3655,9 @@ export const OPERATIONS = [
         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`)."),
         },
     },
     {
@@ -3193,10 +3674,11 @@ export const OPERATIONS = [
         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`)."),
         },
     },
     {
@@ -3336,9 +3818,10 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Published.', schema: ref('PublishBlockResult') },
             ...CommonMutationErrors,
-            '400': ErrorResponse('`validation-failed` (see `details.issues`), or an unknown `projectId`.'),
+            '400': ErrorResponse("`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`)."),
         },
     },
     {
@@ -3389,8 +3872,8 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Eval run started.', schema: ref('StartEvalRunResult') },
             ...CommonMutationErrors,
-            '400': ErrorResponse('Malformed body (both / neither of `agentRef` / `flowRef`, dispatcher-input-invalid).'),
-            '404': ErrorResponse('No eval suite with that id under this tenant.'),
+            '400': ErrorResponse("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`).'),
             '422': ErrorResponse('No dispatcher registered for the suite kind.'),
         },
     },
@@ -3734,6 +4217,7 @@ export const OPERATIONS = [
                 schema: ref('DeploymentRecord'),
             },
             ...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."),
             '400': ErrorResponse('Signature invalid, image unverifiable, or deployment-validation-failed with per-primitive `details[]`.'),
             '403': ErrorResponse("Signer key not on the tenant's trust list."),
         },
@@ -3943,7 +4427,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/audit/authz',
         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.',
+        description: '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: [
@@ -4005,6 +4489,13 @@ export const OPERATIONS = [
                 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': {
@@ -4051,7 +4542,7 @@ export const OPERATIONS = [
                 },
             },
             ...CommonAuthErrors,
-            '400': ErrorResponse('Malformed cursor, `from`, `to`, or `outcome`.'),
+            '400': ErrorResponse('Malformed cursor, `from`, `to`, `outcome`, or `order`.'),
         },
     },
     // ---------- orgs ----------
@@ -4216,6 +4707,7 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Team created.', schema: ref('CreateResourceResult') },
             ...CommonMutationErrors,
+            '404': ErrorResponse('org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).'),
         },
     },
     {
@@ -4263,7 +4755,7 @@ export const OPERATIONS = [
         responses: {
             '204': { description: 'Updated. No body.' },
             ...CommonMutationErrors,
-            '404': ErrorResponse('No team with that id under this tenant.'),
+            '404': ErrorResponse('team-not-found: no team with that id under this tenant; or org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).'),
         },
     },
     {
@@ -4372,6 +4864,7 @@ export const OPERATIONS = [
         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."),
         },
     },
     {
@@ -4404,6 +4897,7 @@ export const OPERATIONS = [
             '204': { description: 'Role updated. No body.' },
             ...CommonMutationErrors,
             '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."),
         },
     },
     // ---------- projects ----------
@@ -4469,6 +4963,7 @@ export const OPERATIONS = [
         responses: {
             '201': { description: 'Project created.', schema: ref('CreateResourceResult') },
             ...CommonMutationErrors,
+            '404': ErrorResponse('org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).'),
         },
     },
     {
@@ -4517,7 +5012,7 @@ export const OPERATIONS = [
         responses: {
             '204': { description: 'Updated. No body.' },
             ...CommonMutationErrors,
-            '404': ErrorResponse('No project with that id under this tenant.'),
+            '404': ErrorResponse('project-not-found: no project with that id under this tenant; or org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).'),
         },
     },
     {
@@ -4629,6 +5124,7 @@ export const OPERATIONS = [
         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."),
         },
     },
     {
@@ -4661,6 +5157,7 @@ export const OPERATIONS = [
             '204': { description: 'Role updated. No body.' },
             ...CommonMutationErrors,
             '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."),
         },
     },
     // ---------- tenant ----------