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, whether written audit records carry a correlation id, outbox
diagnostic availability, and counts for users, accounts, tenant accounts,
memberships, applications, catalogs, profile values, audit records, and
pending outbox events. Those checks describe the records in hand. They
do not prove that every event that should have been emitted was emitted.
See `docs/evidence-classification.md`.

## 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.

## Metrics

`GET /metrics` exposes Prometheus text containing the binary
`user_engine_ready` dependency gauge and bounded aggregate
`user_engine_records{kind=...}` counters. It does not expose identity values,
emails, tenant names, correlation identifiers, credential material, or raw
outbox payloads. Keep this route cluster-internal and authorize ingress only
from the selected monitoring workload.

## 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.