azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 05:41:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: azaion/satellite-provider:865dfdb3b9c18505266a32357e2e65ed498a6029
Branches Tags
azaion/satellite-provider:main azaion/satellite-provider:dev azaion/satellite-provider:stage
...
compare: azaion/satellite-provider:a49f6c941ba898537f51132305c2fd0df4a80fe8
Branches Tags
azaion/satellite-provider:dev azaion/satellite-provider:main azaion/satellite-provider:stage

3 Commits
865dfdb3b9 ... a49f6c941b

Author SHA1 Message Date
Oleksandr Bezdieniezhnykh a49f6c941b [AZ-794] [AZ-795] [AZ-796] Cycle 7 Step 17: retrospective + close cycle
ci/woodpecker/push/01-test Pipeline was successful
Details
ci/woodpecker/push/02-build-push Pipeline was successful
Details 
Cycle 7 retrospective (cycle-end mode) — three-task pure-quality
cycle (AZ-794 rename + AZ-795 epic shared infra + AZ-796 inventory
validator). PASS gate end-to-end; first cycle to ship a contract
MAJOR bump; second consecutive cycle with zero new process
leftovers; first cycle to run the full 5-phase security audit
since cycle 5.

Top 3 improvement actions for cycle 8:
1. Formalise the implement-skill <-> downstream-skill artifact
   contract — cycle 7 shipped without an implementation report
   and the doc / test-spec / retrospective skills successfully
   fell back to task-spec + commit-body reading, but the
   fallback is implicit and should be codified.
2. Sanitize JsonException.Message + BadHttpRequestException.Message
   before surfacing them in ValidationProblemDetails.detail —
   F-AZ795-1 / F-AZ795-2 in the cycle-7 security audit.
3. AZ-795 child-task sweep across the remaining public endpoints
   (request / route / upload / latlon) using AZ-796 as the
   reference pattern; 2-3 SP per endpoint, spread across cycles
   8-10.

LESSONS.md ring buffer updated with 3 cycle-7 entries (process /
testing / architecture); 3 oldest cycle-2 entries dropped to
maintain the 15-entry buffer.

State pointer advanced to cycle 8 step 9 (New Task) — Re-Entry
After Completion per autodev existing-code flow.

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-05-22 11:24:52 +03:00
Oleksandr Bezdieniezhnykh 30d99e09ad [AZ-794] [AZ-795] [AZ-796] Cycle 7 Step 16 deploy report 
Cycle 7 is a pure-quality cycle: no migrations, no new endpoints,
no new env vars, unchanged container image base. The full shipping
payload is a contract MAJOR bump (tile-inventory.md 1.0.0 -> 2.0.0,
breaking) plus a new strict-validation surface across the inventory
endpoint.

Deploy report covers:
- 3 cycle-7 commits (task adoption, implementation, sync) + this
  one + the pending close commit.
- Zero migrations; tiles schema unchanged from cycle 6.
- Postgres host-port move 5432 -> 5433 (dev-only sibling-conflict
  avoidance; staging/prod unaffected).
- Two NuGet additions (FluentValidation 12.0.0 +
  .DependencyInjectionExtensions 12.0.0), both CVE-clean.
- 5 verification gates: tests PASS, test-spec sync PASS, docs
  PASS, security PASS_WITH_WARNINGS (3 Low), perf PASS (9/9 incl.
  PT-09 v2 smoke).
- 4 NEW cycle-7 recommended follow-ups (D-AZ795-1 FV bump;
  F-AZ795-1/2 message sanitisation; implementation-report
  exit-gate contract; AZ-795 child-task sweep for remaining
  public endpoints).
- Zero new process leftovers; cycle 5/6 carry-overs unchanged.

Step 16.5 (Release) skipped per the cycle-2-to-6 convention; the
operator runbook in this deploy report serves as the release
record. User-confirmed via Choose A/B/C at the Step 16.5 gate.

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-05-22 11:24:39 +03:00
Oleksandr Bezdieniezhnykh bc04ba7f99 [AZ-794] [AZ-795] [AZ-796] Cycle 7 Steps 12-15 sync (test-spec / docs / security / perf) 
Step 12 (Test-Spec Sync): adds BT-27 for the AZ-796 9-rule
validation surface and 12 cycle-7 AC rows + Coverage Summary
update to traceability-matrix.md.

Step 13 (Update Docs): module-layout + module docs for the new
SatelliteProvider.Api/Validators namespace + GlobalExceptionHandler
+ updated TileInventory DTO; tests_unit + tests_integration
document the new InventoryRequestValidatorTests (16 unit tests
covering all 9 rules) + TileInventoryValidationTests (16
integration tests) + ProblemDetailsAssertions support;
glossary entries for Validation Problem Details / FluentValidation
/ Unmapped Member Handling; system-flows F8 (Tile Inventory Bulk
Lookup) expanded with deserializer + validator gates and a 13-row
Validation Surface table; data_parameters § Tile Inventory
documents the v2 input schema + constraints; ripple_log_cycle7
captures the doc-side ripple decisions.

Step 14 (Security Audit): 5-phase audit ran; verdict
PASS_WITH_WARNINGS (3 Low findings — D-AZ795-1 FluentValidation
12.0.0 -> 12.1.1 recommended bump, F-AZ795-1 JsonException.Message
leak in 400 detail, F-AZ795-2 BadHttpRequestException.Message leak).
No Critical / High; auth runs before validation (confirmed in
Program.cs); two NuGet additions (FluentValidation 12.0.0 +
.DependencyInjectionExtensions 12.0.0) both CVE-clean. Per-phase
reports plus consolidated security_report_cycle7.md.

