satellite-provider/_docs/02_document/tests/blackbox-tests.md

Blackbox Test Scenarios

BT-01: Single Tile Download

Trigger: GET /api/satellite/tiles/latlon?lat=47.461747&lon=37.647063&zoom=18 Precondition: Tile not in cache Expected: HTTP 200; JSON with zoomLevel=18, tileSizePixels=256, imageType="jpg", filePath matching pattern tiles/18/*/... Pass criterion: All fields present and correct values

BT-02: Tile Cache Reuse

Trigger: Same GET as BT-01 repeated Precondition: BT-01 completed (tile now cached) Expected: HTTP 200; same tile ID returned; no new file created Pass criterion: tile.Id matches first request's tile.Id

BT-03: Region Request (200m, zoom 18, no stitch)

Trigger: POST /api/satellite/request with lat=47.461747, lon=37.647063, sizeMeters=200, zoomLevel=18, stitchTiles=false Expected: HTTP 200 immediately; status transitions: pending → processing → completed Pass criterion: Final status="completed"; csvFilePath non-empty; summaryFilePath non-empty; tilesDownloaded + tilesReused > 0 Timeout: 240s

BT-04: Region Request (400m, zoom 17, no stitch)

Trigger: POST /api/satellite/request with lat=47.461747, lon=37.647063, sizeMeters=400, zoomLevel=17, stitchTiles=false Expected: Same as BT-03 Pass criterion: Same as BT-03 Timeout: 240s

BT-05: Region with Stitching (500m, zoom 18)

Trigger: POST /api/satellite/request with lat=47.461747, lon=37.647063, sizeMeters=500, zoomLevel=18, stitchTiles=true Expected: Completes with stitched image generated Pass criterion: status="completed"; stitched image file exists and size > 1024 bytes Timeout: 240s

BT-06: Simple Route Creation (2 points)

Trigger: POST /api/satellite/route with id=<new-Guid>, name=<unique>, 2 waypoints (48.276067,37.384458) → (48.270740,37.374029), regionSizeMeters=500, zoomLevel=18, requestMaps=false, createTilesZip=false. Post-AZ-809 (cycle 8) every [JsonRequired] axis must be present — see _docs/02_document/contracts/api/route-creation.md v1.0.0. Expected: HTTP 200 + route created with interpolated intermediate points. Pass criterion: totalPoints > 2; every point spacing ≤ 200m; first point type="original"; last point type="original"; intermediates type="intermediate".

BT-07: Route Retrieval by ID

Trigger: GET /api/satellite/route/{id} after BT-06 Expected: Same route returned with all points Pass criterion: route.Id matches; points count matches creation response

BT-08: Route with Map Processing

Trigger: POST /api/satellite/route with requestMaps=true, 2 points, regionSize=300 Expected: Route maps processed, stitched image and CSV created Pass criterion: mapsReady=true; stitchedImagePath non-empty; csvFilePath non-empty; stitched image > 1024 bytes Timeout: 180s

BT-09: Route with Tiles ZIP

Trigger: POST /api/satellite/route with requestMaps=true, createTilesZip=true, 2 points Expected: ZIP file created with tiles Pass criterion: tilesZipPath non-empty; ZIP > 1024 bytes; ZIP entry count = unique tiles in CSV; entries start with "tiles/"; path has ≥5 parts (directory structure preserved) Timeout: 180s

BT-10: Complex Route (10 points, maps)

Trigger: POST /api/satellite/route with 10 waypoints, requestMaps=true, regionSize=300 Expected: All points interpolated; map tiles processed Pass criterion: mapsReady=true; uniqueTileCount ≥ 10; stitched image > 1024 bytes Timeout: 240s

BT-11: Route with Geofences (10 points + 2 rectangles)

Trigger: POST /api/satellite/route with 10 waypoints + 2 geofence polygons, requestMaps=true Expected: Geofence regions created and processed Pass criterion: mapsReady=true; uniqueTileCount ≥ 10; stitched image > 1024 bytes; geofence regions linked to route Timeout: 240s

BT-12: Extended Route (20 points, maps)

Trigger: POST /api/satellite/route with 20 waypoints in separate geographic area, requestMaps=true Expected: Large route processed completely Pass criterion: mapsReady=true; uniqueTileCount ≥ 20; stitched image > 1024 bytes Timeout: 360s

Negative Scenarios

BT-N01: Invalid Coordinates (out of range)

Trigger: GET /api/satellite/tiles/latlon?lat=91&lon=181&zoom=18 Expected: Error response Pass criterion: HTTP 4xx or error in response body

BT-N02: Invalid Zoom Level

Trigger: GET /api/satellite/tiles/latlon?lat=47.46&lon=37.64&zoom=25 Expected: Error response Pass criterion: HTTP 4xx or error indicating invalid zoom

BT-N03: Route with < 2 Points

Trigger: POST /api/satellite/route with only 1 point (post-AZ-809 wire format: id/name/regionSizeMeters/zoomLevel/points/requestMaps/createTilesZip). Expected: HTTP 400 + ValidationProblemDetails per error-shape.md v1.0.0; errors["points"] map entry from CreateRouteRequestValidator. Pass criterion: HTTP 400; response body Content-Type: application/problem+json; errors["points"] mentions the [2, 500] count constraint. AC trace: AZ-809 AC-1 (rule 7).

BT-N04: Geofence with Invalid Coordinates (0,0) — superseded by AZ-809

Trigger: POST /api/satellite/route with geofence NW=(0,0) SE=(0,0). Expected: HTTP 400 + ValidationProblemDetails. Pre-AZ-809 behavior accepted (0,0) corners but caught the equal-corners case via the legacy RouteValidator. Post-AZ-809, GeofencePolygonValidator rejects equal corners because BOTH cross-field invariants (NW.Lat > SE.Lat and NW.Lon < SE.Lon) fail. Pass criterion: HTTP 400; errors["geofences.polygons[0].northWest"] contains both the lat and lon invariant messages. AC trace: AZ-809 AC-1 (rule 9, cross-field invariant).

BT-N05: Geofence with Inverted Corners — superseded by AZ-809

Trigger: POST /api/satellite/route with geofence NW.lat < SE.lat (NW south-of SE). Expected: HTTP 400 + ValidationProblemDetails. Post-AZ-809 the failure surfaces at errors["geofences.polygons[0].northWest"] with message "`northWest.lat` must be greater than `southEast.lat` (NW is north-of SE)". Pass criterion: HTTP 400; named error key matches the wire path; message is the cross-field invariant. AC trace: AZ-809 AC-1 (rule 9).

---

Cycle 2 — AZ-488 UAV Tile Upload (POST /api/satellite/upload)

All Cycle-2 UAV scenarios run with a JWT containing permissions: ["GPS"] (per AZ-487 + AZ-488). Files use the contract at _docs/02_document/contracts/api/uav-tile-upload.md v1.0.0; per-item correlation is by ordinal index between metadata array and IFormFileCollection.

BT-13: UAV Upload — Happy-Path 1-Item Batch Persists source='uav'

Trigger: POST /api/satellite/upload with a 1-item batch — a 256×256 JPEG (~50 KiB), capturedAt = now, valid coordinates inside the test region. Precondition: Empty tiles table for the chosen cell; valid GPS JWT. Expected: HTTP 200; response body has items[0].status == "accepted" and a non-empty tileId; a new row exists in tiles with source='uav', captured_at matching the request (UTC, ≤ 1 s drift), file_path == 'tiles/uav/{z}/{x}/{y}.jpg'; the file exists on disk at that path with the uploaded bytes. Pass criterion: All of the above true. AC trace: AZ-488 AC-1.

BT-14: UAV Upload — 3-Item Mixed Batch Returns Per-Item Results

Trigger: POST /api/satellite/upload with a 3-item batch where item-1 is a valid 256×256 JPEG, item-2 is a 512×512 JPEG (wrong dimensions), item-3 has PNG magic bytes (wrong format). Precondition: Empty tiles table; valid GPS JWT. Expected: HTTP 200; items[0].status == "accepted" with a tileId; items[1].status == "rejected" with rejectReason == "WRONG_DIMENSIONS"; items[2].status == "rejected" with rejectReason == "INVALID_FORMAT". Exactly one new row appears in tiles (for item-1 only). No file written for items 2 or 3. Pass criterion: status array matches [accepted, rejected, rejected] AND reasons match exactly AND COUNT(*) WHERE source='uav' == 1 for the test region. AC trace: AZ-488 AC-2, AC-7a, AC-7c.

BT-15: UAV Upload — Multi-Source Coexistence with google_maps

Trigger: Pre-seed tiles (raw INSERT) with a source='google_maps' row at (L, Ln, z=18, size_m=200) and captured_at = T1 = now − 2h. Then POST /api/satellite/upload with a UAV tile for the same cell and capturedAt = T2 = now. Precondition: AZ-484 migration 013 applied (5-column unique index in place); valid GPS JWT. Expected: HTTP 200; both rows exist in tiles after upload (no overwrite of the google_maps row); a follow-up GetByTileCoordinatesAsync(L, Ln, 18, 200) returns the source='uav' row (per AZ-484 selection rule: max captured_at across sources). Pass criterion: SELECT source FROM tiles WHERE ... returns both 'google_maps' AND 'uav'; the repository read returns the UAV row. AC trace: AZ-488 AC-3; cross-references AZ-484 AC-1 (storage Inv-3) and AZ-484 AC-2 (selection rule).

BT-16: UAV Upload — Same-Source UPSERT Collapses to One Row

Trigger: POST /api/satellite/upload with a UAV tile for cell (L, Ln, 18, 200) at capturedAt = T1 = now − 30m, then a second POST for the same cell at capturedAt = T2 = now with different image bytes (different seed). Precondition: Cell is empty for source='uav' before T1; valid GPS JWT. Expected: HTTP 200 for both calls. After the second call, exactly one source='uav' row remains for the cell with captured_at == T2; the JPEG at ./tiles/uav/{z}/{x}/{y}.jpg is overwritten with the T2 bytes. Any pre-existing source='google_maps' row is untouched. Pass criterion: SELECT COUNT(*) FROM tiles WHERE source='uav' AND (L, Ln, 18, 200) == 1 AND MAX(captured_at) ≈ T2 AND on-disk JPEG checksum matches the T2 upload. AC trace: AZ-488 AC-4; cross-references AZ-484 AC-3.

BT-17: UAV Upload — Quality-Gate Rule-Ordering Determinism

Trigger: POST /api/satellite/upload with a single item that violates BOTH Rule 1 (PNG magic instead of JPEG) AND Rule 3 (512×512 dimensions). Authenticated with GPS permission. Expected: HTTP 200; items[0].status == "rejected" with rejectReason == "INVALID_FORMAT" (Rule 1 fires first; Rule 3 never evaluated). Pass criterion: rejectReason equals exactly INVALID_FORMAT; never WRONG_DIMENSIONS. AC trace: AZ-488 AC-7; rule-ordering invariant from _docs/02_document/contracts/api/uav-tile-upload.md v1.0.0.

Cycle 2 — AZ-487 Endpoint Parity (existing endpoints with Bearer token)

BT-18: Existing Tile Endpoint Returns Identical Body with Valid Bearer

Trigger: GET /api/satellite/tiles/latlon?lat=47.461747&lon=37.647063&zoom=18 with a valid Bearer token. Precondition: Tile may or may not be cached. Expected: Response body is structurally identical to BT-01 (tileId, zoomLevel == 18, tileSizePixels == 256, imageType == "jpg", filePath matches tiles/18/*/*). Pass criterion: status == 200 AND BT-01's pass criterion AND no behavioral change vs pre-AZ-487 baseline. AC trace: AZ-487 AC-4 (handler unchanged); validates AZ-487 AC-8 (existing suite parity).

