API, sessions, or migrations fail

Symptoms

A listener is unavailable, the process refuses startup, control requests are unauthorized, or a query reads no tenants.

Likely causes

Invalid typed configuration, failed schema/topology migration, unavailable dependency, wrong certificate domain, expired/process-lost session, policy denial, or certificate-derived query scope. A second control replica does not honor the first's in-memory sessions.

Diagnosis

Inspect docker compose -f deploy/compose.yaml ps -a and the relevant migrator/API logs. Check /readyz through the configured operations listener. Separate transport failure, structured refusal, and empty authorized query result. Check the route's required guard and handler tenant checks.

Resolution

Correct configuration and complete the owning migration. Re-establish a session on the correct process after restart. Supply an authorized query certificate scope instead of adding a user-controlled tenant parameter. Keep raw driver errors out of external clients.

Verification

Migrations exit successfully, readiness reports the relevant dependencies ready, and an authorized request succeeds while the corresponding unauthorized request remains refused.

Continue with health and metrics and failure semantics.

Source evidence

Reviewed against the source baseline. Seagull-backend-v2/internal/control/guard.go · Seagull-backend-v2/internal/control/sessions.go · Seagull-backend-v2/internal/hunt/scope.go · Seagull-backend-v2/deploy/compose.yaml.