# State Machines

Use these states exactly. Do not invent ad-hoc alternatives.

## Dataset state machine

```text
CREATED
  ↓
UPLOADING
  ↓
UPLOADED
  ↓
VALIDATING
  ↓
METADATA_EXTRACTED
  ↓
READY
```

Failure states:

```text
VALIDATION_FAILED
METADATA_FAILED
PROCESSING_FAILED
REQUIRES_CRS
ARCHIVED
DELETED
```

Rules:

- `READY` means metadata and validation are good enough for compatible operations.
- `REQUIRES_CRS` blocks geospatial operations but may allow file inspection.
- `ARCHIVED` keeps data but hides it from active workflows.
- `DELETED` means logical deletion unless physical cleanup is explicitly run.

## AnalysisRun state machine

```text
QUEUED
  ↓
RUNNING
  ↓
SUCCEEDED
```

Failure/cancel states:

```text
FAILED
CANCELLED
PARTIAL
```

Rules:

- `PARTIAL` is allowed only when outputs are explicitly incomplete and marked as such.
- Failed runs must retain logs/error code.
- Retrying creates a new run unless retry semantics are explicitly implemented.

## Job state machine

```text
PENDING
  ↓
STARTED
  ↓
FINISHED
```

Failure states:

```text
FAILED
RETRYING
CANCELLED
TIMEOUT
```

## Export state machine

```text
REQUESTED
  ↓
GENERATING
  ↓
READY
```

Failure states:

```text
FAILED
EXPIRED
```

## Frontend page state model

Every data-driven page must handle:

- `empty`
- `loading`
- `ready`
- `error`
- `partial`
- `offline/unavailable` where external service is involved.