docs(portal): document request correlation contracts

adk-rust/crates/detmir-portal/src/production/request_context.rs

@@ -1,3 +1,11 @@
+//! Request correlation and route classification for portal observability.
+//!
+//! This module derives a low-cardinality route name, business module and role
+//! label for each request. These fields are used by structured logs and metrics.
+//!
+//! CONTRACT: generated route names must not expose volatile identifiers such as
+//! case IDs, candidate IDs or evidence IDs; use route templates instead.
+
 use std::cell::RefCell;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{Instant, SystemTime, UNIX_EPOCH};
@@ -93,6 +101,9 @@ fn resolve_request_ids(
 }
 
 fn sanitize_request_token(value: String) -> String {
+    // SECURITY: log correlation tokens are accepted from reverse proxies and
+    // clients, so strip control characters and path separators before they reach
+    // logs or metric labels. Truncation bounds accidental high-cardinality input.
     value
         .chars()
         .filter(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.' | ':'))