fix(db): enforce global nullpool session budget

apps/api/tests/test_workload_database_identity_projection.py

@@ -196,6 +196,11 @@ def test_runtime_workloads_use_distinct_database_secret_projections() -> None:
         "awoooi-broker-db",
     }
 
+    api_env = _env_by_name(
+        _deployment_container("k8s/awoooi-prod/06-deployment-api.yaml", "api")
+    )
+    assert api_env["DATABASE_NULL_POOL_CONCURRENCY_LIMIT"]["value"] == "2"
+
 
 def test_api_and_worker_project_shared_secrets_explicitly() -> None:
     for path, container_name in (
@@ -217,6 +222,36 @@ def test_api_and_worker_project_shared_secrets_explicitly() -> None:
             assert secret_ref["optional"] is True
 
 
+def test_api_null_pool_cap_preserves_the_verified_role_headroom() -> None:
+    documents = yaml.safe_load_all(
+        (
+            REPO_ROOT / "k8s/awoooi-prod/06-deployment-api.yaml"
+        ).read_text()
+    )
+    deployment = next(
+        document
+        for document in documents
+        if document and document.get("kind") == "Deployment"
+    )
+    container = next(
+        item
+        for item in deployment["spec"]["template"]["spec"]["containers"]
+        if item["name"] == "api"
+    )
+    env = _env_by_name(container)
+    replica_count = int(deployment["spec"]["replicas"])
+    per_process_cap = int(
+        env["DATABASE_NULL_POOL_CONCURRENCY_LIMIT"]["value"]
+    )
+
+    role_connection_limit = 12
+    required_free_headroom = 8
+    assert replica_count == 2
+    assert replica_count * per_process_cap == (
+        role_connection_limit - required_free_headroom
+    )
+
+
 def test_workload_database_bootstrap_keeps_secret_values_off_output() -> None:
     script = (
         REPO_ROOT / "scripts/ops/awoooi-workload-db-identity-bootstrap.sh"
@@ -261,6 +296,7 @@ def test_workload_database_bootstrap_keeps_secret_values_off_output() -> None:
 
 def test_cd_uses_live_spec_rollback_and_non_mutating_post_verifier() -> None:
     workflow = (REPO_ROOT / ".gitea/workflows/cd.yaml").read_text()
+    normalized_workflow = " ".join(workflow.split())
 
     assert "WORKLOAD_DB_ROLLBACK_FILE" in workflow
     assert "WORKLOAD_DB_SECRET_PREEXISTENCE_FILE" in workflow
@@ -285,6 +321,28 @@ def test_cd_uses_live_spec_rollback_and_non_mutating_post_verifier() -> None:
     assert "API_PUBLIC_READINESS_ATTEMPTS" in workflow
     assert "API_HTTP_CONCURRENCY_ATTEMPTS" in workflow
     assert "API_HTTP_PROBE_SAFETY_RESERVE=4" in workflow
+    assert '"$API_DB_NULL_POOL_CONCURRENCY_LIMIT" -eq 2' in workflow
+    assert (
+        '"$API_DB_AVAILABLE_CONNECTION_HEADROOM" -ge '
+        '"$API_DB_REQUIRED_CONNECTION_BUDGET"'
+    ) in workflow
+    assert (
+        '"$WORKER_DB_AVAILABLE_CONNECTION_HEADROOM" -ge '
+        '"$WORKER_DB_REQUIRED_CONNECTION_BUDGET"'
+    ) in workflow
+    assert (
+        '"$BROKER_DB_AVAILABLE_CONNECTION_HEADROOM" -ge '
+        '"$BROKER_DB_REQUIRED_CONNECTION_BUDGET"'
+    ) in workflow
+    assert (
+        "available_connection_headroom >= required_connection_budget"
+        in normalized_workflow
+    )
+    assert (
+        '"$API_DB_AVAILABLE_CONNECTION_HEADROOM" -ge '
+        '"$API_DB_REPRESENTATIVE_PROBE_COUNT"'
+    ) not in workflow
+    assert "api_database_null_pool_concurrency_limit" in workflow
     assert "API_HTTP_CONCURRENCY_WORKERS" in workflow
     assert "API sequential readiness permanent HTTP status" in workflow
     assert "api/v1/health/ready" in workflow