[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.Common/DTO/UavTileMetadata.cs

@@ -3,6 +3,12 @@ namespace SatelliteProvider.Common.DTO;
 // AZ-488 / `uav-tile-upload.md` v1.0.0 — per-tile metadata supplied with each
 // batch item. `CapturedAt` is normalized to UTC by the upload handler before
 // reaching the persistence layer.
+//
+// AZ-503: `FlightId` is optional. When provided, two UAVs uploading the same
+// (z, x, y) cell from different flights coexist as distinct DB rows and write
+// to per-flight on-disk paths (./tiles/uav/{flight_id}/{z}/{x}/{y}.jpg). When
+// absent, the row is treated as flight-anonymous and the UPSERT collapses to
+// the AZ-484 "single row per (cell, source)" semantics via COALESCE-to-zero.
 public record UavTileMetadata
 {
     public double Latitude { get; init; }
@@ -10,6 +16,7 @@ public record UavTileMetadata
     public int TileZoom { get; init; }
     public double TileSizeMeters { get; init; }
     public DateTime CapturedAt { get; init; }
+    public Guid? FlightId { get; init; }
 }
 
 public record UavTileBatchMetadataPayload

SatelliteProvider.Common/Utils/Uuidv5.cs

@@ -0,0 +1,80 @@
+using System.Buffers.Binary;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace SatelliteProvider.Common.Utils;
+
+// AZ-503: pure-C# RFC 9562 (formerly RFC 4122 §4.3) UUIDv5 implementation.
+//
+// .NET 10 ships Guid.CreateVersion7 but NOT a version-5 builder, so we implement
+// the SHA-1-based algorithm here. Onboard `gps-denied-onboard/components/c6_tile_cache/_uuid.py`
+// MUST use the same TileNamespace constant and the same algorithm (Python's stdlib
+// uuid.uuid5 is identical by construction) so both sides of the wire compute
+// byte-identical IDs for the same (z, x, y, source, flight_id) inputs.
+//
+// Cross-repo namespace coordination: TileNamespace below is THE pinned value.
+// Any change here must be paired with the same change on the onboard side; the
+// AZ-503 task spec requires this and AC-1 (Python reference vectors) gates it.
+public static class Uuidv5
+{
+    // Pinned cross-repo namespace for tile identity. Must match
+    // gps-denied-onboard `c6_tile_cache/_uuid.py:TILE_NAMESPACE`.
+    // Chosen as a fresh random UUID (no semantic meaning beyond being a stable
+    // 128-bit constant shared between the two repos).
+    public static readonly Guid TileNamespace = new("5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c");
+
+    public static Guid Create(Guid namespaceId, string name)
+    {
+        ArgumentNullException.ThrowIfNull(name);
+
+        // Namespace UUIDs are concatenated as 16 bytes in network (big-endian)
+        // order. .NET's Guid.ToByteArray() returns mixed-endian (RFC 4122
+        // "Microsoft" layout), so we cannot use it directly — we must rebuild
+        // the byte array in big-endian order, matching what Python's
+        // uuid.UUID.bytes produces.
+        Span<byte> namespaceBytes = stackalloc byte[16];
+        WriteGuidBigEndian(namespaceId, namespaceBytes);
+
+        var nameBytes = Encoding.UTF8.GetBytes(name);
+
+        Span<byte> hash = stackalloc byte[20];
+        var buffer = new byte[16 + nameBytes.Length];
+        namespaceBytes.CopyTo(buffer);
+        Buffer.BlockCopy(nameBytes, 0, buffer, 16, nameBytes.Length);
+        if (!SHA1.TryHashData(buffer, hash, out _))
+        {
+            throw new InvalidOperationException("SHA-1 hash computation failed.");
+        }
+
+        // Take first 16 bytes, set version to 5 (upper nibble of byte 6) and
+        // variant to RFC 4122 (upper two bits of byte 8 set to `10`).
+        Span<byte> uuidBytes = stackalloc byte[16];
+        hash[..16].CopyTo(uuidBytes);
+        uuidBytes[6] = (byte)((uuidBytes[6] & 0x0F) | 0x50);
+        uuidBytes[8] = (byte)((uuidBytes[8] & 0x3F) | 0x80);
+
+        return ReadGuidBigEndian(uuidBytes);
+    }
+
+    private static void WriteGuidBigEndian(Guid value, Span<byte> destination)
+    {
+        Span<byte> mixed = stackalloc byte[16];
+        value.TryWriteBytes(mixed);
+        // Convert from Microsoft mixed-endian (first 3 fields little-endian) to
+        // network (big-endian) order.
+        BinaryPrimitives.WriteUInt32BigEndian(destination[..4], BinaryPrimitives.ReadUInt32LittleEndian(mixed[..4]));
+        BinaryPrimitives.WriteUInt16BigEndian(destination.Slice(4, 2), BinaryPrimitives.ReadUInt16LittleEndian(mixed.Slice(4, 2)));
+        BinaryPrimitives.WriteUInt16BigEndian(destination.Slice(6, 2), BinaryPrimitives.ReadUInt16LittleEndian(mixed.Slice(6, 2)));
+        mixed.Slice(8, 8).CopyTo(destination.Slice(8, 8));
+    }
+
+    private static Guid ReadGuidBigEndian(ReadOnlySpan<byte> bigEndian)
+    {
+        Span<byte> mixed = stackalloc byte[16];
+        BinaryPrimitives.WriteUInt32LittleEndian(mixed[..4], BinaryPrimitives.ReadUInt32BigEndian(bigEndian[..4]));
+        BinaryPrimitives.WriteUInt16LittleEndian(mixed.Slice(4, 2), BinaryPrimitives.ReadUInt16BigEndian(bigEndian.Slice(4, 2)));
+        BinaryPrimitives.WriteUInt16LittleEndian(mixed.Slice(6, 2), BinaryPrimitives.ReadUInt16BigEndian(bigEndian.Slice(6, 2)));
+        bigEndian.Slice(8, 8).CopyTo(mixed.Slice(8, 8));
+        return new Guid(mixed);
+    }
+}