---

Cycle 5 — AZ-503 Tile Identity → UUIDv5 + integer UPSERT (foundation)

All Cycle-5 UAV scenarios reuse the AZ-488 envelope. The new observable surface is: a flightId field in UavTileMetadata, deterministic tileId / locationHash values, and a per-flight on-disk layout ./tiles/uav/{flight_id|none}/{z}/{x}/{y}.jpg. No new HTTP route or wire change beyond the optional metadata field.

BT-19: UAV Upload — Multi-Flight Coexistence with Shared location_hash

Trigger: POST /api/satellite/upload twice for the SAME (z=18, tile_x, tile_y, tile_size_meters) from two different flight_id values F1 ≠ F2 (each upload sends metadata.flightId = F, valid 256×256 JPEG, fresh capturedAt). Precondition: Empty tiles table for the chosen cell; valid GPS JWT. Expected: HTTP 200 for both calls. After the second call, exactly TWO rows exist in tiles for source='uav' at the cell — one per flight. Both rows share the same location_hash (deterministic per {z}/{x}/{y}); each has a distinct id (deterministic per {z}/{x}/{y}/uav/{flight_id}). On disk, two files exist at ./tiles/uav/{F1}/{z}/{x}/{y}.jpg and ./tiles/uav/{F2}/{z}/{x}/{y}.jpg; rm -rf ./tiles/uav/{F1}/ removes ONLY Flight F1's evidence. Pass criterion: SELECT COUNT(*) FROM tiles WHERE source='uav' AND (z,x,y,size_m)=(...) == 2 AND COUNT(DISTINCT location_hash) == 1 AND COUNT(DISTINCT id) == 2 AND COUNT(DISTINCT file_path) == 2 AND both files present on disk. AC trace: AZ-503 AC-3, AC-11.

