{
  "$id": "https://stella.ops/schema/scanner-surface.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ScannerSurface",
  "description": "SCANNER-SURFACE-01 task contract defining scanner job execution, surface analysis, and result reporting",
  "type": "object",
  "oneOf": [
    { "$ref": "#/$defs/ScanTaskRequest" },
    { "$ref": "#/$defs/ScanTaskResult" },
    { "$ref": "#/$defs/ScanTaskProgress" }
  ],
  "$defs": {
    "ScanTaskRequest": {
      "type": "object",
      "required": ["taskType", "taskId", "subject", "surfaces"],
      "properties": {
        "taskType": {
          "type": "string",
          "const": "SCAN_REQUEST"
        },
        "taskId": {
          "type": "string",
          "format": "uuid",
          "description": "Unique task identifier"
        },
        "correlationId": {
          "type": "string",
          "description": "Correlation ID for tracing"
        },
        "tenantId": {
          "type": "string",
          "description": "Tenant scope"
        },
        "subject": {
          "$ref": "#/$defs/ScanSubject",
          "description": "Subject to scan"
        },
        "surfaces": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "VULNERABILITY",
              "SBOM",
              "SECRETS",
              "MALWARE",
              "COMPLIANCE",
              "LICENSE",
              "REACHABILITY"
            ]
          },
          "minItems": 1,
          "description": "Analysis surfaces to execute"
        },
        "options": {
          "$ref": "#/$defs/ScanOptions"
        },
        "priority": {
          "type": "string",
          "enum": ["LOW", "NORMAL", "HIGH", "CRITICAL"],
          "default": "NORMAL"
        },
        "deadline": {
          "type": "string",
          "format": "date-time",
          "description": "Optional deadline for task completion"
        }
      }
    },
    "ScanTaskResult": {
      "type": "object",
      "required": ["taskType", "taskId", "status", "completedAt"],
      "properties": {
        "taskType": {
          "type": "string",
          "const": "SCAN_RESULT"
        },
        "taskId": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "type": "string",
          "enum": ["COMPLETED", "FAILED", "PARTIAL", "CANCELLED"]
        },
        "completedAt": {
          "type": "string",
          "format": "date-time"
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0,
          "description": "Task duration in milliseconds"
        },
        "subject": {
          "$ref": "#/$defs/ScanSubject"
        },
        "surfaceResults": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SurfaceResult"
          }
        },
        "summary": {
          "$ref": "#/$defs/ScanSummary"
        },
        "artifacts": {
          "$ref": "#/$defs/ScanArtifacts"
        },
        "attestation": {
          "$ref": "#/$defs/AttestationRef"
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ScanError"
          }
        }
      }
    },
    "ScanTaskProgress": {
      "type": "object",
      "required": ["taskType", "taskId", "phase", "progressPercent"],
      "properties": {
        "taskType": {
          "type": "string",
          "const": "SCAN_PROGRESS"
        },
        "taskId": {
          "type": "string",
          "format": "uuid"
        },
        "phase": {
          "type": "string",
          "enum": [
            "QUEUED",
            "STARTING",
            "PULLING_IMAGE",
            "EXTRACTING",
            "ANALYZING",
            "CORRELATING",
            "FINALIZING"
          ]
        },
        "progressPercent": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "currentSurface": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "ScanSubject": {
      "type": "object",
      "required": ["type", "reference"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["IMAGE", "DIRECTORY", "ARCHIVE", "SBOM", "REPOSITORY"],
          "description": "Type of scan subject"
        },
        "reference": {
          "type": "string",
          "description": "Subject reference (image ref, path, etc.)"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Content digest if known"
        },
        "platform": {
          "type": "string",
          "description": "Target platform (linux/amd64, etc.)"
        },
        "credentials": {
          "$ref": "#/$defs/CredentialRef",
          "description": "Credentials for accessing subject"
        }
      }
    },
    "CredentialRef": {
      "type": "object",
      "properties": {
        "secretName": {
          "type": "string",
          "description": "Secret name for credential lookup"
        },
        "provider": {
          "type": "string",
          "enum": ["VAULT", "K8S_SECRET", "ENV", "FILE"]
        }
      }
    },
    "ScanOptions": {
      "type": "object",
      "properties": {
        "severityThreshold": {
          "type": "string",
          "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"],
          "description": "Minimum severity to report"
        },
        "includeUnfixed": {
          "type": "boolean",
          "default": true,
          "description": "Include vulnerabilities without fixes"
        },
        "sbomFormat": {
          "type": "string",
          "enum": ["SPDX_JSON", "CYCLONEDX_JSON", "SYFT_JSON"],
          "description": "SBOM output format"
        },
        "analyzers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Specific analyzers to run"
        },
        "skipAnalyzers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Analyzers to skip"
        },
        "layerAnalysis": {
          "type": "boolean",
          "default": false,
          "description": "Perform per-layer analysis"
        },
        "generateAttestation": {
          "type": "boolean",
          "default": true,
          "description": "Generate signed attestation"
        }
      }
    },
    "SurfaceResult": {
      "type": "object",
      "required": ["surface", "status"],
      "properties": {
        "surface": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": ["SUCCESS", "FAILED", "SKIPPED", "PARTIAL"]
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0
        },
        "artifactDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "findings": {
          "type": "object",
          "additionalProperties": true,
          "description": "Surface-specific findings summary"
        },
        "error": {
          "$ref": "#/$defs/ScanError"
        }
      }
    },
    "ScanSummary": {
      "type": "object",
      "properties": {
        "vulnerabilities": {
          "type": "object",
          "properties": {
            "critical": { "type": "integer", "minimum": 0 },
            "high": { "type": "integer", "minimum": 0 },
            "medium": { "type": "integer", "minimum": 0 },
            "low": { "type": "integer", "minimum": 0 },
            "unknown": { "type": "integer", "minimum": 0 }
          }
        },
        "packages": {
          "type": "integer",
          "minimum": 0,
          "description": "Total packages discovered"
        },
        "secretsDetected": {
          "type": "integer",
          "minimum": 0
        },
        "complianceViolations": {
          "type": "integer",
          "minimum": 0
        },
        "licenseIssues": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "ScanArtifacts": {
      "type": "object",
      "properties": {
        "sbom": {
          "$ref": "#/$defs/ArtifactRef"
        },
        "vulnerabilityReport": {
          "$ref": "#/$defs/ArtifactRef"
        },
        "secretsReport": {
          "$ref": "#/$defs/ArtifactRef"
        },
        "complianceReport": {
          "$ref": "#/$defs/ArtifactRef"
        },
        "reachabilityReport": {
          "$ref": "#/$defs/ArtifactRef"
        }
      }
    },
    "ArtifactRef": {
      "type": "object",
      "required": ["digest", "mediaType"],
      "properties": {
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "mediaType": {
          "type": "string"
        },
        "size": {
          "type": "integer",
          "minimum": 0
        },
        "location": {
          "type": "string",
          "format": "uri",
          "description": "Storage location"
        }
      }
    },
    "AttestationRef": {
      "type": "object",
      "properties": {
        "envelopeDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "predicateType": {
          "type": "string",
          "format": "uri"
        },
        "location": {
          "type": "string",
          "format": "uri"
        },
        "transparencyLog": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "ScanError": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "examples": [
            "IMAGE_PULL_FAILED",
            "ANALYZER_TIMEOUT",
            "INSUFFICIENT_RESOURCES",
            "INVALID_FORMAT"
          ]
        },
        "message": {
          "type": "string"
        },
        "surface": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean",
          "default": false
        }
      }
    }
  },
  "examples": [
    {
      "taskType": "SCAN_REQUEST",
      "taskId": "550e8400-e29b-41d4-a716-446655440000",
      "correlationId": "pipeline-run-abc123",
      "tenantId": "acme-corp",
      "subject": {
        "type": "IMAGE",
        "reference": "registry.example.com/app:v1.2.3",
        "platform": "linux/amd64"
      },
      "surfaces": ["VULNERABILITY", "SBOM", "SECRETS"],
      "options": {
        "severityThreshold": "LOW",
        "sbomFormat": "SPDX_JSON",
        "generateAttestation": true
      },
      "priority": "NORMAL"
    }
  ]
}