[AZ-484] Multi-source tile storage: source + captured_at

Add per-source tile rows to support multi-provider imagery (Google
Maps + future UAV). Migration 013 (transactional) introduces
source/captured_at columns, backfills existing rows to
(source='google_maps', captured_at=created_at), and replaces the
4-column unique index with a 5-column index that includes source.

TileRepository:
- ColumnList includes source + captured_at
- GetByTileCoordinatesAsync returns most-recent row across sources
  (ORDER BY captured_at DESC, updated_at DESC, id DESC)
- GetTilesByRegionAsync uses DISTINCT ON to pick the most-recent
  tile per cell, restoring caller-facing row order
- Insert/Update upsert on the new 5-column conflict key

TileSource enum lives in Common.Enums. Snake_case wire format
(google_maps, uav) is enforced by a focused TileSourceTypeHandler
because the generic ToLowerInvariant pattern would emit
"googlemaps", violating contract v1.0.0.

TileService stamps Source=GoogleMaps + CapturedAt=UtcNow on every
new tile. Tile-storage contract is now frozen at v1.0.0.

AC coverage 7/7. New unit + integration tests cover all ACs;
existing 200 unit + 5 smoke tests preserved.

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

SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql

@@ -0,0 +1,31 @@
+-- AZ-484: introduce per-source tile rows.
+-- Adds `source` and `captured_at` columns, backfills existing rows to
+-- (source='google_maps', captured_at=created_at), drops the 4-column unique index
+-- created by migration 012 (idx_tiles_unique_location), and replaces it with a
+-- 5-column unique index that includes `source`. The whole migration runs inside a
+-- single transaction so a failure mid-flight cannot leave the table without its
+-- unique index or with partially backfilled rows (per coderule.mdc and AZ-484
+-- Risk 1 mitigation).
+
+BEGIN;
+
+ALTER TABLE tiles ADD COLUMN IF NOT EXISTS source VARCHAR(32);
+ALTER TABLE tiles ADD COLUMN IF NOT EXISTS captured_at TIMESTAMP;
+
+UPDATE tiles
+SET source = 'google_maps'
+WHERE source IS NULL;
+
+UPDATE tiles
+SET captured_at = created_at
+WHERE captured_at IS NULL;
+
+ALTER TABLE tiles ALTER COLUMN source SET NOT NULL;
+ALTER TABLE tiles ALTER COLUMN captured_at SET NOT NULL;
+
+DROP INDEX IF EXISTS idx_tiles_unique_location;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_tiles_unique_location_source
+    ON tiles (latitude, longitude, tile_zoom, tile_size_meters, source);
+
+COMMIT;

SatelliteProvider.DataAccess/Models/TileEntity.cs

@@ -1,3 +1,5 @@
+using SatelliteProvider.Common.Enums;
+
 namespace SatelliteProvider.DataAccess.Models;
 
 public class TileEntity
@@ -14,6 +16,8 @@ public class TileEntity
     public string? MapsVersion { get; set; }
     public int? Version { get; set; }
     public string FilePath { get; set; } = string.Empty;
+    public TileSource Source { get; set; }
+    public DateTime CapturedAt { get; set; }
     public DateTime CreatedAt { get; set; }
     public DateTime UpdatedAt { get; set; }
 }

SatelliteProvider.DataAccess/Repositories/TileRepository.cs

@@ -16,7 +16,8 @@ public class TileRepository : ITileRepository
                    latitude, longitude,
                    tile_size_meters as TileSizeMeters, tile_size_pixels as TileSizePixels,
                    image_type as ImageType, maps_version as MapsVersion, version,
-                   file_path as FilePath, created_at as CreatedAt, updated_at as UpdatedAt";
+                   file_path as FilePath, source, captured_at as CapturedAt,
+                   created_at as CreatedAt, updated_at as UpdatedAt";
 
     private readonly string _connectionString;
     private readonly ILogger<TileRepository> _logger;
