noresponse 2.1.15 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2469d4f72cf85b77dbd86ca8a05136ff313081e86be235d86cc5190ba9141639
-  data.tar.gz: 4368344ab696f56ae59f9dc2b932f25f5e66183f6e57a3ebf398f79a0146e965
+  metadata.gz: 9ced920c7288c6434e1fbd06de24541b1ac3bec7dccb43bcef7aa7ccad375377
+  data.tar.gz: 67f9fc2cce7b114edd72d84031d91312c04414114fd61ce3f7db0c3e63c6714e
 SHA512:
-  metadata.gz: 70c09610fdb41378166092d7af4693538817762093e6ff73df8b6333c341e0bbee290b3b8b6156140361131ac1ef716d4277aa88b75ce30fa4f3e92814810688
-  data.tar.gz: 6f120c6191d655a540ffeb3d78f9c8c093c0cb6f42eb3641f0c2c9fb35076edf4d958af2965e6f517c380500c77b562795a09928ec5e095ecf0b959b4a286577
+  metadata.gz: a7c8af727605dcef753fb10d0d3c46bf0a5fc8c90bb411d0117aceb023fb5807af788984dd5d77a09dc984a0979ee797ea75cdf6c301edc8d4aa4f74e3c83fdd
+  data.tar.gz: 02faf461ec16e415a4c799557fff8ae5e9bdcd5f62a192dfa5682c0a37bdbe10c00176d71b7de6f360616442f00b055ce429be012dc70a24acf75b18bdc3fc96

data/lib/no_response/accounts.rb

@@ -49,7 +49,7 @@ module NoResponse
     }
     def get(account_id:, retries: nil, timeout_ms: nil, http_headers: nil)
       # get - Read an account's one current risk.
-      # An account is the account_id you send with your assessments. Its current risk is the risk of its latest assessment with a decision (status complete or partial), scored as GET /v1/assessments/{assessment_id} scores that assessment, with a decision for each flow. Every assessment updates its account: once an assessment completes, the account carries its risk. Requires the history scope. Read-only and safe to retry. An account with no unexpired assessment that has a decision answers 404 not_found, and a malformed account_id answers 400 invalid_request.
+      # An account is the account_id you send with your assessments. Its current risk is the risk of its latest assessment with a decision (status complete or partial), scored as GET /v1/assessments/{assessment_id} scores that assessment, with a decision for each flow; risk.decision is the decision for the flow of that assessment. Every assessment answers with this same account. Every assessment updates its account: once an assessment completes, the account carries its risk. Requires the history scope. Read-only and safe to retry. An account with no unexpired assessment that has a decision answers 404 not_found, and a malformed account_id answers 400 invalid_request.
       request = Models::Operations::GetAccountRequest.new(
         account_id: account_id
       )

data/lib/no_response/assessments.rb

@@ -50,7 +50,7 @@ module NoResponse
     }
     def create(body:, idempotency_key: nil, retries: nil, timeout_ms: nil, http_headers: nil)
       # create - Assess identifiers for a signup or gateway decision.
-      # Returns within the deadline (3000 ms at most) with a complete, partial or pending assessment: 200 carries complete or partial, 202 carries pending with Location and Retry-After. A pending answer has no recommendation; apply your own fallback for pending, 429, 503 or a timeout. risk.block says when your block threshold was reached. Requires the assess scope. Idempotency-Key is optional in the SDK and is bound to the body for 24 hours: the same key with the same body replays the latest assessment with Idempotent-Replayed: true and starts no new work; the same key with a different body answers 409 idempotency_key_reused. response_mode defaults to standard; detailed needs the detailed scope.
+      # Assesses one signup, login or purchase (flow) and answers with the account's one current risk: account.risk.decision is the decision for this flow (allow, step_up, review or block, where block means your block threshold was reached), and detail holds this assessment's own facts. depth sets how long the answer waits for sources: quick waits only for the fast ones (500 ms), full for the whole budget (3000 ms at most); it defaults to full for signup and purchase and quick for login. 200 carries complete or partial, 202 carries pending with Location and Retry-After. While the account's first assessment is pending, account is absent: apply your own fallback for that, 429, 503 or a timeout. NoResponse blocks nothing itself; you decide. Requires the assess scope. Idempotency-Key is optional in the SDK and is bound to the body for 24 hours: the same key with the same body replays the latest assessment with Idempotent-Replayed: true and starts no new work; the same key with a different body answers 409 idempotency_key_reused. response_mode defaults to standard; detailed needs the detailed scope.
       request = Models::Operations::CreateAssessmentRequest.new(
         body: body,
         idempotency_key: idempotency_key
@@ -348,7 +348,7 @@ module NoResponse
     }
     def get(assessment_id:, response_mode: nil, retries: nil, timeout_ms: nil, http_headers: nil)
       # get - Poll the authoritative assessment of one assessment.
