# Regression Traps

This document lists common failure modes Codex must actively avoid.

## Geospatial Traps

### CRS Loss

Never store or return geometries without CRS context. GeoJSON is usually WGS84 by convention, but source CRS must still be preserved in dataset metadata.

### Bounding Box Confusion

Never mix `[minx, miny, maxx, maxy]` with `[west, south, east, north]` without explicitly naming fields.

### Area Units

Never compute area in degrees. Reproject to an appropriate projected CRS before area or distance calculations. For Flanders/Kempen, prefer Belgian Lambert 72 / EPSG:31370 for metric calculations unless a stronger reason is documented.

### Raster/Vector Alignment

Never compare raster-derived outputs with vector reference layers without documenting resolution, CRS and alignment assumptions.

### Invalid Geometry

Always validate polygons. Attempt safe fixes only when documented; otherwise return a validation error.

## AI Traps

### Confidence Is Not Accuracy

Do not present model confidence as accuracy. Accuracy requires comparison against reference or labels.

### Fixture Detection Is Not Real AI

When using fixture/stub output, label it clearly as fixture/demo mode.

### Silent Model Fallback

Never silently fall back from real model inference to fixture mode. The response must indicate the mode used.

### Mask Polygonization Noise

Segmentation polygonization must include simplification/cleanup parameters and preserve original mask path.

## Backend Traps

### Long Work in Request Thread

Do not run heavy raster/AI operations synchronously inside request handlers. Use a job boundary.

### Inconsistent Status Values

Use the frozen status enum only: `queued`, `running`, `completed`, `failed`, `cancelled`.

### File Path Leakage

API responses may expose logical storage keys or download URLs, not arbitrary host paths.

## Frontend Traps

### UI-Only State

Do not create project, area, dataset or analysis state only in frontend memory. Persist via API.

### Empty Success Screens

Every page must distinguish loading, empty, error, ready and completed states.

### Map Layer Ambiguity

Every map layer must show source, timestamp, opacity, visibility and legend where applicable.

## Documentation Traps

### TODO Instead of Decision

Do not use TODO comments for architecture gaps. Either implement, document a limitation, or ask for a decision.

### Contract Drift

If code changes API responses, update contract docs and examples in the same pass.