moderate 1.0.0.beta1 → 1.0.0

data/examples/regexp_pattern_adapter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# ──────────────────────────────────────────────────────────────────────────────
+# REFERENCE ADAPTER — NOT shipped, NOT loaded, NOT a dependency of `moderate`.
+#
+# Patterns a word list can't express: phone numbers, links, e-mail addresses,
+# "contact me on…" — the off-platform contact and spam shapes a marketplace or a
+# chat wants to see. The idea comes from @killondark's PR #1 (2025), written
+# against the 0.x validator; this is the same idea in 1.0's adapter contract.
+#
+# ── How to use it ─────────────────────────────────────────────────────────────
+#   1. Copy this file into your app (e.g. app/adapters/regexp_pattern_adapter.rb).
+#   2. Register it with your patterns, each under the category it means, and point a
+#      field at it. It's synchronous, so :block works as well as :flag:
+#          Moderate.configure do |config|
+#            config.register_adapter :patterns, RegexpPatternAdapter.new(
+#              spam: [%r{https?://}i, /\bwhats\s*app\b/i],
+#              privacy: [/\b\d{3}[\s.-]?\d{3}[\s.-]?\d{3}\b/]       # a 9-digit phone number
+#            )
+#            config.filter "Message", :body, with: :patterns, mode: :flag
+#          end
+#   3. Categories are yours: any Symbol works. Choose names your queue and your
+#      `config.report_categories` already speak (an enforced flag files its report
+#      under the first category the community list also has).
+#
+# ── What it returns ───────────────────────────────────────────────────────────
+# A Moderate::Result with one Label per category that matched (score 1.0, input
+# :text), `allowed: false` when anything matched, and the matched fragments in
+# `raw[:matches]` so the queue can show WHAT tripped it.
+# ──────────────────────────────────────────────────────────────────────────────
+class RegexpPatternAdapter
+  # @param patterns [Hash{Symbol=>Regexp, Array<Regexp>}] category => pattern(s)
+  def initialize(patterns = {}, **keyword_patterns)
+    @patterns = patterns.to_h.merge(keyword_patterns).to_h do |category, list|
+      list = Array(list)
+      unless list.all?(Regexp)
+        given = list.map(&:class).uniq.join(", ")
+        raise ArgumentError, "RegexpPatternAdapter: #{category.inspect} needs Regexp patterns, got #{given}"
+      end
+
+      [category.to_sym, list.freeze]
+    end.freeze
+  end
+
+  # A regexp runs in-process: safe for :block (a validation) as well as :flag.
+  def synchronous? = true
+
+  def classify(value)
+    matches = matches_in(value.to_s)
+
+    Moderate::Result.new(
+      allowed: matches.empty?,
+      labels: matches.keys.map { |category| Moderate::Label.new(category: category, score: 1.0, input: :text) },
+      source: "patterns",
+      raw: { matches: matches }
+    )
+  end
+
+  private
+
+  # category => the distinct fragments of `text` its patterns matched
+  def matches_in(text)
+    @patterns.each_with_object({}) do |(category, list), found|
+      hits = list.flat_map { |pattern| text.scan(pattern).map { |hit| Array(hit).first.to_s } }.reject(&:empty?)
+      found[category] = hits.uniq if hits.any?
+    end
+  end
+end

data/gemfiles/{rails_7.1.gemfile → rails_8.0.gemfile}

@@ -3,30 +3,32 @@
 source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
-gem "rails", "~> 7.1.0"
+gem "rails", "~> 8.0.5", ">= 8.0.5.1"
+gem "json", ">= 2.19.9", "< 3"
 
 group :development do
   gem "appraisal"
+  gem "bundler-audit", require: false
   gem "web-console"
-  gem "standard"
   gem "rubocop", "~> 1.0"
   gem "rubocop-minitest", "~> 0.35"
   gem "rubocop-performance", "~> 1.0"
+  gem "standard"
 end
 
 group :test do
   gem "minitest", "~> 5.0"
   gem "mocha"
   gem "simplecov", require: false