-      # Returns the highest assessment_version. Requires the assess or history scope. While status is pending, or partial with a source still running, the response carries Retry-After; poll no faster than it says. Another tenant's assessment, an unknown or expired assessment and a malformed assessment_id all answer 404 not_found. response_mode=detailed needs the detailed scope.
+      # Returns the highest assessment_version, with the account's current risk. Requires the assess or history scope. While status is pending, or partial with a source still running, the response carries Retry-After; poll no faster than it says. Another tenant's assessment, an unknown or expired assessment and a malformed assessment_id all answer 404 not_found. response_mode=detailed needs the detailed scope.
       request = Models::Operations::GetAssessmentRequest.new(
         assessment_id: assessment_id,
         response_mode: response_mode

data/lib/no_response/late_results.rb

@@ -4,7 +4,7 @@
 # Late-result handlers. Hand-written beside the generated client.
 #
 # An assessment can be revised after the signup was allowed: a slow source
-# settles and the recommendation rises. NoResponse sends the new version as a
+# settles and the account's decision rises. NoResponse sends the new version as a
 # signed assessment.updated webhook. LateResults.handle verifies that delivery
 # with Webhooks.construct_event, picks an action from your policy, and acts
 # through the auth provider's admin API: revoke the user's sessions or ban the
@@ -30,10 +30,12 @@ module NoResponse
     BAN = 'ban'
     ACTIONS = [NONE, REVOKE_SESSIONS, BAN].freeze
 
-    # Revoke sessions on review; do nothing on allow or step_up. Banning is opt-in.
-    DEFAULT_POLICY = { 'allow' => NONE, 'step_up' => NONE, 'review' => REVOKE_SESSIONS }.freeze
+    # Revoke sessions on review and block; do nothing on allow or step_up.
+    # Banning is opt-in.
+    DEFAULT_POLICY = { 'allow' => NONE, 'step_up' => NONE, 'review' => REVOKE_SESSIONS,
+                       'block' => REVOKE_SESSIONS }.freeze
 
-    RECOMMENDATIONS = %w[allow step_up review].freeze
+    DECISIONS = %w[allow step_up review block].freeze
 
     # Raised when the provider's admin API refuses a call. Answer the webhook
     # with a 5xx so NoResponse retries it. The message holds no response body
@@ -61,23 +63,25 @@ module NoResponse
     Result = Struct.new(:event, :action, :user_id, keyword_init: true)
 
     class << self
-      # The action your policy names for a verified event. Only a served
-      # assessment with a recommendation can act; a test event never does.
-      # policy maps allow, step_up and review (as strings or symbols) to NONE,
-      # REVOKE_SESSIONS or BAN; a recommendation you leave out does nothing. An
-      # unknown action raises ArgumentError.
+      # The action your policy names for a verified event, from the account's
+      # decision (data.account.risk.decision). Only a served assessment whose
+      # account has a decision can act; a pending assessment, an expiry and a
+      # test event never do. policy maps allow, step_up, review and block (as
+      # strings or symbols) to NONE, REVOKE_SESSIONS or BAN; a decision you
+      # leave out does nothing. An unknown action raises ArgumentError.
       def action_for(event, policy = DEFAULT_POLICY)
         return NONE if event.type != 'assessment.updated' || event.test? || event.expired?
 
         data = event.data
-        recommendation = data.recommendation || data.risk&.recommendation
-        recommendation = recommendation.to_s
-        return NONE unless RECOMMENDATIONS.include?(recommendation)
+        return NONE if data.status == Models::Shared::Status::PENDING || data.account.nil?
+
+        decision = data.account.risk.decision.to_s
+        return NONE unless DECISIONS.include?(decision)
 
         table = policy.to_h.transform_keys(&:to_s)
-        return NONE unless table.key?(recommendation)
+        return NONE unless table.key?(decision)
 
-        action = table[recommendation]
+        action = table[decision]
         return NONE if action.nil?
 
         action = action.to_s
@@ -103,7 +107,7 @@ module NoResponse
         action = action_for(event, policy)
         return Result.new(event: event, action: NONE) if action == NONE || event.type != 'assessment.updated'
 
-        account_id = event.data.account_id
+        account_id = event.data.detail.account_id
         resolved = user_id ? user_id.call(account_id, event) : account_id
         return Result.new(event: event, action: NONE) if resolved.nil? || resolved.to_s.empty?
 
@@ -169,13 +173,19 @@ module NoResponse
       # user before deleting the refresh tokens, and act reports BAN. Unblock
       # the user in the dashboard to undo it. Any other refusal, such as 403
       # insufficient_scope, raises.
+      #
+      # A 429 from the Management API is waited out and retried: Retry-After,
+      # else X-RateLimit-Reset, else 0.25 s doubling, at most 4 retries a call
+      # and 3 s of waiting a revoke or ban. Past that the 429 raises as
+      # ProviderActionError. An http_client may return [status, body, headers]
+      # so the headers are honoured; without them the backoff applies.
       def auth0(token:, domain: nil, base_url: nil, http_client: nil)
         raise ArgumentError, 'auth0 needs token' if token.to_s.empty?
 
         base = base_url || (domain.to_s.empty? ? nil : "https://#{domain}/api/v2")
         raise ArgumentError, 'auth0 needs domain or base_url' if base.nil?
 
-        Auth0.new(Caller.new('auth0', base, "Bearer #{token}", http_client))
+        Auth0.new(Caller.new('auth0', base, "Bearer #{token}", http_client, retry_rate_limits: true))
       end
 
       # A provider for an app with its own login, or for trying the handler
@@ -191,16 +201,62 @@ module NoResponse
     end
 
     # One provider HTTP client: base URL, Authorization header, error mapping.
+    #
+    # Rate limits. Auth0 answers 429 when the Management API rate limit is
+    # hit, and a 429 means it did not act, so the call is safe to send again,
+    # a DELETE included. One revoke or ban waits at most RATE_LIMIT_BUDGET
+    # seconds in all, and each call retries at most RATE_LIMIT_RETRIES times:
+    # it waits Retry-After seconds, else until X-RateLimit-Reset (Unix
+    # seconds), else 0.25, 0.5, 1 and 2 s. A wait that would pass the budget is
+    # not started: the 429 raises at once as ProviderActionError, the webhook
+    # answers 5xx and NoResponse delivers it again later. The budget keeps the
+    # handler inside the 5 s a delivery has to be answered.
     class Caller
-      def initialize(name, base_url, authorization, http_client)
+      RATE_LIMIT_RETRIES = 4
+      RATE_LIMIT_BUDGET = 3.0
+      RATE_LIMIT_BACKOFF = 0.25
+
+      def initialize(name, base_url, authorization, http_client, retry_rate_limits: false)
         @name = name
         @base = base_url.to_s.sub(%r{/+\z}, '')
         @authorization = authorization
         @http_client = http_client
+        @retry_rate_limits = retry_rate_limits
+        @waited = 0.0
       end
 
       attr_reader :name
 
+      # A caller with the same settings and its own rate-limit budget, for one action.
+      def fresh
+        Caller.new(@name, @base, @authorization, @http_client, retry_rate_limits: @retry_rate_limits)
+      end
+
+      # How long a 429 asks to wait, in seconds.
+      def self.rate_limit_wait(headers, retry_index)
+        after = number(header(headers, 'retry-after'))
+        return after if after && after >= 0
+
+        reset = number(header(headers, 'x-ratelimit-reset'))
+        return [0.0, reset - Time.now.to_f].max if reset
+
+        RATE_LIMIT_BACKOFF * (2**retry_index)
+      end
+
+      def self.header(headers, name)
+        (headers || {}).each { |key, value| return Array(value).first.to_s.strip if key.to_s.downcase == name }
+        nil
+      end
+
+      def self.number(text)
+        return nil if text.nil? || text.empty?
+
+        value = Float(text)
+        value.finite? ? value : nil
+      rescue ArgumentError
+        nil
+      end
+
       def call(method, path, query: nil, body: nil, allow_404: false)
         uri = URI.parse(@base + path)
         uri.query = URI.encode_www_form(query) if query && !query.empty?
@@ -210,7 +266,7 @@ module NoResponse
           headers['Content-Type'] = 'application/json'
           payload = JSON.generate(body)
         end
-        status, text = perform(method, uri, headers, payload)
+        status, text = send_waiting_out_rate_limits(method, uri, headers, payload)
         return nil if allow_404 && status == 404
         unless status.between?(200, 299)
           raise ProviderActionError.new(@name, status, "#{@name} #{method} #{path} answered #{status}", error_code(text))
@@ -226,6 +282,21 @@ module NoResponse
 
       private
 
+      def send_waiting_out_rate_limits(method, uri, headers, payload)
+        retry_index = 0
+        loop do
+          status, text, response_headers = perform(method, uri, headers, payload)
+          return [status, text] unless status == 429 && @retry_rate_limits && retry_index < RATE_LIMIT_RETRIES
+
+          wait = Caller.rate_limit_wait(response_headers, retry_index)
+          return [status, text] if @waited + wait > RATE_LIMIT_BUDGET
+
+          @waited += wait
+          sleep(wait)
+          retry_index += 1
+        end
+      end
+
       # The error code in a provider's error body: Auth0's errorCode, or a top-level code.
       def error_code(text)
         body = JSON.parse(text.to_s)
@@ -247,7 +318,7 @@ module NoResponse
         request = Net::HTTPGenericRequest.new(method, !payload.nil?, true, uri.request_uri, headers)
         request.body = payload unless payload.nil?
         response = http.start { |connection| connection.request(request) }
-        [response.code.to_i, response.body.to_s]
+        [response.code.to_i, response.body.to_s, response.to_hash]
       end
     end
 
@@ -345,10 +416,11 @@ module NoResponse
 
       def ban(user_id)
         user = Segment.encode(user_id)
-        block(user)
+        call = @call.fresh
+        block(call, user)
         # The block already ends a session the plan cannot delete.
-        delete_sessions(user)
-        delete_refresh_tokens(user_id, user)
+        delete_sessions(call, user)
+        delete_refresh_tokens(call, user_id, user)
         nil
       end
 
@@ -366,10 +438,11 @@ module NoResponse
 
       def revoke(user_id)
         user = Segment.encode(user_id)
-        ended = delete_sessions(user)
+        call = @call.fresh
+        ended = delete_sessions(call, user)
         # Without the sessions API a login session survives; blocking is the only way to end it.
-        block(user) unless ended
-        delete_refresh_tokens(user_id, user)
+        block(call, user) unless ended
+        delete_refresh_tokens(call, user_id, user)
         ended ? REVOKE_SESSIONS : BAN
       end
 
@@ -378,13 +451,13 @@ module NoResponse
         error.status == 403 && error.code == 'feature_not_enabled'
       end
 
-      def block(user)
-        @call.call('PATCH', "/users/#{user}", body: { 'blocked' => true }, allow_404: true)
+      def block(call, user)
+        call.call('PATCH', "/users/#{user}", body: { 'blocked' => true }, allow_404: true)
       end
 
       # Ends every session; false when the plan has no sessions API.
-      def delete_sessions(user)
-        @call.call('DELETE', "/users/#{user}/sessions", allow_404: true)
+      def delete_sessions(call, user)
+        call.call('DELETE', "/users/#{user}/sessions", allow_404: true)
         true
       rescue ProviderActionError => e
         raise unless not_on_plan?(e)
@@ -392,9 +465,9 @@ module NoResponse
         false
       end
 
-      def delete_refresh_tokens(user_id, user)
+      def delete_refresh_tokens(call, user_id, user)
         begin
-          @call.call('DELETE', "/users/#{user}/refresh-tokens", allow_404: true)
+          call.call('DELETE', "/users/#{user}/refresh-tokens", allow_404: true)
           return
         rescue ProviderActionError => e
           raise unless not_on_plan?(e)
@@ -403,15 +476,15 @@ module NoResponse
         ids = []
         %w[refresh_token rotating_refresh_token].each do |type|
           10.times do |page|
-            body = @call.call('GET', '/device-credentials',
-                              query: [['user_id', user_id], ['type', type], ['page', page.to_s], ['per_page', PAGE.to_s]],
-                              allow_404: true)
+            body = call.call('GET', '/device-credentials',
+                             query: [['user_id', user_id], ['type', type], ['page', page.to_s], ['per_page', PAGE.to_s]],
+                             allow_404: true)
             listed = body.is_a?(Array) ? body.grep(Hash) : []
             ids.concat(listed.map { |c| c['id'] }.select { |id| id.is_a?(String) && !id.empty? })
             break if listed.length < PAGE
           end
         end
-        ids.each { |id| @call.call('DELETE', "/device-credentials/#{ERB::Util.url_encode(id)}", allow_404: true) }
+        ids.each { |id| call.call('DELETE', "/device-credentials/#{ERB::Util.url_encode(id)}", allow_404: true) }
       end
     end
 

data/lib/no_response/models/shared/account.rb

@@ -17,7 +17,7 @@ module NoResponse
           Models::Shared::AccountRisk,
           {'format_json': {'letter_case': ::NoResponse::Utils.field_name("risk"), required: true}}
         )
