[AZ-484] Cycle 1 Steps 12-16: docs, security, perf, deploy report

Captures the post-implementation autodev gates for AZ-484 multi-source tile storage: - Step 12 (Test-Spec Sync): added 7 AC rows (AZ-484 AC-1..AC-7) and a PT-07 NFR row to traceability-matrix.md; added PT-07 scenario to performance-tests.md. - Step 13 (Update Docs): refreshed data_model.md (tiles columns + indexes + selection rule + UPSERT contract + migrations 012/013), module-layout.md (Common/Enums section with L-001 guidance, DataAccess imports-from now lists 6 sites), 6 module / component docs to reflect the new repo signatures, source/captured_at fields, and Dapper enum bypass workaround. ripple_log_cycle1.md records zero out-of-scope ripple. - Step 14 (Security Audit): PASS_WITH_WARNINGS - 0 Critical, 0 High, 5 Medium, 5 Low. AZ-484 itself added zero new findings. Hardening items (Postgres default creds, .env in build context, GMaps key rotation, ASP.NET Core 8.0.21 -> 8.0.25, rate limiter) recorded for separate tickets. - Step 15 (Performance Test): all PT-01..PT-07 scenarios Unverified (non-blocking); PT-07 baseline-comparison harness deferred to a leftover for next cycle. - Step 16 (Deploy): cycle deploy report covering migration safety, rollback path, post-deploy verification, security caveats. Co-authored-by: Cursor <cursoragent@cursor.com>
[AZ-484] Fix multi-source tile reads: drop Dapper enum handler
2026-06-22 13:51:14 +00:00 · 2026-05-11 10:03:05 +03:00 · 2026-05-11 06:44:34 +03:00 · 2026-05-11 06:21:59 +03:00 · 2026-05-11 06:05:06 +03:00
42 changed files with 1874 additions and 78 deletions
@@ -15,3 +15,4 @@ TestResults/
 coverage.cobertura.xml
 coverage.opencover.xml
 *.coverage
+_docs/03_implementation/test_runs/
@@ -0,0 +1,7 @@
+namespace SatelliteProvider.Common.Enums;
+
+public enum TileSource
+{
+    GoogleMaps,
+    Uav,
+}
@@ -0,0 +1,36 @@
+namespace SatelliteProvider.Common.Enums;
+
+// AZ-484: contract v1.0.0 stores TileSource as a snake_case string
+// ('google_maps', 'uav'). Dapper's TypeHandler<T> for enum types is bypassed
+// during deserialization (Dapper issue #259), so we cannot rely on a Dapper
+// handler to round-trip enum<->wire string. Instead, TileEntity stores the
+// wire value as a plain string and producers/consumers convert through this
+// helper at the boundary, preserving type safety in business code while
+// avoiding the Dapper enum read bug.
+public static class TileSourceConverter
+{
+    public const string GoogleMapsWireValue = "google_maps";
+    public const string UavWireValue = "uav";
+
+    public static string ToWireValue(TileSource value) => value switch
+    {
+        TileSource.GoogleMaps => GoogleMapsWireValue,
+        TileSource.Uav => UavWireValue,
+        _ => throw new ArgumentOutOfRangeException(nameof(value), value, "Unknown TileSource"),
+    };
+
+    public static TileSource FromWireValue(string wireValue)
+    {
+        ArgumentNullException.ThrowIfNull(wireValue);
+
+        return wireValue.ToLowerInvariant() switch
+        {
+            GoogleMapsWireValue => TileSource.GoogleMaps,
+            UavWireValue => TileSource.Uav,
+            _ => throw new ArgumentException($"'{wireValue}' is not a defined member of enum TileSource", nameof(wireValue)),
+        };
+    }
+
+    public static bool IsValidWireValue(string? wireValue) =>
+        wireValue is GoogleMapsWireValue or UavWireValue;
+}
@@ -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;
@@ -1,3 +1,5 @@
+using SatelliteProvider.Common.Enums;
+
 namespace SatelliteProvider.DataAccess.Models;

 public class TileEntity
@@ -14,6 +16,12 @@ public class TileEntity
    public string? MapsVersion { get; set; }
    public int? Version { get; set; }
    public string FilePath { get; set; } = string.Empty;
+    // AZ-484: stored as the contract wire value (snake_case string). See
+    // TileSourceConverter for enum<->wire conversion. Cannot use the
+    // TileSource enum directly because Dapper bypasses TypeHandler<T> for
+    // enum types during read deserialization (Dapper issue #259).
+    public string Source { get; set; } = TileSourceConverter.GoogleMapsWireValue;
+    public DateTime CapturedAt { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
 }
@@ -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,13 +67,24 @@ 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); the pre-AZ-484
+        // updated_at DESC tiebreak is unreachable here because DISTINCT ON already
+        // guarantees one row per (latitude, longitude, ...) tuple.
        const string sql = $@"
-            SELECT {ColumnList}
-            FROM tiles
-            WHERE latitude BETWEEN @MinLat AND @MaxLat
-              AND longitude BETWEEN @MinLon AND @MaxLon
-              AND tile_zoom = @TileZoom
-            ORDER BY latitude DESC, longitude ASC, updated_at DESC";
+            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";

        var stopwatch = Stopwatch.StartNew();
        var tiles = await connection.QueryAsync<TileEntity>(sql, new
@@ -96,18 +110,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 +137,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 +149,8 @@ public class TileRepository : ITileRepository
                maps_version = @MapsVersion,
                version = @Version,
                file_path = @FilePath,
+                source = @Source,
+                captured_at = @CapturedAt,
                updated_at = @UpdatedAt
            WHERE id = @Id";

@@ -15,9 +15,21 @@ public static class MigrationTests
            ?? "Host=postgres;Port=5432;Database=satelliteprovider;Username=postgres;Password=postgres";

        await DedupeSqlCollapsesDuplicatesByLatestUpdatedAt_AZ357_AC2(connectionString);
-        await NewUniqueConstraintExistsOnFourColumns_AZ357_AC2(connectionString);

        Console.WriteLine("✓ Migration 012 tests: PASSED");
+
+        Console.WriteLine();
+        Console.WriteLine("Test: Migration 013 (AZ-484)");
+        Console.WriteLine("============================");
+        Console.WriteLine();
+
+        await BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4(connectionString);
+        await MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1(connectionString);
+        await MostRecentAcrossSourcesSelection_AZ484_AC2(connectionString);
+        await SameSourceUpsertReplacesPreviousRow_AZ484_AC3(connectionString);
+        await NewUniqueConstraintIncludesSourceColumn_AZ484_AC1(connectionString);
+
+        Console.WriteLine("✓ Migration 013 tests: PASSED");
    }

    private static async Task DedupeSqlCollapsesDuplicatesByLatestUpdatedAt_AZ357_AC2(string connectionString)
@@ -103,50 +115,326 @@ public static class MigrationTests
        Console.WriteLine("  ✓ Unique row (idF) preserved");
    }

-    private static async Task NewUniqueConstraintExistsOnFourColumns_AZ357_AC2(string connectionString)
+    private static async Task NewUniqueConstraintIncludesSourceColumn_AZ484_AC1(string connectionString)
    {
        Console.WriteLine();
-        Console.WriteLine("AZ-357 AC-2 part 2: post-migration unique index has the new 4-column shape");
+        Console.WriteLine("AZ-484 AC-1 part 2: post-migration-013 unique index includes the source column");

        // Arrange / Act
        await using var conn = new NpgsqlConnection(connectionString);
        await conn.OpenAsync();

        const string sql = @"
-            SELECT indexdef
+            SELECT indexname, indexdef
            FROM pg_indexes
            WHERE schemaname = 'public'
-              AND tablename = 'tiles'
-              AND indexname = 'idx_tiles_unique_location';";
+              AND tablename = 'tiles';";

-        await using var cmd = new NpgsqlCommand(sql, conn);
-        var indexDef = (string?)await cmd.ExecuteScalarAsync();
+        var rows = new List<(string Name, string Def)>();
+        await using (var cmd = new NpgsqlCommand(sql, conn))
+        await using (var reader = await cmd.ExecuteReaderAsync())
+        {
+            while (await reader.ReadAsync())
+            {
+                rows.Add((reader.GetString(0), reader.GetString(1)));
+            }
+        }

        // Assert
-        if (indexDef == null)
+        var newIndex = rows.FirstOrDefault(r => string.Equals(r.Name, "idx_tiles_unique_location_source", StringComparison.Ordinal));
+        if (newIndex.Def is null)
        {
-            throw new Exception("AZ-357 AC-2: idx_tiles_unique_location does not exist on tiles table after migration 012");
+            throw new Exception(
+                "AZ-484 AC-1: expected unique index 'idx_tiles_unique_location_source' on tiles after migration 013, but it is not present. " +
+                $"Found indexes: {string.Join(", ", rows.Select(r => r.Name))}");
        }

-        // Expected shape after migration 012 — 4 cols, no version, UNIQUE
-        var lower = indexDef.ToLowerInvariant();
+        var lower = newIndex.Def.ToLowerInvariant();
        if (!lower.Contains("unique"))
        {
-            throw new Exception($"AZ-357 AC-2: idx_tiles_unique_location is not UNIQUE. Definition: {indexDef}");
+            throw new Exception($"AZ-484 AC-1: idx_tiles_unique_location_source is not UNIQUE. Definition: {newIndex.Def}");
        }
-        foreach (var col in new[] { "latitude", "longitude", "tile_zoom", "tile_size_meters" })
+        foreach (var col in new[] { "latitude", "longitude", "tile_zoom", "tile_size_meters", "source" })
        {
            if (!lower.Contains(col))
            {
-                throw new Exception($"AZ-357 AC-2: idx_tiles_unique_location missing column '{col}'. Definition: {indexDef}");
+                throw new Exception($"AZ-484 AC-1: idx_tiles_unique_location_source missing column '{col}'. Definition: {newIndex.Def}");
            }
        }
-        if (lower.Contains("version"))
+
+        var oldIndex = rows.FirstOrDefault(r => string.Equals(r.Name, "idx_tiles_unique_location", StringComparison.Ordinal));
+        if (oldIndex.Def is not null)
        {
-            throw new Exception($"AZ-357 AC-2: idx_tiles_unique_location still includes 'version' column — migration did not drop it. Definition: {indexDef}");
+            throw new Exception(
+                "AZ-484 AC-1: legacy 4-column index 'idx_tiles_unique_location' still exists after migration 013 — migration did not drop it. " +
+                $"Definition: {oldIndex.Def}");
        }

-        Console.WriteLine($"  ✓ Index present with new shape: {indexDef}");
+        Console.WriteLine($"  ✓ New 5-column unique index present: {newIndex.Def}");
+        Console.WriteLine("  ✓ Legacy 4-column unique index dropped");
+    }
+
+    private static async Task BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4(string connectionString)
+    {
+        Console.WriteLine();
+        Console.WriteLine("AZ-484 AC-4: backfill UPDATE assigns source='google_maps' and captured_at = created_at, preserving row count");
+
+        // Arrange — TEMP table simulating the pre-migration tiles shape with 3 sample rows.
+        await using var conn = new NpgsqlConnection(connectionString);
+        await conn.OpenAsync();
+
+        await ExecAsync(conn, """
+            CREATE TEMP TABLE tiles_backfill_test (
+                id UUID PRIMARY KEY,
+                created_at TIMESTAMP NOT NULL,
+                source VARCHAR(32),
+                captured_at TIMESTAMP
+            );
+            """);
+
+        var idA = Guid.Parse("aaaaaaaa-1111-1111-1111-111111111111");
+        var idB = Guid.Parse("bbbbbbbb-2222-2222-2222-222222222222");
+        var idC = Guid.Parse("cccccccc-3333-3333-3333-333333333333");
+
+        await ExecAsync(conn, """
+            INSERT INTO tiles_backfill_test (id, created_at) VALUES
+                (@idA, '2024-01-15 12:34:56'),
+                (@idB, '2025-06-20 03:00:00'),
+                (@idC, '2026-05-11 06:00:00');
+            """,
+            ("idA", idA), ("idB", idB), ("idC", idC));
+
+        // Act — apply the same UPDATE pattern that migration 013 uses.
+        await ExecAsync(conn, """
+            UPDATE tiles_backfill_test SET source = 'google_maps' WHERE source IS NULL;
+            UPDATE tiles_backfill_test SET captured_at = created_at WHERE captured_at IS NULL;
+            """);
+
+        // Assert
+        var rows = new List<(Guid Id, string Source, DateTime CreatedAt, DateTime CapturedAt)>();
+        await using (var cmd = new NpgsqlCommand(
+            "SELECT id, source, created_at, captured_at FROM tiles_backfill_test ORDER BY id;", conn))
+        await using (var reader = await cmd.ExecuteReaderAsync())
+        {
+            while (await reader.ReadAsync())
+            {
+                rows.Add((
+                    reader.GetGuid(0),
+                    reader.GetString(1),
+                    reader.GetDateTime(2),
+                    reader.GetDateTime(3)));
+            }
+        }
+
+        if (rows.Count != 3)
+        {
+            throw new Exception($"AZ-484 AC-4 backfill changed row count. Expected 3, got {rows.Count}.");
+        }
+        foreach (var row in rows)
+        {
+            if (row.Source != "google_maps")
+            {
+                throw new Exception($"AZ-484 AC-4: row {row.Id} has source='{row.Source}', expected 'google_maps'.");
+            }
+            if (row.CapturedAt != row.CreatedAt)
+            {
+                throw new Exception($"AZ-484 AC-4: row {row.Id} captured_at={row.CapturedAt:o} does not equal created_at={row.CreatedAt:o}.");
+            }
+        }
+
+        Console.WriteLine("  ✓ All 3 backfilled rows have source='google_maps' and captured_at = created_at");
+    }
+
+    private static async Task MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1(string connectionString)
+    {
+        Console.WriteLine();
+        Console.WriteLine("AZ-484 AC-1: per-source unique index lets two producers store distinct rows for the same cell");
+
+        // Arrange — TEMP table replicating the 5-column unique index shape.
+        await using var conn = new NpgsqlConnection(connectionString);
+        await conn.OpenAsync();
+
+        await CreateTempTilesTable(conn, "tiles_multisource_test");
+        await ExecAsync(conn, """
+            CREATE UNIQUE INDEX idx_tiles_multisource_test_unique
+                ON tiles_multisource_test (latitude, longitude, tile_zoom, tile_size_meters, source);
+            """);
+
+        var idGoogle = Guid.NewGuid();
+        var idUav = Guid.NewGuid();
+
+        // Act
+        await ExecAsync(conn, """
+            INSERT INTO tiles_multisource_test (id, latitude, longitude, tile_zoom, tile_size_meters, source, captured_at, file_path, updated_at)
+            VALUES (@id, 47.5, 37.6, 18, 100, 'google_maps', '2026-05-10 00:00:00', 'tiles/google.jpg', '2026-05-10 00:00:00');
+            """, ("id", idGoogle));
+
+        await ExecAsync(conn, """
+            INSERT INTO tiles_multisource_test (id, latitude, longitude, tile_zoom, tile_size_meters, source, captured_at, file_path, updated_at)
+            VALUES (@id, 47.5, 37.6, 18, 100, 'uav', '2026-05-11 00:00:00', 'tiles/uav.jpg', '2026-05-11 00:00:00');
+            """, ("id", idUav));
+
+        // Assert
+        var rowCount = await ScalarLongAsync(conn,
+            "SELECT COUNT(*) FROM tiles_multisource_test WHERE latitude = 47.5 AND longitude = 37.6 AND tile_zoom = 18 AND tile_size_meters = 100;");
+        if (rowCount != 2)
+        {
+            throw new Exception($"AZ-484 AC-1: expected 2 rows for the cell after multi-source insert, got {rowCount}.");
+        }
+
+        Console.WriteLine("  ✓ Both google_maps and uav rows coexist under the 5-column unique index");
+    }
+
+    private static async Task MostRecentAcrossSourcesSelection_AZ484_AC2(string connectionString)
+    {
+        Console.WriteLine();
+        Console.WriteLine("AZ-484 AC-2: most-recent-across-sources selection rule returns the latest captured_at row");
+
+        // Arrange — TEMP table with two rows for the same cell, distinct sources, T2 > T1.
+        await using var conn = new NpgsqlConnection(connectionString);
+        await conn.OpenAsync();
+
+        await CreateTempTilesTable(conn, "tiles_selection_test");
+
+        var idGoogleT1 = Guid.NewGuid();
+        var idUavT2 = Guid.NewGuid();
+
+        await ExecAsync(conn, """
+            INSERT INTO tiles_selection_test (id, latitude, longitude, tile_zoom, tile_size_meters, source, captured_at, file_path, updated_at)
+            VALUES
+                (@idG, 48.0, 38.0, 18, 100, 'google_maps', '2026-04-01 00:00:00', 'g.jpg', '2026-04-01 00:00:00'),
+                (@idU, 48.0, 38.0, 18, 100, 'uav',         '2026-05-01 00:00:00', 'u.jpg', '2026-05-01 00:00:00');
+            """,
+            ("idG", idGoogleT1), ("idU", idUavT2));
+
+        // Act — same SELECT shape used by TileRepository.GetByTileCoordinatesAsync.
+        Guid? winnerId;
+        string? winnerSource;
+        await using (var cmd = new NpgsqlCommand("""
+            SELECT id, source FROM tiles_selection_test
+            WHERE latitude = 48.0 AND longitude = 38.0 AND tile_zoom = 18 AND tile_size_meters = 100
+            ORDER BY captured_at DESC, updated_at DESC, id DESC
+            LIMIT 1;
+            """, conn))
+        await using (var reader = await cmd.ExecuteReaderAsync())
+        {
+            if (!await reader.ReadAsync())
+            {
+                throw new Exception("AZ-484 AC-2: selection query returned no rows; expected the uav row.");
+            }
+            winnerId = reader.GetGuid(0);
+            winnerSource = reader.GetString(1);
+        }
+
+        // Assert
+        if (winnerId != idUavT2 || winnerSource != "uav")
+        {
+            throw new Exception(
+                $"AZ-484 AC-2: expected uav row (id={idUavT2}) to win, got id={winnerId} source='{winnerSource}'.");
+        }
+
+        Console.WriteLine("  ✓ Selection rule picked the uav row (captured_at T2 > T1) deterministically");
+    }
+
+    private static async Task SameSourceUpsertReplacesPreviousRow_AZ484_AC3(string connectionString)
+    {
+        Console.WriteLine();
+        Console.WriteLine("AZ-484 AC-3: same-source UPSERT keeps a single row with refreshed captured_at and file_path");
+
+        // Arrange — TEMP table with the 5-column unique index so ON CONFLICT works.
+        await using var conn = new NpgsqlConnection(connectionString);
+        await conn.OpenAsync();
+
+        await CreateTempTilesTable(conn, "tiles_upsert_test");
+        await ExecAsync(conn, """
+            CREATE UNIQUE INDEX idx_tiles_upsert_test_unique
+                ON tiles_upsert_test (latitude, longitude, tile_zoom, tile_size_meters, source);
+            """);
+
+        var idFirst = Guid.NewGuid();
+        var idSecond = Guid.NewGuid();
+
+        await ExecAsync(conn, """
+            INSERT INTO tiles_upsert_test (id, latitude, longitude, tile_zoom, tile_size_meters, source, captured_at, file_path, updated_at)
+            VALUES (@id, 49.0, 39.0, 18, 100, 'uav', '2026-04-01 00:00:00', 'first.jpg', '2026-04-01 00:00:00');
+            """, ("id", idFirst));
+
+        // Act — second insert for the same cell+source uses the same UPSERT pattern as TileRepository.InsertAsync.
+        await ExecAsync(conn, """
+            INSERT INTO tiles_upsert_test (id, latitude, longitude, tile_zoom, tile_size_meters, source, captured_at, file_path, updated_at)
+            VALUES (@id, 49.0, 39.0, 18, 100, 'uav', '2026-05-01 00:00:00', 'second.jpg', '2026-05-01 00:00:00')
+            ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source)
+            DO UPDATE SET
+                file_path = EXCLUDED.file_path,
+                captured_at = EXCLUDED.captured_at,
+                updated_at = EXCLUDED.updated_at;
+            """, ("id", idSecond));
+
+        // Assert
+        long rowCount = 0;
+        DateTime capturedAt = DateTime.MinValue;
+        string? filePath = null;
+        await using (var cmd = new NpgsqlCommand("""
+            SELECT COUNT(*) OVER () AS total, captured_at, file_path
+            FROM tiles_upsert_test
+            WHERE latitude = 49.0 AND longitude = 39.0 AND tile_zoom = 18 AND tile_size_meters = 100 AND source = 'uav';
+            """, conn))
+        await using (var reader = await cmd.ExecuteReaderAsync())
+        {
+            if (!await reader.ReadAsync())
+            {
+                throw new Exception("AZ-484 AC-3: no rows after UPSERT — expected exactly one.");
+            }
+            rowCount = reader.GetInt64(0);
+            capturedAt = reader.GetDateTime(1);
+            filePath = reader.GetString(2);
+        }
+
+        if (rowCount != 1)
+        {
+            throw new Exception($"AZ-484 AC-3: expected exactly 1 uav row after UPSERT, got {rowCount}.");
+        }
+        if (capturedAt != new DateTime(2026, 5, 1, 0, 0, 0, DateTimeKind.Unspecified))
+        {
+            throw new Exception($"AZ-484 AC-3: captured_at not refreshed. Got {capturedAt:o}, expected 2026-05-01.");
+        }
+        if (filePath != "second.jpg")
+        {
+            throw new Exception($"AZ-484 AC-3: file_path not refreshed. Got '{filePath}', expected 'second.jpg'.");
+        }
+
+        Console.WriteLine("  ✓ Same-source UPSERT collapsed to 1 row with refreshed captured_at and file_path");
+    }
+
+    private static async Task CreateTempTilesTable(NpgsqlConnection conn, string tableName)
+    {
+        // Mirrors the post-migration-013 column shape relevant to AZ-484 (omits
+        // vestigial maps_version/version columns that AC-1..AC-3 do not exercise).
+        await ExecAsync(conn, $$"""
+            CREATE TEMP TABLE {{tableName}} (
+                id UUID PRIMARY KEY,
+                latitude DOUBLE PRECISION NOT NULL,
+                longitude DOUBLE PRECISION NOT NULL,
+                tile_zoom INT NOT NULL,
+                tile_size_meters DOUBLE PRECISION NOT NULL,
+                source VARCHAR(32) NOT NULL,
+                captured_at TIMESTAMP NOT NULL,
+                file_path VARCHAR(500) NOT NULL,
+                updated_at TIMESTAMP NOT NULL
+            );
+            """);
+    }
+
+    private static async Task<long> ScalarLongAsync(NpgsqlConnection conn, string sql)
+    {
+        await using var cmd = new NpgsqlCommand(sql, conn);
+        var result = await cmd.ExecuteScalarAsync();
+        return result switch
+        {
+            long l => l,
+            int i => i,
+            _ => throw new Exception($"Unexpected scalar type {result?.GetType()} for SQL: {sql}"),
+        };
    }

    private static async Task ExecAsync(NpgsqlConnection conn, string sql, params (string Name, object Value)[] parameters)
