calmlens 0.19.0 → 0.21.0

data/lib/calmlens/testing/mock_decision.rb

@@ -82,16 +82,17 @@ module CalmLens
     end
 
     # The report a decided asset gets, as the API sends it: every category (unflagged ones
-    # evaluated with score 0), the policy's actions and `flaggedCategories`.
+    # evaluated with score 0), the policy's actions, the automated status and `flaggedCategories`.
     # @return [Hash{String => Object}, nil] `categories`, `score` and `policy`; nil for `pending` and `failed`
     def report
       return if undecided?
 
       evaluated = (MockClassification::CATEGORIES - @not_evaluated).map { |category| [category, @flags.dig(category, :score) || 0] }
-      { 'raw' => { 'categories' => MockClassification::CATEGORIES.to_h { |category| [category, category_report(category)] } },
+      { 'raw' => { 'categories' => MockClassification::CATEGORIES.to_h { |category| [category, category_report(category)] },
+                   'hashMatches' => [] },
         'categories' => evaluated.to_h { |category, value| [category, { 'score' => value, 'action' => action(value) }] },
-        'explanationComplete' => true, 'source' => 'policy', 'automatedAction' => STATUS_ACTIONS[@status],
-        'regions' => [], 'flaggedCategories' => evaluated.reject { |_, value| action(value) == 'allow' }.map(&:first) }
+        'explanationComplete' => true, 'source' => 'policy', 'rule' => nil, 'automatedStatus' => @status,
+        'regions' => [], 'linkSafety' => nil, 'flaggedCategories' => evaluated.reject { |_, value| action(value) == 'allow' }.map(&:first) }
     end
 
     def inspect = "#<#{self.class.name} #{@status}>"

