openapi: 3.0.3
info:
  title: Tractatus Framework API
  version: 1.0.0
  description: |
    REST API for the Tractatus Framework - an architectural AI safety framework implementing structural governance for agentic AI systems.

    **Key Features:**
    - Instruction persistence and classification
    - Cross-reference validation (prevents training pattern override)
    - Boundary enforcement (separates technical from values decisions)
    - Context pressure monitoring (multi-factor session health)
    - Metacognitive verification (AI self-checks for scope creep)
    - Comprehensive audit logging

    **Security:** Most endpoints require JWT authentication with admin role.

    **Rate Limiting:**
    - Login endpoint: 5 attempts per 15 minutes per IP
    - General API: 100 requests per 15 minutes per IP
  contact:
    name: Tractatus Framework
    email: john.stroh.nz@pm.me
    url: https://agenticgovernance.digital
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: https://agenticgovernance.digital/api
    description: Production server
  - url: http://localhost:9000/api
    description: Development server

tags:
  - name: Authentication
    description: User authentication and session management
  - name: Documents
    description: Framework documentation endpoints
  - name: Governance Services
    description: Core AI safety framework services (admin only)
  - name: Audit
    description: Audit logging and analytics (admin only)
  - name: Admin
    description: System administration and moderation (admin only)

paths:
  # ==================== Authentication ====================
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: |
        Authenticate with email and password to receive a JWT access token.

        **Rate Limiting:** 5 attempts per 15 minutes per IP address.
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: admin@tractatus.local
                password:
                  type: string
                  format: password
                  example: tractatus2025
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  token:
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: Too many login attempts
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Too many login attempts from this IP. Please try again in 15 minutes.

  /auth/me:
    get:
      tags:
        - Authentication
      summary: Get current user
      description: Retrieve the authenticated user's profile information
      operationId: getCurrentUser
      security:
        - BearerAuth: []
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /auth/logout:
    post:
      tags:
        - Authentication
      summary: User logout
      description: |
        Logout the current user. This logs the event on the server side.
        The client should remove the JWT token from storage.
      operationId: logout
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Logged out successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==================== Documents ====================
  /documents:
    get:
      tags:
        - Documents
      summary: List all documents
      description: Retrieve a paginated list of all published framework documents
      operationId: listDocuments
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: quadrant
          in: query
          description: Filter by quadrant
          schema:
            type: string
            enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

    post:
      tags:
        - Documents
      summary: Create document (admin)
      description: Create a new framework document
      operationId: createDocument
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentInput'
      responses:
        '201':
          description: Document created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  document:
                    $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /documents/search:
    get:
      tags:
        - Documents
      summary: Search documents
      description: Full-text search across all framework documents
      operationId: searchDocuments
      parameters:
        - name: q
          in: query
          required: true
          description: Search query
          schema:
            type: string
            example: boundary enforcement
      responses:
        '200':
          description: Search results retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  count:
                    type: integer
                    example: 5

  /documents/archived:
    get:
      tags:
        - Documents
      summary: List archived documents
      description: Retrieve all archived documents
      operationId: listArchivedDocuments
      responses:
        '200':
          description: Archived documents retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'

  /documents/{identifier}:
    get:
      tags:
        - Documents
      summary: Get document by ID or slug
      description: Retrieve a single document by MongoDB ObjectId or URL slug
      operationId: getDocument
      parameters:
        - name: identifier
          in: path
          required: true
          description: Document ID or slug
          schema:
            type: string
            example: 27027-incident-analysis
      responses:
        '200':
          description: Document retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  document:
                    $ref: '#/components/schemas/Document'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Documents
      summary: Update document (admin)
      description: Update an existing document
      operationId: updateDocument
      security:
        - BearerAuth: []
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentInput'
      responses:
        '200':
          description: Document updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  document:
                    $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Documents
      summary: Delete document (admin)
      description: Delete a document (soft delete - archives it)
      operationId: deleteDocument
      security:
        - BearerAuth: []
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Document deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Document archived successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ==================== Governance Services ====================
  /governance:
    get:
      tags:
        - Governance Services
      summary: Get framework status
      description: |
        Retrieve the current status of all governance framework components.

        **Admin Only** - Contains sensitive runtime data.
      operationId: getFrameworkStatus
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Framework status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameworkStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /governance/status:
    get:
      tags:
        - Governance Services
      summary: Get detailed governance status
      description: |
        Retrieve detailed status including component health, instruction counts, and system uptime.

        **Admin Only**
      operationId: getDetailedGovernanceStatus
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Detailed status retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/FrameworkStatus'
                  - type: object
                    properties:
                      uptime:
                        type: number
                        description: Server uptime in seconds
                        example: 86400.5
                      environment:
                        type: string
                        example: production
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /governance/classify:
    post:
      tags:
        - Governance Services
      summary: Classify instruction
      description: |
        Test the InstructionPersistenceClassifier service by classifying a text instruction.

        Returns: quadrant, persistence level, temporal scope, verification requirements, reasoning, and confidence score.

        **Admin Only**
      operationId: classifyInstruction
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                  example: Always use MongoDB on port 27027
                context:
                  type: object
                  properties:
                    source:
                      type: string
                      example: user
                    session_id:
                      type: string
                      example: sess_123
      responses:
        '200':
          description: Classification successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  classification:
                    $ref: '#/components/schemas/InstructionClassification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /governance/validate:
    post:
      tags:
        - Governance Services
      summary: Validate action
      description: |
        Test the CrossReferenceValidator service by validating a proposed action against instruction history.

        Detects conflicts, training pattern overrides (27027 failure mode), and provides validation status.

        **Admin Only**
      operationId: validateAction
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: object
                  properties:
                    type:
                      type: string
                      example: database_change
                    description:
                      type: string
                      example: Change MongoDB port from 27027 to 27017
                    impact:
                      type: string
                      example: System configuration change
                context:
                  type: object
                  properties:
                    messages:
                      type: array
                      items:
                        type: object
      responses:
        '200':
          description: Validation complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  validation:
                    $ref: '#/components/schemas/ValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /governance/enforce:
    post:
      tags:
        - Governance Services
      summary: Test boundary enforcement
      description: |
        Test the BoundaryEnforcer service by checking if an action crosses into values territory.

        Identifies privacy, ethics, sovereignty, and strategic direction decisions requiring human approval.

        **Admin Only**
      operationId: enforceBounda ry
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: object
                  properties:
                    type:
                      type: string
                      example: content_moderation
                    description:
                      type: string
                      example: Decide which user comments to hide
                context:
                  type: object
      responses:
        '200':
          description: Boundary enforcement check complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  enforcement:
                    $ref: '#/components/schemas/BoundaryEnforcement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /governance/pressure:
    post:
      tags:
        - Governance Services
      summary: Analyze context pressure
      description: |
        Test the ContextPressureMonitor service by analyzing session health across multiple factors.

        Returns pressure level (NORMAL/ELEVATED/HIGH/CRITICAL/DANGEROUS) and individual factor scores.

        **Admin Only**
      operationId: analyzePressure
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                context:
                  type: object
                  properties:
                    tokenUsage:
                      type: integer
                      example: 50000
                    tokenBudget:
                      type: integer
                      example: 200000
                    messageCount:
                      type: integer
                      example: 20
                    errorCount:
                      type: integer
                      example: 2
                    complexityScore:
                      type: number
                      example: 0.6
      responses:
        '200':
          description: Pressure analysis complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  pressure:
                    $ref: '#/components/schemas/PressureAnalysis'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /governance/verify:
    post:
      tags:
        - Governance Services
      summary: Metacognitive verification
      description: |
        Test the MetacognitiveVerifier service by performing AI self-checks on proposed actions.

        Detects scope creep, misalignment, and provides confidence scoring with alternatives.

        **Admin Only**
      operationId: verifyAction
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: object
                  properties:
                    type:
                      type: string
                      example: feature_implementation
                    description:
                      type: string
                      example: Add user authentication system
                    steps:
                      type: array
                      items:
                        type: string
                reasoning:
                  type: object
                  properties:
                    justification:
                      type: string
                      example: Required for secure user management
                context:
                  type: object
      responses:
        '200':
          description: Verification complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  verification:
                    $ref: '#/components/schemas/MetacognitiveVerification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ==================== Audit ====================
  /audit/audit-logs:
    get:
      tags:
        - Audit
      summary: Get audit logs
      description: |
        Retrieve audit logs with filtering and pagination.

        **Admin Only**
      operationId: getAuditLogs
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: action
          in: query
          description: Filter by action type
          schema:
            type: string
        - name: userId
          in: query
          description: Filter by user ID
          schema:
            type: string
        - name: startDate
          in: query
          description: Filter by start date (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: Filter by end date (ISO 8601)
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Audit logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLog'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /audit/audit-analytics:
    get:
      tags:
        - Audit
      summary: Get audit analytics
      description: |
        Retrieve aggregated analytics on audit logs (action counts, user activity, trends).

        **Admin Only**
      operationId: getAuditAnalytics
      security:
        - BearerAuth: []
      parameters:
        - name: startDate
          in: query
          description: Start date for analytics period (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: End date for analytics period (ISO 8601)
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Analytics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  analytics:
                    type: object
                    properties:
                      totalLogs:
                        type: integer
                        example: 1250
                      actionBreakdown:
                        type: object
                        additionalProperties:
                          type: integer
                        example:
                          login: 450
                          document_create: 120
                          document_update: 380
                          classify: 200
                          validate: 100
                      topUsers:
                        type: array
                        items:
                          type: object
                          properties:
                            userId:
                              type: string
                            email:
                              type: string
                            count:
                              type: integer
                      timeline:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            count:
                              type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ==================== Admin ====================
  /admin/moderation:
    get:
      tags:
        - Admin
      summary: List moderation queue
      description: |
        Retrieve items pending moderation.

        **Admin or Moderator role required**
      operationId: getModerationQueue
      security:
        - BearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, approved, rejected, escalated]
            default: pending
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Moderation queue retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ModerationItem'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /admin/moderation/{id}:
    get:
      tags:
        - Admin
      summary: Get moderation item
      description: |
        Retrieve a single moderation item by ID.

        **Admin or Moderator role required**
      operationId: getModerationItem
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Moderation item retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  item:
                    $ref: '#/components/schemas/ModerationItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/moderation/{id}/review:
    post:
      tags:
        - Admin
      summary: Review moderation item
      description: |
        Approve, reject, or escalate a moderation item.

        **Admin or Moderator role required**
      operationId: reviewModerationItem
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum: [approve, reject, escalate]
                  example: approve
                notes:
                  type: string
                  example: Content meets guidelines
      responses:
        '200':
          description: Review completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  item:
                    $ref: '#/components/schemas/ModerationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/stats:
    get:
      tags:
        - Admin
      summary: Get system statistics
      description: |
        Retrieve overall system statistics (users, documents, submissions, moderation queue).

        **Admin or Moderator role required**
      operationId: getSystemStats
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  stats:
                    type: object
                    properties:
                      users:
                        type: object
                        properties:
                          total:
                            type: integer
                            example: 125
                          admins:
                            type: integer
                            example: 3
                          moderators:
                            type: integer
                            example: 5
                      documents:
                        type: object
                        properties:
                          total:
                            type: integer
                            example: 45
                          published:
                            type: integer
                            example: 42
                          archived:
                            type: integer
                            example: 3
                      moderation:
                        type: object
                        properties:
                          pending:
                            type: integer
                            example: 12
                          approved:
                            type: integer
                            example: 380
                          rejected:
                            type: integer
                            example: 45
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /admin/activity:
    get:
      tags:
        - Admin
      summary: Get activity log
      description: |
        Retrieve recent admin activity (last 100 actions).

        **Admin role required**
      operationId: getActivityLog
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            maximum: 500
      responses:
        '200':
          description: Activity log retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  activities:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          format: date-time
                        userId:
                          type: string
                        email:
                          type: string
                        action:
                          type: string
                          example: document_update
                        details:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

# ==================== Components ====================
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token obtained from /api/auth/login endpoint.

        Include in Authorization header: `Authorization: Bearer <token>`

  schemas:
    User:
      type: object
      properties:
        _id:
          type: string
          example: 68e3a6fb21af2fd194bf4b50
        email:
          type: string
          format: email
          example: admin@tractatus.local
        role:
          type: string
          enum: [admin, moderator, user]
          example: admin
        created_at:
          type: string
          format: date-time

    Document:
      type: object
      properties:
        _id:
          type: string
          example: 67890abc12345def67890abc
        title:
          type: string
          example: Introduction to the Tractatus Framework
        slug:
          type: string
          example: introduction-to-tractatus
        quadrant:
          type: string
          enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
          example: STRATEGIC
        content_markdown:
          type: string
          description: Document content in Markdown format
        content_html:
          type: string
          description: Auto-generated HTML from Markdown
        status:
          type: string
          enum: [draft, published, archived]
          default: published
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          type: string
          description: User ID

    DocumentInput:
      type: object
      required:
        - title
        - slug
        - quadrant
        - content_markdown
      properties:
        title:
          type: string
          example: Core Concepts of the Tractatus Framework
        slug:
          type: string
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          example: core-concepts
        quadrant:
          type: string
          enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
          example: OPERATIONAL
        content_markdown:
          type: string
          description: Document content in Markdown format
        status:
          type: string
          enum: [draft, published, archived]
          default: published

    FrameworkStatus:
      type: object
      properties:
        success:
          type: boolean
          example: true
        components:
          type: object
          properties:
            InstructionPersistenceClassifier:
              type: string
              enum: [ACTIVE, INACTIVE, ERROR]
              example: ACTIVE
            CrossReferenceValidator:
              type: string
              enum: [ACTIVE, INACTIVE, ERROR]
              example: ACTIVE
            BoundaryEnforcer:
              type: string
              enum: [ACTIVE, INACTIVE, ERROR]
              example: ACTIVE
            ContextPressureMonitor:
              type: string
              enum: [ACTIVE, INACTIVE, ERROR]
              example: ACTIVE
            MetacognitiveVerifier:
              type: string
              enum: [ACTIVE, INACTIVE, ERROR]
              example: ACTIVE
        instructions:
          type: object
          properties:
            total:
              type: integer
              example: 28
            HIGH:
              type: integer
              example: 27
            MEDIUM:
              type: integer
              example: 1
            LOW:
              type: integer
              example: 0
        pressure:
          type: object
          properties:
            level:
              type: string
              enum: [NORMAL, ELEVATED, HIGH, CRITICAL, DANGEROUS]
              example: NORMAL
            score:
              type: number
              example: 0.033

    InstructionClassification:
      type: object
      properties:
        quadrant:
          type: string
          enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
          example: SYSTEM
        persistence:
          type: string
          enum: [HIGH, MEDIUM, LOW]
          example: HIGH
        temporal_scope:
          type: string
          enum: [SESSION, PROJECT, PERMANENT]
          example: PROJECT
        verification_required:
          type: string
          enum: [MANDATORY, RECOMMENDED, OPTIONAL]
          example: MANDATORY
        reasoning:
          type: string
          example: Port configuration affects system infrastructure
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          example: 0.95

    ValidationResult:
      type: object
      properties:
        status:
          type: string
          enum: [PASS, WARN, BLOCK]
          example: BLOCK
        conflicts:
          type: array
          items:
            type: object
            properties:
              instruction_id:
                type: string
              text:
                type: string
                example: Always use MongoDB on port 27027
              severity:
                type: string
                enum: [CRITICAL, HIGH, MEDIUM, LOW]
                example: CRITICAL
        trainingOverride:
          type: boolean
          example: true
          description: True if action appears to override training patterns (27027 failure mode)
        recommendation:
          type: string
          example: Action conflicts with HIGH persistence instruction (inst_002). Recommend maintaining port 27027.

    BoundaryEnforcement:
      type: object
      properties:
        status:
          type: string
          enum: [ALLOW, BLOCK, ESCALATE]
          example: BLOCK
        boundary:
          type: string
          enum: [PRIVACY, ETHICS, SOVEREIGNTY, STRATEGIC]
          example: ETHICS
          description: Which values boundary was crossed
        reasoning:
          type: string
          example: Content moderation decisions involve ethical judgments about acceptable speech
        alternatives:
          type: array
          items:
            type: string
          example:
            - Define clear content policy guidelines
            - Implement automated flagging system
            - Escalate to human moderators for final decision
        requiresHuman:
          type: boolean
          example: true

    PressureAnalysis:
      type: object
      properties:
        level:
          type: string
          enum: [NORMAL, ELEVATED, HIGH, CRITICAL, DANGEROUS]
          example: NORMAL
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          example: 0.25
        factors:
          type: object
          properties:
            tokenPressure:
              type: number
              example: 0.25
              description: Token usage / budget
            messagePressure:
              type: number
              example: 0.15
              description: Message count / threshold
            errorPressure:
              type: number
              example: 0.1
              description: Error rate
            complexityPressure:
              type: number
              example: 0.6
              description: Task complexity score
            instructionVolume:
              type: number
              example: 0.28
              description: Active instruction density
        recommendation:
          type: string
          example: Session health is normal. Continue work.
        triggerHandoff:
          type: boolean
          example: false
          description: True if pressure warrants session handoff

    MetacognitiveVerification:
      type: object
      properties:
        decision:
          type: string
          enum: [PROCEED, REVIEW, BLOCK]
          example: PROCEED
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          example: 0.85
        concerns:
          type: array
          items:
            type: string
          example:
            - Consider rate limiting for authentication endpoints
        alternatives:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
              pros:
                type: array
                items:
                  type: string
              cons:
                type: array
                items:
                  type: string
        scopeCreep:
          type: boolean
          example: false
          description: True if action appears to exceed original scope
        alignment:
          type: object
          properties:
            strategic:
              type: number
              example: 0.9
            operational:
              type: number
              example: 0.85
            tactical:
              type: number
              example: 0.8

    AuditLog:
      type: object
      properties:
        _id:
          type: string
        timestamp:
          type: string
          format: date-time
        userId:
          type: string
        email:
          type: string
          format: email
        action:
          type: string
          example: document_create
        resource:
          type: string
          example: documents
        resourceId:
          type: string
        details:
          type: object
        ipAddress:
          type: string
          example: 192.168.1.100
        userAgent:
          type: string

    ModerationItem:
      type: object
      properties:
        _id:
          type: string
        type:
          type: string
          enum: [case_submission, media_inquiry, comment]
          example: case_submission
        status:
          type: string
          enum: [pending, approved, rejected, escalated]
          example: pending
        submittedAt:
          type: string
          format: date-time
        content:
          type: object
        reviewedBy:
          type: string
          description: User ID of reviewer
        reviewedAt:
          type: string
          format: date-time
        reviewNotes:
          type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 50
        total:
          type: integer
          example: 250
        pages:
          type: integer
          example: 5

    Error:
      type: object
      properties:
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Missing required field 'text'
        details:
          type: object
          description: Additional error details (optional)

  responses:
    BadRequest:
      description: Bad Request - Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Bad Request
            message: Missing required field 'text'

    Unauthorized:
      description: Unauthorized - Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Authentication required. Please provide a valid JWT token.

    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            message: Admin role required for this endpoint

    NotFound:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
            message: Document not found

security:
  - BearerAuth: []