geointel/docs/specs/STATE_MACHINES.md

State Machines

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

Dataset state machine

CREATED
  ↓
UPLOADING
  ↓
UPLOADED
  ↓
VALIDATING
  ↓
METADATA_EXTRACTED
  ↓
READY

Failure states:

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

QUEUED
  ↓
RUNNING
  ↓
SUCCEEDED

Failure/cancel states:

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

PENDING
  ↓
STARTED
  ↓
FINISHED

Failure states:

FAILED
RETRYING
CANCELLED
TIMEOUT

Export state machine

REQUESTED
  ↓
GENERATING
  ↓
READY

Failure states:

FAILED
EXPIRED

Frontend page state model

Every data-driven page must handle:

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