data/lib/calmlens/testing/rsql.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative 'asset_filters'
+
+module CalmLens
+  module Testing
+    # Asset list filters as the API reads them (zodbase/rsql with @rsql/parser): comparisons joined
+    # by `;` or `and` (binding tighter), `,` or `or`, and grouped with parentheses. A filter names
+    # only {MockAssetFilters::FIELDS}, each with only its own operators; anything else, or
+    # bad syntax, answers 400 `filter/invalid`. A number field's value must be a number,
+    # and `null` is a missing value only on a nullable field. `*` in an `==` or `!=` text value
+    # matches any run of characters regardless of case; without it `==` is exact. As in SQL, a
+    # comparison never matches a missing value.
+    # @api private
+    module RSQL
+      module_function
+
+      # A filter the API refuses, answered as `filter/invalid`.
+      class Invalid < StandardError; end
+
+      def filter(items, expression)
+        return items if expression.nil? || expression.to_s.empty?
+
+        test = Parser.new(Lexer.new(expression.to_s).tokens).parse
+        items.select { |item| test.call(item) }
+      rescue Invalid
+        raise Failure.new(ErrorCodes::INVALID_FILTER, 'Invalid filter', status: 400)
+      end
+
+      # A test for one comparison, refusing a field or operator the API doesn't accept.
+      def comparison(field, operator, raw_values)
+        rule = MockAssetFilters::FIELDS[field]
+        raise Invalid unless rule && rule[:operators].include?(operator)
+
+        values = raw_values.map { |raw| typed(rule, raw) }
+        pattern = values.first.is_a?(String) && values.first.include?('*') ? wildcard(values.first) : nil
+        lambda do |item|
+          actual = field.split('.').reduce(item) { |object, key| object.is_a?(Hash) ? object[key] : nil }
+          # A list holds any of the values (=in=) or none of them (=out=); a missing list holds none.
+          next values.any? { |value| Array(actual).include?(value) } == (operator == '=in=') if rule[:kind] == 'list'
+
+          # Only `==null` matches a missing value.
+          next operator == '==' && values.first.nil? if actual.nil?
+
+          compare([actual], operator, values, pattern)
+        end
+      end
+
+      def compare(entries, operator, values, pattern)
+        first = values.first
+        case operator
+        when '==' then pattern ? entries.any? { |entry| pattern.match?(entry.to_s) } : !first.nil? && entries.include?(first)
+        when '!=' then pattern ? entries.none? { |entry| pattern.match?(entry.to_s) } : first.nil? || !entries.include?(first)
+        when '=in=' then values.compact.any? { |value| entries.include?(value) }
+        when '=out=' then values.none?(&:nil?) && values.none? { |value| entries.include?(value) }
+        else !first.nil? && entries.any? { |entry| ordered?(entry, operator, first) }
+        end
+      end
+
+      # A value as the API reads it for the field: `null` is missing on a nullable field, a number
+      # field's value must be a finite number (as JavaScript's `Number` reads it), and text stays text.
+      def typed(rule, raw)
+        return nil if raw == 'null' && rule[:nullable]
+        return raw unless rule[:kind] == 'number'
+
+        number(raw) || raise(Invalid)
+      end
+
+      RADIXES = { 'x' => 16, 'o' => 8, 'b' => 2 }.freeze
+
+      def number(raw)
+        text = raw.strip
+        return 0 if text.empty?
+        return Integer(text[2..], RADIXES.fetch(text[1].downcase)) if text.match?(/\A0(?:[xX]\h+|[oO][0-7]+|[bB][01]+)\z/)
+        return unless text.match?(/\A[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?\z/)
+
+        value = Float(text)
+        value.finite? ? value : nil
+      end
+
+      # `*` matches any run of characters, ignoring case; every other character matches itself.
+      def wildcard(value)
+        Regexp.new("\\A#{value.split('*', -1).map { |part| Regexp.escape(part) }.join('.*')}\\z",
+                   Regexp::IGNORECASE | Regexp::MULTILINE)
+      end
+
+      # Numbers compare as numbers, text by code point.
+      def ordered?(entry, operator, value)
+        return false unless entry.is_a?(Numeric) == value.is_a?(Numeric)
+
+        entry.public_send(operator, value)
+      end
+
+      # Tokens like @rsql/parser's lexer: quoted values (with backslash escapes), parentheses, `;`
+      # and `,` (or `and ` and `or `), comparison operators (`==`, `!=`, `<`, `<=`, `>`, `>=` and
+      # `=word=`) and unquoted runs up to a reserved character.
+      class Lexer
+        RESERVED = ['"', "'", '(', ')', ';', ',', '=', '!', '~', '<', '>', ' ', "\n", "\t", "\r"].freeze
+        WHITESPACE = [' ', "\n", "\t", "\r"].freeze
+
+        attr_reader :tokens
+
+        def initialize(input)
+          @input = input
+          @index = 0
+          @tokens = []
+          @tokens << next_token while token_ahead?
+        end
+
+        private
+
+        # Skips whitespace; true while input remains.
+        def token_ahead?
+          @index += 1 while @index < @input.length && WHITESPACE.include?(@input[@index])
+          @index < @input.length
+        end
+
+        def next_token
+          char = @input[@index]
+          case char
+          when '"', "'" then quoted(char)
+          when '(', ')' then single(:paren, char)
+          when ';', ',' then single(:logic, char)
+          when '=', '!', '~', '<', '>' then operator
+          else verbose || unquoted
+          end
+        end
+
+        def single(type, char)
+          @index += 1
+          [type, char]
+        end
+
+        def quoted(quote)
+          finish = @index
+          loop do
+            finish = @input.index(quote, finish + 1)
+            raise Invalid if finish.nil?
+
+            slashes = 0
+            slashes += 1 while @input[finish - 1 - slashes] == '\\' && finish - 1 - slashes > @index
+            break if slashes.even?
+          end
+          token = [:quoted, @input[(@index + 1)...finish].gsub(/\\([\s\S])/, '\1')]
+          @index = finish + 1
+          token
+        end
+
+        def operator
+          match = @input[@index..].match(/\A(?:==|!=|<=|>=|<|>|=[a-z]*=)/)
+          raise Invalid unless match
+
+          @index += match[0].length
+          [:operator, match[0]]
+        end
+
+        def verbose
+          match = @input[@index..].match(/\A(and|or) /)
+          return unless match
+
+          @index += match[1].length
+          [:logic, match[1] == 'and' ? ';' : ',']
+        end
+
+        def unquoted
+          finish = @index + 1
+          finish += 1 while finish < @input.length && !RESERVED.include?(@input[finish])
+          token = [:unquoted, @input[@index...finish]]
+          @index = finish
+          token
+        end
+      end
+
+      # Builds the test for a whole filter: `,` (or) of `;` (and) of comparisons and groups.
+      class Parser
+        def initialize(tokens)
+          @tokens = tokens
+          @position = 0
+        end
+
+        def parse
+          test = disjunction
+          raise Invalid unless @position == @tokens.size
+
+          test
+        end
+
+        private
+
+        def peek = @tokens[@position]
+
+        def take
+          token = @tokens[@position] || raise(Invalid)
+          @position += 1
+          token
+        end
+
+        def take_if(token) = peek == token && take
+
+        def disjunction
+          alternatives = [conjunction]
+          alternatives << conjunction while take_if([:logic, ','])
+          ->(item) { alternatives.any? { |test| test.call(item) } }
+        end
+
+        def conjunction
+          terms = [term]
+          terms << term while take_if([:logic, ';'])
+          ->(item) { terms.all? { |test| test.call(item) } }
+        end
+
+        def term
+          if take_if([:paren, '('])
+            test = disjunction
+            raise Invalid unless take == [:paren, ')']
+
+            return test
+          end
+          selector = take
+          operator = take
+          raise Invalid unless selector[0] == :unquoted && operator[0] == :operator
+
+          RSQL.comparison(selector[1], operator[1], arguments)
+        end
+
+        def arguments
+          return [value] unless take_if([:paren, '('])
+
+          values = [value]
+          values << value while take_if([:logic, ','])
+          raise Invalid unless take == [:paren, ')']
+
+          values
+        end
+
+        def value
+          token = take
+          raise Invalid unless %i[unquoted quoted].include?(token[0])
+
+          token[1]
+        end
+      end
+    end
+  end
+end

data/lib/calmlens/testing/test_input_detections.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'classification'
+
+module CalmLens
+  module TestInputs
+    # Checks a test scenario's `detections` (test_input_scenario.rb).
+    # @api private
+    module Detections
+      module_function
+
+      # The people and faces a test image reports, each a list of boxes or `unavailable`.
+      def validate(value)
+        value = Scenario.fields(value, 'detections', %w[people faces], [])
+        checked = {}
+        checked['people'] = list(value['people'], 'people', %w[box confidence]) if value.key?('people')
+        checked['faces'] = list(value['faces'], 'faces', %w[box confidence age]) if value.key?('faces')
+        checked
+      end
+
+      def list(value, name, allowed)
+        return value if value == 'unavailable'
+
+        Scenario.check(value.is_a?(Array), "Detection #{name} must be an Array or 'unavailable'")
+        Scenario.array(value, name, MockClassification::TEST_DETECTIONS_MAX).map do |entry|
+          entry = Scenario.fields(entry, 'detection', allowed, %w[box])
+          checked = { 'box' => check_box(entry['box']) }
+          if entry.key?('confidence')
+            Scenario.check(integer_between?(entry['confidence'], 0, 100), 'Detection confidence must be an Integer from 0 to 100')
+            checked['confidence'] = entry['confidence']
+          end
+          checked['age'] = check_age(entry['age']) if entry.key?('age')
+          checked
+        end
+      end
+
+      # `[left, top, width, height]` in basis points of the image, inside it.
+      def check_box(box)
+        max = MockClassification::TEST_DETECTION_BOX_MAX
+        Scenario.check(box.is_a?(Array) && box.size == 4 && box.all? { |item| integer_between?(item, 0, max) } &&
+                box[0] + box[2] <= max && box[1] + box[3] <= max,
+                       "A detection box is [left, top, width, height]: Integers from 0 to #{max} inside the image")
+        box.dup
+      end
+
+      def check_age(age)
+        return age if age.is_a?(String) && MockClassification::TEST_FACE_AGE_PRESETS.include?(age)
+
+        max = MockClassification::TEST_FACE_AGE_MAX
+        age = Scenario.fields(age, 'age', %w[low high], %w[low high]) if age.is_a?(Hash)
+        Scenario.check(age.is_a?(Hash) && integer_between?(age['low'], 0, max) && integer_between?(age['high'], age['low'], max),
+                       "A face age is #{MockClassification::TEST_FACE_AGE_PRESETS.join(' or ')}, or Integers low to high from 0 to #{max}")
+        { 'low' => age['low'], 'high' => age['high'] }
+      end
+
+      def integer_between?(value, min, max) = value.is_a?(Integer) && value.between?(min, max)
+    end
+
+    private_constant :Detections
+  end
+end

data/lib/calmlens/testing/test_input_scenario.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'classification'
+require_relative 'test_input_detections'
 
 module CalmLens
   # The scenario checks behind the signed test inputs (test_inputs.rb).
@@ -23,6 +24,7 @@ module CalmLens
         when Hash then "{#{value.map { |key, item| "\"#{key}\":#{canonical_json(item)}" }.join(',')}}"
         when Array then "[#{value.map { |item| canonical_json(item) }.join(',')}]"
         when Float then js_number(value)