BT-20: UAV Upload — Idempotent Re-Insert Preserves Deterministic tileId and content_sha256

Trigger: POST /api/satellite/upload for cell (z=18, x, y, size_m) with flightId = F and JPEG body B and capturedAt = T1. Repeat the SAME body and flightId with capturedAt = T2 > T1. Precondition: Empty tiles table for the cell; valid GPS JWT. Expected: HTTP 200 for both calls. Exactly ONE row exists for the cell after both inserts. The row's id is identical before and after the second insert (deterministic UUIDv5 from {z}/{x}/{y}/uav/{F}). updated_at advances to T2; created_at is NOT regenerated. content_sha256 equals SHA-256(B) externally computed; the second insert's content_sha256 matches the first (byte-identical body). Pass criterion: SELECT COUNT(*) == 1 AND id is stable AND content_sha256 == sha256(B) AND created_at unchanged AND updated_at == T2. AC trace: AZ-503 AC-2, AC-7.

BT-21: UAV Upload — Float-Rounded Coordinates Collapse to a Single Row

Trigger: POST /api/satellite/upload for cell (z=18, x, y, size_m) with latitude = 47.123456789012345 and flightId = F. Repeat with the SAME (x, y, z) but latitude recomputed from tile_center = TileToWorldPos(x, y, z) (slightly different float representation). Precondition: Empty tiles table for the cell; valid GPS JWT. Expected: HTTP 200 for both calls. Exactly ONE row results — the integer-only UPSERT conflict key (tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, ...)) triggers despite the float-different latitude values. Pass criterion: SELECT COUNT(*) FROM tiles WHERE source='uav' AND tile_zoom=18 AND tile_x=x AND tile_y=y AND tile_size_meters=size_m == 1. AC trace: AZ-503 AC-4.

BT-22: Migration 014 — Identity Columns Land and Backfill Is Deterministic

