[AZ-794] [AZ-795] [AZ-796] Strict input validation + z/x/y rename

AZ-794: rename inventory wire fields tileZoom/tileX/tileY -> z/x/y
to match the slippy-map URL convention. Contract bumped to v2.0.0.

AZ-795: shared validation infrastructure -- FluentValidation +
ValidationEndpointFilter + GlobalValidatorConfig (camelCase paths).
GlobalExceptionHandler now converts JsonException (UnmappedMember +
JsonRequired) into RFC 7807 ValidationProblemDetails. JSON layer
hardened with UnmappedMemberHandling.Disallow + camelCase naming
policy. New error-shape.md contract.

AZ-796: InventoryRequestValidator covers 9 rules (XOR tiles vs
locationHashes, cap 1000, z 0..22, x/y in slippy bounds, hash
length/charset). 16 unit tests + 16 integration tests + a manual
curl probe script.

Adjacent fixes uncovered by the new strict layer:
- IdempotentPostTests RoutePoint payload corrected to lat/lon
  (the DTO has used JsonPropertyName for ages; previously silently
  ignored under PascalCase fallback).
- TileInventoryTests slippy x/y reduced to fit z=18 bounds.
- docker-compose.yml host port for Postgres moved 5432 -> 5433 to
  avoid sibling-project conflict; appsettings.Development + README
  + AGENTS + architecture + containerization docs aligned.

New coderule (suite + repo): API consumer-facing OpenAPI
descriptions must not contain task IDs, contract filenames, or
version-bump history -- internal change tracking belongs in
commits/contract docs/changelogs. Existing offending descriptions
in Program.cs cleaned up.

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

SatelliteProvider.Api/Validators/GlobalValidatorConfig.cs

@@ -0,0 +1,31 @@
+using FluentValidation;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-795 / AZ-796: process-wide FluentValidation configuration shared by the
+// API host and unit tests. Tests must call ApplyOnce() in their fixture setup
+// so the property-name casing they assert against matches what the running
+// API will produce — see `_docs/02_document/contracts/api/error-shape.md`
+// invariant Inv-4 (camelCase paths in `errors` map).
+public static class GlobalValidatorConfig
+{
+    private static readonly object _gate = new();
+    private static bool _applied;
+
+    public static void ApplyOnce()
+    {
+        lock (_gate)
+        {
+            if (_applied) return;
+
+            ValidatorOptions.Global.PropertyNameResolver = (type, member, expression) =>
+            {
+                var name = member?.Name;
+                if (string.IsNullOrEmpty(name)) return null;
+                return char.ToLowerInvariant(name[0]) + name[1..];
+            };
+
+            _applied = true;
+        }
+    }
+}

SatelliteProvider.Api/Validators/InventoryRequestValidator.cs

