agent foundation

lib/Http/RequestContext.php

@@ -4,6 +4,8 @@ namespace MintyPHP\Http;
 
 use MintyPHP\Repository\Support\RepoQuery;
 
+// Holds per-request metadata (id, channel, method, path, ip) as a static singleton.
+// Must be initialized once at the entry point (web, api, cli) via start().
 final class RequestContext
 {
     /** @var array<string, mixed>|null */
@@ -27,6 +29,7 @@ final class RequestContext
         self::$context = self::buildDefaultContext();
     }
 
+    // Returns the request ID, generating one if missing. Use this when you need a guaranteed value.
     public static function id(): string
     {
         self::ensureStarted();
@@ -38,6 +41,7 @@ final class RequestContext
         return $requestId;
     }
 
+    // Returns the ID only if already set — safe to call before start() (e.g. in error handlers).
     public static function currentId(): ?string
     {
         if (self::$context === null) {
@@ -80,6 +84,7 @@ final class RequestContext
         return self::id();
     }
 
+    // HMAC when a key is configured (e.g. hashing IPs for audit logs) — plain SHA256 as fallback.
     public static function hashValue(string $value): string
     {
         $secret = defined('APP_CRYPTO_KEY') ? trim((string) APP_CRYPTO_KEY) : '';
@@ -191,6 +196,8 @@ final class RequestContext
         return in_array($channel, ['web', 'api', 'scheduler', 'cli'], true) ? $channel : '';
     }
 
+    // Accept a caller-supplied request ID for cross-service trace correlation.
+    // Only trusted if it's a valid UUID format — arbitrary strings are ignored.
     private static function requestIdFromHeader(): ?string
     {
         $header = trim((string) ($_SERVER['HTTP_X_REQUEST_ID'] ?? ''));