feat: mail service

integration/README.md

@@ -8,6 +8,12 @@ Each suite must raise real service processes, speak only over public HTTP/gRPC/R
 ```text
 integration/
 ├── README.md
+├── authsessionmail/
+│   ├── authsession_mail_test.go
+│   └── harness_test.go
+├── gatewayauthsessionmail/
+│   ├── gateway_authsession_mail_test.go
+│   └── harness_test.go
 ├── authsessionuser/
 │   ├── authsession_user_test.go
 │   └── harness_test.go
@@ -33,6 +39,8 @@ integration/
         ├── keys.go
         ├── mail_stub.go
         ├── process.go
+        ├── redis_container.go
+        ├── smtp_capture.go
         └── user_stub.go
 ```
 
@@ -48,11 +56,20 @@ integration/
 
 - `gatewayauthsession` verifies the integration boundary between real `Edge Gateway` and real `Auth / Session Service`.
 - `authsessionuser` verifies the integration boundary between real `Auth / Session Service` and real `User Service`.
+- `authsessionmail` verifies the integration boundary between real `Auth / Session Service` and real `Mail Service`.
+- `gatewayauthsessionmail` verifies the public auth flow across real `Edge Gateway`, real `Auth / Session Service`, and real `Mail Service`.
 - `gatewayuser` verifies the direct authenticated self-service boundary between real `Edge Gateway` and real `User Service`.
 - `gatewayauthsessionuser` verifies the full public-auth plus authenticated-account chain across real `Edge Gateway`, real `Auth / Session Service`, and real `User Service`.
 
-The current fast suites use one isolated `miniredis` instance plus either
+The current fast suites still use one isolated `miniredis` instance plus either
 real downstream processes or external stateful HTTP stubs where appropriate.
+`authsessionmail` and `gatewayauthsessionmail` are the deliberate exceptions:
+they use one real Redis container through `testcontainers-go`, because those
+boundaries must exercise the real Redis-backed `Mail Service` runtime.
+`authsessionmail` additionally contains one targeted SMTP-capture scenario for
+the real `smtp` provider path, while `gatewayauthsessionmail` keeps `Mail
+Service` in `stub` mode and extracts the confirmation code through the trusted
+operator delivery surface.
 
 ## Running
 
@@ -62,6 +79,8 @@ Run from the module directory:
 cd integration
 go test ./gatewayauthsession/...
 go test ./authsessionuser/...
+go test ./authsessionmail/...
+go test ./gatewayauthsessionmail/...
 go test ./gatewayuser/...
 go test ./gatewayauthsessionuser/...
 ```
@@ -71,6 +90,8 @@ Useful regression commands after boundary changes:
 ```bash
 go test ./gatewayauthsession/...
 go test ./authsessionuser/...
+go test ./authsessionmail/...
+go test ./gatewayauthsessionmail/...
 go test ./gatewayuser/...
 go test ./gatewayauthsessionuser/...
 cd ../gateway && go test ./...
@@ -88,8 +109,17 @@ Do not use `go test ./...` from the repository root. The repository is organized
 4. Add new helpers to `internal/contracts/<contract>/` only when they describe a reusable public wire contract.
 5. Prefer fast deterministic infrastructure by default: in-memory test doubles, `httptest` stubs, and `miniredis`.
 
-## Future Real Redis Smoke Suites
+## Real Redis Suites
 
 Fast suites stay on `miniredis` by default.
-When a boundary needs one real Redis smoke suite later, keep it in the same boundary package and gate it explicitly with environment-driven configuration such as `INTEGRATION_REAL_REDIS_ADDR`.
-That smoke suite should complement, not replace, the deterministic `miniredis` coverage.
+When one boundary explicitly needs real Redis semantics, prefer a package-local
+container setup through `testcontainers-go` plus reusable helpers in
+`internal/harness`, as done by `authsessionmail` and
+`gatewayauthsessionmail`.
+
+Current rule of thumb:
+
+- use `miniredis` when the boundary does not depend on Redis persistence or
+  scheduling behavior
+- use `testcontainers-go` only when the real Redis process materially changes
+  the behavior being verified