Initial GeoIntel V1 foundation

docs/JOB_LIFECYCLE_CONTRACT.md

@@ -0,0 +1,64 @@
+# Job Lifecycle Contract
+
+GeoIntel uses background jobs for long-running geospatial and AI tasks.
+
+## Status Values
+- `queued`: job record exists but worker has not started.
+- `running`: worker is processing.
+- `completed`: output persisted and metrics available.
+- `failed`: processing stopped with a recoverable or unrecoverable error.
+- `cancelled`: user requested cancellation before completion.
+
+## Common Job Fields
+- id
+- project_id
+- job_type
+- status
+- progress_percent
+- current_step
+- parameters_json
+- result_json
+- error_json
+- created_at
+- started_at
+- finished_at
+
+## Job Types
+- raster_metadata
+- raster_clip
+- raster_tile
+- vector_metadata
+- vector_clip
+- object_detection
+- segmentation
+- qaqc
+- export_geojson
+- export_report
+
+## Progress Steps
+Object detection should use these steps:
+1. validate_input
+2. prepare_tiles
+3. load_model
+4. run_inference
+5. georeference_outputs
+6. persist_results
+7. calculate_metrics
+8. completed
+
+## Error Contract
+A failed job must store:
+```json
+{
+  "code": "RASTER_CRS_MISSING",
+  "message": "Raster CRS could not be determined.",
+  "recoverable": true,
+  "step": "validate_input"
+}
+```
+
+## Frontend Behavior
+- queued: show pending state.
+- running: show current step and progress.
+- completed: show outputs and actions.
+- failed: show error, details and retry where safe.