[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>

scripts/run-tests.sh

@@ -11,7 +11,7 @@ trap cleanup EXIT
 
 usage() {
     cat <<EOF
-Usage: $(basename "$0") [--unit-only | --smoke | --full] [--skip-format]
+Usage: $(basename "$0") [--unit-only | --smoke | --full] [--skip-format] [--keep-state]
 
 Modes:
   --unit-only   Run only the .NET unit test project (no Docker Compose, no integration tests)
@@ -20,6 +20,8 @@ Modes:
 
 Flags:
   --skip-format Skip the dotnet format --verify-no-changes check (use only for emergency runs)
+  --keep-state  Skip the AZ-493 integration test DB-reset hook so leftover rows from the
+                previous run remain in Postgres. Useful for debugging a failed run.
 
 Environment:
   GOOGLE_MAPS_API_KEY  Required for any integration test mode (loaded from .env or shell env).
@@ -31,12 +33,14 @@ EOF
 
 mode="full"
 skip_format="false"
+keep_state="false"
 for arg in "$@"; do
     case "$arg" in
         --unit-only)   mode="unit"; ;;
         --smoke)       mode="smoke"; ;;
         --full)        mode="full"; ;;
         --skip-format) skip_format="true"; ;;
+        --keep-state)  keep_state="true"; ;;
         -h|--help)     usage; exit 0; ;;
         "")            ;;
         *)             echo "Unknown argument: $arg"; usage; exit 2; ;;
@@ -98,8 +102,14 @@ docker run --rm -v "$PROJECT_ROOT:/src" -w /src mcr.microsoft.com/dotnet/sdk:8.0
     sh -c "dotnet restore SatelliteProvider.sln && dotnet test SatelliteProvider.Tests/SatelliteProvider.Tests.csproj --no-restore --configuration Release --collect:'XPlat Code Coverage' --results-directory /src/TestResults --logger 'console;verbosity=normal'"
 
 echo ""
-echo "Step 2: Integration tests (Docker Compose, mode=$mode)"
-INTEGRATION_TESTS_MODE="$mode" docker compose \
+echo "Step 2: Integration tests (Docker Compose, mode=$mode, keep_state=$keep_state)"
+INTEGRATION_KEEP_STATE_VALUE=""
+if [[ "$keep_state" == "true" ]]; then
+    INTEGRATION_KEEP_STATE_VALUE="1"
+fi
+INTEGRATION_TESTS_MODE="$mode" \
+INTEGRATION_KEEP_STATE="$INTEGRATION_KEEP_STATE_VALUE" \
+    docker compose \
     -f "$PROJECT_ROOT/docker-compose.yml" \
     -f "$PROJECT_ROOT/docker-compose.tests.yml" \
     up --build --abort-on-container-exit --exit-code-from integration-tests