-  gem "activejob"
   gem "actionmailer"
+  gem "activejob"
   gem "activestorage"
-  gem "sqlite3"
-  gem "pg"
   gem "mysql2"
+  gem "pg"
+  gem "sqlite3"
   gem "bootsnap", require: false
-  gem "puma"
   gem "importmap-rails"
+  gem "puma"
   gem "sprockets-rails"
   gem "stimulus-rails"
   gem "turbo-rails"

data/gemfiles/rails_8.1.gemfile

@@ -7,26 +7,27 @@ gem "rails", "~> 8.1.0"
 
 group :development do
   gem "appraisal"
+  gem "bundler-audit", require: false
   gem "web-console"
-  gem "standard"
   gem "rubocop", "~> 1.0"
   gem "rubocop-minitest", "~> 0.35"
   gem "rubocop-performance", "~> 1.0"
+  gem "standard"
 end
 
 group :test do
   gem "minitest", "~> 5.0"
   gem "mocha"
   gem "simplecov", require: false
-  gem "activejob"
   gem "actionmailer"
+  gem "activejob"
   gem "activestorage"
-  gem "sqlite3"
-  gem "pg"
   gem "mysql2"
+  gem "pg"
+  gem "sqlite3"
   gem "bootsnap", require: false
-  gem "puma"
   gem "importmap-rails"
+  gem "puma"
   gem "sprockets-rails"
   gem "stimulus-rails"
   gem "turbo-rails"

data/lib/generators/moderate/install_generator.rb

@@ -5,6 +5,7 @@ require "rails/generators/active_record"
 
 module Moderate
   module Generators
+    # `rails generate moderate:install`: the adaptive migration and the initializer.
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
@@ -19,6 +20,23 @@ module Moderate
         migration_template "create_moderate_tables.rb.erb", File.join(db_migrate_path, "create_moderate_tables.rb")
       end
 
+      # The gem's own migrations (db/migrate: what changed since the tables above were
+      # first shipped), copied AFTER create_moderate_tables and in their order, the way
+      # `bin/rails moderate:install:migrations` copies them: "<number>_<name>.moderate.rb".
+      # An app holding copies runs those, and the engine then leaves the gem's
+      # db/migrate out of its paths (see the "moderate.migrations" initializer), so no
+      # migration is ever found twice. One already in the app, by name, is skipped.
+      def copy_gem_migrations
+        dir = File.expand_path(db_migrate_path, destination_root)
+        Dir[Moderate::Engine.root.join("db/migrate/[0-9]*_*.rb").to_s].each do |source|
+          version, name = File.basename(source, ".rb").split("_", 2)
+          next if Dir.glob(File.join(dir, "[0-9]*_#{name}{,.*}.rb")).any?
+
+          number = self.class.next_migration_number(dir)
+          create_file File.join(db_migrate_path, "#{number}_#{name}.moderate.rb"), copied_migration(source, version)
+        end
+      end
+
       def create_initializer
         template "initializer.rb", "config/initializers/moderate.rb"
       end
@@ -48,6 +66,13 @@ module Moderate
 
       private
 