@@ -3,6 +3,7 @@ using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using SatelliteProvider.Common.Configs;
 using SatelliteProvider.Common.DTO;
+using SatelliteProvider.Common.Enums;
 using SatelliteProvider.Common.Interfaces;
 using SatelliteProvider.Common.Utils;
 using SatelliteProvider.DataAccess.Models;
@@ -157,6 +158,8 @@ public class TileService : ITileService
            MapsVersion = null,
            Version = null,
            FilePath = downloaded.FilePath,
+            Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+            CapturedAt = now,
            CreatedAt = now,
            UpdatedAt = now
        };
@@ -125,7 +125,8 @@ public class RepositoryRefactorTests
            "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"
        };
        var regionColumns = new[]
        {
@@ -6,6 +6,7 @@ using Microsoft.Extensions.Options;
 using Moq;
 using SatelliteProvider.Common.Configs;
 using SatelliteProvider.Common.DTO;
+using SatelliteProvider.Common.Enums;
 using SatelliteProvider.Common.Interfaces;
 using SatelliteProvider.DataAccess.Models;
 using SatelliteProvider.DataAccess.Repositories;
@@ -93,6 +94,8 @@ public class TileServiceTests
                FilePath = "tiles/18/0/0/cached.jpg",
                TileSizePixels = 256,
                ImageType = "jpg",
+                Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+                CapturedAt = DateTime.UtcNow,
            },
        };
        tileRepo
@@ -148,6 +151,8 @@ public class TileServiceTests
                FilePath = "tiles/18/0/0/cached_prior_year.jpg",
                TileSizePixels = 256,
                ImageType = "jpg",
+                Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+                CapturedAt = DateTime.UtcNow.AddYears(-1),
            },
        };
        tileRepo
@@ -271,6 +276,8 @@ public class TileServiceTests
            ImageType = "jpg",
            FilePath = "tiles/18/0/0/x.jpg",
            Version = 2026,
+            Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+            CapturedAt = DateTime.UtcNow,
        };
        var tileRepo = new Mock<ITileRepository>();
        tileRepo.Setup(r => r.GetByIdAsync(id)).ReturnsAsync(entity);
@@ -339,7 +346,16 @@ public class TileServiceTests
            var tileRepo = new Mock<ITileRepository>();
            tileRepo
                .Setup(r => r.GetByTileCoordinatesAsync(z, x, y))
-                .ReturnsAsync(new TileEntity { Id = Guid.NewGuid(), TileZoom = z, TileX = x, TileY = y, FilePath = tempPath });
+                .ReturnsAsync(new TileEntity
+                {
+                    Id = Guid.NewGuid(),
+                    TileZoom = z,
+                    TileX = x,
+                    TileY = y,
+                    FilePath = tempPath,
+                    Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+                    CapturedAt = DateTime.UtcNow,
+                });

            var service = BuildService(downloader, tileRepo);

@@ -444,6 +460,38 @@ public class TileServiceTests
        capturedToken.Should().Be(cts.Token, "AZ-371 AC-3: caller-supplied CT must reach the downloader");
    }

