lex-microsoft_teams 0.6.50 → 0.6.52

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35010357ecbf55560b6957ae2467c5975eec04056da102a34b1d4c870a0f1ce3
-  data.tar.gz: 38d375c241ba2691948bf6d80f275410f0a1003e0e7456852f3bc2ca1bf4acce
+  metadata.gz: ac161b519f294da86eb8956d3aab55f11f4cd87d7fe710c43c033640b630efe5
+  data.tar.gz: bf64b0446e44cd89f9f9cc8be018a2629f0d375ccbfea4848e4668a16ad04598
 SHA512:
-  metadata.gz: ae71a656141975e85dc7b5e294e99d7d5a1f67a34e57feea943f177d4bf1c31224ef462adc5140163f6cb028ca1fede816fa713c25185522d8718fe01631a0af
-  data.tar.gz: b2e865c65531f7d464d7f058c2e8d965b1ca96643ca15bee7a6018c0dd260d7477771b0418404f9a6dd0ef8fc8dd983d8c68d0a06704fb2432af031d377150d6
+  metadata.gz: 926fd8d8f6aa8bbe022fbb17491b959faea7580dd28dee76c48199392fb3d50bd917934ed4025f4a65f20f7353412abbc6788de4634ebeb00d3bf07497e53e28
+  data.tar.gz: 26ee2c81c7e0330b575b2aedb8f2284d86c4d40a5b42d089b8edce9a6cd33b06699cf2bac2e7671ff62eff830940ed179b27db1cbcdf2e171d856916a24a296f

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.6.52] - 2026-05-29
+### Fixed
+- **Actors now defer their next scheduled run on a Graph throttle** instead of re-firing on their fixed timer interval — resolves the 0.6.51 "Known follow-up". New `Helpers::ThrottleAware` mixin records a "suppress until" instant of `now + retry_after` when a Graph call raises `Errors::Throttled`; subsequent ticks short-circuit until that window elapses. Wired into `PresencePoller`, `MeetingIngest`, and `ApiIngest`. Falls back to a bounded 60s deferral when the server gave no usable `Retry-After`, and clamps any single deferral to 600s. Previously a poller on a 30–300s interval would walk straight back into the still-open shared circuit every interval, emitting a `[throttle_circuit] hard circuit` ERROR (and a duplicate `Errors::Throttled` WARN/ERROR) each tick while ingesting nothing.
+- **`ProfileIngest#full_ingest` and `ApiIngest#ingest_api` now propagate `Errors::Throttled`** rather than folding it into a per-stage error hash. `full_ingest` catches it once and aborts the remaining fan-out stages — once the shared circuit is open every later stage would only raise `Throttled(attempts: 0)` instantly, so continuing produced a burst of identical errors. The actor that drives `ingest_api` uses the propagated throttle to open its deferral window. Non-throttle errors keep their existing error-result behavior.
+
+## [0.6.51] - 2026-05-27
+### Added
+- `Faraday::RetryAfter` middleware honoring `Retry-After` per RFC 9110 §10.2.3 (originally RFC 7231 §7.1.3) in both delta-seconds and HTTP-date forms. Retries HTTP 429 by default; 503/504 opt-in. Bounded by `max_retries` and cumulative `max_wait`; ±jitter on advertised wait to avoid thundering-herd. Configurable via `microsoft_teams.client.retry.{max_retries,max_wait,jitter,fallback_wait,retry_statuses}`; `fetch` semantics preserve explicit falsey values.
+- `Errors::Throttled` exception with `status`, `retry_after` (nullable; `nil` distinguishes "no server guidance" from "retry immediately"), `retry_after_known?` predicate, `request`, and `attempts`.
+- `Faraday::RetryAfter.parse_header` shared class method (single source of truth for Retry-After parsing).
+- `default_settings` for all actors with explicit `enabled`, `interval`, and tuning knobs. Actors no longer need nil guards — values are guaranteed by the extension settings merge on boot. Defaults: `api_ingest` 3600s, `incremental_sync` 900s, `presence_poller` disabled, `channel_poller` disabled, `direct_chat_poller` disabled, `observed_chat_poller` disabled, `meeting_ingest` 900s, `profile_ingest` enabled (once on boot).
+- `Helpers::GraphCache` module — `cached_graph_get` wraps Graph API calls with `Legion::Cache` TTL-based caching. Supports `shared: true` for resource-scoped endpoints (e.g., `/chats/{id}/members` — same data for all participants) vs user-scoped for `/me/*` endpoints. Cache keys incorporate the process identity UUID to prevent cross-user leakage.
+
+### Fixed
+- Stuck or chatty consumers no longer brown out other users on the same Entra app registration's Graph quota. The `RetryAfter` middleware now raises `Errors::Throttled` **centrally on exhaustion** — every consumer of `graph_connection` and `bot_connection` gets the typed event without per-callsite handling. Fixes #18.
+- `Helpers::GraphClient#handle_graph_response` retains a defensive 429/503/504 branch that raises `Errors::Throttled` for callers that build a Faraday connection without the middleware (custom tests, ad-hoc tooling).
+- Logger acquisition failures no longer silently drop retry telemetry — falls back to `Legion::Logging` unconditionally; loss of those signals was how the original outage went undiagnosed for days.
+- **O(N×M) member scan eliminated** — `ProfileIngest#find_chat_for_person` and `ApiIngest#match_chat_to_person` previously called `GET /chats/{id}/members` for every chat × every person (up to 500+ calls per tick). Replaced with `build_chat_member_index` that fetches members once per chat and builds an in-memory lookup hash. Reduces ~514 calls/tick to ~50 for `IncrementalSync`; ~7,500 calls/tick to ~65 for `ApiIngest`.
+- `IncrementalSync` interval raised from 120s to 900s (was the single largest source of sustained Graph pressure).
+- `ApiIngest` interval raised from 1800s to 3600s.
+- Actors that were accidentally re-enabled by `952607c` (rubocop removed `return false` guards) are now properly gated by `settings[:actor_name][:enabled]` — `presence_poller`, `channel_poller`, `direct_chat_poller`, and `observed_chat_poller` all default to `false`.
+
+### Known follow-up
+- Actors (`*_poller.rb`, `meeting_ingest`, `profile_ingest`) still catch `Errors::Throttled` via the generic `rescue StandardError` block but do not yet *defer their next scheduled run* using the carried `retry_after`. To be addressed in a follow-up issue. *(Resolved in [Unreleased] — see `Helpers::ThrottleAware`.)*
+
 ## [0.6.50] - 2026-05-27
 ### Added
 - Full OData query parameter support across all Graph API runner methods per Microsoft Graph REST v1.0 docs