+      # As Rails' engine copy writes it: magic comments first, then where it came from.
+      def copied_migration(source, version)
+        body = File.read(source)
+        magic = body[/\A(?:#.*\b(?:coding|frozen_string_literal):.*\n)+/].to_s
+        "#{magic}# This migration comes from moderate (originally #{version})\n#{body.delete_prefix(magic)}"
+      end
+
       def migration_version
         "[#{ActiveRecord::VERSION::STRING.to_f}]"
       end

data/lib/generators/moderate/templates/create_moderate_tables.rb.erb

@@ -151,6 +151,11 @@ class CreateModerateTables < ActiveRecord::Migration<%= migration_version %>
     add_index :moderate_flags, [:owner_id, :status], name: "index_moderate_flags_on_owner_id_and_status"
     add_index :moderate_flags, [:status, :created_at], name: "index_moderate_flags_on_status_and_created_at"
 
+    # moderate_flags.pending_key (at most one PENDING flag per content + field) is NOT
+    # here: the gem's own AddPendingKeyToModerateFlags creates it, for a fresh install
+    # (moderate:install copies it right after this migration) and an upgrade alike, so
+    # one migration creates it everywhere and its `down` drops only what it created.
+
     # Flag's mode/source/status vocabularies are validated in Moderate::Flag
     # (constants + inclusion validations), not by DB CHECK constraints — same
     # migration-free-taxonomy rationale as moderate_reports above.
@@ -187,6 +192,11 @@ class CreateModerateTables < ActiveRecord::Migration<%= migration_version %>
     add_index :moderate_appeals, [:status, :created_at], name: "index_moderate_appeals_on_status_and_created_at"
     add_index :moderate_appeals, :appellant_email, name: "index_moderate_appeals_on_appellant_email"
 
+    # The 1.0 retention columns (redacted_at, held_until) and moderate_classifications
+    # are NOT here: the gem's own AddRetentionAndClassificationsToModerateTables creates
+    # them, for a fresh install (moderate:install copies it after this migration) and
+    # an upgrade alike, so its `down` drops only what it created.
+
     # Appeal's source/status vocabularies are validated in Moderate::Appeal
     # (constants + inclusion validations), not by DB CHECK constraints — same
     # migration-free-taxonomy rationale as moderate_reports above.
@@ -212,7 +222,7 @@ class CreateModerateTables < ActiveRecord::Migration<%= migration_version %>
   # Returns an empty-hash default for SQLite/PostgreSQL, nil for MySQL.
   # Models handle nil metadata gracefully by defaulting to {} in their accessors.
   def json_column_default
-    return nil if connection.adapter_name.downcase.include?("mysql")
+    return nil if mysql?
 
     {}
   end
@@ -220,11 +230,16 @@ class CreateModerateTables < ActiveRecord::Migration<%= migration_version %>
   # Same MySQL caveat as `json_column_default`, but for list-shaped columns,
   # which default to an empty array on SQLite/PostgreSQL.
   def json_array_default
-    return nil if connection.adapter_name.downcase.include?("mysql")
+    return nil if mysql?
 
     []
   end
 
+  # MySQL under either of Rails' adapters: mysql2, or Trilogy (Rails 7.1+).
+  def mysql?
+    connection.adapter_name.downcase.match?(/mysql|trilogy/)
+  end
+
   # The SQL function for COUNTING CHARACTERS in a check constraint, chosen per
   # adapter so the message-length guard is portable:
   #   - SQLite has no `char_length`; its `length(text)` already counts CHARACTERS.

data/lib/generators/moderate/templates/initializer.rb

@@ -104,7 +104,8 @@ Moderate.configure do |config|
   # same place. No-op by default.
   #
   # The full event vocabulary:
-  #   :report_received        :report_decision        :affected_user_decision
+  #   :report_received        :notice_received
+  #   :report_decision        :affected_user_decision
   #   :appeal_received        :appeal_decision
   #   :user_blocked           :user_unblocked         :user_banned
   #   :content_flagged        :content_removed
@@ -139,9 +140,15 @@ Moderate.configure do |config|
   # `moderate` doesn't own your user lifecycle, so it never bans a user itself.
   # When a moderator resolves a report with `ban_user: true`, this proc decides
   # what "banned" means in your domain — suspend, soft-delete, flip a flag, etc.
-  # Signature uses keyword args. No-op by default (the action still audits).
+  # Signature uses keyword args. Required before any ban: with none set,
+  # `ban_user: true` raises instead of claiming a suspension that never happened.
   #
   # config.ban_handler = ->(user:, by:, reason:) { user.suspend!(reason: reason) }
+  #
+  # If your app can lift a ban, tell moderate whether a person is banned NOW, so a
+  # second ban after an unban is applied again instead of counted as already done:
+  #
+  # config.banned = ->(user) { user.suspended? }
 
   # ==========================================================================
   # PUBLIC FORM HUMAN VERIFICATION — optional per-request skips
@@ -173,19 +180,6 @@ Moderate.configure do |config|
   #
   # config.transparency_report_enabled = true
 
-  # ==========================================================================
-  # SIGNED LINKS — purposes for the signed Global IDs in emails & notices
-  # ==========================================================================
-  #
-  # `moderate` mints signed, single-purpose links (e.g. an appeal link in a
-  # decision email, a confirm-receipt link in a DSA notice). These purposes
-  # scope each signature so a link minted for one action can't be replayed for
-  # another. The defaults cover the built-in flows; add your own if you mint
-  # custom signed links against moderate records.
-  #
-  # Default: [:appeal, :confirm_notice, :unsubscribe]
-  # config.signed_gid_purposes = [:appeal, :confirm_notice, :unsubscribe]
-
   # ==========================================================================
   # LOCALE
   # ==========================================================================

data/lib/generators/moderate/views_generator.rb

@@ -41,9 +41,9 @@ module Moderate
         end
 
         # The engine layout (only if one ships under layouts/moderate).
-        if include?("layout")
-          directory "layouts/moderate", "app/views/layouts/moderate" if engine_view_exists?("layouts/moderate")
-        end
+        return unless include?("layout")
+
+        directory "layouts/moderate", "app/views/layouts/moderate" if engine_view_exists?("layouts/moderate")
       end
 
       private

data/lib/moderate/attachments.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Moderate
+  # What the filter and ClassifyJob need to know about an Active Storage value
+  # before they hand it to an adapter, and the claim protocol that makes each set of
+  # files classified once per record without holding a lock during the adapter call.
+  #
+  # ── Claim, classify, complete ───────────────────────────────────────────────
+  # `classify_once` runs in three steps:
+  #
+  #   1. under the CONTENT record's row lock (content first, like every lock in the
+  #      gem): stop if this record's field is already classified for exactly these
+  #      files, or if another worker holds a live claim on them; else write our
+  #      claim (a moderate_classifications row) and release the lock;
+  #   2. call the adapter, outside any lock — a slow provider never blocks writes to
+  #      the content's row (a user's, for an avatar);
+  #   3. under the lock again: if the field still holds the same files and the claim
+  #      is still ours, file the flag, stamp the row classified and clear the
+  #      claim; otherwise discard the result (the files changed — the new set has
+  #      its own classification — or our claim expired and another worker took it).
+  #
+  # A claim expires after `config.classification_claim_ttl` (10 minutes by default,
+  # at most a day), so a worker that died mid-call doesn't block the files forever:
+  # the next look after expiry overrides it. An adapter that RAISES also leaves its
+  # claim until expiry, and nothing here schedules a retry for it: a later attempt
+  # takes it over — the after-upload guard job, a job's one recheck at the claim's
+  # expiry, a new save of the field, or your job backend retrying the same job (same
+  # job id, so the claim is still its own).
+  #
+  # ── Where the claims live ──────────────────────────────────────────────────────
+  # In the gem's own table, `moderate_classifications` (Moderate::Classification):
+  # one row per record, field and exact set of files (a digest of their ordered blob
+  # ids), UNIQUE on those four, holding the claim (`claimed_by`, `claimed_at`) and
+  # the completion (`classified_at`). Rows are written only under the content
+  # record's lock, so nothing else — another record sharing the blob, Active
+  # Storage's analyzer rewriting `blob.metadata` — can touch them. The same files on
+  # another record, or a changed set on this one, are a different row: classified
+  # again.
+  #
+  # @api private
+  module Attachments
+    module_function
+
+    def attachment?(value)
+      value.respond_to?(:attached?) && defined?(::ActiveStorage::Blob) ? true : false
+    end
+
+    def blobs(value)
+      return [] unless attachment?(value)
+
+      found = value.respond_to?(:blobs) ? value.blobs.to_a : [value.try(:blob)]
+      found.grep(::ActiveStorage::Blob).sort_by(&:id)
+    end
+
+    def blob_ids(value)
+      blobs(value).map(&:id)
+    end
+
+    # Every file behind the value is on its service (a value with no blobs, or one
+    # that isn't an attachment at all, has nothing to wait for).
+    def uploaded?(value)
+      blobs(value).all? { |blob| blob.service.exist?(blob.key) }
+    end
+
+    # A stored blob whose file isn't on its service: a direct upload still in flight.
+    # A blob this save is about to upload (not persisted yet) has its bytes in hand.
+    def upload_unfinished?(value)
+      blobs(value).any? { |blob| blob.persisted? && !blob.service.exist?(blob.key) }
+    end
+
+    def classified?(record, field, value)
+      found = blobs(value)
+      found.any? && Classification.for_set(record, field, digest(found)).where.not(classified_at: nil).exists?
+    end
+
+    # The whole protocol (see the module comment). `read` returns the field's value
+    # as committed now (it is called under the lock, twice); `classify` calls the
+    # adapter; `file` files the flag for a flagged result. Returns one of:
+    #   :classified   — classified by us, marked
+    #   :done         — already classified for these files
+    #   :claimed      — another worker holds a live claim (with its expiry, see #claim_expires_at)
+    #   :discarded    — the files changed, or the claim was lost, while the adapter ran
+    #   :empty        — nothing attached any more
+    def classify_once(record, field, owner:, read:, classify:, file:, now: Time.current)
+      claim = Moderate.with_row_lock(record) { claim!(record, field, read.call, owner: owner, now: now) }
+      return claim[:status] unless claim[:status] == :claimed_by_us
+
+      result = classify.call(claim[:value])
+
+      Moderate.with_row_lock(record) do
+        value = read.call
+        found = blobs(value)
+        row = Classification.find_by(id: claim[:row].id)
+        if row && found.map(&:id) == claim[:blob_ids] && row.claimed_by == owner
+          file.call(value, result) if result.flagged?
+          row.update!(classified_at: Time.current, claimed_by: nil, claimed_at: nil,
+            adapter: result.source.to_s.presence, flagged: result.flagged?)
+          :classified
+        else
+          Classification.where(id: claim[:row].id, claimed_by: owner).update_all(claimed_by: nil, claimed_at: nil)
+          :discarded
+        end
+      end
+    end
+
+    # When a live claim held by someone else expires (nil if there isn't one).
+    def claim_expires_at(record, field, value)
+      found = blobs(value)
+      claimed_at = found.any? && Classification.for_set(record, field, digest(found)).pick(:claimed_at)
+      claimed_at && (claimed_at + claim_ttl)
+    end
+
+    def claim_ttl
+      Moderate.config.classification_claim_ttl.to_i
+    end
+
+    def digest(found)
+      Digest::SHA256.hexdigest(found.map(&:id).sort.join(","))[0, 16]
+    end
+
+    # --- Under the lock ------------------------------------------------------------
+
+    def claim!(record, field, value, owner:, now:)
+      found = blobs(value)
+      return { status: :empty } if found.empty?
+
+      row = Classification.for_set(record, field, digest(found)).first_or_initialize
+      return { status: :done } if row.classified?
+      return { status: :claimed } if row.claimed_by.present? && row.claimed_by != owner && row.claimed_at > now - claim_ttl
+
+      row.update!(claimed_by: owner, claimed_at: now)
+      { status: :claimed_by_us, row: row, blob_ids: found.map(&:id), value: value }
+    rescue ActiveRecord::RecordNotUnique
+      { status: :claimed } # another worker inserted the row first (only without row locks)
+    end
+  end
+end

data/lib/moderate/configuration.rb

@@ -15,7 +15,8 @@ module Moderate
   #     plain-English ArgumentError on a bad value — failing fast at the assignment
   #     line. `validate!` runs once more at the end of `configure` for cross-field
   #     checks (e.g. a :block filter pointed at an async adapter).
-  #   - Every hook (`audit`/`notify`/`on_block`/`ban_handler`) defaults to a no-op,
+  #   - Every hook (`audit`/`notify`/`on_block`/`ban_handler`) defaults to a no-op
+  #     (`ban_handler` refuses a ban it can't apply rather than faking one),
   #     so the gem works untouched and a host wires hooks only as needed.
   #
   # This mirrors the validating-setter convention across the ecosystem
@@ -57,11 +58,51 @@ module Moderate
     attr_accessor :report_categories
 
     # --- Hooks (all no-op by default) ----------------------------------------
-    attr_accessor :audit, :notify, :on_block, :ban_handler
+    attr_accessor :audit, :notify, :on_block
+    attr_reader :ban_handler # its writer (below) refuses a non-callable and tracks configured?
 
     # --- Misc -----------------------------------------------------------------
     attr_accessor :locale
 
+    # --- Attachment classification ----------------------------------------------
+    # How long a worker's claim on a set of attached files lasts (seconds, or an
+    # ActiveSupport::Duration) before another worker may take it over: longer than
+    # your slowest adapter call, short enough that a worker that died mid-call doesn't
+    # leave the files unclassified for long. See Moderate::Attachments.
+    # Capped at a day (MAX_CLASSIFICATION_CLAIM_TTL) so a claim always ends, and a
+    # purge — which keeps rows with a live claim — can't be held off forever.
+    attr_reader :classification_claim_ttl
+
+    # What the boot check does when the app holds copies of the gem's migrations
+    # (*.moderate.rb) but not every one this version ships: :raise (the default; under
+    # a rake task it logs instead, so `bin/rails moderate:install:migrations` can run),
+    # :log, or :off. See Moderate::Engine.check_migration_copies!.
+    MIGRATION_COPIES_CHECKS = %i[raise log off].freeze
+    attr_reader :migration_copies_check
+
+    def migration_copies_check=(mode)
+      mode = mode.to_s.strip.downcase.to_sym
+      unless MIGRATION_COPIES_CHECKS.include?(mode)
+        raise ArgumentError, "migration_copies_check must be one of: #{MIGRATION_COPIES_CHECKS.join(", ")}"
+      end
+
+      @migration_copies_check = mode
+    end
+
+    MAX_CLASSIFICATION_CLAIM_TTL = 24 * 60 * 60 # 1 day, in seconds
+
+    def classification_claim_ttl=(value)
+      seconds = value.respond_to?(:to_f) ? value.to_f : 0.0
+      unless seconds.positive? && seconds <= MAX_CLASSIFICATION_CLAIM_TTL
+        raise ArgumentError,
+          "classification_claim_ttl must be more than 0 and at most a day (#{MAX_CLASSIFICATION_CLAIM_TTL} seconds), " \
+          "got #{value.inspect}: longer than your slowest adapter call, short enough that files a dead worker " \
+          "claimed are taken over"
+      end
+
+      @classification_claim_ttl = value
+    end
+
     # --- DSA notice form ------------------------------------------------------
     # Documented in docs/dsa-notice-form.md. Held here so the engine/controller
     # (written by other components) read them off the same Configuration object.
@@ -72,12 +113,11 @@ module Moderate
     # the controller auto-uses Turnstile instead and this proc is bypassed.
     attr_reader :parent_controller
     attr_accessor :notice_form_enabled, :notice_rate_limit,
-                  :notice_turnstile_site_key, :notice_turnstile_secret_key,
-                  :notice_captcha_verifier, :notice_guard, :notice_human_verification_skip_if,
-                  :appeal_form_enabled, :appeal_rate_limit, :appeal_guard,
-                  :appeal_human_verification_skip_if, :appeal_return_path,
-                  :transparency_report_enabled,
-                  :signed_gid_purposes
+      :notice_turnstile_site_key, :notice_turnstile_secret_key,
+      :notice_captcha_verifier, :notice_guard, :notice_human_verification_skip_if,
+      :appeal_form_enabled, :appeal_rate_limit, :appeal_guard,
+      :appeal_human_verification_skip_if, :appeal_return_path,
+      :transparency_report_enabled
 
     def initialize
       # Identity. "User" is the overwhelmingly common case; the host overrides it
@@ -123,6 +163,9 @@ module Moderate
       # Misc. nil locale ⇒ follow I18n.default_locale at use time.
       @locale = nil
 
+      @classification_claim_ttl = 600 # 10 minutes, in seconds
+      @migration_copies_check = :raise
+
       # Engine controller defaults. The parent controller defaults to a stock base so
       # the engine works even on API-only apps — the same `parent_controller`
       # indirection Devise and api_keys use.
@@ -159,8 +202,42 @@ module Moderate
       # off, the mounted `/transparency` route 404s; the aggregation stays queryable in
       # code so a host can still build/publish its own report.
       @transparency_report_enabled = false
+    end
 
-      @signed_gid_purposes = %i[appeal confirm_notice unsubscribe]
+    # How a "ban" is applied in the host. Unlike the other hooks, leaving it unset is
+    # not a silent no-op when a ban is actually asked for: `ban_user: true` (and
+    # Moderate.apply_ban) raise until one is wired, because "we suspended your
+    # account" must never be sent for a suspension that didn't happen. Assigning nil
+    # puts the default back.
+    def ban_handler=(handler)
+      if handler.nil?
+        @ban_handler = ->(user:, by:, reason:) {}
+        @ban_handler_configured = false
+      else
+        raise ArgumentError, "ban_handler must respond to #call" unless handler.respond_to?(:call)
+
+        @ban_handler = handler
+        @ban_handler_configured = true
+      end
+    end
+
+    def ban_handler_configured?
+      @ban_handler_configured == true
+    end
+
+    # Is this person banned right now, in your app? Optional: `->(user) { user.banned? }`.
+    # A ban decision on someone a decision of this same episode already banned is
+    # normally recorded as covered by that one (one ban per person per episode). That
+    # is only true while the account is still banned: set this, and a person your app
+    # has unbanned since is banned again by your ban_handler, so a "suspended"
+    # statement of reasons is never sent for an account nothing suspended. Unset
+    # (nil), the earlier ban counts, as before.
+    attr_reader :banned
+
+    def banned=(check)
+      raise ArgumentError, "banned must respond to #call (e.g. ->(user) { user.banned? })" unless check.nil? || check.respond_to?(:call)
+
+      @banned = check
     end
 
     def parent_controller=(value)
@@ -230,6 +307,20 @@ module Moderate
       @adapters.key?(normalize_name(name))
     end
 
+    # Is the adapter registered under `name` background-only? Same probe the
+    # :block validator uses (`validate_block_mode_adapter!`): an adapter is
+    # async ONLY if it explicitly answers `synchronous? == false`; adapters
+    # that don't expose the predicate are assumed synchronous — the
+    # conservative default that keeps simple adapters working. The :flag
+    # enforcement path reads this to decide inline-classify vs routing the
+    # work through Moderate::ClassifyJob (see ContentFilterable).
+    def adapter_async?(name)
+      adapter = adapter_for(name)
+      return false if adapter.nil?
+
+      adapter.respond_to?(:synchronous?) && !adapter.synchronous?
+    end
+
     # --- Filters --------------------------------------------------------------
 
     # Declare a per-field filter policy in the initializer — the twin of
@@ -276,9 +367,7 @@ module Moderate
     # the ecosystem-wide convention.
     def normalize_mode(value)
       mode = value.to_s.strip.downcase.to_sym
-      unless FILTER_MODES.include?(mode)
-        raise ArgumentError, "default_filter_mode must be one of: #{FILTER_MODES.join(', ')}"
-      end
+      raise ArgumentError, "default_filter_mode must be one of: #{FILTER_MODES.join(", ")}" unless FILTER_MODES.include?(mode)
 
       mode
     end