-        # The decision for each flow. Every flow uses the tenant's signup thresholds today, so all three equal risk.decision.
+        # The decision for each flow. Every flow uses the tenant's signup thresholds today, so all three are equal.
         field(
           :decisions_by_flow,
           Models::Shared::AccountDecisionsByFlow,

data/lib/no_response/models/shared/accountdecisionsbyflow.rb

@@ -4,7 +4,7 @@
 module NoResponse
   module Models
     module Shared
-      # The decision for each flow. Every flow uses the tenant's signup thresholds today, so all three equal risk.decision.
+      # The decision for each flow. Every flow uses the tenant's signup thresholds today, so all three are equal.
       class AccountDecisionsByFlow
         extend T::Sig
         include Crystalline::MetadataFields

data/lib/no_response/models/shared/assessment.rb

@@ -4,23 +4,13 @@
 module NoResponse
   module Models
     module Shared
-      # One assessment of one account, as POST /v1/assessments, GET /v1/assessments/{assessment_id} and the assessment.updated webhook return it. status says whether it is final (complete), usable with a source still running (partial) or not yet usable (pending). risk and recommendation are present for complete and partial; assessment_url is present for pending. Keep the highest assessment_version.
+      # One assessment, as POST /v1/assessments, GET /v1/assessments/{assessment_id} and the assessment.updated webhook return it. account is the account's one current risk: its score, the decision for this assessment's flow, the reasons and the decision for each flow. detail holds this assessment's own facts. status says whether the assessment is final (complete), usable with a source still running (partial) or not yet usable (pending). While the account's first assessment is pending, account is absent; wait for the webhook or poll the assessment. Keep the highest detail.assessment_version.
       class Assessment
         extend T::Sig
         include Crystalline::MetadataFields
 
-        # Opaque, server-assigned assessment id: 'asm_' and a 26-character Crockford base32 ULID. Unique within the tenant; another tenant's assessment id answers 404.
-        field(
-          :assessment_id,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("assessment_id"), required: true}}
-        )
-        # Your own opaque identifier for the account being checked, scoped to your tenant. Use an id you mint, with no direct identifier (email, phone, name or national id) in it. '|' is accepted so an Auth0 user id such as 'auth0|64abc' passes unchanged; '@', '+', '$' and whitespace are refused by the pattern, as is an exact-shape JWT; a hex digest such as a SHA-256 is allowed, because hashing an internal id is a common pseudonymous scheme. A value such as '07700900123' or 'jane.doe.gmail.com' cannot be told apart from an opaque id. It travels in bodies, and in a URL only as the path segment of GET /v1/accounts/{account_id} and its /assessments. An assessment requested by a provider hook at pre_registration, which has no account yet, carries the server-issued account_id pre: followed by its assessment_id.
-        field(
-          :account_id,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("account_id"), required: true}}
-        )
+        # This assessment's id, equal to detail.assessment_id.
+        field :id, ::String, {'format_json': {'letter_case': ::NoResponse::Utils.field_name("id"), required: true}}
         # complete: final; nothing is still running. A lane that failed or missed its 10 s deadline stays listed in incomplete_sources, and confidence is lower. partial: a recommendation exists and at least one lane is still running or did not settle (see incomplete_sources). pending: nothing usable before the deadline; no recommendation yet, poll or wait for the webhook.
         field(
           :status,
@@ -33,210 +23,85 @@ module NoResponse
             }
           }
         )