data/lib/legion/extensions/microsoft_teams/actors/api_ingest.rb

@@ -5,6 +5,8 @@ module Legion
     module MicrosoftTeams
       module Actor
         class ApiIngest < Legion::Extensions::Actors::Every
+          include Legion::Extensions::MicrosoftTeams::Helpers::ThrottleAware
+
           def runner_class = Legion::Extensions::MicrosoftTeams::Runners::ApiIngest
 
           def runner_function = 'ingest_api'
@@ -27,12 +29,12 @@ module Legion
           end
 
           def time
-            interval = teams_settings.dig(:ingest, :api_interval) || 1800
-            interval.to_i
+            teams_settings.dig(:api_ingest, :interval)
           end
 
           def enabled?
-            defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
+            teams_settings.dig(:api_ingest, :enabled) &&
+              defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
           rescue StandardError => e
             handle_exception(e, level: :warn, operation: 'ApiIngest#enabled?')
             false
@@ -40,29 +42,37 @@ module Legion
 
           def manual
             log.debug('ApiIngest#manual starting')
+            # The runner re-raises Errors::Throttled (rather than folding it
+            # into an error result) precisely so this actor can defer its
+            # next run by the advertised retry_after instead of charging the
+            # shared Graph circuit again on the next interval.
+            with_throttle_deferral { run_ingest }
+          rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'ApiIngest#manual')
+          end
+
+          private
+
+          def run_ingest
             token = resolve_token
             unless token
               log.warn('ApiIngest: no delegated token, skipping')
               return
             end
 
