# CreatePipelineLabel

## Permission Scope

label

## Overview

Creates a new label on a pipeline. The label can then be attached to items within the same pipeline via AttachLabelToPipelineItem.

## Business Rules

- Pipeline must exist
- Pipeline must be ACTIVE (not ARCHIVED)
- Name is required and must be non-empty
- Name must be unique within the pipeline
- Color is optional
- Description is optional
- Consumer extension fields (declared via the `fields` extension point) are passed through to the insert

## Process Flow

```mermaid
flowchart TD
    A[Receive createPipelineLabel input] --> B{Pipeline exists?}
    B -->|No| C[Return PIPELINE_NOT_FOUND]
    B -->|Yes| D{Pipeline ACTIVE?}
    D -->|No| E[Return PIPELINE_ARCHIVED]
    D -->|Yes| F{Name non-empty?}
    F -->|No| G[Return INVALID_NAME]
    F -->|Yes| H{Name unique within pipeline?}
    H -->|No| I[Return DUPLICATE_LABEL_NAME]
    H -->|Yes| J[Persist PipelineLabel]
    J --> K[Return created PipelineLabel]
```

## External Dependencies

- None

## Error Scenarios

- **PIPELINE_NOT_FOUND**: Specified pipeline ID does not exist
- **PIPELINE_ARCHIVED**: Pipeline is archived
- **INVALID_NAME**: Name is empty or blank
- **DUPLICATE_LABEL_NAME**: A label with the same name already exists on the pipeline

## Test Cases

- creates a label on an active pipeline
- returns error when pipeline not found
- returns error when pipeline is archived
- returns error when name is empty
- returns error when label name duplicates another on the same pipeline