+        when Integer then value.to_s
         else "\"#{value}\""
         end
       end
@@ -49,7 +51,7 @@ module CalmLens
 
       # Checks a scenario and returns it with camelCase String keys in canonical order.
       def validate(input)
-        input = fields(input, 'scenario', %w[regionalActions unassessedCategories instances], %w[instances])
+        input = fields(input, 'scenario', %w[regionalActions unassessedCategories instances detections], %w[instances])
         instances = array(input['instances'], 'instances', 128).map { |instance| check_instance(instance) }
         with_action = instances.count { |instance| instance.key?('action') }
         check([0, instances.size].include?(with_action), 'Set an action for every instance or omit all actions')
@@ -72,7 +74,9 @@ module CalmLens
           end
           checked['unassessedCategories'] = unassessed
         end
-        checked.merge('instances' => instances)
+        checked['instances'] = instances
+        checked['detections'] = Detections.validate(input['detections']) if input.key?('detections')
+        checked
       end
 
       def check_instance(instance)

data/lib/calmlens/testing/test_inputs.rb

@@ -8,8 +8,9 @@ require_relative 'test_image_grid'
 module CalmLens
   # Signed test inputs: text codes, test images and media phrases that a project's moderation
   # recognises as a declared scenario when they are signed with its secret test input key (shown in