-            ingest = teams_settings[:ingest] || {}
+            ai_settings = teams_settings[:api_ingest]
             log.info('ApiIngest: starting Graph API ingest')
             result = runner_class.ingest_api(
               token:          token,
-              top_people:     ingest.fetch(:top_people, 15),
-              message_depth:  ingest.fetch(:message_depth, 50),
-              skip_bots:      ingest.fetch(:skip_bots, true),
+              top_people:     ai_settings[:top_people],
+              message_depth:  ai_settings[:message_depth],
+              skip_bots:      ai_settings[:skip_bots],
               imprint_active: imprint_active?
             )
             log.info("ApiIngest: #{result.inspect[0, 200]}")
             result
-          rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'ApiIngest#manual')
           end
 
-          private
-
           def token_available?
             resolve_token != nil
           end
@@ -75,12 +85,7 @@ module Legion
           end
 
           def teams_settings
-            return {} unless defined?(Legion::Settings)
-
-            Legion::Settings[:microsoft_teams] || {}
-          rescue StandardError => e
-            handle_exception(e, level: :warn, operation: 'ApiIngest#teams_settings')
-            {}
+            settings
           end
 
           def imprint_active?

data/lib/legion/extensions/microsoft_teams/actors/channel_poller.rb

@@ -7,10 +7,6 @@ module Legion
         class ChannelPoller < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
 
-          DEFAULT_INTERVAL       = 60
-          DEFAULT_MAX_TEAMS      = 10
-          DEFAULT_MAX_CHANNELS   = 5
-
           def initialize(**opts)
             return unless enabled?
 
@@ -20,7 +16,7 @@ module Legion
 
           def runner_class    = self.class
           def runner_function = 'manual'
-          def time            = channel_setting(:poll_interval, DEFAULT_INTERVAL)
+          def time            = settings.dig(:channel_poller, :interval)
           def delay           = 300
           def run_now?        = false
           def use_runner?     = false
@@ -36,7 +32,7 @@ module Legion
           end
 
           def enabled?
-            # channel_setting(:enabled, false) == true
+            settings.dig(:channel_poller, :enabled)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'ChannelPoller#enabled?')
             false
@@ -148,11 +144,11 @@ module Legion
           end
 
           def max_teams
-            channel_setting(:max_teams, DEFAULT_MAX_TEAMS)
+            settings.dig(:channel_poller, :max_teams)
           end
 
           def max_channels_per_team
-            channel_setting(:max_channels_per_team, DEFAULT_MAX_CHANNELS)
+            settings.dig(:channel_poller, :max_channels_per_team)
           end
 
           def delegated_token
@@ -162,17 +158,8 @@ module Legion
             nil
           end
 
-          def channel_setting(key, default)
-            return default unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :channels, key) || default
-          rescue StandardError => e
-            handle_exception(e, level: :debug, operation: "ChannelPoller#channel_setting(#{key})")
-            default
-          end
-
           def channel_traces_enabled?
-            channel_setting(:store_traces, false) == true
+            settings.dig(:channel_poller, :store_traces) == true
           end
 
           def store_channel_message_trace(team_name:, channel_name:, msg:)

data/lib/legion/extensions/microsoft_teams/actors/direct_chat_poller.rb

@@ -8,8 +8,6 @@ module Legion
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
           include Legion::Extensions::MicrosoftTeams::Helpers::HighWaterMark
 
-          POLL_INTERVAL = 15
-
           def initialize(**opts)
             return unless enabled?
 
@@ -19,7 +17,7 @@ module Legion
 
           def runner_class    = Legion::Extensions::MicrosoftTeams::Runners::Bot
           def runner_function = 'handle_message'
-          def time            = settings_interval(:direct_poll_interval, POLL_INTERVAL)
+          def time            = settings.dig(:direct_chat_poller, :interval)
           def delay           = 60
           def run_now?        = false
           def use_runner?     = false
