Defer the Okta/notification fan-out to a post-response BackgroundTask

[somethingnew2-0]

Post-migration TODO item 10. The multi-Okta-call operations — ModifyGroupUsers, ModifyRoleGroups, DeleteGroup, and their composers ApproveAccessRequest / CreateApp / ApproveRoleRequest — committed the local DB state and then awaited a fan-out of Okta API calls plus notification dispatch before returning. That tail dominates the latency of those endpoints. It now runs in a FastAPI BackgroundTask after the response, so the HTTP response returns as soon as the local DB state commits.

How it works

Operations hand their fan-out batch to a request-scoped collector via defer_or_drain_fan_out. A defer_fan_out dependency on the six mutating routers registers the drain as a post-response BackgroundTask (and drains inline on the endpoint-error path, since the error response FastAPI builds won't carry the background task). Outside an HTTP request — CLI, syncer, MCP, direct execute() — there's no collector and the batch drains inline exactly as before, so a route that lacks the dependency degrades to correct-but-not-deferred, never incorrect.

Things worth a reviewer's attention

• Notification payloads are expunged from the session before deferral. This is the subtle part. The deferred drain runs after the router's db.expire_all() and (in prod) session teardown, and notification hooks read ORM attributes synchronously — so a deferred hook holding live ORM objects would raise MissingGreenlet/DetachedInstanceError and send_notification would silently drop the notification. Expunging detaches the payload with its loaded state intact, and only runs when the fan-out is actually being deferred (the inline path keeps objects attached for callers that reuse them). A dedicated test fails without it.
• Fan-out failures log at ERROR, not WARNING — Access surfaces the errors its plugins and Okta calls raise rather than swallowing them as warnings, matching the async plugin-hook dispatch. The failure still never propagates (DB state is committed; the syncer reconciles Okta drift).
• Lifecycle hooks and audit logging stay inline — the former uses the session and may mutate committed state; the latter is a fast local log call.
• The drain uses asyncio.wait (not asyncio.gather) so a cancelled request/drain doesn't tear down the in-flight Okta calls it trails.
• Under httpx ASGITransport the deferred drain completes within the awaited request, so existing Okta call-count assertions keep working unchanged.

Previously stacked on #481 and #511; both have merged, so this is now a single commit on main.

🤖 Generated with Claude Code