openapi.yaml

openapi: "3.1.0"
info:
  title: Akashi API
  description: |
    Version control for AI decisions. Akashi is the decision coordination
    layer for multi-agent AI systems — recording, querying, and auditing
    every agent decision. Check before deciding to surface precedents and
    active conflicts. Trace after deciding to record reasoning, alternatives,
    and confidence. Captures the full decision lifecycle: outcome, reasoning,
    alternatives considered, evidence, and confidence level.

    ## Authentication

    All `/v1/` endpoints require a Bearer JWT token obtained from
    `POST /auth/token`. Tokens are scoped to an organization and carry
    the agent's RBAC role.

    ## Response Envelope

    All JSON responses are wrapped in a standard envelope:

    ```json
    {
      "data": { ... },
      "meta": {
        "request_id": "uuid",
        "timestamp": "2026-01-15T10:30:00Z"
      }
    }
    ```

    Error responses use a parallel structure:

    ```json
    {
      "error": {
        "code": "INVALID_INPUT",
        "message": "description"
      },
      "meta": {
        "request_id": "uuid",
        "timestamp": "2026-01-15T10:30:00Z"
      }
    }
    ```
  version: 0.1.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: http://localhost:8080
    description: Local development

tags:
  - name: Auth
    description: Authentication
  - name: Agents
    description: Agent management (admin-only)
  - name: Runs
    description: Agent run lifecycle
  - name: Trace
    description: Convenience endpoint for single-call decision recording
  - name: Query
    description: Decision querying and history
  - name: Search
    description: Full-text and semantic search
  - name: Access
    description: Fine-grained access grants between agents
  - name: Export
    description: Bulk data export for auditors
  - name: Keys
    description: API key management (admin-only)
  - name: Usage
    description: Usage metering (admin-only)
  - name: Settings
    description: Organization settings and policies
  - name: System
    description: Health, SSE, and infrastructure

security:
  - bearerAuth: []

