Run app-group-lifecycle plugin hooks after the response

[somethingnew2-0]

Summary

App-group-lifecycle plugin hooks no longer run on the request path. A fire is recorded as plain data and replayed from a post-response BackgroundTask, so a group create, rename, or membership change commits and answers the request without waiting on the plugin's reconciliation against an external system.

Stacked on #577. Base is brynna/google-group-manager-refactor-cf8e89; GitHub retargets this to main once #577 merges. It genuinely depends on that work — see below.

Motivation

These hooks were the slowest thing left on the request path. group_created on a plugin-managed app group does Okta plus whatever the plugin talks to (for the Google reference plugin: a lookup, a push-mapping create, and a wait for Okta to import), all before the user gets a response. Notifications and Okta calls were moved off the response path in #481; lifecycle hooks were the remaining holdout, and the reason they were is that they write, so the detached-snapshot trick notifications use does not apply to them.

#577 is what makes this tractable rather than an ecosystem migration. Before it, hooks received the raw AsyncSession and plugins used it directly, so deferring meant every operator's plugin had to survive running on a different session. After it, the only session reference on this path is inside invoke_app_group_lifecycle_hook, and the change is a host concern.

Design notes

A deferred fire carries ids, not objects. This deliberately does not reuse _fan_out.py: its primitive spawns with create_task at defer time, which would put a second coroutine on the live request session; and one request's fires are order-dependent. Replay re-loads the group by id, which is better than a snapshot would have been — a hook sees committed truth, and a group deleted (or converted out of being an app group) in the meantime is skipped rather than reconciled against a row that is no longer there.

The drain binds _session_scope, not just a session. ctx.set_group_description delegates to ModifyGroupDetails, which reaches for the ambient db.session. If that resolved to a different session than the one the context holds, its writes would land in a transaction nobody commits — silently persisting nothing. There is a test whose only job is to catch that.

One fire stays inline. ModifyGroupType fires group_deleted while the row is still an app group and deletes the app_group row immediately after; a replay would re-load a plain OktaGroup and drop the fire without a trace.

Ordering is unchanged. The lifecycle drain is registered ahead of the Okta/notification drain. Those Okta tasks are already in flight — operations spawn them with create_task and only the await was ever deferred — so hooks keep racing the pushes rather than newly trailing them. Making them trail is arguably more correct and is a separate question.

Losing a fire costs latency, not correctness. A pod killed between response and drain drops it; sync-app-groups re-converges on its next run, which is only true because #577 made sync_group per-group and idempotent.

The plugin interface addition, and why it's here

Deferring means a create/update response no longer carries status the hook writes, so the group page has to poll. Gating that on "pending" would have hardcoded the Google plugin's vocabulary into a client every operator shares — Access has no opinion on what a plugin's status values mean.

So AppGroupLifecyclePluginStatusProperty gains pending_values: the plugin names the values that mean "still converging", and the group page refreshes while a status sits on one. It is additive and defaults to opting out. Landing it now rather than as a follow-up because 2.0 is the window for interface changes, and because the polling it enables also fixes a case that predates this PR — a group parked in the Google plugin's "awaiting Okta import" state never updated without a manual reload.

The client also polls when a plugin that declares pending_values has written no status at all, which is what a freshly created group looks like before its first hook lands. Both signals are derived from data rather than navigation state, since two of the three post-submit paths do a full page reload.

Notes for reviewers

• The most consequential single line is the scope binding in run_deferred_lifecycle; the accompanying comment explains what breaks without it.
• The generated API client is regenerated in the same commit as the schema change, which the openapi-client-drift job requires. I learned that the hard way — the first push failed on it — so .claude/access-dev-testing.md now documents the gate and the offline regeneration CI uses, since npm run codegen otherwise wants a dev backend on 6060.
• The group-page poll is driven from state rather than a ref. The ref version looked right and did nothing: react-query re-reads refetchInterval when its options change, and a ref mutation does not re-render. It took watching the requests against a running backend to catch, and there is no page-level test infrastructure here that would have.
• Commit-by-commit works well here: commit 3 is the only one that changes behavior.

🤖 Generated with Claude Code