Finalize user-engine contracts and operability

docs/operability.md

@@ -0,0 +1,39 @@
+# 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.