Trigger: Run dotnet ef migrations apply (via API container startup) against a DB with cycle-4 schema; then query information_schema.columns and pg_indexes for tiles. Precondition: DB starts with migration 013 applied (cycle 4 baseline); pgcrypto available. Expected: tiles table has flight_id uuid NULL, location_hash uuid NOT NULL, content_sha256 bytea NULL, legacy_id uuid NULL. idx_tiles_unique_identity exists as a UNIQUE index over (tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-...'::uuid)). AZ-484 index idx_tiles_unique_location_source is dropped. For any pre-existing row, location_hash equals uuidv5(TILE_NAMESPACE, '{tile_zoom}/{tile_x}/{tile_y}') byte-identically (validated against a SQL pg_temp.uuidv5 reference function). Pass criterion: All column / index assertions pass AND the deterministic backfill matches the reference function on 100% of sampled rows. AC trace: AZ-503 AC-8.

BT-23: Inventory Endpoint — Order Preserved Across Present/Absent Mix

Trigger: POST /api/satellite/tiles/inventory with a body of 25 interleaved (z, x, y) coords at zoom 18, where 12 of the 25 are seeded into tiles (mix of google_maps and per-flight uav rows) and 13 are absent. Valid JWT attached. Precondition: Migration 015 applied (tiles_leaflet_path index exists); rows seeded via TileRepository.AddAsync so location_hash is populated. Expected: HTTP 200; response body is a TileInventoryResponse with results.length == 25; entries appear in the same order as the request body; 12 entries have present=true with id / locationHash / capturedAt / source populated; 13 entries have present=false with only locationHash populated (UUIDv5 of "{z}/{x}/{y}"), id is null, and capturedAt / source / flightId / resolutionMPerPx are all null. Pass criterion: All ordering, presence, and field-shape invariants from tile-inventory.md v1.0.0 Inv-1..Inv-6 hold for every entry. AC trace: AZ-505 AC-1 (resolves AZ-503 AC-5 deferral).

BT-24: Leaflet Read Path — Most-Recent Selection Keyed on location_hash

Trigger: GET /tiles/{z}/{x}/{y} against a cell that has two seeded rows for the same (z, x, y): a google_maps row with captured_at = T - 2h and a uav row with captured_at = T - 30min (strictly newer) and a distinct flight_id. Precondition: Migration 015 applied; both rows persisted with their location_hash populated via Uuidv5.LocationHashForTile. Expected: The DB-level SELECT that TileRepository.GetByTileCoordinatesAsync runs (SELECT … FROM tiles WHERE location_hash = $1 ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1) returns exactly one row — the UAV row. Pass criterion: picked.id == uavId (the newer row wins); selection semantics are byte-identical to AZ-484 / AZ-503-foundation, only the access key changed from the (tile_zoom, tile_x, tile_y, tile_size_meters) 4-tuple to location_hash. AC trace: AZ-505 AC-2 (resolves AZ-503 AC-6 deferral).

BT-25: HTTP/2 Multiplexed Tile Reads on a Single TLS Connection

Trigger: A single HttpClient configured with SocketsHttpHandler { EnableMultipleHttp2Connections = false } + HttpVersion.Version20 + HttpVersionPolicy.RequestVersionExact issues 20 concurrent GET /tiles/{z}/{x}/{y} requests for the same well-known tile. Precondition: Kestrel configured with HttpProtocols.Http1AndHttp2; dev listener bound to https://+:8080 with a self-signed cert (./certs/api.pfx, generated by scripts/run-tests.sh); the integration-test container trusts the cert via /usr/local/share/ca-certificates/ + update-ca-certificates. ALPN advertises h2 and http/1.1. Expected: All 20 responses succeed with HTTP 200; each HttpResponseMessage.Version equals 2.0; per-tile ETag and Cache-Control headers are preserved unchanged from the HTTP/1.1 baseline; all 20 streams share a single TLS connection (enforced by EnableMultipleHttp2Connections = false). Pass criterion: 20/20 responses are Status=200, Version=2.0, with non-null ETag and non-null Cache-Control. Note (post-merge correction): Original AZ-505 wording was "dev plaintext endpoint" / h2c; switched to TLS+ALPN during the cycle-6 Run-Tests step because Kestrel silently downgrades Http1AndHttp2 to HTTP/1.1 over plaintext (ALPN cannot run unencrypted). See _docs/03_implementation/implementation_report_tile_inventory_cycle6.md → "Post-merge correction". AC trace: AZ-505 AC-5 (resolves AZ-503 AC-12 deferral).

BT-26: Inventory Endpoint — Request Validation

Trigger: Four POST /api/satellite/tiles/inventory calls, each exercising one validation rule. Precondition: API up; valid JWT attached except for the anonymous case. Expected:

• Both tiles and locationHashes populated → HTTP 400 with a descriptive detail per tile-inventory.md Inv-1.
• Neither tiles nor locationHashes populated → HTTP 400.
• tiles.length > 5000 or locationHashes.length > 5000 → HTTP 400 (the 5000 cap matches TileInventoryLimits.MaxEntriesPerRequest, Inv-7).
• No Authorization: Bearer … header → HTTP 401 before the handler runs (matches the .RequireAuthorization() baseline; same shape as SEC-05). Pass criterion: All four expected status codes returned; no response leaks server internals. AC trace: AZ-505 AC-6.

---

Cycle 7 — AZ-794 / AZ-795 / AZ-796 Strict Validation + z/x/y Rename

Cycle 7 hardens POST /api/satellite/tiles/inventory by combining (a) the OSM-convention rename of body fields from tileZoom/tileX/tileY to z/x/y (AZ-794), (b) the shared input-validation infrastructure (AZ-795 — FluentValidation + ValidationEndpointFilter<T> + GlobalExceptionHandler + JsonSerializerOptions.UnmappedMemberHandling.Disallow), and (c) the inventory endpoint's nine concrete validation rules (AZ-796). The cycle's wire-shape contract is tile-inventory.md v2.0.0; the failure-response contract is error-shape.md v1.0.0.

The cycle introduces no new HTTP routes. Functional positive coverage is unchanged from cycle 6 — TileInventoryTests.OrderingAndPresentAbsentShaping_AC1 and the rest of the AZ-505 suite continue to assert ordering, present/absent shaping, leaflet selection, HTTP/2, and the perf budget against the post-rename body shape. The new tests below cover the strict-rejection behaviour that pre-cycle-7 silently coerced.

BT-27: Inventory Endpoint — Nine Validation Rules with RFC 7807 ProblemDetails

Trigger: A family of POST /api/satellite/tiles/inventory calls, each violating exactly ONE validation rule from AZ-796 §"Required validations (9 rules)". One additional sub-case asserts the legacy tileZoom/tileX/tileY field names are now rejected (intersection of AZ-794 + AZ-796). Precondition: API up; valid JWT attached on every sub-case. error-shape.md v1.0.0 + tile-inventory.md v2.0.0 frozen. Expected: HTTP 400 with Content-Type: application/problem+json for every sub-case. The body conforms to the validation-failure shape from error-shape.md v1.0.0 (Inv-1 .. Inv-7); the errors map names the offending field path using the request body's camelCase. Sub-cases:

#	Rule	Trigger excerpt	Expected errors key	Test method
1	Body present	empty body (zero bytes, Content-Type: application/json)	(no errors map — framework-level ProblemDetails)	EmptyBody_Returns400
2a	XOR of tiles / locationHashes	{} (neither populated)	$	NeitherPopulated_Returns400
2b	XOR (both populated)	{"tiles":[…],"locationHashes":[…]}	$	BothPopulated_Returns400
3	tiles non-empty	{"tiles":[]}	$ (treated as not-populated by XOR)	EmptyTilesArray_Returns400
4	tiles ≤ MaxEntriesPerRequest (5000)	5001-entry tiles array	tiles	TilesOverCap_Returns400
5a	Required z on each entry	{"tiles":[{"x":1,"y":1}]}	path mentioning z	MissingZ_Returns400WithFieldPath
5b	Required x / y on each entry	{"tiles":[{"z":18}]}	(validator + JsonRequired report missing axes)	MissingXAndY_Returns400
6a	Non-negative axis	{"tiles":[{"z":18,"x":-1,"y":0}]}	tiles[0].x	NegativeAxis_Returns400
6b	Integer type	{"tiles":[{"z":"eighteen","x":1,"y":1}]}	path mentioning the axis	TypeMismatch_Returns400
7	z in slippy-map range 0..22	{"tiles":[{"z":30,"x":0,"y":0}]}	tiles[0].z; message mentions "between 0 and 22"	ZoomOutOfRange_Returns400WithFieldPath
8a	x < 2^z	{"tiles":[{"z":2,"x":4,"y":0}]}	tiles[0].x	XBeyondZoomBounds_Returns400
8b	y < 2^z	{"tiles":[{"z":0,"x":0,"y":1}]}	tiles[0].y	YBeyondZoomBounds_Returns400
9a	Unknown root field	{"unknownField":42,"tiles":[…]}	path mentioning unknownField	UnknownRootField_Returns400
9b	Unknown nested field on tile entry	{"tiles":[{"z":18,"x":1,"y":1,"foo":42}]}	path mentioning foo	UnknownNestedField_Returns400
9c	Legacy v1 names (tileZoom/tileX/tileY)	exact AZ-777 Phase 1 reproduction body	path mentioning tileZoom	OldV1FieldName_Returns400 (cross-listed under AZ-794)
pos	Happy path with z/x/y	{"tiles":[{"z":18,"x":1,"y":1}]}	HTTP 200 — no body shape change vs AZ-505 baseline	HappyPath_Returns200

Pass criterion: Every failure sub-case returns HTTP 400 with the expected errors key OR an equivalent RFC 7807 ProblemDetails for the empty-body case; the happy path returns HTTP 200. No sub-case leaks server-internal state (DB strings, secrets, stack traces) per error-shape.md Inv-5. AC trace: AZ-796 AC-1 (all 9 rules + ProblemDetails shape), AC-2 (happy path); AZ-794 AC-1 (positive z/x/y acceptance — sub-case pos), AZ-794 AC-2 (sub-case 9c proves the old names produce a structured 400, eliminating the silent-coerce-to-0 footgun); AZ-795 (epic-level — every sub-case exercises the shared ValidationEndpointFilter + GlobalExceptionHandler + UnmappedMemberHandling.Disallow infra). Notes: The 9 rules split across two enforcement layers — rules 5/6/9 are enforced by the deserializer (JsonRequired + UnmappedMemberHandling.Disallow + native JSON type validation, see AZ-795 shared infra) and surface as BadHttpRequestException → GlobalExceptionHandler.JsonException branch; rules 2/3/4/7/8 are enforced by InventoryRequestValidator (FluentValidation) via ValidationEndpointFilter<TileInventoryRequest>. Both paths produce identically-shaped ValidationProblemDetails bodies (error-shape.md v1.0.0 invariant).

---

Cycle 8 — AZ-808 / AZ-809 / AZ-810 / AZ-811 / AZ-812 Strict Validation Sweep + Region Rename

Cycle 8 extends the AZ-795 shared validation infrastructure (FluentValidation + ValidationEndpointFilter<T> + GlobalExceptionHandler + JsonSerializerOptions.UnmappedMemberHandling.Disallow) to the four remaining public-facing endpoints, and lands the OSM-convention Lat/Lon rename on the Region API in the same commit set. Every cycle-8 endpoint emits the same ValidationProblemDetails shape (error-shape.md v1.0.0) used by AZ-796. No new HTTP routes; existing positive coverage (BT-01..BT-18 region/route/tile flows, BT-13..BT-17 UAV upload, BT-N01..BT-N05 negatives) is preserved. The new tests below cover the strict-rejection behaviour that pre-cycle-8 either silently coerced (missing id → zero-Guid; unknown ?latitude= → lat=0) or accepted out-of-range (lat > 90, zoom > 22) values that downstream code couldn't render.

BT-28: Region Request Endpoint — Strict Validation + OSM Rename

Trigger: A family of POST /api/satellite/request calls. AZ-812's Lat/Lon rename ships in the same commit as AZ-808; every sub-case uses the post-rename wire shape {"id":"<guid>","lat":..,"lon":..,"sizeMeters":..,"zoomLevel":..,"stitchTiles":..}. Precondition: API up; valid JWT attached. error-shape.md v1.0.0 + region-request.md v1.0.0 frozen (v1.0.0 published directly with the post-AZ-812 names per AZ-812 AC-6 coordination). Expected: HTTP 400 with Content-Type: application/problem+json for every failure sub-case; HTTP 200 + RegionStatusResponse for the happy path. errors[] names the offending field path in request-body camelCase.

#	Rule	Trigger excerpt	Expected errors key	Test method
pos	Happy path with lat/lon	full valid body	HTTP 200 — body shape unchanged from pre-AZ-808 ({regionId,status})	HappyPath_Returns200
1	Empty body	zero bytes, Content-Type: application/json	(framework-level ProblemDetails)	EmptyBody_Returns400
2a	Required id (silent-coercion fix)	omit id entirely	id — message states id is required (NOT zero-Guid coercion)	Post_WithMissingId_ReturnsBadRequest
2b	Zero-Guid id	"id":"00000000-0000-0000-0000-000000000000"	id	ZeroGuidId_Returns400
3	lat in range [-90, 90]	"lat":91	lat	LatOutOfRange_Returns400
4	lon in range [-180, 180]	"lon":181	lon	LonOutOfRange_Returns400
5	sizeMeters in range [100, 10_000]	"sizeMeters":1000000	sizeMeters	SizeMetersOutOfRange_Returns400
6	zoomLevel in range [0, 22]	"zoomLevel":30	zoomLevel	ZoomOutOfRange_Returns400
7	Required stitchTiles	omit stitchTiles	stitchTiles	MissingStitchTiles_Returns400
8	Unknown root field (UnmappedMemberHandling.Disallow)	"debug":42	path mentioning debug	UnknownRootField_Returns400
9	Legacy v1 names (latitude/longitude)	exact AZ-777 Phase 2 reproduction body	path mentioning latitude (treated as unknown post-AZ-812)	OldLatLongNames_Returns400
10	Type mismatch on lat	"lat":"fifty"	path mentioning lat	LatTypeMismatch_Returns400

Pass criterion: Every failure sub-case returns HTTP 400 with the expected errors key OR an equivalent RFC 7807 body for the empty-body case; the happy path returns HTTP 200 + a non-empty regionId. AZ-812 AC-4 is verified by sub-cases pos (new names accepted) and 9 (old names rejected by UnmappedMemberHandling.Disallow) on the same endpoint. No regression in RegionRequestTests.cs (cycle 8 Step 11 — green). AC trace: AZ-808 AC-1 (8 rules + ProblemDetails shape), AC-2 (happy path); AZ-812 AC-2 (wire format end-to-end), AC-3 (existing happy-path tests pass — Step 11 green), AC-4 (post-rename accepted, pre-rename rejected — sub-cases pos + 9). Notes: The 8 validations split between the deserializer (rule 7 missing-required, rule 8 unknown-root, rule 10 type-mismatch — surface via GlobalExceptionHandler) and RegionRequestValidator (rules 2b/3/4/5/6 — surface via ValidationEndpointFilter<RequestRegionRequest>). The silent-coercion case (rule 2a) is the AZ-777 Phase 2 reproducer: pre-cycle-8 a missing id deserialized to Guid.Empty and the handler silently created a region with id 00000000-...; post-cycle-8 it fails-fast at the deserializer.

BT-29: Create Route Endpoint — Nested + Cross-Field Strict Validation

Trigger: A family of POST /api/satellite/route calls covering AZ-809's 14 rules. Bodies use the post-AZ-809 wire shape {id, name, description?, regionSizeMeters, zoomLevel, points: [{lat, lon}, …], requestMaps, createTilesZip, geofences?: {polygons: [{northWest, southEast}]}}. Precondition: API up; valid JWT attached. error-shape.md v1.0.0 + route-creation.md v1.0.0 frozen. Expected: HTTP 400 with Content-Type: application/problem+json for every failure sub-case; HTTP 200 + RouteResponse for the happy path. errors[] keys use the nested path (e.g. points[1].lat, geofences.polygons[0].northWest).

#	Rule	Trigger excerpt	Expected errors key	Test method
pos	Happy path (requestMaps=false, no background processing)	minimal 2-point valid body	HTTP 200 — body shape unchanged	HappyPath_Returns200
1	Empty body	zero bytes	(framework-level ProblemDetails)	EmptyBody_Returns400
2a	Required id (silent-coercion fix)	omit id	id is required (no zero-Guid coercion)	MissingId_Returns400
2b	Zero-Guid id	"id":"00000000-..."	id	ZeroGuidId_Returns400
3	Required name non-empty	"name":""	name	EmptyName_Returns400
5	regionSizeMeters in [100, 10_000]	1000000	regionSizeMeters	RegionSizeMetersOutOfRange_Returns400
6	zoomLevel in [0, 22]	30	zoomLevel	ZoomOutOfRange_Returns400
7	points count in [2, 500]	1-point array	points	PointsCountBelowMin_Returns400
8a	Per-point lat in [-90, 90]	points[1].lat=91	points[1].lat	PointLatOutOfRange_Returns400
8b	Per-point lon in [-180, 180]	points[1].lon=181	points[1].lon	PointLonOutOfRange_Returns400
9	Geofence cross-field invariant (NW.lat > SE.lat AND NW.lon < SE.lon)	NW.lat ≤ SE.lat	geofences.polygons[0].northWest	GeofenceNwSeInvariantViolated_Returns400
10	Required requestMaps (no defaulting)	omit requestMaps	requestMaps	MissingRequestMaps_Returns400
12	Cross-field: createTilesZip=true requires requestMaps=true	{createTilesZip:true, requestMaps:false}	top-level message (no per-field key)	CreateTilesZipRequiresRequestMaps_Returns400
13	Unknown root field	"debug":42	path mentioning debug	UnknownRootField_Returns400
14	Nested type mismatch	"points[0].lat":"fifty"	path mentioning points[0].lat	NestedTypeMismatch_Returns400

Pass criterion: Every failure sub-case returns HTTP 400 with the expected errors key OR an equivalent RFC 7807 body for the empty/cross-field cases; the happy path returns HTTP 200 + a non-empty routeId. No regression in RouteCreationTests.cs (cycle 8 Step 11 — green). The AZ-779-class footgun (silent coercion of missing id to zero-Guid creating untracked routes) is closed by sub-case 2a. AC trace: AZ-809 AC-1 (14 rules + ProblemDetails shape), AC-2 (happy path). Advisory ACs AC-9 (sizeMeters vs regionSizeMeters naming) and AC-10 (input lat/lon vs output latitude/longitude asymmetry) are explicitly not tested — surfaced to parent-suite team for follow-up only. Notes: The 14 rules split across three layers — deserializer (rules 3 type-mismatch, 13 unknown-root, 14 nested type mismatch, 10 missing-required), CreateRouteRequestValidator (rules 2b/5/6/7, plus orchestration of nested validators), RoutePointValidator (rules 8a/8b — applied per-element via RuleForEach(x => x.Points).SetValidator), GeofencePolygonValidator (rule 9 cross-field), and a top-level Must() (rule 12). Rule 4 (description length cap if present) is enforced by CreateRouteRequestValidator.RuleFor(x => x.Description).MaximumLength(...) and is not exercised by an explicit sub-case because the existing pos body omits description and there is no probe-confirmed footgun there. The cross-field rule 12 surfaces under a top-level errors map entry (no field key) per FluentValidation convention for RuleFor(x => x).Must(...).

BT-30: UAV Upload Metadata Endpoint — Multipart Strict Validation

Trigger: A family of POST /api/satellite/upload multipart calls covering AZ-810's 14 rules. The endpoint is multipart/form-data, so the validator wires through a custom UavUploadValidationFilter (NOT the generic ValidationEndpointFilter<T> used by JSON-body endpoints) which deserializes the metadata form field via the strict global JsonSerializerOptions and routes errors through three composed layers (deserializer → FluentValidation → envelope cross-field check). Precondition: API up; valid JWT with permissions:["GPS"] attached. error-shape.md v1.0.0 + uav-tile-upload.md v1.2.0 frozen. Expected: HTTP 400 with Content-Type: application/problem+json for every failure sub-case; HTTP 200 + per-item result list for the happy path (per-item file rejections still return HTTP 200 — file-byte semantics unchanged from AZ-488). errors[] keys are prefixed with metadata. (e.g. metadata.items[0].latitude) for FluentValidation-layer rules; deserializer-layer failures surface under errors["metadata"] (per UavUploadValidationFilter design — the deserializer doesn't know the per-field path inside the form value).

