Design: a user-directory protocol so modules stop importing users.models (Keycloak installs break) #501

Tier 2: structural (needs a design note first)

Problem

Keycloak is meant to replace users, but several modules reach into users.models directly, bypassing users/contracts/:

• audit_log/resolve.py:31-32, a module-level import
• dashboard/stats.py:15
• permissions/service.py:25,61,75,129,147,287, six lazy imports
• api_tokens/service.py:89,160 and api_tokens/resolver.py:59
• auth/contracts/schemas.py:13: the provider-neutral contract refers to users.User under TYPE_CHECKING, and a comment admits the cycle

discovery.py:201-204 only warns when a depends_on target is missing. A Keycloak-only install therefore boots and fails later, at import or request time.

Related duplication and cycles:

• file_storage/resolve.py:30-66 is a near copy of users/audit.py:29-50: parse the UUID, select id, email, full_name, return full_name or email. audit_log/resolve.py:38-50 itself warns that two copies are "two chances for the same row to be called two things".
• users ↔ audit_log form a cycle. audit_log declares depends_on=[Users], while users/admin/recent_activity.py:151,172-173 lazily imports audit_log.resolve and audit_log.service.

Proposal

• Add a UserDirectory protocol in core (get_label(ids), exists(id), count(), and possibly search), registered on app.state by whichever auth-provider module is installed (users or keycloak).
• Port the importers listed above to it. Delete the duplicated resolver.
• Have audit_log contribute the recent-activity card through a provider hook rather than users importing audit_log.
• In strict (production) discovery, make a missing depends_on target an error.