openapi: "3.1.0"
info:
  title: OmegaOS™ Kernel API
  version: "0.1.0-draft"
  description: |
    DRAFT SPECIFICATION FOR EVALUATION — not connected to a live production endpoint.

    This document describes the API surface of the OmegaOS™ Kernel decision engine
    as designed and documented. It is provided for technical evaluation by prospective
    pilot participants and procurement teams.

    Proof ≠ truth of inputs. This API produces cryptographic proof of decision processes,
    not assertions about the validity of external data.
  contact:
    name: HOVO Engineering
    email: contact@hovo.global
    url: https://hovo.global
  license:
    name: Proprietary
    url: https://hovo.global/terms

servers:
  - url: https://{customer-instance}
    description: On-premise deployment (customer infrastructure)
    variables:
      customer-instance:
        default: localhost:8080
        description: Customer-specific deployment URL

paths:
  /health:
    get:
      summary: Health check
      description: Returns runtime health status. No authentication required.
      operationId: getHealth
      tags: [System]
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [healthy]
                  version:
                    type: string
                    example: "0.1.0"
                  uptime_seconds:
                    type: integer
                    example: 86400

  /decisions/resolve:
    post:
      summary: Resolve a decision
      description: |
        Submit evidence and policy context for deterministic three-state resolution.
        Returns a trilean outcome (TRUE, FALSE, INDETERMINATE) with a signed evidence chain.
      operationId: resolveDecision
      tags: [Decisions]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [policy_id, evidence]
              properties:
                policy_id:
                  type: string
                  description: Policy rule set identifier
                  example: "pol-aml-standard-v2"
                evidence:
                  type: array
                  items:
                    type: object
                    required: [source, type, value]
                    properties:
                      source:
                        type: string
                        example: "kyc-provider"
                      type:
                        type: string
                        example: "identity-verification"
                      value:
                        type: object
                        description: Source-specific evidence payload
                context:
                  type: object
                  description: Optional metadata (tenant, user, session)
                  properties:
                    tenant_id:
                      type: string
                    operator_id:
                      type: string
      responses:
        "200":
          description: Decision resolved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionResult"
        "400":
          description: Invalid request (missing evidence or policy)
        "401":
          description: Unauthorized

  /decisions/{id}:
    get:
      summary: Retrieve a decision
      description: Retrieve a previously resolved decision by its unique identifier.
      operationId: getDecision
      tags: [Decisions]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: "dec-2026-0001"
      responses:
        "200":
          description: Decision found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionResult"
        "404":
          description: Decision not found

  /decisions/{id}/replay:
    get:
      summary: Replay a decision
      description: |
        Re-execute a historical decision using its original evidence and policy snapshot.
        Returns the replayed outcome and a verification hash confirming deterministic consistency.
      operationId: replayDecision
      tags: [Decisions]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: "dec-2026-0001"
      responses:
        "200":
          description: Replay completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  original:
                    $ref: "#/components/schemas/DecisionResult"
                  replayed:
                    $ref: "#/components/schemas/DecisionResult"
                  match:
                    type: boolean
                    description: Whether original and replayed outcomes are identical
                  verification_hash:
                    type: string
                    description: SHA-256 of concatenated original + replayed proof chains

  /decisions/{id}/evidence-pack:
    get:
      summary: Export evidence pack
      description: |
        Export the complete evidence pack for a decision, including input evidence,
        policy snapshot, evaluation trace, and proof chain. Suitable for offline
        verification and regulatory submission.
      operationId: exportEvidencePack
      tags: [Decisions]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: "dec-2026-0001"
        - name: format
          in: query
          schema:
            type: string
            enum: [jsonl, json]
            default: jsonl
      responses:
        "200":
          description: Evidence pack exported
          content:
            application/jsonl:
              schema:
                type: string
                description: JSONL-formatted evidence pack

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Tenant-scoped JWT issued during deployment

  schemas:
    DecisionResult:
      type: object
      properties:
        decision_id:
          type: string
          example: "dec-2026-0001"
        timestamp:
          type: string
          format: date-time
        policy_version:
          type: string
          example: "v1.2.0"
        outcome:
          type: string
          enum: [ALLOW, DENY, INDETERMINATE]
        trilean:
          type: string
          enum: ["TRUE", "FALSE", INDETERMINATE]
          description: K3 Kleene logic evaluation result
        evidence_count:
          type: integer
        input_hash:
          type: string
          description: SHA-256 of normalized input evidence
        replay_hash:
          type: string
          description: SHA-256 of the complete evaluation trace
        proof_chain:
          type: array
          items:
            type: object
            properties:
              step:
                type: string
              input_hash:
                type: string
              output_hash:
                type: string
              timestamp:
                type: string
                format: date-time

tags:
  - name: System
    description: Runtime health and configuration
  - name: Decisions
    description: Decision resolution, retrieval, replay, and evidence export