#	Rule	Layer	Trigger excerpt	Expected errors key	Test method
pos	Happy path	—	well-formed multipart envelope with valid 256×256 JPEG	HTTP 200, per-item status=accepted	HappyPath_Returns200
1	metadata form field present	deserializer	omit metadata field	metadata	MissingMetadataField_Returns400
2	metadata deserializes to UavTileBatchMetadataPayload	deserializer	"items":"notanarray"	metadata	MetadataNotAnObject_Returns400
3	metadata.items count in [1, 100]	FluentValidation	101-item array	metadata.items	OversizedItemsArray_Returns400
4	metadata.items count == file count (envelope cross-field)	envelope filter	2 items, 1 file	both metadata.items and files	ItemsFileCountMismatch_Returns400
5	per-item latitude in [-90, 90]	FluentValidation	items[1].latitude=91	metadata.items[1].latitude	LatitudeOutOfRange_Returns400
6	per-item longitude in [-180, 180]	FluentValidation	items[0].longitude=181	metadata.items[0].longitude	LongitudeOutOfRange_Returns400
7	per-item tileZoom in [0, 22]	FluentValidation	items[0].tileZoom=30	metadata.items[0].tileZoom	TileZoomOutOfRange_Returns400
8	per-item tileSizeMeters > 0	FluentValidation	items[0].tileSizeMeters=0	metadata.items[0].tileSizeMeters	TileSizeMetersZero_Returns400
9a	per-item capturedAt not in future (skew = 30s)	FluentValidation	capturedAt=UtcNow+1h	metadata.items[0].capturedAt	CapturedAtFuture_Returns400
9b	per-item capturedAt not older than MaxAgeDays (default 7d)	FluentValidation	capturedAt=UtcNow-60d	metadata.items[0].capturedAt	CapturedAtTooOld_Returns400
10	per-item required fields (latitude/longitude/tileZoom/tileSizeMeters/capturedAt) present ([JsonRequired])	deserializer	omit latitude from one item	metadata (deserializer-level; per-field path not available inside form value)	MissingRequiredField_Returns400
11	Unknown root field on UavTileBatchMetadataPayload	deserializer	"debug":42 at metadata root	metadata	UnknownRootField_Returns400
12	Unknown nested field on UavTileMetadata	deserializer	"altitude":100 on an item	metadata	UnknownItemField_Returns400
13	Type mismatch on per-item field	deserializer	"latitude":"fifty"	metadata	LatitudeTypeMismatch_Returns400

