user-engine/docs/operability.md

Operability

Diagnostics

Use readiness() for dependency checks and operability_snapshot() for runtime counters and invariant checks. The snapshot currently reports store readiness, audit correlation completeness, outbox diagnostic availability, and counts for users, accounts, tenant accounts, memberships, applications, catalogs, profile values, audit records, and pending outbox events.

Structured Logs

Use structured_log_context(correlation_id=..., tenant=..., actor=...) as the base log envelope. Adapters should add transport details around that envelope without dropping correlation id or tenant.

Outbox Drain

outbox_diagnostics() reports pending event count, event type counts, and the oldest pending correlation id. A real outbox drain adapter should publish events idempotently by event_id, retain correlation_id, and only mark delivery after the sink acknowledges receipt.

Cache Status

ClaimsEnrichmentProjectionCache.status() reports entry count and cached tenant, application, and user keys. Token issuers must invalidate affected users after profile, membership, or catalog changes before minting enriched claims.

Runbook Checks

1. Run make test-conformance.
2. Confirm readiness().ready is true.
3. Confirm operability_snapshot().issues is empty.
4. Confirm pending outbox events are either drained or expected for the local environment.
5. Confirm production identity adapters reject local, expired, and missing-tenant claims.