-  # the portal's project settings), so CalmLens returns that scenario instead of classifying them.
-  # The formats match the JavaScript SDK's `calmlens/test-inputs` byte for byte.
+  # the portal's project settings to those who can read them) and the project has "Recognise test
+  # inputs" turned on, so CalmLens returns that scenario instead of classifying them. The formats
+  # match the JavaScript SDK's `calmlens/test-inputs` byte for byte.
   #
   # A scenario is a Hash with the API's keys, as Strings or Symbols (snake_case keys are converted
   # to camelCase like other options):
@@ -20,8 +21,14 @@ module CalmLens
   # 1) and `action` (`allow`, `limit`, `age-restrict` or `block`, on every instance or none) are
   # optional. `unassessedCategories` lists categories reported as not assessed, none with instances;
   # `regionalActions` gives up to one `limit`, `age-restrict` or `block` action for each of
-  # {REGIONS}. Values are Strings and Numerics. An absent list is left out of the signed scenario;
-  # an empty one is sent as `[]`. Anything else raises `sdk/invalid-argument`.
+  # {REGIONS}. `detections` (optional, `people` and `faces` each optional) sets the person and face
+  # detection results a test image reports: each list holds at most 32 entries, or is the String
+  # `'unavailable'` to report the feature as not evaluated. An entry has a `box`, `[left, top, width,
+  # height]` as Integers in basis points of the image (0 to 10000, inside it), and an optional
+  # Integer `confidence` from 0 to 100; a face may also have an `age`, `'adult'`, `'minor'` or
+  # `{ 'low' => 30, 'high' => 40 }` (Integers from 0 to 120). Values are Strings and Numerics. An
+  # absent list is left out of the signed scenario; an empty one is sent as `[]`. Anything else
+  # raises `sdk/invalid-argument`.
   #
   # @example
   #   code = CalmLens::TestInputs.generate_text_code('harassment.insult', test_input_key)
@@ -47,8 +54,11 @@ module CalmLens
       value.each { |item| deep_freeze.call(item) } if value.is_a?(Array)
       value.freeze
     end
+    person = { 'box' => [2500, 1500, 5000, 8500] }
+    face = ->(age = nil) { { 'box' => [3500, 2000, 3000, 3500], **(age ? { 'age' => age } : {}) } }
     # Ready-made scenarios (deeply frozen): a clean input, a limited one, adult images and text,
