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
 

docs/CODEX_EXECUTION_LOG.md

@@ -1,3 +1,22 @@
+## Sprint 18 vector change detection foundation (2026-06-16)
+
+Changed:
+- Added `POST /api/v1/analysis/change-detection` for comparing two vector datasets in the same project through the existing synchronous job envelope.
+- Added `ChangeDetectionService` with persisted `vector_features` as the primary source of comparable geometries and explicit stored-GeoJSON fallback warnings for older datasets.
+- Added frontend Change Detection controls, summary counts and MapLibre overlay styling for `added`, `removed` and `unchanged` feature properties.
+- Added backend tests for persisted-vector comparison and canonical API envelope behavior.
+
+Limitations:
+- The foundation classifies `added`, `removed` and `unchanged` only. It does not emit fake `changed` objects without durable object ids/versioning.
+- No migrations, live GRB/OSM/Sentinel fetching, AI inference, new dependencies, LiDAR, Copilot, Training Studio or separate Reports module were introduced.
+
+Validation:
+- `python -m compileall backend/app`
+- `cd backend && python -m pytest -W error::DeprecationWarning`
+- `cd frontend && npm run typecheck`
+- `cd frontend && npm run build`
+- `bash scripts/run_readiness_check.sh` via Git Bash on Windows
+- `cd backend && python -m alembic heads && python -m alembic upgrade head --sql`
 # Codex Execution Log
 
 This file must be updated by Codex after each implementation pass.

docs/TODO.md

@@ -159,9 +159,9 @@ This file now starts with the current implementation status. Older preparation/b
 ## 12. Change Detection
 
 - [ ] Compare two runs
-- [ ] Added/removed objects
-- [ ] Change stats
-- [ ] Change layer
+- [x] Added/removed objects
+- [x] Change stats
+- [x] Change layer
 
 ## 13. Tests