[AZ-505] Test-spec sync + task-mode doc updates for cycle 6

Step 12 (Test-Spec Sync, cycle-update mode):
- blackbox-tests.md: append BT-23..BT-26 for AZ-505's new
  observable behaviors (inventory order/shape; leaflet
  most-recent via location_hash; HTTP/2 multiplex over TLS+ALPN;
  request validation).
- performance-tests.md: append PT-09 (inventory p95 ≤ 1000ms /
  2500 tiles); records cycle-6 measured p95=66ms; documents
  promotion path to scripts/run-performance-tests.sh if budget
  ever tightens.
- traceability-matrix.md: resolve the 5 AZ-503 deferrals
  (AC-5/6/9/10/12) by pointing at AZ-505 test names + add 7
  AZ-505 AC rows (AC-1..AC-7) + bump totals (90 -> 94 tests,
  56/56 -> 63/63 in-scope) + add cycle-6 coverage shape notes
  (budget relaxation rationale, voting-filter deferral note,
  TLS+ALPN pivot, NFR propagation).

Step 13 (Update Docs, task mode):
- common_dtos.md: add 5 new TileInventory DTOs.
- common_interfaces.md: add ITileService.GetInventoryAsync.
- services_tile_service.md: document TileService.GetInventoryAsync
  steps + the XOR-validation-in-handler note.
- dataaccess_migrator.md: bump migration count 14 -> 15;
  describe migration 015 (AZ-505 leaflet covering index, lock
  window, INCLUDE-list trade-off).
- system-flows.md: add F7 (Leaflet Tile Serving, AZ-310 +
  AZ-505 location_hash rewire + TLS+ALPN) and F8 (Tile
  Inventory Bulk Lookup) with sequence diagrams, validation
  surface, and AC-4 perf evidence. Update Flow Inventory +
  Dependencies tables accordingly.
- glossary.md: add "Tile Inventory" entry pointing at the
  v1.0.0 contract.
- ripple_log_cycle6.md: new file — exhaustive reverse-dependency
  analysis confirms zero stale downstream module docs.

Advance autodev state from step 11 -> 14 (skipping 12+13 as
completed in this commit; auto-chain through Step 14 = Security
Audit optional gate).

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/02_document/modules/common_dtos.md