@@ -27,7 +25,8 @@ module Legion
           def generate_task?  = false
 
           def enabled?
-            defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot) &&
+            settings.dig(:direct_chat_poller, :enabled) &&
+              defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot) &&
               Legion.const_defined?(:Transport, false)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'DirectChatPoller#enabled?')
@@ -95,9 +94,7 @@ module Legion
           end
 
           def bot_id_from_settings
-            return nil unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, :bot_id)
+            settings.dig(:bot, :bot_id)
           end
 
           def delegated_token
@@ -106,12 +103,6 @@ module Legion
             handle_exception(e, level: :warn, operation: 'DirectChatPoller#delegated_token')
             nil
           end
-
-          def settings_interval(key, default)
-            return default unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, key) || default
-          end
         end
       end
     end

data/lib/legion/extensions/microsoft_teams/actors/incremental_sync.rb

@@ -14,17 +14,12 @@ module Legion
           def delay           = 60
 
           def time
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'IncrementalSync#time')
-              {}
-            end
-            settings.dig(:ingest, :incremental_interval) || 120
+            settings.dig(:incremental_sync, :interval)
           end
 
           def enabled?
-            defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
+            settings.dig(:incremental_sync, :enabled) &&
+              defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
               token_available?
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'IncrementalSync#enabled?')
@@ -36,17 +31,11 @@ module Legion
             token = resolve_token
             return unless token
 
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'IncrementalSync#manual settings')
-              {}
-            end
-            ingest = settings[:ingest] || {}
+            is_settings = settings[:incremental_sync]
             runner_class.incremental_sync(
               token:         token,
-              top_people:    ingest.fetch(:top_people, 10),
-              message_depth: ingest.fetch(:message_depth, 50)
+              top_people:    is_settings[:top_people],
+              message_depth: is_settings[:message_depth]
             )
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'IncrementalSync#manual')

data/lib/legion/extensions/microsoft_teams/actors/meeting_ingest.rb

@@ -6,8 +6,7 @@ module Legion
       module Actor
         class MeetingIngest < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
-
-          DEFAULT_INGEST_INTERVAL = 300
+          include Legion::Extensions::MicrosoftTeams::Helpers::ThrottleAware
 
           def runner_class    = self.class
           def runner_function = 'manual'
@@ -22,17 +21,12 @@ module Legion
           end
 
           def time
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'MeetingIngest#time')
-              {}
-            end
-            settings.dig(:meetings, :ingest_interval) || DEFAULT_INGEST_INTERVAL
+            settings.dig(:meeting_ingest, :interval)
           end
 
           def enabled?
-            Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
+            settings.dig(:meeting_ingest, :enabled) &&
+              Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'MeetingIngest#enabled?')
             false
@@ -48,6 +42,17 @@ module Legion
 
           def manual
             log.info('MeetingIngest polling for meetings')
+            # Defer the next run when Graph throttles the meetings listing
+            # (the first, fixed call every tick makes); per-meeting throttles
+            # are handled by the inner rescue below and don't change cadence.
+            with_throttle_deferral { ingest_meetings }
+          rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'MeetingIngest#manual')
+          end
+
+          private
+
+          def ingest_meetings
             token = Legion::Extensions::Identity::Entra::Helpers::TokenManager.load_token(:delegated)
             return if token.nil?
 
@@ -64,16 +69,12 @@ module Legion
                 process_meeting(meeting_id: meeting_id, subject: meeting['subject'], token: token)
                 @processed_meetings.add(meeting_id)
               rescue StandardError => e
-                handle_exception(e, level: :error, operation: 'MeetingIngest#manual',
+                handle_exception(e, level: :error, operation: 'MeetingIngest#ingest_meetings',
                                  meeting_id: meeting_id)
               end
             end
-          rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'MeetingIngest#manual')
           end
 