-        # Ordinal confidence in the recommendation under the current policy: low, medium, high or unavailable.
+        # The customer event an assessment is made for: signup (a new account), login (a returning sign-in) or purchase (a payment or credit grant). The account's risk is reported with the decision for this flow.
         field(
-          :confidence,
-          Models::Shared::Confidence,
+          :flow,
+          Models::Shared::Flow,
           {
             'format_json': {
-              'letter_case': ::NoResponse::Utils.field_name("confidence"),
+              'letter_case': ::NoResponse::Utils.field_name("flow"),
               required: true,
-              'decoder': ::NoResponse::Utils.open_enum_from_string(Models::Shared::Confidence, false)
+              'decoder': ::NoResponse::Utils.open_enum_from_string(Models::Shared::Flow, false)
             }
           }
         )
-        # The lanes that did not settle, each listed once with a reason; lanes, not sources. In a detailed view a lane is listed exactly when one of its signals did not settle; a standard view carries no signals to match.
+        # How long the synchronous answer waits for sources. quick waits only for the fast sources, those that answer within 500 ms of ingress (or deadline_ms when lower); full waits for the whole budget, up to 3000 ms. Sources still running at the cut continue asynchronously and update the assessment either way.
         field(
-          :incomplete_sources,
-          Crystalline::Array.new(Models::Shared::IncompleteSource),
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("incomplete_sources"), required: true}}
-        )
-        # Version of the hand-authored heuristic weights that produced the recommendation, for example 'risk-2026-10.7'. A tenant threshold override adds a +t<N> suffix, e.g. 'risk-2026-10.7+t3'.
-        field(
-          :policy_version,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("policy_version"), required: true}}
-        )
-        # Monotonic revision of this assessment. 1 on the synchronous answer; each material change while the assessment is served (an async continuation settling a source, a change of recommendation, confidence or status) increments it. Expiry does not increment it: an expired assessment is gone, not revised, and the expiry webhook carries the last served version.
-        field(
-          :assessment_version,
-          ::Integer,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("assessment_version"), required: true}}
-        )
-        # When the assessment was created. Fixed for the life of the assessment: every revision carries the same created_at.
-        field(
-          :created_at,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("created_at"), required: true}}
-        )
-
-        field(
-          :updated_at,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("updated_at"), required: true}}
-        )
-        # After this instant the assessment is no longer served: GET /v1/assessments/{assessment_id} answers 404 and it leaves the account history. It is created_at plus your retention period at creation (default and maximum 365 days) and is fixed per record: a later revision keeps it, and a new assessment for the same account starts its own clock. If you later shorten retention, the effective expiry becomes created_at plus the shorter of the two periods.
-        field(
-          :expires_at,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("expires_at"), required: true}}
-        )
-
-        field(
-          :timing,
-          Models::Shared::AssessmentTiming,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("timing"), required: true}}
-        )
-        # Version of the body shape.
-        field(
-          :schema_version,
-          ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("schema_version"), required: true}}
-        )
-        # An optional provider correlation id, echoed back. It is not an idempotency key. Refuses an exact-shape JWT or a bare 40, 64 or 128 character hex digest; a UUID is accepted.
-        field(
-          :request_id,
-          Crystalline::Nilable.new(::String),
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("request_id")}}
-        )
-        # The recommended action: allow, step_up or review. Your application applies it.
-        field(
-          :recommendation,
-          Crystalline::Nilable.new(Models::Shared::Recommendation),
+          :depth,
+          Models::Shared::Depth,
           {
             'format_json': {
-              'letter_case': ::NoResponse::Utils.field_name("recommendation"),
-              'decoder': ::NoResponse::Utils.open_enum_from_string(Models::Shared::Recommendation, true)
+              'letter_case': ::NoResponse::Utils.field_name("depth"),
+              required: true,
+              'decoder': ::NoResponse::Utils.open_enum_from_string(Models::Shared::Depth, false)
             }
           }
         )
