# 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.