openapi: 3.0.3
info:
  title: GNX Earsling Logic Engine API
  version: 1.0.0
  description: >
    Pre-output control API for ear-contact signal reliability verification.
    This API is for non-diagnostic verification, licensing review, examiner review,
    Evidence Packet retrieval, and evidence-based output control.
servers:
  - url: https://earsling.com
paths:
  /health/ready:
    get:
      summary: Readiness check
      responses:
        "200":
          description: Engine is ready
  /v1/policy:
    get:
      summary: Policy boundary and decision set
      responses:
        "200":
          description: Current policy boundary, fail-closed rules, and evidence fields
  /v1/examiner/claim-map:
    get:
      summary: Examiner claim-map review endpoint
      responses:
        "200":
          description: Claim element to verification point mapping
  /v1/license/package:
    get:
      summary: Licensee integration package endpoint
      responses:
        "200":
          description: API contract and integration principles for licensee review
  /v1/events/ingest:
    post:
      summary: Ingest device operation event
      responses:
        "200":
          description: Event accepted with audit receipt
  /v1/signal/evaluate:
    post:
      summary: Evaluate candidate signal and disturbance state
      responses:
        "200":
          description: Output-control decision
  /v1/output/decide:
    post:
      summary: Decide whether candidate value may be output
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                contactQuality:
                  type: number
                  minimum: 0
                  maximum: 1
                motion:
                  type: number
                  minimum: 0
                  maximum: 1
                heat:
                  type: number
                  minimum: 0
                  maximum: 1
                vibration:
                  type: number
                  minimum: 0
                  maximum: 1
                opticalNoise:
                  type: number
                  minimum: 0
                  maximum: 1
                electrodeNoise:
                  type: number
                  minimum: 0
                  maximum: 1
                communicationLoad:
                  type: number
                  minimum: 0
                  maximum: 1
                powerShift:
                  type: number
                  minimum: 0
                  maximum: 1
                requestRawValue:
                  type: boolean
      responses:
        "200":
          description: Pre-output control decision with Evidence Packet ID
  /v1/evidence/latest:
    get:
      summary: Retrieve latest Evidence Packet
      responses:
        "200":
          description: Latest Evidence Packet
  /v1/evidence/{id}:
    get:
      summary: Retrieve Evidence Packet
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Evidence Packet


  /proof:
    get:
      summary: Human Evidence Packet Proof Console
      responses:
        "200":
          description: Interactive proof console HTML


  /vault:
    get:
      summary: Human document vault
      responses:
        "200":
          description: Interactive document vault HTML

  /docs/manifest.json:
    get:
      summary: Public document manifest
      responses:
        "200":
          description: Vault document manifest


  /docs:
    get:
      summary: Human document listing hub
      responses:
        "200":
          description: Interactive docs listing HTML

  /docs/manifest.json:
    get:
      summary: Public docs manifest
      responses:
        "200":
          description: Docs manifest JSON
