[AZ-503] Tile identity → UUIDv5 + integer UPSERT (foundation)

Foundation half of original AZ-503 (split during /autodev step 10 batch 2
on user choice; deferred work moved to AZ-505 with a Blocks link).

Adds deterministic tile identity (UUIDv5 over (z, x, y, source, flight_id))
shared cross-repo with gps-denied-onboard via the pinned TileNamespace
5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c, switches the tiles UPSERT key from
floats to integers with per-flight separation, plumbs FlightId through
UavTileMetadata + handler, and writes UAV evidence to per-flight
on-disk directories so two flights at the same (z, x, y) coexist.

- Common: pure-C# RFC 9562 Uuidv5 (no third-party dep) + FlightId DTO
  field; 10 Python-reference unit vectors verify byte parity.
- DataAccess: migration 014 adds flight_id (uuid NULL), location_hash
  (uuid NOT NULL, backfilled via session-scoped pg_temp.uuidv5),
  content_sha256 (bytea NULL), legacy_id (uuid NULL = preserves
  pre-AZ-503 random id one cycle); drops idx_tiles_unique_location_source
  (AZ-484) and adds idx_tiles_unique_identity keyed on
  (tile_zoom, tile_x, tile_y, tile_size_meters, source,
   COALESCE(flight_id, '00000000-...'::uuid)) + idx_tiles_location_hash.
- TileRepository: ColumnList + UPSERT updated; id never updated on
  conflict (preserves AC-2 idempotence). UpdateAsync extended.
- Services: TileService and UavTileUploadHandler compute deterministic
  Id + LocationHash + ContentSha256 before insert; UAV file path
  becomes ./tiles/uav/{flight_id or 'none'}/{z}/{x}/{y}.jpg.
- Tests: Uuidv5Tests (10 reference vectors), UavTileFilePathTests
  (per-flight + anonymous paths), UavTileUploadHandlerTests (AC-2,
  AC-3, AC-7, AC-11 unit-level), UavUploadTests (AC-3 + AC-4
  integration: multi-flight DB coexistence with shared location_hash
  + distinct file_path; float-different lat/lon collapse to 1 row),
  MigrationTests (column shape, idx_tiles_unique_identity supersedes
  AZ-484 index, deterministic backfill).
- IntegrationTests project references Common to reuse Uuidv5 in raw
  SQL seeds.
- AZ-488 MultiSourceCoexistence seed fixed to populate location_hash
  (otherwise migration 014's NOT NULL constraint fails).

ACs covered: AC-1, AC-2, AC-3, AC-4, AC-7, AC-8, AC-11.
ACs deferred to AZ-505: AC-5, AC-6, AC-9, AC-10, AC-12.

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

SatelliteProvider.Services.TileDownloader/TileService.cs

@@ -1,3 +1,5 @@
+using System.Globalization;
+using System.Security.Cryptography;
 using Microsoft.Extensions.Caching.Memory;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
@@ -144,9 +146,33 @@ public class TileService : ITileService
     private TileEntity BuildTileEntity(DownloadedTileInfoV2 downloaded)
     {
         var now = DateTime.UtcNow;
+        var source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps);
+        // AZ-503: deterministic UUIDv5 over (z, x, y, source, flight_id-or-zero).
+        // google_maps tiles have no flight_id so the name fragment uses the
+        // canonical all-zeros UUID; the same Python-side serialization in
+        // gps-denied-onboard produces byte-identical IDs.
+        var idName = string.Create(CultureInfo.InvariantCulture,
+            $"{downloaded.ZoomLevel}/{downloaded.X}/{downloaded.Y}/{source}/{Guid.Empty}");
+        var locationHashName = string.Create(CultureInfo.InvariantCulture,
+            $"{downloaded.ZoomLevel}/{downloaded.X}/{downloaded.Y}");
+        var id = Uuidv5.Create(Uuidv5.TileNamespace, idName);
+        var locationHash = Uuidv5.Create(Uuidv5.TileNamespace, locationHashName);
+        // content_sha256 is computed from the actual JPEG body on disk. Google Maps
+        // downloads land on disk before this method runs (FilePath is set by the
+        // downloader), so a single read here is safe and avoids re-streaming. If
+        // the file is missing for any reason, leave ContentSha256 null and rely on
+        // the application invariant of "NOT NULL for AZ-503+ inserts" surfacing
+        // the problem in tests rather than silently inserting a sentinel digest.
+        byte[]? contentSha256 = null;
+        if (File.Exists(downloaded.FilePath))
+        {
+            using var stream = File.OpenRead(downloaded.FilePath);
+            contentSha256 = SHA256.HashData(stream);
+        }
+
         return new TileEntity
         {
-            Id = Guid.NewGuid(),
+            Id = id,
             TileZoom = downloaded.ZoomLevel,
             TileX = downloaded.X,
             TileY = downloaded.Y,
@@ -158,10 +184,14 @@ public class TileService : ITileService
             MapsVersion = null,
             Version = null,
             FilePath = downloaded.FilePath,
-            Source = TileSourceConverter.ToWireValue(TileSource.GoogleMaps),
+            Source = source,
             CapturedAt = now,
             CreatedAt = now,
-            UpdatedAt = now
+            UpdatedAt = now,
+            FlightId = null,
+            LocationHash = locationHash,
+            ContentSha256 = contentSha256,
+            LegacyId = null
         };
     }
 