-          private
-
           def process_meeting(meeting_id:, subject:, token:)
             log.debug("MeetingIngest#process_meeting meeting_id=#{meeting_id} subject=#{subject}")
             conn = graph_connection(token: token)

data/lib/legion/extensions/microsoft_teams/actors/observed_chat_poller.rb

@@ -8,8 +8,6 @@ module Legion
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
           include Legion::Extensions::MicrosoftTeams::Helpers::HighWaterMark
 
-          POLL_INTERVAL = 30
-
           def initialize(**opts)
             return unless enabled?
 
@@ -18,7 +16,7 @@ module Legion
 
           def runner_class    = Legion::Extensions::MicrosoftTeams::Runners::Bot
           def runner_function = 'observe_message'
-          def time            = settings_interval(:observe_poll_interval, POLL_INTERVAL)
+          def time            = settings.dig(:observed_chat_poller, :interval)
           def delay           = 180
           def run_now?        = false
           def use_runner?     = false
@@ -26,11 +24,9 @@ module Legion
           def generate_task?  = false
 
           def enabled?
-            return false unless defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot)
-            return false unless Legion.const_defined?(:Transport, false)
-            return false unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, :observe, :enabled) == true
+            settings.dig(:observed_chat_poller, :enabled) &&
+              defined?(Legion::Extensions::MicrosoftTeams::Runners::Bot) &&
+              Legion.const_defined?(:Transport, false)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'ObservedChatPoller#enabled?')
             false
@@ -106,12 +102,6 @@ module Legion
             handle_exception(e, level: :warn, operation: 'ObservedChatPoller#delegated_token')
             nil
           end
-
-          def settings_interval(key, default)
-            return default unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :bot, key) || default
-          end
         end
       end
     end

data/lib/legion/extensions/microsoft_teams/actors/presence_poller.rb

@@ -6,8 +6,7 @@ module Legion
       module Actor
         class PresencePoller < Legion::Extensions::Actors::Every
           include Legion::Extensions::MicrosoftTeams::Helpers::Client
-
-          DEFAULT_POLL_INTERVAL = 60
+          include Legion::Extensions::MicrosoftTeams::Helpers::ThrottleAware
 
           def runner_class    = self.class
           def runner_function = 'manual'
@@ -17,13 +16,12 @@ module Legion
           def generate_task?  = false
 
           def time
-            return DEFAULT_POLL_INTERVAL unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:microsoft_teams, :presence, :poll_interval) || DEFAULT_POLL_INTERVAL
+            settings.dig(:presence_poller, :interval)
           end
 
           def enabled?
-            Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
+            settings.dig(:presence_poller, :enabled) &&
+              Legion::Extensions::Identity::Entra::Helpers::TokenManager.respond_to?(:load_token)
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'PresencePoller#enabled?')
             false
@@ -31,6 +29,18 @@ module Legion
 
           def manual
             log.debug('PresencePoller#manual starting')
+            # Honour a recent Graph throttle by deferring this run; on a
+            # 429 the block raises Errors::Throttled, which the mixin
+            # converts into a deferral window so the next tick stands down
+            # for retry_after seconds instead of re-firing on the interval.
+            with_throttle_deferral { poll_presence }
+          rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'PresencePoller#manual')
+          end
+
+          private
+
+          def poll_presence
             token = delegated_token
             unless token
               log.debug('No token available, skipping presence poll')
@@ -52,12 +62,8 @@ module Legion
               log.info("Presence changed: availability=#{availability}, activity=#{activity}")
               @last_presence = current
             end
-          rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'PresencePoller#manual')
           end
 
-          private
-
           def delegated_token
             Legion::Extensions::Identity::Entra::Helpers::TokenManager.load_token(:delegated)
           rescue StandardError => e

data/lib/legion/extensions/microsoft_teams/actors/profile_ingest.rb

@@ -21,7 +21,8 @@ module Legion
           end
 
           def enabled?
-            defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
+            settings.dig(:profile_ingest, :enabled) &&
+              defined?(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces) &&
               token_available?
           rescue StandardError => e
             handle_exception(e, level: :debug, operation: 'ProfileIngest#enabled?')