-        # The one risk decision for this event. score is 0 (safe) to 100 (risky): the sum of the weights of the reasons that fired, clamped to 0 to 100, from hand-set versioned weights. Every answer with a recommendation carries it, and the top-level recommendation equals risk.recommendation. It names no source or provider.
-        field(
-          :risk,
-          Crystalline::Nilable.new(Models::Shared::Risk),
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("risk")}}
-        )
-        # Detailed view only (response_mode=detailed, which needs the detailed scope): a standard answer omits signals[], and a detailed one always carries it, possibly empty. The body does not name its mode, so that rule is the serving gate's; the schema states the half it can: an answer with risk.details is a detailed view and carries signals[]. At most one signal per (type, source_id, identifier).
+        # One assessment's own facts: its score and recommendation, the signals behind them, the lanes still running and its timing. risk here is this assessment's own score; the account's current risk is the account member of the assessment. risk and recommendation are present for complete and partial; assessment_url is present for pending.
         field(
-          :signals,
-          Crystalline::Nilable.new(Crystalline::Array.new(Models::Shared::Signal)),
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("signals")}}
+          :detail,
+          Models::Shared::AssessmentDetail,
+          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("detail"), required: true}}
         )
-        # Labels the v0 policy as hand-authored and not statistically validated.
+        # Version of the body shape.
         field(
-          :policy_basis,
+          :schema_version,
           ::String,
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("policy_basis"), required: true}}
-        )
-        # Server-relative path of the authoritative assessment, GET /v1/assessments/{assessment_id}.
-        field(
-          :assessment_url,
-          Crystalline::Nilable.new(::String),
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("assessment_url")}}
+          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("schema_version"), required: true}}
         )