SatelliteProvider.Services.TileDownloader/UavTileUploadHandler.cs

@@ -1,3 +1,5 @@
+using System.Globalization;
+using System.Security.Cryptography;
 using System.Text.Json;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
@@ -23,6 +25,10 @@ public sealed class UavTileUploadHandler : IUavTileUploadHandler
 {
     private const string UavTileFileExtension = ".jpg";
     private const string UavTileSubdirectory = "uav";
+    // AZ-503: stable path segment used when an upload arrives without a FlightId.
+    // Picked as a literal token (not a UUID) so flight-anonymous evidence is
+    // visually distinct from real flight directories during ops triage.
+    private const string AnonymousFlightSegment = "none";
 
     private readonly IUavTileQualityGate _qualityGate;
     private readonly ITileRepository _tileRepository;
@@ -138,7 +144,7 @@ public sealed class UavTileUploadHandler : IUavTileUploadHandler
     private async Task<Guid> PersistAsync(UavTileMetadata metadata, ReadOnlyMemory<byte> imageBytes, CancellationToken cancellationToken)
     {
         var (tileX, tileY) = GeoUtils.WorldToTilePos(new GeoPoint(metadata.Latitude, metadata.Longitude), metadata.TileZoom);
-        var filePath = BuildUavTileFilePath(_storageConfig, metadata.TileZoom, tileX, tileY);
+        var filePath = BuildUavTileFilePath(_storageConfig, metadata.TileZoom, tileX, tileY, metadata.FlightId);
 
         var directory = Path.GetDirectoryName(filePath);
         if (!string.IsNullOrEmpty(directory))
@@ -148,16 +154,29 @@ public sealed class UavTileUploadHandler : IUavTileUploadHandler
 
         // File-first, row-second so a crash leaves an orphan file rather than a row
         // pointing at nothing (Risk 2 in the AZ-488 task spec).
-        await File.WriteAllBytesAsync(filePath, imageBytes.ToArray(), cancellationToken);
+        var imageArray = imageBytes.ToArray();
+        await File.WriteAllBytesAsync(filePath, imageArray, cancellationToken);
 
         var capturedAtUtc = metadata.CapturedAt.Kind == DateTimeKind.Utc
             ? metadata.CapturedAt
             : metadata.CapturedAt.ToUniversalTime();
         var now = _timeProvider.GetUtcNow().UtcDateTime;
 
+        // AZ-503: deterministic id from (z, x, y, source, flight_id-or-zero) and
+        // location_hash from (z, x, y). Cross-repo identical via Uuidv5.TileNamespace.
+        var source = TileSourceConverter.ToWireValue(TileSource.Uav);
+        var flightIdForName = metadata.FlightId ?? Guid.Empty;
+        var idName = string.Create(CultureInfo.InvariantCulture,
+            $"{metadata.TileZoom}/{tileX}/{tileY}/{source}/{flightIdForName}");
+        var locationHashName = string.Create(CultureInfo.InvariantCulture,
+            $"{metadata.TileZoom}/{tileX}/{tileY}");
+        var id = Uuidv5.Create(Uuidv5.TileNamespace, idName);
+        var locationHash = Uuidv5.Create(Uuidv5.TileNamespace, locationHashName);
+        var contentSha256 = SHA256.HashData(imageArray);
+
         var entity = new TileEntity
         {
-            Id = Guid.NewGuid(),
+            Id = id,
             TileZoom = metadata.TileZoom,
             TileX = tileX,
             TileY = tileY,
@@ -169,24 +188,32 @@ public sealed class UavTileUploadHandler : IUavTileUploadHandler
             MapsVersion = null,
             Version = null,
             FilePath = filePath,
-            Source = TileSourceConverter.ToWireValue(TileSource.Uav),
+            Source = source,
             CapturedAt = capturedAtUtc,
             CreatedAt = now,
             UpdatedAt = now,
+            FlightId = metadata.FlightId,
+            LocationHash = locationHash,
+            ContentSha256 = contentSha256,
+            LegacyId = null,
         };
 
         return await _tileRepository.InsertAsync(entity);
     }
 
-    public static string BuildUavTileFilePath(StorageConfig storageConfig, int tileZoom, int tileX, int tileY)
+    public static string BuildUavTileFilePath(StorageConfig storageConfig, int tileZoom, int tileX, int tileY, Guid? flightId = null)
     {
         ArgumentNullException.ThrowIfNull(storageConfig);
+        var flightSegment = flightId.HasValue
+            ? flightId.Value.ToString("D", CultureInfo.InvariantCulture)
+            : AnonymousFlightSegment;
         return Path.Combine(
             storageConfig.TilesDirectory,
             UavTileSubdirectory,
-            tileZoom.ToString(System.Globalization.CultureInfo.InvariantCulture),
-            tileX.ToString(System.Globalization.CultureInfo.InvariantCulture),
-            tileY.ToString(System.Globalization.CultureInfo.InvariantCulture) + UavTileFileExtension);
+            flightSegment,
+            tileZoom.ToString(CultureInfo.InvariantCulture),
+            tileX.ToString(CultureInfo.InvariantCulture),
+            tileY.ToString(CultureInfo.InvariantCulture) + UavTileFileExtension);
     }
 
     private static UavTileUploadHandlerResult EnvelopeError(string detail) =>