Pass criterion: Every failure sub-case returns HTTP 400 with the expected errors key. The happy path returns HTTP 200 + a per-item result list with status=accepted. Per-item file rejections (existing IUavTileQualityGate semantics: INVALID_FORMAT, WRONG_DIMENSIONS, SIZE_OUT_OF_BAND, CAPTURED_AT_FUTURE, CAPTURED_AT_TOO_OLD, IMAGE_TOO_UNIFORM) still return HTTP 200 with per-item status=rejected (AZ-488 contract preserved). AZ-810 AC-9 verified by full integration suite green at cycle 8 Step 11 (after the test-data clamp fix — see _docs/03_implementation/batch_04_cycle8_report.md AC-9 row + commit b763da3). AC trace: AZ-810 AC-1 (14 rules + ProblemDetails shape), AC-2 (happy path unchanged), AC-9 (no AZ-488 regression). Notes: This is the first endpoint where the validation infra had to step outside the generic ValidationEndpointFilter<T> — multipart form-data is not a JSON body, so the metadata field has to be extracted from IFormCollection and deserialized inside a custom filter (UavUploadValidationFilter). Three layers compose: (1) deserializer with JsonSerializerOptions.UnmappedMemberHandling.Disallow + [JsonRequired] — surfaces under errors["metadata"]; (2) UavTileBatchMetadataPayloadValidator + UavTileMetadataValidator (FluentValidation) — error paths prefixed with metadata.; (3) envelope cross-field check (items.Count == files.Count) inside the filter — surfaces under BOTH errors["metadata.items"] AND errors["files"]. The metadata. prefix and the bare-"metadata" key for deserializer-level errors are documented in _docs/02_document/contracts/api/uav-tile-upload.md v1.2.0 §Validation Rules.

