Initial public release

docs/specs/STATE_MACHINES.md

@@ -0,0 +1,108 @@
+# 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.