ss-tools/specs/023-clean-repo-enterprise/contracts/api.yaml

openapi: 3.1.0
info:
  title: Clean Release Compliance API
  version: "1.0.0"
  description: >
    API contract for enterprise clean release validation in isolated corporate networks.
servers:
  - url: https://internal-api.company.local
paths:
  /api/clean-release/checks:
    post:
      summary: Start enterprise clean compliance check
      operationId: startCleanComplianceCheck
      tags: [clean-release]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartCheckRequest'
            examples:
              enterpriseClean:
                value:
                  candidate_id: "2026.03.03-rc1"
                  profile: "enterprise-clean"
                  execution_mode: "tui"
      responses:
        "202":
          description: Check run accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartCheckResponse'
        "400":
          description: Invalid request
        "403":
          description: Forbidden
        "409":
          description: Candidate is not eligible for check
  /api/clean-release/checks/{check_run_id}:
    get:
      summary: Get compliance check status
      operationId: getCleanComplianceStatus
      tags: [clean-release]
      parameters:
        - name: check_run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Current check status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckStatusResponse'
        "404":
          description: Check run not found
  /api/clean-release/reports/{report_id}:
    get:
      summary: Get compliance report
      operationId: getCleanComplianceReport
      tags: [clean-release]
      parameters:
        - name: report_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Compliance report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceReportResponse'
        "404":
          description: Report not found

components:
  schemas:
    StartCheckRequest:
      type: object
      required: [candidate_id, profile, execution_mode]
      properties:
        candidate_id:
          type: string
        profile:
          type: string
          enum: [enterprise-clean, development]
        execution_mode:
          type: string
          enum: [tui, ci]
    StartCheckResponse:
      type: object
      required: [check_run_id, candidate_id, status, started_at]
      properties:
        check_run_id:
          type: string
        candidate_id:
          type: string
        status:
          type: string
          enum: [running]
        started_at:
          type: string
          format: date-time

    CheckStageResult:
      type: object
      required: [stage, status]
      properties:
        stage:
          type: string
          enum: [data_purity, internal_sources_only, no_external_endpoints, manifest_consistency]
        status:
          type: string
          enum: [pass, fail, skipped]
        details:
          type: string
        duration_ms:
          type: integer
          minimum: 0

    Violation:
      type: object
      required: [violation_id, category, severity, location, remediation, blocked_release]
      properties:
        violation_id:
          type: string
        category:
          type: string
          enum: [data-purity, external-source, manifest-integrity, policy-conflict, operational-risk]
        severity:
          type: string
          enum: [critical, high, medium, low]
        location:
          type: string
        evidence:
          type: string
        remediation:
          type: string
        blocked_release:
          type: boolean
        detected_at:
          type: string
          format: date-time

    CheckStatusResponse:
      type: object
      required: [check_run_id, candidate_id, final_status, checks]
      properties:
        check_run_id:
          type: string
        candidate_id:
          type: string
        final_status:
          type: string
          enum: [running, compliant, blocked, failed]
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        checks:
          type: array
          items:
            $ref: '#/components/schemas/CheckStageResult'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'

    ComplianceReportResponse:
      type: object
      required:
        [report_id, check_run_id, candidate_id, generated_at, final_status, operator_summary, violations_count, blocking_violations_count]
      properties:
        report_id:
          type: string
        check_run_id:
          type: string
        candidate_id:
          type: string
        generated_at:
          type: string
          format: date-time
        final_status:
          type: string
          enum: [compliant, blocked, failed]
        operator_summary:
          type: string
        structured_payload_ref:
          type: string
        violations_count:
          type: integer
          minimum: 0
        blocking_violations_count:
          type: integer
          minimum: 0
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'