[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/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);