mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-22 00:01:15 +00:00
[AZ-505] Tile inventory endpoint + HTTP/2 + Leaflet covering index
Production code:
- POST /api/satellite/tiles/inventory (XOR body, 5000-cap,
most-recent-per-location_hash select, present/absent shaping).
- Kestrel HttpProtocols.Http1AndHttp2 on every listener (AC-5).
- Migration 015 creates tiles_leaflet_path covering index over
(location_hash, captured_at DESC, updated_at DESC, id DESC)
INCLUDE (file_path, source); drops superseded idx_tiles_location_hash.
- TileRepository.GetByTileCoordinatesAsync rewired to filter by
location_hash (Index Only Scan via tiles_leaflet_path).
- TileRepository.GetTilesByLocationHashesAsync added with Npgsql-
direct ANY($1::uuid[]) binding (Dapper IEnumerable expansion is
incompatible with the array form).
- Uuidv5.LocationHashForTile centralises the UUIDv5(TileNamespace,
"{z}/{x}/{y}") formula — single source of truth for the cross-repo
invariant (gps-denied-onboard parity).
Contracts:
- New: contracts/api/tile-inventory.md v1.0.0.
- Bumped: contracts/data-access/tile-storage.md to v2.0.0 (joint
ownership by AZ-503-foundation + AZ-505: schema + covering index +
GetByTileCoordinatesAsync rewrite).
Tests:
- TileInventoryTests covers AC-1, AC-2 (DB-level), AC-4, AC-6.
- Http2MultiplexingTests covers AC-5 (20 concurrent multiplexed GETs
over h2c via SocketsHttpHandler + AppContext Http2Unencrypted switch).
- LeafletPathIndexOnlyTests covers AC-3 (EXPLAIN (ANALYZE, BUFFERS)
asserts Index Only Scan over tiles_leaflet_path with heap_blocks=0).
Docs:
- architecture.md, system-flows.md, data_model.md, module-layout.md,
glossary.md, modules/api_program.md, modules/dataaccess_tile_repository.md,
components/02_data_access/description.md all updated to reference the
v2.0.0 tile-storage contract + new tile-inventory contract + AC-7.
Reports:
- batch_01_cycle6_report.md, batch_01_cycle6_review.md,
implementation_completeness_cycle6_report.md (PASS),
implementation_report_tile_inventory_cycle6.md.
Task spec moved todo/ -> done/.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,105 @@
|
||||
# Product Implementation Completeness Gate — Cycle 6
|
||||
|
||||
**Cycle**: 6
|
||||
**Date**: 2026-05-12
|
||||
**Scope**: AZ-505 (batch 1)
|
||||
|
||||
## Inputs Reviewed
|
||||
|
||||
- `_docs/02_tasks/done/AZ-505_tile_inventory_http2_leaflet_index.md`
|
||||
- `_docs/02_document/architecture.md`
|
||||
- `_docs/02_document/system-flows.md`
|
||||
- `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 (this cycle)
|
||||
- `_docs/02_document/contracts/data-access/tile-storage.md` v2.0.0 (this cycle)
|
||||
- `_docs/02_document/components/02_data_access/description.md`
|
||||
- `_docs/02_document/modules/api_program.md`
|
||||
- `_docs/02_document/modules/dataaccess_tile_repository.md`
|
||||
- `_docs/03_implementation/batch_01_cycle6_report.md`
|
||||
- `_docs/03_implementation/reviews/batch_01_cycle6_review.md`
|
||||
- Source code under each task's ownership envelope
|
||||
|
||||
## Per-Task Classification
|
||||
|
||||
### AZ-505 — Tile inventory endpoint + HTTP/2 + Leaflet covering index
|
||||
|
||||
**Verdict**: PASS
|
||||
|
||||
Evidence (source code, not tests or reports):
|
||||
|
||||
- **`SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql`** — `CREATE INDEX tiles_leaflet_path` covering index + `DROP INDEX IF EXISTS idx_tiles_location_hash`. Forward + back-migration documented in the header. Lock-window caveat per AZ-505 Risk 2 documented.
|
||||
- **`SatelliteProvider.Common/DTO/TileInventory.cs`** — five public DTOs (`TileInventoryRequest`, `TileCoord`, `TileInventoryResponse`, `TileInventoryEntry`, `TileInventoryLimits`) matching the v1.0.0 `tile-inventory.md` contract Shape section.
|
||||
- **`SatelliteProvider.Common/Utils/Uuidv5.cs`** — `LocationHashForTile(int z, int x, int y)` static; single source-of-truth for the cross-repo `UUIDv5(TileNamespace, "{z}/{x}/{y}")` formula. Eliminates the duplication that auto-fix flagged (Medium / Maintainability) during code review.
|
||||
- **`SatelliteProvider.Common/Interfaces/ITileService.cs`** — `GetInventoryAsync` added.
|
||||
- **`SatelliteProvider.DataAccess/Repositories/ITileRepository.cs`** — `GetTilesByLocationHashesAsync` added.
|
||||
- **`SatelliteProvider.DataAccess/Repositories/TileRepository.cs`** — `GetByTileCoordinatesAsync` rewired to filter by `location_hash` (computed via `Uuidv5.LocationHashForTile`); selection rule preserved. `GetTilesByLocationHashesAsync` implemented via Npgsql-direct `NpgsqlCommand` with `NpgsqlDbType.Array | Uuid` parameter binding + manual `NpgsqlDataReader` mapping. The Dapper-bypass is justified inline (Dapper's `IEnumerable` expansion is incompatible with `ANY($1::uuid[])`).
|
||||
- **`SatelliteProvider.Services.TileDownloader/TileService.cs`** — `GetInventoryAsync` implements the ordering invariant + Form-A / Form-B / present-absent shaping. `BuildTileEntity`'s `locationHashName` site is also consolidated to `Uuidv5.LocationHashForTile`.
|
||||
- **`SatelliteProvider.Api/Program.cs`** — `app.MapPost("/api/satellite/tiles/inventory", GetTilesInventory).RequireAuthorization().Accepts<TileInventoryRequest>("application/json").Produces<TileInventoryResponse>(200).ProducesProblem(400).WithOpenApi(...)`. Inline `GetTilesInventory` handler enforces body XOR + 5000-cap before delegating to `ITileService.GetInventoryAsync`. Kestrel configured with `HttpProtocols.Http1AndHttp2` on every listener via `builder.WebHost.ConfigureKestrel(opts => opts.ConfigureEndpointDefaults(lo => lo.Protocols = HttpProtocols.Http1AndHttp2))`.
|
||||
|
||||
Search for unresolved markers in modified source:
|
||||
|
||||
```
|
||||
$ rg -i 'placeholder|TODO|NotImplemented|scaffold|native bridge|fake|mock' \
|
||||
SatelliteProvider.Api/Program.cs \
|
||||
SatelliteProvider.Common/DTO/TileInventory.cs \
|
||||
SatelliteProvider.Common/Interfaces/ITileService.cs \
|
||||
SatelliteProvider.Common/Utils/Uuidv5.cs \
|
||||
SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql \
|
||||
SatelliteProvider.DataAccess/Repositories/ITileRepository.cs \
|
||||
SatelliteProvider.DataAccess/Repositories/TileRepository.cs \
|
||||
SatelliteProvider.Services.TileDownloader/TileService.cs
|
||||
```
|
||||
|
||||
→ no matches. (`stub` matches appear only in test-only fixtures from prior cycles; out of this task's scope.)
|
||||
|
||||
Named technologies / integrations promised by the task:
|
||||
|
||||
- **`tiles_leaflet_path` covering index** — created by migration 015; verified to exist when migrations run on a fresh DB.
|
||||
- **Kestrel HTTP/2 (`Http1AndHttp2`)** — wired via `builder.WebHost.ConfigureKestrel` per the AZ-505 Outcome bullet 3. AC-5 integration test confirms `HttpResponseMessage.Version == 2.0` over 20 concurrent multiplexed GETs.
|
||||
- **Npgsql `ANY($1::uuid[])` array binding** — used in `GetTilesByLocationHashesAsync`. The escape from Dapper is documented inline and is the production behaviour exercised by the AC-1 / AC-4 integration tests.
|
||||
- **Cross-repo `Uuidv5.TileNamespace`** — unchanged from AZ-503. AZ-505 consumes the existing constant via `Uuidv5.LocationHashForTile`. The sibling-repo's Python `c6_tile_cache/_uuid.py:TILE_NAMESPACE` is owned by `gps-denied-onboard` and is **out of scope for the satellite-provider workspace** per the AZ-505 Constraints section.
|
||||
|
||||
End-to-end production pipeline check: `POST /api/satellite/tiles/inventory` accepts XOR body shapes, delegates to `ITileService.GetInventoryAsync`, which composes `Uuidv5.LocationHashForTile` + `ITileRepository.GetTilesByLocationHashesAsync` (a real Npgsql query against the live DB, not a stub). `GET /tiles/{z}/{x}/{y}` (via `ServeTile`) now hits `tiles_leaflet_path` as an `Index Only Scan` — verified by `LeafletPathIndexOnlyTests` against the seeded fixture. No mocks, no scaffolded fallbacks anywhere on the hot path.
|
||||
|
||||
## Gate Verdict: PASS
|
||||
|
||||
Every promise from the AZ-505 task spec is implemented as production behaviour.
|
||||
|
||||
- No FAIL.
|
||||
- No BLOCKED.
|
||||
- No remediation tasks required.
|
||||
- Proceed to /implement Step 16 (Final Test Run). Per the existing-code flow, the next autodev step (Step 11 — Run Tests) owns the full-suite gate, so /implement Step 16 hands off to autodev Step 11 rather than re-running the suite.
|
||||
|
||||
## Files / Symbols Checked
|
||||
|
||||
Production code:
|
||||
- `SatelliteProvider.Api/Program.cs` (Kestrel config + endpoint registration + handler)
|
||||
- `SatelliteProvider.Common/DTO/TileInventory.cs` (5 DTOs)
|
||||
- `SatelliteProvider.Common/Interfaces/ITileService.cs` (1 method added)
|
||||
- `SatelliteProvider.Common/Utils/Uuidv5.cs` (1 method added)
|
||||
- `SatelliteProvider.DataAccess/Migrations/015_AddTilesLeafletPathIndex.sql`
|
||||
- `SatelliteProvider.DataAccess/Repositories/ITileRepository.cs` (1 method added)
|
||||
- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` (`GetByTileCoordinatesAsync` rewrite + `GetTilesByLocationHashesAsync` added)
|
||||
- `SatelliteProvider.Services.TileDownloader/TileService.cs` (`GetInventoryAsync` added + `BuildTileEntity` consolidated to `Uuidv5.LocationHashForTile`)
|
||||
|
||||
DB schema (post-migration):
|
||||
- `tiles_leaflet_path` covering index on `(location_hash, captured_at DESC, updated_at DESC, id DESC) INCLUDE (file_path, source)`
|
||||
- `idx_tiles_location_hash` dropped
|
||||
|
||||
Contracts:
|
||||
- `_docs/02_document/contracts/api/tile-inventory.md` v1.0.0 (new) — matches implementation Shape, Invariants, Test Cases
|
||||
- `_docs/02_document/contracts/data-access/tile-storage.md` v2.0.0 (major bump) — captures AZ-503-foundation columns + AZ-505 covering index + read-rewrite; Change Log entry names both producer tasks
|
||||
|
||||
Tests (existence + AC mapping verified):
|
||||
- `SatelliteProvider.IntegrationTests/TileInventoryTests.cs` (AC-1, AC-2, AC-4, AC-6)
|
||||
- `SatelliteProvider.IntegrationTests/Http2MultiplexingTests.cs` (AC-5)
|
||||
- `SatelliteProvider.IntegrationTests/LeafletPathIndexOnlyTests.cs` (AC-3)
|
||||
|
||||
## Unresolved Scaffold / Native Placeholders: None
|
||||
|
||||
## Named Promised Technologies Not Integrated: None
|
||||
|
||||
(All named integrations — `tiles_leaflet_path`, Kestrel HTTP/2, Npgsql `ANY($1::uuid[])` array binding, cross-repo `Uuidv5.TileNamespace` — are integrated and exercised by AC tests.)
|
||||
|
||||
## Required Remediation Tasks: None
|
||||
|
||||
Cycle 6 is complete from the implementation perspective. The full integration-test gate is owned by autodev Step 11 (test-run skill) per the handoff in `implementation_report_tile_inventory_cycle6.md`.
|
||||
Reference in New Issue
Block a user