-    # regional delivery, content restricted in Germany, and mixed instances in one category.
+    # regional delivery, content restricted in Germany, mixed instances in one category, and test
+    # images with one person and face, nobody, an adult's face, a minor's face and a group of three.
     PRESETS = deep_freeze.call(
       clean: { 'instances' => [] },
       limited: one.call('harassment', 'harassment-abuse'),
@@ -59,7 +69,15 @@ module CalmLens
                                                                     { 'region' => 'FR', 'action' => 'limit' }] },
       germany: one.call('hate', 'hate-symbol', 'hate-nazi-symbols-public-display'),
       mixed: { 'instances' => [{ 'category' => 'harassment', 'qualifiers' => %w[harassment-abuse harassment-documentary] },
-                               { 'category' => 'harassment', 'qualifiers' => ['harassment-threat'] }] }
+                               { 'category' => 'harassment', 'qualifiers' => ['harassment-threat'] }] },
+      one_face: { 'instances' => [], 'detections' => { 'people' => [person], 'faces' => [face.call] } },
+      no_face: { 'instances' => [], 'detections' => { 'people' => [], 'faces' => [] } },
+      adult_face: { 'instances' => [], 'detections' => { 'people' => [person], 'faces' => [face.call('adult')] } },
+      minor_face: { 'instances' => [], 'detections' => { 'people' => [person], 'faces' => [face.call('minor')] } },
+      group: { 'instances' => [], 'detections' => {
+        'people' => [500, 3600, 6700].map { |left| { 'box' => [left, 2000, 2800, 8000] } },
+        'faces' => [1200, 4300, 7400].map { |left| { 'box' => [left, 2500, 1400, 2000] } }
+      } }
     )
 
     HEX_WORDS = %w[zero one two three four five six seven eight nine alpha bravo charlie delta echo foxtrot].freeze
@@ -82,15 +100,16 @@ module CalmLens
                when 'sexual.adult' then PRESETS[kind == 'image' ? :adult_image : :adult_text]
                when 'hate.regional-symbol' then PRESETS[:germany]
                when 'sexual.involving-minors' then { 'instances' => [{ 'category' => 'sexual', 'qualifiers' => ['sexual-minors'] }] }
-               when 'violence.graphic' then { 'instances' => [{ 'category' => 'violence', 'qualifiers' => ['violence-graphic'] }] }
+               when 'violence.graphic'
+                 { 'instances' => [{ 'category' => 'violence', 'qualifiers' => %w[violence-injury violence-graphic] }] }
                when *MockClassification::CATEGORIES then { 'instances' => [{ 'category' => signal, 'qualifiers' => [] }] }
                else raise Internal.invalid("Unknown test signal #{signal.inspect}")
                end
       Marshal.load(Marshal.dump(preset))
     end
 
-    # The signed text code for a scenario or a signal (one of {SIGNALS}): put it anywhere in a text
-    # input.
+    # The signed text code for a scenario or a signal (one of {SIGNALS}). Submit it as the whole
+    # text: CalmLens moderates text with anything else around the code as ordinary content.
     # @param input [Hash, String] a scenario or a signal
     # @param test_input_key [String] the project's secret test input key from the portal
     # @return [String]
@@ -100,7 +119,9 @@ module CalmLens
     end
 
     # Paints the signed test image for a scenario or a signal (one of {SIGNALS}): a grid that
-    # survives lossy formats and resizing. Upload its `png`, or encode its `rgba` in any format.
+    # survives lossy formats and resizing. Upload its `png`, or encode its `rgba` in any format, as
+    # the whole image, optionally on a plain single-colour border: CalmLens moderates an image with
+    # anything else in it as ordinary content.
     # @param input [Hash, String] a scenario or a signal
     # @param test_input_key [String] the project's secret test input key from the portal
     # @return [Image]
@@ -135,11 +156,12 @@ module CalmLens
       Scenario.validate(input.is_a?(String) ? for_signal(input, kind) : input)
     end
 
+    # The signed payload is the scenario's canonical JSON.
     def text_code(checked, test_input_key)
       payload = [Scenario.canonical_json(checked)].pack('m0').tr('+/', '-_').delete('=')
       raise Internal.invalid('Test scenario is too large') if payload.bytesize > 8000
 
