// SPDX-License-Identifier: Apache-2.0
// Copyright 2024-2026 Vorion LLC
/**
 * OpenAPI 3.1 specification for the INTENT module
 */
export const intentOpenApiSpec = {
    openapi: '3.1.0',
    info: {
        title: 'Vorion INTENT Module API',
        version: '1.0.0',
        description: `
# INTENT Module API

The INTENT module provides production-grade goal processing with validation,
persistence, audit events, and human-in-the-loop escalation workflows.

## API Versioning

This API uses URL-based versioning. All endpoints are prefixed with the API version:
- **Current version**: \`/api/v1\`

### Version Negotiation

1. **URL Path (Recommended)**: Include version in URL path: \`/api/v1/intents\`
2. **Accept Header (Fallback)**: Use \`application/vnd.vorion.v1+json\`

### Version Headers

All responses include:
- \`X-API-Version\`: The API version used for the request

### Deprecation Notices

When using deprecated versions or unversioned endpoints:
- \`Deprecation: true\` header indicates the endpoint is deprecated
- \`Sunset\` header indicates when the endpoint will be removed
- \`Warning\` header provides migration guidance

## Features

- **Intent Lifecycle Management**: Submit, track, cancel, and delete intents
- **Trust Gate Validation**: Automatic trust level verification for sensitive operations
- **Escalation Workflows**: Human-in-the-loop approval for high-risk intents
- **GDPR Compliance**: Soft delete and data erasure support
- **Audit Trail**: Cryptographically chained event history

## Authentication

All endpoints require Bearer token authentication. Include the JWT token in the
Authorization header:

\`\`\`
Authorization: Bearer <token>
\`\`\`

The token must contain:
- \`tenantId\`: The tenant context for multi-tenant isolation
- \`sub\`: The user/entity identifier
- \`jti\`: Token identifier for revocation support

## Rate Limiting

API requests are rate-limited per tenant. Rate limit headers are included in responses:
- \`X-RateLimit-Limit\`: Maximum requests per window
- \`X-RateLimit-Remaining\`: Remaining requests in current window
- \`X-RateLimit-Reset\`: Unix timestamp when the window resets
- \`Retry-After\`: Seconds to wait before retrying (on 429 responses)
`,
        contact: {
            name: 'Agent Anchor AI API Support',
            email: 'api-support@agentanchorai.com',
        },
        license: {
            name: 'MIT',
            url: 'https://opensource.org/licenses/MIT',
        },
    },
    servers: [
        {
            url: '/api/v1',
            description: 'API v1 base path',
        },
    ],
    tags: [
        {
            name: 'Intents',
            description: 'Intent lifecycle management operations',
        },
        {
            name: 'Escalations',
            description: 'Human-in-the-loop escalation workflows',
        },
        {
            name: 'Events',
            description: 'Intent event history and verification',
        },
        {
            name: 'GDPR',
            description: 'Data protection and erasure operations',
        },
        {
            name: 'Health',
            description: 'Service health and status endpoints',
        },
        {
            name: 'OpenAPI',
            description: 'API documentation endpoints',
        },
    ],
    paths: {
        '/intent': {
            post: {
                tags: ['Intents'],
                summary: 'Submit a new intent',
                operationId: 'submitIntent',
                description: `
Submit a new intent for processing. The intent will be validated, deduplicated,
and queued for evaluation.

**Trust Gate Validation**: If the intent type requires a specific trust level,
the request will be rejected if the caller's trust level is insufficient.

**Deduplication**: Identical intents (same goal, context, entity) submitted within
the deduplication window will return the existing intent instead of creating a duplicate.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                ],
                requestBody: {
                    required: true,
                    content: {
                        'application/json': {
                            schema: { $ref: '#/components/schemas/IntentSubmission' },
                            examples: {
                                basic: {
                                    summary: 'Basic intent submission',
                                    value: {
                                        entityId: '123e4567-e89b-12d3-a456-426614174000',
                                        goal: 'Send notification to user',
                                        context: {
                                            userId: 'user-456',
                                            message: 'Your order has shipped',
                                        },
                                    },
                                },
                                withPriority: {
                                    summary: 'High priority intent',
                                    value: {
                                        entityId: '123e4567-e89b-12d3-a456-426614174000',
                                        goal: 'Process urgent payment',
                                        context: {
                                            amount: 1000,
                                            currency: 'USD',
                                        },
                                        intentType: 'payment-processing',
                                        priority: 9,
                                        idempotencyKey: 'payment-order-789',
                                    },
                                },
                            },
                        },
                    },
                },
                responses: {
                    '202': {
                        description: 'Intent accepted for processing',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/Intent' },
                                example: {
                                    id: '550e8400-e29b-41d4-a716-446655440000',
                                    tenantId: 'tenant-123',
                                    entityId: '123e4567-e89b-12d3-a456-426614174000',
                                    goal: 'Send notification to user',
                                    context: { userId: 'user-456', message: 'Your order has shipped' },
                                    metadata: {},
                                    status: 'pending',
                                    priority: 0,
                                    createdAt: '2024-01-15T10:30:00.000Z',
                                    updatedAt: '2024-01-15T10:30:00.000Z',
                                },
                            },
                        },
                    },
                    '400': { $ref: '#/components/responses/BadRequest' },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
            get: {
                tags: ['Intents'],
                summary: 'List intents',
                operationId: 'listIntents',
                description: `
List intents for the current tenant with optional filtering and pagination.

Results are ordered by creation time (newest first) and use cursor-based
pagination for efficient traversal of large result sets.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/EntityIdFilter' },
                    { $ref: '#/components/parameters/StatusFilter' },
                    { $ref: '#/components/parameters/Limit' },
                    { $ref: '#/components/parameters/Cursor' },
                ],
                responses: {
                    '200': {
                        description: 'List of intents',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/IntentListResponse' },
                            },
                        },
                    },
                    '400': { $ref: '#/components/responses/BadRequest' },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/{id}': {
            get: {
                tags: ['Intents'],
                summary: 'Get intent by ID',
                operationId: 'getIntent',
                description: `
Retrieve a specific intent by its ID, including events and evaluations.

The response includes the full intent object along with:
- Event history (most recent first)
- Evaluation records (trust gate, basis, decision stages)
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                ],
                responses: {
                    '200': {
                        description: 'Intent details with events and evaluations',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/IntentWithEvents' },
                            },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
            delete: {
                tags: ['Intents', 'GDPR'],
                summary: 'Delete intent (GDPR soft delete)',
                operationId: 'deleteIntent',
                description: `
Soft delete an intent for GDPR compliance. The intent record is marked as deleted
and sensitive data (context, metadata) is cleared, but the audit trail is preserved.

After soft deletion:
- The intent will not appear in list queries
- The intent ID remains valid for audit purposes
- Context and metadata fields are emptied
- The \`deletedAt\` timestamp is set

**Note**: Permanently deleted after the retention period (configurable).
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                ],
                responses: {
                    '204': {
                        description: 'Intent successfully deleted',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/{id}/cancel': {
            post: {
                tags: ['Intents'],
                summary: 'Cancel an intent',
                operationId: 'cancelIntent',
                description: `
Cancel an in-flight intent. Only intents in cancellable states can be cancelled:
- \`pending\`
- \`evaluating\`
- \`escalated\`

Intents in terminal states (\`completed\`, \`failed\`, \`cancelled\`, \`approved\`, \`denied\`)
cannot be cancelled.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                ],
                requestBody: {
                    required: true,
                    content: {
                        'application/json': {
                            schema: { $ref: '#/components/schemas/CancelIntentRequest' },
                            example: {
                                reason: 'User requested cancellation',
                            },
                        },
                    },
                },
                responses: {
                    '200': {
                        description: 'Intent cancelled successfully',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/Intent' },
                            },
                        },
                    },
                    '400': { $ref: '#/components/responses/BadRequest' },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/{id}/escalate': {
            post: {
                tags: ['Intents', 'Escalations'],
                summary: 'Escalate an intent',
                operationId: 'escalateIntent',
                description: `
Create an escalation for an intent that requires human approval.

This endpoint is typically called by the evaluation pipeline when a policy
rule triggers an escalation action, but can also be invoked manually.

The escalation will be routed to the specified recipient(s) and will
timeout if not resolved within the specified duration.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                ],
                requestBody: {
                    required: true,
                    content: {
                        'application/json': {
                            schema: { $ref: '#/components/schemas/EscalateIntentRequest' },
                            example: {
                                reason: 'High-value transaction requires manual approval',
                                reasonCategory: 'high_risk',
                                escalatedTo: 'finance-approvers',
                                timeout: 'PT4H',
                            },
                        },
                    },
                },
                responses: {
                    '201': {
                        description: 'Escalation created',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/Escalation' },
                            },
                        },
                    },
                    '400': { $ref: '#/components/responses/BadRequest' },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/{id}/events': {
            get: {
                tags: ['Events'],
                summary: 'Get intent events',
                operationId: 'getIntentEvents',
                description: `
Retrieve the event history for an intent. Events are ordered by occurrence time
(most recent first) and include cryptographic hashes for tamper detection.

Each event contains:
- Event type (e.g., \`intent.submitted\`, \`intent.status.changed\`)
- Event payload with relevant data
- Occurrence timestamp
- Hash and previous hash for chain integrity verification
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                    {
                        name: 'limit',
                        in: 'query',
                        description: 'Maximum number of events to return',
                        schema: {
                            type: 'integer',
                            minimum: 1,
                            maximum: 100,
                            default: 10,
                        },
                    },
                ],
                responses: {
                    '200': {
                        description: 'List of intent events',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: {
                                    type: 'object',
                                    properties: {
                                        data: {
                                            type: 'array',
                                            items: { $ref: '#/components/schemas/IntentEvent' },
                                        },
                                    },
                                    required: ['data'],
                                },
                            },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/{id}/verify': {
            get: {
                tags: ['Events'],
                summary: 'Verify intent event chain',
                operationId: 'verifyIntentEventChain',
                description: `
Verify the cryptographic integrity of an intent's event chain.

This endpoint validates that:
- Each event's hash matches its content
- The chain of previous hashes is unbroken
- No events have been tampered with

Returns verification status and details about any chain breaks.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                ],
                responses: {
                    '200': {
                        description: 'Chain verification result',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/ChainVerificationResult' },
                                examples: {
                                    valid: {
                                        summary: 'Valid chain',
                                        value: { valid: true },
                                    },
                                    invalid: {
                                        summary: 'Broken chain',
                                        value: {
                                            valid: false,
                                            invalidAt: 3,
                                            error: 'Chain broken at event 3: hash mismatch',
                                        },
                                    },
                                },
                            },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/{id}/escalation': {
            get: {
                tags: ['Escalations'],
                summary: 'Get escalation for intent',
                operationId: 'getIntentEscalation',
                description: 'Get the most recent escalation associated with an intent.',
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/IntentId' },
                ],
                responses: {
                    '200': {
                        description: 'Escalation details',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/Escalation' },
                            },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/escalation/{id}/resolve': {
            put: {
                tags: ['Escalations'],
                summary: 'Resolve an escalation',
                operationId: 'resolveEscalation',
                description: `
Resolve an escalation by approving or rejecting it.

**Authorization**: Only authorized users can resolve escalations:
- Admin roles (\`admin\`, \`tenant:admin\`, \`escalation:admin\`)
- Direct assignees (escalatedTo matches user ID)
- Verified group members (database-verified group membership)
- Explicitly assigned approvers

The resolution will update both the escalation and the associated intent's status.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    { $ref: '#/components/parameters/EscalationId' },
                ],
                requestBody: {
                    required: true,
                    content: {
                        'application/json': {
                            schema: { $ref: '#/components/schemas/ResolveEscalationRequest' },
                            examples: {
                                approve: {
                                    summary: 'Approve escalation',
                                    value: {
                                        resolution: 'approved',
                                        notes: 'Verified by finance team - amount within authorized limits',
                                    },
                                },
                                reject: {
                                    summary: 'Reject escalation',
                                    value: {
                                        resolution: 'rejected',
                                        notes: 'Transaction violates policy - see ticket #1234',
                                    },
                                },
                            },
                        },
                    },
                },
                responses: {
                    '200': {
                        description: 'Escalation resolved',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/Escalation' },
                            },
                        },
                    },
                    '400': { $ref: '#/components/responses/BadRequest' },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/health': {
            get: {
                tags: ['Health'],
                summary: 'Intent service health check',
                operationId: 'getIntentHealth',
                description: `
Check the health status of the intent service and its dependencies.

This endpoint does not require authentication and is suitable for
load balancer health checks.
`,
                responses: {
                    '200': {
                        description: 'Service is healthy',
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/HealthResponse' },
                                example: {
                                    status: 'healthy',
                                    timestamp: '2024-01-15T10:30:00.000Z',
                                    checks: {
                                        database: { status: 'ok', latencyMs: 5 },
                                        redis: { status: 'ok', latencyMs: 2 },
                                        queues: { status: 'ok' },
                                    },
                                },
                            },
                        },
                    },
                    '503': {
                        description: 'Service is unhealthy',
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/HealthResponse' },
                                example: {
                                    status: 'unhealthy',
                                    timestamp: '2024-01-15T10:30:00.000Z',
                                    checks: {
                                        database: { status: 'error', error: 'Connection timeout' },
                                        redis: { status: 'ok', latencyMs: 2 },
                                        queues: { status: 'ok' },
                                    },
                                },
                            },
                        },
                    },
                },
            },
        },
        '/intent/openapi.json': {
            get: {
                tags: ['OpenAPI'],
                summary: 'Get OpenAPI specification',
                operationId: 'getOpenApiSpec',
                description: 'Returns the OpenAPI 3.1 specification for the INTENT module API.',
                responses: {
                    '200': {
                        description: 'OpenAPI specification',
                        content: {
                            'application/json': {
                                schema: {
                                    type: 'object',
                                    description: 'OpenAPI 3.1 specification document',
                                },
                            },
                        },
                    },
                },
            },
        },
        '/intent/gdpr/export/{entityId}': {
            get: {
                tags: ['GDPR'],
                summary: 'Export entity data (GDPR)',
                operationId: 'exportEntityData',
                description: `
Export all data associated with an entity for GDPR data portability requests.

Returns all intents, events, evaluations, and escalations associated with the
specified entity in a structured format.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    {
                        name: 'entityId',
                        in: 'path',
                        required: true,
                        description: 'Entity UUID to export data for',
                        schema: {
                            type: 'string',
                            format: 'uuid',
                        },
                    },
                ],
                responses: {
                    '200': {
                        description: 'Entity data export',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/GdprDataExport' },
                            },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
        '/intent/gdpr/erase/{entityId}': {
            delete: {
                tags: ['GDPR'],
                summary: 'Erase entity data (GDPR)',
                operationId: 'eraseEntityData',
                description: `
Erase all data associated with an entity for GDPR right-to-erasure requests.

This operation:
- Soft deletes all intents for the entity
- Clears sensitive context and metadata
- Preserves minimal audit trail for compliance

**Note**: Some data may be retained for legal/compliance purposes as documented
in your data retention policy.
`,
                security: [{ bearerAuth: [] }],
                parameters: [
                    { $ref: '#/components/parameters/TenantId' },
                    {
                        name: 'entityId',
                        in: 'path',
                        required: true,
                        description: 'Entity UUID to erase data for',
                        schema: {
                            type: 'string',
                            format: 'uuid',
                        },
                    },
                ],
                responses: {
                    '200': {
                        description: 'Entity data erased',
                        headers: {
                            'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
                            'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
                            'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
                        },
                        content: {
                            'application/json': {
                                schema: { $ref: '#/components/schemas/GdprEraseResponse' },
                                example: {
                                    entityId: '123e4567-e89b-12d3-a456-426614174000',
                                    intentsErased: 15,
                                    erasedAt: '2024-01-15T10:30:00.000Z',
                                },
                            },
                        },
                    },
                    '401': { $ref: '#/components/responses/Unauthorized' },
                    '403': { $ref: '#/components/responses/Forbidden' },
                    '404': { $ref: '#/components/responses/NotFound' },
                    '429': { $ref: '#/components/responses/TooManyRequests' },
                    '500': { $ref: '#/components/responses/InternalError' },
                },
            },
        },
    },
    components: {
        securitySchemes: {
            bearerAuth: {
                type: 'http',
                scheme: 'bearer',
                bearerFormat: 'JWT',
                description: `
JWT token for authentication. The token must contain:
- \`tenantId\`: Tenant identifier for multi-tenant isolation
- \`sub\`: User/entity identifier
- \`jti\`: Token identifier for revocation support
- \`exp\`: Expiration timestamp
`,
            },
        },
        parameters: {
            TenantId: {
                name: 'X-Tenant-ID',
                in: 'header',
                description: 'Tenant identifier (extracted from JWT if not provided)',
                schema: {
                    type: 'string',
                },
            },
            IntentId: {
                name: 'id',
                in: 'path',
                required: true,
                description: 'Intent UUID',
                schema: {
                    type: 'string',
                    format: 'uuid',
                },
            },
            EscalationId: {
                name: 'id',
                in: 'path',
                required: true,
                description: 'Escalation UUID',
                schema: {
                    type: 'string',
                    format: 'uuid',
                },
            },
            EntityIdFilter: {
                name: 'entityId',
                in: 'query',
                description: 'Filter by entity ID',
                schema: {
                    type: 'string',
                    format: 'uuid',
                },
            },
            StatusFilter: {
                name: 'status',
                in: 'query',
                description: 'Filter by intent status',
                schema: {
                    $ref: '#/components/schemas/IntentStatus',
                },
            },
            Limit: {
                name: 'limit',
                in: 'query',
                description: 'Maximum number of results to return',
                schema: {
                    type: 'integer',
                    minimum: 1,
                    maximum: 100,
                    default: 50,
                },
            },
            Cursor: {
                name: 'cursor',
                in: 'query',
                description: 'Pagination cursor (last item ID from previous page)',
                schema: {
                    type: 'string',
                    format: 'uuid',
                },
            },
        },
        headers: {
            'X-RateLimit-Limit': {
                description: 'Maximum number of requests allowed in the current time window',
                schema: {
                    type: 'integer',
                },
            },
            'X-RateLimit-Remaining': {
                description: 'Number of requests remaining in the current time window',
                schema: {
                    type: 'integer',
                },
            },
            'X-RateLimit-Reset': {
                description: 'Unix timestamp when the rate limit window resets',
                schema: {
                    type: 'integer',
                },
            },
        },
        schemas: {
            IntentSubmission: {
                type: 'object',
                description: 'Request body for submitting a new intent',
                required: ['entityId', 'goal', 'context'],
                properties: {
                    entityId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'UUID of the entity (agent, user, service) submitting the intent',
                    },
                    goal: {
                        type: 'string',
                        minLength: 1,
                        maxLength: 1024,
                        description: 'Description of what the intent aims to achieve',
                    },
                    context: {
                        type: 'object',
                        additionalProperties: true,
                        description: 'Contextual data for intent evaluation (max 64KB)',
                    },
                    metadata: {
                        type: 'object',
                        additionalProperties: true,
                        description: 'Optional metadata for tracking and filtering',
                    },
                    intentType: {
                        type: 'string',
                        minLength: 1,
                        maxLength: 128,
                        description: 'Type classification for routing and policy matching',
                    },
                    priority: {
                        type: 'integer',
                        minimum: 0,
                        maximum: 9,
                        default: 0,
                        description: 'Priority level (0=lowest, 9=highest)',
                    },
                    idempotencyKey: {
                        type: 'string',
                        maxLength: 128,
                        description: 'Client-provided key for idempotent submissions',
                    },
                },
            },
            Intent: {
                type: 'object',
                description: 'An intent representing a goal to be governed',
                required: ['id', 'tenantId', 'entityId', 'goal', 'context', 'metadata', 'status', 'createdAt', 'updatedAt'],
                properties: {
                    id: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Unique intent identifier',
                    },
                    tenantId: {
                        type: 'string',
                        description: 'Tenant identifier',
                    },
                    entityId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Entity that submitted the intent',
                    },
                    goal: {
                        type: 'string',
                        description: 'Intent goal description',
                    },
                    intentType: {
                        type: 'string',
                        // OpenAPI 3.1 uses type arrays for nullable
                        description: 'Intent type classification',
                    },
                    context: {
                        type: 'object',
                        additionalProperties: true,
                        description: 'Intent context data',
                    },
                    metadata: {
                        type: 'object',
                        additionalProperties: true,
                        description: 'Intent metadata',
                    },
                    priority: {
                        type: 'integer',
                        description: 'Priority level (0-9)',
                    },
                    status: {
                        $ref: '#/components/schemas/IntentStatus',
                    },
                    trustSnapshot: {
                        type: 'object',
                        // OpenAPI 3.1 uses type arrays for nullable
                        additionalProperties: true,
                        description: 'Trust state snapshot at submission time',
                    },
                    trustLevel: {
                        type: 'integer',
                        // OpenAPI 3.1 uses type arrays for nullable
                        minimum: 0,
                        maximum: 4,
                        description: 'Trust level (L0-L4)',
                    },
                    trustScore: {
                        type: 'integer',
                        // OpenAPI 3.1 uses type arrays for nullable
                        minimum: 0,
                        maximum: 1000,
                        description: 'Trust score (0-1000)',
                    },
                    createdAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Creation timestamp',
                    },
                    updatedAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Last update timestamp',
                    },
                    deletedAt: {
                        type: ['string', 'null'],
                        format: 'date-time',
                        description: 'Soft delete timestamp (GDPR)',
                    },
                    cancellationReason: {
                        type: ['string', 'null'],
                        description: 'Reason for cancellation if cancelled',
                    },
                },
            },
            IntentStatus: {
                type: 'string',
                enum: ['pending', 'evaluating', 'approved', 'denied', 'escalated', 'executing', 'completed', 'failed', 'cancelled'],
                description: `Intent lifecycle status:
- \`pending\`: Awaiting evaluation
- \`evaluating\`: Being evaluated by the policy engine
- \`approved\`: Approved for execution
- \`denied\`: Denied by policy
- \`escalated\`: Awaiting human approval
- \`executing\`: Currently executing
- \`completed\`: Successfully completed
- \`failed\`: Execution failed
- \`cancelled\`: Cancelled by user or system`,
            },
            IntentWithEvents: {
                allOf: [
                    { $ref: '#/components/schemas/Intent' },
                    {
                        type: 'object',
                        properties: {
                            events: {
                                type: 'array',
                                items: { $ref: '#/components/schemas/IntentEvent' },
                                description: 'Recent events for this intent',
                            },
                            evaluations: {
                                type: 'array',
                                items: { $ref: '#/components/schemas/IntentEvaluation' },
                                description: 'Evaluation records for this intent',
                            },
                        },
                    },
                ],
            },
            IntentEvent: {
                type: 'object',
                description: 'An event in the intent lifecycle',
                required: ['id', 'intentId', 'eventType', 'payload', 'occurredAt'],
                properties: {
                    id: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Event identifier',
                    },
                    intentId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Associated intent ID',
                    },
                    eventType: {
                        type: 'string',
                        description: 'Event type (e.g., intent.submitted, intent.approved)',
                    },
                    payload: {
                        type: 'object',
                        additionalProperties: true,
                        description: 'Event payload data',
                    },
                    occurredAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Event occurrence timestamp',
                    },
                    hash: {
                        type: 'string',
                        // OpenAPI 3.1 uses type arrays for nullable
                        description: 'SHA-256 hash for tamper detection',
                    },
                    previousHash: {
                        type: 'string',
                        // OpenAPI 3.1 uses type arrays for nullable
                        description: 'Previous event hash for chain integrity',
                    },
                },
            },
            IntentEvaluation: {
                type: 'object',
                description: 'An evaluation record for an intent',
                required: ['id', 'intentId', 'tenantId', 'result', 'createdAt'],
                properties: {
                    id: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Evaluation identifier',
                    },
                    intentId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Associated intent ID',
                    },
                    tenantId: {
                        type: 'string',
                        description: 'Tenant identifier',
                    },
                    result: {
                        $ref: '#/components/schemas/EvaluationPayload',
                    },
                    createdAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Evaluation timestamp',
                    },
                },
            },
            EvaluationPayload: {
                type: 'object',
                description: 'Evaluation result data by stage',
                required: ['stage'],
                properties: {
                    stage: {
                        type: 'string',
                        enum: ['trust-snapshot', 'trust-gate', 'basis', 'decision', 'error', 'cancelled'],
                        description: 'Evaluation stage',
                    },
                },
                discriminator: {
                    propertyName: 'stage',
                },
                oneOf: [
                    {
                        type: 'object',
                        properties: {
                            stage: { type: 'string', const: 'trust-snapshot' },
                            result: { type: 'object' }, // nullable in 3.0
                        },
                    },
                    {
                        type: 'object',
                        properties: {
                            stage: { type: 'string', const: 'trust-gate' },
                            passed: { type: 'boolean' },
                            requiredLevel: { type: 'integer' },
                            actualLevel: { type: 'integer' },
                        },
                    },
                    {
                        type: 'object',
                        properties: {
                            stage: { type: 'string', const: 'basis' },
                            evaluation: { type: 'object' },
                            namespace: { type: 'string' },
                        },
                    },
                    {
                        type: 'object',
                        properties: {
                            stage: { type: 'string', const: 'decision' },
                            decision: { type: 'object' },
                        },
                    },
                    {
                        type: 'object',
                        properties: {
                            stage: { type: 'string', const: 'error' },
                            error: {
                                type: 'object',
                                properties: {
                                    message: { type: 'string' },
                                    timestamp: { type: 'string', format: 'date-time' },
                                },
                            },
                        },
                    },
                    {
                        type: 'object',
                        properties: {
                            stage: { type: 'string', const: 'cancelled' },
                            reason: { type: 'string' },
                            cancelledBy: { type: 'string' },
                        },
                    },
                ],
            },
            IntentListResponse: {
                type: 'object',
                required: ['data', 'pagination'],
                properties: {
                    data: {
                        type: 'array',
                        items: { $ref: '#/components/schemas/Intent' },
                    },
                    pagination: {
                        type: 'object',
                        properties: {
                            nextCursor: {
                                type: 'string',
                                format: 'uuid',
                                description: 'Cursor for next page',
                            },
                            hasMore: {
                                type: 'boolean',
                                description: 'Whether more results are available',
                            },
                        },
                    },
                },
            },
            CancelIntentRequest: {
                type: 'object',
                required: ['reason'],
                properties: {
                    reason: {
                        type: 'string',
                        minLength: 1,
                        maxLength: 500,
                        description: 'Reason for cancellation',
                    },
                },
            },
            EscalateIntentRequest: {
                type: 'object',
                required: ['reason', 'reasonCategory', 'escalatedTo'],
                properties: {
                    reason: {
                        type: 'string',
                        description: 'Human-readable reason for escalation',
                    },
                    reasonCategory: {
                        $ref: '#/components/schemas/EscalationReasonCategory',
                    },
                    escalatedTo: {
                        type: 'string',
                        description: 'User ID, role, or group to escalate to',
                    },
                    timeout: {
                        type: 'string',
                        pattern: '^P(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$',
                        default: 'PT1H',
                        description: 'ISO 8601 duration for escalation timeout',
                    },
                    context: {
                        type: 'object',
                        additionalProperties: true,
                        description: 'Additional context for the approver',
                    },
                },
            },
            Escalation: {
                type: 'object',
                description: 'An escalation requiring human approval',
                required: ['id', 'intentId', 'tenantId', 'reason', 'reasonCategory', 'escalatedTo', 'status', 'timeout', 'timeoutAt', 'slaBreached', 'createdAt', 'updatedAt'],
                properties: {
                    id: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Escalation identifier',
                    },
                    intentId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Associated intent ID',
                    },
                    tenantId: {
                        type: 'string',
                        description: 'Tenant identifier',
                    },
                    reason: {
                        type: 'string',
                        description: 'Reason for escalation',
                    },
                    reasonCategory: {
                        $ref: '#/components/schemas/EscalationReasonCategory',
                    },
                    escalatedTo: {
                        type: 'string',
                        description: 'Target user, role, or group',
                    },
                    escalatedBy: {
                        type: 'string',
                        description: 'Entity that created the escalation',
                    },
                    status: {
                        $ref: '#/components/schemas/EscalationStatus',
                    },
                    resolution: {
                        type: ['object', 'null'],
                        properties: {
                            resolvedBy: { type: 'string' },
                            resolvedAt: { type: 'string', format: 'date-time' },
                            notes: { type: 'string' },
                        },
                    },
                    timeout: {
                        type: 'string',
                        description: 'ISO 8601 duration',
                    },
                    timeoutAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Timeout deadline',
                    },
                    acknowledgedAt: {
                        type: 'string',
                        format: 'date-time',
                        // OpenAPI 3.1 uses type arrays for nullable
                        description: 'When the escalation was acknowledged',
                    },
                    slaBreached: {
                        type: 'boolean',
                        description: 'Whether the SLA was breached',
                    },
                    context: {
                        type: 'object',
                        // OpenAPI 3.1 uses type arrays for nullable
                        additionalProperties: true,
                        description: 'Escalation context',
                    },
                    metadata: {
                        type: 'object',
                        // OpenAPI 3.1 uses type arrays for nullable
                        additionalProperties: true,
                        description: 'Escalation metadata',
                    },
                    createdAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Creation timestamp',
                    },
                    updatedAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Last update timestamp',
                    },
                },
            },
            EscalationStatus: {
                type: 'string',
                enum: ['pending', 'acknowledged', 'approved', 'rejected', 'timeout', 'cancelled'],
                description: `Escalation status:
- \`pending\`: Awaiting acknowledgment
- \`acknowledged\`: Acknowledged by approver
- \`approved\`: Approved by approver
- \`rejected\`: Rejected by approver
- \`timeout\`: Timed out without resolution
- \`cancelled\`: Cancelled`,
            },
            EscalationReasonCategory: {
                type: 'string',
                enum: ['trust_insufficient', 'high_risk', 'policy_violation', 'manual_review', 'constraint_escalate'],
                description: `Reason for escalation:
- \`trust_insufficient\`: Entity trust level too low
- \`high_risk\`: High-risk operation detected
- \`policy_violation\`: Policy rule triggered escalation
- \`manual_review\`: Requires manual review
- \`constraint_escalate\`: Constraint evaluation triggered escalation`,
            },
            ResolveEscalationRequest: {
                type: 'object',
                required: ['resolution'],
                properties: {
                    resolution: {
                        type: 'string',
                        enum: ['approved', 'rejected'],
                        description: 'Resolution decision',
                    },
                    notes: {
                        type: 'string',
                        maxLength: 1000,
                        description: 'Optional notes explaining the decision',
                    },
                },
            },
            ChainVerificationResult: {
                type: 'object',
                description: 'Result of cryptographic event chain verification',
                required: ['valid'],
                properties: {
                    valid: {
                        type: 'boolean',
                        description: 'Whether the chain is valid',
                    },
                    invalidAt: {
                        type: 'integer',
                        description: 'Index of first invalid event (if invalid)',
                    },
                    error: {
                        type: 'string',
                        description: 'Error description (if invalid)',
                    },
                },
            },
            HealthResponse: {
                type: 'object',
                description: 'Health check response with service status and dependency checks',
                required: ['status', 'timestamp'],
                properties: {
                    status: {
                        type: 'string',
                        enum: ['healthy', 'degraded', 'unhealthy'],
                        description: 'Overall health status',
                    },
                    timestamp: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Health check timestamp',
                    },
                    checks: {
                        type: 'object',
                        properties: {
                            database: {
                                type: 'object',
                                properties: {
                                    status: { type: 'string', enum: ['ok', 'error', 'timeout'] },
                                    latencyMs: { type: 'integer' },
                                    error: { type: 'string' },
                                },
                            },
                            redis: {
                                type: 'object',
                                properties: {
                                    status: { type: 'string', enum: ['ok', 'error', 'timeout'] },
                                    latencyMs: { type: 'integer' },
                                    error: { type: 'string' },
                                },
                            },
                            queues: {
                                type: 'object',
                                properties: {
                                    status: { type: 'string', enum: ['ok', 'error'] },
                                    error: { type: 'string' },
                                },
                            },
                        },
                    },
                },
            },
            GdprDataExport: {
                type: 'object',
                description: 'GDPR data export containing all data associated with an entity',
                required: ['entityId', 'exportedAt', 'intents'],
                properties: {
                    entityId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Entity identifier',
                    },
                    exportedAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Export timestamp',
                    },
                    intents: {
                        type: 'array',
                        items: { $ref: '#/components/schemas/IntentWithEvents' },
                        description: 'All intents for the entity',
                    },
                    escalations: {
                        type: 'array',
                        items: { $ref: '#/components/schemas/Escalation' },
                        description: 'All escalations for the entity',
                    },
                },
            },
            GdprEraseResponse: {
                type: 'object',
                description: 'Response from GDPR data erasure request with count of erased records',
                required: ['entityId', 'intentsErased', 'erasedAt'],
                properties: {
                    entityId: {
                        type: 'string',
                        format: 'uuid',
                        description: 'Entity identifier',
                    },
                    intentsErased: {
                        type: 'integer',
                        description: 'Number of intents erased',
                    },
                    erasedAt: {
                        type: 'string',
                        format: 'date-time',
                        description: 'Erasure timestamp',
                    },
                },
            },
            Error: {
                type: 'object',
                description: 'Standard error response wrapper',
                required: ['error'],
                properties: {
                    error: {
                        type: 'object',
                        required: ['code', 'message'],
                        properties: {
                            code: {
                                type: 'string',
                                description: 'Error code',
                            },
                            message: {
                                type: 'string',
                                description: 'Human-readable error message',
                            },
                            details: {
                                type: 'object',
                                additionalProperties: true,
                                description: 'Additional error details',
                            },
                        },
                    },
                },
            },
        },
        responses: {
            BadRequest: {
                description: 'Bad request - invalid input parameters',
                content: {
                    'application/json': {
                        schema: { $ref: '#/components/schemas/Error' },
                        example: {
                            error: {
                                code: 'VALIDATION_ERROR',
                                message: 'Invalid request body',
                                details: {
                                    field: 'entityId',
                                    issue: 'Must be a valid UUID',
                                },
                            },
                        },
                    },
                },
            },
            Unauthorized: {
                description: 'Unauthorized - missing or invalid authentication',
                content: {
                    'application/json': {
                        schema: { $ref: '#/components/schemas/Error' },
                        example: {
                            error: {
                                code: 'UNAUTHORIZED',
                                message: 'Authentication required',
                            },
                        },
                    },
                },
            },
            Forbidden: {
                description: 'Forbidden - insufficient permissions',
                content: {
                    'application/json': {
                        schema: { $ref: '#/components/schemas/Error' },
                        example: {
                            error: {
                                code: 'FORBIDDEN',
                                message: 'Insufficient permissions to access this resource',
                            },
                        },
                    },
                },
            },
            NotFound: {
                description: 'Resource not found',
                content: {
                    'application/json': {
                        schema: { $ref: '#/components/schemas/Error' },
                        example: {
                            error: {
                                code: 'NOT_FOUND',
                                message: 'Intent not found',
                            },
                        },
                    },
                },
            },
            TooManyRequests: {
                description: 'Rate limit exceeded',
                headers: {
                    'Retry-After': {
                        description: 'Seconds to wait before retrying',
                        schema: {
                            type: 'integer',
                        },
                    },
                },
                content: {
                    'application/json': {
                        schema: { $ref: '#/components/schemas/Error' },
                        example: {
                            error: {
                                code: 'RATE_LIMIT_EXCEEDED',
                                message: 'Too many requests, please retry after 60 seconds',
                            },
                        },
                    },
                },
            },
            InternalError: {
                description: 'Internal server error',
                content: {
                    'application/json': {
                        schema: { $ref: '#/components/schemas/Error' },
                        example: {
                            error: {
                                code: 'INTERNAL_ERROR',
                                message: 'An unexpected error occurred',
                            },
                        },
                    },
                },
            },
        },
    },
    security: [
        { bearerAuth: [] },
    ],
};
/**
 * Get the OpenAPI specification as a JSON string
 */
export function getOpenApiSpecJson() {
    return JSON.stringify(intentOpenApiSpec, null, 2);
}
/**
 * Get the OpenAPI specification object
 */
export function getOpenApiSpec() {
    return intentOpenApiSpec;
}
//# sourceMappingURL=openapi.js.map