[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.Tests/UavTileFilePathTests.cs

@@ -9,7 +9,7 @@ public class UavTileFilePathTests
     [Theory]
     [InlineData("./tiles", 18, 76800, 50331)]
     [InlineData("/var/lib/sat/tiles", 16, 12345, 67890)]
-    public void BuildUavTileFilePath_MatchesContract(string root, int zoom, int x, int y)
+    public void BuildUavTileFilePath_AnonymousFlight_UsesNoneSegment(string root, int zoom, int x, int y)
     {
         // Arrange
         var storage = new StorageConfig { TilesDirectory = root };
@@ -18,8 +18,44 @@ public class UavTileFilePathTests
         var path = UavTileUploadHandler.BuildUavTileFilePath(storage, zoom, x, y);
 
         // Assert
-        var expected = Path.Combine(root, "uav", zoom.ToString(), x.ToString(), y + ".jpg");
+        var expected = Path.Combine(root, "uav", "none", zoom.ToString(), x.ToString(), y + ".jpg");
         path.Should().Be(expected,
-            "UAV file paths follow `./tiles/uav/{zoom}/{x}/{y}.jpg` per `uav-tile-upload.md` v1.0.0");
+            "AZ-503: flight-anonymous UAV paths use the literal `none` segment so they are visually distinct from real flight directories during ops triage");
+    }
+
+    [Theory]
+    [InlineData("./tiles", 18, 76800, 50331, "11111111-2222-3333-4444-555555555555")]
+    [InlineData("/var/lib/sat/tiles", 16, 12345, 67890, "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")]
+    public void BuildUavTileFilePath_PerFlight_UsesFlightIdDirectory(string root, int zoom, int x, int y, string flightIdString)
+    {
+        // Arrange
+        var storage = new StorageConfig { TilesDirectory = root };
+        var flightId = Guid.Parse(flightIdString);
+
+        // Act
+        var path = UavTileUploadHandler.BuildUavTileFilePath(storage, zoom, x, y, flightId);
+
+        // Assert
+        var expected = Path.Combine(root, "uav", flightIdString, zoom.ToString(), x.ToString(), y + ".jpg");
+        path.Should().Be(expected,
+            "AZ-503 AC-11: UAV file paths follow `./tiles/uav/{flight_id}/{zoom}/{x}/{y}.jpg` so per-flight evidence is structurally isolated on disk");
+    }
+
+    [Fact]
+    public void BuildUavTileFilePath_DifferentFlights_ProduceDifferentPaths()
+    {
+        // Arrange
+        var storage = new StorageConfig { TilesDirectory = "./tiles" };
+        var f1 = Guid.Parse("11111111-1111-1111-1111-111111111111");
+        var f2 = Guid.Parse("22222222-2222-2222-2222-222222222222");
+
+        // Act
+        var p1 = UavTileUploadHandler.BuildUavTileFilePath(storage, 18, 100, 200, f1);
+        var p2 = UavTileUploadHandler.BuildUavTileFilePath(storage, 18, 100, 200, f2);
+
+        // Assert
+        p1.Should().NotBe(p2, "AZ-503 AC-11: two flights uploading the same (z, x, y) cell must land at distinct paths");
+        p1.Should().Contain(f1.ToString());
+        p2.Should().Contain(f2.ToString());
     }
 }

SatelliteProvider.Tests/UavTileUploadHandlerTests.cs

@@ -56,7 +56,13 @@ public class UavTileUploadHandlerTests : IDisposable
         result.Response.Items[0].TileId.Should().NotBeNull();
         inserted.Should().HaveCount(1);
         inserted[0].Source.Should().Be(TileSourceConverter.ToWireValue(TileSource.Uav));
-        inserted[0].FilePath.Should().Contain(Path.Combine("uav", "18"));
+        // AZ-503: flight-anonymous upload (ValidMetadata has FlightId=null) uses the
+        // literal "none" segment between "uav" and the zoom directory.
+        inserted[0].FilePath.Should().Contain(Path.Combine("uav", "none", "18"));
+        inserted[0].LocationHash.Should().NotBe(Guid.Empty,
+            "AZ-503: location_hash must be deterministic UUIDv5(TILE_NAMESPACE, \"z/x/y\")");
+        inserted[0].ContentSha256.Should().NotBeNullOrEmpty(
+            "AZ-503 AC-7: content_sha256 must be persisted for every UAV upload");
         File.Exists(inserted[0].FilePath).Should().BeTrue();
     }
 
@@ -170,6 +176,74 @@ public class UavTileUploadHandlerTests : IDisposable
         result.EnvelopeError.Should().Contain("Invalid `metadata` JSON");
     }
 
