[AZ-493] Cycle 3 batch 3: integration test DB-reset hook

AZ-493 (2 SP): replace the cycle-2 wallclock-seeded _coordinateCounter
workaround with a proper Postgres state-reset hook that runs at
integration test runner startup, eliminating the per-source-unique-index
collision risk that the persistent docker-compose Postgres volume
introduced post-AZ-484.

The reset is split into two surfaces:

* SatelliteProvider.TestSupport.IntegrationTestResetGuard - pure
  static class, I/O-free, unit-tested. Two independent guards: (a)
  ASPNETCORE_ENVIRONMENT must equal "Testing", (b) DB_CONNECTION_STRING
  Host must be in the allowed-host list (postgres, localhost, 127.0.0.1).
  Failure of either guard surfaces a structured operator-friendly
  InvalidOperationException.
* SatelliteProvider.IntegrationTests.IntegrationTestDatabaseReset -
  instance class owning the Npgsql side effects. Calls the guard then
  runs TRUNCATE TABLE route_regions, route_points, routes, regions,
  tiles RESTART IDENTITY CASCADE inside a single Npgsql transaction.

Spec-vs-reality: the task spec prescribed "DB name contains _test" as
Guard 2; the actual compose file uses Database=satelliteprovider and
DB rename is gated on user confirmation per coderule.mdc. Substituted
a Host allowlist as the equivalent guard (intent identical: reject
remote / production hosts). Recorded as Low/Spec-Gap in the review.

Program.cs adds --keep-state CLI flag and INTEGRATION_KEEP_STATE env
var (1/true) opt-outs so a developer can inspect leftover state when
debugging. Startup banner shows which path executed.
docker-compose.tests.yml gets ASPNETCORE_ENVIRONMENT=Testing +
passthrough for INTEGRATION_KEEP_STATE. scripts/run-tests.sh wires the
--keep-state flag through to compose.

UavUploadTests._coordinateCounter wallclock seed is retained as
defense-in-depth (per the task spec's implementer choice). The reset
is the primary isolation path; the seed is the belt-and-suspenders
fallback for --keep-state runs.

8 new unit tests in SatelliteProvider.Tests/TestSupport/
IntegrationTestResetGuardTests.cs cover Production/Staging/missing-env
throw, allowed-host case-insensitivity, disallowed-host rejection
with representative prod hostnames, and the AllowedHosts contract.

tests_integration.md gains a Reliability section that documents the
hook, the two guards, the truncate order, and the three opt-out forms.
module-layout.md TestSupport entry extended with the new pure guard
and the explicit "Npgsql stays in IntegrationTests" boundary.

Test-suite gate (AC-6) deferred to Step 16 Final Test Run per implement
skill convention. Per-batch review verdict: PASS_WITH_WARNINGS with 1
Low (spec-vs-reality on Guard 2, non-blocking).

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

SatelliteProvider.IntegrationTests/IntegrationTestDatabaseReset.cs

@@ -0,0 +1,42 @@
+using Npgsql;
+using SatelliteProvider.TestSupport;
+
+namespace SatelliteProvider.IntegrationTests;
+
+public sealed class IntegrationTestDatabaseReset
+{
+    public static readonly IReadOnlyList<string> TruncateOrder =
+        new[] { "route_regions", "route_points", "routes", "regions", "tiles" };
+
+    private readonly string _connectionString;
+
+    public IntegrationTestDatabaseReset(string connectionString)
+    {
+        if (string.IsNullOrWhiteSpace(connectionString))
+        {
+            throw new ArgumentException("Connection string must not be empty.", nameof(connectionString));
+        }
+        _connectionString = connectionString;
+    }
+
+    public async Task EnsureCleanStateAsync()
+    {
+        var environment = Environment.GetEnvironmentVariable(IntegrationTestResetGuard.EnvironmentEnvVar);
+        var builder = new NpgsqlConnectionStringBuilder(_connectionString);
+        IntegrationTestResetGuard.EnsureGuardPassesOrThrow(environment, builder.Host);
+
+        await using var connection = new NpgsqlConnection(_connectionString);
+        await connection.OpenAsync();
+
+        await using var transaction = await connection.BeginTransactionAsync();
+        var truncateSql = $"TRUNCATE TABLE {string.Join(", ", TruncateOrder)} RESTART IDENTITY CASCADE";
+        await using (var cmd = new NpgsqlCommand(truncateSql, connection, transaction))
+        {
+            await cmd.ExecuteNonQueryAsync();
+        }
+        await transaction.CommitAsync();
+
+        Console.WriteLine(
+            $"✓ Integration test DB reset complete: truncated [{string.Join(", ", TruncateOrder)}] on {builder.Host}/{builder.Database}");
+    }
+}

SatelliteProvider.IntegrationTests/Program.cs

@@ -19,6 +19,15 @@ class Program
             TestRunMode.Smoke = modeEnv == "smoke";
         }
 
