# CreateWorkerEmployment

## Permission Scope

`employment`

## Overview

CreateWorkerEmployment opens an employment relationship for a Worker at an organization Company, creating the initial effective-dated generation bound to an EmploymentType and a WorkRegime catalog entry.

## Business Rules

- Every WorkerEmployment references exactly one Worker and exactly one organization Company
- The initial generation has `effectiveStart = hireDate` and `effectiveEnd = null`
- `employmentTypeId` references an EmploymentType catalog entry; it must belong to the same Company and be `ACTIVE`
- `workRegimeId` references a WorkRegime catalog entry; it must belong to the same Company and be `ACTIVE`
- Employment types and work regimes are catalog data (add a new one without a code change), not fixed enums
- A future-dated `hireDate` schedules the employment; it is not treated as active until that date
- A Worker may hold multiple concurrent employments across different Companies (future multi-entity seam, ADR-018)
- A Worker/Company pair may not have two concurrently-open WorkerEmployment generations; a new generation may only be opened once the prior one has an `effectiveEnd`

## Process Flow

```mermaid
flowchart TD
    A[Open employment: Worker, Company, hireDate, employmentTypeId, workRegimeId] --> B{Worker exists?}
    B -- No --> X[Reject: WORKER_NOT_FOUND]
    B -- Yes --> C{Company exists?}
    C -- No --> Y[Reject: COMPANY_NOT_FOUND]
    C -- Yes --> D{employmentTypeId an ACTIVE entry in this Company?}
    D -- No --> Z[Reject: INVALID_EMPLOYMENT_TYPE_REFERENCE]
    D -- Yes --> E{workRegimeId an ACTIVE entry in this Company?}
    E -- No --> V[Reject: INVALID_WORK_REGIME_REFERENCE]
    E -- Yes --> F{Open generation already exists for this Worker/Company?}
    F -- Yes --> W[Reject: EFFECTIVE_DATE_OVERLAPS_EXISTING_GENERATION]
    F -- No --> G[Create initial generation: effectiveStart = hireDate, effectiveEnd = null]
```

## External Dependencies

- [workforce::Worker](../model/Worker.md) model — the Worker being employed
- [workforce::EmploymentType](../model/EmploymentType.md) model — the employment type catalog
- [workforce::WorkRegime](../model/WorkRegime.md) model — the work regime catalog
- organization::Company (cross-module) — the legal entity employing the Worker

## Error Scenarios

- **WORKER_NOT_FOUND**: the specified Worker does not exist
- **COMPANY_NOT_FOUND**: the specified organization Company does not exist
- **INVALID_EMPLOYMENT_TYPE_REFERENCE**: `employmentTypeId` does not reference an ACTIVE EmploymentType in this Company
- **INVALID_WORK_REGIME_REFERENCE**: `workRegimeId` does not reference an ACTIVE WorkRegime in this Company
- **EFFECTIVE_DATE_OVERLAPS_EXISTING_GENERATION**: an open generation already exists for this Worker/Company pair

## Test Cases

- opening an employment creates a single open generation from the hire date
- a future-dated hire date is not returned as the current employment until its start date
- creating an employment for a non-existent Worker is rejected
- creating an employment at a non-existent Company is rejected
- creating an employment with an employment type outside the Company is rejected
- creating an employment with a work regime outside the Company is rejected
- creating an employment while an open generation already exists for the same Worker/Company is rejected