mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 12:21:14 +00:00

Files

T

Oleksandr Bezdieniezhnykh 909f69cb3a [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>

2026-05-12 21:16:37 +03:00

7.8 KiB

Raw Blame History

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.

7.8 KiB Raw Blame History