@@ -0,0 +1,73 @@
+using FluentValidation;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-796: FluentValidation rules for POST /api/satellite/tiles/inventory.
+// Wired through ValidationEndpointFilter<TileInventoryRequest> at endpoint
+// registration time (`WithValidation<TileInventoryRequest>()` in Program.cs).
+// Failures are converted to RFC 7807 ValidationProblemDetails per
+// `_docs/02_document/contracts/api/error-shape.md` v1.0.0.
+//
+// Required-field detection (rules 5+) is partially handled at the deserializer
+// level via `[JsonRequired]` on TileCoord.Z/X/Y plus
+// `JsonSerializerOptions.UnmappedMemberHandling.Disallow` (AZ-795). This
+// validator covers the non-deserializer-detectable rules: XOR populated,
+// per-array entry caps, and slippy-map range constraints.
+public sealed class InventoryRequestValidator : AbstractValidator<TileInventoryRequest>
+{
+    public InventoryRequestValidator()
+    {
+        RuleFor(req => req).Custom((req, ctx) =>
+        {
+            var hasTiles = req.Tiles is { Count: > 0 };
+            var hasHashes = req.LocationHashes is { Count: > 0 };
+            if (hasTiles == hasHashes)
+            {
+                ctx.AddFailure(
+                    "$",
+                    "Populate exactly one of `tiles` or `locationHashes` (sending both, or neither, is not allowed).");
+            }
+        });
+
+        RuleFor(req => req.Tiles!.Count)
+            .LessThanOrEqualTo(TileInventoryLimits.MaxEntriesPerRequest)
+            .OverridePropertyName("tiles")
+            .WithMessage($"`tiles` must contain at most {TileInventoryLimits.MaxEntriesPerRequest} entries.")
+            .When(req => req.Tiles is not null);
+
+        RuleFor(req => req.LocationHashes!.Count)
+            .LessThanOrEqualTo(TileInventoryLimits.MaxEntriesPerRequest)
+            .OverridePropertyName("locationHashes")
+            .WithMessage($"`locationHashes` must contain at most {TileInventoryLimits.MaxEntriesPerRequest} entries.")
+            .When(req => req.LocationHashes is not null);
+
+        RuleForEach(req => req.Tiles)
+            .SetValidator(new TileCoordValidator())
+            .When(req => req.Tiles is not null);
+    }
+}
+
+internal sealed class TileCoordValidator : AbstractValidator<TileCoord>
+{
+    private const int MaxZoom = 22;
+
+    public TileCoordValidator()
+    {
+        RuleFor(c => c.Z)
+            .InclusiveBetween(0, MaxZoom)
+            .WithMessage($"`z` must be between 0 and {MaxZoom} (slippy-map zoom range).");
+
+        RuleFor(c => c.X)
+            .GreaterThanOrEqualTo(0)
+            .WithMessage("`x` must be ≥ 0.")
+            .Must((coord, x) => coord.Z >= 0 && coord.Z <= MaxZoom && x < (1L << coord.Z))
+            .WithMessage(coord => $"`x` must be < 2^z = {(coord.Z >= 0 && coord.Z <= MaxZoom ? (1L << coord.Z).ToString() : "<invalid z>")} for z={coord.Z}.");
+
+        RuleFor(c => c.Y)
+            .GreaterThanOrEqualTo(0)
+            .WithMessage("`y` must be ≥ 0.")
+            .Must((coord, y) => coord.Z >= 0 && coord.Z <= MaxZoom && y < (1L << coord.Z))
+            .WithMessage(coord => $"`y` must be < 2^z = {(coord.Z >= 0 && coord.Z <= MaxZoom ? (1L << coord.Z).ToString() : "<invalid z>")} for z={coord.Z}.");
+    }
+}

SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs

@@ -0,0 +1,42 @@
+using FluentValidation;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-795: shared validation infrastructure. A generic IEndpointFilter that
+// resolves IValidator<T> from DI for the first argument of type T in the
+// invoked endpoint and returns RFC 7807 ValidationProblemDetails (HTTP 400)
+// with a structured `errors` map when the validator rejects. When validation
+// passes, the filter forwards to the next stage unchanged.
+//
+// The filter is generic per request type; per-endpoint wire-up is done via
+// `RouteHandlerBuilder.WithValidation<T>()` (see ValidationEndpointFilterExtensions).
+// Per AZ-795 Outcome: callers must NOT need per-endpoint try/catch boilerplate;
+// the filter provides the uniform error contract documented in
+// `_docs/02_document/contracts/api/error-shape.md`.
+public sealed class ValidationEndpointFilter<T> : IEndpointFilter where T : class
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var argument = context.Arguments.OfType<T>().FirstOrDefault();
+        if (argument is null)
+        {
+            return await next(context);
+        }
+
+        var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
+        if (validator is null)
+        {
+            return await next(context);
+        }
+
+        var result = await validator.ValidateAsync(argument, context.HttpContext.RequestAborted);
+        if (!result.IsValid)
+        {
+            return Results.ValidationProblem(result.ToDictionary());
+        }
+
+        return await next(context);
+    }
+}

SatelliteProvider.Api/Validators/ValidationEndpointFilterExtensions.cs

@@ -0,0 +1,19 @@
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-795: ergonomic extension method for opting an endpoint into
+// FluentValidation. Applied at MapPost/MapGet registration time:
+//
+//   app.MapPost("/api/satellite/tiles/inventory", GetTilesInventory)
+//      .WithValidation<TileInventoryRequest>();
+//
+// One line per endpoint; no per-handler try/catch boilerplate; uniform
+// RFC 7807 error shape — see `_docs/02_document/contracts/api/error-shape.md`.
+public static class ValidationEndpointFilterExtensions
+{
+    public static RouteHandlerBuilder WithValidation<T>(this RouteHandlerBuilder builder)
+        where T : class
+    {
+        builder.AddEndpointFilter<ValidationEndpointFilter<T>>();
+        return builder;
+    }
+}