-      "<!calmlens-test #{tag(test_input_key, "calmlens-test:v1:#{payload}")} #{payload}>"
+      "<!calmlens-test #{tag(test_input_key, "calmlens-test:v2:#{payload}")} #{payload}>"
     end
 
     def check_key(key)

data/lib/calmlens/testing.rb

@@ -22,9 +22,12 @@ module CalmLens
   # A `purged` outcome removes the content with reason `policy`. The CDN answers like the real one:
   # `asset/not-available` (403) for blocked, purged, failed or removed content,
   # `viewer/age-confirmation-required` (403) for an age-restricted asset without
-  # `viewer_claims: {age_confirmed: true}`, whatever the key, and `asset/api-key-missing-permission` (403)
+  # `viewer_claims: {age_confirmed: true}`, whatever the key, and `auth/permission-denied` (403)
   # for a private asset unless `api_key` comes from {.create_api_key} with an `assets:download`
-  # grant. The default key has no grants. {#decide} applies a reviewer's decision, and
+  # grant (the default key has no grants), or the URL is signed: {CDN#sign_asset_url} returns
+  # `{cdn_base_url}/assets/{project_id}/sig_…`, a readable grant that only the mock's CDN accepts,
+  # which serves `original` only when signed with `original: true`. {#fetch_cdn} loads such a URL
+  # without the API key, as a browser would. {#decide} applies a reviewer's decision, and
   # {Assets#wait_for_decision} takes no real time: a pending asset times out at once.
   # Filters join comparisons with `;` (and), which binds tighter than `,` (or), and group them with
   # `( … )`; list cursors resume after the last item returned. {Assets#search} is the API's keyword
@@ -60,13 +63,15 @@ module CalmLens
     # Simulated failures for {#fail_next_request}, besides API error codes and exceptions.
     REQUEST_FAILURES = %w[transport-error timeout].freeze
     # The methods {#fail_next_request} can target, by resource. Iterators are their list calls.
-    OPERATIONS = { assets: %i[search list retrieve list_children update create classify upload_part create_signed_url move
-                              retry explain wait_for_decision delete_content delete batch],
+    OPERATIONS = { assets: %i[search list retrieve list_children list_timeline update create classify upload_part move
+                              retry explain wait_for_decision remove_content delete batch],
                    folders: %i[list retrieve create update delete move],
                    hash_lists: %i[list retrieve create update delete list_entries add_entry remove_entry],
-                   policies: %i[list retrieve create update apply_preset set_automatic_updates delete assign],
+                   policies: %i[list retrieve retrieve_assigned create update reset upgrade set_automatic_updates delete
+                                assign],
+                   lenses: %i[list create retrieve update delete],
                    text: %i[classify], events: %i[list],
-                   cdn: %i[serve] }.freeze
+                   cdn: %i[serve sign_asset_url get_asset_info] }.freeze
     private_constant :OPERATIONS
     # The operation names {#fail_next_request} accepts, in their camelCase form.
     OPERATION_NAMES = (OPERATIONS.flat_map do |resource, methods|
@@ -128,7 +133,7 @@ module CalmLens
       -> { lock.synchronize { last = [(Time.now.to_f * 1000).to_i, last + 1].max } }
     end
 
-    # @param project_id [String]
+    # @param project_id [String] `project-1` by default.
     # @param api_key [String] a key from {.create_api_key}; the default has no grants.
     # @param now [#call] returns the current time in epoch milliseconds. The default clock reads the
     #   system time but advances at least 1 ms per reading, so records made in a row have strictly
@@ -141,7 +146,9 @@ module CalmLens
     #   queue the work) and returns a status from {MockDecision::STATUSES} or a {MockDecision}. It is
     #   called on uploads (`assets.create`, `assets.classify`, `text.classify` and a final part:
     #   trigger `upload`), `assets.retry` (`retry`), `assets.explain` with `rerun: true` (`rerun`) and
-    #   {#complete_processing} without a decision (`complete`). `pending` leaves the asset processing.
+    #   {#complete_processing} without a decision (`complete`). `pending` leaves the asset processing;
+    #   for a re-run it keeps the asset's decision until {#complete_processing}, and a failed re-run
+    #   keeps it.
     #   Without it, queued work other than `complete` stays `pending` and the rest is `allowed`. It
     #   runs while the mock handles a request, so it must not call the mock.
     # @param max_retries [Integer] retries after a retryable failure; 0 by default, so a simulated
@@ -162,7 +169,8 @@ module CalmLens
       super(api_key: api_key, project_id: project_id, base_url: base_url, cdn_base_url: cdn_base_url, max_retries: max_retries,
             **options, transport: method(:receive))
       @fake = Testing::FakeAPI.new(project_id: project_id, base_url: self.base_url, cdn_base_url: self.cdn_base_url,
-                                   now: now, create_id: create_id, moderate: moderate, grants: MockServerClient.grants_of(api_key))
+                                   now: now, create_id: create_id, moderate: moderate, api_key: api_key,
+                                   grants: MockServerClient.grants_of(api_key))
       @state = @fake.state
       # Like the API, the stand-in checks upload sizes itself, in the API's order.
       @session.defer_upload_checks = true