+    [Fact]
+    public void BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5()
+    {
+        // Arrange
+        var downloader = new Mock<ISatelliteDownloader>();
+        var tileRepo = new Mock<ITileRepository>();
+        TileEntity? captured = null;
+        tileRepo
+            .Setup(r => r.InsertAsync(It.IsAny<TileEntity>()))
+            .Callback<TileEntity>(e => captured = e)
+            .ReturnsAsync(Guid.NewGuid());
+        downloader
+            .Setup(d => d.DownloadSingleTileAsync(It.IsAny<double>(), It.IsAny<double>(), It.IsAny<int>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new DownloadedTileInfoV2(1, 2, 18, 47.46, 37.65, "tiles/18/1/2.jpg", 100.0));
+
+        var service = BuildService(downloader, tileRepo);
+        var before = DateTime.UtcNow;
+
+        // Act
+        _ = service.DownloadAndStoreSingleTileAsync(47.46, 37.65, 18).GetAwaiter().GetResult();
+
+        // Assert
+        var after = DateTime.UtcNow;
+        captured.Should().NotBeNull();
+        captured!.Source.Should().Be(TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+            "AZ-484 AC-5: the Google Maps download path stamps Source='google_maps' (contract wire value)");
+        captured.CapturedAt.Kind.Should().NotBe(DateTimeKind.Local,
+            "captured_at must be UTC per the v1.0.0 storage contract");
+        captured.CapturedAt.Should().BeOnOrAfter(before).And.BeOnOrBefore(after,
+            "AZ-484 AC-5: CapturedAt is the UtcNow at download time");
+    }
+
    [Fact]
    public async Task DownloadAndStoreSingleTileAsync_DownloaderThrows_DoesNotInsert_AZ311_AC2b()
    {
@@ -0,0 +1,81 @@
+using FluentAssertions;
+using SatelliteProvider.Common.Enums;
+
+namespace SatelliteProvider.Tests;
+
+public class TileSourceConverterTests
+{
+    [Theory]
+    [InlineData(TileSource.GoogleMaps, "google_maps")]
+    [InlineData(TileSource.Uav, "uav")]
+    public void ToWireValue_EmitsContractWireValue_AZ484(TileSource value, string expected)
+    {
+        // Act
+        var result = TileSourceConverter.ToWireValue(value);
+
+        // Assert
+        result.Should().Be(expected);
+    }
+
+    [Theory]
+    [InlineData("google_maps", TileSource.GoogleMaps)]
+    [InlineData("GOOGLE_MAPS", TileSource.GoogleMaps)]
+    [InlineData("uav", TileSource.Uav)]
+    [InlineData("UAV", TileSource.Uav)]
+    public void FromWireValue_AcceptsContractWireValue_AZ484(string raw, TileSource expected)
+    {
+        // Act
+        var result = TileSourceConverter.FromWireValue(raw);
+
+        // Assert
+        result.Should().Be(expected);
+    }
+
+    [Theory]
+    [InlineData(TileSource.GoogleMaps)]
+    [InlineData(TileSource.Uav)]
+    public void RoundTrip_PreservesValue_AZ484(TileSource value)
+    {
+        // Act
+        var roundTripped = TileSourceConverter.FromWireValue(TileSourceConverter.ToWireValue(value));
+
+        // Assert
+        roundTripped.Should().Be(value);
+    }
+
+    [Fact]
+    public void FromWireValue_UnknownString_ThrowsArgumentException_AZ484()
+    {
+        // Act
+        Action act = () => TileSourceConverter.FromWireValue("satar");
+
+        // Assert — Inv-1: unknown sources surface, not silently coerce (coderule.mdc: never suppress errors).
+        act.Should().Throw<ArgumentException>().WithMessage("*satar*");
+    }
+
+    [Fact]
+    public void FromWireValue_NullValue_ThrowsArgumentNullException_AZ484()
+    {
+        // Act
+        Action act = () => TileSourceConverter.FromWireValue(null!);
+
+        // Assert
+        act.Should().Throw<ArgumentNullException>();
+    }
+
+    [Theory]
+    [InlineData("google_maps", true)]
+    [InlineData("uav", true)]
+    [InlineData("GoogleMaps", false)]
+    [InlineData("satar", false)]
+    [InlineData("", false)]
+    [InlineData(null, false)]
+    public void IsValidWireValue_OnlyExactWireValuesPass_AZ484(string? raw, bool expected)
+    {
+        // Act
+        var result = TileSourceConverter.IsValidWireValue(raw);
+
+        // Assert
+        result.Should().Be(expected);
+    }
+}
@@ -20,20 +20,22 @@ The three Layer-3 service components are compile-time siblings: each only refere

 **Architectural principles** (inferred):
 - Single-instance deployment, no horizontal scaling requirements (`inferred-from: Channel-based queue, no distributed state`)
- Immutable tile storage with year-based versioning for cache invalidation (`inferred-from: version column + unique index`)
+- Append-by-source tile storage — multiple producers (Google Maps, UAV upload, future SatAR, …) can each persist a row per `(latitude, longitude, tile_zoom, tile_size_meters)` cell. Reads return the most-recent row across sources, ordered by `captured_at DESC` with deterministic `(updated_at DESC, id DESC)` tie-breaks. The single-row-per-cell-per-source invariant is enforced by the 5-column unique index `idx_tiles_unique_location_source` introduced in migration 013 (AZ-484). The `tiles.version` column is vestigial since AZ-357 dropped year-based cache invalidation in favour of cell-level overwrite. (`inferred-from: tiles table + AZ-484/AZ-357 migrations + tile-storage contract v1.0.0`)
 - Fire-and-forget async processing with status polling (`inferred-from: queue + background service + status endpoint`)
 - No authentication layer — designed as an internal/trusted network service (`inferred-from: no auth middleware in Program.cs`)

 **Planned features** (confirmed by user, currently stubs):
 - MGRS endpoint — tile access via Military Grid Reference System coordinates
- Upload endpoint — UAV nadir camera tile ingestion (Layer 2: orthogonal tiles uploaded post-flight, stored alongside Google Maps Layer 1; most recent layer returned on access)
+- Upload endpoint — UAV nadir camera tile ingestion. Writes a row with `source='uav'` for the captured cell; the storage layer accepts it alongside any existing Google Maps row, and reads return whichever has the highest `captured_at`. AZ-484 has built the multi-source storage; the upload endpoint itself (T2 — AZ-485) and any quality-gate logic remain to be implemented.
+
+The N-source storage contract is authoritative in `_docs/02_document/contracts/data-access/tile-storage.md` (v1.0.0). Anything that reads or writes `tiles` MUST follow that contract rather than re-deriving the rules from prose here.

 **Drift signals**:
 - `geofence_polygons` mentioned in AGENTS.md as a routes table column but does not exist in schema or entity — documentation drift

 ## 1. System Context

-**Problem being solved**: A GPS-denied UAV navigation service requires satellite imagery for positioning and route planning without GPS. This service pre-downloads Google Maps satellite tiles (Layer 1) for specified regions and routes, accepts UAV-captured nadir camera imagery uploaded post-flight (Layer 2), and serves the most recent tile layer on access. Tiles are stitched into composite images and packaged for offline use.
+**Problem being solved**: A GPS-denied UAV navigation service requires satellite imagery for positioning and route planning without GPS. This service pre-downloads satellite tiles from one or more imagery sources (currently Google Maps; future sources including UAV nadir camera upload and additional providers such as SatAR) for specified regions and routes, stores them alongside each other under a per-source storage key, and serves the most-recent row across sources on access. Tiles are stitched into composite images and packaged for offline use.

 **System boundaries**: The Satellite Provider is a self-contained backend service. It receives HTTP requests (region/route definitions), downloads tiles from Google Maps, stores them on disk and in PostgreSQL, and produces output files (images, CSVs, ZIPs).

@@ -41,8 +43,8 @@ The three Layer-3 service components are compile-time siblings: each only refere

 | System | Integration Type | Direction | Purpose |
 |--------|-----------------|-----------|---------|
-| Satellite imagery provider (e.g., Google Maps) | HTTPS (tile download) | Outbound | Layer 1 satellite imagery source (provider-agnostic via `ISatelliteDownloader`) |
-| GPS-Denied Service (UAV) | REST API | Inbound | Layer 2 nadir camera tile uploads post-flight |
+| Satellite imagery provider (e.g., Google Maps) | HTTPS (tile download) | Outbound | First implementation of the multi-source `tiles` storage; provider-agnostic via `ISatelliteDownloader`. Stamps `source='google_maps'` on every persisted row. |
+| GPS-Denied Service (UAV) | REST API | Inbound | Future producer of `source='uav'` rows via the upload endpoint (T2 — AZ-485). The storage layer (AZ-484) is already in place; the endpoint itself is still a stub. |
 | PostgreSQL | TCP (Npgsql) | Both | Tile metadata, region/route state |
 | File System | Local disk | Both | Tile image storage, output artifacts |
 | HTTP Clients | REST API | Inbound | Region/route requests, tile queries |
@@ -16,13 +16,14 @@
 | Method | Input | Output | Async | Error Types |
 |--------|-------|--------|-------|-------------|
 | `GetByIdAsync` | Guid | `TileEntity?` | Yes | NpgsqlException |
-| `GetByTileCoordinatesAsync` | zoom, x, y | `TileEntity?` | Yes | NpgsqlException |
-| `FindExistingTileAsync` | lat, lon, tileSizeM, zoom, version | `TileEntity?` | Yes | NpgsqlException |
-| `GetTilesByRegionAsync` | lat, lon, sizeM, zoom | `IEnumerable<TileEntity>` | Yes | NpgsqlException |
-| `InsertAsync` | `TileEntity` | Guid | Yes | NpgsqlException |
+| `GetByTileCoordinatesAsync` | zoom, x, y | `TileEntity?` (most-recent across sources, AZ-484) | Yes | NpgsqlException |
+| `GetTilesByRegionAsync` | lat, lon, sizeM, zoom | `IEnumerable<TileEntity>` (one row per cell via `DISTINCT ON`, AZ-484) | Yes | NpgsqlException |
+| `InsertAsync` | `TileEntity` | Guid (per-source UPSERT, AZ-484) | Yes | NpgsqlException |
 | `UpdateAsync` | `TileEntity` | int | Yes | NpgsqlException |
 | `DeleteAsync` | Guid | int | Yes | NpgsqlException |

+`FindExistingTileAsync` was removed by AZ-376 (replaced by direct cell lookups through `GetByTileCoordinatesAsync` + `GetTilesByRegionAsync`).
+
 ### Interface: IRegionRepository
 | Method | Input | Output | Async | Error Types |
 |--------|-------|--------|-------|-------------|
@@ -58,7 +59,7 @@
 |-------|-----------|----------|--------------|
 | GetByTileCoordinatesAsync (tile lookup) | Very High | Yes | `(tile_zoom, tile_x, tile_y)` |
 | GetTilesByRegionAsync (spatial) | High | Yes | `(latitude, longitude, tile_zoom)` |
-| InsertAsync (tile upsert) | High | Yes | Composite unique on `(lat, lon, zoom, size, version)` |
+| InsertAsync (tile per-source upsert) | High | Yes | Composite unique on `(lat, lon, tile_zoom, tile_size_meters, source)` (AZ-484: `idx_tiles_unique_location_source`) |
 | GetByStatusAsync (region polling) | Medium | No | `(status)` |
 | GetRoutesWithPendingMapsAsync | Low | No | `(request_maps, maps_ready)` |

@@ -88,7 +89,9 @@

 - Repository interfaces are defined in this project (not in Common), creating a dependency from Services to DataAccess
 - Column mapping uses SQL aliases (`tile_zoom as TileZoom`) rather than Dapper attribute mapping
- TileRepository.InsertAsync uses an upsert pattern; concurrent inserts of the same tile won't conflict
+- TileRepository.InsertAsync uses a per-source UPSERT pattern (AZ-484); two producers (e.g., `google_maps` + `uav`) coexist as separate rows for the same cell, while same-source re-inserts overwrite and refresh `captured_at`
+- `TileEntity.Source` is stored as a plain `string` (not the `TileSource` enum) due to Dapper issue #259 — see `_docs/LESSONS.md` L-001. Conversion happens via `SatelliteProvider.Common.Enums.TileSourceConverter`
+- The frozen v1.0.0 `tile-storage` contract (`_docs/02_document/contracts/data-access/`) is the authoritative spec for all `tiles` invariants enforced here
 - No soft-delete; `DeleteAsync` is a hard delete

 ## 8. Dependency Graph
@@ -8,7 +8,7 @@

 **csproj**: `SatelliteProvider.Services.TileDownloader/SatelliteProvider.Services.TileDownloader.csproj` (split out of the monolithic `SatelliteProvider.Services` project in epic AZ-309)

-**Upstream dependencies**: Common (DTOs, GeoUtils, configs, RateLimitException), DataAccess (TileEntity, ITileRepository)
+**Upstream dependencies**: Common (DTOs, Enums — `TileSource` + `TileSourceConverter` since AZ-484, GeoUtils, configs, RateLimitException), DataAccess (TileEntity, ITileRepository)

 **Downstream consumers**: RegionProcessing and WebApi — both via `ITileService` from Common (no compile-time `ProjectReference` from any consumer to this project's concrete types).

@@ -35,7 +35,7 @@
 | Data | Cache Type | TTL | Invalidation |
 |------|-----------|-----|-------------|
 | Tile bytes | In-memory (IMemoryCache, owned by TileService since AZ-310) | 1h absolute, 30min sliding | None (manual restart) |
-| Tile metadata | Database | Until year rollover | Version-based (current year) |
+| Tile metadata | Database | Append-by-source per cell (AZ-484); reads return most-recent across sources | Per-source UPSERT keyed on `(latitude, longitude, tile_zoom, tile_size_meters, source)` overwrites the existing same-source row and refreshes `captured_at` |
 | Active downloads | ConcurrentDictionary | Duration of download | Removed on completion |

 ## 5. Implementation Details
@@ -0,0 +1,117 @@
+# Contract: tile-storage
+
+**Component**: DataAccess
+**Producer task**: AZ-484 — `_docs/02_tasks/todo/AZ-484_multi_source_tile_storage.md`
+**Consumer tasks**: AZ-485 (planned T2 — UAV upload endpoint); future tasks adding additional sources (e.g., SatAR)
+**Version**: 1.0.0
+**Status**: frozen
+**Last Updated**: 2026-05-11
+
+## Purpose
+
+Defines how satellite imagery tiles are persisted in the `tiles` table when more than one acquisition source can write to the same geographic cell. Producers must agree on the source enum, the captured-at semantics, and the per-source UPSERT contract. Readers must use the documented selection rule and tolerate the multi-source row layout.
+
+## Shape
+
+### Schema (PostgreSQL `tiles` table — relevant columns only)
+
+```sql
+-- Pre-existing columns (unchanged)
+id                  UUID            PRIMARY KEY
+tile_zoom           INT             NOT NULL
+tile_x              INT             NOT NULL
+tile_y              INT             NOT NULL
+latitude            DOUBLE PRECISION NOT NULL
+longitude           DOUBLE PRECISION NOT NULL
+tile_size_meters    DOUBLE PRECISION NOT NULL
+tile_size_pixels    INT             NOT NULL
+image_type          VARCHAR(10)     NOT NULL
+file_path           VARCHAR(500)    NOT NULL
+created_at          TIMESTAMP       NOT NULL DEFAULT CURRENT_TIMESTAMP
+updated_at          TIMESTAMP       NOT NULL DEFAULT CURRENT_TIMESTAMP
+
+-- New in v1.0.0 (this contract)
+source              VARCHAR(32)     NOT NULL    -- enum-stored: 'google_maps' | 'uav'
+captured_at         TIMESTAMP       NOT NULL    -- UTC; producer-supplied semantics, see below
+
+-- Vestigial columns (preserved per coderule.mdc; readers MUST NOT depend on them)
+maps_version        VARCHAR(50)     NULL
+version             INT             NULL
+```
+
+### Field reference
+
+| Field | Type | Required | Description | Constraints |
+|-------|------|----------|-------------|-------------|
+| `source` | enum (`TileSource`) stored as `VARCHAR(32)` | yes | Producer of the tile | `'google_maps'` or `'uav'`. New values require a contract version bump. |
+| `captured_at` | `TIMESTAMP` UTC | yes | Producer-defined "moment the imagery represents" | For `google_maps`: `DateTime.UtcNow` at download time (provider does not expose original imagery date). For `uav`: the UAV capture timestamp supplied by the upload client. Must be UTC; non-UTC must be converted before write. |
+| `(latitude, longitude, tile_zoom, tile_size_meters, source)` | composite | yes | Per-source uniqueness | Enforced via `UNIQUE INDEX idx_tiles_unique_location_source`. |
+
+### Index
+
+```sql
+CREATE UNIQUE INDEX idx_tiles_unique_location_source
+    ON tiles (latitude, longitude, tile_zoom, tile_size_meters, source);
+```
+
+The previous 4-column unique index `(latitude, longitude, tile_zoom, tile_size_meters)` from migration 012 is dropped.
+
+### Producer write API
+
+| Operation | Repository method | Conflict semantics |
+|-----------|-------------------|--------------------|
+| Insert / replace same-source row for a cell | `ITileRepository.InsertAsync(TileEntity)` | `ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source) DO UPDATE SET file_path, tile_x, tile_y, captured_at, updated_at`. Producers MUST set `Source` and `CapturedAt`. |
+| Update by primary key | `ITileRepository.UpdateAsync(TileEntity)` | Updates by `id` only. Caller's responsibility not to violate the unique index. |
+| Delete by primary key | `ITileRepository.DeleteAsync(Guid)` | Removes a single row by `id`; no cascade. |
+
+### Consumer read API and selection rule
+
+| Operation | Repository method | Selection rule |
+|-----------|-------------------|----------------|
+| Read by `id` | `ITileRepository.GetByIdAsync(Guid)` | Returns the row identified by `id` (no source filter). |
+| Read most-recent for a cell by slippy coordinates | `ITileRepository.GetByTileCoordinatesAsync(zoom, x, y)` | Returns the row with the highest `(captured_at, updated_at, id)` tuple across all sources for that cell. At most one row. |
+| Read region | `ITileRepository.GetTilesByRegionAsync(lat, lon, sizeMeters, zoomLevel)` | Returns at most one row per `(latitude, longitude, tile_zoom, tile_size_meters)` group, selected by the same most-recent rule. |
+
+The selection rule is **most-recent across all sources** ordered by `captured_at DESC`, with `(updated_at DESC, id DESC)` as deterministic tie-breakers.
+
+## Invariants
+
+- **Inv-1**: Every row has a non-null `source` whose string value is a member of `TileSource`. Rows with unknown source values are a contract violation.
+- **Inv-2**: Every row has a non-null `captured_at` in UTC.
+- **Inv-3**: At most one row exists per `(latitude, longitude, tile_zoom, tile_size_meters, source)`.
+- **Inv-4**: For any cell with one or more rows, the row returned by `GetByTileCoordinatesAsync` and the per-cell row returned by `GetTilesByRegionAsync` are identical.
+- **Inv-5**: The `source` column value space is closed: only the snake_case wire values defined in `SatelliteProvider.Common.Enums.TileSourceConverter` (`"google_maps"`, `"uav"`) are valid. Adding a new producer requires a new `TileSource` enum member, a corresponding wire value in `TileSourceConverter`, AND a contract version bump (minor). Note: `TileEntity.Source` is stored as the wire string (not the C# enum) because Dapper's `TypeHandler<T>` for enum types is bypassed during read deserialization (Dapper issue #259); `TileSourceConverter.{ToWireValue,FromWireValue}` is the documented bridge.
+- **Inv-6**: `captured_at` semantics are producer-defined per the Field Reference table above; consumers MUST NOT reinterpret it (e.g., consumers MUST NOT assume `captured_at` from `google_maps` reflects original imagery date).
+
+## Non-Goals
+
+- **Not covered**: Per-source historical revision retention. Same-source uploads to the same cell overwrite the previous row by design — this is not a versioned table. Consumers wanting season selection or rollback must propose a v2 schema.
+- **Not covered**: Cross-source merging or compositing at read time. Reads return exactly one row per cell.
+- **Not covered**: Quality scoring, threshold gating, or any policy beyond the selection rule. Quality enforcement happens upstream of the write (T2).
+- **Not covered**: Backwards-compatible reads against the legacy 4-column unique index. Migration 013 is mandatory before any consumer of v1.0.0 runs.
+- **Not covered**: The vestigial `maps_version` and `version` columns. Consumers MUST NOT read them; producers MUST NOT write them in v1.0.0+.
+
+## Versioning Rules
+
+- **Patch (1.0.x)**: Documentation clarifications, additional invariants that do not change runtime behavior, expanded test cases.
+- **Minor (1.x.0)**: Adding a new `TileSource` enum member; adding optional columns that consumers may safely ignore; relaxing constraints in a backward-compatible way.
+- **Major (2.0.0)**: Removing or renaming a column; changing the unique index columns; changing the selection rule (e.g., adding source priority); changing `captured_at` from required to optional or vice versa; introducing per-source historical revisions.
+
+Each version bump requires updating the Change Log below and notifying every consumer listed in the header. If consumers' tasks have not yet been written, the producer task is responsible for surfacing the change to the user before merging.
+
+## Test Cases
+
+| Case | Input | Expected | Notes |
+|------|-------|----------|-------|
+| valid-google-only | Insert `source='google_maps' captured_at=T1` for a fresh cell | Single row returned by region read; `source='google_maps'`, `captured_at=T1`. | Baseline regression case. |
+| valid-multi-source | Insert `google_maps captured_at=T1`, then `uav captured_at=T2 > T1` for same cell | Both rows persisted; `GetByTileCoordinatesAsync` returns the `uav` row. | AC-1 + AC-2 of producer task. |
+| same-source-upsert | Insert `uav captured_at=T1`, then `uav captured_at=T2 > T1` for same cell | Exactly one `uav` row remains, with `captured_at=T2` and updated `file_path`. | AC-3 of producer task. |
+| time-tiebreak | Insert `google_maps captured_at=T`, then `uav captured_at=T` (identical) for same cell | Selection deterministic by `(updated_at DESC, id DESC)` tie-break; result must be reproducible across two test runs with the same seed. | Inv-4 enforcement. |
+| backfill-completeness | Migration 013 against a snapshot DB with N pre-existing rows | Post-migration row count is N; every row has `source='google_maps'` and `captured_at = created_at`. | AC-4 of producer task. |
+| invalid-source | Direct SQL insert with `source='satar'` (not in enum) | Repository read either rejects deserialization or raises a contract violation; behavior MUST surface the violation, not swallow it. | Inv-1 + `coderule.mdc` "never suppress errors silently". |
+
+## Change Log
+
+| Version | Date | Change | Author |
+|---------|------|--------|--------|
+| 1.0.0 | 2026-05-11 | Initial contract — multi-source schema (`source`, `captured_at`), 5-column unique key, most-recent-across-sources read rule. Produced by AZ-484. | autodev (Step 9) |
@@ -14,6 +14,8 @@ erDiagram
        varchar image_type
        varchar maps_version
        int version
+        varchar source
+        timestamp captured_at
        varchar file_path
        int tile_x
        int tile_y
@@ -96,19 +98,25 @@ Stores metadata for downloaded satellite imagery tiles. Each tile is a single im
 | tile_size_meters | DOUBLE PRECISION | NOT NULL | Ground coverage in meters |
 | tile_size_pixels | INT | NOT NULL | Image dimension in pixels |
 | image_type | VARCHAR(10) | NOT NULL | Image format (e.g., "jpg") |
-| maps_version | VARCHAR(50) | | Legacy free-form provider tag; post-AZ-373 new rows write NULL (column retained for forensics on pre-existing rows) |
-| version | INT | NOT NULL, DEFAULT 2025 | Year-based versioning for cache invalidation |
+| maps_version | VARCHAR(50) | | Legacy free-form provider tag; post-AZ-373 new rows write NULL. Vestigial post-AZ-484 (column retained for forensics on pre-existing rows; no longer part of any index) |
+| version | INT | NOT NULL, DEFAULT 2025 | Year-based versioning for cache invalidation. Vestigial post-AZ-484 — removed from the unique key by migration 012 (preparation for AZ-484); column retained nullable for backward compatibility |
+| source | VARCHAR(32) | NOT NULL, DEFAULT 'google_maps' | AZ-484: producer of the imagery (`'google_maps'`, `'uav'`). Closed value set — see `tile-storage` v1.0.0 contract Inv-5 and `Common.Enums.TileSourceConverter`. Backfilled to `'google_maps'` for all pre-AZ-484 rows by migration 013 |
+| captured_at | TIMESTAMP | NOT NULL | AZ-484: imagery acquisition timestamp (UTC). Drives most-recent-across-sources selection. Backfilled to `created_at` for pre-AZ-484 rows by migration 013 |
 | file_path | VARCHAR(500) | NOT NULL | Relative path to stored image |
 | tile_x | INT | NOT NULL | Tile X coordinate (Slippy Map) |
 | tile_y | INT | NOT NULL | Tile Y coordinate (Slippy Map) |
 | created_at | TIMESTAMP | NOT NULL, DEFAULT NOW | |
 | updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW | |

-**Indexes**:
- `idx_tiles_unique_location` UNIQUE (latitude, longitude, tile_zoom, tile_size_meters, version)
+**Indexes** (post-AZ-484):
+- `idx_tiles_unique_location_source` UNIQUE (latitude, longitude, tile_zoom, tile_size_meters, source) — created by migration 013; replaces the pre-AZ-484 4-col `idx_tiles_unique_location` (which itself superseded the legacy 5-col `(…, version)` index dropped by migration 012)
 - `idx_tiles_coordinates` (tile_zoom, tile_x, tile_y, version)
 - `idx_tiles_zoom` (tile_zoom)

+**Selection rule**: `GetByTileCoordinatesAsync` and `GetTilesByRegionAsync` return the most-recent row across sources for any `(latitude, longitude, tile_zoom, tile_size_meters)` cell. Tie-break: `captured_at DESC, updated_at DESC, id DESC`. Region read uses `DISTINCT ON` to enforce one-row-per-cell at the SQL layer.
+
+**UPSERT contract**: `INSERT … ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source) DO UPDATE` — same-source re-insert refreshes `file_path, tile_x, tile_y, captured_at, updated_at`. Two producers for the same cell coexist as separate rows.
+
 ### regions

 Tracks region download requests and their processing status.
@@ -215,3 +223,5 @@ Junction table linking routes to their generated region requests, with geofence
 | 009 | AddGeofencePolygonIndex | Polygon index tracking |
 | 010 | AddTilesZipToRoutes | ZIP generation fields |
 | 011 | AddTileCoordinates | Slippy map X/Y + rename zoom_level → tile_zoom |
+| 012 | DropTileVersionConstraint | Drops legacy 5-col `(…, version)` unique index; replaces with 4-col `idx_tiles_unique_location` (preparation for AZ-484) |
+| 013 | AddTileSourceAndCapturedAt | AZ-484: adds `source` (default `'google_maps'`) + `captured_at` columns; backfills both for pre-existing rows; replaces 4-col unique with 5-col `idx_tiles_unique_location_source`. Transactional; idempotent against partial replays |
@@ -11,8 +11,10 @@
 | Geofence | A rectangular geographic boundary (NW + SE corners) used to filter which route points receive map tile coverage | components/05_route_management/description.md |
 | Zoom Level | Google Maps tile resolution level (1–20); higher = more detail, smaller ground coverage per tile | modules/common_configs.md |
 | Stitch | Compositing multiple tiles into a single larger image with optional markers/borders | modules/services_region_service.md |
-| Layer 1 | Satellite imagery from external providers (provider-agnostic; first implementation: Google Maps) | user clarification |
-| Layer 2 | UAV-captured nadir camera imagery (orthogonal tiles uploaded post-flight) | user clarification |
+| 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`, …). Each cell may have at most one row per source; reads return the most-recent across sources. 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 (v1.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-sources read selection rule. | _docs/02_document/contracts/data-access/tile-storage.md (v1.0.0) |
 | Nadir Camera | Downward-facing camera on a UAV capturing ground imagery during flight | user clarification |
 | GPS-Denied Service | The consuming system: a UAV navigation service operating without GPS, using satellite/UAV imagery for positioning | user clarification |
 | Slippy Map Coordinates | Tile X/Y indices in the Web Mercator projection grid (standard for web map tile servers) | data_model.md |
@@ -27,6 +27,10 @@
  - `SatelliteProvider.Common/Configs/ProcessingConfig.cs`
  - `SatelliteProvider.Common/Configs/DatabaseConfig.cs`
  - `SatelliteProvider.Common/DTO/*.cs` (all DTOs)
+  - `SatelliteProvider.Common/Enums/RegionStatus.cs`
+  - `SatelliteProvider.Common/Enums/RoutePointType.cs`
+  - `SatelliteProvider.Common/Enums/TileSource.cs` (added by AZ-484; backed by the `tile-storage` v1.0.0 contract)
+  - `SatelliteProvider.Common/Enums/TileSourceConverter.cs` (added by AZ-484; converts `TileSource` enum to/from the snake_case wire string used by `TileEntity.Source`)
  - `SatelliteProvider.Common/Exceptions/RateLimitException.cs`
  - `SatelliteProvider.Common/Interfaces/*.cs` (all service interfaces)
  - `SatelliteProvider.Common/Utils/GeoUtils.cs`
@@ -53,7 +57,7 @@
 - **Internal**: (none — all repository types are public for DI registration)
 - **Owns**: `SatelliteProvider.DataAccess/**`
 - **ProjectReferences**: `SatelliteProvider.Common`
- **Imports from**: `SatelliteProvider.Common.Enums` (5 sites: `RegionRepository`, `IRegionRepository`, `Models/RegionEntity`, `Models/RoutePointEntity`, `TypeHandlers/EnumStringTypeHandler`); `SatelliteProvider.Common.Configs` (`MapConfig.DefaultTileSizePixels` in `TileRepository`); `SatelliteProvider.Common.Utils` (`GeoUtils.EarthEquatorialCircumferenceMeters`, `GeoUtils.MetersPerDegreeLatitude` in `TileRepository`).
+- **Imports from**: `SatelliteProvider.Common.Enums` (6 sites: `RegionRepository`, `IRegionRepository`, `Models/RegionEntity`, `Models/RoutePointEntity`, `TypeHandlers/EnumStringTypeHandler`, `Models/TileEntity` — references `TileSourceConverter.GoogleMapsWireValue` const for the AZ-484 default value); `SatelliteProvider.Common.Configs` (`MapConfig.DefaultTileSizePixels` in `TileRepository`); `SatelliteProvider.Common.Utils` (`GeoUtils.EarthEquatorialCircumferenceMeters`, `GeoUtils.MetersPerDegreeLatitude` in `TileRepository`).
 - **Consumed by**: TileDownloader, RegionProcessing, RouteManagement, WebApi

 ### Component: TileDownloader
@@ -135,6 +139,13 @@
 - **Purpose**: Stateless geospatial utility functions (coordinate math, distance, bearing)
 - **Consumed by**: TileDownloader, RegionProcessing, RouteManagement

+### Common/Enums
+
+- **Directory**: `SatelliteProvider.Common/Enums/`
+- **Purpose**: Domain enums shared across layers (`RegionStatus`, `RoutePointType`, `TileSource`) plus their explicit wire-value converters when persistence requires snake_case strings (`TileSourceConverter`). Converter classes belong here — not in DataAccess — because they encode a domain-level vocabulary that must be visible to every component.
+- **Consumed by**: DataAccess (entity defaults, type handler registration), TileDownloader (sets `TileEntity.Source` via `TileSourceConverter.ToWireValue`), Tests
+- **Important constraint**: Dapper's `SqlMapper.TypeHandler<TEnum>` is bypassed for enum reads (Dapper issue #259 — see `_docs/LESSONS.md` L-001). For any new enum that must round-trip through a database column, prefer the `string`-on-entity + `Enum`-at-API-boundary pattern with a converter class in this folder. Do NOT register a `TypeHandler<TEnum>` and assume it will be honored on reads.
+
 ## Allowed Dependencies (layering)

 | Layer | Components | May import from (compile-time ProjectReferences) |
@@ -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 (11 scripts)
+## Migrations (13 scripts)
 1. `001_CreateTilesTable.sql`
 2. `002_CreateRegionsTable.sql`
 3. `003_CreateIndexes.sql`
@@ -35,6 +35,8 @@ Runs DbUp-based SQL migrations against PostgreSQL on application startup. Ensure
 9. `009_AddGeofencePolygonIndex.sql`
 10. `010_AddTilesZipToRoutes.sql`
 11. `011_AddTileCoordinates.sql`
+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.

 ## Configuration
 Receives connection string directly as constructor parameter.
@@ -9,7 +9,9 @@ Database entity classes that map directly to PostgreSQL tables via Dapper. Prope
 Maps to `tiles` table.
 - `Id` (Guid), `TileZoom` (int), `TileX` (int), `TileY` (int)
 - `Latitude`, `Longitude` (double), `TileSizeMeters` (double), `TileSizePixels` (int)
- `ImageType` (string), `MapsVersion` (string?), `Version` (int)
+- `ImageType` (string), `MapsVersion` (string?), `Version` (int) — `MapsVersion`/`Version` are vestigial post-AZ-484 (kept nullable for backward compatibility; no longer part of the unique key)
+- `Source` (string) — AZ-484 producer wire value, defaults to `TileSourceConverter.GoogleMapsWireValue` (`"google_maps"`). Stored as plain string (not the `TileSource` enum) due to Dapper issue #259 — see `_docs/LESSONS.md` L-001. Convert via `SatelliteProvider.Common.Enums.TileSourceConverter.{ToWireValue,FromWireValue}`.
+- `CapturedAt` (DateTime, UTC) — AZ-484 imagery acquisition timestamp; drives the most-recent-across-sources selection.
 - `FilePath` (string), `CreatedAt`, `UpdatedAt` (DateTime)

 ### RegionEntity
@@ -7,26 +7,31 @@ Dapper-based repository for the `tiles` table. Handles CRUD operations and spati

 ### ITileRepository (interface)
 - `GetByIdAsync(Guid id) → Task<TileEntity?>`
- `GetByTileCoordinatesAsync(int tileZoom, int tileX, int tileY) → Task<TileEntity?>`: finds tile by slippy map coordinates, returns latest version
- `FindExistingTileAsync(double lat, double lon, double tileSizeMeters, int zoomLevel, int version) → Task<TileEntity?>`: fuzzy coordinate match (tolerance: 0.0001° lat/lon, 1m tile size)
- `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileEntity>>`: spatial bounding box query with expanded range to cover tile edges
- `InsertAsync(TileEntity tile) → Task<Guid>`: upsert — `ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, version) DO UPDATE` file_path, tile_x, tile_y, updated_at
- `UpdateAsync(TileEntity tile) → Task<int>`
+- `GetByTileCoordinatesAsync(int tileZoom, int tileX, int tileY) → Task<TileEntity?>`: finds the most-recent tile across all sources for the given slippy coordinates. Selection rule: `ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1` (AZ-484 v1.0.0 contract).
+- `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileEntity>>`: spatial bounding box query (expanded by 2 × tile size to cover edges); applies `DISTINCT ON (latitude, longitude, tile_zoom, tile_size_meters)` per AZ-484 to return at most one row per cell — the most-recent across sources — preserving the historical caller-facing order `latitude DESC, longitude ASC`.
+- `InsertAsync(TileEntity tile) → Task<Guid>`: per-source UPSERT — `ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source) DO UPDATE file_path, tile_x, tile_y, captured_at, updated_at` (AZ-484 5-column unique key).
+- `UpdateAsync(TileEntity tile) → Task<int>`: full row update by `id` including `source` and `captured_at`.
 - `DeleteAsync(Guid id) → Task<int>`

 ### TileRepository (implementation)
-Constructs a new `NpgsqlConnection` per method call (no connection pooling at the repository level; Npgsql pools connections internally).
+Constructs a new `NpgsqlConnection` per method call (no connection pooling at the repository level; Npgsql pools connections internally). Logs a `Slow GetTilesByRegionAsync` warning when the region query exceeds 500 ms.

 ## Internal Logic
- `GetTilesByRegionAsync` calculates a bounding box by expanding the requested region by 2 × tile size to ensure edge tiles are included. Uses meters-to-degrees approximation (111,000 m/degree latitude, adjusted for longitude).
- `InsertAsync` uses an upsert pattern to handle duplicate tile downloads gracefully.
- `GetByTileCoordinatesAsync` orders by `version DESC` and takes the latest.
+- `GetTilesByRegionAsync` calculates a bounding box by expanding the requested region by 2 × tile size to ensure edge tiles are included. Uses meters-to-degrees approximation via `GeoUtils` (post-AZ-377 — single source of truth for Earth constants).
+- `InsertAsync` uses a per-source UPSERT pattern keyed on the 5-column unique index `idx_tiles_unique_location_source` (created by migration 013). Two producers (e.g., `google_maps` + `uav`) coexist for the same cell; same-source re-insert refreshes `captured_at` and `updated_at`.
+- `GetByTileCoordinatesAsync` and `GetTilesByRegionAsync` apply the AZ-484 selection rule: most-recent across sources, deterministic tie-break on `(captured_at DESC, updated_at DESC, id DESC)`.
+- `TileEntity.Source` is a plain `string` storing the snake_case wire value (`'google_maps'` | `'uav'`); enum<->wire conversion happens via `SatelliteProvider.Common.Enums.TileSourceConverter`. This avoids Dapper issue #259 (TypeHandler<T> bypass for enum reads — see `_docs/LESSONS.md` L-001).
+- `FindExistingTileAsync` was removed by AZ-376 (see `_docs/04_refactoring/03-code-quality-refactoring/`).

 ## Dependencies
 - NuGet: `Dapper`, `Npgsql`
 - `SatelliteProvider.DataAccess.Models.TileEntity`
+- `SatelliteProvider.Common.GeoUtils` (Earth constants / meters-to-degrees)
 - `Microsoft.Extensions.Logging`

+## Contract
+Implements the frozen v1.0.0 contract `_docs/02_document/contracts/data-access/tile-storage.md`. Schema invariants Inv-1..Inv-5 are enforced here (UPSERT key, selection rule, source value space).
+
 ## Consumers
 - `TileService` — all read/write operations
 - `Program.cs` (ServeTile, GetTileByLatLon handlers) — `GetByTileCoordinatesAsync`, `InsertAsync`
@@ -9,9 +9,9 @@ Orchestrates tile downloading and persistence. Bridges the downloader (Google Ma

 ### TileService (implements ITileService)
 - `DownloadAndStoreTilesAsync(double lat, double lon, double sizeMeters, int zoomLevel, CancellationToken) → Task<List<TileMetadata>>`:
-  1. Queries existing tiles in the region from the repository (latest per `(latitude, longitude, zoom_level, tile_size_meters)` post-AZ-357)
+  1. Queries existing tiles in the region from the repository — most-recent across sources per `(latitude, longitude, tile_zoom, tile_size_meters)` (AZ-484 selection rule applied by `TileRepository.GetTilesByRegionAsync` via `DISTINCT ON`)
  2. Calls `ISatelliteDownloader.GetTilesWithMetadataAsync` with existing tiles to skip
-  3. Creates `TileEntity` for each newly downloaded tile and inserts via repository (upsert)
+  3. Creates `TileEntity` for each newly downloaded tile and inserts via repository (per-source UPSERT keyed on `(latitude, longitude, tile_zoom, tile_size_meters, source)`)
  4. Returns combined list of existing + new tile metadata
 - `GetTileAsync(Guid id) → Task<TileMetadata?>`: single tile lookup
 - `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileMetadata>>`: query tiles in a region
@@ -20,7 +20,8 @@ Orchestrates tile downloading and persistence. Bridges the downloader (Google Ma

 ## 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
- `MapToMetadata(TileEntity) → TileMetadata`: entity-to-DTO mapping (static helper); `MapsVersion` is no longer projected onto `TileMetadata` / `DownloadTileResponse`
+- AZ-484: `BuildTileEntity` stamps every newly downloaded row with `Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps)` (wire value `"google_maps"`) and `CapturedAt = DateTime.UtcNow`. The Google Maps download path is the only producer of `'google_maps'` rows; UAV ingestion (separate task) is the only producer of `'uav'` rows.
+- `MapToMetadata(TileEntity) → TileMetadata`: entity-to-DTO mapping (static helper); `MapsVersion` is no longer projected onto `TileMetadata` / `DownloadTileResponse`. `Source` and `CapturedAt` are not currently projected to the public DTO (no API contract change observable for AZ-484).
 - `TileSizePixels` sourced from `MapConfig.TileSizePixels` (default 256, post-AZ-371); image type fixed at `"jpg"`
 - `IMemoryCache` keyed by `(z, x, y)` with 1h absolute / 30min sliding expiration; populated on first hit and on downloader fallback

@@ -29,6 +30,7 @@ Orchestrates tile downloading and persistence. Bridges the downloader (Google Ma
 - `ITileRepository`
 - `IMemoryCache` (registered by `AddTileDownloader()`)
 - `SatelliteProvider.Common.DTO` — GeoPoint, TileMetadata, TileBytes
+- `SatelliteProvider.Common.Enums` — `TileSource`, `TileSourceConverter` (AZ-484)
 - `SatelliteProvider.DataAccess.Models` — TileEntity

 ## Consumers
@@ -11,6 +11,7 @@ Console application that runs end-to-end integration tests against a live API in
 - `BasicRouteTests` — route creation with intermediate points
 - `ComplexRouteTests` — routes with geofencing
 - `ExtendedRouteTests` — routes with `requestMaps: true` and tile ZIP creation
+- `MigrationTests` — direct PostgreSQL schema/index validation (no HTTP). AZ-484 cycle added: `NewUniqueConstraintIncludesSourceColumn_AZ484_AC1`, `BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4`, `MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1`, `MostRecentAcrossSourcesSelection_AZ484_AC2`, `SameSourceUpsertReplacesPreviousRow_AZ484_AC3` (latter four use temp tables to keep production data untouched).

 ### Supporting Classes
 - `Models.cs` — HTTP response DTOs for deserialization
@@ -0,0 +1,56 @@
+# Ripple Log — Cycle 1 (AZ-484)
+
+Generated by `document/SKILL.md` Task mode, Step 0.5 (Import-Graph Ripple).
+
+## Cycle scope
+- AZ-484 — Multi-source tile storage schema
+
+## Changed source identifiers (Step 0)
+- `SatelliteProvider.DataAccess.Migrations.013_AddTileSourceAndCapturedAt.sql` (DDL — not a C# import target)
+- `SatelliteProvider.Common.Enums.TileSource` (new)
+- `SatelliteProvider.Common.Enums.TileSourceConverter` (new)
+- `SatelliteProvider.DataAccess.Models.TileEntity` (added `Source`, `CapturedAt`; `Source` typed as `string` per L-001 workaround)
+- `SatelliteProvider.DataAccess.Repositories.TileRepository` (`ColumnList`, `GetByTileCoordinatesAsync`, `GetTilesByRegionAsync`, `InsertAsync`, `UpdateAsync`)
+- `SatelliteProvider.DataAccess.TypeHandlers.EnumStringTypeHandler` (registration list — net-zero after the L-001 pivot)
+- `SatelliteProvider.Services.TileDownloader.TileService.BuildTileEntity` (stamps `Source` + `CapturedAt`)
+
+## Reverse-dependency analysis (Step 0.5)
+Tooling: `Grep` over the C# tree for `using SatelliteProvider.Common.Enums`, `TileSource`, `TileEntity`, `ITileRepository` references.
+
+### Direct importers of the changed identifiers (already in the AZ-484 changeset)
+- `SatelliteProvider.DataAccess/Models/TileEntity.cs` — imports `Common.Enums` (uses `TileSourceConverter.GoogleMapsWireValue` const for the field default)
+- `SatelliteProvider.Services.TileDownloader/TileService.cs` — imports `Common.Enums` (calls `TileSourceConverter.ToWireValue(TileSource.GoogleMaps)`)
+- `SatelliteProvider.Tests/TileServiceTests.cs`, `TileSourceConverterTests.cs`, `RepositoryRefactorTests.cs`, `EnumStringTypeHandlerTests.cs`
+- `SatelliteProvider.IntegrationTests/MigrationTests.cs`
+
+All of the above were edited and their tests were re-run as part of AZ-484 itself; no documentation ripple is required for them.
+
+### Indirect importers requiring doc refresh
+The only consumers that touch `TileEntity` *as a type* (not as a column-aware contract) are:
+
+- `SatelliteProvider.Services.TileDownloader/GoogleMapsDownloaderV2.cs` — accepts `IEnumerable<TileEntity>` for the cache-skip parameter. **No doc ripple**: the downloader treats `TileEntity` as an opaque cache token; the new `Source` / `CapturedAt` columns are not accessed by the downloader.
+- `Program.cs` (WebApi) — calls `ITileRepository.GetByTileCoordinatesAsync` and `InsertAsync`. **No doc ripple to `api_program.md`**: the endpoint contract did not change (response DTO `TileMetadata` is unaffected by AZ-484; `Source` and `CapturedAt` are not currently projected to the public API).
+- `RegionService` / `RegionProcessingService` — call `ITileService` methods, not `ITileRepository` directly. **No doc ripple**: the `ITileService` method signatures are unchanged; the most-recent-across-sources read rule is fully enforced inside `TileRepository` and is invisible to region/route consumers.
+
+### Refreshed-anyway docs (within the immediate scope)
+The following docs were refreshed during this Update Docs step because they describe the storage layer or its direct boundary, and AZ-484 changed the substantive content even though import graphs alone would not have triggered them:
+
+- `_docs/02_document/modules/dataaccess_tile_repository.md` — interface signatures (`FindExistingTileAsync` removal, AZ-484 selection rule, 5-col UPSERT key); changed by direct edit (in scope)
+- `_docs/02_document/modules/dataaccess_models.md` — `TileEntity` field list (`Source` as `string` + L-001 note, `CapturedAt`); changed by direct edit (in scope)
+- `_docs/02_document/modules/dataaccess_migrator.md` — migration count 11 → 13, entries for 012 and 013; changed by direct edit (in scope)
+- `_docs/02_document/modules/services_tile_service.md` — `DownloadAndStoreTilesAsync` selection rule + UPSERT semantics, `BuildTileEntity` source stamping, `Common.Enums` dependency; changed by direct edit (in scope)
+- `_docs/02_document/modules/tests_integration.md` — `MigrationTests` AZ-484 method list; changed by direct edit (in scope)
+- `_docs/02_document/components/03_tile_downloader/description.md` — upstream dependency list (`Common.Enums`), tile-metadata caching strategy now reads "append-by-source per cell"; changed by direct edit (in scope)
+- `_docs/02_document/components/02_data_access/description.md` — `ITileRepository` table (FindExistingTileAsync row removed; AZ-484 annotations on Get/Insert), Queries table (UPSERT key now 5-col + source), Caveats (UPSERT semantics, L-001 note, contract pointer); changed by direct edit (in scope)
+- `_docs/02_document/data_model.md` — `tiles` table columns (`source`, `captured_at` added; `version` / `maps_version` flagged vestigial), Indexes section (replaced unique key entry, added selection-rule + UPSERT contract notes), Migration History (012, 013); changed by direct edit (in scope)
+- `_docs/02_document/module-layout.md` — Common Public API list (`TileSourceConverter` already present; updated DataAccess "Imports from" 5 → 6 sites including `Models/TileEntity`; new Common/Enums subsection with the L-001 guidance); changed by direct edit (in scope)
+- `_docs/02_document/architecture.md`, `_docs/02_document/glossary.md`, `_docs/02_document/contracts/data-access/tile-storage.md` — already updated during the AZ-484 implementation batch (see batch_25_cycle1_report.md)
+
+## Heuristic mode flag
+Not used. Direct `Grep` over the C# tree was sufficient — no parser failure, no fall-back to directory-proximity scanning.
+
+## Summary
+- Direct importers in AZ-484 changeset: 7 (already updated as part of the implementation)
+- Indirect importers requiring NO doc ripple: 3 (GoogleMapsDownloaderV2, Program.cs, RegionService chain)
+- In-scope refresh-anyway docs: 10 (listed above)
+- Out-of-scope ripple-only docs: 0
@@ -41,3 +41,12 @@
 **Load**: 1 request
 **Expected**: Route created (with interpolation) within 5s
 **Pass criterion**: HTTP 200 response within 5000ms; totalPoints > 20
+
+## PT-07: GetTilesByRegionAsync Latency Post-AZ-484 (multi-source baseline)
+
+**Trigger**: TileRepository.GetTilesByRegionAsync exercised via POST /api/satellite/request (200m region, zoom 18) against a tiles table seeded with the pre-AZ-484 data shape (single-source rows backfilled to source='google_maps').
+**Load**: 1 request, repeated 20 times to get a stable distribution.
+**Expected**: 95th-percentile latency must not regress more than 10% vs the pre-AZ-484 baseline measured against PT-03 / PT-04. The new 5-column unique index `idx_tiles_unique_location_source` covers the same `(latitude, longitude, tile_zoom, tile_size_meters)` filter columns as the pre-AZ-484 4-column index, so no regression is expected.
+**Pass criterion**: p95(GetTilesByRegionAsync) ≤ 1.10 × pre-AZ-484 p95 baseline.
+**Source**: AZ-484 NFR (Performance) — `_docs/02_tasks/done/AZ-484_multi_source_tile_storage.md` § Non-Functional Requirements.
+**Note**: This NFR is recorded for tracking. Active enforcement (running PT-07 against a real workload and comparing) is deferred to autodev Step 15 (Performance Test) when a baseline run is available. Until then, the integration test `MostRecentAcrossSourcesSelection_AZ484_AC2` provides correctness coverage for the new query shape.
@@ -26,6 +26,13 @@
 | S1 | Migrations run on startup | RS-02 | ✓ |
 | S2 | Queue rejects when full | RS-04, RL-02 | ✓ |
 | S3 | Failed regions marked failed | RS-03 | ✓ |
+| AZ-484 AC-1 | Schema accepts source + captured_at; multi-source rows coexist under 5-col unique index | `MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1`, `NewUniqueConstraintIncludesSourceColumn_AZ484_AC1` (integration) | ✓ |
+| AZ-484 AC-2 | Read returns most-recent across sources | `MostRecentAcrossSourcesSelection_AZ484_AC2` (integration) | ✓ |
+| AZ-484 AC-3 | Same-source UPSERT collapses to one row with refreshed captured_at | `SameSourceUpsertReplacesPreviousRow_AZ484_AC3` (integration) | ✓ |
+| AZ-484 AC-4 | Migration 013 backfill leaves no orphans (count preserved, source='google_maps', captured_at=created_at) | `BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4` (integration) | ✓ |
+| AZ-484 AC-5 | Google Maps download path stamps Source='google_maps' (wire) + CapturedAt UTC | `BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5` (unit) | ✓ |
+| AZ-484 AC-6 | Existing region/route flows unchanged post-T1 (200 unit + smoke baseline preserved) | Full unit suite (213 tests) + integration smoke scenarios BT-01..BT-12 | ✓ |
+| AZ-484 AC-7 | Vision + contract docs amended (architecture.md, glossary.md, module-layout.md, tile-storage.md frozen v1.0.0) | doc-state AC; verified by `monorepo-document` reviews | ✓ |

 ## Restrictions → Test Mapping

@@ -40,6 +47,13 @@
 | Max ZIP 50 MB | RL-01 | ✓ |
 | No authentication | SEC-01 through SEC-04 (all requests accepted without auth) | ✓ |

+## NFRs → Test Mapping
+
+| NFR | Source | Tests | Coverage |
+|-----|--------|-------|----------|
+| AZ-484 Perf — `GetTilesByRegionAsync` p95 ≤ 1.10 × pre-AZ-484 baseline | AZ-484 task spec § Non-Functional Requirements | PT-07 (recorded; active perf comparison deferred to Step 15) | ◐ recorded |
+| AZ-484 Compatibility — no public HTTP response field added/removed; vestigial `maps_version`/`version` columns preserved (nullable) | AZ-484 task spec § Non-Functional Requirements | Existing integration suite (no API contract change observable); BT-01 / region status responses verify response shape | ✓ |
+
 ## Coverage Summary

 | Category | Total Tests | ACs Covered | Restrictions Covered |
@@ -50,4 +64,5 @@
 | Resilience | 6 | 4 | 3 |
 | Security | 4 | — | 1 |
 | Resource Limits | 4 | 3 | 4 |
-| **Total** | **37** | **22/22 (100%)** | **8/8 (100%)** |
+| Cycle 1 — AZ-484 (integration + unit) | 6 | 7/7 | — |
+| **Total** | **43** | **29/29 (100%)** | **8/8 (100%)** |
@@ -58,6 +58,13 @@ Roadmap: `_docs/04_refactoring/03-code-quality-refactoring/analysis/refactoring_
 | AZ-380 | C27 | Delete CalculatePolygonDiagonalDistance | 4 | — | 1 | Done (In Testing) |
 | AZ-372 | C19 | dotnet format + NetAnalyzers + Coverlet | 4 | — | 3 | Done (In Testing) |

+### Step 9 cycle 1 — New Task: Multi-source tile storage + UAV upload (AZ-483 epic)
+
+| Task | Title | Depends On | Points | Status |
+|------|-------|-----------|--------|--------|
+| AZ-484 | Multi-source tile storage schema (source + captured_at) | — | 5 | To Do |
+| AZ-485 (planned) | UAV upload endpoint + quality gate | AZ-484, contract `tile-storage.md` v1.0.0 | ~5 | Not yet created (deferred to a future Step 9 loop) |
+
 ## Execution Order

 ### Step 6
@@ -77,11 +84,16 @@ Phase 2 (Correctness): AZ-359 → AZ-357 → AZ-362 (AZ-362 needs AZ-353)
 Phase 3 (Structural cleanup): AZ-366 → AZ-377 → AZ-368 → AZ-367 → AZ-369 → AZ-365 → AZ-364 (folds AZ-360) — AZ-377 needs AZ-371
 Phase 4 (Typing/config/tooling/polish): AZ-371 → AZ-370 → AZ-373 → AZ-374 → AZ-375 → AZ-376 → AZ-378 → AZ-379 → AZ-380 → AZ-372

+### Step 9 cycle 1 (Multi-source tile storage epic AZ-483)
+1. AZ-484 — Multi-source tile storage schema (foundational)
+2. AZ-485 (planned) — UAV upload endpoint + quality gate (consumer of AZ-484's contract)
+
 ## Total Effort

 Step 6: 6 tasks, 17 story points
 Step 8 (02-coupling-refactoring): 6 tasks, 17 story points
 Step 8 (03-code-quality-refactoring): 27 tasks, ~66 story points
+Step 9 cycle 1: 1 task created (AZ-484, 5 pts); 1 deferred (AZ-485)

 ## Coverage Verification

@@ -0,0 +1,157 @@
+# Multi-source tile storage schema (source + captured_at)
+
+**Task**: AZ-484_multi_source_tile_storage
+**Name**: Multi-source tile storage schema
+**Description**: Extend `tiles` to allow one row per `(cell, source)`; add `captured_at`; update repository read selection to most-recent-across-sources; backfill existing rows; publish v1.0.0 storage contract; amend Architecture Vision.
+**Complexity**: 5 points
+**Dependencies**: None (builds on the post-AZ-357 / C06 schema state)
+**Component**: DataAccess + Common (new TileSource enum) + TileDownloader (BuildTileEntity)
+**Tracker**: AZ-484
+**Epic**: AZ-483
+
+## Problem
+
+The `tiles` table currently allows exactly one row per `(latitude, longitude, tile_zoom, tile_size_meters)` (post-AZ-357 / C06). The Architecture Vision in `architecture.md` already commits to a Layer 1 + Layer 2 model where Google Maps and UAV imagery coexist per cell, but the schema cannot represent two producers for the same geographic cell. T1 (this task) closes that gap so that T2 (UAV upload, AZ-485) has a place to write its rows. Without T1, T2 would have to scaffold a temporary single-source path and immediately throw it away.
+
+## Outcome
+
+- `tiles` table accepts multiple rows per `(latitude, longitude, tile_zoom, tile_size_meters)` distinguished by `source` (enum) and stamps `captured_at` (UTC timestamp).
+- Repository read paths return the most-recent row per cell across sources, deterministically (`captured_at DESC`, then `updated_at DESC`, then `id DESC`).
+- All existing rows are backfilled to `source='google_maps'`, `captured_at=created_at` — zero orphan rows.
+- `architecture.md` § Architecture Vision reflects the N-source model rather than only Layer 1 + Layer 2.
+- `_docs/02_document/contracts/data-access/tile-storage.md` v1.0.0 published and referenced from this task and from the future T2 task (AZ-485).
+- Region/route flows behave identically to today (Google Maps remains the only producer until T2 lands).
+- All 200 unit + 5 smoke tests pass.
+
+## Scope
+
+### Included
+
+- Migration `SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql`:
+  - Add `source VARCHAR(32) NOT NULL` and `captured_at TIMESTAMP NOT NULL` columns.
+  - Backfill existing rows: `source='google_maps'`, `captured_at = created_at`.
+  - Drop existing unique index `idx_tiles_unique_location` (4-column).
+  - Create new unique index `idx_tiles_unique_location_source` over `(latitude, longitude, tile_zoom, tile_size_meters, source)`.
+  - Wrap the entire migration in a single transaction.
+- New enum `SatelliteProvider.Common.Enums.TileSource { GoogleMaps, Uav }`, string-stored via the existing `EnumStringTypeHandler` pattern (matches AZ-370 status / point-type enums).
+- `SatelliteProvider.DataAccess.Models.TileEntity`: add `Source` (TileSource) and `CapturedAt` (DateTime) fields.
+- `SatelliteProvider.DataAccess.Repositories.TileRepository`:
+  - Update `ColumnList` constant to include `source` and `captured_at`.
+  - Update `GetByIdAsync`, `GetByTileCoordinatesAsync`, `GetTilesByRegionAsync` to apply the most-recent-across-sources selection rule.
+  - Update `InsertAsync` to UPSERT on the new 5-column key, also setting `captured_at` and (re)setting `source` from the entity.
+  - Update `UpdateAsync` SET clause to include `source` and `captured_at`.
+- `SatelliteProvider.Services.TileDownloader.TileService.BuildTileEntity`: set `Source = TileSource.GoogleMaps` and `CapturedAt = DateTime.UtcNow`.
+- Update existing tests that construct `TileEntity` or mock `ITileRepository` to populate the new fields (12+ sites: `TileServiceTests` ~10, `RegionServiceTests` ~3, `RepositoryRefactorTests` ColumnList assertion, `InfrastructureTests` 2 mocks).
+- New unit tests:
+  - Repository read selection: insert two rows for the same cell with different sources and `captured_at`, assert the latest one is returned by both `GetByTileCoordinatesAsync` and `GetTilesByRegionAsync`.
+  - Repository same-source UPSERT: re-insert a `uav` row, assert single row remains with updated `captured_at` and `file_path`.
+  - Migration backfill: pre/post row count + per-row `source='google_maps'` + `captured_at = created_at` invariants.
+- Documentation:
+  - `_docs/02_document/architecture.md` § Architecture Vision amendment (Layer 1 + Layer 2 → N sources, append-by-source, latest-across-sources on read).
+  - `_docs/02_document/glossary.md`: add `Tile Source` and `Captured At` rows; update `Layer 1` / `Layer 2` rows to acknowledge the N-source generalization.
+  - `_docs/02_document/module-layout.md` § Component: Common Public API: list `SatelliteProvider.Common/Enums/TileSource.cs`.
+- Contract file `_docs/02_document/contracts/data-access/tile-storage.md` v1.0.0 (already drafted; flip Status from `draft` to `frozen` upon implementation completion).
+
+### Excluded
+
+- `POST /api/satellite/upload` implementation — handled by T2 (AZ-485).
+- Any quality assessment, threshold gating, or rejection logic — T2.
+- Multi-revision / season-based / per-source historical retention — out of scope by design (the quality gate, not history retention, is the cache-freshness mechanism).
+- Dropping vestigial `version` or `maps_version` columns (per `coderule.mdc` — column drops require explicit confirmation; user has confirmed leaving them).
+- Public HTTP response shape changes (no new fields on `DownloadTileResponse` or any other response).
+
+## Acceptance Criteria
+
+**AC-1: Schema accepts source + captured_at**
+Given the migration has run
+When a tile row is inserted with `source='uav'` for a cell that already has a `source='google_maps'` row
+Then both rows are stored and the unique index does not reject the insert.
+
+**AC-2: Read returns most-recent across sources**
+Given a cell has two rows: one `source='google_maps' captured_at=T1` and one `source='uav' captured_at=T2 > T1`
+When `GetByTileCoordinatesAsync` (or region read) is called for that cell
+Then the row with `captured_at=T2` is returned (single row).
+
+**AC-3: Same-source UPSERT**
+Given a cell has a row `source='uav' captured_at=T1`
+When another insert arrives for `source='uav' captured_at=T2 > T1`
+Then exactly one `source='uav'` row remains for that cell, with `captured_at=T2` and `file_path` updated.
+
+**AC-4: Backfill leaves no orphans**
+Given the database had N rows in `tiles` before migration
+When `013_AddTileSourceAndCapturedAt.sql` runs
+Then the table still has N rows, every row has `source='google_maps'`, and every row has `captured_at = created_at`.
+
+**AC-5: Google Maps download path uses new fields**
+Given a tile is downloaded via `TileService.DownloadAndStoreSingleTileAsync` or `DownloadAndStoreTilesAsync`
+When the row is inspected
+Then `source = 'google_maps'` and `captured_at` is the UTC timestamp at download time.
+
+**AC-6: Existing flows unchanged**
+Given the post-T1 build
+When `scripts/run-tests.sh --smoke` runs
+Then all 200 unit + 5 smoke scenarios pass with no functional change to region/route output (CSV row count, stitched-image presence, ZIP size, status transitions all match pre-T1 baseline).
+
+**AC-7: Vision and contract documents updated**
+Given T1 is complete
+When `architecture.md`, `glossary.md`, `module-layout.md`, and `_docs/02_document/contracts/data-access/tile-storage.md` are inspected
+Then the multi-source model is documented in all four, the contract is v1.0.0 with Status `frozen`, and the contract is referenced from this task spec.
+
+## Non-Functional Requirements
+
+**Performance**
+- `GetTilesByRegionAsync` 95th-percentile latency must not regress more than 10% vs the pre-T1 baseline. The new 5-column unique index covers the existing read filter, so no regression is expected; the slow-query log threshold remains 500 ms (`TileRepository.SlowQueryThresholdMs`).
+
+**Compatibility**
+- No public HTTP response field added or removed.
+- Existing `tiles.maps_version` and `tiles.version` columns remain present and nullable; no consumer reads them in v1.0.0 of the storage contract.
+
+**Reliability**
+- Migration MUST be transactional. A failure mid-migration MUST leave the table in its pre-migration state — never with a missing unique index or partially backfilled rows.
+
+## Unit Tests
+
+| AC Ref | What to Test | Required Outcome |
+|--------|--------------|------------------|
+| AC-1 | `TileRepository.InsertAsync` with two distinct `source` values for the same cell | Both rows inserted; `GetTilesByRegionAsync` returns at most one of them per the selection rule. |
+| AC-2 | `TileRepository.GetByTileCoordinatesAsync` against a cell with rows of distinct sources | Row with the highest `captured_at` returned; tie-break by `updated_at DESC` then `id DESC` is deterministic across runs. |
+| AC-3 | `TileRepository.InsertAsync` re-inserting a `uav` row for the same cell | Exactly one `uav` row remains with the new `captured_at` and `file_path`. |
+| AC-5 | `TileService.BuildTileEntity` (via `DownloadAndStoreSingleTileAsync` test) | Resulting entity has `Source = TileSource.GoogleMaps` and `CapturedAt` close to `DateTime.UtcNow`. |
+| AC-6 | All existing `TileServiceTests`, `RegionServiceTests`, `RepositoryRefactorTests`, `InfrastructureTests` after mock fixups | Suite remains green; `RepositoryRefactorTests` ColumnList assertion updated to include the new columns. |
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|--------------------------|--------------|-------------------|-----------------|
+| AC-4 | Apply migration 013 to a fixture DB seeded with the migration-012 schema and ≥3 sample rows | Run the migration | Pre-count = post-count, every row has `source='google_maps'`, every row has `captured_at = created_at`, the new unique index exists, the old one does not | Reliability |
+| AC-6 | Pre-T1 baseline output captured for `BT-01` (single tile), `BT-03` (200m region), `BT-08` (route+ZIP) | Re-run `scripts/run-tests.sh --smoke` after T1 | All 5 smoke scenarios PASS; `./ready/` outputs match the pre-T1 byte-shape (file existence, row counts in CSV, ZIP size within ±1%) | Performance, Compatibility |
+
+## Constraints
+
+- DB column drops require explicit user confirmation (`coderule.mdc`); none performed in this task. The vestigial `version` and `maps_version` columns remain.
+- No rename of any existing column.
+- Migration must be transactional and must fail loudly on any inconsistency rather than silently corrupt state — per `coderule.mdc` "never suppress errors silently".
+- Cross-component calls continue to flow through `ITileRepository` and `ITileService` interfaces in `Common`; no new compile-time `ProjectReference` between Layer-3 sibling components (the AZ-309 invariant).
+
+## Risks & Mitigation
+
+**Risk 1: Migration fails partway against a non-empty production-like DB**
+- *Risk*: A failure mid-migration leaves the table without its unique index or with partially backfilled rows.
+- *Mitigation*: Wrap the entire migration in `BEGIN; ... COMMIT;`. Verify on a Docker-Compose dev DB with seed data before applying anywhere else. Add a dedicated unit/integration test that runs the migration against a fixture DB and asserts the post-state.
+
+**Risk 2: Read-path selection rule mis-interacts with existing region cache hit logic**
+- *Risk*: `TileService.DownloadAndStoreTilesAsync` does an existence check via `GetTilesByRegionAsync` and then re-downloads missing tiles. If the most-recent-per-cell rule changes which row is returned, region processing may double-download or skip cached tiles.
+- *Mitigation*: AC-6 explicitly asserts pre/post equivalence. Smoke-test scenario `BT-03` (200m region) exercises the cache-hit path; pre/post tile-row counts must match.
+
+**Risk 3: TileEntity field additions break test mock construction broadly**
+- *Risk*: ~12 test sites construct `TileEntity` directly or set up `Mock<ITileRepository>`. A missed site leaves a default-zero `CapturedAt` that may fail ORDER BY tie-breaks non-deterministically.
+- *Mitigation*: Pre-implementation audit of all `new TileEntity` and `Mock<ITileRepository>` sites; the implementer must list them in the batch report. The `RepositoryRefactorTests` ColumnList assertion catches incomplete repository updates.
+
+**Risk 4: `EnumStringTypeHandler` registration drift**
+- *Risk*: The existing handler may need an extra registration for `TileSource` to round-trip through Dapper. AZ-370 added similar enums; the registration site must be checked.
+- *Mitigation*: Verify and extend the handler registration as part of this task (not a separate ticket).
+
+## Contract
+
+This task produces the contract at `_docs/02_document/contracts/data-access/tile-storage.md` (v1.0.0).
+Consumers (T2 — UAV upload endpoint AZ-485, future SatAR provider, etc.) MUST read that file — not this task spec — to discover the storage interface.
@@ -0,0 +1,89 @@
+# Batch Report
+
+**Batch**: 25 (cycle 1)
+**Tasks**: AZ-484 (Multi-source tile storage schema)
+**Date**: 2026-05-11
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| AZ-484 Multi-source tile storage schema | Done | 11 source files + 4 docs | new + updated unit tests; new integration migration tests (handed off to Run Tests) | 7/7 ACs covered | None |
+
+## AC Test Coverage: All covered (7/7)
+
+| AC | Test |
+|----|------|
+| AC-1 | `MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1`, `NewUniqueConstraintIncludesSourceColumn_AZ484_AC1` (integration) |
+| AC-2 | `MostRecentAcrossSourcesSelection_AZ484_AC2` (integration) |
+| AC-3 | `SameSourceUpsertReplacesPreviousRow_AZ484_AC3` (integration) |
+| AC-4 | `BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4` (integration TEMP-table simulation of migration UPDATE) |
+| AC-5 | `BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5` (unit) |
+| AC-6 | Existing 200 unit + 5 smoke pass unchanged — verified via the full suite run (handed off to autodev Step 11) |
+| AC-7 | Documents amended in this batch; contract `tile-storage.md` Status flipped from `draft` to `frozen` |
+
+## Code Review Verdict: PASS
+Report: `_docs/03_implementation/reviews/batch_25_cycle1_review.md`
+
+## Auto-Fix Attempts: 0
+## Stuck Agents: None
+
+## Pre-Implementation Audit (Risk 3 mitigation)
+
+`new TileEntity` and `Mock<ITileRepository>` sites surveyed before edits:
+
+| Site | Action |
+|------|--------|
+| `SatelliteProvider.Services.TileDownloader/TileService.cs:146` (`BuildTileEntity`) | Updated — sets `Source = TileSource.GoogleMaps`, `CapturedAt = DateTime.UtcNow` |
+| `SatelliteProvider.Tests/TileServiceTests.cs:84` (BT-02 cached) | Updated — explicit `Source` + `CapturedAt = DateTime.UtcNow` |
+| `SatelliteProvider.Tests/TileServiceTests.cs:139` (AZ-357 prior-year) | Updated — explicit `Source` + `CapturedAt = DateTime.UtcNow.AddYears(-1)` to mirror the prior-year semantic |
+| `SatelliteProvider.Tests/TileServiceTests.cs:264` (`GetTileAsync` known-id) | Updated — explicit `Source` + `CapturedAt` |
+| `SatelliteProvider.Tests/TileServiceTests.cs:342` (AZ-310 RepoHit) | Updated — inline `TileEntity` initializer expanded with explicit fields |
+| `SatelliteProvider.Tests/InfrastructureTests.cs:23, :65` (mock-only, no `TileEntity` construction) | No change required — mocks return defaults that no test asserts on |
+| `SatelliteProvider.Tests/RepositoryRefactorTests.cs` ColumnList assertion | Updated — added `source` + `captured_at as CapturedAt` to expected column list |
+
+**Note on the task spec's "RegionServiceTests ~3 sites" estimate**: that count was inaccurate — `SatelliteProvider.Tests/RegionServiceTests.cs` does not reference `TileEntity` or `ITileRepository`. No edit was needed there.
+
+## Files Changed
+
+### New
+- `SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql`
+- `SatelliteProvider.Common/Enums/TileSource.cs`
+- `SatelliteProvider.DataAccess/TypeHandlers/TileSourceTypeHandler.cs`
+
+### Modified — production code
+- `SatelliteProvider.DataAccess/Models/TileEntity.cs` (added `Source`, `CapturedAt`)
+- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` (ColumnList + 4 SQL methods)
+- `SatelliteProvider.DataAccess/TypeHandlers/EnumStringTypeHandler.cs` (registered `TileSourceTypeHandler`)
+- `SatelliteProvider.Services.TileDownloader/TileService.cs` (`BuildTileEntity` stamps Source + CapturedAt)
+
+### Modified — tests
+- `SatelliteProvider.Tests/TileServiceTests.cs`
+- `SatelliteProvider.Tests/RepositoryRefactorTests.cs`
+- `SatelliteProvider.Tests/EnumStringTypeHandlerTests.cs`
+- `SatelliteProvider.IntegrationTests/MigrationTests.cs`
+
+### Modified — documentation
+- `_docs/02_document/architecture.md` (Architecture Vision + System Context)
+- `_docs/02_document/glossary.md` (Tile Source, Captured At, Layer 1/2 disambiguation)
+- `_docs/02_document/module-layout.md` (Common Public API listing)
+- `_docs/02_document/contracts/data-access/tile-storage.md` (Status: `draft` → `frozen`)
+
+## Design Notes
+
+**Wire-format mismatch motivating `TileSourceTypeHandler`.** The generic `EnumStringTypeHandler<T>` emits `value.ToString().ToLowerInvariant()`, which would produce `'googlemaps'` for `TileSource.GoogleMaps`. The v1.0.0 contract requires `'google_maps'`. A dedicated `TileSourceTypeHandler` keeps the snake_case mapping localized and avoids leaking case-conversion logic into the generic handler. Round-trip and unknown-value tests are colocated with the existing handler test class.
+
+**`DISTINCT ON` for region reads.** PostgreSQL's `DISTINCT ON` was chosen over a self-join or window function because the new 5-column unique index can serve as the prefix sort, keeping the change a near-zero overhead for a region query. The outer `ORDER BY latitude DESC, longitude ASC, updated_at DESC` preserves the pre-AZ-484 caller-facing row order.
+
+**Migration transactionality (Risk 1 mitigation).** The migration is wrapped in `BEGIN ... COMMIT`. The IntegrationTests TEMP-table tests cover the backfill semantics; the live-schema test verifies the final post-013 index shape (and that the legacy 4-column index was actually dropped).
+
+## Next Batch
+None — AZ-484 is the only task in this cycle. AZ-485 (UAV upload + quality gate) is deferred to a future Step 9 loop and is recorded in `_docs/02_tasks/_dependencies_table.md` under Step 9 cycle 1.
+
+## Handoff to Step 11 (Run Tests)
+
+Per `/implement` skill Step 16: the autodev next step is Run Tests, so this batch does NOT execute the full suite locally. The `test-run` skill owns the full-suite gate. Pre-conditions required:
+- `dotnet test SatelliteProvider.Tests` should pass (200 unit + new AZ-484 unit tests).
+- `scripts/run-tests.sh --smoke` should pass with the live API + Postgres (5 smoke + new AZ-484 integration migration tests).
+
+If `test-run` reports a failure in either suite, surface it; the existing infrastructure tests for AZ-357 dedupe semantics and the new AZ-484 selection / UPSERT tests are the highest-signal checks.
@@ -0,0 +1,79 @@
+# Deploy Report — Cycle 1 (AZ-484)
+
+**Date**: 2026-05-11
+**Cycle**: 1
+**Scope**: Multi-source tile storage schema (AZ-484) and supporting documentation/security artifacts.
+
+## What is shipping
+
+### Code changes (already committed)
+
+| Commit | Subject |
+|--------|---------|
+| `5ba58b6` | `[AZ-484] [AZ-483] Add task spec + tile-storage v1.0.0 contract draft` |
+| `687d6bd` | `[AZ-484] Multi-source tile storage: source + captured_at` |
+| `e9d6db0` | `[AZ-484] Fix multi-source tile reads: drop Dapper enum handler` |
+
+### Database migration
+
+- **`013_AddTileSourceAndCapturedAt.sql`** — runs on first startup of the new image. Transactional (`BEGIN; … COMMIT;`), idempotent against partial replays. Adds `source` (VARCHAR(32) NOT NULL DEFAULT `'google_maps'`) + `captured_at` (TIMESTAMP NOT NULL); backfills both for every pre-existing row; replaces 4-col `idx_tiles_unique_location` with 5-col `idx_tiles_unique_location_source`.
+
+### Documentation, test-spec, audit artifacts (uncommitted in working tree, scoped to this deploy commit below)
+
+- `_docs/02_document/data_model.md`, `module-layout.md`, 6 module / component docs — Step 13 (Update Docs).
+- `_docs/02_document/ripple_log_cycle1.md` — Step 13 ripple analysis.
+- `_docs/02_document/tests/performance-tests.md`, `traceability-matrix.md` — Step 12 (Test-Spec Sync) — added AZ-484 ACs and PT-07.
+- `_docs/05_security/` (5 files) — Step 14 (Security Audit) — verdict PASS_WITH_WARNINGS.
+- `_docs/06_metrics/perf_2026-05-11_cycle1_az484.md` — Step 15 (Performance Test) — all scenarios Unverified, non-blocking.
+- `_docs/_process_leftovers/2026-05-11_perf-pt07-harness.md` — deferred PT-07 harness work.
+- `_docs/_autodev_state.md` — autodev pointer.
+
+## Pre-deploy checks (recap)
+
+| Gate | Outcome |
+|------|---------|
+| Step 11 — Run Tests | All unit + integration tests pass against the post-AZ-484 build (213 unit + 5 new AZ-484 integration). |
+| Step 14 — Security Audit | **PASS_WITH_WARNINGS** — 0 Critical, 0 High, 5 Medium, 5 Low. AZ-484 itself added zero new findings. Top hardening items recorded in `_docs/05_security/security_report.md`. |
+| Step 15 — Performance Test | All scenarios `Unverified` (PT-07 harness deferred to next cycle). Non-blocking per test-run perf-mode rules. |
+| `dotnet format whitespace --verify-no-changes` | Passed (part of `scripts/run-tests.sh`). |
+
+## Migration safety
+
+- **Idempotent**: re-running migration 013 against an already-migrated database is a no-op (`ADD COLUMN IF NOT EXISTS`, `DROP INDEX IF EXISTS`, `CREATE UNIQUE INDEX IF NOT EXISTS` patterns).
+- **Backwards compatible**: pre-AZ-484 application code that reads `tiles` still works — `source` defaults to `'google_maps'`, `captured_at` is backfilled to `created_at`. Vestigial columns `version` / `maps_version` are preserved nullable.
+- **No data loss**: the only DDL change is dropping `idx_tiles_unique_location` (replaced by `idx_tiles_unique_location_source`); rows are not touched except by the backfill UPDATE.
+- **Lock duration**: ALTER TABLE on a tiles table with O(100K-1M) rows takes a few seconds for ADD COLUMN (metadata-only in PG 11+) and a few seconds for the UPDATE backfill on existing data. Acceptable for a maintenance window-free deploy assuming current row counts (`_docs/02_document/data_model.md` storage estimate: 100K-1M tiles).
+
+## Rollback plan
+
+The migration is forward-only by DbUp design (no automatic down migrations). In the unlikely event AZ-484 needs to be reverted in production:
+
+1. Re-deploy the previous image (`registry.../azaion/satellite-provider:<previous-tag>`). The pre-AZ-484 code reads `*` from `tiles` and ignores the new columns — it will function correctly against the migrated schema.
+2. The 5-col `idx_tiles_unique_location_source` is a strict superset of the pre-AZ-484 4-col index for the only producer pre-AZ-484 sees (`source = 'google_maps'`); pre-AZ-484 UPSERT on `(lat, lon, tile_zoom, tile_size_meters, version)` would fail conflict detection against the new index — so do **not** roll the schema back, only roll the application back. The schema is forward-compatible with the old code.
+3. If a true schema rollback is ever needed, write a follow-up migration `014_RevertAz484.sql` rather than editing `013` in place.
+
+## Post-deploy verification
+
+After the new image is deployed and migrations have run:
+
+1. Hit `GET /api/satellite/region/{any-existing-region-id}` — confirm 200 + status JSON (smoke test that the `tiles` reads still parse with the new entity shape).
+2. Hit `GET /api/satellite/tiles/latlon?Latitude=...&Longitude=...&ZoomLevel=18` for a known cell — confirm 200 + tile bytes.
+3. Run a single `psql` query: `SELECT count(*) FROM tiles WHERE source IS NULL OR captured_at IS NULL;` — expected `0`.
+4. Tail Serilog logs for `Slow GetTilesByRegionAsync` warnings (>500ms) for the first hour. A spike here would be the earliest signal of a perf regression vs. the (unmeasured) pre-AZ-484 baseline.
+
+## CI/CD path
+
+The project's `.woodpecker/02-build-push.yml` builds and pushes the image on push to `dev`, `stage`, `main`. The `dev` branch is the standard target per `.cursor/rules/git-workflow.mdc`. Pushing the new commit to `origin/dev` triggers the pipeline; no manual deploy steps are needed beyond the `git push`.
+
+**Push policy**: per `git-workflow.mdc`, the autodev does NOT push without explicit user request. The next user prompt will offer the push as an explicit option.
+
+## Security caveats carried into this deploy
+
+The Security Audit (Step 14) flagged 5 Medium findings that should be tracked as separate hardening tasks before public-network exposure but do NOT block this internal deploy:
+
+- **S1+S2+I5** — Postgres default credentials in `appsettings.json` + `docker-compose.yml`; `.env` not in `.dockerignore`.
+- **S4** — Google Maps API key needs rotation + `.env.example`.
+- **D1** — Bump `Microsoft.AspNetCore.OpenApi 8.0.21 → 8.0.25` (CVE-2026-26130 SignalR DoS — not reachable in this app).
+- **I3** — Wire `Microsoft.AspNetCore.RateLimiting`.
+
+None of these are AZ-484 regressions; they are pre-existing items that today's audit surfaced. Tracking them as separate Jira tickets is recommended but not enforced by this gate.
@@ -0,0 +1,45 @@
+# Product Implementation Completeness Gate — cycle 1
+
+**Date**: 2026-05-11
+**Cycle**: 1
+**Tasks evaluated**: AZ-484
+**Verdict**: PASS
+
+## Per-Task Classification
+
+### AZ-484 — Multi-source tile storage schema (source + captured_at) — **PASS**
+
+**Evidence checked**:
+
+| Promise from spec | Production evidence |
+|--------------------|---------------------|
+| Migration 013 transactional, with column adds, backfill, index swap | `SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql` (BEGIN/COMMIT, ALTER ADD COLUMN, UPDATE backfill, ALTER SET NOT NULL, DROP INDEX, CREATE UNIQUE INDEX) |
+| `TileSource` enum in Common.Enums | `SatelliteProvider.Common/Enums/TileSource.cs` (`{ GoogleMaps, Uav }`) |
+| `TileEntity` exposes `Source` + `CapturedAt` | `SatelliteProvider.DataAccess/Models/TileEntity.cs` |
+| Repository read selection is most-recent across sources, deterministic | `TileRepository.GetByTileCoordinatesAsync` + `GetTilesByRegionAsync` (DISTINCT ON with `(captured_at DESC, updated_at DESC, id DESC)` tie-break) |
+| Per-source UPSERT semantics on insert | `TileRepository.InsertAsync` (`ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source) DO UPDATE`) |
+| `UpdateAsync` includes the new fields | `TileRepository.UpdateAsync` SET clause |
+| Google Maps download path stamps `Source` + `CapturedAt` | `TileService.BuildTileEntity` |
+| Snake_case wire format for `TileSource` | `SatelliteProvider.Common.Enums.TileSourceConverter` (`ToWireValue` / `FromWireValue` / `IsValidWireValue`). `TileEntity.Source` stores the wire string directly because Dapper bypasses `TypeHandler<T>` for enum reads — see `_docs/LESSONS.md` L-001. |
+| Architecture Vision amended | `_docs/02_document/architecture.md` (Architecture Vision principles + System Context) |
+| Glossary amended | `_docs/02_document/glossary.md` (`Tile Source`, `Captured At`; Layer 1 / Layer 2 disambiguation) |
+| Module-layout amended | `_docs/02_document/module-layout.md` (Common Public API list) |
+| Contract `tile-storage.md` v1.0.0 frozen | `_docs/02_document/contracts/data-access/tile-storage.md` Status: `frozen` |
+
+**Unresolved markers** (`TODO`, `placeholder`, `NotImplemented`, etc.) under owned files (`SatelliteProvider.Common/Enums/TileSource.cs`, `SatelliteProvider.Common/Enums/TileSourceConverter.cs`, `SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql`, `SatelliteProvider.DataAccess/Models/TileEntity.cs`, `SatelliteProvider.DataAccess/Repositories/TileRepository.cs`, `SatelliteProvider.Services.TileDownloader/TileService.cs`): none found.
+
+**Named runtime dependencies**: AZ-484 introduces no new external dependency. It uses the existing Dapper / Npgsql / DbUp stack already integrated. `TileSourceConverter` is a pure helper with no DI registration required. The deleted `TileSourceTypeHandler` registration was removed from `DapperEnumTypeHandlers.RegisterAll` after the Dapper-enum-bypass discovery (see L-001).
+
+**Internal vs external**: every promised capability is an internal product capability and is implemented in production code. No promise is blocked on an external prerequisite. The deferred AZ-485 (UAV upload endpoint) is explicitly out of scope for this task.
+
+**Tests exercise real implementation path**:
+- Unit: `BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5` calls the real `TileService.DownloadAndStoreSingleTileAsync` path.
+- Integration (migration): the AC-1..AC-4 tests run against the real Postgres container, asserting the live schema (5-column unique index, dropped legacy 4-column index) and the SQL semantics of the repository methods.
+
+## Cycle Verdict
+
+All product tasks (1/1) classified PASS. Proceeding to Final Test Run handoff (autodev Step 11).
+
+## Remediation Tasks Created
+
+None.
@@ -0,0 +1,69 @@
+# Implementation Report — multi-source tile storage (cycle 1)
+
+**Date**: 2026-05-11
+**Cycle**: 1
+**Tasks completed**: AZ-484
+**Batches**: 25
+**Code review verdict**: PASS (`_docs/03_implementation/reviews/batch_25_cycle1_review.md`)
+**Completeness gate verdict**: PASS (`_docs/03_implementation/implementation_completeness_cycle1_report.md`)
+**Test handoff**: yes — full-suite execution deferred to autodev Step 11 (Run Tests)
+
+## Summary
+
+AZ-484 introduces multi-source tile storage to the `tiles` table and freezes the v1.0.0 `tile-storage` contract that future producers (T2 — UAV upload AZ-485, future SatAR provider, etc.) will consume. The implementation:
+
+- Migration `013_AddTileSourceAndCapturedAt.sql` adds `source` (`VARCHAR(32) NOT NULL`) and `captured_at` (`TIMESTAMP NOT NULL`) to `tiles`, backfills existing rows to `(source='google_maps', captured_at=created_at)`, drops the legacy 4-column unique index `idx_tiles_unique_location`, and creates the new 5-column unique index `idx_tiles_unique_location_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.
+- `SatelliteProvider.Common.Enums.TileSource { GoogleMaps, Uav }` is the public producer enum. Because the v1.0.0 contract requires snake_case wire values (`google_maps`, `uav`) AND because Dapper 2.1.35 silently bypasses `SqlMapper.TypeHandler<TEnum>` during read deserialization (Dapper issue #259 — see `_docs/LESSONS.md` L-001), `TileEntity.Source` is stored as a plain `string` (the wire value) and `SatelliteProvider.Common.Enums.TileSourceConverter` provides the boundary conversion (`ToWireValue`, `FromWireValue`, `IsValidWireValue`). The first attempt at this batch used a `TileSourceTypeHandler : SqlMapper.TypeHandler<TileSource>` registered via `DapperEnumTypeHandlers.RegisterAll`; that worked for writes but failed at integration-test time on reads, leading to the converter pivot.
+- `TileEntity` exposes `Source` (string, default `TileSourceConverter.GoogleMapsWireValue`) and `CapturedAt` properties.
+- `TileRepository` is updated end-to-end:
+  - `ColumnList` includes `source` and `captured_at as CapturedAt`.
+  - `GetByTileCoordinatesAsync` returns the most-recent row across sources via `ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1`.
+  - `GetTilesByRegionAsync` uses `DISTINCT ON (latitude, longitude, tile_zoom, tile_size_meters)` with the same tie-break tuple, then restores the pre-AZ-484 caller-facing row order.
+  - `InsertAsync` UPSERTs on the 5-column conflict key and refreshes `captured_at` and `updated_at` on conflict.
+  - `UpdateAsync` writes `source` and `captured_at` alongside the other columns.
+- `TileService.BuildTileEntity` stamps `Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps)` (i.e., the wire string `"google_maps"`) and `CapturedAt = DateTime.UtcNow` so every Google-Maps-originated row carries the contract-required fields.
+- Documentation:
+  - `_docs/02_document/architecture.md` Architecture Vision and System Context describe the N-source model, append-by-source storage, and most-recent-across-sources reads, and point at the contract as authoritative.
+  - `_docs/02_document/glossary.md` adds `Tile Source` and `Captured At`, and disambiguates the historic `Layer 1` / `Layer 2` terms against the new `TileSource` enum.
+  - `_docs/02_document/module-layout.md` lists `SatelliteProvider.Common/Enums/TileSource.cs` and `TileSourceConverter.cs` (and the previously implicit `RegionStatus.cs`, `RoutePointType.cs`) under the Common Public API surface.
+  - `_docs/02_document/contracts/data-access/tile-storage.md` is now Status `frozen` at v1.0.0.
+
+## AC Coverage (7/7 — see batch report for the full table)
+
+| AC | Coverage |
+|----|----------|
+| AC-1 | Integration: `MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1`, `NewUniqueConstraintIncludesSourceColumn_AZ484_AC1` |
+| AC-2 | Integration: `MostRecentAcrossSourcesSelection_AZ484_AC2` |
+| AC-3 | Integration: `SameSourceUpsertReplacesPreviousRow_AZ484_AC3` |
+| AC-4 | Integration TEMP-table simulation: `BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4` |
+| AC-5 | Unit: `BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5` |
+| AC-6 | Existing 200 unit + 5 smoke pass unchanged — verified by Step 11 |
+| AC-7 | Doc-state AC; verified inline (architecture, glossary, module-layout, contract status) |
+
+## Risk Mitigation
+
+| Risk | Mitigation in this cycle |
+|------|--------------------------|
+| 1 — Migration fails partway against a non-empty production-like DB | Migration wrapped in `BEGIN ... COMMIT`. AC-4 TEMP-table simulation asserts the backfill semantics; AC-1 live-schema test asserts the post-migration index shape and that the legacy index was dropped. |
+| 2 — Read-path selection rule breaks region cache hit logic | AC-6 covers this via the existing smoke tests (BT-03 200 m region exercises the cache-hit path). Pre/post tile-row counts must match. Handed off to Step 11. |
+| 3 — TileEntity field additions break test mock construction | Pre-implementation audit listed every `new TileEntity` site (5 locations across `TileServiceTests.cs` and `TileService.cs`); each was updated explicitly with `Source = TileSource.GoogleMaps` and a sensible `CapturedAt`. The task spec's "RegionServiceTests ~3 sites" estimate was inaccurate (those tests don't reference `TileEntity` / `ITileRepository`); no edits were needed there. |
+| 4 — `EnumStringTypeHandler` registration drift | `TileSourceTypeHandler` is registered in `DapperEnumTypeHandlers.RegisterAll` alongside the existing handlers. New unit test `RegisterAll_RegistersTileSourceHandler_AZ484` asserts the registration is in place and emits the contract wire value. |
+
+## Deviations from Spec
+
+- **Wire-format handler**: the spec says "string-stored via the existing `EnumStringTypeHandler` pattern". The existing pattern emits `ToString().ToLowerInvariant()`, which would produce `'googlemaps'` (contract requires `'google_maps'`). The first attempt fixed this by introducing `TileSourceTypeHandler : SqlMapper.TypeHandler<TileSource>`. Integration tests revealed that **Dapper bypasses TypeHandler<T> for enum types during read deserialization** (Dapper issue #259, see `_docs/LESSONS.md` L-001). Final implementation pivots to: store `TileEntity.Source` as a `string` (the wire value), and provide `TileSourceConverter` for explicit enum<->wire conversion at the service-layer boundary. Producers still author with the `TileSource` enum and convert at the entity boundary; consumers compare against the wire-value constants on `TileSourceConverter`. The contract (`tile-storage.md` Inv-5) was amended to document this storage choice.
+- **Test site count**: the spec estimated ~12 sites needing mock fixups including ~3 in `RegionServiceTests`. Actual count: 5 sites in `TileServiceTests.cs` and 1 ColumnList assertion in `RepositoryRefactorTests.cs`. `RegionServiceTests.cs` and `InfrastructureTests.cs` did not require `TileEntity` field updates (the latter only constructs mocks, not entities).
+
+## Step 11 — Run Tests result
+
+Full suite (`scripts/run-tests.sh --full`) passed on attempt 3 (logs in `_docs/03_implementation/test_runs/`):
+
+- **Attempt 1** (committed `687d6bd`): integration test failed — `column "updated_at" does not exist`. Root cause: outer `ORDER BY ... updated_at DESC` in `GetTilesByRegionAsync` referenced a column that the inner `DISTINCT ON` subquery had aliased to `UpdatedAt` (Postgres folded to `updatedat`). Fix: removed the unnecessary outer tiebreak — `DISTINCT ON` already guarantees one row per `(latitude, longitude, ...)` so the third sort term was unreachable.
+- **Attempt 2**: integration test failed — `Error parsing column 12 (source=google_maps - String)`. Root cause: Dapper bypasses `TypeHandler<T>` for enum reads (Dapper issue #259); `RegionStatus`/`RoutePointType` accidentally worked because their wire values match member names case-insensitively, but `TileSource.GoogleMaps` ↔ `"google_maps"` does not. Fix: pivoted to string-stored `TileEntity.Source` + `TileSourceConverter`; deleted the bypassed `TileSourceTypeHandler`; added `TileSourceConverterTests`.
+- **Attempt 3**: PASSED. 213 unit tests + full integration suite (multi-source migration, AC-1..AC-4, security SEC-01..SEC-04, AZ-356 stubs, AZ-362 idempotency, AZ-357 migration 012, all route/region happy paths). Wall clock ≈ 5m40s.
+
+The two pivots are recorded in `_docs/LESSONS.md` (L-001 covers the Dapper bypass).
+
+## Deferred work
+
+- AZ-485 — UAV upload endpoint + quality gate. Tracked in `_docs/02_tasks/_dependencies_table.md` § Step 9 cycle 1 as planned, depending on AZ-484 and the now-frozen v1.0.0 contract.
@@ -0,0 +1,68 @@
+# Code Review Report
+
+**Batch**: 25 (cycle 1)
+**Tasks**: AZ-484 (Multi-source tile storage schema)
+**Date**: 2026-05-11
+**Verdict**: PASS
+
+## Findings
+
+None.
+
+## Phase Summary
+
+### Phase 1 — Context
+Read AZ-484 task spec, `_docs/02_document/contracts/data-access/tile-storage.md` v1.0.0, the existing `_docs/02_document/architecture.md` Architecture Vision section, and the existing `module-layout.md` per-component map. Mapped the 15 changed files to AZ-484 (single-task batch).
+
+### Phase 2 — Spec Compliance
+Walked every AC against code:
+
+| AC | Promise | Validating test |
+|----|---------|-----------------|
+| AC-1 | Per-source coexistence on the same cell | `MultiSourceInsertCoexistsUnderNewIndex_AZ484_AC1` (TEMP), `NewUniqueConstraintIncludesSourceColumn_AZ484_AC1` (live schema) |
+| AC-2 | Most-recent across sources on read | `MostRecentAcrossSourcesSelection_AZ484_AC2` |
+| AC-3 | Same-source UPSERT collapses to one row | `SameSourceUpsertReplacesPreviousRow_AZ484_AC3` |
+| AC-4 | Migration backfill leaves no orphans | `BackfillUpdateAssignsGoogleMapsAndCapturedAt_AZ484_AC4` (TEMP simulation of the migration UPDATE) |
+| AC-5 | Google Maps path stamps Source + CapturedAt | `BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5` |
+| AC-6 | Existing 200 unit + 5 smoke pass unchanged | Verified via the full suite run (handed off to autodev Step 11) |
+| AC-7 | Architecture / glossary / module-layout / contract updated | Documents amended in this batch; contract Status flipped from `draft` to `frozen` |
+
+**Contract verification** against `_docs/02_document/contracts/data-access/tile-storage.md` v1.0.0:
+- Shape: `source VARCHAR(32) NOT NULL`, `captured_at TIMESTAMP NOT NULL` — matches migration 013.
+- 5-column unique index `idx_tiles_unique_location_source` — created by migration 013.
+- Producer write API: `InsertAsync` UPSERT on the 5-column key, refreshes `captured_at`/`updated_at`/`file_path`/`tile_x`/`tile_y` — matches.
+- Consumer read API: `GetByTileCoordinatesAsync` LIMIT 1 ordered by `(captured_at DESC, updated_at DESC, id DESC)`; `GetTilesByRegionAsync` uses `DISTINCT ON (latitude, longitude, tile_zoom, tile_size_meters)` with the same tie-break tuple — matches.
+- Wire format: `TileSource.GoogleMaps → 'google_maps'`, `TileSource.Uav → 'uav'` enforced by `TileSourceTypeHandler` (necessary because the generic `EnumStringTypeHandler<T>` would emit `'googlemaps'`).
+- Inv-1 / Inv-2 / Inv-5: `NOT NULL` columns + handler `Parse` throws `DataException` on unknown values (no silent coercion per `coderule.mdc`).
+- Inv-3: 5-column unique index.
+- Inv-4: identical tie-break tuple in `GetByTileCoordinatesAsync` and the inner `DISTINCT ON` of `GetTilesByRegionAsync` guarantees identical winner per cell.
+
+### Phase 3 — Code Quality
+- SRP: `TileSourceTypeHandler` is a focused persistence concern (the bidirectional wire-format mapping); kept separate from the generic `EnumStringTypeHandler<T>` instead of leaking snake_case logic into the generic.
+- Comments: only added where intent is non-obvious (snake_case wire-format requirement, new ORDER BY tuple, per-source UPSERT semantics, transactional migration rationale). No narration-of-code comments.
+- Tests: every new test uses Arrange / Act / Assert.
+- DRY: `CreateTempTilesTable` factored out across the three TEMP-table integration tests.
+
+### Phase 4 — Security Quick-Scan
+- All SQL parameters bound (`@Source`, `@CapturedAt`, etc.) — no string interpolation of caller-supplied values.
+- Migration backfill literal is `'google_maps'`, not user input.
+- No new secrets or credentials introduced.
+
+### Phase 5 — Performance Scan
+- The new `DISTINCT ON` in `GetTilesByRegionAsync` can use `idx_tiles_unique_location_source` for the partition prefix; no extra round-trip; slow-query log threshold preserved.
+- No N+1 patterns introduced.
+
+### Phase 6 — Cross-Task Consistency
+Single-task batch. Internal consistency: enum members, wire values, migration backfill literal, and test assertions all agree on `'google_maps'` / `'uav'`.
+
+### Phase 7 — Architecture Compliance
+- Layering: `TileSource` enum lives in `SatelliteProvider.Common.Enums` (Layer 1 Foundation). DataAccess (Layer 1) and TileDownloader (Layer 3) both consume it through Common — no new cross-sibling ProjectReferences.
+- Public API respect: `TileSource` and `TileSourceTypeHandler` are public; `module-layout.md` Common Public API list updated to include `TileSource.cs`.
+- No new cycles.
+- No duplicate symbols across components.
+
+### Baseline Delta
+Not computed inline — this batch makes no structural changes that would shift the existing `_docs/02_document/architecture_compliance_baseline.md` deltas. The AZ-484 changes stay within the existing layering invariants confirmed in earlier baseline scans.
+
+## Verdict Logic
+No Critical, High, Medium, or Low findings → **PASS**.
@@ -0,0 +1,65 @@
+# Phase 1 — Dependency Scan
+
+**Date**: 2026-05-11
+**Method**: Manual inventory from `*.csproj` + targeted advisory search (WebSearch against GHSA / NVD / NuGet ReversingLabs).
+**Reason for manual mode**: `dotnet list package --vulnerable` is on the project's "do not run from agent" list (AGENTS.md — these commands hang in this environment).
+
+## Inventory
+
+| Project | Package | Version | Notes |
+|---------|---------|---------|-------|
+| Api | Microsoft.AspNetCore.OpenApi | 8.0.21 | ASP.NET Core 8 LTS patch (one behind 8.0.25) |
+| Api | Newtonsoft.Json | 13.0.4 | Latest 13.x |
+| Api | Serilog.AspNetCore | 8.0.3 | |
+| Api | Serilog.Sinks.File | 6.0.0 | |
+| Api | SixLabors.ImageSharp | 3.1.11 | |
+| Api | Swashbuckle.AspNetCore | 6.6.2 | |
+| Common | SixLabors.ImageSharp | 3.1.11 | |
+| DataAccess | Dapper | 2.1.35 | |
+| DataAccess | Npgsql | 9.0.2 | |
+| DataAccess | dbup-postgresql | 6.0.3 | |
+| DataAccess | Microsoft.Extensions.Configuration.Abstractions | 9.0.10 | |
+| DataAccess | Microsoft.Extensions.Logging.Abstractions | 9.0.10 | |
+| TileDownloader | Microsoft.Extensions.Caching.Memory | 9.0.10 | |
+| TileDownloader | Microsoft.Extensions.Http | 9.0.10 | |
+| TileDownloader | Microsoft.Extensions.Logging.Abstractions | 9.0.10 | |
+| TileDownloader | Microsoft.Extensions.Options.ConfigurationExtensions | 9.0.10 | |
+| TileDownloader | Newtonsoft.Json | 13.0.4 | |
+| Tests | coverlet.collector | 6.0.0 | |
+| Tests | FluentAssertions | 8.8.0 | |
+| Tests | Microsoft.Extensions.* | 9.0.10 | (multiple) |
+| Tests | Microsoft.NET.Test.Sdk | 17.8.0 | NuGet.Frameworks transitive CVE flag — see findings |
+| Tests | Moq | 4.20.72 | |
+| Tests | xunit | 2.5.3 | |
+| Tests | xunit.runner.visualstudio | 2.5.3 | |
+
+## Findings
+
+| # | Severity | Package | Version | Advisory | Disposition |
+|---|----------|---------|---------|----------|-------------|
+| D1 | Medium (production-risk: **Low**, exposure: not reachable) | Microsoft.AspNetCore.OpenApi → ASP.NET Core 8 runtime | 8.0.21 | [CVE-2026-26130](https://github.com/dotnet/aspnetcore/security/advisories/GHSA-4vgm-c2wm-63mw) — SignalR DoS via unbounded buffer | **Not exploitable in this app**: codebase grep for `SignalR\|MapHub\|UseSignalR\|HubConnection` returns zero hits. Runtime patch still recommended. Upgrade `Microsoft.AspNetCore.OpenApi` to `8.0.25` (or current 8.0.x patch) and redeploy on a runtime ≥ 8.0.25 to remove the vulnerable code paths from the deployed image. |
+| D2 | Low (test-only) | Microsoft.NET.Test.Sdk | 17.8.0 | [CVE-2022-30184](https://github.com/microsoft/vstest/issues/4409) via transitive `NuGet.Frameworks <6.2.1` — information disclosure (CVSS 5.5) | **Not exploitable in production**: package is `IsTestProject=true` only; never shipped. Upgrade to `Microsoft.NET.Test.Sdk` ≥ 17.9.0 (which dropped the `NuGet.Frameworks` dependency entirely) the next time the test project's deps are touched. |
+
+## Cross-version sanity (per `coderule.mdc`: keep dependency versions consistent)
+
+- `Microsoft.Extensions.*` is uniformly **9.0.10** across DataAccess, TileDownloader, Tests, RegionProcessing, RouteManagement — consistent. ✓
+- `Newtonsoft.Json` is **13.0.4** in both Api and TileDownloader — consistent. ✓
+- `SixLabors.ImageSharp` is **3.1.11** in both Api and Common — consistent. ✓
+- ASP.NET Core meta-package level is at **8.0.21** while extensions are at 9.0.10. The 9.x extensions ship a forward-compatible netstandard2.0 surface and load fine on the .NET 8 runtime — no functional issue, but worth flagging as a minor consistency drift for whoever next bumps the framework.
+
+## Items checked clean
+
+- SixLabors.ImageSharp 3.1.11 — newer than the patched 3.1.7 / 3.1.5 lines (CVE-2024-41131, CVE-2025-27598). No outstanding GHSA against 3.1.11 itself.
+- Newtonsoft.Json 13.0.4 — past CVE-2024-21907 fix line (13.0.1).
+- Npgsql 9.0.2 — outside the 4.x / 5.x / 6.x / 7.x / 8.x ranges affected by CVE-2024-32655 (SQL injection via protocol message size overflow). 9.0.x line was never affected.
+- Dapper 2.1.35 — only "advisory" hit was a dependency-check false positive for SQLite CVE-2017-10989; not a Dapper issue.
+- Swashbuckle.AspNetCore 6.6.2 — no published GHSA / CVE.
+- Serilog.AspNetCore 8.0.3 — no published GHSA / CVE.
+- dbup-postgresql 6.0.3 — no published GHSA / CVE.
+
+## Self-verification
+
+- [x] All package manifests scanned (8 csproj files)
+- [x] Each finding has a CVE ID or advisory reference
+- [x] Upgrade paths identified for every Medium/Low finding
+- [x] No Critical or High finding remains open after exploitability triage
@@ -0,0 +1,87 @@
+# Phase 4 — Configuration & Infrastructure Review
+
+**Date**: 2026-05-11
+**Scope**: `Dockerfile` (API + integration tests), `docker-compose.yml`, `docker-compose.tests.yml`, `.dockerignore`, `.woodpecker/01-test.yml`, `.woodpecker/02-build-push.yml`, `appsettings*.json`, `.env` handling.
+
+## Findings
+
+### I1 — Dockerfile runs as root (Low)
+
+- **Location**: `SatelliteProvider.Api/Dockerfile` (no `USER` directive)
+- **Description**: The final stage of the API image inherits root from `mcr.microsoft.com/dotnet/aspnet:8.0` (current Microsoft images default to root unless overridden). Any process compromise — even a low-impact one — has uid-0 inside the container.
+- **Impact**: Container escape primitives (e.g., kernel CVE, sloppy bind-mount of `/var/run/docker.sock`) become host-root rather than host-uid-1000. The `02-build-push.yml` step itself bind-mounts `/var/run/docker.sock` into the build container — that's a separate concern (build host, not runtime), but it underscores why "least privilege at runtime" matters even on a single-tenant box.
+- **Remediation**: Add to the `final` stage:
+  ```dockerfile
+  RUN adduser --disabled-password --gecos "" --uid 10001 satellite && \
+      chown -R satellite:satellite /app
+  USER satellite
+  ```
+  Also verify `./tiles`, `./ready`, `./logs` host volumes are writable by uid 10001 in deployment manifests.
+
+### I2 — No security headers middleware (Low)
+
+- **Location**: `SatelliteProvider.Api/Program.cs` (no `app.UseSecurityHeaders()` / `app.Use(headers …)` block)
+- **Description**: API responses do not set `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, `X-Frame-Options: DENY`, or HSTS (`Strict-Transport-Security`) — only `app.UseHttpsRedirection()` is wired. For a JSON-only API this is **low** impact (no browser is the primary client), but the missing `Cache-Control` defaults can let proxies cache 5xx responses.
+- **Impact**: Limited — JSON-only responses, no cookies, no browser session. The Swagger UI (Development-only) does render HTML; a permissive default there is more of a hygiene issue than a real risk.
+- **Remediation**: Add a tiny middleware to set the standard hardening headers, OR install `NWebsec.AspNetCore.Middleware` and wire `app.UseHsts()` + the `nosniff` / `frame-options` defaults. Cheap, no behavioural change.
+
+### I3 — No rate limiting on any HTTP endpoint (Medium)
+
+- **Location**: `SatelliteProvider.Api/Program.cs` (no `app.UseRateLimiter()`, no `AddRateLimiter()`)
+- **Description**: There is internal concurrency control on outbound Google Maps calls (`SemaphoreSlim`, `MaxConcurrentDownloads`), but no inbound rate limiting. An attacker can:
+  - Submit `N` `POST /api/satellite/request` calls in a tight loop, filling the bounded `IRegionRequestQueue` (capacity 1000) and DoS-ing the background processor.
+  - Submit `N` `GET /api/satellite/tiles/latlon` calls with novel lat/lon pairs, forcing the upstream Google Maps quota to drain.
+- **Impact**: Service-degradation DoS. Combined with finding A01-caveat (no auth), the only protection is the network boundary.
+- **Remediation**: Wire `Microsoft.AspNetCore.RateLimiting` (built into .NET 8 — no new package). Conservative starting point:
+  ```csharp
+  builder.Services.AddRateLimiter(options =>
+  {
+      options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(ctx =>
+          RateLimitPartition.GetFixedWindowLimiter(
+              partitionKey: ctx.Connection.RemoteIpAddress?.ToString() ?? "unknown",
+              factory: _ => new FixedWindowRateLimiterOptions { PermitLimit = 60, Window = TimeSpan.FromMinutes(1) }));
+  });
+  app.UseRateLimiter();
+  ```
+  Tune per-endpoint after observing baseline production load.
+
+### I4 — No security-event logs / alerting (Low)
+
+- **Location**: Logging strategy across `Program.cs`, `GlobalExceptionHandler`, `CorsConfigurationValidator`
+- **Description**: Operational logs are well-structured (Serilog → file rotation; correlationId propagation), but there are no log entries for what would be security-relevant events: validation failures (BadRequest stream), repeated 4xx from a single IP, malformed input bursts, or migration failures. The migration failure path does throw and crash startup (good signal), but this leaves no trail in the file logs.
+- **Impact**: No way to detect abuse of the unauthenticated endpoints from logs alone. For an internal-only deployment this is acceptable; if the API ever moves toward a less-trusted network, post-deploy log-mining will not be able to reconstruct attack patterns.
+- **Remediation**: Defer until/unless the trust boundary changes. When required: add a structured log line for each 400/404 (with `Method`, `Path`, `RemoteIp`, `correlationId`) and a counter for "validation failures per minute per IP".
+
+### I5 — `.env` is NOT in `.dockerignore` (Medium)
+
+- **Location**: `.dockerignore` (line by line review — no `.env` entry); `SatelliteProvider.Api/Dockerfile:15` (`COPY . .`)
+- **Description**: The Dockerfile's `COPY . .` step copies the entire build context into `/src`. The build context starts at the repo root, where `.env` lives. `.env` IS in `.gitignore` so the dev-only Google Maps key never reaches the git repo, but it WILL be baked into the build-stage image layer (and into the final image, since `final` does `COPY --from=publish /app/publish .` — only `/app/publish` survives, but the `build` stage retains `.env` and is reachable if anyone introspects an intermediate layer).
+- **Impact**:
+  - Anyone with read access to the registry can `docker pull <build-stage-tag>` (if exported) and recover the API key from the layer.
+  - Even just the `final` image: BuildKit cache mounts and any future Dockerfile change that does `COPY . /app` instead of `COPY --from=publish` would silently include the file.
+- **Remediation**: Add `.env` to `.dockerignore`:
+  ```
+  .env
+  .env.*
+  !.env.example
+  ```
+  This is a one-line fix and complements finding S4.
+
+### I6 — `docker-compose.yml` exposes Postgres on `0.0.0.0:5432` (Medium — duplicate of S2; restated here for infra-domain completeness)
+
+- **Location**: `docker-compose.yml:9-10`
+- **Description / Remediation**: See S2.
+
+## Items checked clean
+
+- **Secrets management in CI**: `.woodpecker/02-build-push.yml` uses `from_secret: registry_host / registry_user / registry_token` — no plaintext credentials. The `docker login` step pipes the token via `--password-stdin`, which avoids leaking the token via process list. ✓
+- **Image attribution**: build step labels images with `org.opencontainers.image.revision`, `…created`, `…source` — good provenance hygiene. ✓
+- **Healthcheck on Postgres**: `pg_isready -U postgres` configured. (Note: relies on the weak default user from S2.)
+- **Log volume layout**: `./logs:/app/logs` mounted; not exposed via the API. ✓
+- **Test runner isolation**: `docker-compose.tests.yml` extends the API service (good — same image) but uses `restart: "no"` so a flapping integration test doesn't loop and amplify load.
+
+## Self-verification
+
+- [x] All Dockerfiles reviewed (Api + IntegrationTests)
+- [x] All CI/CD configs reviewed (`.woodpecker/01-test.yml`, `02-build-push.yml`)
+- [x] All env / config files reviewed (`appsettings*.json`, `.env`, `docker-compose*.yml`)
@@ -0,0 +1,40 @@
+# Phase 3 — OWASP Top 10:2025 Review
+
+**Date**: 2026-05-11
+**OWASP version**: [OWASP Top 10:2025](https://owasp.org/Top10/2025/en/) (verified at audit start)
+**Project context**: Self-hosted .NET 8 backend service. Documented as an "internal/trusted network service — no auth layer" (`_docs/02_document/architecture.md` §7). Deployed via Docker behind another network boundary (per `_docs/02_document/deployment/`). The audit is scoped to the codebase as it stands; categories whose findings depend on a missing trust-boundary control are flagged accordingly.
+
+| # | Category | Status | Findings | Notes |
+|---|----------|--------|----------|-------|
+| A01 | Broken Access Control | **N/A** (with caveat) | — | The service intentionally exposes ALL endpoints without authentication or authorization — documented design (architecture.md §7). No IDOR analysis applies because there is no user concept. **Caveat**: this is only safe if the deployment puts the API behind a network-level gatekeeper (VPN, mTLS, internal-only LB). If the deploy ever moves to a public network, this category becomes the #1 risk and EVERY endpoint becomes an unauthenticated execution surface. |
+| A02 | Security Misconfiguration | **FAIL** | S1, S2, I1, I2 | Default Postgres credentials in both `appsettings.json` and `docker-compose.yml`; Postgres port bound to `0.0.0.0`; container runs as root; no security headers middleware. |
+| A03 | Software Supply Chain Failures | **PASS_WITH_WARNINGS** | D1, D2 | Two known transitive CVEs (D1 — ASP.NET Core 8.0.21 SignalR DoS, not exploitable here; D2 — `Microsoft.NET.Test.Sdk` 17.8.0 → `NuGet.Frameworks` info disclosure, test-only). No use of unsigned NuGet packages; no auto-update of dependencies in production. |
+| A04 | Cryptographic Failures | **N/A** | — | No password storage (no users), no encryption at rest, no in-app crypto. The Google Maps integration uses HTTPS (default Npgsql/HttpClient stacks). At-rest tile storage is plain JPEG by design — these are public satellite images, not confidential data. |
+| A05 | Injection | **PASS** | — | All Dapper queries use parameter objects (`new { Id = id }` etc.); no string-built or interpolated user input flows into SQL. No `Process.Start`, no shell exec, no `eval`. JSON deserialization uses `System.Text.Json` defaults (no type-name handling). XSS / template injection N/A — JSON-only API. |
+| A06 | Insecure Design | **FAIL** | S3, I3 | No rate limiting on any endpoint despite the existence of an outbound rate-limited dependency (Google Maps). Latitude / longitude inputs are not range-validated at the API boundary (S3). No quota / throttling on region-request creation, which can multiply outbound calls and disk writes. |
+| A07 | Authentication Failures | **N/A** (with caveat) | — | Same caveat as A01 — there is no authentication system to fail. |
+| A08 | Software or Data Integrity Failures | **PASS** | — | DbUp migrations are idempotent and tracked in `schemaversions`; rollback is forward-only by design. No auto-update path. CI artifacts go through `.woodpecker/02-build-push.yml` with `from_secret: registry_token` (not in plaintext). No unsigned external scripts executed at build/deploy. |
+| A09 | Security Logging and Alerting Failures | **PASS_WITH_WARNINGS** | I4 | Serilog writes structured logs with file rotation; `GlobalExceptionHandler` correlates server logs to client responses via `correlationId` (good). However: no security-event logging (e.g., bad-input bursts, repeated 4xx from same source) and no alerting on log patterns. Acceptable for an internal service; would need attention if exposed publicly. |
+| A10 | Mishandling of Exceptional Conditions | **PASS** | — | `GlobalExceptionHandler` returns RFC 7807 ProblemDetails with a generic body and a correlationId — no exception text leaks to clients. `GlobalExceptionHandlerTests.cs` includes a positive control that confirms a "leakySecret"-shaped exception message is NOT echoed. |
+
+## Cross-reference to Phase 1 / Phase 2 findings
+
+| OWASP Cat | Tied finding | Severity | Source phase |
+|-----------|--------------|----------|--------------|
+| A02 | S1 — default password in appsettings.json | Medium | Phase 2 |
+| A02 | S2 — weak Postgres creds + 0.0.0.0 binding in compose | Medium | Phase 2 |
+| A02 | I1 — Dockerfile runs as root | Low | Phase 4 (next) |
+| A02 | I2 — no security headers middleware | Low | Phase 4 (next) |
+| A03 | D1 — CVE-2026-26130 in ASP.NET Core 8.0.21 (SignalR; not reachable) | Medium (paper) / Low (real) | Phase 1 |
+| A03 | D2 — CVE-2022-30184 transitive via test SDK | Low (test-only) | Phase 1 |
+| A06 | S3 — lat/lon not range-validated at API boundary | Low | Phase 2 |
+| A06 | I3 — no rate limiting on any endpoint | Medium | Phase 4 (next) |
+| A06 | S4 — Google Maps API key handling (no .env.example, no rotation hygiene) | Medium | Phase 2 |
+| A09 | I4 — no security-event logs, no alerting | Low | Phase 4 (next) |
+
+## Self-verification
+
+- [x] All current OWASP Top 10:2025 categories assessed
+- [x] Each FAIL has at least one specific finding with evidence
+- [x] N/A categories have justification + caveat
+- [x] No `security_approach.md` exists in `_docs/00_problem/` to cross-reference (project has not declared explicit security requirements; this audit treats the architecture-vision statement "internal/trusted network service" as the de-facto requirement)
@@ -0,0 +1,120 @@
+# Security Audit Report
+
+**Date**: 2026-05-11
+**Scope**: Satellite Provider — full repository (Api, Common, DataAccess, Services.*, Tests, infra)
+**Trigger**: `/autodev` Step 14 (Security Audit) — feature cycle 1, post-AZ-484
+**Verdict**: **PASS_WITH_WARNINGS**
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | 0 |
+| High     | 0 |
+| Medium   | 5 |
+| Low      | 5 |
+
+No Critical or High findings. The verdict is `PASS_WITH_WARNINGS` driven by 5 Medium findings, all of which are well-understood configuration / hardening gaps rather than exploitable vulnerabilities in the application logic itself. **AZ-484 (the cycle's only feature change) introduced zero new findings** — it is a pure data-layer change with no auth surface, no untrusted-input handling, and no new external dependencies.
+
+## OWASP Top 10:2025 Assessment
+
+| Category | Status | Findings |
+|----------|--------|----------|
+| A01 Broken Access Control | N/A (with caveat) | — |
+| A02 Security Misconfiguration | FAIL | S1, S2/I6, I1, I2 |
+| A03 Software Supply Chain Failures | PASS_WITH_WARNINGS | D1, D2 |
+| A04 Cryptographic Failures | N/A | — |
+| A05 Injection | PASS | — |
+| A06 Insecure Design | FAIL | S3, S4, I3 |
+| A07 Authentication Failures | N/A (with caveat) | — |
+| A08 Software or Data Integrity Failures | PASS | — |
+| A09 Security Logging and Alerting Failures | PASS_WITH_WARNINGS | I4 |
+| A10 Mishandling of Exceptional Conditions | PASS | — |
+
+The two **N/A (with caveat)** entries (A01, A07) reflect the documented architectural choice (`architecture.md` §7) that this is an internal/trusted-network service. **The audit does not endorse that choice — it merely notes that the choice has been made deliberately.** If the deployment trust boundary ever changes, A01 and A07 immediately become FAIL and every endpoint becomes an unauthenticated surface; that decision must be re-examined before any internet-facing exposure.
+
+## Findings
+
+| #  | Severity | Category               | Location                                                | Title                                                                                |
+|----|----------|------------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------|
+| S1 | Medium   | A02 — Misconfiguration | `SatelliteProvider.Api/appsettings.json:24`             | Default Postgres password (`postgres/postgres`) committed in `appsettings.json`     |
+| S2 | Medium   | A02 — Misconfiguration | `docker-compose.yml:6-7,30`                             | Weak Postgres credentials in compose (mirrors S1)                                    |
+| S3 | Low      | A06 — Insecure Design  | `SatelliteProvider.Api/Program.cs:169,207,237`          | Latitude/longitude inputs not range-validated at API boundary                        |
+| S4 | Medium   | A06 — Insecure Design  | `.env` (workspace root)                                 | Apparent real Google Maps API key on developer filesystem; no `.env.example`         |
+| D1 | Medium   | A03 — Supply Chain     | `SatelliteProvider.Api.csproj` — `Microsoft.AspNetCore.OpenApi 8.0.21` | CVE-2026-26130 SignalR DoS (not reachable in this app — codebase has zero SignalR use) |
+| D2 | Low      | A03 — Supply Chain     | `SatelliteProvider.Tests.csproj` — `Microsoft.NET.Test.Sdk 17.8.0` | CVE-2022-30184 transitive via `NuGet.Frameworks <6.2.1` (test-only)                  |
+| I1 | Low      | A02 — Misconfiguration | `SatelliteProvider.Api/Dockerfile`                      | Container runs as root (no `USER` directive)                                          |
+| I2 | Low      | A02 — Misconfiguration | `SatelliteProvider.Api/Program.cs`                      | No security headers middleware                                                        |
+| I3 | Medium   | A06 — Insecure Design  | `SatelliteProvider.Api/Program.cs`                      | No inbound rate limiting on any HTTP endpoint                                         |
+| I4 | Low      | A09 — Logging          | `SatelliteProvider.Api/*` (logging strategy)            | No security-event logs / alerting                                                     |
+| I5 | Medium   | A02 — Misconfiguration | `.dockerignore` + `Dockerfile:15` (`COPY . .`)          | `.env` not in `.dockerignore` — risk of API key being baked into image layers         |
+
+I6 in the infra report is a duplicate of S2 (same root cause) and is not double-counted in the summary.
+
+### Finding Details
+
+Full evidence and remediation for every finding lives in the per-phase reports. The detail tables there are the source of truth — this top-level report intentionally avoids restating multi-paragraph remediation steps.
+
+- **Phase 1**: `_docs/05_security/dependency_scan.md` — D1, D2, full dependency inventory + cross-version sanity check
+- **Phase 2**: `_docs/05_security/static_analysis.md` — S1, S2, S3, S4, plus the categories that were checked clean (SQL injection, command injection, deserialization, path traversal, log leakage, exception leakage)
+- **Phase 3**: `_docs/05_security/owasp_review.md` — OWASP Top 10:2025 per-category assessment + cross-reference table
+- **Phase 4**: `_docs/05_security/infrastructure_review.md` — I1, I2, I3, I4, I5, I6, plus the items checked clean (CI secrets handling, image attribution labels)
+
+## Dependency Vulnerabilities
+
+| Package | CVE | Severity | Reachable? | Fix Version |
+|---------|-----|----------|------------|-------------|
+| Microsoft.AspNetCore.OpenApi (→ ASP.NET Core 8 runtime) | CVE-2026-26130 | High (paper) / Low (this app) | **No** — codebase has zero SignalR use | 8.0.25 |
+| Microsoft.NET.Test.Sdk → NuGet.Frameworks | CVE-2022-30184 | Medium (paper) / Low (this app) | Test project only — never shipped | Microsoft.NET.Test.Sdk 17.9.0+ |
+
+All other dependencies (`Newtonsoft.Json 13.0.4`, `SixLabors.ImageSharp 3.1.11`, `Npgsql 9.0.2`, `Dapper 2.1.35`, `Swashbuckle.AspNetCore 6.6.2`, `Serilog.AspNetCore 8.0.3`, `dbup-postgresql 6.0.3`, `Microsoft.Extensions.* 9.0.10`) are at or beyond the patched line for every CVE I could find.
+
+## AZ-484 Cycle-Specific Verdict
+
+The reason this audit was triggered (the AZ-484 multi-source tile storage cycle) is independently **clean**:
+
+- Migration 013 is transactional and idempotent — no data loss / data integrity finding.
+- `TileSourceConverter` enforces a closed value space at the language layer; `TileEntity.Source` is `string` only as a Dapper-bug workaround documented in `_docs/LESSONS.md` L-001.
+- `TileRepository` queries continue to use parameterised Dapper — no new SQL injection surface.
+- No new external dependencies, no new endpoints, no new untrusted-input flows.
+- All findings in this report predate AZ-484 and are unchanged by it.
+
+## Recommendations
+
+### Immediate (Critical/High)
+
+None — there are no Critical or High findings. The audit does not block the next deploy on its own merit.
+
+### Short-term (Medium — pick before next public-network exposure or any post-deploy hardening pass)
+
+1. **S1 + S2 + I5** — De-default DB credentials and stop shipping the .env into the build context. One coordinated change:
+   - Remove `ConnectionStrings:DefaultConnection` from `appsettings.json` (rely on env-var via the existing throw on null).
+   - Add `POSTGRES_USER` / `POSTGRES_PASSWORD` to a tracked `.env.example` and source them from a dev `.env`; bind `5432` to `127.0.0.1`.
+   - Append `.env` and `.env.*` (with `!.env.example` exception) to `.dockerignore`.
+2. **S4** — Rotate the Google Maps API key out-of-band, add `.env.example`, add Google Cloud key restrictions (HTTP referrer or IP allowlist + per-API quotas). The audit deliberately did not echo the key value into any artifact.
+3. **D1** — Bump `Microsoft.AspNetCore.OpenApi` from `8.0.21` to the current 8.0.x patch (≥ 8.0.25) and rebuild the deployed image so the vulnerable SignalR code paths are physically absent.
+4. **I3** — Wire `Microsoft.AspNetCore.RateLimiting` (built into .NET 8 — no new package). Conservative starting threshold in the per-phase report.
+
+### Long-term (Low — hardening backlog)
+
+1. **I1** — Add a non-root `USER` to the API Dockerfile.
+2. **I2** — Add a tiny security-headers middleware (or pull `NWebsec.AspNetCore.Middleware`).
+3. **S3** — Add explicit lat/lon range guards at the API boundary (matches the existing `SizeMeters` 100-10000 pattern).
+4. **D2** — Bump `Microsoft.NET.Test.Sdk` to ≥ 17.9.0 next time the test project's deps are touched.
+5. **I4** — Defer until the trust boundary changes; if/when the API moves toward a less-trusted network, add structured 4xx logging per IP + a basic alerting rule.
+
+## Verdict Logic
+
+- No Critical or High findings → **not FAIL**
+- 5 Medium + 5 Low findings exist → **not PASS**
+- Therefore: **PASS_WITH_WARNINGS**
+
+This satisfies the autodev gate to proceed to Step 15 (Performance Test). The recommendations above should be tracked as separate Jira tasks under a hardening epic before the first non-internal deployment.
+
+## Self-verification
+
+- [x] All findings from Phases 1–4 included
+- [x] No duplicate findings (I6 explicitly noted as a duplicate of S2 and not double-counted)
+- [x] Every finding has remediation guidance (in per-phase reports)
+- [x] Verdict matches severity logic (no Critical/High → not FAIL; >0 findings → not PASS)
+- [x] No real secret values printed in any audit artifact (S4 described without echoing the API key)
@@ -0,0 +1,90 @@
+# Phase 2 — Static Analysis (SAST)
+
+**Date**: 2026-05-11
+**Scope**: All `*.cs` files in production projects (Api, Common, DataAccess, Services.*) plus Tests for false-positive triage. Configuration files (`appsettings*.json`, `docker-compose*.yml`, `Dockerfile`, `.env`).
+**Method**: Pattern-based grep + targeted file review.
+
+## Patterns checked
+
+| Category | Pattern(s) | Verdict |
+|----------|-----------|---------|
+| SQL injection | `$"SELECT…"`, `+ "WHERE"`, raw `CommandText`, manual SQL string assembly | **Clean** |
+| Command/process injection | `Process.Start`, `ProcessStartInfo`, `cmd.exe`, `/bin/sh`, `UseShellExecute`, `eval`-equivalent | **Clean** |
+| XSS | unsanitized user input flowed to HTML or `Response.Write` | **N/A** — JSON-only API, no HTML rendering |
+| Template injection | Razor / scriban / handlebars on user input | **N/A** — none used |
+| Hardcoded credentials | `password = "…"`, `secret = "…"`, `token = "…"`, `apikey = "…"` in source | See findings S1, S2 |
+| Weak crypto | MD5/SHA1 for passwords, `RNGCryptoServiceProvider` (deprecated), hardcoded keys | **N/A** — no password storage, no crypto code in app |
+| Insecure deserialization | `BinaryFormatter`, `pickle`, untrusted JSON with type-name handling | **Clean** — `System.Text.Json` with default settings; `Newtonsoft.Json` 13.0.4 used only for outbound serialization to Google session-creation endpoint (line `GoogleMapsDownloaderV2.cs`), no deserialization of untrusted inbound JSON |
+| Path traversal | user input flowed into `File.Open`, `Path.Combine` | **Clean** — file paths are computed server-side from validated tile coordinates; no user-supplied path component reaches the filesystem |
+| Sensitive data in logs | passwords, API keys, tokens, PII in log statements | **Clean** — `GlobalExceptionHandler.cs` logs only `Method`, `Path`, `correlationId`; client gets a generic 500 + correlationId. `CorsConfigurationValidator` warning (`PermissiveDefaultWarning`) does not include secrets. There is a deliberate test fixture `GlobalExceptionHandlerTests.cs:23` that uses `"Connection string Host=secret-db;Password=hunter2 failed at line 42"` to verify the handler does NOT echo exception messages back — this is a positive control, not a finding |
+| Verbose error responses | stack traces or internal details returned to clients | **Clean** — `GlobalExceptionHandler` returns RFC 7807 ProblemDetails with `Detail = "An unexpected error occurred. Use the correlationId to look up the server log entry."` |
+| Input validation | numeric ranges, geo coordinates, enum-like strings | See finding S3 |
+
+## Findings
+
+### S1 — Default DB password committed in `appsettings.json` (Medium)
+
+- **Location**: `SatelliteProvider.Api/appsettings.json:24`
+- **Vulnerable code**:
+  ```json
+  "DefaultConnection": "Host=localhost;Database=satelliteprovider;Username=postgres;Password=postgres"
+  ```
+- **Description**: The default (non-Development) appsettings file ships with a weak, well-known password (`postgres/postgres`). In production this string is overridden by `ConnectionStrings__DefaultConnection` in `docker-compose.yml`/env, but the file itself becomes the fallback if env-var injection ever fails or is misconfigured (silent connect-as-default behaviour).
+- **Impact**: If a deployment misconfiguration drops the env override, the app silently falls back to attempting `postgres:postgres@localhost`. On a developer workstation this connects to the local Postgres container with full superuser; in production it would fail loudly only if the prod DB has different creds. Combined with finding S2 below (matching weak creds in compose file), this normalises a credential pattern that real production deployments may inherit.
+- **Remediation**:
+  - Replace the default value with a deliberately-invalid placeholder such as `Host=__set-via-env__;Database=__;Username=__;Password=__` so a misconfiguration fails fast at startup instead of silently falling through.
+  - OR remove the `ConnectionStrings:DefaultConnection` key from `appsettings.json` entirely and require the env var; `Program.cs` line 23–24 already throws when missing — keep that behaviour.
+
+### S2 — Weak Postgres credentials in `docker-compose.yml` (Medium, dev-only as written)
+
+- **Location**: `docker-compose.yml:6-7, 30`
+- **Vulnerable code**:
+  ```yaml
+  POSTGRES_USER: postgres
+  POSTGRES_PASSWORD: postgres
+  …
+  - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=satelliteprovider;Username=postgres;Password=postgres
+  ```
+- **Description**: Same `postgres/postgres` credentials as S1. The compose file is labelled `Development` (`ASPNETCORE_ENVIRONMENT=Development`), so this is contained — but the file is the only compose artifact in the repo, which means anyone running `docker-compose up` on a network-reachable host immediately exposes a Postgres-with-default-creds.
+- **Impact**: Postgres on `0.0.0.0:5432` (port `"5432:5432"` mapping) with `postgres/postgres` is one of the most-scanned credential pairs on the public internet. If a developer runs this on a non-laptop host (cloud VM, shared lab, etc.) the DB is trivially compromised within minutes.
+- **Remediation**:
+  - Bind `5432` to `127.0.0.1:5432` rather than `0.0.0.0:5432` so the host firewall isn't the only protection. (Replace `"5432:5432"` with `"127.0.0.1:5432:5432"`.)
+  - Source `POSTGRES_USER` / `POSTGRES_PASSWORD` from the same `.env` file that already supplies `GOOGLE_MAPS_API_KEY` (line 31 already shows the pattern). Provide an `.env.example` with placeholder values and document the required vars in the README.
+  - The deploy/observability docs at `_docs/02_document/deployment/` already describe a secret-manager strategy for staging/prod — fold the same pattern into the dev compose.
+
+### S3 — Latitude / longitude inputs not range-validated at the API boundary (Low)
+
+- **Locations**:
+  - `SatelliteProvider.Api/Program.cs:169` — `GetTileByLatLon([FromQuery] double Latitude, [FromQuery] double Longitude, [FromQuery] int ZoomLevel, …)`
+  - `SatelliteProvider.Api/Program.cs:207` — `RequestRegion` validates `SizeMeters` only; `request.Latitude` / `request.Longitude` are unchecked
+  - `SatelliteProvider.Api/Program.cs:237` — `CreateRoute` delegates to `RouteService` which validates names but does not range-check waypoint coordinates
+- **Description**: `Latitude`, `Longitude`, and (for region requests) the implicit `MaxRoutePointSpacingMeters` boundary are accepted without enforcing valid geographic ranges (`-90 ≤ lat ≤ 90`, `-180 ≤ lon ≤ 180`). `ZoomLevel` IS validated downstream by `GoogleMapsDownloaderV2` against `MapConfig.AllowedZoomLevels` — so it is fine.
+- **Impact**:
+  - Garbage inputs (e.g. `lat=999`) propagate through `GeoUtils.WorldToTilePos` and the slippy-map math, eventually producing nonsensical tile coordinates that are persisted to `tiles` and `regions`. This is a **data-quality** issue, not a code-execution issue.
+  - No DoS amplification: every tile-download endpoint already enforces zoom against `AllowedZoomLevels`, so an attacker cannot use lat/lon abuse to multiply outbound Google Maps traffic beyond what zoom already bounds.
+- **Remediation**: Add explicit guard clauses at the API boundary (matches the existing `SizeMeters` 100-10000 pattern):
+  ```csharp
+  if (Latitude < -90 || Latitude > 90)  return Results.BadRequest(new { error = "Latitude must be between -90 and 90" });
+  if (Longitude < -180 || Longitude > 180) return Results.BadRequest(new { error = "Longitude must be between -180 and 180" });
+  ```
+  Apply uniformly to `GetTileByLatLon`, `RequestRegion`, and to each waypoint inside `CreateRoute`.
+
+### S4 — `.env` file on developer filesystem contains an apparently real Google Maps API key (Medium — exposure depends on key reach)
+
+- **Location**: `.env` (workspace root, **not** tracked — confirmed via `git ls-files` and `.gitignore:10`)
+- **Description**: The local `.env` contains a 39-character `AIzaSy…` value matching the Google Maps API key format. The file is correctly excluded from git (line 10 of `.gitignore`) and `git log -- .env` returns no history, so the key was never committed to this repository.
+- **Impact**: No repository exposure. **However**:
+  - If the same key is shared across developers via Slack / email / other repos, it has likely already leaked elsewhere.
+  - There is no `.env.example` template in the repo, which means new contributors typically request the real key via insecure channels rather than generating a fresh one.
+  - The key has no per-call attribution; abuse cannot be traced back to a specific developer.
+- **Remediation**:
+  - **Rotate the key in the Google Cloud console** (out of scope for this audit — the key value is intentionally not echoed into this report).
+  - Add `.env.example` to the repo with `GOOGLE_MAPS_API_KEY=replace-with-your-own-key-from-cloud-console` and reference it in the README setup section.
+  - Configure Google Cloud key restrictions: HTTP referrer allowlist (for browser keys) or IP allowlist (for server keys), and per-API quotas. Optional: per-developer keys.
+
+## Self-verification
+
+- [x] All production source directories scanned (Api, Common, DataAccess, Services.TileDownloader, Services.RegionProcessing, Services.RouteManagement)
+- [x] Each finding has file path and line number
+- [x] False positives from test files explicitly distinguished (`GlobalExceptionHandlerTests.cs:23` "leakySecret" is a positive control)
+- [x] No real secret values printed in this report (S4 is described without echoing the key)
@@ -0,0 +1,52 @@
+# Perf Run — Cycle 1 (post-AZ-484)
+
+**Date**: 2026-05-11
+**Mode**: `test-run` perf mode
+**Runner detected**: `scripts/run-performance-tests.sh` (PT-01..PT-06)
+**Target**: `API_URL=http://localhost:18980` (would require local docker stack)
+**Status**: **NOT EXECUTED** — see "Run decision" below
+
+## Run decision
+
+The perf gate did not execute scenarios in this cycle. The choice was made at the autodev Step 15 user-prompt with full context:
+
+- AZ-484 changed the read hot path (`GetTilesByRegionAsync` now uses `DISTINCT ON`; `GetByTileCoordinatesAsync` uses the new most-recent-across-sources tie-break).
+- The cycle-specific NFR `PT-07` (recorded in `_docs/02_document/tests/performance-tests.md` and the traceability matrix during Step 12) requires `p95 ≤ 1.10 × pre-AZ-484 baseline`. The runner script `scripts/run-performance-tests.sh` does **not yet have a PT-07 implementation** — adding the baseline-capture / comparison harness is its own work item.
+- Running PT-01..PT-06 requires bringing up `docker-compose` on the developer host. Per `meta-rule.mdc` execution-safety guidance, Docker / long-running perf operations need explicit user opt-in, which was not granted on this turn.
+
+## Scenario classification
+
+Per the test-run perf-mode rules, every scenario without measured data + threshold comparison is recorded as **Unverified**. Unverified is **not blocking**: the gate does not fail; it just surfaces the coverage gap.
+
+| Scenario | Threshold | Result |
+|----------|-----------|--------|
+| PT-01 Tile Download Latency (cold) | ≤ 30000 ms | **Unverified** |
+| PT-02 Cached Tile Retrieval Latency | ≤ 500 ms | **Unverified** |
+| PT-03 Region Processing 200m / z18 | ≤ 60000 ms (end-to-end) | **Unverified** |
+| PT-04 Region Processing 500m / z18 + stitch | ≤ 120000 ms | **Unverified** |
+| PT-05 5 Concurrent Regions | all complete in ≤ 300000 ms | **Unverified** |
+| PT-06 Route Point Interpolation Speed | ≤ 5000 ms | **Unverified** |
+| PT-07 `GetTilesByRegionAsync` p95 vs pre-AZ-484 baseline | ≤ 1.10 × baseline | **Unverified — harness not implemented** |
+
+## Why this is acceptable for this cycle
+
+- AZ-484's correctness was validated by the integration test `MostRecentAcrossSourcesSelection_AZ484_AC2` and the four other AZ-484 integration tests added in Step 11. Those tests use a temp `tiles_az484_*` table to avoid touching production data, and they exercise the same `DISTINCT ON` SQL path that PT-07 would measure.
+- The Step 11 unit + integration suite passed clean against the post-AZ-484 code; there is no functional regression to feed a perf regression.
+- The post-AZ-484 SQL is structurally cheaper or equivalent to the pre-AZ-484 path: `DISTINCT ON` over the same `(latitude, longitude, tile_zoom, tile_size_meters)` subset uses the existing `idx_tiles_unique_location_source` index. There is no new join, no new full-table scan, and no new lock surface.
+- The audit-only nature of this gap is logged so the next cycle picks it up — see leftover entry.
+
+## Follow-up work (logged as a leftover)
+
+A leftover file `_docs/_process_leftovers/2026-05-11_perf-pt07-harness.md` records the deferred work to:
+
+1. Implement PT-07 in `scripts/run-performance-tests.sh` (capture baseline, run post-change measurement, compute ratio).
+2. Re-run the full perf suite once the docker stack is available and the harness is in place.
+3. Flip PT-07 from "recorded" to "active" in `_docs/02_document/tests/performance-tests.md` and the traceability matrix.
+
+## Self-verification
+
+- [x] Runner detection executed (`scripts/run-performance-tests.sh` exists)
+- [x] Run decision recorded with reasons
+- [x] Every scenario classified (Pass / Warn / Fail / Unverified)
+- [x] Follow-up work captured as a tracker leftover (non-user-input blocker per `tracker.mdc`)
+- [x] No fabricated metrics — every "Unverified" is genuine
@@ -0,0 +1,29 @@
+# Engineering Lessons
+
+Recurring bugs, surprising library behaviors, and process insights extracted from completed cycles. Newest at the top. Keep entries short — this is for fast scanning at the start of new cycles, not exhaustive history.
+
+---
+
+## L-001 — Dapper `TypeHandler<T>` is bypassed for enum types during read deserialization
+
+**Cycle**: 1 (AZ-484)
+**Discovered by**: integration test failure (`Error parsing column 12 (source=google_maps - String)`); root-caused via web search to long-standing Dapper issue [#259](https://github.com/DapperLib/Dapper/issues/259).
+**Affects**: Dapper 2.1.35 (and most other versions until the proposed `Settings.PreferTypeHandlersForEnums` opt-in in PR #2200, not yet merged).
+
+**What happens**
+Registering `SqlMapper.AddTypeHandler(new MyEnumHandler())` for an `enum` type — even via `SqlMapper.TypeHandler<TEnum>` — works for **writes** (the handler's `SetValue` is invoked for parameter binding) but is **silently bypassed for reads**. Dapper's IL-emitted deserializer checks `IsEnum` first and falls back to `Enum.TryParse(string, ignoreCase: true)`.
+
+**Why this is dangerous**
+If the enum's wire string happens to match a member name case-insensitively (e.g., `RegionStatus.Failed` ↔ `"failed"`), the bypass goes unnoticed and round-trip works *accidentally*. The bug only surfaces when the wire format diverges from the C# member name (e.g., `TileSource.GoogleMaps` ↔ `"google_maps"` — `Enum.TryParse("google_maps")` does not match `GoogleMaps` because of the underscore).
+
+**Recommended approach**
+- Do **not** rely on `SqlMapper.TypeHandler<TEnum>` for read-side enum mapping unless the wire values match the enum member names case-insensitively.
+- For enums whose wire format diverges (snake_case, kebab-case, custom IDs), store the entity field as `string` and provide an explicit converter (`*Converter.ToWireValue` / `FromWireValue`) for use at the service-layer boundary. This is what AZ-484 does for `TileEntity.Source` ↔ `TileSourceConverter`.
+- Unit-test the converter directly. Do not assume that round-tripping through Dapper proves anything for enums.
+
+**Detection**
+- Unit tests of the type handler in isolation will pass even when the handler is bypassed at runtime.
+- Failure surfaces only at integration-test time when the actual SELECT runs.
+- If you must keep an enum-typed field, write at minimum one integration test that reads the enum back through Dapper from a real database row.
+
+---
@@ -2,12 +2,12 @@

 ## Current Step
 flow: existing-code
-step: 9
-name: New Task
-status: not_started
+step: 16
+name: Deploy
+status: in_progress
 sub_step:
-  phase: 0
-  name: awaiting-invocation
+  phase: 1
+  name: cycle-deploy-report
  detail: ""
 retry_count: 0
 cycle: 1
@@ -0,0 +1,32 @@
+# Leftover — PT-07 perf harness + cycle 1 perf run
+
+- **Timestamp**: 2026-05-11T07:05:00Z
+- **Origin**: autodev cycle 1, Step 15 (Performance Test)
+- **Blocker class**: non-user-input — work was deferred at the Step 15 user gate; no missing user decision blocks completion.
+
+## What was deferred
+
+1. **PT-07 implementation** in `scripts/run-performance-tests.sh`: capture pre-change baseline for `GetTilesByRegionAsync` p95 latency, run post-change measurement, compute the ratio, and assert `ratio ≤ 1.10`. PT-07 was recorded as a documentation entry during Step 12 (`_docs/02_document/tests/performance-tests.md` + `traceability-matrix.md` "NFRs → Test Mapping" section) but the runner script does not yet have the corresponding scenario.
+2. **Active perf run** of PT-01..PT-06 against the post-AZ-484 build. The runner exists; it requires `docker-compose up` on the dev host. Not executed this cycle (per the meta-rule "ask before kicking off Docker / long-running perf operations").
+
+## Why it is safe to defer
+
+- AZ-484 functional correctness validated by 5 dedicated AZ-484 integration tests (Step 11). The DB read paths exercised by PT-07 are the same ones exercised by `MostRecentAcrossSourcesSelection_AZ484_AC2` etc.
+- The post-AZ-484 SQL uses the same `idx_tiles_unique_location_source` index as the contract specifies; structurally there is no new full scan, join, or lock added vs. pre-AZ-484.
+- Cycle 1 perf run is recorded as `Unverified` (not `Fail`) per the test-run perf-mode rules — gate does not block deploy.
+
+## Replay actions for next /autodev invocation
+
+When the next cycle's autodev runs, before any new tracker write or before re-entering Step 15 in cycle 2:
+
+1. Add PT-07 to `scripts/run-performance-tests.sh`:
+   - Capture a pre-change baseline by checking out the parent of the AZ-484 commit (`git rev-parse HEAD~N` where N points at the AZ-484 batch), running the existing PT-03/PT-04 region scenarios, and recording the `GetTilesByRegionAsync` timings (the repository already logs slow query warnings at >500 ms — extend that log line to include median/p95 captured per call window).
+   - Run the post-change measurement against the current `HEAD`.
+   - Compute the p95 ratio and fail when `> 1.10`.
+2. Bring up the docker stack (`docker-compose up --build -d`) and run the full perf script with the user's explicit go-ahead.
+3. Capture results into `_docs/06_metrics/perf_<YYYY-MM-DD>_cycle<N>.md`.
+4. Once results are recorded, delete this leftover file.
+
+## Tracker action (none required this cycle)
+
+This leftover does NOT require a Jira ticket on its own — it tracks deferred process work, not user-visible scope. If the perf comparison reveals a regression next cycle, that finding will create a Jira bug; until then there is nothing to file.
Author	SHA1	Message	Date
Oleksandr Bezdieniezhnykh	51b572108a	[AZ-484] Cycle 1 Steps 12-16: docs, security, perf, deploy report ci/woodpecker/push/01-test Pipeline was successful Details ci/woodpecker/push/02-build-push Pipeline was successful Details Captures the post-implementation autodev gates for AZ-484 multi-source tile storage: - Step 12 (Test-Spec Sync): added 7 AC rows (AZ-484 AC-1..AC-7) and a PT-07 NFR row to traceability-matrix.md; added PT-07 scenario to performance-tests.md. - Step 13 (Update Docs): refreshed data_model.md (tiles columns + indexes + selection rule + UPSERT contract + migrations 012/013), module-layout.md (Common/Enums section with L-001 guidance, DataAccess imports-from now lists 6 sites), 6 module / component docs to reflect the new repo signatures, source/captured_at fields, and Dapper enum bypass workaround. ripple_log_cycle1.md records zero out-of-scope ripple. - Step 14 (Security Audit): PASS_WITH_WARNINGS - 0 Critical, 0 High, 5 Medium, 5 Low. AZ-484 itself added zero new findings. Hardening items (Postgres default creds, .env in build context, GMaps key rotation, ASP.NET Core 8.0.21 -> 8.0.25, rate limiter) recorded for separate tickets. - Step 15 (Performance Test): all PT-01..PT-07 scenarios Unverified (non-blocking); PT-07 baseline-comparison harness deferred to a leftover for next cycle. - Step 16 (Deploy): cycle deploy report covering migration safety, rollback path, post-deploy verification, security caveats. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-11 10:03:05 +03:00
Oleksandr Bezdieniezhnykh	e9d6db077c	[AZ-484] Fix multi-source tile reads: drop Dapper enum handler Two integration-test failures uncovered after the initial commit: 1) GetTilesByRegionAsync outer ORDER BY referenced 'updated_at' but the inner DISTINCT ON subquery aliased it to 'UpdatedAt' (Postgres folds to 'updatedat'). DISTINCT ON already guarantees one row per (latitude, longitude, ...) so the third tiebreak was unreachable; removed it. 2) Dapper 2.1.35 silently bypasses SqlMapper.TypeHandler<T> for enum types during read deserialization (Dapper issue #259). The TileSourceTypeHandler worked for writes but reads fell through to Enum.TryParse, which cannot map 'google_maps' to GoogleMaps. Pivoted: TileEntity.Source is now a string (the wire value). TileSource enum stays as the public producer surface in Common.Enums; TileSourceConverter (Common.Enums) provides ToWireValue / FromWireValue / IsValidWireValue at the boundary. TileSourceTypeHandler deleted; registration removed from DapperEnumTypeHandlers.RegisterAll. tile-storage.md Inv-5 amended to document the storage choice. _docs/LESSONS.md L-001 records the Dapper bypass for future cycles. Full suite passes (213 unit + integration suite incl. AZ-484 AC-1..AC-5, security SEC-01..SEC-04, AZ-356/362/357). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-11 06:44:34 +03:00
Oleksandr Bezdieniezhnykh	687d6bdd5b	[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>	2026-05-11 06:21:59 +03:00
Oleksandr Bezdieniezhnykh	5ba58b6c8d	[AZ-484] [AZ-483] Add task spec + tile-storage v1.0.0 contract draft Step-9 (new-task) cycle 1 artifacts for the AZ-483 multi-source tile storage epic. AZ-485 (UAV upload + quality gate) deferred to a future Step-9 loop and recorded as planned in the dependencies table. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-11 06:05:06 +03:00