@@ -110,6 +110,33 @@ 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)
+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.
+
+### 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).
+- Total entries (in either field) ≤ `TileInventoryLimits.MaxEntriesPerRequest` (5000); over-cap → HTTP 400 (Inv-7).
+
+### TileInventoryEntry (added AZ-505)
+Per-entry result inside `TileInventoryResponse`. One entry per request entry, in the SAME order as the request (`tile-inventory.md` Inv-2).
+- `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).
+- `CapturedAt` (DateTime?), `Source` (string?), `FlightId` (Guid?), `ResolutionMPerPx` (double?) — populated on the most-recent row; all null when `Present=false`.
+
+### TileInventoryResponse (added AZ-505)
+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).
+
 ## Internal Logic
 - `GeoPoint` uses a precision tolerance of `0.00005` degrees (~5.5 meters) for equality comparison.
 - `SatTile` eagerly computes its bounding box corners on construction by calling `GeoUtils.TileToWorldPos`.

_docs/02_document/modules/common_interfaces.md

@@ -11,6 +11,7 @@ Service contracts defining the application's core operations. Implementations li
 - `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileMetadata>>`: query tiles within a geographic region
 - `GetOrDownloadTileAsync(int z, int x, int y, CancellationToken) → Task<TileBytes>`: serve a tile by Z/X/Y, hitting cache, then repository, then downloader (added in AZ-310)
 - `DownloadAndStoreSingleTileAsync(double latitude, double longitude, int zoomLevel, CancellationToken) → Task<TileMetadata>`: download one tile by lat/lon and persist (added in AZ-311)
+- `GetInventoryAsync(TileInventoryRequest request, CancellationToken) → Task<TileInventoryResponse>`: bulk per-cell metadata read for the `POST /api/satellite/tiles/inventory` endpoint (added AZ-505). Computes `location_hash` per request entry via `Uuidv5.LocationHashForTile` (Form A) or uses the caller-supplied hashes (Form B), delegates the read to `ITileRepository.GetTilesByLocationHashesAsync`, applies the AZ-484 / AZ-503-foundation most-recent-across-sources selection per cell, and shapes the result so `response.results.length == request entry count` in input order (see `tile-inventory.md` v1.0.0 Inv-2..Inv-6). XOR validation + entry-cap enforcement happen in the API handler, not here.
 
 ### IRegionService
 - `RequestRegionAsync(Guid id, double lat, double lon, double sizeMeters, int zoomLevel, bool stitchTiles) → Task<RegionStatusResponse>`: creates a region record and enqueues for async processing

_docs/02_document/modules/dataaccess_migrator.md

@@ -23,7 +23,7 @@ Runs DbUp-based SQL migrations against PostgreSQL on application startup. Ensure
 ## Consumers
 - `Program.cs` — instantiated directly (not via DI) and called during startup. If migration fails, the application throws and does not start.
 
-## Migrations (14 scripts)
+## Migrations (15 scripts)
 1. `001_CreateTilesTable.sql`
 2. `002_CreateRegionsTable.sql`
 3. `003_CreateIndexes.sql`
@@ -38,6 +38,7 @@ Runs DbUp-based SQL migrations against PostgreSQL on application startup. Ensure
 12. `012_DropTileVersionConstraint.sql` — drops the legacy 5-col `(latitude, longitude, tile_zoom, tile_size_meters, version)` unique index, replaces with 4-col `idx_tiles_unique_location` (preparation for AZ-484).
 13. `013_AddTileSourceAndCapturedAt.sql` — AZ-484 multi-source tile storage. Transactional. Adds `source` (VARCHAR(32) NOT NULL DEFAULT 'google_maps') and `captured_at` (TIMESTAMP NOT NULL) columns; backfills existing rows with `source='google_maps'`, `captured_at=created_at`; drops `idx_tiles_unique_location` and creates 5-col `idx_tiles_unique_location_source` on `(latitude, longitude, tile_zoom, tile_size_meters, source)`. Idempotent against partial replays.
 14. `014_AddTileIdentityColumns.sql` — AZ-503 tile-identity foundation. Transactional. Enables the `pgcrypto` extension (`CREATE EXTENSION IF NOT EXISTS pgcrypto`) for the in-migration SHA-1 digest. Adds `flight_id` (UUID NULL), `location_hash` (UUID — backfilled then set NOT NULL), `content_sha256` (BYTEA NULL), `legacy_id` (UUID NULL). Defines a transactional `pg_temp.uuidv5(namespace, name)` PL/pgSQL function that mirrors `SatelliteProvider.Common.Utils.Uuidv5.Create` byte-for-byte, then backfills `location_hash = pg_temp.uuidv5(TILE_NAMESPACE, '{tile_zoom}/{tile_x}/{tile_y}')` and `legacy_id = id` for every pre-existing row. Drops AZ-484's `idx_tiles_unique_location_source` and creates `idx_tiles_unique_identity` UNIQUE on `(tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-0000-0000-0000-000000000000'::uuid))` plus a non-unique `idx_tiles_location_hash` on `(location_hash)`. Safe to replay on a partially-migrated database because column adds are `IF NOT EXISTS`-equivalent and `pg_temp.uuidv5` is deterministic — re-running yields the same `location_hash` values.
+15. `015_AddTilesLeafletPathIndex.sql` — AZ-505 leaflet covering index. Transactional. Creates `tiles_leaflet_path` covering index on `(location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source)` so the leaflet hot path (`SELECT file_path FROM tiles WHERE location_hash = $1 ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1`) becomes an `Index Only Scan` once `VACUUM ANALYZE` sets the visibility map. Drops the lightweight `idx_tiles_location_hash` introduced by migration 014 — the new covering index has the same leading column, so equality lookups by `location_hash` use it instead. Lock window: runs in DbUp's per-script transaction (incompatible with `CREATE INDEX CONCURRENTLY`); on a populated `tiles` table the build holds an `ACCESS SHARE` + `SHARE` lock for the build duration, blocking writes (see AZ-505 Risk 2). Inventory queries (`GetTilesByLocationHashesAsync`) intentionally project columns beyond the INCLUDE list (`id`, `captured_at`, `flight_id`, etc.) and therefore trigger a bounded heap fetch — acceptable per AZ-505 NFR-Perf-2 (p95 ≤ 1000 ms / 2500 tiles) and explicit in the migration header.
 
 ## Configuration
 Receives connection string directly as constructor parameter.

_docs/02_document/modules/services_tile_service.md

@@ -17,6 +17,11 @@ Orchestrates tile downloading and persistence. Bridges the downloader (Google Ma
 - `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileMetadata>>`: query tiles in a region
 - `GetOrDownloadTileAsync(int z, int x, int y, CancellationToken) → Task<TileBytes>` (AZ-310): cache → repository → downloader fallback for single Z/X/Y serving
 - `DownloadAndStoreSingleTileAsync(double latitude, double longitude, int zoomLevel, CancellationToken) → Task<TileMetadata>` (AZ-311): download one tile by lat/lon, persist, return metadata
+- `GetInventoryAsync(TileInventoryRequest request, CancellationToken) → Task<TileInventoryResponse>` (AZ-505): bulk per-cell metadata read for `POST /api/satellite/tiles/inventory`. Steps:
+  1. Project the request to an ordered `Guid[]` of `location_hash` values — either by computing `Uuidv5.LocationHashForTile(z, x, y)` per entry (Form A `request.Tiles`) or by echoing the caller-supplied hashes (Form B `request.LocationHashes`). The request-order vector is retained so step 3 can shape the response in input order.
+  2. Call `ITileRepository.GetTilesByLocationHashesAsync(hashes, CancellationToken)` once. The repository returns the most-recent row per hash (`(captured_at DESC, updated_at DESC, id DESC) LIMIT 1` per `location_hash`); this is the AZ-484 / AZ-503-foundation selection rule preserved at the bulk layer.
+  3. Build a `TileInventoryEntry[]` of the same length as the input vector. For each request slot: emit `Present=false` (only `LocationHash` populated) when no row was returned for that hash; otherwise emit `Present=true` with `Id` / `CapturedAt` / `Source` / `FlightId` / `ResolutionMPerPx` populated from the row. Order matches the request — duplicate hashes in the request produce duplicate entries pointing at the same row (`tile-inventory.md` v1.0.0 Inv-2 / Inv-3).
+  4. XOR validation (both populated / neither populated) and the 5000-entry cap are NOT enforced here — they live in the API handler (`GetTilesInventory` in `Program.cs`) so the HTTP-layer error contract is single-sourced and `ITileService.GetInventoryAsync` can be called from non-HTTP contexts without re-implementing the gate.
 
 ## Internal Logic
 - New rows write `Version = null` and `MapsVersion = null` (post-AZ-357 / AZ-373); the `version` and `maps_version` columns are retained for backward compatibility with pre-existing rows