BT-31: GET tiles/latlon — Query-Param Strict Validation + Unknown-Param Rejection

Trigger: A family of GET /api/satellite/tiles/latlon?lat=&lon=&zoom= calls covering AZ-811's 5 rules. The endpoint takes query parameters (not a JSON body), so the validator wires through a novel UnknownQueryParameterEndpointFilter (envelope filter, item 4 of AZ-811's implementation pattern) plus GetTileByLatLonQueryValidator (FluentValidation for the typed query params). Precondition: API up; valid JWT attached. error-shape.md v1.0.0 + tile-latlon.md v1.0.0 frozen. Expected: HTTP 400 with Content-Type: application/problem+json for every failure sub-case; HTTP 200 + DownloadTileResponse for the happy path. errors[] keys name the offending query parameter (e.g. lat).

#	Rule	Trigger excerpt	Expected errors key	Test method
pos	Happy path	?lat=47.46&lon=37.64&zoom=18	HTTP 200 — body shape unchanged	HappyPath_Returns200
1	lat in range [-90, 90]	?lat=91	lat	LatOutOfRange_Returns400
2	lon in range [-180, 180]	?lon=181	lon	LonOutOfRange_Returns400
3	zoom in range [0, 22]	?zoom=30	zoom	ZoomOutOfRange_Returns400
4a	lat required	omit ?lat=	lat ("lat is required")	MissingLat_Returns400
4b	Legacy v1 names (?Latitude=&Longitude=&ZoomLevel=)	exact pre-AZ-811 wire format	errors map names BOTH unknown keys	LegacyLatitudeLongitudeNames_Returns400
4c	Hostile / typo query keys	?debug=1&admin=true	errors map names BOTH unknown keys	UnknownQueryKeys_Returns400
5	lat type mismatch	?lat=fifty	lat	LatTypeMismatch_Returns400