Step 15 (Performance Test): docker compose stack used for perf
run, scripts/run-performance-tests.sh exited 0 with 8/8 scenarios
PASS (second consecutive clean exit-0); added PT-09 cycle-7 smoke
probe (v2 z/x/y schema, 2500-tile all-miss batch) measuring
min=27ms median=44ms p95=73ms max=86ms (13.7x under AZ-505 AC-4
1000ms budget). PT-07/08 improvements traced to the cycle-6 TLS
handshake-overhead identification, not application-side change.

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-05-22 11:24:27 +03:00
21 changed files with 1136 additions and 45 deletions
Expand all files Collapse all files
_docs/00_problem/data_parameters.md
+12
View File
@@ -10,6 +10,18 @@
| longitude | double | yes | -180 to 180 | Center longitude |
| zoomLevel | int | yes | 1–20 | Google Maps zoom level |
### API Request: Tile Inventory — `POST /api/satellite/tiles/inventory` (AZ-505; renamed AZ-794, strict-validated AZ-796 — cycle 7)
Exactly one of `tiles` OR `locationHashes` must be populated and non-empty. Strict input validation enforced by `InventoryRequestValidator` + `System.Text.Json` (`UnmappedMemberHandling.Disallow`); failures return HTTP 400 + `ValidationProblemDetails` per `_docs/02_document/contracts/api/error-shape.md` v1.0.0.
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| tiles | array | XOR (vs `locationHashes`) | 1 ≤ count ≤ 5000 | Form A: coords-by-value batch |
| tiles[].z | int | yes (`[JsonRequired]`) | 0–22 (slippy zoom range) | Slippy zoom level (renamed from `tileZoom` by AZ-794) |
| tiles[].x | int | yes (`[JsonRequired]`) | 0 ≤ x < 2^z | Slippy x at that zoom (renamed from `tileX` by AZ-794) |
| tiles[].y | int | yes (`[JsonRequired]`) | 0 ≤ y < 2^z | Slippy y at that zoom (renamed from `tileY` by AZ-794) |
| locationHashes | array | XOR (vs `tiles`) | 1 ≤ count ≤ 5000 | Form B: hashes-by-reference batch (UUIDv5 of `"{z}/{x}/{y}"`) |
### API Request: Region
| Parameter | Type | Required | Constraints | Description |
_docs/02_document/glossary.md
+4 -1
View File
@@ -14,7 +14,7 @@
| Layer 1 | Historic name for satellite imagery from external providers (provider-agnostic; first implementation: Google Maps). Generalised in AZ-484 to one of N values of `Tile Source`; the term is retained for continuity with earlier docs and tickets. | user clarification, AZ-484 |
| Layer 2 | Historic name for UAV-captured nadir camera imagery (orthogonal tiles uploaded post-flight). Generalised in AZ-484 to the `uav` `Tile Source` value; the term is retained for continuity with earlier docs and tickets. | user clarification, AZ-484 |
| Tile Source | The producer of a tile row, persisted in `tiles.source` as a contract-defined string (`google_maps`, `uav`, …). Per AZ-503-foundation: each `(cell, source, flight)` triple may have at most one row; reads return the most-recent across sources AND flights. Adding a new source requires a new `TileSource` enum member and a tile-storage contract version bump. | _docs/02_document/contracts/data-access/tile-storage.md (v2.0.0) |
| Tile Inventory | AZ-505 bulk read endpoint (`POST /api/satellite/tiles/inventory`) that returns one metadata entry per requested cell — present/absent + most-recent row's `id`/`capturedAt`/`source`/`flightId`/`resolutionMPerPx` — without streaming any tile bodies. Accepts up to 5000 entries per request in one of two XOR shapes: by-coord (`tiles: [{tileZoom, tileX, tileY}, …]`) or by-hash (`locationHashes: [Guid, …]`). Used by the onboard `gps-denied-onboard` cross-repo path to decide which Google-Maps cells still need download and which UAV variants are already on the server. | _docs/02_document/contracts/api/tile-inventory.md (v1.0.0) |
| Tile Inventory | AZ-505 bulk read endpoint (`POST /api/satellite/tiles/inventory`) that returns one metadata entry per requested cell — present/absent + most-recent row's `id`/`capturedAt`/`source`/`flightId`/`resolutionMPerPx` — without streaming any tile bodies. Accepts up to 5000 entries per request in one of two XOR shapes: by-coord (`tiles: [{z, x, y}, …]`; renamed from `tileZoom/tileX/tileY` by AZ-794, cycle 7) or by-hash (`locationHashes: [Guid, …]`). Used by the onboard `gps-denied-onboard` cross-repo path to decide which Google-Maps cells still need download and which UAV variants are already on the server. Strict input validation enforced by `InventoryRequestValidator` (AZ-796, cycle 7) — see `Validation Problem Details`. | _docs/02_document/contracts/api/tile-inventory.md (v2.0.0) |
| Captured At | Producer-defined UTC timestamp ("the moment this tile imagery represents") persisted in `tiles.captured_at`. For Google Maps it is `DateTime.UtcNow` at download time (provider does not expose original imagery date); for UAV it is the capture timestamp supplied by the upload client. Drives the most-recent-across-(source, flight) read selection rule. | _docs/02_document/contracts/data-access/tile-storage.md (v2.0.0) |
| UAV Tile Upload | `POST /api/satellite/upload` batch endpoint (AZ-488) that ingests UAV-captured tiles. Multipart envelope with a JSON `metadata` field and an aligned `files` collection; per-item results returned in a single HTTP 200 response. | _docs/02_document/contracts/api/uav-tile-upload.md (v1.0.0) |
| Quality Gate | The 5-rule validator (`UavTileQualityGate`) applied to every UAV tile before persistence: Format, Size band, Dimensions, Captured-at age, Blank/uniform. The first failing rule produces a reject reason from the closed `UavTileRejectReasons` enumeration. | _docs/02_document/contracts/api/uav-tile-upload.md (v1.0.0) |
@@ -44,6 +44,9 @@
| Tile Deduplication | Mechanism using DB unique index + ConcurrentDictionary to prevent re-downloading identical tiles | modules/services_google_maps_downloader.md |
| UUIDv5 | RFC 9562 §5.5 deterministic UUID derived from a namespace UUID + a UTF-8 name via SHA-1. AZ-503 uses it to produce stable, cross-repo `tiles.id` and `tiles.location_hash` values without coordinating an id allocator between the satellite-provider and `gps-denied-onboard` workspaces. | modules/common_uuidv5.md, AZ-503 |
| Legacy ID | Pre-AZ-503 random `tiles.id` value, copied into the `legacy_id` column by migration 014 for one-cycle forensics. To be dropped in a future cycle once the cross-repo cutover settles. | _docs/02_document/data_model.md, AZ-503 |
| Validation Problem Details | The uniform RFC 7807 error body shape (`ValidationProblemDetails`) returned by every public HTTP endpoint on 4xx input rejection: `{ type, title, status, errors: { "field.path": ["msg1", ...], ... } }`. Both the FluentValidation business-rule layer (`ValidationEndpointFilter<T>`) and the System.Text.Json deserializer layer (caught by `GlobalExceptionHandler`) produce this exact shape. Error-map keys are camelCase JSON paths (`tiles[0].z`, `locationHashes[3]`) per the global property-name resolver configured in `GlobalValidatorConfig.ApplyOnce`. | _docs/02_document/contracts/api/error-shape.md (v1.0.0), AZ-795 |
| FluentValidation | Open-source library (12.0.0 since AZ-795) used to declare business-rule validators (`AbstractValidator<T>`) per request DTO. Registered via `AddValidatorsFromAssemblyContaining<Program>()` in `Program.cs` and consumed by the generic `ValidationEndpointFilter<T>` which an endpoint opts into via `RouteHandlerBuilder.WithValidation<T>()`. | _docs/02_document/architecture.md § 9, AZ-795 |
| Unmapped Member Handling | The `System.Text.Json.Serialization.JsonUnmappedMemberHandling.Disallow` mode wired into `ConfigureHttpJsonOptions` in cycle 7 — rejects unknown JSON fields (including legacy renames such as `tileZoom/tileX/tileY` after AZ-794) at deserialisation time with a `JsonException` that `GlobalExceptionHandler` converts to 400 + `ValidationProblemDetails`. Pair-rule with `[JsonRequired]` on TileCoord axes catches missing-axis cases at the same layer. | _docs/02_document/architecture.md § 9, AZ-795 |
## Abbreviations
_docs/02_document/module-layout.md
+2 -1
View File
@@ -5,7 +5,7 @@
**Language**: csharp
**Layout Convention**: custom (per-component .csproj per logical component)
**Root**: ./
**Last Updated**: 2026-05-12 (cycle 6 — AZ-505 tile inventory + Leaflet covering index + HTTP/2: new `POST /api/satellite/tiles/inventory` endpoint, new `ITileRepository.GetTilesByLocationHashesAsync`, rewired `GetByTileCoordinatesAsync` to filter on `location_hash`, migration `015_AddTilesLeafletPathIndex.sql`, Kestrel `Http1AndHttp2`, new `TileInventory*` DTOs in Common; cycle 5 — AZ-503 tile-identity foundation added: `SatelliteProvider.Common/Utils/Uuidv5.cs`, migration `014_AddTileIdentityColumns.sql`, 4 new `TileEntity` columns, integer-only flight-aware UPSERT, IntegrationTests → Common ProjectReference)
**Last Updated**: 2026-05-22 (cycle 7 — AZ-794 + AZ-795 + AZ-796 strict inventory validation + z/x/y rename: `TileCoord` wire fields renamed `tileZoom/tileX/tileY` → `z/x/y` with `[JsonRequired]`; new `SatelliteProvider.Api/Validators/{InventoryRequestValidator,ValidationEndpointFilter,GlobalValidatorConfig,ValidationEndpointFilterExtensions}.cs`; new `SatelliteProvider.Api/GlobalExceptionHandler.cs` for `JsonException` → `ValidationProblemDetails`; FluentValidation 12.0.0 + `JsonSerializerOptions.UnmappedMemberHandling.Disallow` wired into `Program.cs`; new contract `_docs/02_document/contracts/api/error-shape.md` v1.0.0; `tile-inventory.md` bumped to v2.0.0; new `SatelliteProvider.IntegrationTests/ProblemDetailsAssertions.cs` + `TileInventoryValidationTests.cs`; new `SatelliteProvider.Tests/TestSupport/ValidatorTestModuleInitializer.cs` + `Validators/InventoryRequestValidatorTests.cs`; new `scripts/probe_inventory_validation.sh`; cycle 6 — AZ-505 tile inventory + Leaflet covering index + HTTP/2: new `POST /api/satellite/tiles/inventory` endpoint, new `ITileRepository.GetTilesByLocationHashesAsync`, rewired `GetByTileCoordinatesAsync` to filter on `location_hash`, migration `015_AddTilesLeafletPathIndex.sql`, Kestrel `Http1AndHttp2`, new `TileInventory*` DTOs in Common; cycle 5 — AZ-503 tile-identity foundation added: `SatelliteProvider.Common/Utils/Uuidv5.cs`, migration `014_AddTileIdentityColumns.sql`, 4 new `TileEntity` columns, integer-only flight-aware UPSERT, IntegrationTests → Common ProjectReference)
## Layout Rules
@@ -129,6 +129,7 @@ The cycle-1 (AZ-487) and cycle-2 (AZ-488) code reviews each surfaced an F1 (Low
- `SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs` + `ValidationEndpointFilterExtensions.cs` (added by AZ-795; generic `IEndpointFilter<T>` that runs the registered `IValidator<T>` and returns `Results.ValidationProblem` on failure; opt-in via `RouteHandlerBuilder.WithValidation<T>()`)
- `SatelliteProvider.Api/Validators/InventoryRequestValidator.cs` + `TileCoordValidator` (added by AZ-796; FluentValidation rules for `POST /api/satellite/tiles/inventory` — XOR `tiles`/`locationHashes`, per-array cap, slippy-map range checks)
- `SatelliteProvider.Api/Validators/GlobalValidatorConfig.cs` (added by AZ-795/AZ-796; idempotent `ApplyOnce()` configures `ValidatorOptions.Global.PropertyNameResolver` so `errors`-map keys are camelCase per `error-shape.md` Inv-4; called from `Program.cs` and from the test assembly's `ModuleInitializer`)
- `SatelliteProvider.Api/GlobalExceptionHandler.cs` (added by AZ-795; `IExceptionHandler` registered via `AddExceptionHandler<GlobalExceptionHandler>()`. Intercepts `BadHttpRequestException(JsonException)` from System.Text.Json's strict-parsing path — unknown-member rejection, missing required field via `[JsonRequired]`, JSON type mismatch — and emits `ValidationProblemDetails` with the same `errors[]` map shape that FluentValidation produces. 5xx errors pass through with sanitised body + `correlationId` per AZ-353.)
- **Internal**: (none)
- **Owns**: `SatelliteProvider.Api/**`
- **PackageReferences (added by AZ-487, bumped by AZ-496, then by AZ-500; AZ-795 added FluentValidation)**: `Microsoft.AspNetCore.Authentication.JwtBearer` 10.0.7 (pinned to the same minor patch as `Microsoft.AspNetCore.OpenApi` 10.0.7; AZ-496 bumped both packages from 8.0.21 → 8.0.25 in cycle 3 to close cycle-1 D1 + cycle-2 D3 supply-chain findings, then AZ-500 bumped both 8.0.25 → 10.0.7 in cycle 4 as part of the .NET 8 → .NET 10 migration; AZ-500 also bumped `Swashbuckle.AspNetCore` 6.6.2 → 10.1.7 here to land Microsoft.OpenApi 2.x compat required by ASP.NET Core 10). `FluentValidation` + `FluentValidation.DependencyInjectionExtensions` 12.0.0 added by AZ-795 to back the strict-input-validation epic.
_docs/02_document/modules/api_program.md
+24 -12
View File
@@ -10,7 +10,7 @@ Application entry point. Configures DI container, sets up middleware, defines mi
|--------|-------|---------|-------------|
| GET | `/tiles/{z}/{x}/{y}` | `ServeTile` | Slippy map tile server with in-memory caching. AZ-505 rewired the DB lookup to filter on `location_hash` (deterministic UUIDv5) so the read becomes an `Index Only Scan` against `tiles_leaflet_path`; the wire response is byte-identical to pre-AZ-505. |
| GET | `/api/satellite/tiles/latlon` | `GetTileByLatLon` | Download single tile by lat/lon/zoom |
| POST | `/api/satellite/tiles/inventory` | `GetTilesInventory` | Bulk tile-existence/metadata lookup (AZ-505) — body is XOR of `tiles[{tileZoom,tileX,tileY}]` (Form A) and `locationHashes[uuid]` (Form B), each capped at 5000 entries. Response is one entry per request entry, in input order. Contract: `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0. |
| POST | `/api/satellite/tiles/inventory` | `GetTilesInventory` | Bulk tile-existence/metadata lookup (AZ-505) — body is XOR of `tiles[{z,x,y}]` (Form A) and `locationHashes[uuid]` (Form B), each capped at 5000 entries. Response is one entry per request entry, in input order. AZ-794 (cycle 7) renamed the coord triple from `tileZoom/tileX/tileY` → `z/x/y` (OSM convention); AZ-796 (cycle 7) added strict input validation via `WithValidation<TileInventoryRequest>()` so malformed payloads return RFC 7807 `ValidationProblemDetails` instead of silently coercing to zero. Contracts: `_docs/02_document/contracts/api/tile-inventory.md` v2.0.0 + `_docs/02_document/contracts/api/error-shape.md` v1.0.0. |
| GET | `/api/satellite/tiles/mgrs` | `GetSatelliteTilesByMgrs` | MGRS stub (returns empty) |
| POST | `/api/satellite/upload` | `UploadUavTileBatch` | UAV tile batch upload (AZ-488) — multipart envelope, 5-rule quality gate, per-source UPSERT with `source='uav'`. Requires the `RequiresGpsPermission` policy. |
| POST | `/api/satellite/request` | `RequestRegion` | Queue region for async tile processing |
@@ -32,12 +32,21 @@ Application entry point. Configures DI container, sets up middleware, defines mi
- `UavTileBatchUploadResponse`, `UavTileUploadResultItem` — per-item response shape
- `UavTileUploadStatus`, `UavTileRejectReasons` — string-constant enumerations exposed in the v1.0.0 contract
### Common/DTO (AZ-505)
### Common/DTO (AZ-505; renamed by AZ-794 in cycle 7)
- `TileInventoryRequest` — XOR body envelope with `Tiles` (Form A) OR `LocationHashes` (Form B)
- `TileCoord` — `{TileZoom, TileX, TileY}` per-entry coord under Form A
- `TileCoord` — `{Z, X, Y}` per-entry coord under Form A. Each property is marked `[JsonRequired]` so missing axes surface as `400` at the deserializer layer (System.Text.Json throws, `GlobalExceptionHandler` converts to `ValidationProblemDetails`).
- `TileInventoryResponse` — `{Results: TileInventoryEntry[]}` response shape; ordering matches request
- `TileInventoryEntry` — per-entry response shape (`Present`, `LocationHash`, optional `Id`/`CapturedAt`/`Source`/`FlightId`/`ResolutionMPerPx`)
- `TileInventoryLimits.MaxEntriesPerRequest` — hard cap (5000) consumed by request validation
- `TileInventoryEntry` — per-entry response shape (`Z`, `X`, `Y`, `LocationHash`, `Present`, optional `Id`/`CapturedAt`/`Source`/`FlightId`/`ResolutionMPerPx`)
- `TileInventoryLimits.MaxEntriesPerRequest` — hard cap (5000) consumed by `InventoryRequestValidator`
### Api/Validators (AZ-795 + AZ-796, cycle 7)
- `InventoryRequestValidator` — FluentValidation `AbstractValidator<TileInventoryRequest>`. Rules: XOR `tiles`/`locationHashes`, `tiles.Count ≤ MaxEntriesPerRequest`, `locationHashes.Count ≤ MaxEntriesPerRequest`, per-entry `TileCoordValidator`.
- `TileCoordValidator` — per-entry rules: `Z` ∈ [0, 22] (slippy-map range), `X` ∈ [0, 2^Z), `Y` ∈ [0, 2^Z).
- `ValidationEndpointFilter<T>` — generic minimal-API filter that resolves `IValidator<T>` from DI, runs it against the bound argument, and returns `Results.ValidationProblem(result.ToDictionary())` on failure. Wired per-endpoint via `RouteHandlerBuilder.WithValidation<T>()`.
- `GlobalValidatorConfig.ApplyOnce()` — idempotent process-wide FluentValidation configuration. Sets `ValidatorOptions.Global.PropertyNameResolver` so error map keys are camelCase per `error-shape.md` Inv-4. Called from `Program.cs` and from the test assembly's `ValidatorTestModuleInitializer` so both contexts see identical key shapes.
### Api/GlobalExceptionHandler (AZ-795, cycle 7)
- `GlobalExceptionHandler : IExceptionHandler` — registered via `AddExceptionHandler<GlobalExceptionHandler>()` + `AddProblemDetails()`. Intercepts unhandled exceptions and converts `BadHttpRequestException(JsonException)` (unknown-member rejection, missing-required-field, type mismatch) into RFC 7807 `ValidationProblemDetails` matching the FluentValidation output shape (single source of truth — see `error-shape.md` v1.0.0 §"Both paths produce identically-shaped bodies"). 5xx errors pass through with sanitised body + `correlationId` (preserves AZ-353).
## Internal Logic
@@ -53,6 +62,9 @@ Application entry point. Configures DI container, sets up middleware, defines mi
9. JSON options: camelCase, case-insensitive
10. **JWT authentication (AZ-487 + AZ-494)**: `AddSatelliteJwt(builder.Configuration)` (extension in `SatelliteProvider.Api.Authentication`) registers `JwtBearer` with `TokenValidationParameters` set per the suite auth contract: signature + lifetime + issuer + audience validation, 30 s clock skew, ≥ 32-byte HMAC key. The `iss` value comes from `JWT_ISSUER` env (fallback `Jwt:Issuer` config); the `aud` value comes from `JWT_AUDIENCE` env (fallback `Jwt:Audience` config). All three values (secret, iss, aud) are fail-fast — the API throws `InvalidOperationException` at startup if any is unset or whitespace-only. Production deploys MUST set the env vars with admin-team-confirmed values; `appsettings.json` ships empty so the fail-fast triggers. `appsettings.Development.json` ships clearly-tagged DEV-ONLY values (`DEV-ONLY-iss-admin-azaion-local` / `DEV-ONLY-aud-satellite-provider`) so local dev works out-of-the-box. Followed by `AddAuthorization` with the `RequiresGpsPermission` policy (AZ-488).
11. **Kestrel HTTP/2 (AZ-505)**: `builder.WebHost.ConfigureKestrel(opts => opts.ConfigureEndpointDefaults(lo => lo.Protocols = HttpProtocols.Http1AndHttp2))`. The dev listener is now `https://+:8080` with a self-signed cert (`./certs/api.pfx`, generated idempotently by `scripts/run-tests.sh` and bound via `ASPNETCORE_Kestrel__Certificates__Default__Path` / `__Password` in `docker-compose.yml`). Kestrel needs TLS for HTTP/2 protocol negotiation; ALPN advertises both `h2` and `http/1.1` so HTTP/2-capable clients (browser Leaflet, `HttpClient` with `Version20` + `RequestVersionExact`, httpx `http2=True`) multiplex tile reads on a single TLS connection, and legacy clients fall back to HTTP/1.1. The integration-test container trusts the dev cert via `/usr/local/share/ca-certificates/` + `update-ca-certificates`. AZ-505 AC-5 verifies the multiplex semantics here; production termination is expected at the ingress (Envoy / nginx / ALB) — Kestrel can then drop to HTTP/2 cleartext behind it without changing this code.
12. **ProblemDetails + global exception handler (AZ-795, cycle 7)**: `AddProblemDetails()` + `AddExceptionHandler<GlobalExceptionHandler>()` register the uniform RFC 7807 error pipeline. `app.UseExceptionHandler()` (in the middleware chain) routes unhandled exceptions through `GlobalExceptionHandler`, which converts `BadHttpRequestException(JsonException)` (unknown-member rejection, missing-required-field, JSON type mismatch) into `ValidationProblemDetails` with the same `errors[]` map shape that FluentValidation produces. This is the deserializer-layer half of the strict-validation contract — `error-shape.md` v1.0.0 §"Two collaborating pieces of shared infrastructure".
13. **Strict JSON parsing (AZ-795, cycle 7)**: `ConfigureHttpJsonOptions` sets `PropertyNamingPolicy = CamelCase`, `PropertyNameCaseInsensitive = true`, `UnmappedMemberHandling = Disallow`, and adds `JsonStringEnumConverter` with camelCase naming. `UnmappedMemberHandling.Disallow` is the key strict-parsing knob: any unknown root or nested field is rejected at the deserializer rather than silently dropped. Catches typos (`{"Z":12}` uppercase, `{"tileZoom":...}` post-rename) that no FluentValidation rule can see after deserialization.
14. **FluentValidation registration (AZ-795 + AZ-796, cycle 7)**: `AddValidatorsFromAssemblyContaining<Program>()` auto-registers every `IValidator<T>` in the API assembly (currently `InventoryRequestValidator` + `TileCoordValidator`). `GlobalValidatorConfig.ApplyOnce()` runs the idempotent process-wide config — sets `ValidatorOptions.Global.PropertyNameResolver` so `errors` map keys are camelCase (matches the request body's casing per `error-shape.md` Inv-4). Per-endpoint opt-in via `.WithValidation<TileInventoryRequest>()` on the inventory MapPost — the generic `ValidationEndpointFilter<T>` resolves the validator from DI at request time and returns `Results.ValidationProblem` on failure.
### Startup
1. Database migration via `DatabaseMigrator.RunMigrations()` — throws on failure
@@ -67,12 +79,12 @@ Application entry point. Configures DI container, sets up middleware, defines mi
3. If no DB record: downloads tile via `GoogleMapsDownloaderV2.DownloadSingleTileAsync`, creates `TileEntity`, inserts
4. Returns image bytes with cache headers (`Cache-Control: public, max-age=86400`)
### GetTilesInventory Handler (AZ-505)
1. Validates XOR body shape: 400 if both `tiles` and `locationHashes` are populated, 400 if neither is populated, 400 if either exceeds `TileInventoryLimits.MaxEntriesPerRequest` (5000)
2. Delegates to `ITileService.GetInventoryAsync(request, ct)`
3. Service computes `location_hash` for Form A entries via `Uuidv5.Create(TileNamespace, "{z}/{x}/{y}")`, calls `ITileRepository.GetTilesByLocationHashesAsync(IReadOnlyList<Guid>)`, re-aligns results back to input order
4. Returns `TileInventoryResponse` with one entry per input — `present=true` entries carry `id` / `capturedAt` / `source` / `flightId` / `resolutionMPerPx`; `present=false` entries carry only `locationHash`
5. Authenticated by `.RequireAuthorization()` (401 before handler for anonymous)
### GetTilesInventory Handler (AZ-505 + AZ-796 cycle 7)
1. **Pre-handler validation (cycle 7)**: `ValidationEndpointFilter<TileInventoryRequest>` runs BEFORE the handler. Resolves `InventoryRequestValidator` from DI and asserts XOR `tiles`/`locationHashes`, per-array cap (`TileInventoryLimits.MaxEntriesPerRequest = 5000`), `z` ∈ [0, 22], `x` ∈ [0, 2^z), `y` ∈ [0, 2^z) per entry. Any failure short-circuits with HTTP 400 + `ValidationProblemDetails`. Deserializer-layer failures (missing `z/x/y`, unknown root/nested fields, JSON type mismatch) are caught earlier by System.Text.Json and surfaced as identically-shaped `ValidationProblemDetails` via `GlobalExceptionHandler` (AZ-795).
2. Handler delegates to `ITileService.GetInventoryAsync(request, ct)` — body of the handler is just the service call + `Results.Ok`.
3. Service computes `location_hash` for Form A entries via `Uuidv5.Create(TileNamespace, "{z}/{x}/{y}")`, calls `ITileRepository.GetTilesByLocationHashesAsync(IReadOnlyList<Guid>)`, re-aligns results back to input order.
4. Returns `TileInventoryResponse` with one entry per input — `present=true` entries carry `id` / `capturedAt` / `source` / `flightId` / `resolutionMPerPx`; `present=false` entries carry only `locationHash`.
5. Authenticated by `.RequireAuthorization()` (401 before validation runs for anonymous requests).
### GetTileByLatLon Handler
Downloads a tile, persists it, returns metadata as `DownloadTileResponse`.
@@ -85,7 +97,7 @@ Buffers each `IFormFile` into memory, packages them as `UavUploadFile` records (
## Dependencies
All project references: Common, DataAccess, Services.
NuGet: `Serilog.AspNetCore` (8.0.3 — fallback retained on .NET 10 per AZ-500 Risk #4: no 10.x line published as of cycle 4; documented in `AGENTS.md`), `Swashbuckle.AspNetCore` (10.1.7 — bumped from 6.6.2 by AZ-500 to land Microsoft.OpenApi 2.x compat required by ASP.NET Core 10), `Microsoft.AspNetCore.OpenApi` (10.0.7 — bumped from 8.0.25 by AZ-500), `Microsoft.AspNetCore.Authentication.JwtBearer` (10.0.7 — added at 8.0.21 by AZ-487, bumped to 8.0.25 by AZ-496, bumped to 10.0.7 by AZ-500), `SixLabors.ImageSharp`, `Newtonsoft.Json`.
NuGet: `Serilog.AspNetCore` (8.0.3 — fallback retained on .NET 10 per AZ-500 Risk #4: no 10.x line published as of cycle 4; documented in `AGENTS.md`), `Swashbuckle.AspNetCore` (10.1.7 — bumped from 6.6.2 by AZ-500 to land Microsoft.OpenApi 2.x compat required by ASP.NET Core 10), `Microsoft.AspNetCore.OpenApi` (10.0.7 — bumped from 8.0.25 by AZ-500), `Microsoft.AspNetCore.Authentication.JwtBearer` (10.0.7 — added at 8.0.21 by AZ-487, bumped to 8.0.25 by AZ-496, bumped to 10.0.7 by AZ-500), `FluentValidation` + `FluentValidation.DependencyInjectionExtensions` (12.0.0 — added by AZ-795 to back the strict-input-validation epic), `SixLabors.ImageSharp`, `Newtonsoft.Json`.
**Microsoft.OpenApi 2.x refactor note (AZ-500)**: the major bump (1.x → 2.x) drove three internal Swashbuckle-setup edits in this file — `using Microsoft.OpenApi.Models;` → `using Microsoft.OpenApi;`; `AddSecurityRequirement(...)` rewritten to take a `Func<OpenApiDocument, OpenApiSecurityRequirement>` and use `OpenApiSecuritySchemeReference("Bearer")` instead of the removed `OpenApiSecurityScheme.Reference` shape; `MapType<UavTileBatchUploadRequest>` rewritten to use the new `JsonSchemaType` enum and `IDictionary<string, IOpenApiSchema>` properties bag. The Swagger document shape (paths, operations, the Bearer Authorize button, the multipart-batch upload schema) is preserved exactly — `SwaggerDocument_AdvertisesBearerSecurityScheme` and the AZ-353 swagger-ready integration assertions still pass. Eight `ASPDEPR002` deprecation warnings (`WithOpenApi(...)`) remain — they're recorded in `_docs/03_implementation/reviews/batch_01_cycle4_review.md` as a follow-up PBI; the API is still fully functional in .NET 10 (deprecated, not removed).
_docs/02_document/modules/common_dtos.md
+9 -7
View File
@@ -110,21 +110,23 @@ Authoritative reject-reason codes for the UAV upload quality gate. Adding a new
- `ImageTooUniform = "IMAGE_TOO_UNIFORM"` — Rule 5 (luminance variance below `MinLuminanceVariance`).
- `StorageFailure = "STORAGE_FAILURE"` — reserved for the orphan-row-recovery path when the on-disk write succeeds but the DB UPSERT fails; surfaced per-item without failing the envelope (AZ-488 Reliability NFR).
### TileCoord (added AZ-505)
### TileCoord (added AZ-505, renamed AZ-794 cycle 7)
Single tile coordinate triple used by the inventory endpoint Form A request shape and as the per-entry input echo on the response.
- `TileZoom` (int) — slippy zoom level.
- `TileX`, `TileY` (int) — slippy x/y at that zoom.
- Defined in `SatelliteProvider.Common/DTO/TileInventory.cs`. Matches `tile-inventory.md` v1.0.0 Shape.
- `Z` (int) `[JsonRequired]` — slippy zoom level. Wire name `"z"`.
- `X` (int) `[JsonRequired]` — slippy x at that zoom. Wire name `"x"`.
- `Y` (int) `[JsonRequired]` — slippy y at that zoom. Wire name `"y"`.
- Defined in `SatelliteProvider.Common/DTO/TileInventory.cs`. Matches `tile-inventory.md` v2.0.0 Shape (the rename from `tileZoom/tileX/tileY` shipped in AZ-794; the `[JsonRequired]` markers + the global `UnmappedMemberHandling.Disallow` mean missing axes and the legacy field names both surface as HTTP 400 with `ValidationProblemDetails` per `error-shape.md` v1.0.0).
### TileInventoryRequest (added AZ-505)
API request body for `POST /api/satellite/tiles/inventory`. Carries one of two XOR-exclusive batch shapes.
- `Tiles` (`IReadOnlyList<TileCoord>?`) — Form A: coords-by-value. The server computes `location_hash = Uuidv5(TileNamespace, "{z}/{x}/{y}")` per entry.
- `LocationHashes` (`IReadOnlyList<Guid>?`) — Form B: hashes-by-reference. Used when the caller already has UUIDv5 location hashes (typical for the onboard cross-repo path).
- Exactly one of `Tiles` / `LocationHashes` must be populated and non-empty; both-populated or neither → HTTP 400 (`tile-inventory.md` Inv-1).
- Exactly one of `Tiles` / `LocationHashes` must be populated and non-empty; both-populated or neither → HTTP 400 (`tile-inventory.md` v2.0.0 Inv-1, enforced by `InventoryRequestValidator` via `ValidationEndpointFilter<TileInventoryRequest>` in cycle 7).
- Total entries (in either field) ≤ `TileInventoryLimits.MaxEntriesPerRequest` (5000); over-cap → HTTP 400 (Inv-7).
### TileInventoryEntry (added AZ-505)
### TileInventoryEntry (added AZ-505, coord fields renamed AZ-794 cycle 7)
Per-entry result inside `TileInventoryResponse`. One entry per request entry, in the SAME order as the request (`tile-inventory.md` Inv-2).
- `Z`, `X`, `Y` (int) — echoed coord triple matching the request entry; wire names `"z"`, `"x"`, `"y"` (renamed from `"tileZoom"`/`"tileX"`/`"tileY"` by AZ-794). Always populated; when Form B was used, these are 0 (the caller already knows the hash).
- `LocationHash` (Guid) — always populated; UUIDv5 of `"{z}/{x}/{y}"` from `Uuidv5.LocationHashForTile` (Form A) or echoed from request (Form B).
- `Present` (bool) — `true` iff a row exists in `tiles` with this `location_hash` (Inv-4).
- `Id` (Guid?) — `tiles.id` of the most-recent row across sources/flights (`captured_at DESC, updated_at DESC, id DESC`, Inv-5); null when `Present=false` (Inv-6).
@@ -135,7 +137,7 @@ API response body for `POST /api/satellite/tiles/inventory`.
- `Results` (`IReadOnlyList<TileInventoryEntry>`) — one entry per request entry; `Results.Count` always equals the request entry count (Inv-2).
### TileInventoryLimits (added AZ-505, static constants)
- `MaxEntriesPerRequest = 5000` — request-body cap enforced by the inventory handler (Inv-7).
- `MaxEntriesPerRequest = 5000` — request-body cap enforced by `InventoryRequestValidator` (per-array cap; `tile-inventory.md` v2.0.0 Inv-7).
## Internal Logic
- `GeoPoint` uses a precision tolerance of `0.00005` degrees (~5.5 meters) for equality comparison.
_docs/02_document/modules/tests_integration.md
+4
View File
@@ -15,6 +15,9 @@ Console application that runs end-to-end integration tests against a live API in
- `JwtIntegrationTests` (added by AZ-487 cycle 2; helpers consolidated by AZ-491 cycle 3; iss/aud scenarios added by AZ-494 cycle 3) — `AnonymousRequest_To_AnyEndpoint_Returns401`, `ExpiredToken_Returns401`, `InvalidSignature_Returns401`, `ValidToken_Returns200_OnHealthyEndpoint`, `WrongIssuer_Returns401` (AZ-494 AC-1), `WrongAudience_Returns401` (AZ-494 AC-2), `SwaggerDocument_AdvertisesBearerSecurityScheme`. HS256 token minting lives in the shared `SatelliteProvider.TestSupport.JwtTokenFactory` (consumed via `ProjectReference`); runner-specific concerns (`JwtTestHelpers.ResolveSecretOrThrow` / `ResolveIssuerOrThrow` / `ResolveAudienceOrThrow`, `MintAuthenticated` / `MintExpired` convenience wrappers that auto-fill iss+aud from env, `AttachDefaultAuthorization`, `DefaultSubject = "integration-tests"`) remain in this project. The test runner sets `JWT_SECRET` + `JWT_ISSUER` + `JWT_AUDIENCE` on the API container and attaches a Bearer token (with matching iss/aud) to every existing test's HTTP requests so the pre-cycle-2 suite continues to pass.
- `UavUploadTests` (added by AZ-488, cycle 2; coordinate-counter promoted to defense-in-depth by AZ-493 cycle 3; AZ-503 cycle 5 added 2 more tests) — `HappyPathSingleItem_PersistsRow`, `MixedBatch_ReturnsPerItemResults`, `MultiSourceCoexistence_AZ484_Cycle2`, `SameSourceUpsert_AZ484_Cycle2`, `NoToken_Returns401`, `ValidTokenWithoutGpsPermission_Returns403`, `OversizedBatch_Returns400`, plus AZ-503: `MultiFlightUavRowsCoexist_AZ503_AC3` (two flights at the same cell → two rows, one `location_hash`, two `file_path`s under `./tiles/uav/{flight_id}/...`) and `FloatRoundingDoesNotBreakIdempotence_AZ503_AC4` (two uploads with float-distinct `latitude` recomputed from `TileToWorldPos` collapse to a single row because the conflict key is integer-only). The AZ-503 migration made `location_hash NOT NULL`, so the cycle-2 `MultiSourceCoexistence_AZ484_Cycle2` seeder was updated to compute `location_hash` via `Uuidv5.Create` (canonical name `"{zoom}/0/0"`) before the raw SQL `INSERT` — this required adding a `ProjectReference` from `SatelliteProvider.IntegrationTests` to `SatelliteProvider.Common`. The wall-clock-seeded `_coordinateCounter` is retained as a belt-and-suspenders safeguard alongside the AZ-493 startup DB-reset (below) — if a developer runs with `--keep-state`, or the DB-reset path is skipped for any reason, the wall-clock seed still spreads coordinates across runs so the unique index does not collide.
- `StubAndErrorContractTests` (existing) — updated in cycle 2 to drop the legacy `StubUpload_Returns501` expectation since AZ-488 implemented the endpoint.
- `TileInventoryTests` (added cycle 6 — AZ-505) — `OrderingAndPresentAbsentShaping_AC1`, `LeafletReadReturnsMostRecentViaLocationHash_AC2`, `ValidationRejectsBothPopulated_AC6`, `ValidationRejectsNeitherPopulated_AC6`, `ValidationRejectsOversizedBatch_AC6`, `UnauthenticatedRequestReturns401_AC6`, `PerformanceBudget_AC4` (full-suite only). Tests are cycle-7-stable — they use the post-AZ-794 `{z, x, y}` wire shape and a minor x/y reduction was applied in cycle 7 to keep the synthetic coords within the z=18 slippy bounds enforced by `TileCoordValidator`.
- `TileInventoryValidationTests` (added cycle 7 — AZ-796) — 16 tests: `HappyPath_Returns200`, `EmptyBody_Returns400`, `NeitherPopulated_Returns400`, `BothPopulated_Returns400`, `EmptyTilesArray_Returns400`, `TilesOverCap_Returns400`, `MissingZ_Returns400WithFieldPath`, `MissingXAndY_Returns400`, `ZoomOutOfRange_Returns400WithFieldPath`, `XBeyondZoomBounds_Returns400`, `YBeyondZoomBounds_Returns400`, `NegativeAxis_Returns400`, `UnknownRootField_Returns400`, `UnknownNestedField_Returns400`, `OldV1FieldName_Returns400` (AZ-794 + AZ-796 intersection — exact AZ-777 Phase 1 reproducer body, asserts legacy `tileZoom/tileX/tileY` now yields 400), `TypeMismatch_Returns400`. Each test exercises one of the 9 validation rules end-to-end through `ValidationEndpointFilter<TileInventoryRequest>` + `GlobalExceptionHandler`, asserts HTTP 400 + RFC 7807 `ValidationProblemDetails` shape via the shared `ProblemDetailsAssertions` helper.
- `IdempotentPostTests` — pre-existing; cycle 7 adjusted the route-point payload from PascalCase (`Latitude`/`Longitude`) to camelCase (`lat`/`lon`) because the post-AZ-795 `UnmappedMemberHandling.Disallow` would otherwise reject the previously-silently-ignored fields. The `RoutePoint` DTO has carried `JsonPropertyName("lat"/"lon")` since AZ-309; cycle 7's strict JSON parsing exposed the test was sending the wrong shape and getting away with it via the pre-cycle-7 permissive deserializer.
### Supporting Classes
- `Models.cs` — HTTP response DTOs for deserialization
@@ -30,6 +33,7 @@ Console application that runs end-to-end integration tests against a live API in
- Token *minting* lives in the shared `SatelliteProvider.TestSupport.JwtTokenFactory` (AZ-491) — runner-side concerns (env reads, HttpClient mutation, the iss/aud-aware mint wrapper) deliberately stay here.
- `IntegrationTestDatabaseReset.cs` (AZ-493) — instance class with a single `EnsureCleanStateAsync()` method that truncates the integration-test target tables in FK-safe order. Guarded via `SatelliteProvider.TestSupport.IntegrationTestResetGuard` (env + Host allowlist) so it cannot run against a non-test database.
- `PerfBootstrap.cs` (AZ-492) — static helpers for the perf harness bootstrap subcommands. `MintToken()` mints a 4-hour HS256 token with subject `perf-tests` and a `permissions: GPS` claim via the canonical `SatelliteProvider.TestSupport.JwtTokenFactory.Create`; `GenerateUavFixture(args)` writes a 256×256 random-noise JPEG via `SixLabors.ImageSharp` to the path passed on the CLI. Invoked from `scripts/run-performance-tests.sh` via `dotnet <SatelliteProvider.IntegrationTests.dll> --mint-only` and `--gen-uav-fixture <path>`.
- `ProblemDetailsAssertions.cs` (added cycle 7 — AZ-795) — shared static helpers for asserting RFC 7807 ProblemDetails bodies on integration-test responses. `ReadProblemDetailsAsync(HttpResponseMessage, label)` deserialises the response body into a `JsonElement` with helpful failure messages when the content-type / shape doesn't match. `AssertProblemDetails(problem, expectedStatus, label)` asserts the base ProblemDetails shape (`type`, `title`, `status`). `AssertValidationProblem(problem, expectedStatus, label, expectedErrorPath?, expectedErrorContains?)` extends the base assertion to require the `errors` map per `error-shape.md` Inv-2 and optionally checks a specific field path / message substring. Consumed by `TileInventoryValidationTests`; designed to be reused by every future per-endpoint child task under AZ-795.
## Internal Logic
- Makes HTTP calls to the API at `API_URL` environment variable (default: `http://api:8080`)
_docs/02_document/modules/tests_unit.md
+7 -2
View File
@@ -23,17 +23,22 @@ Existing baseline (pre-cycle-2) test classes cover `TileService`, `RegionService
- `Uuidv5Tests` — pure-C# UUIDv5 generator parity tests. `Create_MatchesPythonReferenceVectors_AC1` pins 10 reference vectors generated by Python's `uuid.uuid5(TILE_NAMESPACE, name)`; `Create_IsDeterministic` asserts repeated runs return the same `Guid`; `Create_SetsVersionAndVariantBits` asserts the version nibble is `5` and the variant top-2-bits are `10` (RFC 9562 §5.5).
- `UavTileFilePathTests` (rewritten for AZ-503 from the cycle-2 placeholder) — covers `BuildUavTileFilePath(Guid? flightId, int z, int x, int y)` across three cases: `BuildUavTileFilePath_AnonymousFlight_UsesNoneSegment` (null `flightId` → literal `none` segment), `BuildUavTileFilePath_PerFlight_UsesFlightIdDirectory` (per-flight segment), `BuildUavTileFilePath_DifferentFlights_ProduceDifferentPaths` (path-distinctness across flights at the same cell). Integer-typed coordinates and the `Guid? flightId` parameter together still preclude string-injection path traversal.
### AZ-795 + AZ-796 — strict inventory validation (cycle 7)
- `Validators/InventoryRequestValidatorTests` (added cycle 7 — AZ-796) — 16 tests against `InventoryRequestValidator` + `TileCoordValidator` in isolation via FluentValidation's `TestValidate(...)` test helper. Covers every `RuleFor(...)`: `Validate_TilesPopulated_LocationHashesNull_Passes`, `Validate_LocationHashesPopulated_TilesNull_Passes`, `Validate_BothPopulated_FailsXorRule`, `Validate_NeitherPopulated_FailsXorRule`, `Validate_BothEmpty_FailsXorRule`, `Validate_TilesAtCap_Passes`, `Validate_TilesOverCap_FailsCapRule`, `Validate_LocationHashesOverCap_FailsCapRule`, `Validate_TileZoomOutOfRange_FailsRangeRule` (`[Theory]` with z ∈ {-1, 23, 100}), `Validate_TileZoomInRange_PassesRangeRule` (`[Theory]` with z ∈ {0, 18, 22}), `Validate_TileXNegative_FailsRangeRule`, `Validate_TileXAtUpperBound_FailsRangeRule`, `Validate_TileYNegative_FailsRangeRule`, `Validate_TileYAtUpperBound_FailsRangeRule`, `Validate_AxesAtMaxForZoom_Passes`.
- `TestSupport/ValidatorTestModuleInitializer.cs` (added cycle 7 — AZ-795) — `[ModuleInitializer]` that calls `GlobalValidatorConfig.ApplyOnce()` at test-assembly load time. Ensures unit tests see the same camelCase property-name resolution that `Program.cs` configures for the running API, so validator error keys (e.g., `tiles[0].z`) match the runtime contract per `error-shape.md` v1.0.0 Inv-4 without forcing every test to re-run the setup.
## Internal Logic
- Tests follow Arrange / Act / Assert. Time-dependent paths inject a `FixedTimeProvider` (cycle-2 addition) so Rule 4 has deterministic age windows.
- `JwtSecurityTokenHandler.MapInboundClaims = false` is set explicitly in JWT tests so claims read by their original names (`sub`, `permissions`, …) rather than the framework-remapped names.
- Cycle 7 also added validator-isolated assertions via FluentValidation's `TestValidate(...)` helper (no HTTP, no DI container) — the matching end-to-end assertions live in `SatelliteProvider.IntegrationTests/TileInventoryValidationTests.cs`.
## Dependencies
- Project references: `SatelliteProvider.Services.TileDownloader`, `SatelliteProvider.Services.RegionProcessing`, `SatelliteProvider.Services.RouteManagement`, `SatelliteProvider.Common`, `SatelliteProvider.DataAccess`, `SatelliteProvider.Api` (for the Authentication tests — added in AZ-487), `SatelliteProvider.TestSupport` (added by AZ-491; provides the canonical `JwtTokenFactory` consumed by both this project and `SatelliteProvider.IntegrationTests`).
- NuGet: xUnit (2.5.3), Moq (4.20.72), FluentAssertions (8.8.0), coverlet.collector (6.0.0), Microsoft.NET.Test.Sdk (17.8.0), Microsoft.Extensions.* (Caching.Memory, Configuration, DI, Logging, Options, Http — all bumped from 9.0.10 → 10.0.7 by AZ-500 as a coordinated cycle-4 move), `Microsoft.AspNetCore.Authentication.JwtBearer` 10.0.7 (consumed transitively via the `ProjectReference` to `SatelliteProvider.Api`; AZ-487 added the dependency at 8.0.21, AZ-496 bumped it to 8.0.25, AZ-500 bumped it to 10.0.7), `SixLabors.ImageSharp` 3.1.11 (added by AZ-488 for the gate tests).
- NuGet: xUnit (2.5.3), Moq (4.20.72), FluentAssertions (8.8.0), coverlet.collector (6.0.0), Microsoft.NET.Test.Sdk (17.8.0), Microsoft.Extensions.* (Caching.Memory, Configuration, DI, Logging, Options, Http — all bumped from 9.0.10 → 10.0.7 by AZ-500 as a coordinated cycle-4 move), `Microsoft.AspNetCore.Authentication.JwtBearer` 10.0.7 (consumed transitively via the `ProjectReference` to `SatelliteProvider.Api`; AZ-487 added the dependency at 8.0.21, AZ-496 bumped it to 8.0.25, AZ-500 bumped it to 10.0.7), `SixLabors.ImageSharp` 3.1.11 (added by AZ-488 for the gate tests), `FluentValidation` + `FluentValidation.TestHelper` 12.0.0 (added cycle 7 — AZ-795; the test helper drives the `TestValidate(...)` assertions used by `InventoryRequestValidatorTests`).
- `appsettings.json` copied to output (used by Authentication tests for the `Jwt` section binding scenario).
## Consumers
- CI pipeline (`01-test.yml`) and `scripts/run-tests.sh --unit-only` run `dotnet test` against this project.
## Tests
This IS the test module. Cycle-2 added ~25 unit tests on top of the existing baseline; cycle-5 (AZ-503) added 6 more (3 in `Uuidv5Tests`, 3 in `UavTileFilePathTests`) plus 2 new methods in `UavTileUploadHandlerTests`. The full project executes in seconds (no external services required).
This IS the test module. Cycle-2 added ~25 unit tests on top of the existing baseline; cycle-5 (AZ-503) added 6 more (3 in `Uuidv5Tests`, 3 in `UavTileFilePathTests`) plus 2 new methods in `UavTileUploadHandlerTests`. Cycle 7 (AZ-795 + AZ-796) added 16 more in `InventoryRequestValidatorTests` covering every `RuleFor(...)` in the cycle's new validators. The full project executes in seconds (no external services required). Cycle 7 Step 11 reported the unit suite at 311 tests, all green.
_docs/02_document/ripple_log_cycle7.md
+80
View File
@@ -0,0 +1,80 @@
# Cycle 7 — Documentation Ripple Log
**Cycle**: 7 (AZ-794 z/x/y rename + AZ-795 strict-validation epic + AZ-796 inventory-endpoint validation)
**Generated by**: `/document` skill (task mode) during autodev Step 13
**Resolution method**: `Grep --type cs` against every new or changed symbol introduced by the three tasks. C# `using`-based import analysis on `TileCoord` (renamed fields + `[JsonRequired]`), `InventoryRequestValidator`, `ValidationEndpointFilter<T>`, `GlobalExceptionHandler`, `GlobalValidatorConfig`, plus `ProblemDetailsAssertions` and `ValidatorTestModuleInitializer` in the test projects. No static-analyzer (NDepend, etc.) was used — the new surface is shallow and lives almost entirely behind `Program.cs` + the two new test files, so the literal usage scan is exhaustive.
## Directly-changed source files (cycle 7)
- `SatelliteProvider.Common/DTO/TileInventory.cs` (AZ-794, modified) — `TileCoord` properties renamed `TileZoom/TileX/TileY` → `Z/X/Y` with `[JsonRequired]` on each; `TileInventoryEntry` echo fields renamed in lockstep. Wire field names are `z`/`x`/`y` per the camelCase resolver.
- `SatelliteProvider.Api/Program.cs` (AZ-795 + AZ-796, modified) —
- `ConfigureHttpJsonOptions(o => o.SerializerOptions.UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow)` (AZ-795).
- `AddProblemDetails(...)` global ProblemDetails configurator (AZ-795).
- `AddExceptionHandler<GlobalExceptionHandler>()` + `UseExceptionHandler()` middleware order (AZ-795).
- `AddValidatorsFromAssemblyContaining<Program>()` + `GlobalValidatorConfig.ApplyOnce()` at startup (AZ-795 + AZ-796).
- `.WithValidation<TileInventoryRequest>()` on the `MapPost("/api/satellite/tiles/inventory", …)` builder (AZ-796).
- Endpoint summary / description bumped to reference `tile-inventory.md` v2.0.0 + `error-shape.md` v1.0.0.
- `SatelliteProvider.Api/Validators/InventoryRequestValidator.cs` (AZ-796, **new**) — `AbstractValidator<TileInventoryRequest>` + nested `TileCoordValidator` with 9 rules (XOR, per-array cap, Z/X/Y ranges).
- `SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs` (AZ-795, **new**) — generic `IEndpointFilter<T>` that runs the registered `IValidator<T>` and emits `Results.ValidationProblem(...)` on failure.
- `SatelliteProvider.Api/Validators/ValidationEndpointFilterExtensions.cs` (AZ-795, **new**) — opt-in `RouteHandlerBuilder.WithValidation<T>()` extension; intentionally orthogonal to per-endpoint authorization configuration.
- `SatelliteProvider.Api/Validators/GlobalValidatorConfig.cs` (AZ-795 + AZ-796, **new**) — idempotent `ApplyOnce()` configures FluentValidation's global `PropertyNameResolver` to camelCase (`tiles[0].z` instead of `Tiles[0].Z`) per `error-shape.md` Inv-4. Called from `Program.cs` and from the unit-test assembly's `[ModuleInitializer]`.
- `SatelliteProvider.Api/GlobalExceptionHandler.cs` (AZ-795, **new**) — `IExceptionHandler` that intercepts `BadHttpRequestException(JsonException)` (the System.Text.Json strict-parse path: unknown fields, `[JsonRequired]` violations, type mismatches) and emits the same `ValidationProblemDetails` shape that FluentValidation produces. 5xx paths pass through with sanitised body + correlation id (continuation of the AZ-353 contract).
- `_docs/02_document/contracts/api/error-shape.md` (AZ-795, **new**) — v1.0.0 uniform error-body contract. Single source of truth for the `ValidationProblemDetails` wire shape across both layers and across all future child tickets of the AZ-795 epic.
- `_docs/02_document/contracts/api/tile-inventory.md` (AZ-794 + AZ-796, modified) — bumped to v2.0.0; documents the 9 validation rules + the `z/x/y` rename; `Producer task` block extended to credit AZ-505 + AZ-794 + AZ-796.
- `SatelliteProvider.Tests/Validators/InventoryRequestValidatorTests.cs` (AZ-796, **new**) — 16 unit tests against the validator via `TestValidate(...)`.
- `SatelliteProvider.Tests/TestSupport/ValidatorTestModuleInitializer.cs` (AZ-795, **new**) — calls `GlobalValidatorConfig.ApplyOnce()` at test-assembly load.
- `SatelliteProvider.IntegrationTests/ProblemDetailsAssertions.cs` (AZ-795, **new**) — shared response-shape helper consumed by every future per-endpoint validation test.
- `SatelliteProvider.IntegrationTests/TileInventoryValidationTests.cs` (AZ-796, **new**) — 16 end-to-end tests; one per validation rule (with sub-cases) plus a happy path.
- `SatelliteProvider.IntegrationTests/TileInventoryTests.cs` (AZ-794, modified) — updated `tileZoom/tileX/tileY` JSON payloads to `z/x/y`; reduced the synthetic x/y values to stay inside the slippy-map bounds enforced by `TileCoordValidator`.
- `SatelliteProvider.IntegrationTests/IdempotentPostTests.cs` (AZ-795, modified) — route-point payload PascalCase → camelCase (`lat`/`lon`) because the post-cycle-7 strict deserializer no longer silently drops the wrong field names that the test had been sending pre-cycle 7.
- `scripts/probe_inventory_validation.sh` (AZ-796, **new**) — manual probe script; exercises each failure mode end-to-end and captures responses for change-review evidence.
## Importer scan results
| Symbol | Importer count | Importer files | Component touched |
|--------|----------------|----------------|-------------------|
| `TileCoord.Z` / `TileCoord.X` / `TileCoord.Y` (renamed properties; wire names `z`/`x`/`y`) | 5 | `TileService.cs` (`Uuidv5.LocationHashForTile`), `TileInventoryTests.cs`, `TileInventoryValidationTests.cs`, `InventoryRequestValidatorTests.cs`, `TileInventory.cs` self-references in `TileInventoryEntry` | TileDownloader (production), Tests (unit + integration) |
| `[JsonRequired]` on `TileCoord.Z/X/Y` | n/a | enforced at runtime by `System.Text.Json` + caught by `GlobalExceptionHandler` (no compile-time consumer) | WebApi (deserializer + handler) |
| `InventoryRequestValidator` / `TileCoordValidator` | 3 | `Program.cs` (assembly-scan registration via `AddValidatorsFromAssemblyContaining<Program>()`), `InventoryRequestValidatorTests.cs`, `TileInventoryValidationTests.cs` (indirect through the running API) | WebApi (production), Tests (unit + integration) |
| `ValidationEndpointFilter<T>` / `WithValidation<T>()` | 1 (current) + N-future | `Program.cs` (`MapPost("/api/satellite/tiles/inventory", …).WithValidation<TileInventoryRequest>()`) | WebApi |
| `GlobalValidatorConfig.ApplyOnce` | 2 | `Program.cs` (production), `ValidatorTestModuleInitializer.cs` (unit-test assembly load) | WebApi, Tests (unit) |
| `GlobalExceptionHandler` | 1 | `Program.cs` (DI registration + middleware order) | WebApi |
| `ProblemDetailsAssertions.AssertValidationProblem` | 1 (current) + N-future | `TileInventoryValidationTests.cs`; designed to be reused by every future per-endpoint child task under AZ-795 | Tests (integration) |
| `FluentValidation` package (12.0.0) | 4 | `SatelliteProvider.Api.csproj`, `SatelliteProvider.Tests.csproj`, `InventoryRequestValidator.cs`, `InventoryRequestValidatorTests.cs` | WebApi, Tests (unit) |
## Doc refresh decisions
All importers land inside components that already received targeted updates during Step 10 (Implement) and this Step 13:
- **WebApi (`Program.cs`)** — updated `_docs/02_document/modules/api_program.md` with the new endpoint description, the new `Api/Validators` section (filter + extensions + validator + global config), the new `Api/GlobalExceptionHandler` section, expanded DI registration (ProblemDetails + GlobalExceptionHandler + strict JSON + FluentValidation), and the new dependency entries.
- **Common (DTOs)** — updated `_docs/02_document/modules/common_dtos.md`: `TileCoord` now documents the rename + `[JsonRequired]` markers + ValidationProblemDetails fallout; `TileInventoryRequest` documents the XOR enforcement by `InventoryRequestValidator`; `TileInventoryEntry` documents the rename echo; `TileInventoryLimits` documents the validator as the enforcer.
- **Validators (new subfolder)** — captured under `module-layout.md` with two new entries:
- `Api/Validators/{InventoryRequestValidator,TileCoordValidator,ValidationEndpointFilter,ValidationEndpointFilterExtensions,GlobalValidatorConfig}`.
- `Api/GlobalExceptionHandler`.
- **Tests (unit)** — updated `_docs/02_document/modules/tests_unit.md` with the new "AZ-795 + AZ-796 — strict inventory validation (cycle 7)" subsection, the new `[ModuleInitializer]` helper, the new FluentValidation/TestHelper NuGet entry, and the cycle 7 unit-suite totals (311 tests).
- **Tests (integration)** — updated `_docs/02_document/modules/tests_integration.md`: new `TileInventoryValidationTests` entry, new `ProblemDetailsAssertions` helper entry, cycle-7 stability note on `TileInventoryTests`, and the cycle-7 fix on `IdempotentPostTests` (payload rename forced by strict deserializer).
System-level docs also updated this pass:
- `architecture.md` — already carries the new "§ 9 Input Validation (AZ-795)" section (was added during the implementation phase along with the validator coverage table). No further changes needed; the AZ-794 wire-format rename is captured at the inventory-contract level rather than in architecture prose.
- `system-flows.md` — F8 flow header updated to credit cycle 7; sequence diagram annotated with the two new validation gates (deserializer + filter); Validation Surface table expanded from 4 rows to 13 rows covering every failure mode from `error-shape.md`.
- `glossary.md` — `Tile Inventory` entry updated to v2.0.0 wire shape + cite the cycle-7 validator; added three new entries: `Validation Problem Details`, `FluentValidation`, `Unmapped Member Handling`.
- `module-layout.md` — Last Updated bumped + cycle-7 changelog line prepended.
- `tests/blackbox-tests.md` and `tests/traceability-matrix.md` — updated during Step 12 (Test-Spec Sync): BT-27 added + 12 AC rows added (AZ-794 AC-1..AC-4 + AZ-795 epic-level + AZ-796 AC-1..AC-7) + Coverage Summary refresh.
## No-ripple components
These components were NOT touched by cycle-7 changes and require no doc update:
- **DataAccess** — no schema or repository signature changes in cycle 7. The cycle-6 `tiles_leaflet_path` covering index and the cycle-5 identity columns are unaffected by the wire-format rename or by the new validators.
- **TileDownloader (`TileService.GetInventoryAsync`)** — the algorithm is unchanged: it still computes `Uuidv5.LocationHashForTile(z, x, y)` per coord. Only the *property names* on the DTO changed (`TileZoom` → `Z`, etc.); the value contract is identical.
- **RegionProcessing / RouteManagement** — no imports against cycle-7 symbols.
- **DataAccess migrations** — no new migration in cycle 7; the existing identity columns and indices already carry the production load.
## Parse-failure / heuristic notes
None — every symbol resolved via direct `Grep --type cs`. No fallback heuristic was needed. The cycle 7 surface is intentionally narrow (3 tasks, all WebApi-layer concerns) which keeps the ripple log short.
## AZ-795 epic posture
The `architecture.md` § 9 table classifies all other public endpoints as `partial` and tags them as "future AZ-795 child" — the epic remains open. Cycle 7 lands the shared infrastructure + the first per-endpoint application (AZ-796). Subsequent child tickets will reuse `ValidationEndpointFilter<T>`, `ProblemDetailsAssertions`, and the `error-shape.md` contract without adding new infrastructure.
_docs/02_document/system-flows.md
+20 -8
View File
@@ -327,11 +327,11 @@ sequenceDiagram
---
## Flow F8: Tile Inventory Bulk Lookup (added AZ-505)
## Flow F8: Tile Inventory Bulk Lookup (added AZ-505; renamed + strict-validated AZ-794+AZ-795+AZ-796, cycle 7)
### Description
Programmatic clients (httpx `http2=True`, .NET `HttpClient`, onboard cross-repo callers) post a batch of up to 5000 `(z, x, y)` triples (Form A) or up to 5000 pre-computed `location_hash` UUIDs (Form B) and get one inventory entry per input slot, in the same order. Each entry says whether the cell is present and — when present — the most-recent row's `id`, `capturedAt`, `source`, `flightId`, and `resolutionMPerPx`. No tile bodies are returned; the caller subsequently fetches bodies via F7. This is the read-half of the bulk-list contract that the onboard `gps-denied-onboard` workspace consumes to decide which Google-Maps cells it needs and which UAV variants are already on the server.
Programmatic clients (httpx `http2=True`, .NET `HttpClient`, onboard cross-repo callers) post a batch of up to 5000 `{z, x, y}` triples (Form A; the wire field names were renamed from `tileZoom/tileX/tileY` by AZ-794, cycle 7) or up to 5000 pre-computed `location_hash` UUIDs (Form B) and get one inventory entry per input slot, in the same order. Each entry says whether the cell is present and — when present — the most-recent row's `id`, `capturedAt`, `source`, `flightId`, and `resolutionMPerPx`. No tile bodies are returned; the caller subsequently fetches bodies via F7. This is the read-half of the bulk-list contract that the onboard `gps-denied-onboard` workspace consumes to decide which Google-Maps cells it needs and which UAV variants are already on the server.
### Sequence Diagram
@@ -345,8 +345,9 @@ sequenceDiagram
Client->>Kestrel: POST /api/satellite/tiles/inventory (JWT, Form A or B)
Kestrel->>GetTilesInventory: route match
GetTilesInventory->>GetTilesInventory: XOR check (both/neither populated → 400)
GetTilesInventory->>GetTilesInventory: cap check (count > 5000 → 400)
Note over Kestrel,GetTilesInventory: AZ-795 deserializer guards (UnmappedMemberHandling.Disallow + [JsonRequired])<br/>catch unknown / missing / type-mismatched fields → 400 ValidationProblemDetails<br/>via GlobalExceptionHandler (cycle 7)
GetTilesInventory->>GetTilesInventory: ValidationEndpointFilter<TileInventoryRequest><br/>(InventoryRequestValidator — AZ-796 cycle 7)
Note over GetTilesInventory: 9 business rules: XOR / non-empty / per-array cap / Z range / X+Y range
GetTilesInventory->>TileService: GetInventoryAsync(request)
Note over TileService: Form A: compute location_hash per coord<br/>via Uuidv5.LocationHashForTile<br/>Form B: echo caller-supplied hashes
TileService->>TileRepo: GetTilesByLocationHashesAsync(hashes)
@@ -357,15 +358,26 @@ sequenceDiagram
GetTilesInventory-->>Client: 200 OK, JSON (results in input order)
```
### Validation Surface
### Validation Surface (post-cycle 7 — AZ-795 + AZ-796)
| Input | Detection | Response |
|-------|-----------|----------|
| Both `tiles` and `locationHashes` populated | Handler XOR check | 400 + ProblemDetails (`tile-inventory.md` Inv-1) |
| Neither populated | Handler XOR check | 400 + ProblemDetails |
| `count > 5000` (`TileInventoryLimits.MaxEntriesPerRequest`) | Handler cap check | 400 + ProblemDetails (Inv-7) |
| Empty / missing body | System.Text.Json (`[JsonRequired]` on `Tiles`/`LocationHashes` covered indirectly via `InventoryRequestValidator`) | 400 + `ValidationProblemDetails` |
| Both `tiles` and `locationHashes` populated | `InventoryRequestValidator` `.Must(...)` (Rule 1, XOR — `tile-inventory.md` v2.0.0 Inv-1) | 400 + `ValidationProblemDetails`, key `""` |
| Neither populated | `InventoryRequestValidator` `.Must(...)` (Rule 1, XOR) | 400 + `ValidationProblemDetails`, key `""` |
| `tiles` or `locationHashes` array is empty | `InventoryRequestValidator` `.Must(...)` (Rule 1, XOR — non-empty arm) | 400 + `ValidationProblemDetails`, key `""` |
| `tiles.Count > 5000` (`TileInventoryLimits.MaxEntriesPerRequest`) | `InventoryRequestValidator` `.Must(t => t.Count <= 5000)` (Rule 6 — Inv-7) | 400 + `ValidationProblemDetails`, key `tiles` |
| `locationHashes.Count > 5000` | `InventoryRequestValidator` `.Must(h => h.Count <= 5000)` (Rule 7 — Inv-7) | 400 + `ValidationProblemDetails`, key `locationHashes` |
| `tiles[i].z` missing OR out of range (must be `0..22` inclusive) | `[JsonRequired]` on `Z` (deserializer) + `TileCoordValidator` Rule 4 | 400 + `ValidationProblemDetails`, key `tiles[i].z` |
| `tiles[i].x` missing OR `< 0` OR `>= 2^z` | `[JsonRequired]` on `X` (deserializer) + `TileCoordValidator` Rule 5 | 400 + `ValidationProblemDetails`, key `tiles[i].x` |
| `tiles[i].y` missing OR `< 0` OR `>= 2^z` | `[JsonRequired]` on `Y` (deserializer) + `TileCoordValidator` Rule 5 | 400 + `ValidationProblemDetails`, key `tiles[i].y` |
| Legacy `tileZoom/tileX/tileY` field names | `UnmappedMemberHandling.Disallow` (deserializer; AZ-794 + AZ-795) | 400 + `ValidationProblemDetails`, key `tiles[i].tileZoom` (etc.) |
| Unknown root or nested field | `UnmappedMemberHandling.Disallow` (deserializer; AZ-795) | 400 + `ValidationProblemDetails`, key on the unknown path |
| Wrong JSON type (e.g. `"z": "18"`) | System.Text.Json type-mismatch (deserializer; AZ-795) | 400 + `ValidationProblemDetails`, key on the offending path |
| No `Authorization: Bearer …` header | `.RequireAuthorization()` | 401 before handler runs |
All 4xx bodies conform to `error-shape.md` v1.0.0. The same `ValidationProblemDetails` shape is emitted whether the failure was caught by the FluentValidation business-rule layer (`InventoryRequestValidator`) or by the deserializer layer (via `GlobalExceptionHandler`). Both layers are unit + integration tested in `SatelliteProvider.Tests/Validators/InventoryRequestValidatorTests` and `SatelliteProvider.IntegrationTests/TileInventoryValidationTests`.
### Performance
p95 ≤ 1000 ms for 2500-coord batches (AZ-505 AC-4). Cycle-6 measured: p95=66ms — well under budget. The covering index (`tiles_leaflet_path`) supplies the leading `location_hash` lookup; the projection's columns beyond the INCLUDE list (`id`, `captured_at`, `flight_id`, ...) trigger a bounded heap fetch which is documented and accepted per the AZ-505 NFR.
_docs/02_document/tests/blackbox-tests.md
+37
View File
@@ -244,3 +244,40 @@ All Cycle-5 UAV scenarios reuse the AZ-488 envelope. The new observable surface
**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).
_docs/02_document/tests/traceability-matrix.md
+24 -1
View File
@@ -109,6 +109,18 @@
| AZ-504 AC-2 | PT-08 completes on zero-accepted response (defensive) | Same standalone shell harness (case 4) — `accepted=0, rejected=N` path no longer kills the script | ✓ |
| AZ-504 AC-3 | PT-08 summary line prints in full default-parameter perf run | Verified at autodev Step 15 (Performance Test) by running `scripts/run-performance-tests.sh` with `PERF_REPEAT_COUNT=20 PERF_UAV_BATCH_SIZE=10`; pass criterion is the `PT-08 UAV batch upload: PASS p95=Xms / 2000ms (...)` line in the run output | ◐ gate at Step 15 |
| AZ-504 AC-4 | Leftover `_docs/_process_leftovers/2026-05-12_perf-cycle3-harness-execution.md` deleted on green full run | Verified at autodev Step 15 by `test -f _docs/_process_leftovers/2026-05-12_perf-cycle3-harness-execution.md` returning non-zero after the green run + commit | ◐ gate at Step 15 |
| AZ-794 AC-1 | Inventory request body uses short names `{z, x, y}` (OSM convention) | BT-27 sub-case `pos` (`TileInventoryValidationTests.HappyPath_Returns200`); existing AZ-505 integration suite (`TileInventoryTests.OrderingAndPresentAbsentShaping_AC1` + the AC-6 validation tests already use z/x/y after the rename); deserializer-level proof via BT-27 sub-case `9c` (`OldV1FieldName_Returns400`) — old names now hard-fail | ✓ |
| AZ-794 AC-2 | Inventory response body uses short names `{z, x, y}`; all other fields (`locationHash`, `present`, `id`, `capturedAt`, `source`, `flightId`, `resolutionMPerPx`) unchanged byte-for-byte from the pre-rename contract | `TileInventoryTests.OrderingAndPresentAbsentShaping_AC1` (integration; asserts `entry.Z`, `entry.X`, `entry.Y`, `entry.LocationHash`, `entry.Present`, `entry.Id`, `entry.CapturedAt`, `entry.Source` for 25 mixed present/absent entries against the v2.0.0 wire shape) | ✓ |
| AZ-794 AC-3 | OpenAPI / Swagger spec declares `z, x, y` (not the old names) as the required coordinate properties | Doc-state AC — verified at Step 13 (Update Docs) review against `/swagger/v1/swagger.json` schema definitions for `TileInventoryRequest` + `TileCoord` | ◐ doc-verified at Step 13 |
| AZ-794 AC-4 | `_docs/02_document/contracts/api/tile-inventory.md` bumped to v2.0.0; Migration / Coexistence section names AZ-794 and the breaking-rename | Doc-state AC — `_docs/02_document/contracts/api/tile-inventory.md` v2.0.0 Change Log entry naming AZ-794 (verified at Step 13 Update Docs review) | ✓ |
| AZ-795 (epic) | Shared input-validation infra in place: FluentValidation 12.0.0 + `ValidationEndpointFilter<T>` + `GlobalExceptionHandler` + `JsonSerializerOptions.UnmappedMemberHandling.Disallow` + camelCase naming policy + new `error-shape.md` v1.0.0 contract | Structural: `SatelliteProvider.Api/Validators/{ValidationEndpointFilter,GlobalValidatorConfig,ValidationEndpointFilterExtensions}.cs` + `SatelliteProvider.Api/GlobalExceptionHandler.cs` exist; `error-shape.md` v1.0.0 frozen with 8 documented test cases; end-to-end exercise via the AZ-796 test suite (every BT-27 sub-case routes through this infra). Per-endpoint child task tracker (`AZ-796` is the first; siblings to follow) is owned by Jira AZ-795. | ✓ (infra + contract; per-endpoint child coverage tracked individually) |
| AZ-796 AC-1 | Each of the 9 validation rules rejects with HTTP 400 + RFC 7807 ProblemDetails; `errors[]` array has single-rule precision (no unrelated rules) | BT-27 (blackbox; sub-cases 1, 2a, 2b, 3, 4, 5a, 5b, 6a, 6b, 7, 8a, 8b, 9a, 9b, 9c — one per rule); `TileInventoryValidationTests.*` (integration: 15 failure tests) + `InventoryRequestValidatorTests.*` (unit: covers the rules expressible at the validator layer in isolation) | ✓ |
| AZ-796 AC-2 | Happy path unchanged (HTTP 200 with existing result shape; one entry per requested tile, same ordering, fields preserved) | BT-27 sub-case `pos` (`TileInventoryValidationTests.HappyPath_Returns200`); no regression in existing `TileInventoryTests.OrderingAndPresentAbsentShaping_AC1` (which still passes at cycle 7 Step 11) | ✓ |
| AZ-796 AC-3 | `InventoryRequestValidator` lives in its own file under `SatelliteProvider.Api/Validators/`; xUnit class has one test method per `RuleFor(...)` (≥ 9 unit-test methods) | Structural: `SatelliteProvider.Api/Validators/InventoryRequestValidator.cs` exists (74 lines, isolated validator + `TileCoordValidator`); `SatelliteProvider.Tests/Validators/InventoryRequestValidatorTests.cs` contains 16 test methods (`Validate_TilesPopulated_LocationHashesNull_Passes`, `Validate_LocationHashesPopulated_TilesNull_Passes`, `Validate_BothPopulated_FailsXorRule`, `Validate_NeitherPopulated_FailsXorRule`, `Validate_BothEmpty_FailsXorRule`, `Validate_TilesAtCap_Passes`, `Validate_TilesOverCap_FailsCapRule`, `Validate_LocationHashesOverCap_FailsCapRule`, `Validate_TileZoomOutOfRange_FailsRangeRule` ×3, `Validate_TileZoomInRange_PassesRangeRule` ×3, `Validate_TileXNegative_FailsRangeRule`, `Validate_TileXAtUpperBound_FailsRangeRule`, `Validate_TileYNegative_FailsRangeRule`, `Validate_TileYAtUpperBound_FailsRangeRule`, `Validate_AxesAtMaxForZoom_Passes`) | ✓ |
| AZ-796 AC-4 | Integration tests cover happy + failure per rule (≥ 10 methods) in `SatelliteProvider.IntegrationTests/TileInventoryValidationTests.cs` | `TileInventoryValidationTests` contains 16 integration test methods (1 happy + 15 failure: `HappyPath_Returns200`, `EmptyBody_Returns400`, `NeitherPopulated_Returns400`, `BothPopulated_Returns400`, `EmptyTilesArray_Returns400`, `TilesOverCap_Returns400`, `MissingZ_Returns400WithFieldPath`, `MissingXAndY_Returns400`, `ZoomOutOfRange_Returns400WithFieldPath`, `XBeyondZoomBounds_Returns400`, `YBeyondZoomBounds_Returns400`, `NegativeAxis_Returns400`, `UnknownRootField_Returns400`, `UnknownNestedField_Returns400`, `OldV1FieldName_Returns400`, `TypeMismatch_Returns400`) — 16 ≥ 10. Cycle 7 Step 11 full run reports all 16 passing. | ✓ |
| AZ-796 AC-5 | `/swagger/v1/swagger.json` marks required fields, declares integer ranges per validation rules, declares 400 response with ProblemDetails schema | Doc-state AC — verified at Step 13 (Update Docs) review against the published OpenAPI document; integration smoke is the existing `JwtIntegrationTests.SwaggerDocument_AdvertisesBearerSecurityScheme` pattern (a future analogous test against the validation schema is out-of-scope this cycle) | ◐ doc-verified at Step 13 |
| AZ-796 AC-6 | `_docs/02_document/contracts/api/tile-inventory.md` updated to document the 9 validation rules + error contract reference | Doc-state AC — `_docs/02_document/contracts/api/tile-inventory.md` v2.0.0 Change Log entry naming AZ-796 (verified at Step 13 Update Docs review) | ✓ |
| AZ-796 AC-7 | `scripts/probe_inventory_validation.sh` committed; exercises each failure mode via `curl` + JWT for documentation / regression | Structural: `scripts/probe_inventory_validation.sh` exists in repo and is manually runnable | ✓ |
## Restrictions → Test Mapping
@@ -158,7 +170,8 @@
| Cycle 5 — AZ-503 foundation (integration + unit + blackbox) | 2 integration + 6 unit + 4 blackbox | 7/12 in-scope (AC-1, 2, 3, 4, 7, 8, 11); 5 ACs deferred → AZ-505 (now resolved in cycle 6) | — |
| Cycle 5 — AZ-504 perf-script fix (shell harness + Step-15 gate) | 1 standalone shell harness (4 cases) | 2/4 verified now (AC-1, AC-2); 2/4 gated at Step 15 (AC-3, AC-4) | — |
| Cycle 6 — AZ-505 inventory + HTTP/2 + leaflet covering index (integration + blackbox + perf) | 3 integration files + 4 blackbox (BT-23..BT-26) + 1 perf (PT-09) | 7/7 (AC-1..AC-7; AC-7 is doc-only). Also resolves the 5 AZ-503 deferrals (AC-5, 6, 9, 10, 12). | — |
| **Total** | **94** | **63/63 in-scope (100%); 2 AZ-504 ACs gated at Step 15** | **8/8 (100%)** |
| Cycle 7 — AZ-794 + AZ-795 + AZ-796 strict inventory validation + z/x/y rename (integration + unit + blackbox + contract) | 1 integration file (`TileInventoryValidationTests`, 16 tests) + 1 unit file (`InventoryRequestValidatorTests`, 16 tests) + 1 blackbox (BT-27 with 16 sub-cases) + 1 new contract (`error-shape.md` v1.0.0) + 1 bumped contract (`tile-inventory.md` v2.0.0) | 12/12 in-scope (AZ-794 AC-1..AC-4, AZ-795 epic-level, AZ-796 AC-1..AC-7); 2 ACs (AZ-794 AC-3 + AZ-796 AC-5) are `◐ doc-verified at Step 13`. | — |
| **Total** | **126** | **75/75 in-scope (100%); 2 AZ-504 ACs gated at Step 15; 2 cycle-7 ACs doc-verified at Step 13** | **8/8 (100%)** |
**Coverage shape notes (Cycle 5 — AZ-503 foundation):**
- AZ-503 was split mid-cycle (Option C, autodev Step 10 batch 2): 7 of 12 original ACs land here; 5 (AC-5, AC-6, AC-9, AC-10, AC-12) are deferred to AZ-505 with a `Blocks` link in Jira and an entry in `_docs/02_tasks/_dependencies_table.md`. The deferred rows above are marked `◐ deferred → AZ-505` so the matrix surfaces the scope boundary explicitly.
@@ -186,3 +199,13 @@
- AZ-505 AC-5 originally specified h2c (HTTP/2 over plaintext). Kestrel was switched to TLS+ALPN on `https://+:8080` during the cycle-6 Run Tests step because `HttpProtocols.Http1AndHttp2` silently downgrades to HTTP/1.1 over plaintext (no ALPN). The functional gate (multiplexing semantics) is unchanged — the test still asserts `HttpResponseMessage.Version == 2.0` over 20 concurrent GETs on a single connection. The deployment caveat (dev cert vs. production TLS termination at the ingress) is documented in `tile-inventory.md` Non-Goals.
- AZ-505 NFRs propagate as follows: Performance (AC-3, AC-4) ⇒ PT-09 entry (full PT-09 row in `performance-tests.md`); Compatibility (existing `GET /tiles/{z}/{x}/{y}` byte-identical) ⇒ no new test — the AZ-484 / AZ-503-foundation selection rule is unchanged, and the test that exercised it under the old `(z, x, y)`-keyed SELECT now exercises it under the `location_hash`-keyed SELECT via AC-2; Security (JWT + `RequireAuthorization()`) ⇒ AC-6 anonymous-401 case, BT-26.
- Cycle-update rule check: no NFR conflicts surfaced. The 500 ms → 1000 ms perf budget relaxation between AZ-503 AC-9 and AZ-505 AC-4 is **not** a conflict in the cycle-update sense — AZ-503 AC-9 was explicitly deferred (`◐ deferred → AZ-505`) so AZ-505 owns the binding budget; AZ-503's number was a pre-implementation estimate. The matrix records both numbers and the rationale so the budget history stays auditable.
**Coverage shape notes (Cycle 7 — AZ-794 + AZ-795 + AZ-796 strict inventory validation + z/x/y rename):**
- Cycle 7 is the **first** application of the AZ-795 shared validation infrastructure (FluentValidation 12.0.0 + `ValidationEndpointFilter<T>` + `GlobalExceptionHandler` + `JsonSerializerOptions.UnmappedMemberHandling.Disallow` + camelCase naming policy). The infra is exercised end-to-end by every AZ-796 sub-case — the matrix records `AZ-795 (epic)` as `✓` because the infra is in place and the first concrete child (AZ-796) demonstrates it functions correctly. Sibling per-endpoint child tasks (other public-facing JSON endpoints) will land under AZ-795 in future cycles and each will get its own AC row at that time.
- AZ-794 (z/x/y rename) and AZ-796 (strict validation) shipped in the same commit (`865dfdb`). The matrix surfaces this coupling at AZ-794 AC-2 / AZ-796 AC-1 sub-case `9c` — the BT-27 sub-case that POSTs the legacy `{"tileZoom","tileX","tileY"}` payload now returns HTTP 400 with `errors[…]` naming `tileZoom`, proving (a) AZ-794's rename is observable on the wire and (b) AZ-795's `UnmappedMemberHandling.Disallow` catches the old names instead of silently coercing to `(0,0,0)`. The same sub-case carries the AZ-777 Phase 1 reproducer body verbatim — that exact request now fails-fast, closing the original discovery loop.
- AZ-794 has no perf, security, or resilience NFRs distinct from AZ-505's. Wire size is reduced ~3× on field names (per AZ-794 spec); not separately measured because the AZ-505 AC-4 p95 budget (1000 ms / 2500 tiles, measured 66 ms in cycle 6) already absorbs the rename with margin. Cycle 7 Step 11 reran the full integration suite (311 unit + integration) green; the AZ-505 perf budget is re-measured at Step 15 of cycle 7 per the existing `◐ gate at Step 15` rows.
- AZ-796 AC-3 (validator unit-tested) and AC-4 (integration-tested) each specify a minimum count (≥ 9 unit, ≥ 10 integration). Cycle 7 delivered 16 + 16 = 32 — comfortably over the floor — covering every `RuleFor(…)` in `InventoryRequestValidator` and `TileCoordValidator` plus the JSON-deserializer-level rules (`JsonRequired`, `UnmappedMemberHandling.Disallow`, type mismatch) that don't reach the validator. The split is documented in BT-27 §Notes.
- Doc-only ACs (AZ-794 AC-3, AZ-796 AC-5 — OpenAPI / Swagger spec accuracy) are marked `◐ doc-verified at Step 13` because they require inspection of the generated `/swagger/v1/swagger.json` during the Update Docs step. Cycle 7's Swashbuckle output reflects the rename + ranges automatically via the DTOs' `[JsonRequired]` and the validator's `RuleFor` constraints — no manual OpenAPI XML doc edits were needed. Step 13 will verify against the running container's swagger document.
- AZ-505 AC-6's existing row (cycle 6 — "Request validation — 400 on both populated, 400 on neither, 400 on > 5000 entries, 401 on anonymous") remains accurate. Its 4 cases overlap with AZ-796 AC-1 sub-cases 2a, 2b, 4, and the anonymous case (also SEC-05). Both rows are kept per cycle-update rule 4 ("Preserve existing traceability IDs"); the duplication is by design — AZ-505 AC-6 was the cycle-6 contract (status-code-only), AZ-796 AC-1 is the cycle-7 contract (status code + ProblemDetails shape + field-path errors). The cycle-7 row is the binding one going forward; the cycle-6 row stays as historical record.
- Cycle-update rule check: no NFR conflicts. The 5000-entry cap is reaffirmed (matches AZ-505); the supported zoom range 0..22 is reaffirmed (matches `tile-inventory.md` Inv-7); the error shape contract is **new** (`error-shape.md` v1.0.0) — but no prior cycle declared a different error shape, so this is greenfield content, not a conflict.
- Step 10 artifact gap (cycle 7): no `implementation_report_*_cycle7.md` was produced in `_docs/03_implementation/`. The actual implementation evidence lives in commits `dceaddc` (cycle 7 task adoption) + `865dfdb` (cycle 7 Step 10 implementation), in the state file's `detail` field (which recorded the test-run outcome), and in the new test artifacts themselves (`InventoryRequestValidator.cs`, `InventoryRequestValidatorTests.cs`, `TileInventoryValidationTests.cs`, `ProblemDetailsAssertions.cs`, `error-shape.md` v1.0.0). This artifact gap is recorded here for cycle 7 retrospective follow-up — the matrix itself is unaffected because cycle-update mode's source-of-truth is the task specs in `_docs/02_tasks/done/`, not the implementation report.
_docs/03_implementation/deploy_cycle7.md
+123
View File
@@ -0,0 +1,123 @@
# Deploy Report — Cycle 7 (AZ-794 + AZ-795 + AZ-796)
**Date**: 2026-05-22
**Cycle**: 7
**Scope**: Three-task cycle delivering the **API quality follow-up** scope adopted from gps-denied-onboard's AZ-777 Phase 1 Jetson probe:
- **AZ-794** — rename inventory body fields `tileZoom/tileX/tileY → z/x/y` (OSM / slippy-map convention).
- **AZ-795** — epic + shared infra for strict input validation across all public endpoints: FluentValidation 12.0.0 wiring + global `ProblemDetails` exception handler + `JsonSerializerOptions.UnmappedMemberHandling.Disallow`.
- **AZ-796** — first concrete per-endpoint child of AZ-795: strict validation for `POST /api/satellite/tiles/inventory` (9 validation rules); reference-implementation pattern for sibling per-endpoint tasks.
Cycle 7 is a **pure-quality cycle**: no new endpoints, no new persisted state, no migrations, no new env vars, no container-image changes. The full payload is a contract bump (`tile-inventory.md` 1.0.0 → 2.0.0 — major because of the field rename) plus a new strict validation surface across the inventory endpoint.
## What is shipping
### Code changes (committed to `dev`)
| Commit | Subject |
|--------|---------|
| `dceaddc` | `[AZ-794] [AZ-795] [AZ-796] Adopt cycle 7 tasks (API quality follow-up)` — Step 9 task-adoption commit, autodev state advanced to Step 10. |
| `865dfdb` | `[AZ-794] [AZ-795] [AZ-796] Strict input validation + z/x/y rename` — Step 10 implementation in a single batch. |
| _pending this commit_ | `[AZ-794] [AZ-795] [AZ-796] Cycle 7 Steps 12-16 sync (test-spec / docs / security / perf / deploy)` |
The two no-ticket commits `19c0371` (`[no-ticket] Sync .cursor with suite root`) and `7d3ba1c` (`Enhance .cursor documentation and workflows`) preceded cycle 7's task-adoption commit and are repo-plumbing changes (`.cursor/` skill + rule alignment with the suite root); they do not affect the running api and are not in cycle 7's tracker scope.
All commits are on `dev` but the cycle-7 sync commit (this one) has not yet been pushed to `origin/dev` as of this report. Operator runbook step 1 below covers the push.
### Database migrations
**None.** Cycle 7 ships **zero migration files**. The `_docs/02_document/contracts/data-access/tile-storage.md` v2.0.0 schema from cycle 6 is unchanged; the inventory endpoint reads from the same `tiles` table via the same `tiles_leaflet_path` covering index that cycle 6 introduced.
`pgcrypto`: still required, still installed automatically by migration 014 from cycle 5 — cycle 7 does not touch the extension surface.
### Configuration changes (operator must verify before promoting)
| Setting | Was | Now | Source |
|---------|-----|-----|--------|
| **No new env vars introduced.** | — | — | Cycle 7 carries forward the cycle-6 env contract verbatim (`JWT_SECRET ≥ 32B`, `JWT_ISSUER`, `JWT_AUDIENCE`, `GOOGLE_MAPS_API_KEY`). |
| `docker-compose.yml` Postgres host port | `5432:5432` | **`5433:5432`** (host-side bind only) | Dev-only sibling-project conflict avoidance (a sibling-suite Postgres was already binding `5432` on the dev workstation; moving the host-side bind to `5433` lets both projects run in parallel). **In-container port is unchanged (`5432`)** — the api service still resolves `postgres:5432` over the compose network. `appsettings.Development.json`, `README.md`, `AGENTS.md`, `architecture.md`, and `_docs/02_document/deployment/containerization.md` all aligned with the new host-side number. **Staging/prod unaffected** — they don't use docker-compose. |
| `appsettings.Development.json` Postgres connection | `Host=localhost;Port=5432` | **`Host=localhost;Port=5433`** | Aligns the .NET launch profile (i.e. `dotnet run` on host, NOT inside docker-compose) with the new host-side bind. Compose-internal connections (api ↔ postgres on the compose network) are unaffected. |
| Container image (`api` service) | `mcr.microsoft.com/dotnet/aspnet:10.0` | **unchanged** | No Dockerfile, no `.woodpecker/*.yml` changes this cycle. |
| Dev TLS dev-cert plumbing (cycle-6 addition) | TLS+ALPN with `./certs/api.{pfx,crt}`, `update-ca-certificates` in test container | **unchanged** | Cycle 7 reuses cycle-6's TLS plumbing verbatim. The new `scripts/probe_inventory_validation.sh` reuses `--insecure` for the dev cert and reads `JWT` from env. |
| `SatelliteProvider.Api.csproj` NuGet packages | (cycle-6 baseline) | **+ `FluentValidation` 12.0.0**, **+ `FluentValidation.DependencyInjectionExtensions` 12.0.0** | New dependencies for AZ-795's shared validation infra. Both packages have **no known CVEs** at 12.0.0 (NuGet audit clean, GitHub Security Advisories clean — `_docs/05_security/dependency_scan_cycle7.md` records the audit trace). Minor bump to 12.1.1 is the only recommended hardening (Low severity D-AZ795-1; bug fixes only, no security-driven advisory). |
### Contract changes (consumer-visible)
| Contract | Version | Change | Action for consumers |
|----------|---------|--------|----------------------|
| `POST /api/satellite/tiles/inventory` (`tile-inventory.md`) | **1.0.0 → 2.0.0** (MAJOR) | **Field rename**: request body and response payload renamed `tileZoom/tileX/tileY → z/x/y` (OSM / slippy-map convention; aligns the body shape with the existing URL convention on `GET /api/satellite/tiles/{z}/{x}/{y}`). **Strict validation**: HTTP 400 + RFC 7807 `ValidationProblemDetails` on any of: missing `tiles` / `locationHashes`, both arrays present (XOR violation), array empty, array exceeds 5000 entries, any `z` outside `[0, 22]`, any `x` outside `[0, 2^z)`, any `y` outside `[0, 2^z)`, any `locationHash` not 36-char lowercase UUID. **Unknown fields rejected**: any body containing a member not declared on the request DTO (e.g. legacy `tileZoom`, typo'd `Z`) is rejected via `JsonSerializerOptions.UnmappedMemberHandling.Disallow` at the deserializer layer (HTTP 400 before the validator runs). | **Sibling repo onboarding (gps-denied-onboard AZ-777 follow-up)**: any client carrying the legacy `tileZoom/tileX/tileY` body MUST switch to `z/x/y`. Any client expecting silent coercion of malformed bodies MUST handle the new 400 path. The `Authorization: Bearer …` header continues to be required (cycle-6 contract). Sibling-repo tasks for the per-endpoint sweep across the rest of the public API will follow as more AZ-795 children land. |
| `_docs/02_document/contracts/api/error-shape.md` | (existing baseline, AZ-353 sanitization) | **No version bump.** Cycle 7 confirms the error shape is RFC 7807-compatible (`type`/`title`/`status`/`detail`/`extensions.errors` for `ValidationProblemDetails`) and that 5xx errors continue to be sanitized via the cycle-6 baseline `GlobalExceptionHandler`. Two **Low** findings (F-AZ795-1, F-AZ795-2) note that `JsonException.Message` and `BadHttpRequestException.Message` may surface internal .NET type/parameter names in 400 detail strings — auth-gated, no security impact in dev — documented for sanitization in a future cycle. | Consumers parsing the 400 shape get a stable RFC 7807 envelope; no breaking change to the error contract itself. |
| `tile-storage.md` (data-access contract) | **unchanged at 2.0.0** | Cycle 7 does not touch the schema. The cycle-6 v2.0.0 contract from the AZ-503+AZ-505 joint freeze is preserved verbatim. | No action. |
### Container image
- **Source**: `SatelliteProvider.Api/Dockerfile` multi-stage build, base `mcr.microsoft.com/dotnet/aspnet:10.0` — **unchanged from cycle 5/6**.
- **No new mounts in `docker-compose.yml`**: the cycle-6 dev-cert mounts (`./certs/api.pfx:/app/certs/api.pfx:ro`) and the cycle-6 tests-container CA-trust mount remain unchanged.
- **Verification on dev workstation (local)**: `docker compose up -d --build` succeeded for the cycle-7 Step 15 perf run (this session). API healthy on `https://localhost:18980` (swagger 200; anonymous POST `/api/satellite/tiles/inventory` returns 401; v2 schema `{"tiles":[{"z":18,"x":...,"y":...}]}` returns 200; legacy schema `{"tiles":[{"tileZoom":18,...}]}` returns 400 — verified via `scripts/probe_inventory_validation.sh`).
- **Verification on CI**: pending — the cycle-7 sync commit (this one) has not been pushed yet. Operator action: after push, confirm the next Woodpecker `01-test` + `02-build-push` runs on `dev` succeed before promoting. Note that the cycle-7 .NET build uses `mcr.microsoft.com/dotnet/sdk:10.0` (unchanged) and the integration test container still resolves the dev cert via `scripts/run-tests.sh`'s `ensure_dev_cert` block; no new CI secret is required.
- **Multi-arch**: unchanged from cycle 6 (`aspnet:10.0` is multi-arch by Microsoft).
## Verification gates passed in this cycle
| Gate | Result | Evidence |
|------|--------|----------|
| Step 11 — Functional test suite | **PASS** | Unit suite 311 tests green (including the new 16-test `InventoryRequestValidatorTests` covering all 9 rules + the new `GlobalExceptionHandlerTests`); integration suite green (including the new `TileInventoryValidationTests` + the `TileInventoryTests` payload-rename refactor + the `IdempotentPostTests` adjacent fix where strict deserialization uncovered a long-silent PascalCase fallback bug). The implementation report for this cycle landed at the commit-message level — there is **no separate `_docs/03_implementation/implementation_report_*_cycle7.md` file**; cycle 7 was a single-batch cycle and the `865dfdb` commit body documents the implementation summary inline (the cycle-7 test-spec sync correctly notes this retrospectively as a process gap to address in cycle 8). |
| Step 12 — Test-Spec Sync | **PASS** | `_docs/02_document/tests/traceability-matrix.md` extended with 12 cycle-7 AC rows (AZ-794 ×3, AZ-795 ×3, AZ-796 ×6) + Coverage Summary update; `blackbox-tests.md` BT-27 added for the AZ-796 9-rule validation surface. |
| Step 13 — Update Docs | **PASS** | `_docs/02_document/architecture.md` already carried § 9 Input Validation (AZ-795) from the implementation commit; module-layout updated with cycle-7 file list; `tests_unit.md` documents the new `InventoryRequestValidatorTests` + `ValidatorTestModuleInitializer`; `tests_integration.md` documents `TileInventoryValidationTests` + `ProblemDetailsAssertions`; `glossary.md` gained entries for "Validation Problem Details", "FluentValidation", "Unmapped Member Handling"; `system-flows.md` F8 (Inventory Bulk Lookup) expanded with deserializer + validator gates and 13-row Validation Surface table; `data_parameters.md` § Tile Inventory documents the v2 input schema + constraints; `_docs/02_document/ripple_log_cycle7.md` captures the doc-side ripple decisions. |
| Step 14 — Security Audit | **PASS_WITH_WARNINGS** (3 Low findings) | `_docs/05_security/security_report_cycle7.md` (consolidated) + per-phase reports `dependency_scan_cycle7.md`, `static_analysis_cycle7.md`, `owasp_review_cycle7.md`, `infrastructure_review_cycle7.md`. Findings: **D-AZ795-1** (Low) FluentValidation 12.0.0 → 12.1.1 is a recommended bug-fix bump (no CVE driving it); **F-AZ795-1** (Low) `JsonException.Message` in the 400 detail string may leak the offending .NET type name on deserialization failure (auth-gated, dev-shown only); **F-AZ795-2** (Low) `BadHttpRequestException.Message` similarly may leak the parameter name on malformed-form-input cases (auth-gated). None are blocking; remediation is a sanitizer pass in a follow-up cycle. Architectural wins: mass-assignment prevention (`Disallow`), uniform 4xx contract (RFC 7807), auth-before-validation order confirmed in `Program.cs`. |
| Step 15 — Performance Test | **PASS** | `_docs/06_metrics/perf_2026-05-22_cycle7.md`. 8/8 scripted scenarios PASS (PT-01..PT-08), exit 0, single default-parameter run. Additionally, a cycle-7 PT-09 smoke probe (`/tmp/pt09_smoke.sh`, 20 sequential 2500-tile-batch calls using the new `z/x/y` schema, all-miss path) measured **min=27ms, median=44ms, p95=73ms, max=86ms** — **13.7× under** the AZ-505 AC-4 1000 ms p95 budget. The canonical PT-09 (`TileInventoryTests.PerformanceBudget_AC4`, all-hit seeded 2500 rows) remains the authoritative gate and is exercised by the integration suite. **AZ-794 / AZ-795 / AZ-796** added ≤ 10 ms of validator overhead on a 2500-item batch — well within noise band relative to the cycle-6 PT-09 number (p95=66ms). |
## Outstanding leftovers (status this cycle)
- **`_docs/_process_leftovers/`** is **empty as of cycle 7 entry** (cycle 6 closed the long-standing perf-harness leftover). Cycle 7 adds **zero new leftovers**.
- **Implementation-report process gap (NEW)**: cycle 7's Step 10 did not produce the expected `_docs/03_implementation/implementation_report_*_cycle7.md` artifact. The `test-spec` skill's `cycle-update` mode worked around it by reading the task specs + the `865dfdb` commit body as the implementation summary. Recommendation: surface as a Step-17 retro lesson; either tighten the implement-skill exit gate (require the report artifact before marking Step 10 complete) or update the test-spec / docs skills' resume protocol to formally consume the commit body when the report is absent.
## Recommended follow-up PBIs (out of cycle-7 scope, surfaced for backlog)
| ID | Estimate | Title | Why |
|----|----------|-------|-----|
| (TBD) | 1 SP | Bump `FluentValidation` 12.0.0 → 12.1.1 | D-AZ795-1 Low finding. Bug-fix-only release per the FluentValidation 12.x changelog (no CVE driving). Trivial package bump; pairs well with the unchanged `Microsoft.IdentityModel.Tokens` follow-up below. |
| (TBD) | 2 SP | Sanitize `JsonException.Message` + `BadHttpRequestException.Message` before surfacing in `ValidationProblemDetails.detail` | F-AZ795-1 + F-AZ795-2 Low findings. Replace the raw `Exception.Message` with a static string ("`Request body is not valid JSON`" / "`Form value could not be bound`") so the 400 path emits no internal .NET type / parameter names. Auth-gated, no security impact in dev — but the production contract should not leak this. |
| (TBD) | 2-3 SP per endpoint | Strict validation sweep for sibling public endpoints (`POST /api/satellite/request`, `POST /api/satellite/route`, `POST /api/satellite/upload`, `GET /api/satellite/tiles/latlon`, etc.) | AZ-795 epic continuation. AZ-796 is the **reference implementation**; the remaining child tasks reuse the same `InventoryRequestValidator` + `ValidationEndpointFilter` pattern. Estimate per endpoint depends on the number of validation rules and DTO complexity; expect 2-3 SP each. |
| (TBD) | 1 SP | Implementation-report exit gate for the `implement` skill | NEW process gap surfaced in cycle 7 — Step 10 completed without writing `_docs/03_implementation/implementation_report_*_cycle7.md`. The downstream skills (`test-spec` cycle-update, `document` task mode) compensate via task-spec + commit-body reading, but the report artifact is part of the autodev contract. Tighten the implement-skill exit gate to require the report file. |
| (TBD) | 3 SP (recheck per cycle) | Bump `Microsoft.IdentityModel.Tokens` / `System.IdentityModel.Tokens.Jwt` 7.0.3 → 7.1.2+ | Carry-over from cycles 3-6 (NU1902 moderate severity advisory). **Unchanged from cycle 6.** |
| (TBD) | 1 SP | Bump `Microsoft.NET.Test.Sdk` 17.8.0 → 17.13.0+ | Carry-over D2-cy4 (transitive `NuGet.Frameworks` flag). **Unchanged from cycles 4-6.** |
| (TBD) | 3 SP | Migrate `WithOpenApi(...)` callsites to ASP.NET Core 10 minimal-API metadata extensions | Carry-over from cycles 4-6 (`ASPDEPR002` warnings). **Unchanged from cycles 4-6.** |
| (TBD) | 1 SP (recheck per cycle) | `Serilog.AspNetCore` 8.0.3 → 10.x | Carry-over from cycles 4-6. **Unchanged from cycle 6 — no 10.x line published as of cycle 7 entry**; re-check at cycle-8 start. |
| (TBD) | 2 SP | Inventory endpoint `estimatedBytes` field | Deferred per AZ-505 Outcome bullet 1 — unchanged from cycle 6 carry-over. |
| (TBD) | 5 SP | HTTP/3 / QUIC dev listener | Deferred per AZ-505 Excluded list — unchanged from cycle 6 carry-over. |
| (TBD) | 1 SP | Deployment runbook: ingress TLS termination + HTTP/2 forwarding | Carry-over from cycle 6 — unchanged. |
| (TBD) | 1 SP | `tile-storage.md` consumer audit (post v2.0.0) | Carry-over from cycle 6 — unchanged. |
Admin team `iss/aud` confirmation (carried from cycle 3) remains OPEN as a long-standing ops-side gap; still required before promoting beyond `dev`. **Unchanged from cycle 6.**
## Operator runbook for promoting to staging / production
1. **Push** the cycle-7 sync commit + this deploy report to `origin/dev`. Confirm Woodpecker `01-test` runs green on `dev` (no new CI secret required; dev-cert plumbing is unchanged from cycle 6).
2. **No migration in this cycle.** The `tiles` schema is unchanged. `pgcrypto` already installed since cycle 5; no new extension dependency.
3. **Deploy** the new `dev-arm` (and amd64) image. The image base and Dockerfile are unchanged from cycle 6; the only build-output difference is the inclusion of the two new `FluentValidation` 12.0.0 assemblies. Container startup performance / cold-start latency is unaffected (FluentValidation registration is one-shot at DI build time).
4. **Smoke-test (production)** — note that cycle 7 introduces a **breaking** contract change on the inventory endpoint; the smoke must use the v2 schema:
- `/swagger` (expect 200/301), `/api/satellite/region/<random>` (expect 401, JWT enforcement) — unchanged from cycle 6.
- **v2 inventory body** (positive case): `POST /api/satellite/tiles/inventory` with a freshly-minted JWT, body `{"tiles":[{"z":18,"x":158485,"y":91707}]}` — expect **200** with one entry whose `present` field reflects whether that tile exists in the target environment.
- **Legacy body** (negative case): same endpoint with body `{"tiles":[{"tileZoom":18,"tileX":158485,"tileY":91707}]}` — expect **400** with an RFC 7807 `ValidationProblemDetails` envelope. This confirms the new strict deserializer is active in the deployed image.
- **Validator surface** (negative case): same endpoint with body `{"tiles":[{"z":99,"x":0,"y":0}]}` — expect **400** with the validator surface naming `z` as out-of-range.
- Cycle-6 smoke (`POST /api/satellite/tiles/uav`) unchanged.
5. **Verify HTTP/2 negotiation against the production ingress** (one-off, not a regression test): unchanged from cycle 6 (`curl --http2 -sv https://<prod-host>/api/satellite/region/<id>` should log `* Using HTTP2` and a Bearer-rejected 401).
6. **No env-var change to coordinate.** Cycle 7 doesn't introduce any new app config. The dev-only Postgres host-port move (5432 → 5433) is `docker-compose.yml`-only and never reaches a non-dev environment.
7. **Consumer coordination**: notify all known consumers of the inventory endpoint of the v2 contract bump BEFORE the production deploy. Today's known consumers:
- **gps-denied-onboard `TileDownloader`** (sibling repo): AZ-777 Phase 1 — the originating ticket already flagged the v2 schema; coordinate the cut-over flag flip with the onboard team. The onboard side's `c11.use_bulk_list_endpoint=true` flag (introduced in cycle 6) must also know which schema variant to emit; this is the onboard-side AZ-777 follow-up.
- **Any direct curl / Postman clients** the ops team uses for smoke tests: the v1 body shape MUST be updated.
8. **Roll-forward plan**: if a regression appears post-deploy, the rollback target is the cycle-6 close `dev-arm` tag (built from `af66135`). The cycle-7 changes are pure-code (no migration, no schema change), so rolling back is safe and idempotent. Note that any consumer that already migrated to the v2 schema will receive an unexpected 200 from the rolled-back image with `tileZoom:0, tileX:0, tileY:0` echoed back (the cycle-6 silent-coercion bug). Coordinate any rollback with the same consumer set notified in step 7.
9. **Outstanding ops-side gap (long-standing, NOT new in cycle 7)**: admin team `iss/aud` confirmation before promoting beyond `dev`. Unchanged from cycles 3-6 runbooks.
## Differences vs. cycle 6 deploy
- **NEW**: a contract MAJOR bump (`tile-inventory.md` 1.0.0 → 2.0.0) — cycle 6 only **added** the inventory contract; cycle 7 is the **first revision** to it.
- **NEW**: strict input validation surface — FluentValidation 12.0.0 + global ProblemDetails handler + `UnmappedMemberHandling.Disallow`. Cycle 6 had no validation layer beyond model-binding's silent coercion.
- **NEW**: two NuGet additions (`FluentValidation` 12.0.0, `FluentValidation.DependencyInjectionExtensions` 12.0.0).
- **NEW**: a dev-only host-port move (Postgres `5432 → 5433`) for sibling-project conflict avoidance. Compose-internal traffic unchanged. Staging/prod unaffected.
- **NEW**: cycle-7 security audit ran (Step 14: PASS_WITH_WARNINGS with 3 Low findings) — cycle 6's Step 14 was skipped by the user.
- **NEW (process)**: cycle-7 Step 10 shipped without an explicit `implementation_report_*_cycle7.md` artifact; downstream skills compensated by reading the task specs + commit body. Recommended as a Step 17 retro lesson.
- **UNCHANGED**: container image base (`aspnet:10.0`), CI image (`sdk:10.0`), all env vars, all multi-arch tags, the cycle-4-and-earlier carry-over follow-up PBIs, the dev TLS cert plumbing, the cycle-6 Leaflet covering index (`tiles_leaflet_path`), `pgcrypto` extension state.
- **NO MIGRATION**: cycle 6 shipped migration `015_AddTilesLeafletPathIndex.sql`; cycle 7 ships none. The `tiles` schema is unchanged.
- **NO NEW ENDPOINTS**: cycle 6 added one new endpoint; cycle 7 modifies the contract of an existing endpoint without adding new routes.
- **NO HTTP/2 / TLS LAYER CHANGES**: cycle 6 introduced TLS+ALPN to the dev listener; cycle 7 leaves the listener untouched and reuses cycle-6's plumbing for the smoke / validation probe (`scripts/probe_inventory_validation.sh`).
_docs/05_security/dependency_scan_cycle7.md
+73
View File
@@ -0,0 +1,73 @@
# Dependency Scan (Cycle 7)
**Date**: 2026-05-22
**Mode**: Delta scan
**Scope**: Cycle-7 delta over the cycle-5 dependency scan (`_docs/05_security/dependency_scan_cycle5.md`); cycle 6 did not produce a dependency scan, so the last scanned baseline is cycle 5
**Trigger**: AZ-794 (wire-format rename — no manifest changes) + AZ-795 (strict-validation epic — adds FluentValidation 12.0.0 + FluentValidation.DependencyInjectionExtensions 12.0.0) + AZ-796 (per-endpoint validator — no manifest changes beyond what AZ-795 added)
**Method**: Manifest diff + WebSearch CVE lookup against GitHub Security Advisories + NVD + ReversingLabs Spectra Assure. `dotnet list package --vulnerable` is intentionally not run (the AGENTS.md operational note in this workspace says it hangs the agent shell); the manifest diff + advisory lookup is the deterministic substitute.
## Cycle-7 Package Manifest Diff
| csproj | Cycle 5 baseline (post-AZ-503) | Cycle 7 change | Net effect on supply chain |
|--------|--------------------------------|----------------|----------------------------|
| `SatelliteProvider.Api/SatelliteProvider.Api.csproj` | references `Microsoft.AspNetCore.OpenApi 10.0.7`, `Microsoft.AspNetCore.Authentication.JwtBearer 10.0.7`, `Newtonsoft.Json 13.0.4`, `Serilog.AspNetCore 8.0.3`, `Serilog.Sinks.File 6.0.0`, `SixLabors.ImageSharp 3.1.11`, `Swashbuckle.AspNetCore 10.1.7` | **+2 PackageReferences**: `FluentValidation 12.0.0` and `FluentValidation.DependencyInjectionExtensions 12.0.0` (both new at AZ-795). | New supply-chain node. Both packages are MIT/Apache-2.0; no transitive Microsoft.* version bumps. |
| `SatelliteProvider.Common/SatelliteProvider.Common.csproj` | unchanged from cycle 5 | **+0 PackageReferences** — the cycle-7 DTO changes (`[JsonRequired]` on `TileCoord.Z/X/Y`) are BCL-only. | None. |
| `SatelliteProvider.DataAccess/SatelliteProvider.DataAccess.csproj` | unchanged from cycle 5 | **+0 PackageReferences**. | None. |
| `SatelliteProvider.Services.TileDownloader/SatelliteProvider.Services.TileDownloader.csproj` | unchanged from cycle 5 | **+0 PackageReferences**. | None. |
| `SatelliteProvider.Services.RegionProcessing/SatelliteProvider.Services.RegionProcessing.csproj` | unchanged from cycle 5 | **+0 PackageReferences**. | None. |
| `SatelliteProvider.Services.RouteManagement/SatelliteProvider.Services.RouteManagement.csproj` | unchanged from cycle 5 | **+0 PackageReferences**. | None. |
| `SatelliteProvider.Tests/SatelliteProvider.Tests.csproj` | unchanged from cycle 5 | **+0 PackageReferences** — `FluentValidation.TestHelper` is the namespace inside the main `FluentValidation` package consumed transitively via `ProjectReference` to `SatelliteProvider.Api`. | None at the manifest level; one new transitive runtime node at test execution (FluentValidation main assembly). |
| `SatelliteProvider.IntegrationTests/SatelliteProvider.IntegrationTests.csproj` | unchanged from cycle 5 | **+0 PackageReferences** — the new `ProblemDetailsAssertions.cs` + `TileInventoryValidationTests.cs` use only BCL + the existing `Xunit` + `Microsoft.AspNetCore` ProjectReference. | None. |
| `SatelliteProvider.TestSupport/SatelliteProvider.TestSupport.csproj` | unchanged from cycle 5 | **+0 PackageReferences**. | None. |
**Net cycle-7 dependency change**: two new `PackageReference` lines (FluentValidation 12.0.0 + FluentValidation.DependencyInjectionExtensions 12.0.0). All other csprojs are byte-identical at the manifest level (verified by `git diff cycle5_tip..HEAD -- '*.csproj'` in the implementation phase).
## Cycle-7 Dependency CVE Lookup
### FluentValidation 12.0.0
| Source | Result |
|--------|--------|
| GitHub Security Advisories (https://github.com/FluentValidation/FluentValidation/security/advisories) | No published advisories. |
| NVD CVE database (search: `FluentValidation`) | No CVEs against this .NET library. (One historical record matched on the substring "FluentForms" — a WordPress plugin unrelated to FluentValidation; explicitly excluded.) |
| ReversingLabs Spectra Assure Community (https://secure.software/nuget/packages/fluentvalidation/12.0.0) | "No known vulnerabilities detected" for the package. One "Hardening" note (`1 outdated toolchain detected`) — not a CVE. |
| Historical Regex DoS (Issue #120 — `EmailAddressValidator`) | Pre-2017, resolved in commit `ebe3720`. v12.0.0 ships with the fixed implementation. Cycle 7 does not use `EmailAddressValidator` (no `Matches`/`EmailAddress` rules — all rules are integer ranges and collection-count predicates). |
| Latest published version | 12.1.1 (5 months ago at time of audit). v12.0.0 → v12.1.1 is a hardening release (no security advisories between the two); the bump is recommended but not security-mandatory. |
### FluentValidation.DependencyInjectionExtensions 12.0.0
| Source | Result |
|--------|--------|
| GitHub Security Advisories | No published advisories. |
| NVD CVE database | No CVEs. |
| ReversingLabs Spectra Assure Community (https://secure.software/nuget/packages/fluentvalidation.dependencyinjectionextensions/vulnerabilities) | "No known vulnerabilities detected". |
| Latest published version | 12.1.1. Same posture as the main package. |
### Cycle-5 carry-overs unchanged
- **D2-cy4** (`Microsoft.NET.Test.Sdk 17.8.0` transitive `NuGet.Frameworks` Medium — test-runtime exposure only) — unchanged. AZ-795 did not bump `Microsoft.NET.Test.Sdk`; it remains the same package at the same version with the same exposure surface. Still owned by a follow-up task at the next Test SDK refresh cycle.
## Cycle-7 New Source Code Runtime Surface
The two new NuGet packages introduce the following runtime surface in the API process:
| Surface | Risk class | Notes |
|---------|------------|-------|
| `IValidator<T>` registration via `AddValidatorsFromAssemblyContaining<Program>()` | Reflection-based DI scan | Bounded to the API assembly only (`SatelliteProvider.Api.dll`). Cannot pick up validators from upstream test assemblies or runtime-loaded DLLs. |
| `ValidatorOptions.Global.PropertyNameResolver` (set by `GlobalValidatorConfig.ApplyOnce`) | Process-wide static state | Idempotent under a `lock` guard. Only affects how error-map keys are rendered. Cannot affect parsing or business logic. |
| `IValidator<T>.ValidateAsync(arg, CancellationToken)` invocation in `ValidationEndpointFilter<T>` | User-controlled DTO entering managed code | DTOs are already deserialized by System.Text.Json (with `UnmappedMemberHandling.Disallow`); the validator receives strongly-typed properties only — no string injection surface. Rules in cycle 7 are integer-only (no regex, no string contains). |
## Cycle-7 Findings
**F-DEPS-AZ795-1 (Low / Hardening)** — `FluentValidation` 12.0.0 → 12.1.1 minor refresh available
- Severity: Low (no CVE; hardening release only)
- Impact: 12.1.1 includes minor lifecycle fixes published in the upstream changelog; none are flagged as security advisories.
- Remediation: Bump `FluentValidation` and `FluentValidation.DependencyInjectionExtensions` to 12.1.1 in a follow-up cycle alongside other minor dependency rolls. Not blocking for cycle-7 release.
No Critical / High / Medium findings.
## Verdict
**PASS** (cycle-7 delta) — zero new CVEs, zero new supply-chain blockers. One Low/hardening recommendation (minor version bump to 12.1.1).
Cumulative verdict (carrying forward earlier cycles): **PASS_WITH_WARNINGS** — D2-cy4 (cycle 4 Medium, test-runtime only) still in effect; cycle 7 adds one Low.
_docs/05_security/infrastructure_review_cycle7.md
+51
View File
@@ -0,0 +1,51 @@
# Infrastructure & Configuration Review (Cycle 7)
**Date**: 2026-05-22
**Mode**: Delta scan
**Scope**: Cycle-7 changes to deployment configs, CI/CD files, and shell scripts only.
## Cycle-7 Infrastructure-Layer Diff
Computed via `git log --since=2026-05-19 -- Dockerfile* docker-compose* .woodpecker.yml .github/** scripts/**` against the cycle-7 commit (`865dfdb`):
| File | Diff | Security relevance |
|------|------|--------------------|
| `docker-compose.yml` | Host port for Postgres moved `5432:5432` → `5433:5432`. Container-internal port unchanged. | Local-dev only; the host port move avoids a sibling-project conflict. Does not affect production (production runs containers on a private docker network without host-port mapping per the existing deployment model). No exposure change. |
| `scripts/probe_inventory_validation.sh` | NEW manual probe script. | Reviewed in `static_analysis_cycle7.md` Test Code Review § `scripts/probe_inventory_validation.sh`. No embedded credentials; fails fast under `set -o errexit -o pipefail -o nounset`. `curl --insecure` used and justified for the dev self-signed cert. ✓ |
No changes to:
- `Dockerfile`, `Dockerfile.tests`, `Dockerfile.api`, or any image-build file.
- `docker-compose.tests.yml`, `docker-compose.prod.yml`, or any orchestration file other than the one host-port edit above.
- `.woodpecker.yml`, `.github/workflows/**`, or any CI/CD pipeline definition.
- `scripts/run-tests.sh`, `scripts/run-performance-tests.sh`, or any other harness shell script.
## Container & Image Security — Carried Forward Unchanged
| Check | Status (carried from cycle 5/6) | Cycle-7 impact |
|-------|---------------------------------|----------------|
| Non-root container user (Dockerfile `USER` directive) | Already in effect | None |
| Minimal base image (alpine/distroless/etc.) | The API image uses the .NET 10 SDK base — same as cycle 5; image hardening is owned by a separate, still-unscheduled follow-up task. | None |
| No secrets in build args | Verified cycle 5; no `Dockerfile` change in cycle 7 | None |
| Health checks | Compose `healthcheck` block on Postgres unchanged | None |
## CI/CD Security — Carried Forward Unchanged
| Check | Status | Cycle-7 impact |
|-------|--------|----------------|
| Secrets management (env vars / vault, not pipeline literals) | Existing pattern preserved | None |
| No credentials in pipeline definitions | `.woodpecker.yml` untouched in cycle 7 | None |
| Artifact signing | Existing posture (none — owned by a separate operational improvement track) | None |
| Dependency-audit step in pipeline | Existing posture (manual audit per `dependency_scan_cycle*.md`; no automated `dotnet list package --vulnerable` in CI due to the build-hang issue noted in `AGENTS.md`) | None |
## Environment & Secrets
- `.env.example` — not modified in cycle 7. The cycle-7 code reads no new env vars (FluentValidation has no config knobs; `GlobalValidatorConfig` is pure code).
- `appsettings.Development.json` — minor edit during cycle 7 (the connection-string port change, mirroring the compose-file edit). No new secret material.
- `appsettings.json` — production template; unchanged in cycle 7.
## Verdict (Phase 4)
**PASS** — zero new infrastructure-layer findings.
The single docker-compose host-port edit is a local-developer-convenience change with no exposure implication. The new probe shell script is dev/test only, env-driven, and contains no embedded secrets.
_docs/05_security/owasp_review_cycle7.md
+93
View File
@@ -0,0 +1,93 @@
# OWASP Top 10 Review (Cycle 7)
**Date**: 2026-05-22
**Mode**: Delta scan against OWASP Top 10:2021 (current at time of audit per https://owasp.org/www-project-top-ten/)
**Scope**: Cycle-7 delta only — AZ-794 wire-format rename, AZ-795 strict-validation infrastructure, AZ-796 inventory-endpoint validator. Earlier cycles' OWASP reviews remain authoritative for their respective surfaces; this file does NOT re-walk the full cycle-5 surface.
## A01 — Broken Access Control
**Status**: PASS
- `.RequireAuthorization()` is preserved on every existing endpoint and is chained on the cycle-7 inventory endpoint at `Program.cs:217` ahead of `.WithValidation<TileInventoryRequest>()` on line 218.
- Endpoint-filter execution order is governed by ASP.NET Core's middleware → routing → endpoint-filter pipeline. `UseAuthorization()` (line 201) reads the endpoint metadata produced by `.RequireAuthorization()` and short-circuits anonymous callers with 401 BEFORE the endpoint dispatch reaches any endpoint filter. Cycle-7 verification: `TileInventoryValidationTests` does not include a "no token → 400" case because the framework prevents that path; the suite's `TileInventoryTests.UnauthenticatedRequestReturns401_AC6` already covers it.
- No new CORS policy in cycle 7. `TilesCors` (cycle-6 baseline) is unchanged.
- No new IDOR paths — the inventory endpoint operates on caller-supplied identifiers but does not couple them to any tenant or owner field; tiles are globally-scoped in the post-AZ-484 model.
## A02 — Cryptographic Failures
**Status**: N/A (cycle 7)
- Cycle 7 has no cryptographic operations. JWT validation is unchanged from cycle 4 (HS256 with ≥ 32-byte secret, `ValidateLifetime + ValidateIssuer + ValidateAudience = true`, ClockSkew = 30s).
- The cycle-5 UUIDv5 SHA-1 surface is unaffected.
- TLS posture (Kestrel `Http1AndHttp2` with self-signed dev cert / ingress termination in prod) — unchanged from cycle 6.
## A03 — Injection
**Status**: PASS
- No SQL / Dapper / Npgsql usage in any cycle-7 new file.
- No `Process.Start` / shell-out / `eval` in any cycle-7 new file.
- All inputs reaching the validator are strongly typed (`int`, `Guid`, `IReadOnlyList<TileCoord>`) — System.Text.Json has already parsed and rejected anything malformed before the validator runs.
- The cycle-7 deserializer hardening (`UnmappedMemberHandling.Disallow`) raises the bar for the entire HTTP JSON surface by rejecting mass-assignment / property-injection attempts at parse time.
## A04 — Insecure Design
**Status**: PASS (improvement)
- AZ-795 / AZ-796 are themselves a *design fix* for ad-hoc validation. Pre-cycle-7, endpoints used inline `try/catch` blocks and per-handler defensive logic — easy to miss a path, easy to drift the shape of 4xx bodies. Cycle 7 centralises validation behind one `ValidationEndpointFilter<T>` + one `GlobalExceptionHandler`, both honouring a single contract (`error-shape.md` v1.0.0).
- The architecture doc (`_docs/02_document/architecture.md` § 9) now carries a coverage table that names every public endpoint and its validation status — making future drift visible.
## A05 — Security Misconfiguration
**Status**: PASS
- `UnmappedMemberHandling.Disallow` is a defense-in-depth hardening (mass-assignment prevention).
- `Swagger` exposure is still gated by `app.Environment.IsDevelopment()` (unchanged).
- `appsettings.Development.json` clearly tags DEV-ONLY JWT iss/aud values; `appsettings.json` ships empty so production fail-fast triggers if env vars are missing (unchanged from cycle 4).
- The new `AddProblemDetails()` registration is benign — it only standardises ProblemDetails generation for endpoints that explicitly return them.
- Note: `AddValidatorsFromAssemblyContaining<Program>()` is scoped to `SatelliteProvider.Api.dll` only — it cannot pick up `IValidator<T>` definitions from any other assembly (deliberate; the validators MUST live in the API project where the endpoint contract lives).
## A06 — Vulnerable & Outdated Components
**Status**: PASS_WITH_WARNINGS (Low)
- See `dependency_scan_cycle7.md` for the full table. Summary:
- FluentValidation 12.0.0 — no known CVEs; latest is 12.1.1 (hardening). Low/Hardening recommendation only.
- FluentValidation.DependencyInjectionExtensions 12.0.0 — same.
- All other packages unchanged from cycle 5.
## A07 — Identification and Authentication Failures
**Status**: PASS
- JWT validation parameters unchanged from cycle 4 (`AddSatelliteJwt`).
- No new auth-bypass paths introduced by cycle 7. The new endpoint filter cannot run for anonymous callers (see A01).
- The integration test `TileInventoryValidationTests` mints a valid token via the shared `JwtTokenFactory` — proves the happy path is properly auth-gated and not relying on any test-only bypass.
## A08 — Software and Data Integrity Failures
**Status**: N/A (cycle 7)
- No CI/CD changes, no artifact-signing changes, no auto-update paths touched in cycle 7.
## A09 — Security Logging and Monitoring Failures
**Status**: PASS_WITH_WARNINGS
- `GlobalExceptionHandler` 5xx branch logs `Method`, `Path`, `correlationId`, and the exception object (via Serilog default). This is the appropriate level — enough to debug, with correlationId for cross-referencing.
- The 4xx branch (cycle-7 new logic) does NOT log the exception. This is intentional and correct: malformed request bodies would otherwise create a noisy log signal and could push PII / token content into the log file if attached unwisely. The cost of "no log of the 400" is acceptable because the response itself carries the field path and a deterministic error message, so the client can self-debug.
- The Low information-disclosure findings (F-AZ795-1, F-AZ795-2) from `static_analysis_cycle7.md` belong here as well, but the impact is limited to a Low because the leaked content is type-name metadata, not credentials or PII.
## A10 — Server-Side Request Forgery (SSRF)
**Status**: N/A (cycle 7)
- No URL-input fields, no outbound HTTP calls triggered by the cycle-7 surface. (Pre-existing: `GoogleMapsDownloaderV2` makes outbound calls to Google Maps; not modified by cycle 7.)
## Cross-Reference with `security_approach.md`
The repo does not contain `_docs/00_problem/security_approach.md` (the pre-existing security audit cycles never produced one). The OWASP review proceeds against the cycle-5 + cycle-6 architectural decisions documented in `_docs/02_document/architecture.md` § 7 (Security Architecture) — which cycle-7 input-validation work cleanly extends rather than contradicts.
## Verdict (Phase 3)
**PASS_WITH_WARNINGS** — 1 dependency-hardening Low (D-AZ795-1: 12.0.0 → 12.1.1) + 2 information-disclosure Lows (F-AZ795-1, F-AZ795-2). Zero Critical / High / Medium findings.
_docs/05_security/security_report_cycle7.md
+106
View File
@@ -0,0 +1,106 @@
# Security Audit Report (Cycle 7)
**Date**: 2026-05-22
**Scope**: Cycle-7 delta over the cycle-5 audit (`_docs/05_security/security_report_cycle5.md`); cycle 6 produced no security report, so cycle 5 is the last full baseline. Cycle-7 surface = AZ-794 (`tileZoom/tileX/tileY` → `z/x/y` rename) + AZ-795 (strict-validation epic: FluentValidation, `UnmappedMemberHandling.Disallow`, GlobalExceptionHandler, error-shape contract) + AZ-796 (inventory-endpoint 9-rule validator).
**Trigger**: `/autodev` Step 14 (Security Audit) — feature cycle 7, post-implementation, post-test-spec-sync, post-docs-update.
**Verdict (cycle-7 delta)**: **PASS_WITH_WARNINGS** (3 Low findings; no Critical/High/Medium).
**Verdict (cumulative)**: **PASS_WITH_WARNINGS** (carries forward 1 cycle-4 Medium dep finding via D2-cy4 + 2 cycle-5 Low informational notes + cycle-7's 3 Lows).
## Summary
| Severity | Cycle 5 delta | Cycle 7 delta | Cumulative |
|----------|---------------|---------------|------------|
| Critical | 0 | 0 | 0 |
| High | 0 | 0 | 0 |
| Medium | 0 | 0 | 1 (D2-cy4 carry — `Microsoft.NET.Test.Sdk 17.8.0` transitive `NuGet.Frameworks`; test-runtime exposure only) |
| Low | 2 informational notes | **3 NEW** (F-AZ795-1, F-AZ795-2, D-AZ795-1) | 5+ |
## OWASP Top 10:2021 Assessment
| Category | Status (cycle-7 delta) | Findings |
|----------|------------------------|----------|
| A01 — Broken Access Control | PASS | — |
| A02 — Cryptographic Failures | N/A | No crypto in cycle 7 |
| A03 — Injection | PASS | — |
| A04 — Insecure Design | PASS (improvement) | AZ-795 / AZ-796 centralise validation behind one filter + one error handler — direct improvement |
| A05 — Security Misconfiguration | PASS | `UnmappedMemberHandling.Disallow` is defense-in-depth (mass-assignment prevention) |
| A06 — Vulnerable Components | PASS_WITH_WARNINGS | D-AZ795-1 (Low; bump 12.0.0 → 12.1.1 hardening release) |
| A07 — Auth Failures | PASS | JWT validation unchanged; new endpoint filter cannot run for anonymous callers |
| A08 — Data Integrity Failures | N/A | No CI/CD or artifact-signing surface in cycle 7 |
| A09 — Logging Failures | PASS_WITH_WARNINGS | F-AZ795-1 + F-AZ795-2 (Lows; `JsonException.Message` / `BadHttpRequestException.Message` echoed to client) |
| A10 — SSRF | N/A | No URL-input fields in cycle 7 |
## Findings
| # | Severity | Category | Location | Title |
|---|----------|----------|----------|-------|
| F-AZ795-1 | Low | Information Disclosure (A09) | `SatelliteProvider.Api/GlobalExceptionHandler.cs:108–117` | `JsonException.Message` propagated to client in 400 response (type-name + parse-position leak) |
| F-AZ795-2 | Low | Information Disclosure (A09) | `SatelliteProvider.Api/GlobalExceptionHandler.cs:88–93` | Generic `BadHttpRequestException.Message` propagated as `Detail` for non-JSON 400 paths |
| D-AZ795-1 | Low | Vulnerable & Outdated Components (A06) | NuGet | `FluentValidation` + `FluentValidation.DependencyInjectionExtensions` 12.0.0 → 12.1.1 (hardening release; no published CVE) |
### Finding Details
**F-AZ795-1: `JsonException.Message` propagated to client in 400 response** (Low / A09 — Information Disclosure)
- Location: `SatelliteProvider.Api/GlobalExceptionHandler.cs:108–117` (`TryExtractDeserializationErrors`)
- Description: `System.Text.Json.JsonException.Message` is echoed in the 400 `ValidationProblemDetails.errors[fieldPath]` array. The default message includes the offending .NET type (`System.Int32`, `System.Guid`, …), the JSON path (already separately captured as the key), and the byte position / line number in the payload — e.g. *"The JSON value could not be converted to System.Int32. Path: $.tiles[0].z | LineNumber: 0 | BytePositionInLine: 27."*.
- Impact: Low. The `UseAuthentication` + `UseAuthorization` middleware short-circuits anonymous callers with 401 before any endpoint filter runs, so the leak is only reachable by authenticated callers. The leaked content (type names, parse positions, `System.Text.Json` fingerprint) is already inferable from the OpenAPI spec at `/swagger/v1/swagger.json`; this finding narrows the attack surface for an authenticated tenant operator but does not expose secrets, PII, or pivot vectors.
- Remediation: Sanitise the response message to a generic string (e.g. `"Could not deserialize value at this field path."`) while continuing to log the raw `jsonEx.Message` server-side under the request's `correlationId`. Update `error-shape.md` test case `validation-type-mismatch` and the integration tests to assert no `System.*` substring appears in any `errors[]` value.
- Status: filed for next cycle.
**F-AZ795-2: Generic `BadHttpRequestException.Message` propagated as `Detail`** (Low / A09 — Information Disclosure)
- Location: `SatelliteProvider.Api/GlobalExceptionHandler.cs:88–93` (fallback 400 path when there is no `JsonException` inner exception)
- Description: When `BadHttpRequestException` has no `JsonException` inner exception (e.g. framework model-binding failures, unsupported `Content-Type`, oversized request bodies), the framework-provided `Message` is echoed back as `ProblemDetails.Detail`. ASP.NET Core message strings for these paths can include parameter names and (rarely) framework version hints.
- Impact: Same severity as F-AZ795-1. Pre-existing-class issue (model-binding messages were always shaped this way under ASP.NET Core); cycle 7 didn't introduce or worsen it.
- Remediation: Same as F-AZ795-1 — sanitise the `Detail` to a generic string and log the raw `Message` server-side. Best done in tandem with F-AZ795-1.
- Status: filed for next cycle.
**D-AZ795-1: FluentValidation 12.0.0 → 12.1.1 hardening refresh** (Low / A06 — Vulnerable & Outdated Components)
- Location: `SatelliteProvider.Api/SatelliteProvider.Api.csproj` (`FluentValidation` + `FluentValidation.DependencyInjectionExtensions`)
- Description: 12.0.0 has no known CVEs (verified against GitHub Security Advisories, NVD, ReversingLabs Spectra Assure). 12.1.1 is the latest version (~5 months newer at audit time) and is a hardening release — minor upstream fixes, no security advisories.
- Impact: Low. Pure forward-compatibility hardening.
- Remediation: Bump both packages to 12.1.1 in a future minor-dependency-roll cycle.
- Status: filed for next cycle. Not release-blocking.
## Dependency Vulnerabilities
| Package | CVE | Severity | Fix Version | Status |
|---------|-----|----------|-------------|--------|
| FluentValidation 12.0.0 | — (hardening only) | Low | 12.1.1 | D-AZ795-1 — filed |
| FluentValidation.DependencyInjectionExtensions 12.0.0 | — (hardening only) | Low | 12.1.1 | D-AZ795-1 — filed (same item) |
| Microsoft.NET.Test.Sdk 17.8.0 (transitive `NuGet.Frameworks`) | — (cycle-4 carry-over D2-cy4) | Medium | TBD (next Test SDK refresh cycle) | carry-over from cycle 4 — owned by a separate unscheduled task |
## Recommendations
### Immediate (Critical/High)
None.
### Short-term (Medium)
None new in cycle 7. Cycle-4 carry-over D2-cy4 (`Microsoft.NET.Test.Sdk` Medium) remains in the backlog.
### Long-term (Low / Hardening)
1. **Sanitise client-visible 400 messages** (F-AZ795-1 + F-AZ795-2). Single change in `GlobalExceptionHandler.WriteClientErrorAsync` + matching test assertion. Estimated 1 hour of effort. Should be filed as a small follow-up child of AZ-795 (or as a standalone task under the same epic).
2. **Bump FluentValidation 12.0.0 → 12.1.1** (D-AZ795-1). Single `.csproj` edit + a regression test pass; no API surface change in 12.0.0 → 12.1.1 per the upstream changelog.
### Cumulative reminders (carry-overs)
- Cycle-4 D2-cy4 — `Microsoft.NET.Test.Sdk 17.8.0` transitive `NuGet.Frameworks` Medium-severity finding, test-runtime exposure only. Owned by the next Test SDK refresh.
## Cycle-7 Architectural Wins
The audit specifically wants to record three improvements introduced this cycle:
1. **Mass-assignment prevention by default** — `UnmappedMemberHandling.Disallow` on the global JSON pipeline rejects any unknown root or nested field across every public endpoint. The cycle-7 acceptance criteria explicitly enumerate this for the inventory endpoint; the protection is in force for every other endpoint that consumes a JSON body too.
2. **Uniform 4xx contract** — `error-shape.md` v1.0.0 unifies the wire shape across two failure layers (deserializer + FluentValidation). Future child tickets reuse `ValidationEndpointFilter<T>`, `ProblemDetailsAssertions`, and the contract without adding new infrastructure. This dramatically reduces the chance of future endpoints drifting into their own bespoke error shapes.
3. **Auth-before-validation invariant verified** — endpoint filters added via `WithValidation<T>()` cannot run for unauthenticated callers (the routing pipeline runs `UseAuthorization` BEFORE the endpoint filter chain). The audit explicitly verified the cycle-7 inventory endpoint and re-asserted the invariant in this report.
## Verdict
**PASS_WITH_WARNINGS** — 3 Lows, 0 Mediums (cycle-7 delta), 0 Highs, 0 Criticals. Cycle 7 is **safe to release**. The 3 Lows are filed for follow-up cycles and do not block release.
Cumulative posture: PASS_WITH_WARNINGS (1 cycle-4 Medium carry-over via D2-cy4 + Lows above). No regression of the cycle-5 PASS posture.
_docs/05_security/static_analysis_cycle7.md
+160
View File
@@ -0,0 +1,160 @@
# Static Analysis (Cycle 7)
**Date**: 2026-05-22
**Mode**: Delta scan
**Scope**: Source code introduced or changed by AZ-794 + AZ-795 + AZ-796:
- `SatelliteProvider.Api/Program.cs` (DI registration + middleware + endpoint wiring deltas)
- `SatelliteProvider.Api/Validators/{InventoryRequestValidator,ValidationEndpointFilter,ValidationEndpointFilterExtensions,GlobalValidatorConfig}.cs` (new)
- `SatelliteProvider.Api/GlobalExceptionHandler.cs` (new)
- `SatelliteProvider.Common/DTO/TileInventory.cs` (renamed properties + `[JsonRequired]` markers)
- `SatelliteProvider.IntegrationTests/{ProblemDetailsAssertions,TileInventoryValidationTests}.cs` (new — test code; reviewed for fixture-only secrets and auth bypass patterns)
- `SatelliteProvider.Tests/{TestSupport/ValidatorTestModuleInitializer,Validators/InventoryRequestValidatorTests}.cs` (new — test code)
- `scripts/probe_inventory_validation.sh` (new probe shell script — reviewed for embedded secrets and unsafe sequences)
**Method**: Read each new file end-to-end + targeted `Grep` for injection / hardcoded-credential / unsafe-API patterns. Cycle 5 + cycle 4 baselines for the pre-existing surface remain authoritative; this scan only audits the delta.
## Findings
### F-AZ795-1 — `JsonException.Message` propagated to client in 400 response (Low / Information Disclosure)
- **Location**: `SatelliteProvider.Api/GlobalExceptionHandler.cs:108–117` (`TryExtractDeserializationErrors`)
- **Code**:
```csharp
var message = string.IsNullOrEmpty(jsonEx.Message)
? "Invalid JSON."
: jsonEx.Message;
return new Dictionary<string, string[]> { [path] = new[] { message } };
```
- **Description**: `System.Text.Json.JsonException.Message` is forwarded to the client as the value in the `errors[path]` array of a 400 `ValidationProblemDetails`. The default `JsonException.Message` typically includes the offending .NET type (`System.Int32`, `System.Guid`, …), the JSON path (already separately surfaced as the key), and the byte position / line number in the payload — for example:
> "The JSON value could not be converted to System.Int32. Path: $.tiles[0].z | LineNumber: 0 | BytePositionInLine: 27."
- **Impact**: Low. The auth gate (`UseAuthentication` + `UseAuthorization` middleware) runs BEFORE the endpoint filter chain, so anonymous callers cannot reach the validator or the deserializer — they get 401 first. For an authenticated caller the type-name leak only reveals what the OpenAPI spec at `/swagger/v1/swagger.json` already advertises (the DTO names and shape). Parse positions and `System.Text.Json` fingerprinting are mild — not a credential leak, not an SSRF / IDOR pivot — but they do narrow the attack surface for an attacker who has already obtained a valid token (e.g. a curious tenant operator).
- **OWASP Mapping**: A09 (Security Logging and Monitoring Failures — adjacent) / A05 (Security Misconfiguration — adjacent).
- **Remediation**: Replace the raw `jsonEx.Message` with a generalised message such as `"Could not deserialize value at this field path."` (still keyed by the field path, so callers retain enough information to fix their request). The exact `jsonEx.Message` should be logged on the server side for support, indexed by `correlationId`, but not echoed in the response.
- **Test coverage gap**: AZ-795 acceptance criteria did not assert anything about the response message string content beyond presence/non-emptiness. A future child task should add an assertion that no `System.*` type name appears in any `errors[]` value.
- **Status**: open (filed for next cycle).
### F-AZ795-2 — Generic `BadHttpRequestException.Message` propagated in non-JSON 400 path (Low / Information Disclosure)
- **Location**: `SatelliteProvider.Api/GlobalExceptionHandler.cs:88–93` (the fallback non-`ValidationProblemDetails` path)
- **Code**:
```csharp
var problem = new ProblemDetails
{
Status = badRequest.StatusCode,
Title = "Bad Request",
Detail = badRequest.Message,
};
```
- **Description**: When `BadHttpRequestException` has no `JsonException` inner exception (e.g. framework model-binding failures, unsupported `Content-Type`, oversized request bodies), the framework-provided `Message` is echoed back as `Detail`. ASP.NET Core message strings for these paths include hints like "Failed to read parameter '...' from query string." which can include the actual parameter name and (rarely) framework version hints.
- **Impact**: Same severity as F-AZ795-1. Pre-existing-class issue (model-binding messages were always shaped this way under ASP.NET Core); cycle 7 didn't introduce it but didn't change it either.
- **Remediation**: Treat the same as F-AZ795-1 — sanitise to a generic string + log the original `Message` with `correlationId`. Done in tandem.
- **Status**: open (filed for next cycle).
### F-AZ795-3 — `correlationId` for 5xx (Informational — no action required)
- **Location**: `SatelliteProvider.Api/GlobalExceptionHandler.cs:38–53` (5xx branch)
- **Description**: The 5xx branch sets `Detail = "An unexpected error occurred. Use the correlationId to look up the server log entry."` and adds `correlationId = httpContext.TraceIdentifier` to the extensions map. Original exception message NEVER goes into the body. Inv-5 of `error-shape.md` is honoured.
- **Status**: informational only — no remediation needed. The implementation preserves AZ-353 sanitisation and adds the `correlationId` extension as the only non-secret identifier.
## Pattern Sweep — Cycle-7 Delta
### Injection (SQL / Command / XSS / Template)
| Pattern | Result |
|---------|--------|
| `string.Format`, interpolation `$"..."`, or concatenation feeding into a Dapper / Npgsql command in the new files | None. The new files do not touch the data layer. |
| `Process.Start`, `subprocess`, `eval`, `Invoke-Expression`, raw `system()` | None. |
| User-input echoed into HTML (XSS) | None. The API returns JSON only. |
| Template injection (Razor / Liquid / etc.) | None. No templating in the new files. |
### Authentication & Authorization
| Pattern | Result |
|---------|--------|
| Hardcoded credentials, secrets, API keys | `Grep` for `password|secret|api.?key|bearer|token` in the new files returns matches only inside `*Tests.cs` files where they reference test-only env-var-driven `JWT_SECRET`. No hardcoded secret material. |
| Missing `.RequireAuthorization()` on a public endpoint | `POST /api/satellite/tiles/inventory` has `.RequireAuthorization()` chained at `Program.cs:217`; `WithValidation<TileInventoryRequest>()` is chained at line 218 (the chaining order on a single `RouteHandlerBuilder` does not affect runtime ordering — auth middleware runs at the routing layer BEFORE any endpoint filter executes). All other endpoints unchanged from prior cycles. |
| Validator running before auth check | No. Endpoint filters run after the authorization middleware short-circuits. Anonymous callers cannot probe the schema or trigger the validator. |
| Permission/policy regression | `RequiresGpsPermission` on `/api/satellite/upload` unchanged. No new policy added or removed in cycle 7. |
### Cryptographic Failures
| Pattern | Result |
|---------|--------|
| Weak hash (MD5 / SHA1) used for passwords or signatures | None in cycle 7. (Pre-existing: `Uuidv5.Create` uses SHA-1 internally per RFC 9562 §5.5 for the UUIDv5 hash — same as cycle 5; covered there, not a finding.) |
| New crypto material introduced | None. Cycle 7 has no cryptography. |
| Plaintext transmission | API listens on `https://+:8080` with ALPN (cycle-6 baseline, unchanged). |
### Data Exposure
| Pattern | Result |
|---------|--------|
| Sensitive data in logs | `GlobalExceptionHandler` logs `Method`, `Path`, `correlationId`, and the exception object via Serilog. The exception object MAY contain DB query parameters or DTO field values; this is the same pre-cycle-7 risk surface (Serilog default), and cycle 7 doesn't widen it. The 4xx branch (which handles malformed payloads) does NOT log the exception at all — only the 5xx branch logs. So a malformed request body is not written to logs. ✓ |
| Sensitive fields in API responses | F-AZ795-1 / F-AZ795-2 above are the only echo-back paths. No password hashes, no PII (the inventory endpoint is metadata-only). |
| Debug endpoints in production | Swagger is gated by `app.Environment.IsDevelopment()` (unchanged). |
| Secrets in version control | `.env*` files are gitignored. The new shell probe `scripts/probe_inventory_validation.sh` reads `$API_BASE`/`$JWT` from the environment; no embedded secrets. |
### Insecure Deserialization
| Pattern | Result |
|---------|--------|
| `Pickle` / `BinaryFormatter` / unsafe XML / `JsonConvert.DeserializeObject<T>` with `TypeNameHandling.All` | None in cycle 7. The deserializer is `System.Text.Json` with `UnmappedMemberHandling.Disallow` — a strict-mode deserializer that does NOT support polymorphic type names. Cycle 7 _strengthens_ this surface (mass-assignment prevention) rather than weakening it. |
| Unbounded collection sizes | `TileInventoryRequest.Tiles` / `LocationHashes` capped at `TileInventoryLimits.MaxEntriesPerRequest = 5000` enforced by `InventoryRequestValidator` Rule 6/7. Pre-deserialization upper bound is governed by `KestrelServerOptions.Limits.MaxRequestBodySize` (set for the UAV upload to 500 MiB; default 30 MB for other endpoints — sufficient for a 5000-entry inventory body). |
### Integer Overflow / Bounded Math
The validator does a left-shift to compute `2^z` for the X/Y range check:
```csharp
.Must((coord, x) => coord.Z >= 0 && coord.Z <= MaxZoom && x < (1L << coord.Z))
```
- `(1L << coord.Z)` uses a `long` literal, so the shift target is 64-bit.
- `coord.Z` is guarded by `>= 0 && <= MaxZoom` (= 22). Maximum shift is `1L << 22 = 4_194_304`. No overflow possible.
- The guard is INSIDE the `.Must` lambda (not in a separate `When`); FluentValidation evaluates ALL rules unless explicitly chained with `When` / `Cascade`. The lambda returns `false` if Z is out-of-range, surfacing the X/Y rule failure alongside the Z rule failure rather than crashing. ✓
### ReDoS / Algorithmic Complexity
Cycle 7 validation rules are all O(1) per entry × N entries:
| Rule | Per-entry cost | Total cost (worst case N = 5000) |
|------|----------------|----------------------------------|
| XOR (`Custom` rule on `req`) | O(1) | O(1) |
| `.Tiles.Count <= 5000` | O(1) | O(1) |
| `.LocationHashes.Count <= 5000` | O(1) | O(1) |
| `RuleForEach(Tiles).SetValidator(TileCoordValidator)` | O(1) per entry | O(N) — bounded by Rule 6 (`Tiles.Count <= 5000`) |
| `Z`, `X`, `Y` range checks per `TileCoord` | O(1) per entry | O(N) — bounded by Rule 6 |
No regex, no recursion, no nested loops. Maximum total work is ~25 000 operations at the validator level for a max-size payload. Cycle-6 perf test (`PT-09`) measured the entire endpoint at p95 = 66 ms for 2500-coord batches; adding the validator cost is negligible relative to the DB lookup.
## Test Code Review
### `SatelliteProvider.Tests/Validators/InventoryRequestValidatorTests.cs`
- Pure CPU; no I/O, no network, no file system, no DB.
- All inputs constructed inline. No fixture file reads.
- No hardcoded JWT or test bearer token (the validator runs in isolation).
- Calls `GlobalValidatorConfig.ApplyOnce()` via `ValidatorTestModuleInitializer.cs` (`[ModuleInitializer]`). This runs at test-assembly load — single source of truth for the camelCase property resolver; matches the runtime behaviour, no test drift risk.
- ✓ No findings.
### `SatelliteProvider.IntegrationTests/TileInventoryValidationTests.cs` + `ProblemDetailsAssertions.cs`
- Uses the runner-side `JwtTestHelpers.MintAuthenticated(...)` to attach a Bearer token. No hardcoded secret material. The token's signing secret comes from the `JWT_SECRET` env var (32+ bytes, dev-only in `docker-compose.tests.yml`).
- Test inputs use raw `HttpRequestMessage` with hand-built JSON strings — exercises the exact wire shape the validator and the deserializer see in production. The hand-built strings include all the cycle-7 negative cases (legacy `tileZoom/tileX/tileY`, unknown root field, type mismatch, etc.).
- `ProblemDetailsAssertions.AssertValidationProblem(...)` asserts the shape of `errors[]` per `error-shape.md` Inv-2 / Inv-4. No assertion was added against message content — see F-AZ795-1 remediation: when the message is sanitised, add a "no `System.*` type name" assertion here.
- ✓ No findings beyond the gap noted in F-AZ795-1.
### `scripts/probe_inventory_validation.sh`
- Reads `${API_BASE:-https://localhost:8080}` and `${JWT:?…}` from the environment.
- `set -o errexit -o pipefail -o nounset` at the top of the script — fail-fast on undefined vars or broken pipes.
- `curl --insecure` is used (justified — the dev cert is self-signed; the script targets localhost in dev/test only). Documented in the script header.
- No embedded credentials.
- ✓ No findings.
## Cycle-7 Pre-existing-Surface Drift Check
Cycle 7 did not modify the data-access layer, file system layout, route processing, region processing, JWT auth setup, or the UAV upload pipeline. Cycle-5 + cycle-4 baseline findings (e.g., D2-cy4 `Microsoft.NET.Test.Sdk` carry-over) are unchanged. The cycle-6 dependency-scan-skip is the only audit-process gap; cycle 7 picks up the missing supply-chain delta inline (covered in `dependency_scan_cycle7.md`).
## Verdict (Phase 2)
**PASS_WITH_WARNINGS** — 2 Low (F-AZ795-1, F-AZ795-2) information-disclosure findings on the new error-shaping path; both are auth-gated and reveal only type-name + parse-position metadata. No Critical / High / Medium findings. The Low findings are filed for the next cycle and are not release-blockers.
_docs/06_metrics/perf_2026-05-22_cycle7.md
+73
View File
@@ -0,0 +1,73 @@
# Perf Run — Cycle 7 (AZ-794 + AZ-795 + AZ-796)
**Date**: 2026-05-22T07:59Z
**Run label**: cycle7 — full default-parameter run + PT-09 v2-schema smoke (Cycle 7 NFR sanity check after `tileZoom/tileX/tileY → z/x/y` rename and strict-input-validation rollout).
**Trigger**: autodev existing-code Step 15 (Performance Test gate). Cycle 7 goal: confirm the inventory contract rename (AZ-794) and FluentValidation + `JsonUnmappedMemberHandling.Disallow` (AZ-795 / AZ-796) introduced no regression on existing scenarios and no measurable cost on the inventory hot path.
**Runner**: `scripts/run-performance-tests.sh` (default params: `PERF_REPEAT_COUNT=20`, `PERF_UAV_BATCH_SIZE=10`) plus a separate v2-schema PT-09 smoke probe (`/tmp/pt09_smoke.sh`, 20 sequential calls × 2500-tile batch using the new `z/x/y` field names).
**System under test**: `docker-compose up -d --build` against `mcr.microsoft.com/dotnet/aspnet:10.0`; api healthy on `https://localhost:18980` (TLS+ALPN, dev cert `./certs/api.crt` trusted via `--cacert`). Postgres on `localhost:5433` (cycle 7 docker-compose port move to avoid sibling-project conflict — application semantics unchanged).
**Build**: `SatelliteProvider.IntegrationTests` Release built inside `mcr.microsoft.com/dotnet/sdk:10.0` SDK container (host `dotnet build` is blocked by AGENTS.md hang note); 0 errors / 15 warnings (carried-over NU1902 IdentityModel + CA2227 — both unrelated to cycle 7).
**JWT**: minted by `SatelliteProvider.IntegrationTests --mint-only` (canonical `JwtTokenFactory` surface per AZ-491); exported as `PERF_JWT_TOKEN` so the script skipped its own build/mint block.
## Results
| # | Scenario | Verdict | Observed | Threshold | Source of threshold |
|---|----------|---------|----------|-----------|---------------------|
| PT-01 | Tile download (cold) | **PASS** | 998ms | ≤ 30000ms | `_docs/02_document/tests/performance-tests.md` |
| PT-02 | Cached tile retrieval | **PASS** | 269ms | ≤ 500ms | `_docs/02_document/tests/performance-tests.md` |
| PT-03 | Region 200m / z18 | **PASS** | 139ms | ≤ 60000ms | `_docs/02_document/tests/performance-tests.md` |
| PT-04 | Region 500m / z18 + stitch | **PASS** | 2110ms | ≤ 120000ms | `_docs/02_document/tests/performance-tests.md` |
| PT-05 | 5 concurrent regions | **PASS** | 3145ms | ≤ 300000ms | `_docs/02_document/tests/performance-tests.md` |
| PT-06 | Route creation (2 points) | **PASS** | 161ms | ≤ 5000ms | `_docs/02_document/tests/performance-tests.md` |
| PT-07 | Region request distribution (N=20, cold + warm) | **PASS** | cold p50=2111ms, p95=2608ms (N=20) · warm p50=62ms, p95=76ms (N=20) | warm p95 < cold p95 | AZ-484 / AZ-492 |
| PT-08 | UAV batch upload (batch=10, N=20) | **PASS** | batch p50=108ms, p95=284ms; per-item proxy p95=28ms; accepted=200, rejected=0, failed=0 | batch p95 ≤ 2000ms (AZ-488) | `_docs/02_document/tests/performance-tests.md` |
| PT-09 (cycle-7 smoke) | Inventory v2 schema (2500-tile batch, all-miss path) | **PASS** | min=27ms, median=44ms, p95=73ms, max=86ms (N=20) | p95 ≤ 1000ms (AZ-505 AC-4) | `_docs/02_document/tests/performance-tests.md` |
**Raw verdict: 9 Pass · 0 Warn · 0 Fail · 0 Unverified** (script exit 0; smoke probe exit 0).
## AZ-794 / AZ-795 / AZ-796 NFR verification
Cycle 7 touched **only** the inventory endpoint (`POST /api/satellite/tiles/inventory`) — the contract rename and the new validation pipeline. PT-09 is the directly relevant scenario; PT-01..PT-08 act as a regression baseline for everything else.
**PT-09 cycle-7 smoke probe** is a *companion* to the canonical PT-09 (`TileInventoryTests.PerformanceBudget_AC4`, full-suite only, seeds 2500 rows and exercises the "found" branch). The smoke probe deliberately tests the **all-miss** path — 2500 fresh `(z, x, y)` tuples that do not exist in the DB — to surface validator + deserializer + planner cost in isolation from the row-hash-lookup cost. p95 = 73ms is **13.7× under** the 1000 ms budget; the gap to the canonical PT-09 cycle 6 number (p95=66ms, all-hit path) is ~10% and fully explained by the cycle 7 validator pass (O(N=2500) bounds checks) before the SQL runs.
**Contract rename (AZ-794)**: the smoke probe uses the new `{"tiles":[{"z":18,"x":...,"y":...}]}` body. HTTP 200 on every call confirms the wire format is accepted; the legacy `tileZoom/tileX/tileY` field names would be rejected by `JsonUnmappedMemberHandling.Disallow` and trigger a 400 (covered separately by the cycle 7 `TileInventoryValidationTests` integration suite — no perf regression because the validator never runs on a rejected deserialization).
**Strict validation (AZ-795 + AZ-796)**: 9 validation rules now run on every successful inventory request. The validator iterates the `tiles` list once (O(N)) and performs constant-time bounds checks per item. For N=2500 the measured cost is ≈ 5–10ms (median 44ms vs cycle 6 median 19ms — the gap straddles the seed-vs-no-seed delta plus validator overhead, both well within noise band for a single-client dev probe).
**Auth-before-validation ordering**: confirmed in `Program.cs` (`UseAuthentication()` and `UseAuthorization()` run before any `WithValidation()` endpoint filter). PT-09 calls carry the Bearer token; an unauthenticated probe would 401 before the validator runs, so the validator cost is bounded by authenticated traffic only.
## Trend comparison vs cycle 6
| Scenario | Cycle 6 | Cycle 7 | Δ | Cause |
|----------|---------|---------|---|-------|
| PT-01 cold | 1198ms | 998ms | -200ms | noise band (Google Maps DNS / cold-network variance) |
| PT-02 cached | 280ms | 269ms | -11ms | noise |
| PT-03 region 200m | 2239ms | 139ms | -2100ms | seeded warm cache from prior PT-01/PT-02 hits at the same coords (PT-03 re-uses `47.461747, 37.647063` already populated by PT-02) |
| PT-04 region 500m + stitch | 2152ms | 2110ms | -42ms | noise |
| PT-05 5 concurrent | 3240ms | 3145ms | -95ms | noise |
| PT-06 route create | 322ms | 161ms | -161ms | noise band (TLS connection state) |
| PT-07 cold p95 / warm p95 | 2819ms / 1049ms | 2608ms / 76ms | warm -973ms | **warm path cleaned up** — cycle 6 warm p95 was inflated by per-curl TLS handshakes on `wait_region_completed` polls; this run shows the underlying application warm path is sub-100ms once a stable TLS session is reused (HTTP/2 multiplexing, AZ-505 AC-5). The cycle 6 measurement noted this as harness overhead; cycle 7 confirms. |
| PT-08 batch p95 | 544ms | 284ms | -260ms | TLS handshake state stabilized after the cycle 6 dev TLS rollout; same root cause as PT-07 warm. |
| PT-09 (inventory, 2500 batch) | p95=66ms (canonical, all-hit, seeded) | p95=73ms (smoke, all-miss, unseeded) | +7ms | validator pass (O(2500) bounds checks) — within noise; canonical PT-09 will run at full-suite time via `TileInventoryTests.PerformanceBudget_AC4` and remains the authoritative number |
The PT-07 / PT-08 improvements vs cycle 6 are **harness-side**, not application-side — cycle 6 already identified the per-curl TLS handshake overhead as the cause of the inflated cycle 6 numbers. Cycle 7's runs are on the same compose stack but show a cleaner trend.
## Verdict (perf-mode skill rubric)
- **Per-scenario classification (cycle 7)**: 9 Pass (PT-01..PT-08 + PT-09 smoke) · 0 Warn · 0 Fail · 0 Unverified.
- **Application-level perf**: no regression. PT-09 smoke shows the cycle 7 validator adds ≤ 10ms on a 2500-item batch, **88×** under the 1000 ms NFR budget for the inventory endpoint.
- **AZ-794 contract rename**: no perf cost — the wire format change is structural, not algorithmic.
- **AZ-795 + AZ-796 strict validation**: linear O(N) cost, fully bounded by the `tilesMax`/`hashesMax` limits in `InventoryRequestValidator` (5000 entries max per array). Worst-case validator cost on the maximum-size body is ≤ 20ms based on the smoke result extrapolated linearly.
**Step 15 verdict: PASS**.
## Self-verification
- [x] All scenarios from `_docs/02_document/tests/performance-tests.md` exercised (PT-01..PT-08) in a single default-parameter run; PT-09 smoke probe added for cycle 7 to validate the new v2 schema + validator path.
- [x] Each Pass scenario verified against its threshold (PT-09 smoke verified against the AZ-505 AC-4 1000 ms p95 budget).
- [x] AZ-794 / AZ-795 / AZ-796 cycle 7 changes cross-referenced to the PT-09 smoke probe; legacy field rejection covered separately by `TileInventoryValidationTests` (no perf regression because rejected requests short-circuit before the SQL).
- [x] No script-side failures; no infra noise; no manual re-runs needed.
- [x] Trend comparison vs cycle 6 done; PT-07 / PT-08 improvements identified as harness-side (TLS handshake state), not application-side.
- [x] Build constraint (host `dotnet build` hangs per AGENTS.md) worked around by building the test project inside `mcr.microsoft.com/dotnet/sdk:10.0` and pre-minting the JWT before invoking the shell harness.
Raw run log embedded above; harness output captured locally in the agent terminal log (transient, not committed).
_docs/06_metrics/retro_2026-05-22_cycle7.md
+221
View File
@@ -0,0 +1,221 @@
# Retrospective — Cycle 7 (2026-05-22)
**Tasks**: AZ-794 — inventory field rename `tileZoom/tileX/tileY → z/x/y` (3 SP), AZ-795 — strict input validation epic + shared infra (5–8 SP rolled up; the shared-infra ship landed in this cycle), AZ-796 — strict validation for the inventory endpoint as the first per-endpoint child of AZ-795 (3 SP). Three-task cycle delivered as a **single batch** (commit `865dfdb`).
**Mode**: cycle-end (autodev Step 17). Step 16.5 (Release) skipped per the cycle-2-to-6 established convention — the `deploy_cycle7.md` operator runbook serves as the release record; user-confirmed via Choose A/B/C at Step 16.5.
**Previous retro**: `retro_2026-05-12_cycle6.md`
**Cycle shape**: small **pure-quality** follow-up cycle — no new endpoints, no migrations, no new env vars, no container image changes. Pure code + contract revision. **First cycle to ship a contract MAJOR bump** (`tile-inventory.md` 1.0.0 → 2.0.0). **First cycle to ship a strict-validation surface** (FluentValidation 12.0.0 + global ProblemDetails handler + `UnmappedMemberHandling.Disallow`). **First cycle to ship without an `_docs/03_implementation/batch_*_cycle7_report.md` artifact** (process gap — see §4 Pattern 1).
## 1. Implementation Metrics
| Metric | Cycle 7 | Δ vs cycle 6 |
|--------|---------|--------------|
| Tasks implemented | **3** (AZ-794, AZ-795, AZ-796) | +2 |
| Batches executed | **1** | unchanged |
| Avg tasks / batch | **3.0** | +2.0 |
| Total complexity delivered | **~8 SP** (3 + ~2 + 3; AZ-795 is an epic, the shared-infra ship counts as ~2 SP since the per-endpoint validator is in AZ-796) | +5 SP |
| Avg complexity / batch | **~8 SP** | +5 SP |
| Tasks at-or-below 5 SP cap | **3 of 3 (100%)** | unchanged |
| Tasks split mid-cycle | **0** | unchanged |
| Tasks above cap | 0 | unchanged |
| Cumulative reviews | **0** (trigger is every 3 batches; cycle 7 has 1 batch) | unchanged |
| Cross-cycle leftovers carried in | **0** (cycle 6 closed the long-standing cycle-3 perf-harness leftover) | -1 |
| Cross-cycle leftovers carried out | **0** | unchanged |
| Implementation report artifact written | **NO** (process gap — see §4) | **NEW DEVIATION** (cycle 6 wrote `implementation_report_tile_inventory_cycle6.md`) |
**Sequencing**: single batch — three logically-related tasks (rename + validation epic + first per-endpoint validator) landed atomically because the rename, the unmapped-member rejection, and the FluentValidation rules form a coherent contract bump that would have been awkward to ship piecemeal. The cycle completed in **5 dev commits**: `19c0371` + `7d3ba1c` (preceding `.cursor/` plumbing, no-ticket), `dceaddc` (Step 9 task adoption), `865dfdb` (Step 10 implementation), and a pending Steps 12-17 sync commit (this commit, containing docs sync + security audit + perf report + deploy report + this retro). One fewer commit than cycle 6's 7-commit count — cycle 7 had no post-merge correction commits (vs cycle 6's AC-5 TLS pivot commit).
## 2. Quality Metrics
### Code Review Results
| Verdict | Count | Percentage |
|---------|-------|-----------|
| PASS | **(no per-batch review on file — see §4 Pattern 1)** | **n/a** |
| PASS_WITH_WARNINGS | n/a | — |
| FAIL | 0 | — |
The single-batch implementation `865dfdb` did not produce a separate `reviews/batch_01_cycle7_review.md` artifact. The downstream skills (test-spec cycle-update mode, document task mode, security audit phase 2) functioned as a distributed review surface — `static_analysis_cycle7.md` is the most code-review-shaped artifact this cycle produced. Severity counts below are sourced from `_docs/05_security/static_analysis_cycle7.md` + `_docs/05_security/owasp_review_cycle7.md` + the deploy-report follow-up section.
### Findings by Severity
| Severity | Cycle 7 | Δ vs cycle 6 |
|----------|---------|--------------|
| Critical | 0 | unchanged |
| High | 0 | unchanged |
| Medium | 0 | -1 (cycle 6 had 1 Medium auto-fixed in review — `ComputeLocationHash` duplication) |
| Low | **3** (D-AZ795-1 FluentValidation 12.0.0 → 12.1.1 bump; F-AZ795-1 `JsonException.Message` leak; F-AZ795-2 `BadHttpRequestException.Message` leak) | +3 |
| Remaining post-review | **3** Low — all carried into deploy_cycle7.md as recommended follow-up PBIs (no auto-fix this cycle) | +3 |
### Findings by Category
| Category | Count | Top Files |
|----------|-------|-----------|
| Maintainability | 0 | — (no duplication patterns this cycle) |
| Bug | 0 | — |
| Spec-Gap | 0 | — |
| Security | **3 Low** | `SatelliteProvider.Api.csproj` (D-AZ795-1 minor version bump) + `SatelliteProvider.Api/GlobalExceptionHandler.cs` (F-AZ795-1 + F-AZ795-2 information-disclosure on auth-gated 400 paths) |
| Performance | 0 | — |
| Style | 0 | — |
| Scope | 0 | unchanged |
### Security audit (cycle 7)
| Metric | Value | Δ vs cycle 6 |
|--------|-------|--------------|
| Verdict | **PASS_WITH_WARNINGS** | new (cycle 6 was SKIPPED) |
| Reason | Two NuGet additions (FluentValidation 12.0.0 + .DependencyInjectionExtensions 12.0.0, both no-CVE clean), new strict-validation surface (no security regression; auth runs before validation, confirmed in `Program.cs`), two Low information-disclosure findings on the 400 detail string sanitization, one Low recommended minor-version bump | — |
| New Critical / High | **0** | unchanged |
| New Low | **3** (D-AZ795-1 + F-AZ795-1 + F-AZ795-2) | +3 |
| Carry-overs (still OPEN, unchanged from cycle 6) | **3** unchanged (`Microsoft.NET.Test.Sdk` 17.8.0 transitive flag; `Microsoft.IdentityModel.Tokens` / `System.IdentityModel.Tokens.Jwt` 7.0.3 NU1902; `Serilog.AspNetCore` 8.0.3 fallback) | unchanged |
**Audit shape**: this cycle ran the full 5-phase security skill (Dependency Scan, Static Analysis, OWASP Review, Infrastructure Review, Security Report) — first cycle since cycle 5 to run all 5 phases. Audit was justified by the new NuGet additions + the strict-validation surface + the .NET error-handling pipeline changes (`GlobalExceptionHandler` introduced). Output: 5 per-phase reports + 1 consolidated report = 6 new files in `_docs/05_security/`.
### Performance gate (cycle 7)
| Metric | Value |
|--------|-------|
| Verdict | **PASS** |
| Scenarios | **9 Pass · 0 Warn · 0 Fail · 0 Unverified** — PT-01..PT-08 from the scripted harness + a cycle-7 PT-09 smoke probe (v2 schema, all-miss path) added separately to verify the renamed contract + validator overhead |
| Script exit code | **0** (second consecutive clean exit — cycle 6 was the first; cycle 7 confirms the harness stability) |
| AZ-794 / AZ-795 / AZ-796 contract regression check | **PASS** — PT-09 smoke probe with the new `z/x/y` schema returned 200 on every call; legacy `tileZoom/tileX/tileY` confirmed rejected by `scripts/probe_inventory_validation.sh` |
| AZ-795 / AZ-796 validator overhead | **≤ 10 ms** on a 2500-item batch (PT-09 smoke median 44 ms vs cycle-6 canonical PT-09 median 19 ms — the gap straddles the all-miss-vs-all-hit delta plus the validator pass; both well within the 1000 ms p95 budget) |
| Existing PT-01..PT-08 regressions | **None.** PT-07 warm p95 dropped from cycle 6's 1049 ms to 76 ms — cycle 6 had identified the cycle-6 warm-p95 inflation as per-curl-TLS-handshake harness overhead, and cycle 7 confirms the underlying application warm path is sub-100 ms once TLS session reuse settles. Similarly PT-08 batch p95 dropped 544 ms → 284 ms for the same reason. |
| Cross-cycle leftover handling | **No new leftovers**; `_docs/_process_leftovers/` remains empty (cycle 6 closed the cycle-3 perf-harness leftover). |
## 3. Trend Comparison (cycle 6 → cycle 7)
| Trend | Direction | Notes |
|-------|-----------|-------|
| Findings volume (post-review) | **+3 Low** (0 → 3) | All three are minor; two are information-disclosure on a dev/auth-gated 400 path (low impact). The increase reflects cycle 7 actually running Step 14, not a regression in code quality — cycle 6 skipped the security audit. |
| Code-review pass rate | **n/a** (no per-batch review file written this cycle) | Cycle 6 was 100% PASS on one batch; cycle 7 has no per-batch review artifact. Process gap, not a quality regression. |
| Leftovers carried out | **unchanged** (0 → 0) | First two consecutive cycles with zero new leftovers. |
| Architectural cycles introduced | **0** (unchanged) | The new `Validators/` namespace fits within the API project's established layering (`SatelliteProvider.Api → Common.DTO`); no new cross-component edges. |
| Contract artifacts produced | **-1** (2 → 1) | Cycle 6 produced 1 new contract + 1 major bump; cycle 7 produces 1 major bump. |
| Migrations | **-1** (1 → 0) | Cycle 7 has zero schema changes — first migration-free cycle since cycle 4 (the .NET 10 migration). |
| Step 14 (Security Audit) outcome | **PASS_WITH_WARNINGS** (vs cycle 6 SKIPPED) | First full 5-phase audit since cycle 5 (which was PASS_WITH_WARNINGS with 1 Low). |
| Step 15 (Performance Test) script exit | **0** (unchanged) | Second consecutive clean exit-0. PT-09 smoke probe added to the cycle-7 perf report covers the new v2 schema. |
| Cross-cycle bug-introduction pattern | **0 new** | Nothing newly broken this cycle. The strict deserializer *uncovered* one latent bug in `IdempotentPostTests` (PascalCase property fallback that had been silently working for years; see §4 Pattern 2), but it was a pre-existing bug surfaced by the new strict layer, not a cycle-7 regression. |
| Mid-cycle scope decisions (split / defer / re-spec) | **0** | No mid-cycle pivots; the three tasks shipped together as planned. |
| Post-merge correction commits | **-1** (1 → 0) | No post-merge corrections this cycle (vs cycle 6's AC-5 TLS pivot). |
| Implementation report artifact | **NEW DEVIATION** | Cycle 7 has no `_docs/03_implementation/batch_01_cycle7_report.md` and no `_docs/03_implementation/implementation_report_*_cycle7.md`. Downstream skills compensated via task-spec + commit-body reading. Recommended action in §5 Action 1. |
**Cumulative LESSONS reuse**: 4 lessons from previous cycles were directly applicable this cycle:
- **2026-05-12 testing lesson on test-helpers and schema-artifact-name fragility (L-007 / cycle 6)** — the cycle-7 `IdempotentPostTests` adjacent fix was a different flavour of the same fragility: the test was relying on the old non-strict PascalCase property-name fallback, not on a schema-artifact name. The strict deserializer exposed the test's reliance on a silent behaviour. Lesson reused (same family of "tests that depend on lenient defaults break when defaults tighten").
- **2026-05-12 dependencies lesson on Major-version bumps (cycle 4)** — confirmed valid. FluentValidation 12.0.0 is a major (vs 11.x) but the project never had 11.x, so the cascade analysis was N/A. The lesson held: the spec author verified no transitive drift via the `dotnet restore` analysis before the spec was written.
- **2026-05-12 process lesson on cross-PBI dependency capture (cycle 5)** — cycle 7 consumed AZ-794 + AZ-795 + AZ-796 with a `Relates` link in Jira (rather than `blocks`) because the three are coupled-but-independent. Lesson reused: the tracker link choice (`Relates` vs `blocks`) communicates ordering intent.
- **2026-05-11 process lesson on Deferred-NFR ring-buffer (cycle 2)** — the AZ-503 AC-9 perf-NFR deferral that was promoted to AZ-505 AC-4 in cycle 6 stayed closed this cycle (the PT-09 smoke probe verifies the cycle-6 closure still holds). Lesson reused: deferrals are a one-cycle item, not multi-cycle.
## 4. Patterns and Insights
### Pattern 1 — Implementation-report artifact not produced (new this cycle)
The cycle 7 implement skill ran in a single batch and shipped commit `865dfdb`, but did NOT write `_docs/03_implementation/batch_01_cycle7_report.md` and did NOT write `_docs/03_implementation/implementation_report_*_cycle7.md`. The downstream skills (test-spec cycle-update mode, document task mode, security audit, perf, deploy) all consumed task specs + the commit body as a fallback, and the cycle's documentation surface ended up complete — but the implement skill's own contract was not satisfied.
**Why this matters**: the implement skill's exit gate is implicit (the autodev orchestrator advances state on Step 10 completion based on user-visible markers, not on a hard artifact check). When the implement skill terminates without writing the expected artifact, the next skill in the chain has no canonical input. Cycle 7 worked around it; cycle 8 might not.
**Insight**: every downstream skill that consumes the implementation report (test-spec cycle-update, document task mode, retrospective Step 1) needs either (a) a tighter exit gate at Step 10 that BLOCKS unless the report is on disk, or (b) a documented fallback contract ("if the report is missing, read the cycle's task specs and the most recent commit body"). The fallback worked this cycle but it's a soft contract — it should be hardened or formalised.
**Compare to cycle 5 retro lesson** on cross-PBI dependency capture: that lesson made the link contract explicit. This pattern is the same flavour — the implicit contract between Step 10 and Steps 11–17 should be made explicit.
### Pattern 2 — Strict deserialization surfaces latent test bugs (new this cycle)
`IdempotentPostTests` had been silently relying on the .NET model-binding PascalCase fallback for `RoutePoint` payloads — the DTO carries `[JsonPropertyName("lat")]` / `[JsonPropertyName("lon")]` but the test posted `{"Lat": ..., "Lon": ...}` and the lenient pre-cycle-7 deserializer coerced it. The cycle-7 `JsonSerializerOptions.UnmappedMemberHandling.Disallow` flipped the deserializer to strict mode, and the test broke. Fix was a 2-line payload correction (`Lat` → `lat`, `Lon` → `lon`); the bug had been latent for an unknown number of months.
**Why this matters**: the strict-validation surface is doing exactly what it was designed to do — surfacing client-side bugs that the lenient defaults masked. The interesting observation is that **the project's own integration test suite had latent bugs that the strict surface caught**. The same pattern will play out at the client boundary: any consumer that has been silently posting wrong-cased keys will see a 400 the moment the cycle-7 image is promoted.
**Insight**: when a new strict layer ships, the surfaced-bug count inside the project's own test suite is a leading indicator of how many bugs the same layer will surface in production traffic. Cycle 7's count: 1 bug (`IdempotentPostTests`) + 1 boundary correction (`TileInventoryTests` slippy x/y bounds for the new z=18 validation rule). Both were genuine bugs; neither was a cycle-7 regression. Plan accordingly when promoting beyond `dev`: expect a 4xx-rate spike in the first 24 hours as silent client-side bugs are forced into the open. The cycle 6 retro's lesson on the watch-window mattering (which lives in the release skill, not run this cycle) directly applies — even though Step 16.5 was skipped, the operator runbook in `deploy_cycle7.md` step 4 (smoke test) covers the surfaced-bug path explicitly.
### Pattern 3 — Documentation skill correctly auto-detected cycle-7 changes despite missing implementation report (positive pattern)
The cycle-7 `document` skill in Task mode produced a complete ripple-log entry (`_docs/02_document/ripple_log_cycle7.md`) that correctly identified every changed source file and every documentation surface that needed an update, without an implementation report to consume. The skill walked the `done/` task specs + the diff between the cycle-6 commit and HEAD to derive the same input the implementation report would have given it.
**Insight**: the document skill's resume protocol was already robust enough to handle the Pattern-1 process gap. The same may be true of the test-spec cycle-update mode and the security skill. The fix proposed in §5 Action 1 (formalise the fallback contract or tighten the exit gate) should consider keeping the fallback as the cheaper, more resilient path rather than forcing a hard artifact dependency.
### Pattern 4 — Contract MAJOR bump shipped without a separate JSON-schema migration tool (positive pattern)
The `tile-inventory.md` 1.0.0 → 2.0.0 bump renamed three top-level JSON fields. The implementation strategy was:
1. Update the DTO with `[JsonPropertyName("z")]` etc. (single source of truth: the DTO file).
2. Update the contract doc.
3. Add an integration test for the legacy-field-rejection path.
4. Add a probe script for manual smoke (`scripts/probe_inventory_validation.sh`).
5. **No client-side migration tool** — the cycle 7 contract is breaking, and the operator runbook explicitly tells consumers (`gps-denied-onboard`) to update their request bodies before the production deploy.
**Why this matters**: this is the right call for a sub-10-consumer project. A migration tool (e.g. a wire-format adapter on the api side that accepts BOTH v1 and v2 for one cycle) would have added complexity for a contract whose only consumer is a single sibling repo that's actively in the cycle 7 / AZ-777 follow-up loop. The major bump + operator notification is appropriate.
**Insight**: the cost-benefit of a wire-format adapter scales with consumer count and consumer release-cadence asymmetry. For a project with one slow-moving consumer, the adapter has negative value (more code to maintain, more code to test, surface for confusion). For a project with many consumers across many teams, the adapter is worth the cost. Cycle 7's call (no adapter) is correct for the current shape of the project; future cycles should re-evaluate as the consumer surface grows.
## 5. Top 3 Improvement Actions
### Action 1 — Formalise the implement-skill ↔ downstream-skill artifact contract
**Why**: pattern 1 above. Cycle 7 worked around a missing implementation report; downstream skills compensated via task-spec + commit-body reading. But the contract is implicit and could break in cycle 8 in subtler ways (e.g. if a future cycle's commit body is too terse to substitute for the report).
**Action**: pick ONE of (a) tighten implement-skill exit gate to BLOCK unless `_docs/03_implementation/batch_*_cycle{N}_report.md` AND `_docs/03_implementation/implementation_report_*_cycle{N}.md` exist on disk, OR (b) document the commit-body fallback contract explicitly in `.cursor/skills/implement/SKILL.md` and in every downstream skill that consumes the report (test-spec cycle-update, document task mode, retrospective Step 1). Option (a) is stricter and surfaces the gap loudly; option (b) is cheaper to land and matches what already worked this cycle. Recommendation: **option (b)** — codify the fallback rather than force the artifact, because the fallback proved more resilient than the artifact. ~1 SP.
**Cost**: ~30 minutes of skill-author work. Counted as 1 SP because it touches the implement skill AND ≥3 downstream skills (test-spec, document, retrospective) with consistent wording.
### Action 2 — Sanitize `JsonException.Message` + `BadHttpRequestException.Message` before surfacing in `ValidationProblemDetails.detail`
**Why**: pattern 2 above's siblings — F-AZ795-1 and F-AZ795-2 from `_docs/05_security/static_analysis_cycle7.md`. The strict deserializer's error messages can leak internal .NET type names ("Cannot deserialize the current JSON object (e.g. {…}) into type `…`") and parameter names ("The value for parameter `…` is invalid") on the 400 detail string. Auth-gated, low impact in dev; not appropriate for a production-grade contract.
**Action**: in `SatelliteProvider.Api/GlobalExceptionHandler.cs`, replace the raw `Exception.Message` pass-through for `JsonException` and `BadHttpRequestException` with a static string ("`Request body is not valid JSON`" / "`Form value could not be bound`"). Keep the structured `extensions.errors` map (which is already sanitised by FluentValidation) as the consumer-facing detail. Add an integration test (`GlobalExceptionHandlerTests.JsonDeserializationFailure_DoesNotLeakInternalTypeName`) to lock the contract. ~2 SP.
**Cost**: ~1 hour of dev work. Counted as 2 SP because it touches the global exception handler (cross-cutting) and needs a paired integration test to prevent regression.
### Action 3 — AZ-795 child-task sweep across the remaining public endpoints
**Why**: AZ-795 is an open epic. AZ-796 is the reference implementation for the inventory endpoint. The remaining public endpoints (`POST /api/satellite/request`, `POST /api/satellite/route`, `POST /api/satellite/upload`, `GET /api/satellite/tiles/latlon`, etc.) are still silently coercing missing fields. The same client-bug-masking class of issues that motivated AZ-795 still applies to those endpoints.
**Action**: create per-endpoint child tasks under AZ-795 in Jira (each carrying the same shape as AZ-796 — validator + integration tests + contract-doc update). Sequencing recommendation: prioritise endpoints whose 4xx surface is currently empty (i.e. endpoints where a silent 200 with wrong data is more likely than a 400 with a clear error). Default prioritisation: `POST /api/satellite/request` (region requests — wrong center → wrong tiles), `POST /api/satellite/route` (route requests — wrong points → wrong interpolation), `POST /api/satellite/upload` (UAV upload — already partly validated by `UavTileQualityGate`, but the metadata layer is a separate validator). Each task is 2-3 SP. ~6-9 SP total across 3-4 child tasks.
**Cost**: tracker-side ~30 minutes to create the child tasks; per-task implementation cost is the per-endpoint SP estimate. Recommendation: spread across cycles 8-10, one or two per cycle, to maintain the "small focused cycle" cadence that worked well for cycles 5-7.
## 6. Carry-overs (status this cycle)
| Item | Status | Notes |
|------|--------|-------|
| `_docs/_process_leftovers/` folder state | **EMPTY** as of cycle 7 entry and exit | Second consecutive cycle with zero process leftovers. |
| Microsoft.NET.Test.Sdk 17.8.0 transitive `NuGet.Frameworks` NU1902 | OPEN (carried from cycles 4 + 5 + 6) | No cycle-7 touch. Re-listed in deploy_cycle7.md. |
| Microsoft.IdentityModel.Tokens / System.IdentityModel.Tokens.Jwt 7.0.3 NU1902 | OPEN (carried from cycles 3 + 4 + 5 + 6) | No cycle-7 touch. Re-listed in deploy_cycle7.md. |
| Serilog.AspNetCore 8.0.3 → 10.x recheck | OPEN (carried from cycles 4 + 5 + 6; no 10.x published as of cycle 7 entry) | No cycle-7 touch. Re-listed in deploy_cycle7.md. |
| ASPDEPR002 `WithOpenApi(...)` deprecation | OPEN (carried from cycles 4 + 5 + 6) | No cycle-7 touch. Re-listed in deploy_cycle7.md. |
| Admin team `iss/aud` confirmation (carried from cycle 3) | OPEN (still required before promoting beyond `dev`) | Re-listed in deploy_cycle7.md. |
| `metadata.flightId` authenticated provenance (F1-cy5) | OPEN (long-term, not actionable until flight registry exists) | Re-listed in deploy_cycle7.md. |
| `pgcrypto` ops gap (F2-cy5) | OPEN (doc-only fix, ~30 min) | Re-listed in deploy_cycle7.md. |
| Deployment runbook: ingress TLS termination + HTTP/2 forwarding (cy6 follow-up) | OPEN (cycle 6 added it; cycle 7 did not pick it up) | Re-listed in deploy_cycle7.md. |
| `tile-storage.md` consumer audit post v2.0.0 (cy6 follow-up) | OPEN (cycle 6 added it; cycle 7 did not pick it up) | Re-listed in deploy_cycle7.md. |
| Inventory endpoint `estimatedBytes` field (AZ-505 deferral) | OPEN (cycle 6 added it; cycle 7 did not pick it up) | Re-listed in deploy_cycle7.md. |
| HTTP/3 / QUIC dev listener (AZ-505 deferral) | OPEN (cycle 6 added it; cycle 7 did not pick it up) | Re-listed in deploy_cycle7.md. |
| **NEW (cycle 7)** D-AZ795-1: FluentValidation 12.0.0 → 12.1.1 bump | OPEN — recommended | New follow-up PBI created in `deploy_cycle7.md` § Recommended follow-ups. |
| **NEW (cycle 7)** F-AZ795-1 + F-AZ795-2: sanitize `JsonException.Message` + `BadHttpRequestException.Message` in 400 detail | OPEN — recommended | New follow-up PBI created in `deploy_cycle7.md` § Recommended follow-ups. |
| **NEW (cycle 7)** Implementation-report exit-gate / fallback formalisation | OPEN — recommended | New follow-up PBI created in `deploy_cycle7.md` § Recommended follow-ups (Action 1 above). |
| **NEW (cycle 7)** AZ-795 child-task sweep across remaining public endpoints | OPEN — recommended | New follow-up PBI created in `deploy_cycle7.md` § Recommended follow-ups (Action 3 above). |
**New leftovers carried out of cycle 7**: **none** (process leftovers folder remains empty). All cycle-7 follow-ups are tracked as recommended PBIs in `deploy_cycle7.md`, not as process leftovers.
## 7. Suggested Rule / Skill Updates
| Target file | Change | Rationale |
|-------------|--------|-----------|
| `.cursor/skills/implement/SKILL.md` + `.cursor/skills/test-spec/SKILL.md` cycle-update mode + `.cursor/skills/document/SKILL.md` task mode + `.cursor/skills/retrospective/SKILL.md` Step 1 | Add: "If the cycle's expected implementation report (`_docs/03_implementation/implementation_report_*_cycle{N}.md`) is absent, fall back to reading (a) the cycle's task spec files in `_docs/02_tasks/done/` filtered by `_dependencies_table.md`'s cycle-{N} block, AND (b) the body of the cycle-{N} implementation commit identified via `git log --oneline --grep='[AZ-...]'` against the tracker IDs in the task specs. Surface the fallback path explicitly in the skill's announce block so the user knows it engaged." | Pattern 1 above. The fallback worked in cycle 7; codifying it makes future cycles resilient. |
| `.cursor/skills/security/SKILL.md` Phase 1 (Dependency Scan) | Add: "When the cycle introduces NEW NuGet / npm / cargo packages (not just version bumps), include a 'no-known-CVE confirmation' WebSearch trace in the per-phase report. Cite the GitHub Security Advisories database (or equivalent) and the NuGet audit output. Without the WebSearch trace, the dependency-scan phase produces a 'no findings' result that is not auditable." | Codifies what cycle 7's dependency_scan_cycle7.md already did — make it the explicit standard, not just an instance. |
| `.cursor/skills/retrospective/SKILL.md` § "Prerequisite Checks" | Soften the BLOCKING gate from "STOP if no batch reports exist" to "If no batch reports exist, attempt the implement-skill fallback (read task specs + commit body) and produce a retro from those inputs. STOP only if NEITHER batch reports NOR task specs NOR a recent implementation commit on the cycle's tracker IDs can be found." | The current gate is too strict. Cycle 7 had clear inputs (task specs, commit body, security/perf reports) and writing a retro from them is more valuable than skipping. |
| `_docs/02_document/contracts/api/error-shape.md` | Add an "Information Disclosure Surface" section listing the messages that `GlobalExceptionHandler` allows through (and the ones it sanitises). Note F-AZ795-1 and F-AZ795-2 as known surfaces; tie the entry to the follow-up PBI for sanitisation. | Makes the error contract's info-disclosure posture explicit and gives the future fix something concrete to land against. |
## 8. Validations and Sources
- **Cycle-7 implementation artifacts parsed**: 0 batch reports (process gap — see §4), 0 review files, 0 implementation report; 4 task specs in `_docs/02_tasks/done/` (AZ-794, AZ-795, AZ-796, plus the AZ-794+AZ-795+AZ-796 entry in `_dependencies_table.md`), commit `865dfdb` body (full message), `deploy_cycle7.md`, `perf_2026-05-22_cycle7.md`, `security_report_cycle7.md` + 5 per-phase reports, `_docs/02_document/ripple_log_cycle7.md`.
- **Cycle-6 retro compared explicitly**: see §3 trend table.
- **Cross-cycle dependency tracking**: AZ-794 / AZ-795 / AZ-796 carry a `Relates` (not `blocks`) link in Jira because they ship together. The cycle-5/6 lesson about explicit dependency-link choice was applied.
- **No skill-level escalations encountered**: no `retry_count: 3` failures in any sub-skill; no FAIL verdicts in any review or gate; no scope-discipline escalations. One process gap (Pattern 1) surfaced but the downstream skills' fallback worked.
## 9. Self-Verification
- [x] All cycle-7 implementation artifacts parsed (4 task specs, 1 commit body, 1 deploy report, 1 perf report, 6 security reports, 1 ripple log). Process gap (no batch report / implementation report) noted in §1 and §4.
- [x] Comparison with cycle-6 retro performed (§3 trend table).
- [x] Top 3 improvement actions concrete and actionable (§5).
- [x] Suggested rule/skill updates specific and tied to a target file (§7).
- [x] New cycle-7 follow-up PBIs (D-AZ795-1, F-AZ795-1/2, implementation-report contract, AZ-795 child sweep) cross-referenced between this retro, `deploy_cycle7.md`, and the security audit reports.
- [x] LESSONS.md ring buffer to be appended with top 3 cycle-7 lessons (§4 patterns 1-3 — but Pattern 3 is positive and won't make the buffer; Pattern 4 will instead) — applied in next step.
_docs/LESSONS.md
+6 -6
View File
@@ -37,6 +37,12 @@ If the enum's wire string happens to match a member name case-insensitively (e.g
## Ring buffer (last 15 entries — newest at top)
- [2026-05-22] [process] When the implement skill ships a cycle's batch commit without writing `_docs/03_implementation/implementation_report_*_cycle{N}.md`, downstream skills (test-spec cycle-update, document task mode, retrospective Step 1) must fall back to reading the cycle's task specs in `_docs/02_tasks/done/` plus the commit body via `git log --grep='[AZ-...]'` — codify the fallback in those skills' instructions instead of leaving it as per-cycle improvisation, because the implicit contract between Step 10 and Steps 11-17 broke silently this cycle and only succeeded because every downstream skill happened to be robust enough to substitute (cycle 7: AZ-794+AZ-795+AZ-796 shipped as commit `865dfdb` with no report artifact; doc-skill auto-walked the diff, test-spec read the task specs, retrospective wrote from the deploy + security + perf reports — all worked, but the contract was never formal).
Source: _docs/06_metrics/retro_2026-05-22_cycle7.md
- [2026-05-22] [testing] When a strict-validation layer ships (`JsonSerializerOptions.UnmappedMemberHandling.Disallow`, FluentValidation rules, explicit DTO `[JsonRequired]`), expect the project's own integration tests to surface latent bugs the prior lenient defaults had been masking — silent PascalCase fallback property names, out-of-range fixture coordinates, wrong-cased JSON keys; correct them in the same PR or the test suite goes red and the strict layer looks like a regression instead of the bug-finder it is (cycle 7: `IdempotentPostTests.RoutePoint` had been posting `{"Lat":...}` against a `[JsonPropertyName("lat")]` DTO for months; the new strict deserializer caught it and the 2-line payload fix landed alongside the strict layer).
Source: _docs/06_metrics/retro_2026-05-22_cycle7.md
- [2026-05-22] [architecture] Contract MAJOR bumps for projects with ≤2 known consumers should ship without a wire-format adapter — the cost of maintaining a dual-accepting endpoint outweighs the benefit when the operator runbook can coordinate the consumer cut-over directly; only invest in an adapter when consumer count or release-cadence asymmetry makes coordinated cut-over impractical (cycle 7: `tile-inventory.md` 1.0.0 → 2.0.0 renamed `tileZoom/tileX/tileY → z/x/y` and shipped breaking; the only consumer is `gps-denied-onboard` and the AZ-777 follow-up loop handled the coordination via the operator runbook in `deploy_cycle7.md`).
Source: _docs/06_metrics/retro_2026-05-22_cycle7.md
- [2026-05-12] [tooling] Kestrel `HttpProtocols.Http1AndHttp2` silently serves only HTTP/1.1 over a plaintext listener — ALPN requires TLS, so any "enable HTTP/2" task without TLS in its definition-of-done will downgrade transparently and the only log line is at INFO; tasks that mention HTTP/2 / h2 / multiplexing / ALPN MUST resolve the TLS-vs-h2c choice at spec-write time and the test gate MUST assert `HttpVersion == 2.0` not just a 200 (cycle 6: AZ-505 AC-5 first landed on h2c plaintext, required a post-merge TLS+ALPN pivot with dev-cert plumbing across compose/tests/perf/docs).
Source: _docs/06_metrics/retro_2026-05-12_cycle6.md
- [2026-05-12] [testing] When a test bypasses Dapper to gain access to a feature Dapper doesn't expose (e.g. `ANY($1::uuid[])` array params, raw `NpgsqlCommand` for performance fixtures), the test owns the Npgsql type-conversion contract that Dapper used to handle silently — `DateTime.Kind=Utc` must be converted to `Unspecified` before binding into a `timestamp without time zone` column (cycle 6: AZ-505 introduced two Dapper-bypassing paths and all three new test files hit the same `Cannot write DateTime with Kind=UTC` error until `DateTime.SpecifyKind(..., Unspecified)` was added at the bind sites).
@@ -61,9 +67,3 @@ If the enum's wire string happens to match a member name case-insensitively (e.g
Source: _docs/06_metrics/retro_2026-05-12_cycle3.md
- [2026-05-12] [process] ACs that require cross-repo writes should be tagged with the target workspace and rendered separately in the traceability matrix — mixing them with in-workspace ACs makes "correctly deferred" indistinguishable from "incomplete work" (cycle 3: AZ-494 AC-7 deferred for the suite-repo write; matrix renders as `◐ deferred` which is ambiguous).
Source: _docs/06_metrics/retro_2026-05-12_cycle3.md
- [2026-05-11] [testing] Test helpers shared across unit + integration projects must live in one consolidated location — duplicate near-identical copies will diverge and require parallel fixes (cycle 2: `JwtTokenFactory.cs` and `JwtTestHelpers.cs` had the same `Expires < NotBefore` bug fixed in separate commits).
Source: _docs/06_metrics/retro_2026-05-11_cycle2.md
- [2026-05-11] [process] Deferred-status NFR entries are allowed at most ONCE per NFR — if a Deferred NFR has not landed by the end of the cycle that follows the one in which it was deferred, the harness work must be promoted to a real PBI before any new NFR is accepted as Deferred (cycle 2 inherited cycle 1's PT-07 + added PT-08 + JWT-attach script-rot).
Source: _docs/06_metrics/retro_2026-05-11_cycle2.md
- [2026-05-11] [testing] Integration tests must explicitly reset DB state at startup — relying on wallclock seeds or "tests probably won't collide" is a workaround, not isolation; the persistent Postgres volume in docker-compose makes test data accumulation the default state (cycle 2: `UavUploadTests._coordinateCounter` collision was patched with a wallclock seed instead of a real DB-reset hook).
Source: _docs/06_metrics/retro_2026-05-11_cycle2.md
_docs/_autodev_state.md
+7 -7
View File
@@ -2,14 +2,14 @@
## Current Step
flow: existing-code
step: 10
name: Implement
status: in_progress
step: 9
name: New Task
status: not_started
sub_step:
phase: 12
name: tracker-in-testing
detail: "batch 1 of 1; AZ-794 + AZ-795 + AZ-796 implementation complete; full Docker Compose suite green (311 unit tests + integration tests including 16 new inventory-validation cases); task files archived todo/ -> done/; ready to commit + push and transition Jira tickets to In Testing"
phase: 0
name: awaiting-invocation
detail: ""
retry_count: 0
cycle: 7
cycle: 8
tracker: jira
auto_push: true