Add vector change detection foundation

docs/API_CONTRACTS.md

@@ -795,7 +795,64 @@ If the segmentation run has no persisted geometries, the endpoint returns `SEGME
 
 ### POST `/api/v1/analysis/change-detection`
 
-Request contains source analysis or datasets A/B and method.
+Compares two persisted vector datasets in the same project and returns a synchronous
+job envelope. This is a lightweight V1 foundation for added/removed object review,
+not a temporal run-history engine.
+
+Request:
+
+```json
+{
+  "source_dataset_id": "uuid",
+  "target_dataset_id": "uuid",
+  "iou_threshold": 0.8,
+  "include_unchanged": true
+}
+```
+
+Response is a canonical API envelope containing a `JobRead` payload. On success,
+`result_json` contains:
+
+```json
+{
+  "source_dataset_id": "uuid",
+  "target_dataset_id": "uuid",
+  "source_feature_count": 2,
+  "target_feature_count": 2,
+  "added_count": 1,
+  "removed_count": 1,
+  "unchanged_count": 1,
+  "iou_threshold": 0.8,
+  "warnings": [],
+  "generated_at": "2026-06-16T00:00:00Z",
+  "geojson": {
+    "type": "FeatureCollection",
+    "features": []
+  }
+}
+```
+
+Change detection prefers persisted `vector_features`. If an older vector dataset
+has no persisted vector rows, it falls back to the stored GeoJSON artifact and
+adds a warning to `result_json.warnings`. Supported comparable geometry types are
+`Polygon` and `MultiPolygon`; point/line geometries return `UNSUPPORTED_GEOMETRY`.
+
+GeoJSON feature properties include:
+
+- `change_type`: `added`, `removed` or `unchanged`
+- `source_dataset_id`
+- `target_dataset_id`
+- `source_feature_id`
+- `target_feature_id`
+- `iou`
+
+Limitations:
+
+- No live GRB/OSM/Sentinel fetching.
+- No fake object lifecycle classification.
+- No `changed` classification without durable object ids/versioning.
+- No first-class change table yet; the current output is stored in job
+  `result_json` and rendered in the frontend map.
 
 ## QA/QC