-        # The identity fields of the auth context the assessment was made with, echoed for the tenant's own correlation: the request's auth_context, or the one a hosted provider hook (POST /hooks/{integration_id}) built, with transport provider_hook and its hook_point. Present exactly when the request carried an auth_context, and the same on every revision of the assessment. Values are as the request or the hook sent them; tokens, timestamps, roles and scopes are not echoed, and the echo does not change the score.
+        # Body of the 200 answer to GET /v1/accounts/{account_id}: the one current risk of one of the calling tenant's accounts. It is the risk of the account's latest assessment that has a decision (status complete or partial), by created_at and then assessment_id, scored exactly as GET /v1/assessments/{assessment_id} scores that assessment. Its assessments are the account's history (GET /v1/accounts/{account_id}/assessments).
         field(
-          :auth_context,
-          Crystalline::Nilable.new(Models::Shared::AssessmentAuthContext),
-          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("auth_context")}}
+          :account,
+          Crystalline::Nilable.new(Models::Shared::Account),
+          {'format_json': {'letter_case': ::NoResponse::Utils.field_name("account")}}
         )
 
         sig {
           params(
-            assessment_id: ::String,
-            account_id: ::String,
+            id: ::String,
             status: Models::Shared::Status,
-            confidence: Models::Shared::Confidence,
-            incomplete_sources: T::Array[Models::Shared::IncompleteSource],
-            policy_version: ::String,
-            assessment_version: ::Integer,
-            created_at: ::String,
-            updated_at: ::String,
-            expires_at: ::String,
-            timing: Models::Shared::AssessmentTiming,
+            flow: Models::Shared::Flow,
+            depth: Models::Shared::Depth,
+            detail: Models::Shared::AssessmentDetail,
             schema_version: ::String,
-            request_id: T.nilable(::String),
-            recommendation: T.nilable(Models::Shared::Recommendation),
-            risk: T.nilable(Models::Shared::Risk),
-            signals: T.nilable(T::Array[Models::Shared::Signal]),
-            policy_basis: ::String,
-            assessment_url: T.nilable(::String),
-            auth_context: T.nilable(Models::Shared::AssessmentAuthContext)
+            account: T.nilable(Models::Shared::Account)
           )
             .void
         }