Pass criterion: Every failure sub-case returns HTTP 400 with the expected errors key. The happy path returns HTTP 200 + a non-empty tileId and a path of shape tiles/{zoom}/{x}/{y}.jpg. No regression in TileByLatLonTests.cs (cycle 8 Step 11 — green). BT-N01 (lat=91&lon=181&zoom=18) and BT-N02 (zoom=25) — pre-cycle-8 negative scenarios that only asserted "HTTP 4xx or error in body" — are now strictly bound: BT-N01 produces HTTP 400 with errors["lat"] AND errors["lon"]; BT-N02 produces HTTP 400 with errors["zoom"]. AC trace: AZ-811 AC-1 (5 rules + ProblemDetails shape), AC-2 (happy path), AC-9 (the novel unknown-query-param envelope filter is documented in _docs/02_document/modules/api_program.md for reuse). Notes: This is the first endpoint to need a generic unknown-query-param rejection layer — ASP.NET's default model binder silently ignores unknown query parameters (parallel to UnmappedMemberHandling.Disallow for JSON bodies, but no built-in equivalent exists for query strings). The new UnknownQueryParameterEndpointFilter introspects the route's declared parameters and rejects any extra keys. Sub-cases 4b and 4c exercise this filter: 4b proves the pre-AZ-811 wire format (?Latitude=&Longitude=&ZoomLevel=) that silently fell back to lat=0, lon=0, zoom=0 now fails fast with HTTP 400 naming all three unknown keys; 4c proves the same path catches arbitrary hostile / typo keys. The filter is designed for reuse by any future query-param endpoint (AZ-811 AC-9).