+        // AZ-493: opt-out of the startup DB reset so a developer can inspect leftover state.
+        var keepStateEnv = Environment.GetEnvironmentVariable("INTEGRATION_KEEP_STATE")?.Trim();
+        var keepState = args.Any(a => a.Equals("--keep-state", StringComparison.OrdinalIgnoreCase))
+            || string.Equals(keepStateEnv, "1", StringComparison.Ordinal)
+            || string.Equals(keepStateEnv, "true", StringComparison.OrdinalIgnoreCase);
+
+        var connectionString = Environment.GetEnvironmentVariable("DB_CONNECTION_STRING")
+            ?? "Host=postgres;Port=5432;Database=satelliteprovider;Username=postgres;Password=postgres";
+
         string jwtSecret;
         try
         {
@@ -35,6 +44,7 @@ class Program
         Console.WriteLine("=========================");
         Console.WriteLine($"API URL : {apiUrl}");
         Console.WriteLine($"Mode    : {(TestRunMode.Smoke ? "smoke (fast subset, tightened timeouts)" : "full")}");
+        Console.WriteLine($"State   : {(keepState ? "keep (DB reset skipped)" : "reset (clean DB at startup, AZ-493)")}");
         Console.WriteLine($"Auth    : JWT_SECRET resolved ({System.Text.Encoding.UTF8.GetByteCount(jwtSecret)} bytes)");
         Console.WriteLine();
 
@@ -52,6 +62,24 @@ class Program
             Console.WriteLine("Waiting for API to be ready...");
             await WaitForApiReady(httpClient);
             Console.WriteLine("✓ API is ready");
+
+            if (keepState)
+            {
+                Console.WriteLine("⚠ --keep-state / INTEGRATION_KEEP_STATE set; skipping DB reset (AZ-493)");
+            }
+            else
+            {
+                try
+                {
+                    await new IntegrationTestDatabaseReset(connectionString).EnsureCleanStateAsync();
+                }
+                catch (InvalidOperationException ex)
+                {
+                    Console.WriteLine($"❌ DB reset refused: {ex.Message}");
+                    return 1;
+                }
+            }
+
             Console.WriteLine();
 
             await JwtIntegrationTests.RunAll(apiUrl, jwtSecret);

SatelliteProvider.IntegrationTests/UavUploadTests.cs

@@ -356,6 +356,11 @@ public static class UavUploadTests
     // (named volume); a monotonic counter from 0 would collide with prior runs on
     // the per-source unique index, especially for tests that seed rows via raw
     // INSERT rather than the API's UPSERT path.
+    // Kept as defense-in-depth after AZ-493 introduced a Program.cs startup DB
+    // reset. If the reset is skipped via --keep-state OR fails silently, the
+    // wallclock seed still spreads coordinates across runs so the per-source
+    // unique index does not collide. Safe to remove if/when the DB-reset path
+    // becomes load-bearing for every run.
     private static int _coordinateCounter = (int)((DateTime.UtcNow.Ticks / TimeSpan.TicksPerSecond) % 1_000_000);
 
     private static (double Latitude, double Longitude) NextTestCoordinate()