-        def initialize(
-          assessment_id:,
-          account_id:,
-          status:,
-          confidence:,
-          incomplete_sources:,
-          policy_version:,
-          assessment_version:,
-          created_at:,
-          updated_at:,
-          expires_at:,
-          timing:,
-          schema_version: "1",
-          request_id: nil,
-          recommendation: nil,
-          risk: nil,
-          signals: nil,
-          policy_basis: "heuristic_unvalidated",
-          assessment_url: nil,
-          auth_context: nil
-        )
-          @assessment_id = assessment_id
-          @account_id = account_id
+        def initialize(id:, status:, flow:, depth:, detail:, schema_version: "1", account: nil)
+          @id = id
           @status = status
-          @confidence = confidence
-          @incomplete_sources = incomplete_sources
-          @policy_version = policy_version
-          @assessment_version = assessment_version
-          @created_at = created_at
-          @updated_at = updated_at
-          @expires_at = expires_at
-          @timing = timing
+          @flow = flow
+          @depth = depth
+          @detail = detail
           unless schema_version == "1"
             raise ArgumentError, "Invalid value for schema_version"
           end
 
           @schema_version = "1"
-          @request_id = request_id
-          @recommendation = recommendation
-          @risk = risk
-          @signals = signals
-          unless policy_basis == "heuristic_unvalidated"
-            raise ArgumentError, "Invalid value for policy_basis"
-          end
-
-          @policy_basis = "heuristic_unvalidated"
-          @assessment_url = assessment_url
-          @auth_context = auth_context
+          @account = account
         end
 
         sig { params(other: T.untyped).returns(T::Boolean) }
         def ==(other)
           return false unless other.is_a?(self.class)
-          return false unless @assessment_id == other.assessment_id
-          return false unless @account_id == other.account_id
+          return false unless @id == other.id
           return false unless @status == other.status
-          return false unless @confidence == other.confidence
-          return false unless @incomplete_sources == other.incomplete_sources
-          return false unless @policy_version == other.policy_version
-          return false unless @assessment_version == other.assessment_version
-          return false unless @created_at == other.created_at
-          return false unless @updated_at == other.updated_at
-          return false unless @expires_at == other.expires_at
-          return false unless @timing == other.timing
+          return false unless @flow == other.flow
+          return false unless @depth == other.depth
+          return false unless @detail == other.detail
           return false unless @schema_version == other.schema_version
-          return false unless @request_id == other.request_id
-          return false unless @recommendation == other.recommendation
-          return false unless @risk == other.risk
-          return false unless @signals == other.signals
-          return false unless @policy_basis == other.policy_basis
-          return false unless @assessment_url == other.assessment_url
-          return false unless @auth_context == other.auth_context
+          return false unless @account == other.account
           true
         end
       end