@@ -41,11 +42,13 @@ public class TileRepository : ITileRepository
     public async Task<TileEntity?> GetByTileCoordinatesAsync(int tileZoom, int tileX, int tileY)
     {
         using var connection = new NpgsqlConnection(_connectionString);
+        // AZ-484 selection rule: most-recent across sources, deterministic tie-break on
+        // (captured_at DESC, updated_at DESC, id DESC).
         const string sql = $@"
             SELECT {ColumnList}
             FROM tiles
             WHERE tile_zoom = @TileZoom AND tile_x = @TileX AND tile_y = @TileY
-            ORDER BY updated_at DESC
+            ORDER BY captured_at DESC, updated_at DESC, id DESC
             LIMIT 1";
 
         return await connection.QuerySingleOrDefaultAsync<TileEntity>(sql, new { TileZoom = tileZoom, TileX = tileX, TileY = tileY });
@@ -64,12 +67,21 @@ public class TileRepository : ITileRepository
         var latRange = expandedSizeMeters / GeoUtils.MetersPerDegreeLatitude;
         var lonRange = expandedSizeMeters / (GeoUtils.MetersPerDegreeLatitude * Math.Cos(latitude * Math.PI / 180.0));
 
+        // AZ-484 selection rule: at most one row per (lat, lon, zoom, size) cell, picking
+        // the most-recent across sources via DISTINCT ON, with deterministic tie-break on
+        // (captured_at DESC, updated_at DESC, id DESC). The outer ORDER BY restores the
+        // pre-AZ-484 caller-facing order (latitude DESC, longitude ASC, updated_at DESC).
         const string sql = $@"
-            SELECT {ColumnList}
-            FROM tiles
-            WHERE latitude BETWEEN @MinLat AND @MaxLat
-              AND longitude BETWEEN @MinLon AND @MaxLon
-              AND tile_zoom = @TileZoom
+            SELECT * FROM (
+                SELECT DISTINCT ON (latitude, longitude, tile_zoom, tile_size_meters)
+                       {ColumnList}
+                FROM tiles
+                WHERE latitude BETWEEN @MinLat AND @MaxLat
+                  AND longitude BETWEEN @MinLon AND @MaxLon
+                  AND tile_zoom = @TileZoom
+                ORDER BY latitude, longitude, tile_zoom, tile_size_meters,
+                         captured_at DESC, updated_at DESC, id DESC
+            ) deduped
             ORDER BY latitude DESC, longitude ASC, updated_at DESC";
 
         var stopwatch = Stopwatch.StartNew();
@@ -96,18 +108,23 @@ public class TileRepository : ITileRepository
     public async Task<Guid> InsertAsync(TileEntity tile)
     {
         using var connection = new NpgsqlConnection(_connectionString);
+        // AZ-484: per-source UPSERT — conflict key now includes `source` so that two
+        // producers (e.g. google_maps + uav) can coexist for the same cell. A re-insert
+        // for the SAME source updates file_path / tile_x / tile_y plus refreshes
+        // captured_at and updated_at to reflect the new acquisition.
         const string sql = @"
-            INSERT INTO tiles (id, tile_zoom, tile_x, tile_y, latitude, longitude, tile_size_meters, 
-                             tile_size_pixels, image_type, maps_version, version, file_path, 
-                             created_at, updated_at)
-            VALUES (@Id, @TileZoom, @TileX, @TileY, @Latitude, @Longitude, @TileSizeMeters, 
-                    @TileSizePixels, @ImageType, @MapsVersion, @Version, @FilePath, 
-                    @CreatedAt, @UpdatedAt)
-            ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters) 
-            DO UPDATE SET 
+            INSERT INTO tiles (id, tile_zoom, tile_x, tile_y, latitude, longitude, tile_size_meters,
+                             tile_size_pixels, image_type, maps_version, version, file_path,
+                             source, captured_at, created_at, updated_at)
+            VALUES (@Id, @TileZoom, @TileX, @TileY, @Latitude, @Longitude, @TileSizeMeters,
+                    @TileSizePixels, @ImageType, @MapsVersion, @Version, @FilePath,
+                    @Source, @CapturedAt, @CreatedAt, @UpdatedAt)
+            ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source)
+            DO UPDATE SET
                 file_path = EXCLUDED.file_path,
                 tile_x = EXCLUDED.tile_x,
                 tile_y = EXCLUDED.tile_y,