@@ -37,17 +38,11 @@ module Legion
             end
             log.info('ProfileIngest: token acquired, starting ingest')
 
-            settings = begin
-              Legion::Settings[:microsoft_teams] || {}
-            rescue StandardError => e
-              handle_exception(e, level: :debug, operation: 'ProfileIngest#manual settings')
-              {}
-            end
-            ingest = settings[:ingest] || {}
+            pi_settings = settings[:profile_ingest]
             runner_class.full_ingest(
               token:         token,
-              top_people:    ingest.fetch(:top_people, 10),
-              message_depth: ingest.fetch(:message_depth, 50)
+              top_people:    pi_settings[:top_people],
+              message_depth: pi_settings[:message_depth]
             )
           rescue StandardError => e
             handle_exception(e, level: :error, operation: 'ProfileIngest#manual')

data/lib/legion/extensions/microsoft_teams/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Errors
+        # Raised when Microsoft Graph (or the Bot Framework) throttles the
+        # caller and the retry policy has been exhausted, or when an actor
+        # wants to surface a throttle event without retrying further.
+        #
+        # `retry_after` carries the last advertised Retry-After interval
+        # (in seconds) as parsed from the upstream header. **It is nil when
+        # the server returned no Retry-After header or one we could not
+        # parse** — callers must check `retry_after_known?` before treating
+        # the value as a server directive. Conflating "header missing" with
+        # "retry immediately" was the bug the original fleet outage exposed.
+        class Throttled < StandardError
+          attr_reader :status, :retry_after, :request, :attempts
+
+          # @param status [Integer]      the upstream HTTP status (e.g. 429)
+          # @param retry_after [Float, Integer, nil] seconds the server
+          #   advised waiting, or nil if the header was absent/unparseable
+          # @param request [String, nil] the path or URL that was throttled
+          # @param attempts [Integer, nil] how many retries the middleware
+          #   tried before giving up; nil means "not tracked"
+          def initialize(status:, retry_after: nil, request: nil, attempts: nil)
+            @status      = coerce_status(status)
+            @retry_after = coerce_retry_after(retry_after)
+            @request     = request
+            @attempts    = attempts.nil? ? nil : Integer(attempts)
+            super(build_message)
+          end
+
+          # @return [Boolean] true when the upstream advised a specific wait
+          #   interval; false when the header was missing or unparseable. Use
+          #   this to decide whether to honor the wait verbatim or apply a
+          #   local policy default before re-scheduling.
+          def retry_after_known?
+            !@retry_after.nil?
+          end
+
+          private
+
+          def coerce_status(value)
+            Integer(value)
+            # rubocop:disable Legion/RescueLogging/NoCapture
+            # No logger available during exception construction; we re-raise
+            # with a clearer message instead.
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "Throttled status must be an Integer, got #{value.inspect}"
+            # rubocop:enable Legion/RescueLogging/NoCapture
+          end
+
+          def coerce_retry_after(value)
+            return nil if value.nil?
+
+            seconds = Float(value)
+            seconds.negative? ? 0.0 : seconds
+            # rubocop:disable Legion/RescueLogging/NoCapture
+            # Unparseable retry_after intentionally collapses to nil so the
+            # public `retry_after_known?` predicate is the single source of
+            # truth for "did the server give us usable guidance." Logging
+            # belongs at the parse site (Faraday::RetryAfter), not here.
+          rescue ArgumentError, TypeError
+            nil
+            # rubocop:enable Legion/RescueLogging/NoCapture
+          end
+
+          def build_message
+            parts = ["Microsoft Graph throttled (HTTP #{@status})"]
+            parts << "after #{@attempts} attempt(s)" if @attempts
+            parts << if retry_after_known?
+                       "retry_after=#{format('%.2f', @retry_after)}s"
+                     else
+                       'retry_after=unknown'
+                     end
+            parts << "request=#{@request}" if @request
+            parts.join('; ')
+          end
+        end
+      end
+    end
+  end
+end