@@ -174,8 +182,9 @@ module CalmLens
     end
 
     # Applies a reviewer's decision to a stored asset, as the portal or API would: the moderation
-    # status changes (`purged` also removes the content), the review joins `manualReviews`, and an
-    # `asset.<decision>` event with a `decided-by: reviewer` fact joins the events feed.
+    # status changes (`purged` also removes the content), the review joins `manualReviews` with
+    # `decidedBy` the mock API key (`{ 'type' => 'api-key', 'id' => nil }`) and `applied: true`, and an
+    # `asset.<decision>` event whose `actor` is a `user` joins the events feed.
     # @param asset_id [String]
     # @param decision [String] `allowed`, `limited`, `age-restricted`, `blocked` or `purged`
     # @return [Hash] the asset
@@ -193,7 +202,8 @@ module CalmLens
     # @param decision [String, MockDecision, nil] a status from {MockDecision::STATUSES} or a {MockDecision}
     # @return [Hash] the asset
     # @raise [APIError] `asset/not-found` for an unknown asset
-    # @raise [InvalidArgumentError] when the asset isn't processing, or for an unknown decision
+    # @raise [InvalidArgumentError] when the asset isn't processing or awaiting a queued re-run, or for
+    #   an unknown decision
     def complete_processing(asset_id, decision = nil)
       @mock_lock.synchronize { @fake.complete_processing(asset_id, decision) } || raise(not_found)
     end
@@ -228,6 +238,9 @@ module CalmLens
         raise Internal.invalid('retry_after must be a whole number of seconds')
       end
       raise Internal.invalid('details must be a Hash') unless details.nil? || details.is_a?(Hash)
+      if !(failure.is_a?(String) && ErrorCodes::STATUSES.key?(failure)) && !(details.nil? && retry_after.nil?)
+        raise Internal.invalid('details and retry_after apply only to an API error code')
+      end
 
       name = operation && operation.to_s.split('.').map { |part| Internal.camelize(part) }.join('.')
       if name && !OPERATION_NAMES.include?(name)
@@ -238,6 +251,18 @@ module CalmLens
       self
     end
 
+    # Fetches a URL of the mock's CDN as a browser would, with a GET and without the API key: a signed
+    # asset URL from {CDN#sign_asset_url} (with a resource appended), or a public one from
+    # {CDN#get_asset_url}. The request is recorded like any other. Error statuses are returned, not
+    # raised.
+    # @param url [String]
+    # @return [Response] with its body read
+    def fetch_cdn(url)
+      raise Internal.invalid('url must be a String') unless url.is_a?(String)
+
+      @session.cdn('GET', url, {}, {}, authenticate: false)
+    end
+
     # @see ServerClient#ensure_lenses
     def ensure_lenses(options) = operation('ensureLenses') { super }
 
@@ -272,7 +297,9 @@ module CalmLens
     end
 
     # Adds an event to the mock's events feed. Fields you omit (`id`, `projectId`, `createdAt`,
-    # `severity`, `title`, `facts`, and nil `description` and `assetId`) are filled in. An event
+    # `severity`, `title`, `facts`, and nil `description` and `assetId`) are filled in, and `actor`
+    # is the mock API key (`{ 'type' => 'api-key', 'id' => nil }`) unless you pass one, such as
+    # `actor: { type: 'user', id: nil }`. An event
     # with the `asset_id` of a stored asset carries that asset's snapshot as it is now, unless you
     # pass `asset`.
     # @param event [Hash] at least `type:`; snake_case keys are converted.