+                captured_at = EXCLUDED.captured_at,
                 updated_at = EXCLUDED.updated_at
             RETURNING id";
 
@@ -118,11 +135,11 @@ public class TileRepository : ITileRepository
     {
         using var connection = new NpgsqlConnection(_connectionString);
         const string sql = @"
-            UPDATE tiles 
+            UPDATE tiles
             SET tile_zoom = @TileZoom,
                 tile_x = @TileX,
                 tile_y = @TileY,
-                latitude = @Latitude, 
+                latitude = @Latitude,
                 longitude = @Longitude,
                 tile_size_meters = @TileSizeMeters,
                 tile_size_pixels = @TileSizePixels,
@@ -130,6 +147,8 @@ public class TileRepository : ITileRepository
                 maps_version = @MapsVersion,
                 version = @Version,
                 file_path = @FilePath,
+                source = @Source,
+                captured_at = @CapturedAt,
                 updated_at = @UpdatedAt
             WHERE id = @Id";
 

SatelliteProvider.DataAccess/TypeHandlers/EnumStringTypeHandler.cs

@@ -47,5 +47,6 @@ public static class DapperEnumTypeHandlers
 
         SqlMapper.AddTypeHandler(new EnumStringTypeHandler<RegionStatus>());
         SqlMapper.AddTypeHandler(new EnumStringTypeHandler<RoutePointType>());
+        SqlMapper.AddTypeHandler(new TileSourceTypeHandler());
     }
 }

SatelliteProvider.DataAccess/TypeHandlers/TileSourceTypeHandler.cs

@@ -0,0 +1,49 @@
+using System.Data;
+using Dapper;
+using SatelliteProvider.Common.Enums;
+
+namespace SatelliteProvider.DataAccess.TypeHandlers;
+
+// AZ-484: TileSource needs an explicit string mapping because the multi-word
+// member 'GoogleMaps' must round-trip as the snake_case wire value 'google_maps'
+// per the v1.0.0 tile-storage contract. The generic EnumStringTypeHandler<T>
+// only does ToString().ToLowerInvariant(), which would emit 'googlemaps'.
+public class TileSourceTypeHandler : SqlMapper.TypeHandler<TileSource>
+{
+    public const string GoogleMapsWireValue = "google_maps";
+    public const string UavWireValue = "uav";
+
+    public override TileSource Parse(object value)
+    {
+        if (value is null || value is DBNull)
+        {
+            throw new DataException("Cannot parse null DB value into enum TileSource");
+        }
+
+        var s = value as string ?? value.ToString();
+        if (string.IsNullOrEmpty(s))
+        {
+            throw new DataException("Cannot parse empty DB value into enum TileSource");
+        }
+
+        return s.ToLowerInvariant() switch
+        {
+            GoogleMapsWireValue => TileSource.GoogleMaps,
+            UavWireValue => TileSource.Uav,
+            _ => throw new DataException($"DB value '{s}' is not a defined member of enum TileSource"),
+        };
+    }
+
+    public override void SetValue(IDbDataParameter parameter, TileSource value)
+    {
+        parameter.Value = ToWireValue(value);
+        parameter.DbType = DbType.String;
+    }
+
+    public static string ToWireValue(TileSource value) => value switch
+    {
+        TileSource.GoogleMaps => GoogleMapsWireValue,
+        TileSource.Uav => UavWireValue,
+        _ => throw new ArgumentOutOfRangeException(nameof(value), value, "Unknown TileSource"),
+    };
+}