+    [Fact]
+    public async Task HandleAsync_TwoFlightsSameCell_ProduceDistinctIdsAndPathsButSameLocationHash()
+    {
+        // Arrange — AZ-503 AC-3 + AC-11: two flights uploading the same (z, x, y).
+        var jpegA = UavTileImageFactory.CreateRandomJpeg();
+        var jpegB = UavTileImageFactory.CreateRandomJpeg();
+        var f1 = Guid.Parse("11111111-1111-1111-1111-111111111111");
+        var f2 = Guid.Parse("22222222-2222-2222-2222-222222222222");
+        var metaA = ValidMetadata() with { FlightId = f1 };
+        var metaB = ValidMetadata() with { FlightId = f2 };
+        var (handler, repo) = BuildHandler();
+        var inserted = new List<TileEntity>();
+        repo.Setup(r => r.InsertAsync(It.IsAny<TileEntity>()))
+            .ReturnsAsync((TileEntity e) => e.Id)
+            .Callback<TileEntity>(e => inserted.Add(e));
+
+        // Act
+        await handler.HandleAsync(
+            JsonSerializer.Serialize(new UavTileBatchMetadataPayload { Items = { metaA } }),
+            new List<UavUploadFile> { new("a.jpg", "image/jpeg", jpegA) });
+        await handler.HandleAsync(
+            JsonSerializer.Serialize(new UavTileBatchMetadataPayload { Items = { metaB } }),
+            new List<UavUploadFile> { new("b.jpg", "image/jpeg", jpegB) });
+
+        // Assert
+        inserted.Should().HaveCount(2);
+        inserted[0].FlightId.Should().Be(f1);
+        inserted[1].FlightId.Should().Be(f2);
+        inserted[0].Id.Should().NotBe(inserted[1].Id, "AC-3: per-flight rows must have distinct deterministic ids");
+        inserted[0].LocationHash.Should().Be(inserted[1].LocationHash,
+            "AC-3: both rows share the same location_hash because (z, x, y) is identical");
+        inserted[0].FilePath.Should().NotBe(inserted[1].FilePath,
+            "AC-11: per-flight on-disk paths must differ");
+        inserted[0].FilePath.Should().Contain(f1.ToString());
+        inserted[1].FilePath.Should().Contain(f2.ToString());
+        File.Exists(inserted[0].FilePath).Should().BeTrue();
+        File.Exists(inserted[1].FilePath).Should().BeTrue();
+    }
+
+    [Fact]
+    public async Task HandleAsync_IdenticalUpload_ProducesIdenticalIdAndDeterministicContentSha()
+    {
+        // Arrange — AZ-503 AC-2 + AC-7: same inputs → same UUIDv5 + same SHA-256.
+        var jpeg = UavTileImageFactory.CreateRandomJpeg();
+        var meta = ValidMetadata() with { FlightId = Guid.Parse("33333333-3333-3333-3333-333333333333") };
+        var (handler, repo) = BuildHandler();
+        var inserted = new List<TileEntity>();
+        repo.Setup(r => r.InsertAsync(It.IsAny<TileEntity>()))
+            .ReturnsAsync((TileEntity e) => e.Id)
+            .Callback<TileEntity>(e => inserted.Add(e));
+
+        // Act
+        await handler.HandleAsync(
+            JsonSerializer.Serialize(new UavTileBatchMetadataPayload { Items = { meta } }),
+            new List<UavUploadFile> { new("first.jpg", "image/jpeg", jpeg) });
+        await handler.HandleAsync(
+            JsonSerializer.Serialize(new UavTileBatchMetadataPayload { Items = { meta } }),
+            new List<UavUploadFile> { new("second.jpg", "image/jpeg", jpeg) });
+
+        // Assert
+        inserted.Should().HaveCount(2);
+        inserted[0].Id.Should().Be(inserted[1].Id, "AC-2: identical inputs must produce identical deterministic ids");
+        inserted[0].LocationHash.Should().Be(inserted[1].LocationHash);
+        inserted[0].ContentSha256.Should().BeEquivalentTo(inserted[1].ContentSha256,
+            "AC-7: identical JPEG bodies must produce identical SHA-256 digests");
+        inserted[0].ContentSha256!.Length.Should().Be(32, "SHA-256 always produces 32 bytes");
+    }
+
     private (UavTileUploadHandler Handler, Mock<ITileRepository> Repo) BuildHandler(UavQualityConfig? quality = null)
     {
         var qualityConfig = quality ?? new UavQualityConfig();

SatelliteProvider.Tests/Uuidv5Tests.cs

@@ -0,0 +1,101 @@
+using FluentAssertions;
+using SatelliteProvider.Common.Utils;
+
+namespace SatelliteProvider.Tests;
+
+// AZ-503 AC-1: Uuidv5.Create must produce byte-identical output to Python's
+// stdlib `uuid.uuid5(namespace, name)`. Expected values below were generated
+// against TILE_NAMESPACE = 5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c using Python
+// 3.x's `uuid` module and pasted as fixed-string assertions (per AZ-503 spec
+// Risk 2 mitigation — vectors are explicit, not computed at test time).
+//
+// The cross-repo contract: gps-denied-onboard `c6_tile_cache/_uuid.py` MUST
+// use the SAME namespace constant and Python's stdlib `uuid.uuid5`. Both sides
+// therefore compute identical IDs for identical (namespace, name) inputs.
+public class Uuidv5Tests
+{
+    [Theory]
+    [InlineData("18/12345/23456/google_maps/00000000-0000-0000-0000-000000000000", "89e9514c-066d-5015-973f-ac42758ebf37")]
+    [InlineData("18/12345/23456", "38b26f49-a966-5121-aaf4-9cc476f57869")]
+    [InlineData("15/0/0/google_maps/00000000-0000-0000-0000-000000000000", "82a17784-50f3-58e2-b3a1-5da8224ff19d")]
+    [InlineData("20/1048575/1048575/uav/11111111-2222-3333-4444-555555555555", "9aaefb75-68c1-5691-89b4-3552323ef5de")]
+    [InlineData("16/76800/50331/google_maps/00000000-0000-0000-0000-000000000000", "88576e42-70ae-5977-a809-014d1448b012")]
+    [InlineData("18/12345/23456/uav/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "7d3c86e8-ce9b-5e40-9a08-8ffe6bab346a")]
+    [InlineData("0/0/0/google_maps/00000000-0000-0000-0000-000000000000", "d6557888-270b-59a9-9f21-652fdd0a9e50")]
+    [InlineData("simple-ascii-name", "d33497cd-8017-5ed0-9f9a-b6ff3c852b2a")]
+    [InlineData("unicode-naïveté-✓", "06710360-b8f0-5fe0-8f0a-5e934216e536")]
+    [InlineData("18/76800/50331", "5993e42c-a647-5802-b3a4-50105365832c")]
+    [InlineData("17/57842/41320/uav/12345678-1234-1234-1234-123456789012", "c5a0cac0-7155-5e49-91b8-f29bb0342a96")]
+    public void Create_MatchesPythonUuid5_ForReferenceVectors(string name, string expectedUuid)
+    {
+        // Act
+        var result = Uuidv5.Create(Uuidv5.TileNamespace, name);
+
+        // Assert
+        result.Should().Be(Guid.Parse(expectedUuid),
+            $"C# Uuidv5.Create must match Python uuid.uuid5({Uuidv5.TileNamespace}, \"{name}\") = {expectedUuid}");
+    }
+
+    [Fact]
+    public void Create_IsDeterministic()
+    {
+        // Arrange
+        const string name = "18/12345/23456/google_maps/00000000-0000-0000-0000-000000000000";
+
+        // Act
+        var first = Uuidv5.Create(Uuidv5.TileNamespace, name);
+        var second = Uuidv5.Create(Uuidv5.TileNamespace, name);
+
+        // Assert
+        first.Should().Be(second, "deterministic algorithm must produce identical output for identical inputs");
+    }
+
+    [Fact]
+    public void Create_ProducesVersion5AndRfc4122Variant()
+    {
+        // Arrange
+        var name = "any-name";
+
+        // Act
+        var uuid = Uuidv5.Create(Uuidv5.TileNamespace, name);
+        var bytes = uuid.ToByteArray();
+        // Guid.ToByteArray returns mixed-endian; for version/variant bits we
+        // need big-endian byte 6 (version) and byte 8 (variant). Reconstruct
+        // the big-endian view: bytes 0..3 reversed, 4..5 reversed, 6..7
+        // reversed, 8..15 as-is.
+        var bigEndian = new byte[16];
+        bigEndian[0] = bytes[3]; bigEndian[1] = bytes[2]; bigEndian[2] = bytes[1]; bigEndian[3] = bytes[0];
+        bigEndian[4] = bytes[5]; bigEndian[5] = bytes[4];
+        bigEndian[6] = bytes[7]; bigEndian[7] = bytes[6];
+        Array.Copy(bytes, 8, bigEndian, 8, 8);
+
+        // Assert
+        ((bigEndian[6] & 0xF0) >> 4).Should().Be(5, "version nibble (upper 4 bits of byte 6) must be 5 per RFC 9562 §5.5");
+        (bigEndian[8] & 0xC0).Should().Be(0x80, "variant bits (upper 2 of byte 8) must be 10 per RFC 4122 variant");
+    }
+
+    [Fact]
+    public void Create_DifferentNamesProduceDifferentUuids()
+    {
+        // Arrange
+        var name1 = "18/12345/23456/google_maps/00000000-0000-0000-0000-000000000000";
+        var name2 = "18/12345/23456/google_maps/11111111-1111-1111-1111-111111111111";
+
+        // Act
+        var uuid1 = Uuidv5.Create(Uuidv5.TileNamespace, name1);
+        var uuid2 = Uuidv5.Create(Uuidv5.TileNamespace, name2);
+
+        // Assert
+        uuid1.Should().NotBe(uuid2, "different flight_id values must produce different tile ids");
+    }
+
+    [Fact]
+    public void Create_ThrowsOnNullName()
+    {
+        // Act
+        var act = () => Uuidv5.Create(Uuidv5.TileNamespace, null!);
+
+        // Assert
+        act.Should().Throw<ArgumentNullException>();
+    }
+}