paths:
  # ── Auth ───────────────────────────────────────────────────────────
  /auth/token:
    post:
      operationId: createToken
      tags: [Auth]
      summary: Authenticate and obtain a JWT
      description: |
        Exchange agent credentials for a JWT.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthTokenRequest"
      responses:
        "200":
          description: JWT issued successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AuthTokenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /auth/signup:
    post:
      operationId: signup
      tags: [Auth]
      summary: Self-serve org signup with API key issuance
      description: |
        Creates an organization, its owner agent (org_owner role), and a managed
        API key in one atomic operation. The raw key is returned exactly once.
        Requires AKASHI_SIGNUP_ENABLED=true; returns 404 when disabled.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignupRequest"
      responses:
        "201":
          description: Organization, agent, and API key created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_SignupResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"

  /auth/refresh:
    post:
      operationId: refreshToken
      tags: [Auth]
      summary: Refresh a JWT
      description: Same as `/auth/token` — exchange credentials for a new JWT.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthTokenRequest"
      responses:
        "200":
          description: JWT issued successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AuthTokenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/auth/scoped-token:
    post:
      operationId: createScopedToken
      tags: [Auth]
      summary: Issue a scoped token (admin only)
      description: |
        Issues a short-lived JWT that authenticates as a target agent, with the
        issuing admin's identity recorded in a `scoped_by` claim. Useful for
        testing access control and debugging what a specific agent can see without
        needing its API key.

        - Requires `admin` role or higher.
        - Scoped tokens cannot issue further scoped tokens (no delegation chains).
        - TTL defaults to 5 minutes; maximum is 1 hour (`expires_in` is capped).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScopedTokenRequest"
      responses:
        "200":
          description: Scoped token issued successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_ScopedTokenResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Agents ─────────────────────────────────────────────────────────
  /v1/agents:
    post:
      operationId: createAgent
      tags: [Agents]
      summary: Create an agent
      description: |
        Register a new agent within the caller's organization.
        Requires `admin` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentRequest"
      responses:
        "201":
          description: Agent created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_Agent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
    get:
      operationId: listAgents
      tags: [Agents]
      summary: List all agents
      description: |
        List all agents in the caller's organization.
        Requires `admin` role or higher. Use `?include=stats` to
        enrich each agent with decision_count and last_decision_at.
      parameters:
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum: [stats]
          description: |
            Pass `stats` to include decision_count and last_decision_at
            on each agent in the response.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 200
          description: Maximum number of agents to return (1-1000).
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of agents to skip.
      responses:
        "200":
          description: List of agents.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AgentList"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/agents/{agent_id}:
    get:
      operationId: getAgent
      tags: [Agents]
      summary: Get an agent by ID
      description: |
        Retrieve a single agent by its agent_id.
        Requires `admin` role or higher.
      parameters:
        - $ref: "#/components/parameters/AgentIDPath"
      responses:
        "200":
          description: The agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_Agent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateAgent
      tags: [Agents]
      summary: Update an agent
      description: |
        Partially update an agent's name and/or metadata. Metadata is
        merge-patched (new keys are added, existing keys are overwritten).
        Requires `admin` role or higher.
      parameters:
        - $ref: "#/components/parameters/AgentIDPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAgentRequest"
      responses:
        "200":
          description: Agent updated. Returns the updated agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_Agent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteAgent
      tags: [Agents]
      summary: Delete an agent and all associated data
      description: |
        Permanently deletes the agent and all associated runs, events,
        decisions, evidence, alternatives, and access grants. This is a
        GDPR-compliant erasure operation. Cannot delete the "admin" agent.
        Requires `admin` role or higher.
      parameters:
        - $ref: "#/components/parameters/AgentIDPath"
      responses:
        "200":
          description: Agent and all data deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_DeleteAgentResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/agents/{agent_id}/stats:
    get:
      operationId: getAgentStats
      tags: [Agents]
      summary: Get agent statistics
      description: |
        Returns aggregate decision statistics for a specific agent:
        total count, average confidence, quality breakdown, and
        decision type distribution.
        Requires `admin` role or higher.
      parameters:
        - $ref: "#/components/parameters/AgentIDPath"
      responses:
        "200":
          description: Agent statistics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AgentStats"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/agents/{agent_id}/tags:
    patch:
      operationId: updateAgentTags
      tags: [Agents]
      summary: Update an agent's tags
      description: |
        Replace the tags for an agent. Tags enable group-based access control:
        agents sharing at least one tag can see each other's decisions without
        explicit grants. Tags coexist with the existing grant system.
        Requires `admin` role or higher.
      parameters:
        - $ref: "#/components/parameters/AgentIDPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAgentTagsRequest"
      responses:
        "200":
          description: Tags updated. Returns the updated agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_Agent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Runs ───────────────────────────────────────────────────────────
  /v1/runs:
    post:
      operationId: createRun
      tags: [Runs]
      summary: Start a new agent run
      description: |
        Create a new run for the authenticated agent. Runs are the top-level
        execution context for recording events and decisions.
        Requires `agent` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRunRequest"
      responses:
        "201":
          description: Run created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AgentRun"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/runs/{run_id}:
    get:
      operationId: getRun
      tags: [Runs]
      summary: Get a run with events and decisions
      description: |
        Retrieve a run along with all its events and decisions.
        Requires `reader` role or higher.
      parameters:
        - $ref: "#/components/parameters/RunIDPath"
      responses:
        "200":
          description: Run details with events and decisions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_GetRunResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/runs/{run_id}/events:
    post:
      operationId: appendEvents
      tags: [Runs]
      summary: Append events to a run
      description: |
        Append one or more events to an existing run.
        Supports idempotent retries via `Idempotency-Key`.
        Requires `agent` role or higher.
      parameters:
        - $ref: "#/components/parameters/RunIDPath"
        - $ref: "#/components/parameters/IdempotencyKeyHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppendEventsRequest"
      responses:
        "200":
          description: Events persisted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AppendEventsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/runs/{run_id}/complete:
    post:
      operationId: completeRun
      tags: [Runs]
      summary: Complete or fail a run
      description: |
        Mark a run as completed or failed. Updates the run status and
        records the completion time.
        Supports idempotent retries via `Idempotency-Key`.
        Requires `agent` role or higher.
      parameters:
        - $ref: "#/components/parameters/RunIDPath"
        - $ref: "#/components/parameters/IdempotencyKeyHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteRunRequest"
      responses:
        "200":
          description: Run completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AgentRun"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Trace ──────────────────────────────────────────────────────────
  /v1/trace:
    post:
      operationId: trace
      tags: [Trace]
      summary: Record a decision in a single call
      description: |
        Convenience endpoint that creates a run, records a decision with
        alternatives and evidence, appends lifecycle events, and completes
        the run — all in a single transaction.
        Supports idempotent retries via `Idempotency-Key`.
        Requires `agent` role or higher.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKeyHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TraceRequest"
            example:
              agent_id: planner
              decision:
                decision_type: architecture
                outcome: "Use Redis for session caching"
                confidence: 0.85
                reasoning: "Redis handles expected QPS with sub-ms latency. TTL-based expiry prevents stale sessions without manual cleanup."
                alternatives:
                  - label: "Redis"
                    score: 0.85
                    selected: true
                  - label: "Memcached"
                    score: 0.6
                    selected: false
                    rejection_reason: "No persistence — sessions lost on restart"
                  - label: "Database sessions"
                    score: 0.3
                    selected: false
                    rejection_reason: "Adds read load to primary database"
                evidence:
                  - source_type: document
                    source_uri: "https://redis.io/docs/latest/develop/use/client-side-caching/"
                    content: "Redis supports client-side caching with server-assisted invalidation via RESP3."
                    relevance_score: 0.9
                  - source_type: agent_output
                    content: "Load test showed p99 < 2ms at 10k req/s with Redis 7 cluster."
                    relevance_score: 0.85
              metadata:
                sprint: "2026-Q1"
                ticket: "ARCH-142"
      responses:
        "201":
          description: Decision traced successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_TraceResponse"
              example:
                data:
                  run_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  decision_id: "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                  event_count: 6
                meta:
                  request_id: "11223344-5566-7788-99aa-bbccddeeff00"
                  timestamp: "2026-01-15T10:30:00Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── Query ──────────────────────────────────────────────────────────
  /v1/query:
    post:
      operationId: queryDecisions
      tags: [Query]
      summary: Query decisions with filters
      description: |
        Query decisions with flexible filters, ordering, and pagination.
        Optionally include alternatives and evidence in the response.
        Requires `reader` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryRequest"
            example:
              filters:
                decision_type: architecture
                confidence_min: 0.7
                time_range:
                  from: "2026-01-01T00:00:00Z"
              include:
                - alternatives
                - evidence
              order_by: created_at
              order_dir: desc
              limit: 10
              offset: 0
      responses:
        "200":
          description: Matching decisions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_QueryResponse"
              example:
                data:
                  decisions:
                    - id: "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                      run_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      agent_id: planner
                      org_id: "00000000-0000-0000-0000-000000000001"
                      decision_type: architecture
                      outcome: "Use Redis for session caching"
                      confidence: 0.85
                      reasoning: "Redis handles expected QPS with sub-ms latency."
                      metadata:
                        sprint: "2026-Q1"
                        ticket: "ARCH-142"
                      completeness_score: 0.85
                      quality_score: 0.85
                      valid_from: "2026-01-15T10:30:00Z"
                      transaction_time: "2026-01-15T10:30:00Z"
                      created_at: "2026-01-15T10:30:00Z"
                      alternatives:
                        - id: "11111111-1111-1111-1111-111111111111"
                          decision_id: "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                          label: "Redis"
                          score: 0.85
                          selected: true
                          metadata: {}
                          created_at: "2026-01-15T10:30:00Z"
                        - id: "22222222-2222-2222-2222-222222222222"
                          decision_id: "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                          label: "Memcached"
                          score: 0.6
                          selected: false
                          rejection_reason: "No persistence — sessions lost on restart"
                          metadata: {}
                          created_at: "2026-01-15T10:30:00Z"
                      evidence:
                        - id: "33333333-3333-3333-3333-333333333333"
                          decision_id: "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                          org_id: "00000000-0000-0000-0000-000000000001"
                          source_type: document
                          source_uri: "https://redis.io/docs/latest/develop/use/client-side-caching/"
                          content: "Redis supports client-side caching with server-assisted invalidation via RESP3."
                          relevance_score: 0.9
                          metadata: {}
                          created_at: "2026-01-15T10:30:00Z"
                  total: 1
                  count: 1
                  limit: 10
                  offset: 0
                meta:
                  request_id: "aabbccdd-eeff-0011-2233-445566778899"
                  timestamp: "2026-01-15T10:31:00Z"
        "400":
          $ref: "#/components/responses/BadRequest"

  /v1/query/temporal:
    post:
      operationId: temporalQuery
      tags: [Query]
      summary: Query decisions as of a point in time
      description: |
        Bi-temporal query: returns decisions that were valid at the specified
        `as_of` timestamp. Uses the valid_from/valid_to temporal columns.
        Requires `reader` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemporalQueryRequest"
      responses:
        "200":
          description: Decisions valid at the specified time.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_TemporalQueryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /v1/agents/{agent_id}/history:
    get:
      operationId: agentHistory
      tags: [Query]
      summary: Get decision history for an agent
      description: |
        Retrieve the decision history for a specific agent with pagination
        and optional time range filtering.
        Requires `reader` role or higher.
      parameters:
        - $ref: "#/components/parameters/AgentIDPath"
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: from
          in: query
          description: Start of time range (RFC 3339).
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: End of time range (RFC 3339).
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Agent decision history.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AgentHistoryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /v1/decisions/{id}:
    get:
      operationId: getDecision
      tags: [Decisions]
      summary: Get a decision by ID
      description: |
        Retrieve a single decision by its UUID, including alternatives
        and evidence. Requires `reader` role or higher. Access is
        subject to grant-based filtering.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Decision UUID.
      responses:
        "200":
          description: The decision with alternatives and evidence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_Decision"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/decisions/recent:
    get:
      operationId: recentDecisions
      tags: [Query]
      summary: List recent decisions
      description: |
        Retrieve the most recent decisions, optionally filtered by agent
        or decision type.
        Requires `reader` role or higher.
      parameters:
        - name: agent_id
          in: query
          schema:
            type: string
        - name: decision_type
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 1000
      responses:
        "200":
          description: Recent decisions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_RecentDecisionsResponse"

  /v1/decisions/{id}/revisions:
    get:
      operationId: getDecisionRevisions
      tags: [Query]
      summary: Get decision revision history
      description: |
        Retrieve the full revision chain for a decision, including all
        prior and subsequent versions linked via `supersedes_id`.
        Requires `reader` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The decision ID to get revisions for.
      responses:
        "200":
          description: Revision chain for the decision.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_RevisionsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/decisions/{id}/conflicts:
    get:
      operationId: getDecisionConflicts
      tags: [Conflicts]
      summary: Get conflicts involving a decision
      description: |
        Returns all detected conflicts where this decision appears as
        either side (A or B). Useful for understanding whether a specific
        decision contradicts or supersedes other decisions.
        Requires `reader` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The decision ID to find conflicts for.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [open, acknowledged, resolved, wont_fix]
          description: Filter by conflict status.
      responses:
        "200":
          description: Conflicts involving this decision.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      decision_id:
                        type: string
                        format: uuid
                      conflicts:
                        type: array
                        items:
                          $ref: "#/components/schemas/DecisionConflict"
                      total:
                        type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /v1/decisions/{id}/assess:
    post:
      operationId: assessDecision
      tags: [Decisions]
      summary: Submit outcome assessment for a decision
      description: |
        Records explicit outcome feedback for a prior decision. Append-only:
        each call creates a new row. Re-assessing creates a revision record
        rather than overwriting, preserving the full assessment history.
        The summary counts only the latest assessment per assessor so current
        verdicts are accurate even when assessors change their minds.
        Requires `agent` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The decision ID to assess.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [outcome]
              properties:
                outcome:
                  type: string
                  enum: [correct, incorrect, partially_correct]
                  description: Whether the decision turned out to be correct.
                notes:
                  type: string
                  description: Optional explanation of the assessment.
      responses:
        "200":
          description: Assessment recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/DecisionAssessment"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/decisions/{id}/assessments:
    get:
      operationId: listDecisionAssessments
      tags: [Decisions]
      summary: List assessments for a decision
      description: |
        Returns all outcome assessments for a decision, newest first,
        along with an aggregated summary of counts by outcome.
        Requires `reader` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The decision ID.
      responses:
        "200":
          description: Assessments and summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      decision_id:
                        type: string
                        format: uuid
                      summary:
                        $ref: "#/components/schemas/AssessmentSummary"
                      assessments:
                        type: array
                        items:
                          $ref: "#/components/schemas/DecisionAssessment"
                      count:
                        type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/decisions/{id}/erase:
    post:
      operationId: eraseDecision
      tags: [Decisions, GDPR]
      summary: GDPR tombstone erasure
      description: |
        Scrubs PII fields (outcome, reasoning) from a decision in-place
        without deleting the row, preserving the audit chain. Also scrubs
        associated alternatives (label, rejection_reason) and evidence
        (content, source_uri). Recomputes the content hash over the
        scrubbed fields and records the original hash in a decision_erasures
        row for forensic verification.

        This operation is irreversible. Blocked if the decision is covered
        by an active legal hold.

        Requires `org_owner` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The decision ID to erase.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Optional reason for the erasure (e.g., "GDPR data subject request #1234").
      responses:
        "200":
          description: Decision PII successfully erased.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_ErasureResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Decision is covered by an active legal hold, or has already been erased.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"

  /v1/verify/{id}:
    get:
      operationId: verifyDecision
      tags: [Integrity]
      summary: Verify decision integrity
      description: |
        Recomputes the SHA-256 content hash from the decision's stored
        fields and compares it to the stored hash. Returns whether the
        decision has been tampered with.
        Requires `reader` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The decision ID to verify.
      responses:
        "200":
          description: Integrity verification result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_VerifyResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/conflicts/analytics:
    get:
      operationId: getConflictAnalytics
      tags: [Query]
      summary: Conflict trend analytics
      description: |
        Returns aggregated conflict metrics over a time window: summary stats,
        breakdowns by agent pair / decision type / severity, and a daily
        detected-vs-resolved trend.
        Requires `reader` role or higher.
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d]
            default: "7d"
          description: |
            Convenience period relative to now. Ignored when both `from` and
            `to` are provided.
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          description: Start of time range (RFC 3339). Requires `to`.
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          description: End of time range (RFC 3339). Requires `from`.
        - name: agent_id
          in: query
          schema:
            type: string
          description: Filter to conflicts involving this agent.
        - name: decision_type
          in: query
          schema:
            type: string
          description: Filter to conflicts involving this decision type.
        - name: conflict_kind
          in: query
          schema:
            type: string
            enum: [cross_agent, self_contradiction]
          description: Filter by conflict kind.
      responses:
        "200":
          description: Conflict analytics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_ConflictAnalytics"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/conflicts:
    get:
      operationId: listConflicts
      tags: [Query]
      summary: List detected decision conflicts
      description: |
        List conflicts between decisions, detected via embedding similarity and
        optional LLM validation. Supports filtering by conflict kind, status,
        severity, category, agent, and decision type.
        Requires `reader` role or higher.
      parameters:
        - name: decision_type
          in: query
          schema:
            type: string
        - name: agent_id
          in: query
          schema:
            type: string
        - name: conflict_kind
          in: query
          schema:
            type: string
            enum: [cross_agent, self_contradiction]
          description: Filter by conflict type.
        - name: status
          in: query
          schema:
            type: string
            enum: [open, acknowledged, resolved, wont_fix]
          description: Filter by lifecycle status. Omit to return conflicts of all statuses.
        - name: severity
          in: query
          schema:
            type: string
            enum: [critical, high, medium, low]
          description: Filter by severity.
        - name: category
          in: query
          schema:
            type: string
            enum: [factual, assessment, strategic, temporal]
          description: Filter by category.
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 1000
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        "200":
          description: Decision conflicts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_ConflictsResponse"

  /v1/conflicts/{id}:
    get:
      operationId: getConflict
      tags: [Query]
      summary: Get a single conflict with resolution recommendation
      description: |
        Returns the full conflict detail including a lazily-computed resolution
        recommendation based on confidence, recency, agent track record, and
        revision depth. The recommendation is only present for unresolved conflicts
        (status `open` or `acknowledged`).
        Requires `reader` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The conflict ID.
      responses:
        "200":
          description: Conflict detail with optional recommendation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictDetail"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: patchConflict
      tags: [Query]
      summary: Update conflict lifecycle status
      description: |
        Transition a conflict to a new lifecycle state (acknowledged, resolved,
        wont_fix). Resolution requires `agent` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The conflict ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConflictStatusUpdate"
      responses:
        "200":
          description: Updated conflict.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionConflict"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/conflicts/{id}/adjudicate:
    post:
      operationId: adjudicateConflict
      tags: [Query]
      summary: Adjudicate a conflict by creating an adjudication decision
      description: |
        Creates a new decision trace that serves as the authoritative adjudication
        of the conflict, then links it to the conflict record. This provides a
        full audit trail: the original conflicting decisions, and the explicit
        adjudication with its reasoning.
        Requires `agent` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The conflict ID to adjudicate.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdjudicateConflictRequest"
      responses:
        "200":
          description: Conflict adjudicated. Returns the updated conflict with linked adjudication decision.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionConflict"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/conflict-groups/{id}/resolve:
    patch:
      operationId: resolveConflictGroup
      tags: [Query]
      summary: Batch-resolve all open conflicts in a conflict group
      description: |
        Resolves all open or acknowledged conflicts in a conflict group at once.
        When `winning_agent` is provided with status "resolved", each conflict's
        `winning_decision_id` is set to the decision from that agent.
        Requires `agent` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The conflict group ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConflictGroupResolveRequest"
      responses:
        "200":
          description: Batch resolution result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictGroupResolveResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/admin/conflicts/validate-pair:
    post:
      operationId: validateConflictPair
      tags: [Admin]
      summary: Validate a single decision pair for conflicts
      description: |
        Runs the configured LLM conflict validator against a single decision pair
        and returns the classified relationship (contradiction, complementary,
        refinement, supersession, or unrelated).
        Returns 501 if no LLM validator is configured.
        Requires `platform_admin` role.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidatePairRequest"
      responses:
        "200":
          description: Validation result with classified relationship.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidatePairResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "501":
          description: No LLM conflict validator configured.

  /v1/admin/conflicts/eval:
    post:
      operationId: evalConflictValidator
      tags: [Admin]
      summary: Run the conflict validator evaluation dataset
      description: |
        Runs the default labeled evaluation dataset against the configured
        LLM conflict validator and returns precision, recall, F1, and
        per-pair results. Used to measure validator accuracy.
        Returns 501 if no LLM validator is configured.
        Requires `platform_admin` role.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Evaluation metrics and per-pair results.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictEvalResponse"
        "501":
          description: No LLM conflict validator configured.

  /v1/admin/conflicts/{id}/label:
    put:
      operationId: upsertConflictLabel
      tags: [Admin]
      summary: Upsert a ground truth label for a scored conflict
      description: |
        Inserts or updates a human-verified label for a scored conflict.
        Labels are used for precision/recall evaluation of the conflict scorer.
        Returns 409 if the conflict belongs to a different organization.
        Requires `platform_admin` role.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The scored conflict ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertLabelRequest"
      responses:
        "200":
          description: Label upserted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LabelResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          description: Conflict belongs to a different organization.
    get:
      operationId: getConflictLabel
      tags: [Admin]
      summary: Get a ground truth label for a scored conflict
      description: |
        Returns the human-verified label for a single scored conflict.
        Requires `platform_admin` role.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The scored conflict ID.
      responses:
        "200":
          description: Label found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LabelResponse"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteConflictLabel
      tags: [Admin]
      summary: Delete a ground truth label for a scored conflict
      description: |
        Removes the label for a scored conflict. Used for re-labeling workflows.
        Requires `platform_admin` role.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The scored conflict ID.
      responses:
        "204":
          description: Label deleted.
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/admin/conflict-labels:
    get:
      operationId: listConflictLabels
      tags: [Admin]
      summary: List all ground truth labels for the organization
      description: |
        Returns all conflict labels and aggregate counts for the caller's organization.
        Requires `platform_admin` role.
      responses:
        "200":
          description: Labels and counts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListLabelsResponse"

  /v1/admin/scorer-eval:
    post:
      operationId: scorerEval
      tags: [Admin]
      summary: Compute scorer precision from ground truth labels
      description: |
        Computes precision from ground truth labels on existing scored conflicts.
        Precision = genuine / (genuine + related_not_contradicting + unrelated_false_positive).
        Requires `platform_admin` role.
      responses:
        "200":
          description: Scorer evaluation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScorerEvalResponse"

  /v1/check:
    post:
      operationId: checkPrecedent
      tags: [Query]
      summary: Check for precedent decisions and conflicts
      description: |
        Lightweight lookup for existing decisions of a given type, optionally
        filtered by agent or semantic query. Returns whether a precedent
        exists and any detected conflicts.
        Requires `reader` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckRequest"
      responses:
        "200":
          description: Precedent check result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_CheckResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /v1/trace-health:
    get:
      operationId: getTraceHealth
      tags: [Query]
      summary: Get trace health metrics
      description: |
        Returns aggregate health metrics for the organization's decision trace
        data, including decision quality, evidence coverage, and conflict
        resolution rates. Identifies gaps and returns an overall status.
        Requires `admin` role or higher.
      responses:
        "200":
          description: Trace health metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TraceHealthMetrics"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── Search ─────────────────────────────────────────────────────────
  /v1/search:
    post:
      operationId: searchDecisions
      tags: [Search]
      summary: Full-text and semantic search
      description: |
        Search decisions by keyword or semantic similarity. When `semantic`
        is true, the query is embedded and compared against decision embeddings
        using cosine similarity. Requires `reader` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          description: Search results with similarity scores.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_SearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ── Access Grants ──────────────────────────────────────────────────
  /v1/grants:
    post:
      operationId: createGrant
      tags: [Access]
      summary: Grant access to another agent
      description: |
        Create a fine-grained access grant allowing another agent to read
        or write specific resources. Agents can grant access to their own
        traces; admins can grant access to any resource.
        Requires `agent` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGrantRequest"
      responses:
        "201":
          description: Grant created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_AccessGrant"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"

  /v1/grants/{grant_id}:
    delete:
      operationId: deleteGrant
      tags: [Access]
      summary: Revoke an access grant
      description: |
        Delete an access grant. Agents can delete their own grants; admins
        can delete any grant. Requires `agent` role or higher.
      parameters:
        - name: grant_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The UUID of the grant to delete.
      responses:
        "204":
          description: Grant deleted.
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Export ─────────────────────────────────────────────────────────
  /v1/export/decisions:
    get:
      operationId: exportDecisions
      tags: [Export]
      summary: Export decisions as NDJSON
      description: |
        Stream all decisions matching the filters as newline-delimited JSON.
        Intended for audit and compliance workflows. Uses cursor-based
        pagination internally — one JSON object per line.
        Requires `admin` role or higher.
      parameters:
        - name: agent_id
          in: query
          schema:
            type: string
        - name: decision_type
          in: query
          schema:
            type: string
        - name: from
          in: query
          description: Start of time range (RFC 3339).
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: End of time range (RFC 3339).
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: NDJSON stream of decisions.
          content:
            application/x-ndjson:
              schema:
                $ref: "#/components/schemas/Decision"
          headers:
            Content-Disposition:
              schema:
                type: string
              description: 'Attachment filename, e.g. `attachment; filename="akashi-export-20260115-103000.ndjson"`'
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── API Keys ──────────────────────────────────────────────────────
  /v1/keys:
    post:
      operationId: createKey
      tags: [Keys]
      summary: Mint a new API key
      description: |
        Create a managed API key for an agent. The raw key is returned only
        once in the response — it cannot be retrieved afterward.
        Requires `admin` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateKeyRequest"
      responses:
        "201":
          description: Key created. `raw_key` is shown only once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateKeyResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
    get:
      operationId: listKeys
      tags: [Keys]
      summary: List API keys for the organization
      description: |
        Returns all API keys (active and revoked) for the caller's
        organization. Key hashes are never exposed.
        Requires `admin` role or higher.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        "200":
          description: List of API keys.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_KeyList"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/keys/{id}:
    delete:
      operationId: revokeKey
      tags: [Keys]
      summary: Revoke an API key
      description: |
        Revokes an API key immediately. The key can no longer be used
        for authentication. Revocation is permanent.
        Requires `admin` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The UUID of the key to revoke.
      responses:
        "200":
          description: Key revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: revoked
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/keys/{id}/rotate:
    post:
      operationId: rotateKey
      tags: [Keys]
      summary: Rotate an API key
      description: |
        Atomically revokes the old key and mints a new one for the same
        agent with the same label. The new raw key is returned only once.
        Requires `admin` role or higher.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The UUID of the key to rotate.
      responses:
        "200":
          description: Key rotated. New `raw_key` is shown only once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RotateKeyResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Usage ────────────────────────────────────────────────────────
  /v1/usage:
    get:
      operationId: getUsage
      tags: [Usage]
      summary: Get usage metering for a billing period
      description: |
        Returns decision counts aggregated by API key and agent for the
        specified billing period. The decisions table is the usage ledger —
        no separate metering table exists.
        Requires `admin` role or higher.
      parameters:
        - name: period
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{4}-\d{2}$'
          description: Billing period in YYYY-MM format.
      responses:
        "200":
          description: Usage breakdown for the period.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── System ─────────────────────────────────────────────────────────
  /config:
    get:
      operationId: getConfig
      tags: [System]
      summary: Feature flags
      description: |
        Returns deployment feature flags so the UI can adapt to the current
        configuration. No authentication required.
      security: []
      responses:
        "200":
          description: Feature flag values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      search_enabled:
                        type: boolean
                        description: True when a vector search backend (Qdrant) is configured.
                    required:
                      - search_enabled
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"

  /health:
    get:
      operationId: healthCheck
      tags: [System]
      summary: Health check
      description: Returns server health status including database connectivity.
      security: []
      responses:
        "200":
          description: Server is healthy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_HealthResponse"
        "503":
          description: Server is unhealthy (database disconnected).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_HealthResponse"

  # ── Org Settings ──────────────────────────────────────────────────
  /v1/org/settings:
    get:
      operationId: getOrgSettings
      tags: [Settings]
      summary: Get org settings
      description: |
        Returns the current organization settings, including conflict
        auto-resolution policy. Returns empty defaults if no settings
        have been configured. Requires `reader` role or higher.
      responses:
        "200":
          description: Current org settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_OrgSettingsData"
    put:
      operationId: setOrgSettings
      tags: [Settings]
      summary: Update org settings
      description: |
        Create or update the organization settings. Validates the conflict
        resolution policy if provided. Requires `admin` role.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgSettingsData"
      responses:
        "200":
          description: Updated org settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_OrgSettingsData"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v1/subscribe:
    get:
      operationId: subscribe
      tags: [System]
      summary: Subscribe to real-time events (SSE)
      description: |
        Opens a Server-Sent Events stream for real-time notifications about
        new decisions, run completions, and other events within the
        authenticated agent's organization. Long-lived connection.
        Requires `reader` role or higher.
      responses:
        "200":
          description: SSE stream opened.
          content:
            text/event-stream:
              schema:
                type: string
        "503":
          description: SSE not available (LISTEN/NOTIFY not configured).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"

  /mcp:
    post:
      operationId: mcpRequest
      tags: [System]
      summary: MCP StreamableHTTP transport
      description: |
        Model Context Protocol endpoint. Speaks MCP protocol over HTTP,
        not REST. See the [MCP specification](https://modelcontextprotocol.io/)
        for protocol details. Requires `reader` role or higher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: MCP JSON-RPC request.
      responses:
        "200":
          description: MCP JSON-RPC response.
          content:
            application/json:
              schema:
                type: object
                description: MCP JSON-RPC response.
        "403":
          $ref: "#/components/responses/Forbidden"

  /openapi.yaml:
    get:
      operationId: getOpenAPISpec
      tags: [System]
      summary: OpenAPI specification
      description: Returns this OpenAPI 3.1 specification as YAML.
      security: []
      responses:
        "200":
          description: OpenAPI spec.
          content:
            application/yaml:
              schema:
                type: string

# ════════════════════════════════════════════════════════════════════
# Components
# ════════════════════════════════════════════════════════════════════
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Ed25519-signed JWT obtained from `POST /auth/token`.
        Include as `Authorization: Bearer <token>`.

  parameters:
    RunIDPath:
      name: run_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The UUID of the run.

    AgentIDPath:
      name: agent_id
      in: path
      required: true
      schema:
        type: string
      description: The string identifier of the agent.

    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: |
        Optional idempotency key for retry-safe writes.
        Reusing the same key with a different payload returns `409 CONFLICT`.

  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    Unauthorized:
      description: Invalid credentials.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    Forbidden:
      description: Insufficient permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    Conflict:
      description: Resource already exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"

    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"

  schemas:
    # ── Conflict label schemas ──────────────────────────────────────
    UpsertLabelRequest:
      type: object
      required: [label]
      properties:
        label:
          type: string
          enum: [genuine, related_not_contradicting, unrelated_false_positive]
          description: Ground truth label for the scored conflict.
        notes:
          type: string
          description: Optional notes about the labeling decision.

    LabelResponse:
      type: object
      required: [scored_conflict_id, org_id, label, labeled_by, labeled_at]
      properties:
        scored_conflict_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        label:
          type: string
          enum: [genuine, related_not_contradicting, unrelated_false_positive]
        labeled_by:
          type: string
        labeled_at:
          type: string
          format: date-time
        notes:
          type: string

    ListLabelsResponse:
      type: object
      required: [labels, counts]
      properties:
        labels:
          type: array
          items:
            $ref: "#/components/schemas/LabelResponse"
        counts:
          $ref: "#/components/schemas/ConflictLabelCounts"

    ConflictLabelCounts:
      type: object
      required: [genuine, related_not_contradicting, unrelated_false_positive, total]
      properties:
        genuine:
          type: integer
        related_not_contradicting:
          type: integer
        unrelated_false_positive:
          type: integer
        total:
          type: integer

    ScorerEvalResponse:
      type: object
      required: [precision, true_positives, false_positives, total_labeled]
      properties:
        precision:
          type: number
          format: double
        true_positives:
          type: integer
        false_positives:
          type: integer
        total_labeled:
          type: integer
        message:
          type: string

    # ── Response envelopes ───────────────────────────────────────────
    ResponseMeta:
      type: object
      required: [request_id, timestamp]
      properties:
        request_id:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time

    APIError:
      type: object
      required: [error, meta]
      properties:
        error:
          $ref: "#/components/schemas/ErrorDetail"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    ErrorDetail:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          enum:
            - INVALID_INPUT
            - UNAUTHORIZED
            - FORBIDDEN
            - NOT_FOUND
            - CONFLICT
            - INTERNAL_ERROR
        message:
          type: string
        details:
          description: Additional context about the error.

    # ── Auth schemas ─────────────────────────────────────────────────
    SignupRequest:
      type: object
      required: [org_name, agent_id, email]
      properties:
        org_name:
          type: string
          description: Human-readable organization name. Slugified for the org_slug.
          example: acme-ai
        agent_id:
          type: string
          description: Identifier for the org owner agent.
          example: alice
        email:
          type: string
          format: email
          description: Email address for the org owner (used for future verification).
          example: alice@acme.com

    SignupResponse:
      type: object
      required: [org_id, org_slug, agent_id, api_key, mcp_config]
      properties:
        org_id:
          type: string
          format: uuid
        org_slug:
          type: string
        agent_id:
          type: string
        api_key:
          type: string
          description: Managed API key (ak_* format). Shown exactly once.
        mcp_config:
          $ref: "#/components/schemas/MCPConfigSnippet"

    MCPConfigSnippet:
      type: object
      required: [url, header]
      properties:
        url:
          type: string
          description: MCP endpoint URL.
          example: https://app.akashi.ai/mcp
        header:
          type: string
          description: Ready-to-paste Authorization header value.
          example: "ApiKey alice:ak_abc123_..."

    APIResponse_SignupResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/SignupResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    AuthTokenRequest:
      type: object
      required: [agent_id, api_key]
      properties:
        agent_id:
          type: string
        api_key:
          type: string

    AuthTokenResponse:
      type: object
      required: [token, expires_at]
      properties:
        token:
          type: string
        expires_at:
          type: string
          format: date-time

    ScopedTokenRequest:
      type: object
      required: [as_agent_id]
      properties:
        as_agent_id:
          type: string
          description: The agent_id to impersonate for the duration of the token.
        expires_in:
          type: integer
          description: Token lifetime in seconds. Defaults to 300 (5 min), capped at 3600 (1 hr).
          example: 300

    ScopedTokenResponse:
      type: object
      required: [token, expires_at, as_agent_id, scoped_by]
      properties:
        token:
          type: string
          description: The issued JWT, valid as the target agent.
        expires_at:
          type: string
          format: date-time
        as_agent_id:
          type: string
          description: The agent_id this token authenticates as.
        scoped_by:
          type: string
          description: The admin agent_id that issued this scoped token.

    # ── Agent schemas ────────────────────────────────────────────────
    AgentRole:
      type: string
      enum:
        - platform_admin
        - org_owner
        - admin
        - agent
        - reader

    Agent:
      type: object
      required: [id, agent_id, org_id, name, role, tags, metadata, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        agent_id:
          type: string
        org_id:
          type: string
          format: uuid
        name:
          type: string
        role:
          $ref: "#/components/schemas/AgentRole"
        tags:
          type: array
          items:
            type: string
          description: |
            Tags for group-based access control. Agents sharing at least one
            tag can see each other's decisions. Must match `^[a-z][a-z0-9_-]*$`.
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_seen:
          type: string
          format: date-time
          nullable: true
          description: |
            Timestamp of the agent's most recent authenticated API request.
            Null if the agent has never made an authenticated request.

    CreateAgentRequest:
      type: object
      required: [agent_id, name, api_key]
      properties:
        agent_id:
          type: string
        name:
          type: string
        role:
          $ref: "#/components/schemas/AgentRole"
        api_key:
          type: string
        tags:
          type: array
          items:
            type: string
          description: Optional tags for group-based access control.
        metadata:
          type: object
          additionalProperties: true

    UpdateAgentRequest:
      type: object
      description: |
        Partial update of an agent. At least one field must be provided.
        Metadata is merge-patched (new keys added, existing keys overwritten).
      properties:
        name:
          type: string
          description: New display name for the agent.
        metadata:
          type: object
          additionalProperties: true
          description: Metadata keys to merge into the agent's existing metadata.

    UpdateAgentTagsRequest:
      type: object
      required: [tags]
      properties:
        tags:
          type: array
          items:
            type: string
          description: |
            New set of tags for the agent. Replaces existing tags entirely.
            Each tag must match `^[a-z][a-z0-9_-]*$`.

    AgentStats:
      type: object
      properties:
        decision_count:
          type: integer
          description: Total number of active decisions by this agent.
        avg_confidence:
          type: number
          format: double
          description: Average confidence across all decisions.
        first_decision:
          type: string
          format: date-time
          description: Timestamp of the agent's earliest decision.
        last_decision:
          type: string
          format: date-time
          description: Timestamp of the agent's most recent decision.
        low_quality_count:
          type: integer
          description: Number of decisions with completeness_score below 0.5.
        decision_types:
          type: object
          additionalProperties:
            type: integer
          description: Decision count breakdown by decision_type.

    DeleteAgentResponse:
      type: object
      required: [agent_id, deleted]
      properties:
        agent_id:
          type: string
        deleted:
          $ref: "#/components/schemas/DeleteAgentResult"

    DeleteAgentResult:
      type: object
      required: [evidence, alternatives, decisions, events, runs, grants, agents]
      properties:
        evidence:
          type: integer
          format: int64
        alternatives:
          type: integer
          format: int64
        decisions:
          type: integer
          format: int64
        events:
          type: integer
          format: int64
        runs:
          type: integer
          format: int64
        grants:
          type: integer
          format: int64
        agents:
          type: integer
          format: int64

    # ── Access grant schemas ─────────────────────────────────────────
    AccessGrant:
      type: object
      required: [id, org_id, grantor_id, grantee_id, resource_type, permission, granted_at]
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        grantor_id:
          type: string
          format: uuid
        grantee_id:
          type: string
          format: uuid
        resource_type:
          type: string
        resource_id:
          type: string
        permission:
          type: string
        granted_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    CreateGrantRequest:
      type: object
      required: [grantee_agent_id, resource_type, permission]
      properties:
        grantee_agent_id:
          type: string
        resource_type:
          type: string
        resource_id:
          type: string
        permission:
          type: string
        expires_at:
          type: string
          description: RFC 3339 timestamp.

    # ── Run schemas ──────────────────────────────────────────────────
    RunStatus:
      type: string
      enum: [running, completed, failed]

    AgentRun:
      type: object
      required: [id, agent_id, org_id, status, started_at, metadata, created_at]
      properties:
        id:
          type: string
          format: uuid
        agent_id:
          type: string
        org_id:
          type: string
          format: uuid
        trace_id:
          type: string
        parent_run_id:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/RunStatus"
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time

    CreateRunRequest:
      type: object
      required: [agent_id]
      properties:
        agent_id:
          type: string
        trace_id:
          type: string
        parent_run_id:
          type: string
          format: uuid
        metadata:
          type: object
          additionalProperties: true

    CompleteRunRequest:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [completed, failed]
        metadata:
          type: object
          additionalProperties: true

    # ── Event schemas ────────────────────────────────────────────────
    EventType:
      type: string
      enum:
        - AgentRunStarted
        - AgentRunCompleted
        - AgentRunFailed
        - DecisionStarted
        - AlternativeConsidered
        - EvidenceGathered
        - ReasoningStepCompleted
        - DecisionMade
        - DecisionRevised
        - ToolCallStarted
        - ToolCallCompleted
        - AgentHandoff
        - ConsensusRequested
        - ConflictDetected

    AgentEvent:
      type: object
      required: [id, run_id, org_id, event_type, sequence_num, occurred_at, agent_id, payload, created_at]
      properties:
        id:
          type: string
          format: uuid
        run_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        event_type:
          $ref: "#/components/schemas/EventType"
        sequence_num:
          type: integer
          format: int64
        occurred_at:
          type: string
          format: date-time
        agent_id:
          type: string
        payload:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time

    EventInput:
      type: object
      required: [event_type, payload]
      properties:
        event_type:
          $ref: "#/components/schemas/EventType"
        occurred_at:
          type: string
          format: date-time
        payload:
          type: object
          additionalProperties: true

    AppendEventsRequest:
      type: object
      required: [events]
      properties:
        events:
          type: array
          items:
            $ref: "#/components/schemas/EventInput"

    # ── Decision schemas ─────────────────────────────────────────────
    Decision:
      type: object
      required:
        - id
        - run_id
        - agent_id
        - org_id
        - decision_type
        - outcome
        - confidence
        - metadata
        - completeness_score
        - quality_score
        - valid_from
        - transaction_time
        - created_at
      properties:
        id:
          type: string
          format: uuid
        run_id:
          type: string
          format: uuid
        agent_id:
          type: string
        org_id:
          type: string
          format: uuid
        decision_type:
          type: string
        outcome:
          type: string
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
        reasoning:
          type: string
        metadata:
          type: object
          additionalProperties: true
        completeness_score:
          type: number
          format: float
          description: >
            Completeness score (0.0–1.0) measuring how thoroughly the trace was filled in at
            write time (reasoning length, alternatives, evidence, etc.). Does not measure
            whether the decision was correct or adopted.
        outcome_score:
          type: number
          format: float
          nullable: true
          description: >
            Outcome score (0.0–1.0) reflecting ground-truth assessment feedback.
            Computed as (correct + 0.5 * partially_correct) / total from the
            decision_assessments table. Null when no assessments exist. Updated
            on each new assessment via POST /v1/decisions/{id}/assess.
        quality_score:
          type: number
          format: float
          deprecated: true
          description: >
            Deprecated alias for completeness_score. Emitted alongside completeness_score for
            one release cycle. Use completeness_score in new code.
        precedent_ref:
          type: string
          format: uuid
        valid_from:
          type: string
          format: date-time
        valid_to:
          type: string
          format: date-time
        transaction_time:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        session_id:
          type: string
          format: uuid
          description: MCP or HTTP session that produced this decision.
        agent_context:
          type: object
          description: |
            Composite agent identity context with server/client namespace split.
            "server" contains values the server extracted or verified (MCP client info,
            roots, API key prefix). "client" contains self-reported values from tool
            parameters or request body (model, task, operator). Older decisions may
            have a flat structure (pre-namespace) — treat as "client" for compatibility.
          properties:
            server:
              type: object
              description: Server-extracted or verified context.
              properties:
                tool:
                  type: string
                  description: MCP client name or SDK User-Agent prefix.
                tool_version:
                  type: string
                  description: MCP client version or SDK version.
                roots:
                  type: array
                  items:
                    type: string
                  description: MCP roots URIs (file:// paths from client workspace).
                project:
                  type: string
                  description: Inferred project name from the first MCP root URI.
                api_key_prefix:
                  type: string
                  description: First 8 chars of the managed API key used.
              additionalProperties: true
            client:
              type: object
              description: Self-reported context from the calling agent.
              properties:
                model:
                  type: string
                  description: LLM model powering the agent.
                task:
                  type: string
                  description: What the agent was working on.
                operator:
                  type: string
                  description: Human-readable agent display name.
              additionalProperties: true
          additionalProperties: true
        api_key_id:
          type: string
          format: uuid
          description: Managed API key that authenticated this decision.
        agreement_count:
          type: integer
          description: |
            Number of decisions in this decision's embedding-similarity cluster whose
            outcomes agree (outcome cosine similarity ≥ 0.75). Computed at query time.
        conflict_count:
          type: integer
          description: |
            Number of open or acknowledged conflicts involving this decision.
            Computed at query time.
        consensus_weight:
          type: number
          format: float
          minimum: 0.5
          maximum: 1
          description: |
            0.5 + 0.5 × (agreement_count / max(1, agreement_count + conflict_count)).
            Range [0.5, 1.0]. Only present when at least one agreement or conflict exists.
            Not stored — computed at response time.
        alternatives:
          type: array
          items:
            $ref: "#/components/schemas/Alternative"
        evidence:
          type: array
          items:
            $ref: "#/components/schemas/Evidence"

    Alternative:
      type: object
      required: [id, decision_id, label, selected, metadata, created_at]
      properties:
        id:
          type: string
          format: uuid
        decision_id:
          type: string
          format: uuid
        label:
          type: string
        score:
          type: number
          format: float
        selected:
          type: boolean
        rejection_reason:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time

    SourceType:
      type: string
      pattern: '^[a-z][a-z0-9_]*$'
      description: |
        Type of evidence source. Common values: document, api_response,
        agent_output, user_input, search_result, tool_output, memory,
        database_query. Any lowercase alphanumeric string with underscores
        is accepted.
      example: "document"

    Evidence:
      type: object
      required: [id, decision_id, org_id, source_type, content, metadata, created_at]
      properties:
        id:
          type: string
          format: uuid
        decision_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        source_type:
          $ref: "#/components/schemas/SourceType"
        source_uri:
          type: string
        content:
          type: string
        relevance_score:
          type: number
          format: float
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time

    AssessmentSummary:
      type: object
      description: Aggregated counts of outcome assessments for a decision.
      properties:
        total:
          type: integer
          description: Total number of assessments.
        correct:
          type: integer
        incorrect:
          type: integer
        partially_correct:
          type: integer

    DecisionAssessment:
      type: object
      description: Explicit outcome feedback for a decision from an agent.
      required:
        - id
        - decision_id
        - org_id
        - assessor_agent_id
        - outcome
        - created_at
      properties:
        id:
          type: string
          format: uuid
        decision_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        assessor_agent_id:
          type: string
        outcome:
          type: string
          enum: [correct, incorrect, partially_correct]
        notes:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time

    DecisionConflict:
      type: object
      required:
        - conflict_kind
        - decision_a_id
        - decision_b_id
        - org_id
        - agent_a
        - agent_b
        - run_a
        - run_b
        - decision_type
        - outcome_a
        - outcome_b
        - confidence_a
        - confidence_b
        - decided_at_a
        - decided_at_b
        - detected_at
        - status
      properties:
        id:
          type: string
          format: uuid
        conflict_kind:
          type: string
          enum: [cross_agent, self_contradiction]
          description: Whether the conflict is between different agents or the same agent contradicting themselves.
        decision_a_id:
          type: string
          format: uuid
        decision_b_id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        agent_a:
          type: string
        agent_b:
          type: string
        run_a:
          type: string
          format: uuid
        run_b:
          type: string
          format: uuid
        decision_type:
          type: string
        outcome_a:
          type: string
        outcome_b:
          type: string
        confidence_a:
          type: number
          format: float
        confidence_b:
          type: number
          format: float
        reasoning_a:
          type: string
        reasoning_b:
          type: string
        decided_at_a:
          type: string
          format: date-time
        decided_at_b:
          type: string
          format: date-time
        detected_at:
          type: string
          format: date-time
        decision_type_a:
          type: string
          description: Decision type for decision A (semantic conflicts may have different types).
        decision_type_b:
          type: string
          description: Decision type for decision B.
        topic_similarity:
          type: number
          format: float
          description: Cosine similarity of full decision embeddings; how "about the same topic" they are.
        outcome_divergence:
          type: number
          format: float
          description: 1 minus outcome similarity; how much the outcomes differ.
        significance:
          type: number
          format: float
          description: topic_similarity × outcome_divergence × confidence_weight × temporal_decay.
        scoring_method:
          type: string
          enum: [embedding, text, claim, llm, llm_v2]
          description: How the conflict was detected (embedding = cosine similarity, claim = claim-level, llm_v2 = LLM-validated).
        explanation:
          type: string
          description: LLM-generated explanation of the conflict relationship.
        relationship:
          type: string
          enum: [contradiction, supersession, complementary, refinement, unrelated]
          description: LLM-classified relationship between the two decisions.
        category:
          type: string
          enum: [factual, assessment, strategic, temporal]
          description: Category of the conflict.
        severity:
          type: string
          enum: [critical, high, medium, low]
          description: Severity of the conflict.
        status:
          type: string
          enum: [open, acknowledged, resolved, wont_fix]
          description: Lifecycle status of the conflict.
        resolved_by:
          type: string
          description: Agent ID that resolved the conflict.
        resolved_at:
          type: string
          format: date-time
        resolution_note:
          type: string
          description: Explanation of how/why the conflict was resolved.
        resolution_decision_id:
          type: string
          format: uuid
          description: ID of the decision that resolved this conflict (from POST /v1/conflicts/{id}/resolve).
        confidence_weight:
          type: number
          format: float
          description: sqrt(confidence_a × confidence_b) scaling factor applied to significance.
        temporal_decay:
          type: number
          format: float
          description: exp(-lambda × days_between) scaling factor applied to significance.
        winning_decision_id:
          type: string
          format: uuid
          description: |
            ID of the decision judged to be correct when this conflict was adjudicated.
            Must be either decision_a_id or decision_b_id. Optional — resolution is
            valid without declaring a winner.
        claim_text_a:
          type: string
          description: |
            The specific claim fragment from decision A that produced the highest
            significance during claim-level scoring. Present only when scoring_method
            originated from claim-level analysis. NULL when the winning scoring
            method was not "claim".
        claim_text_b:
          type: string
          description: |
            The specific claim fragment from decision B that produced the highest
            significance during claim-level scoring. Present only when scoring_method
            originated from claim-level analysis. NULL when the winning scoring
            method was not "claim".

    ConflictDetail:
      description: |
        Extended conflict view returned by GET /v1/conflicts/{id}. Includes all
        DecisionConflict fields plus a lazily-computed resolution recommendation.
      allOf:
        - $ref: "#/components/schemas/DecisionConflict"
        - type: object
          properties:
            recommendation:
              $ref: "#/components/schemas/Recommendation"

    Recommendation:
      type: object
      description: |
        Lazily-computed suggestion for which decision should prevail in a conflict.
        Based on confidence delta, recency, agent win rate, and revision depth.
        Absent when the conflict is already resolved or signal strength is insufficient.
      required:
        - suggested_winner
        - reasons
        - confidence
      properties:
        suggested_winner:
          type: string
          format: uuid
          description: ID of the decision the system recommends as the winner.
        reasons:
          type: array
          items:
            type: string
          description: Human-readable explanations ordered by signal strength.
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Confidence in the recommendation (0.0–1.0).

    ConflictStatusUpdate:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [acknowledged, resolved, wont_fix]
        resolution_note:
          type: string
        winning_decision_id:
          type: string
          format: uuid
          description: |
            Optional. The decision judged to be correct. Must be decision_a_id or
            decision_b_id of the conflict. Only valid when status is "resolved".
            When omitted, the conflict is resolved without declaring a winner.

    ConflictGroupResolveRequest:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [resolved, wont_fix]
          description: Target status for all open/acknowledged conflicts in the group.
        resolution_note:
          type: string
          description: Explanation applied to every conflict in the group.
        winning_agent:
          type: string
          description: |
            Optional. Resolve all conflicts in favor of decisions from this agent.
            Only valid when status is "resolved". Each conflict's winning_decision_id
            is set to the decision from this agent (decision_a or decision_b).

    ConflictGroupResolveResult:
      type: object
      required: [group_id, status, resolved]
      properties:
        group_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [resolved, wont_fix]
        resolved:
          type: integer
          description: Number of conflicts that were resolved.

    AdjudicateConflictRequest:
      type: object
      required: [outcome]
      properties:
        outcome:
          type: string
          description: The adjudication outcome — what was decided to adjudicate the conflict.
        reasoning:
          type: string
          description: Why this adjudication was chosen.
        decision_type:
          type: string
          default: conflict_resolution
          description: Decision type for the adjudication trace (defaults to "conflict_resolution").
        winning_decision_id:
          type: string
          format: uuid
          description: |
            Optional. The decision judged to be correct. Must be decision_a_id or
            decision_b_id of the conflict being adjudicated. When omitted, the conflict
            is resolved without declaring a winner.

    # ── API Key schemas ─────────────────────────────────────────────
    APIKey:
      type: object
      required: [id, prefix, agent_id, org_id, label, created_by, created_at]
      properties:
        id:
          type: string
          format: uuid
        prefix:
          type: string
          description: First 8 hex chars of the raw key, for identification.
        agent_id:
          type: string
        org_id:
          type: string
          format: uuid
        label:
          type: string
          description: Human-readable label for this key.
        created_by:
          type: string
          description: Agent ID of who minted this key.
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        revoked_at:
          type: string
          format: date-time
          nullable: true

    CreateKeyRequest:
      type: object
      required: [agent_id]
      properties:
        agent_id:
          type: string
          description: The agent this key authenticates as.
        label:
          type: string
          description: Human-readable label (e.g. "Production MCP", "CI Runner").
        expires_at:
          type: string
          format: date-time
          description: Optional expiration timestamp.

    CreateKeyResponse:
      type: object
      required: [id, prefix, agent_id, label, raw_key, created_at]
      properties:
        id:
          type: string
          format: uuid
        prefix:
          type: string
        agent_id:
          type: string
        label:
          type: string
        raw_key:
          type: string
          description: The full API key. Shown only once — store it securely.
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          nullable: true

    RotateKeyResponse:
      type: object
      required: [new_key, revoked_key_id]
      properties:
        new_key:
          $ref: "#/components/schemas/CreateKeyResponse"
        revoked_key_id:
          type: string
          format: uuid

    UsageResponse:
      type: object
      required: [org_id, period, total_decisions, by_key, by_agent]
      properties:
        org_id:
          type: string
          format: uuid
        period:
          type: string
          description: Billing period (YYYY-MM).
        total_decisions:
          type: integer
          description: Total decisions in the period.
        by_key:
          type: array
          items:
            type: object
            properties:
              key_id:
                type: string
                format: uuid
                nullable: true
              prefix:
                type: string
              label:
                type: string
              agent_id:
                type: string
              decisions:
                type: integer
        by_agent:
          type: array
          items:
            type: object
            properties:
              agent_id:
                type: string
              decisions:
                type: integer

    # ── Trace schemas ────────────────────────────────────────────────
    TraceRequest:
      type: object
      required: [agent_id, decision]
      properties:
        agent_id:
          type: string
        trace_id:
          type: string
        decision:
          $ref: "#/components/schemas/TraceDecision"
        precedent_ref:
          type: string
          format: uuid
        metadata:
          type: object
          additionalProperties: true

    TraceDecision:
      type: object
      required: [decision_type, outcome, confidence]
      properties:
        decision_type:
          type: string
        outcome:
          type: string
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
        reasoning:
          type: string
        alternatives:
          type: array
          items:
            $ref: "#/components/schemas/TraceAlternative"
        evidence:
          type: array
          items:
            $ref: "#/components/schemas/TraceEvidence"

    TraceAlternative:
      type: object
      required: [label, selected]
      properties:
        label:
          type: string
        score:
          type: number
          format: float
        selected:
          type: boolean
        rejection_reason:
          type: string

    TraceEvidence:
      type: object
      required: [source_type, content]
      properties:
        source_type:
          type: string
        source_uri:
          type: string
        content:
          type: string
        relevance_score:
          type: number
          format: float

    # ── Query schemas ────────────────────────────────────────────────
    QueryFilters:
      type: object
      properties:
        agent_id:
          type: array
          items:
            type: string
        run_id:
          type: string
          format: uuid
        decision_type:
          type: string
        confidence_min:
          type: number
          format: float
          minimum: 0
          maximum: 1
        outcome:
          type: string
        time_range:
          $ref: "#/components/schemas/TimeRange"

    TimeRange:
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time

    QueryRequest:
      type: object
      required: [filters]
      properties:
        filters:
          $ref: "#/components/schemas/QueryFilters"
        include:
          type: array
          items:
            type: string
            enum: [alternatives, evidence]
          description: Related data to include in the response.
        order_by:
          type: string
        order_dir:
          type: string
          enum: [asc, desc]
        limit:
          type: integer
          minimum: 1
          maximum: 1000
        offset:
          type: integer
          minimum: 0

    TemporalQueryRequest:
      type: object
      required: [as_of, filters]
      properties:
        as_of:
          type: string
          format: date-time
          description: Point-in-time for bi-temporal query.
        filters:
          $ref: "#/components/schemas/QueryFilters"

    # ── Search schemas ───────────────────────────────────────────────
    SearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
        semantic:
          type: boolean
          default: false
        filters:
          $ref: "#/components/schemas/QueryFilters"
        limit:
          type: integer
          minimum: 1
          maximum: 1000

    SearchResult:
      type: object
      required: [decision, similarity_score]
      properties:
        decision:
          $ref: "#/components/schemas/Decision"
        similarity_score:
          type: number
          format: float
        qdrant_rank:
          type: integer
          description: >
            1-based position in the original Qdrant ANN results. Used as tie-breaker
            when adjusted scores are equal. Zero or absent for text-search fallback results.

    # ── Check schemas ────────────────────────────────────────────────
    CheckRequest:
      type: object
      required: [decision_type]
      properties:
        decision_type:
          type: string
        query:
          type: string
        agent_id:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 1000

    CheckResponse:
      type: object
      required: [has_precedent, decisions]
      properties:
        has_precedent:
          type: boolean
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        conflicts:
          type: array
          items:
            $ref: "#/components/schemas/DecisionConflict"

    # ── Health schemas ───────────────────────────────────────────────
    HealthResponse:
      type: object
      required: [status, version, postgres, uptime_seconds]
      properties:
        status:
          type: string
          enum: [healthy, unhealthy]
        version:
          type: string
        postgres:
          type: string
          enum: [connected, disconnected]
        qdrant:
          type: string
          enum: [connected, disconnected]
          description: Qdrant vector search status. Only present when Qdrant is configured.
        buffer_depth:
          type: integer
          description: Number of events currently buffered for batch insertion.
        buffer_status:
          type: string
          enum: [ok, high, critical]
          description: Health of the event buffer.
        sse_broker:
          type: string
          enum: [running]
          description: SSE broker status. Only present when the broker is active.
        uptime_seconds:
          type: integer
          format: int64

    # ── Inline response wrappers ─────────────────────────────────────
    # These represent the `data` field contents in APIResponse envelopes.

    TraceResponse:
      type: object
      required: [run_id, decision_id, event_count]
      properties:
        run_id:
          type: string
          format: uuid
        decision_id:
          type: string
          format: uuid
        event_count:
          type: integer

    AppendEventsResponse:
      type: object
      required: [accepted, event_ids]
      properties:
        accepted:
          type: integer
        event_ids:
          type: array
          items:
            type: string
            format: uuid

    GetRunResponse:
      type: object
      required: [run, events, decisions]
      properties:
        run:
          $ref: "#/components/schemas/AgentRun"
        events:
          type: array
          items:
            $ref: "#/components/schemas/AgentEvent"
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"

    QueryResponse:
      type: object
      required: [decisions, total, count, limit, offset]
      properties:
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        total:
          type: integer
        count:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    TemporalQueryResponse:
      type: object
      required: [as_of, decisions]
      properties:
        as_of:
          type: string
          format: date-time
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"

    AgentHistoryResponse:
      type: object
      required: [agent_id, decisions, total, limit, offset]
      properties:
        agent_id:
          type: string
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    RecentDecisionsResponse:
      type: object
      required: [decisions, total, count, limit]
      properties:
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        total:
          type: integer
        count:
          type: integer
        limit:
          type: integer

    ConflictsResponse:
      type: object
      required: [conflicts, total, limit, offset]
      properties:
        conflicts:
          type: array
          items:
            $ref: "#/components/schemas/DecisionConflict"
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    SearchResponse:
      type: object
      required: [results, total]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
        total:
          type: integer

    # ── Generic envelope wrappers (for typed $ref in path responses) ─
    APIResponse_AuthTokenResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/AuthTokenResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_ScopedTokenResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/ScopedTokenResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_Agent:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/Agent"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_AgentList:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Agent"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_AgentStats:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          properties:
            agent_id:
              type: string
            stats:
              $ref: "#/components/schemas/AgentStats"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_Decision:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/Decision"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_DeleteAgentResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/DeleteAgentResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_AgentRun:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/AgentRun"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_GetRunResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/GetRunResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_AppendEventsResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/AppendEventsResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_TraceResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/TraceResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_QueryResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/QueryResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_TemporalQueryResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/TemporalQueryResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_AgentHistoryResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/AgentHistoryResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_RecentDecisionsResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/RecentDecisionsResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_ConflictAnalytics:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/ConflictAnalytics"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    ConflictAnalytics:
      type: object
      required: [period, summary, by_agent_pair, by_decision_type, by_severity, trend]
      properties:
        period:
          type: object
          required: [start, end]
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        summary:
          type: object
          required: [total_detected, total_resolved, mean_time_to_resolution_hours, false_positive_rate]
          properties:
            total_detected:
              type: integer
            total_resolved:
              type: integer
            mean_time_to_resolution_hours:
              type: number
              nullable: true
            false_positive_rate:
              type: number
        by_agent_pair:
          type: array
          items:
            type: object
            required: [agent_a, agent_b, count, open, resolved]
            properties:
              agent_a:
                type: string
              agent_b:
                type: string
              count:
                type: integer
              open:
                type: integer
              resolved:
                type: integer
        by_decision_type:
          type: array
          items:
            type: object
            required: [decision_type, count, avg_significance]
            properties:
              decision_type:
                type: string
              count:
                type: integer
              avg_significance:
                type: number
        by_severity:
          type: array
          items:
            type: object
            required: [severity, count]
            properties:
              severity:
                type: string
                enum: [critical, high, medium, low]
              count:
                type: integer
        trend:
          type: array
          items:
            type: object
            required: [date, detected, resolved]
            properties:
              date:
                type: string
                format: date
              detected:
                type: integer
              resolved:
                type: integer

    APIResponse_ConflictsResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/ConflictsResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_CheckResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/CheckResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_SearchResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/SearchResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_AccessGrant:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/AccessGrant"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_KeyList:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          properties:
            keys:
              type: array
              items:
                $ref: "#/components/schemas/APIKey"
            total:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_HealthResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/HealthResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    RevisionsResponse:
      type: object
      required: [decision_id, revisions, count]
      properties:
        decision_id:
          type: string
          format: uuid
        revisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        count:
          type: integer

    APIResponse_RevisionsResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/RevisionsResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    VerifyResponse:
      type: object
      required: [decision_id, status]
      properties:
        decision_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [verified, tampered, no_hash, erased]
          description: |
            Integrity status. "erased" means GDPR tombstone erasure
            was applied; the hash covers the scrubbed content.
        valid:
          type: boolean
          description: Whether the stored content hash matches the recomputed hash.
        content_hash:
          type: string
          description: The hash stored in the database.
        original_hash:
          type: string
          description: Pre-erasure hash (only present when status is "erased").
        erased_at:
          type: string
          format: date-time
          description: When the erasure occurred (only present when status is "erased").
        erased_by:
          type: string
          description: Agent that performed the erasure (only present when status is "erased").
        message:
          type: string
          description: Explanation (only present when status is "no_hash").

    ErasureResponse:
      type: object
      required: [decision_id, erased_at, original_hash, erased_hash, alternatives_erased, evidence_erased]
      properties:
        decision_id:
          type: string
          format: uuid
        erased_at:
          type: string
          format: date-time
        original_hash:
          type: string
          description: The content hash before erasure.
        erased_hash:
          type: string
          description: The content hash recomputed over scrubbed fields.
        alternatives_erased:
          type: integer
          description: Number of alternatives rows scrubbed.
        evidence_erased:
          type: integer
          description: Number of evidence rows scrubbed.

    APIResponse_ErasureResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/ErasureResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    APIResponse_VerifyResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/VerifyResponse"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    TraceHealthMetrics:
      type: object
      required: [status, completeness, evidence, gaps]
      properties:
        status:
          type: string
          enum: [healthy, needs_attention, insufficient_data]
          description: Overall health status of the organization's decision traces.
        completeness:
          $ref: "#/components/schemas/CompletenessMetrics"
        evidence:
          $ref: "#/components/schemas/EvidenceMetrics"
        conflicts:
          $ref: "#/components/schemas/TraceHealthConflictMetrics"
        gaps:
          type: array
          items:
            type: string
          description: Up to 3 actionable improvement suggestions, ordered by severity.

    CompletenessMetrics:
      type: object
      required: [total_decisions, avg_quality, below_half, below_third, with_reasoning, reasoning_pct, with_alternatives, alternatives_pct]
      properties:
        total_decisions:
          type: integer
          description: Total number of active decisions.
        avg_quality:
          type: number
          format: double
          description: Average quality score across all decisions (0.0–1.0).
        below_half:
          type: integer
          description: Count of decisions with completeness_score < 0.5.
        below_third:
          type: integer
          description: Count of decisions with completeness_score < 0.33.
        with_reasoning:
          type: integer
          description: Count of decisions that include reasoning text.
        reasoning_pct:
          type: number
          format: double
          description: Percentage of decisions with reasoning (0–100).
        with_alternatives:
          type: integer
          description: Count of decisions that have at least one recorded alternative.
        alternatives_pct:
          type: number
          format: double
          description: Percentage of decisions with alternatives (0–100).

    EvidenceMetrics:
      type: object
      required: [total_decisions, total_records, avg_per_decision, with_evidence, without_evidence, coverage_pct]
      properties:
        total_decisions:
          type: integer
          description: Total number of active decisions.
        total_records:
          type: integer
          description: Total number of evidence records across all decisions.
        avg_per_decision:
          type: number
          format: double
          description: Average number of evidence records per decision.
        with_evidence:
          type: integer
          description: Count of decisions that have at least one evidence record.
        without_evidence:
          type: integer
          description: Count of decisions without any evidence records.
        coverage_pct:
          type: number
          format: double
          description: Percentage of decisions with evidence (0–100).

    TraceHealthConflictMetrics:
      type: object
      required: [total, open, acknowledged, resolved, wont_fix, resolved_pct]
      properties:
        total:
          type: integer
          description: Total number of detected conflicts.
        open:
          type: integer
          description: Number of unresolved conflicts.
        acknowledged:
          type: integer
          description: Number of acknowledged but not yet resolved conflicts.
        resolved:
          type: integer
          description: Number of resolved conflicts.
        wont_fix:
          type: integer
          description: Number of conflicts closed as won't fix.
        resolved_pct:
          type: number
          format: double
          description: Percentage of conflicts that have been resolved (0–100).

    ValidatePairRequest:
      type: object
      required: [outcome_a, outcome_b]
      properties:
        outcome_a:
          type: string
          description: Outcome text of decision A.
        outcome_b:
          type: string
          description: Outcome text of decision B.
        type_a:
          type: string
          description: Decision type for A (e.g. architecture, code_review).
        type_b:
          type: string
          description: Decision type for B.
        agent_a:
          type: string
          description: Agent ID for decision A.
        agent_b:
          type: string
          description: Agent ID for decision B.
        reasoning_a:
          type: string
          description: Reasoning text for decision A.
        reasoning_b:
          type: string
          description: Reasoning text for decision B.
        project_a:
          type: string
          description: Project name for decision A.
        project_b:
          type: string
          description: Project name for decision B.
        topic_similarity:
          type: number
          format: double
          description: Pre-computed topic similarity score (0–1).

    ValidatePairResponse:
      type: object
      required: [relationship, category, severity, explanation]
      properties:
        relationship:
          type: string
          enum: [contradiction, supersession, complementary, refinement, unrelated]
          description: Classified relationship between the two decisions.
        category:
          type: string
          enum: [factual, assessment, strategic, temporal]
          description: Category of the relationship.
        severity:
          type: string
          enum: [critical, high, medium, low]
          description: Severity if the relationship is a conflict.
        explanation:
          type: string
          description: Brief explanation of the classification.

    ConflictEvalResponse:
      type: object
      required: [metrics, results]
      properties:
        metrics:
          $ref: "#/components/schemas/ConflictEvalMetrics"
        results:
          type: array
          items:
            $ref: "#/components/schemas/ConflictEvalResult"

    ConflictEvalMetrics:
      type: object
      required: [total_pairs, errors, relationship_accuracy, conflict_precision, conflict_recall, conflict_f1, true_positives, false_positives, true_negatives, false_negatives, relationship_hits]
      properties:
        total_pairs:
          type: integer
          description: Total number of eval pairs run.
        errors:
          type: integer
          description: Number of pairs that errored during validation.
        relationship_accuracy:
          type: number
          format: double
          description: Fraction of pairs with exact relationship match.
        conflict_precision:
          type: number
          format: double
          description: Precision for binary conflict detection.
        conflict_recall:
          type: number
          format: double
          description: Recall for binary conflict detection.
        conflict_f1:
          type: number
          format: double
          description: F1 score for binary conflict detection.
        true_positives:
          type: integer
        false_positives:
          type: integer
        true_negatives:
          type: integer
        false_negatives:
          type: integer
        relationship_hits:
          type: integer
          description: Number of exact relationship matches.

    ConflictEvalResult:
      type: object
      required: [label, expected_relationship, actual_relationship, correct, conflict_expected, conflict_actual, explanation]
      properties:
        label:
          type: string
          description: Human-readable label for this eval pair.
        expected_relationship:
          type: string
          description: Ground truth relationship label.
        actual_relationship:
          type: string
          description: Relationship returned by the validator.
        correct:
          type: boolean
          description: Whether actual matched expected.
        conflict_expected:
          type: boolean
          description: Whether the expected relationship is a conflict.
        conflict_actual:
          type: boolean
          description: Whether the validator classified it as a conflict.
        explanation:
          type: string
          description: Validator's explanation for its classification.
        error:
          type: string
          description: Error message if the validation failed.

    # ── Org Settings schemas ─────────────────────────────────────────
    OrgSettingsData:
      type: object
      properties:
        conflict_resolution:
          $ref: "#/components/schemas/ConflictResolutionPolicy"

    ConflictResolutionPolicy:
      type: object
      required:
        - auto_resolve_after_days
        - auto_resolve_winner
        - auto_resolve_max_severity
      properties:
        auto_resolve_after_days:
          type: integer
          minimum: 1
          description: Number of days a conflict must be open before auto-resolution.
        auto_resolve_winner:
          type: string
          enum: [recency, confidence, consensus]
          description: Strategy for selecting the winning decision.
        auto_resolve_max_severity:
          type: string
          enum: [low, medium, high, critical]
          description: Maximum severity eligible for auto-resolution.
        never_auto_resolve_severities:
          type: array
          items:
            type: string
            enum: [low, medium, high, critical]
          description: Severities that are never auto-resolved.
        reopened_resolution_policy:
          type: string
          enum: [escalate]
          description: What happens when a conflict reopens a prior resolution.

    APIResponse_OrgSettingsData:
      type: object
      required: [data, meta]
      properties:
        data:
          $ref: "#/components/schemas/OrgSettingsData"
        meta:
          $ref: "#/components/schemas/ResponseMeta"