moderate 1.0.0.beta2 → 1.0.0

data/lib/moderate/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rails/engine"
+require_relative "text_validator" # `validates :field, moderate: true` (0.x)
 
 module Moderate
   # The Rails engine that wires `moderate` into a host app.
@@ -48,11 +49,9 @@ module Moderate
     #      `event`, `configuration`, `engine`, `macros`) is `require_relative`'d from
     #      `lib/moderate.rb` so the value objects work in a plain-Ruby context with
     #      no Rails — those files MUST NOT also be managed by Zeitwerk (a constant
-    #      can't be both manually required and autoloaded). The 0.x compatibility
-    #      shims (`text`, `text_validator`, `word_list`) are ignored too: they either
-    #      define non-conventional constants (`text_validator.rb` reopens
-    #      `ActiveModel::Validations`, not a `Moderate::*` constant) or are legacy and
-    #      loaded only on demand.
+    #      can't be both manually required and autoloaded). The 0.x validator
+    #      (`text_validator`) is ignored too: it reopens `ActiveModel::Validations`,
+    #      not a `Moderate::*` constant, and this file requires it.
     #
     # We do this on the host's MAIN autoloader (`Rails.autoloaders.main`) inside an
     # initializer scheduled BEFORE `:set_autoload_paths`, the same point Rails wires
@@ -61,13 +60,13 @@ module Moderate
     LIB_ROOT = File.expand_path("..", __dir__) # => .../lib
     MODERATE_LIB = File.expand_path("moderate", LIB_ROOT) # => .../lib/moderate
 
-    # Spine + 0.x-compat files Zeitwerk must NOT manage (they're require_relative'd
-    # from the spine or define non-conventional constants).
+    # Spine files and the 0.x validator: Zeitwerk must NOT manage them (they're
+    # require_relative'd, and the validator defines a non-Moderate constant).
     ZEITWERK_IGNORED = %w[
       version.rb errors.rb label.rb result.rb event.rb
-      configuration.rb engine.rb macros.rb
-      text.rb text_validator.rb word_list.rb
+      configuration.rb engine.rb macros.rb text_validator.rb
     ].freeze
+    private_constant :LIB_ROOT, :MODERATE_LIB, :ZEITWERK_IGNORED
 
     initializer "moderate.autoload", before: :set_autoload_paths do
       loader = Rails.autoloaders.main
@@ -98,19 +97,78 @@ module Moderate
     # autoloadable; adding it to eager_load_paths makes the boot-time pass cover it.
     config.eager_load_paths << MODERATE_LIB
 
-    # Make the host's migrations:install task pick up the gem's migration template
-    # location, and ensure the gem's own migration directory is on the path. The
-    # primary install path is still `rails generate moderate:install` (which copies
-    # the adaptive migration into the host's db/migrate); appending the path here is
-    # belt-and-suspenders so engine-style `moderate:install:migrations` also works.
+    # The gem's own migrations (db/migrate, e.g. beta4's pending_key) and how an app
+    # gets them. The tables come from `rails generate moderate:install`, which writes
+    # the adaptive create migration and then COPIES the gem's migrations after it
+    # (*.moderate.rb), so a fresh app runs both, in order. An app installed before it
+    # copied them (beta3) holds no copies: this appends the gem's db/migrate to its
+    # migration paths, so it runs only what it lacks.
+    #
+    # Not appended when the same migrations would then be found twice (Active Record
+    # raises DuplicateMigrationNameError):
+    #   - under the gem's own Rakefile (ENGINE_ROOT is this engine), where Rails' engine
+    #     tasks already add the engine's db/migrate;
+    #   - when the app holds copies (*.moderate.rb, from moderate:install or
+    #     `bin/rails moderate:install:migrations`): the copies run instead, and a later
+    #     release's migrations arrive with `bin/rails moderate:install:migrations`.
     initializer "moderate.migrations" do |app|
-      unless app.root.to_s == root.to_s
-        config.paths["db/migrate"].expanded.each do |path|
-          app.config.paths["db/migrate"] << path
-        end
+      next if app.root.to_s == root.to_s
+      next if defined?(ENGINE_ROOT) && ENGINE_ROOT.to_s == root.to_s
+
+      Engine.migration_paths_for(app.config.paths["db/migrate"].expanded).each do |path|
+        app.config.paths["db/migrate"] << path
       end
     end
 
+    # The gem's migration directories an app with `host_dirs` as its own should add.
+    def self.migration_paths_for(host_dirs)
+      return [] if host_dirs.any? { |dir| Dir.glob(File.join(dir, "*.moderate.rb")).any? }
+
+      config.paths["db/migrate"].expanded - host_dirs
+    end
+
+    # An app that holds copies of the gem's migrations runs only those (see above), so
+    # a copy missed after an upgrade would never run, silently. At boot, compare the
+    # copies with the gem's migrations by name; when one is missing, raise (or log,
+    # per `config.migration_copies_check`), naming it and the command that copies it.
+    config.after_initialize do |app|
+      next if app.root.to_s == Engine.root.to_s
+
+      Engine.check_migration_copies!(app.config.paths["db/migrate"].expanded)
+    end
+
+    # The gem's migrations (by name) an app holding copies has no copy of; [] for an
+    # app without copies, which gets the gem's own path instead.
+    def self.missing_migration_copies(host_dirs)
+      copies = host_dirs.flat_map { |dir| Dir.glob(File.join(dir, "*.moderate.rb")) }
+      return [] if copies.empty?
+
+      copied = copies.map { |file| File.basename(file, ".moderate.rb").split("_", 2).last }
+      gem_migrations = Dir[root.join("db/migrate/[0-9]*_*.rb").to_s].map { |file| File.basename(file, ".rb").split("_", 2).last }
+      gem_migrations - copied
+    end
+
+    def self.check_migration_copies!(host_dirs, mode: Moderate.config.migration_copies_check)
+      return if mode == :off
+
+      missing = missing_migration_copies(host_dirs)
+      return if missing.empty?
+
+      message = "moderate: your app holds copies of moderate's migrations (*.moderate.rb) but none of " \
+                "#{missing.join(", ")}, which this version of moderate needs. Run `bin/rails " \
+                "moderate:install:migrations`, then `bin/rails db:migrate`."
+      # Under a rake task (the very command that copies them, or db:migrate) log
+      # instead: raising there would make the fix impossible to run.
+      raise Moderate::ConfigurationError, message if mode == :raise && !running_rake_task?
+
+      Rails.logger&.error(message)
+      warn(message)
+    end
+
+    def self.running_rake_task?
+      defined?(::Rake.application) && ::Rake.application.top_level_tasks.any?
+    end
+
     # Register the model macros on ActiveRecord, the canonical Rails way.
     #
     # `ActiveSupport.on_load(:active_record)` defers until ActiveRecord::Base is
@@ -127,12 +185,15 @@ module Moderate
       end
     end
 
-    # Surface the gem's I18n files (filter validation messages, the DSA taxonomy
-    # labels, the notice-form copy) to the host's I18n load path. The locale files
-    # ship under the engine's conventional config/locales (provided by other
-    # components); listing the glob here is harmless if none exist yet.
-    initializer "moderate.locales" do |app|
-      app.config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.{rb,yml}").to_s]
-    end
+    # The gem's I18n files (config/locales/*.yml — default copy and the generic
+    # reportable-field labels) need NO initializer: every Rails::Engine registers
+    # its `config/locales/**/*.{rb,yml}` in `config.i18n.railties_load_path`, which
+    # Rails puts AHEAD of the host app's own locale files — so a host translation
+    # of any `moderate.*` key overrides ours, as it must.
+    #
+    # Do NOT also append them to `app.config.i18n.load_path` (an earlier version
+    # did, while the directory was still empty): that list is loaded AFTER the
+    # host's files, so the gem's defaults would silently clobber the host's
+    # translations. test/integration/locale_precedence_test.rb pins this.
   end
 end

data/lib/moderate/event.rb

@@ -72,4 +72,25 @@ module Moderate
       payload.to_h.transform_keys(&:to_sym)
     end
   end
+
+  # The event vocabulary, frozen for 1.0. Defined by reopening the class (a
+  # constant inside the `Data.define` block would land on the enclosing scope).
+  # test/public_api_test.rb checks that every name the gem emits is listed here and
+  # that the README lists exactly these.
+  class Event
+    # What `config.notify` receives: moments a person (or an admin channel) is told about.
+    NOTIFY_NAMES = %i[
+      report_received notice_received report_decision affected_user_decision
+      appeal_received appeal_decision user_blocked user_unblocked user_banned
+      content_flagged content_removed
+    ].freeze
+
+    # What `config.audit` receives: the record of every intake, decision, block,
+    # ban and removal, plus the gem's own housekeeping.
+    AUDIT_NAMES = %i[
+      report_received appeal_received report_decision flag_decision appeal_decision
+      flag_filed user_blocked user_unblocked user_banned content_removed
+      notify_failed classification_skipped retention_purged legal_hold_placed legal_hold_released
+    ].freeze
+  end
 end

data/lib/moderate/filters/base.rb

@@ -47,6 +47,7 @@ module Moderate
   # async via its own `synchronous? == false`, which the spine honors regardless of
   # whether the adapter inherits from `Base`.
   module Filters
+    # The optional base class for adapters (see the comment above).
     class Base
       class << self
         # The class-level entry point the registry resolution path calls. Spins up

data/lib/moderate/filters/wordlist.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "yaml"
-require "set"
 
 module Moderate
   module Filters
@@ -77,6 +76,10 @@ module Moderate
       # at runtime, so compile them ONCE per process and memoize on the class.
       # (config.additional_words / excluded_words are layered in per-call, since the
       # host can in principle reconfigure between calls — and they're cheap.)
+      #
+      # @api private (as are reset!, compile_bundled_patterns, compile_pair,
+      # compact_source and the normalization constants): the public surface of an
+      # adapter is `classify` and `synchronous?`.
       def self.patterns
         @patterns ||= compile_bundled_patterns
       end
@@ -139,7 +142,7 @@ module Moderate
           .sub(/\\b\z/, "")          # drop trailing word boundary
           .gsub(/\\s[*+]?/, "")      # drop \s, \s*, \s+ whitespace matchers
           .gsub(/\[ ([^\]]*)\]/, '[\1]') # drop a literal space inside a char class
-          .delete(" ")               # drop any remaining literal spaces
+          .delete(" ") # drop any remaining literal spaces
       end
 
       def classify(value)

data/lib/moderate/jobs/classify_job.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Moderate
-  # The background worker for ASYNCHRONOUS filter adapters (the :openai adapter, a
-  # host's hosted classifier, the default :image adapter) running in :flag mode.
+  # The background worker for ASYNCHRONOUS filter adapters (a remote moderation API
+  # such as the OpenAI or Rekognition reference adapters in examples/, or a host's
+  # own classifier) running in :flag mode.
   #
   # ── Why a job exists at all ──────────────────────────────────────────────────
   # An async adapter does blocking I/O (a moderation API call), which must never run
@@ -23,11 +24,27 @@ module Moderate
   # value. If the record was edited or deleted between enqueue and run, we classify
   # what's actually there now (or skip a vanished record), never a stale snapshot.
   #
-  # ── Idempotency ──────────────────────────────────────────────────────────────
+  # ── One flag per run ─────────────────────────────────────────────────────────
   # Flag creation goes through `Moderate::Flag.flag!`, the single builder shared by
-  # the synchronous and asynchronous paths. It's an upsert-by-(flaggable, field,
-  # source) so a retried job (ActiveJob retries on transient failures) doesn't pile
-  # up duplicate queue entries for the same content.
+  # the synchronous and asynchronous paths, and it is the job's last step, so a job
+  # that fails earlier (the adapter's network call) and is retried files one flag.
+  # `flag!` always creates: two runs for the same content (two saves, or a host that
+  # also enqueues the job itself) file two flags, both in the queue.
+  #
+  # ── An attachment whose file isn't on the service yet ────────────────────────
+  # For an attachment the filter enqueues this job before Active Storage uploads
+  # the file (the guard: it runs even if the upload fails) and, once the upload
+  # returns, classifies right away (see Moderate::ContentFilterable). When the job
+  # runs, a blob can be missing: the upload failed or is still running, a direct
+  # upload hasn't finished, a replica lags. The job then re-enqueues itself,
+  # waiting UPLOAD_WAIT × attempt seconds, up to UPLOAD_ATTEMPTS runs in all, and
+  # gives up with a `classification_skipped` audit event. It never hands an adapter
+  # a file that isn't there.
+  #
+  # `blob_ids:` names the files the job was enqueued for: if the field holds other
+  # files by the time it runs, the newer change has its own job and this one stops.
+  # A field already classified for exactly these files (Moderate::Attachments marks
+  # the blobs) is not classified again.
   #
   # ── Base class ───────────────────────────────────────────────────────────────
   # We subclass `ActiveJob::Base` directly (not the host's ApplicationJob) so the gem
@@ -35,16 +52,27 @@ module Moderate
   # rest of the gem stays host-agnostic. The host configures the queue adapter,
   # retries, and queue name globally as usual.
   class ClassifyJob < ActiveJob::Base
-    # Run on a low-priority queue by default — moderation flagging is important but
-    # not latency-critical (the content is already published in :flag mode). A host
-    # can override the queue globally.
-    queue_as { Moderate.config.respond_to?(:job_queue) && Moderate.config.job_queue || :default }
+    # The :default queue. Moderation flagging is important but not latency-critical
+    # (the content is already published in :flag mode); a host that wants it elsewhere
+    # says so in an initializer: `Moderate::ClassifyJob.queue_as :low`.
+    queue_as :default
+
+    # Seconds to wait before the next look at a blob that isn't uploaded yet,
+    # multiplied by the attempt number (5s, 10s, 15s, 20s: under a minute in all).
+    UPLOAD_WAIT = 5
+    # Runs of this job, the first included, before it gives up on such a blob.
+    UPLOAD_ATTEMPTS = 5
 
     # @param record [ActiveRecord::Base] the flaggable record (any Moderate::Reportable).
     # @param field  [String, Symbol] the field whose value to classify.
     # @param adapter [String, Symbol, nil] optional explicit adapter name; when nil,
     #   the field's resolved FilterPolicy (or the global default) decides.
-    def perform(record, field, adapter: nil)
+    # @param upload_attempt [Integer] which look at a not-yet-uploaded attachment
+    #   this is (the job sets it when it re-enqueues itself; callers leave it).
+    # @param blob_ids [Array<Integer>, nil] the attachment's blobs when enqueued.
+    # @param claim_recheck [Boolean] this run is the one look the job takes after
+    #   another worker's claim on the same files expires (set by the job itself).
+    def perform(record, field, adapter: nil, upload_attempt: 1, blob_ids: nil, claim_recheck: false)
       # The record may have been destroyed between enqueue and execution — nothing
       # to classify, nothing to flag. (ActiveJob raises DeserializationError for a
       # GlobalID that no longer resolves; that's rescued at the framework level, but
@@ -60,11 +88,13 @@ module Moderate
 
       value = field_value(record, field)
       return if blank?(value)
+      if Moderate::Attachments.attachment?(value)
+        return classify_attachment(record, field, policy, adapter: adapter, attempt: upload_attempt, blob_ids: blob_ids,
+          claim_recheck: claim_recheck)
+      end
 
       result = Moderate.classify(value, policy: policy)
-      return unless result.flagged?
-
-      file_flag(record, field, policy, result, value)
+      file_flag(record, field, policy, result, value) if result.flagged?
     end
 
     private
@@ -86,7 +116,7 @@ module Moderate
       )
     end
 
-    # File (or upsert) the Moderate::Flag via the shared builder. We pass exactly the
+    # File the Moderate::Flag via the shared builder. We pass exactly the
     # columns the install migration defines for moderate_flags. `Flag.flag!` owns the
     # `content_flagged` notify event so there's a single emission site across the
     # sync and async paths — the job doesn't fire it itself, to avoid double-notifying.
@@ -115,7 +145,7 @@ module Moderate
     # otherwise (the owner column is nullable — a flag with no resolvable owner is
     # still a valid queue item).
     def content_owner(record)
-      record.respond_to?(:reported_owner) ? record.reported_owner : nil
+      Moderate.responsible_user(record)
     end
 
     # Diagnostic context persisted on the flag (the `context` jsonb column): the raw
@@ -138,6 +168,56 @@ module Moderate
       value.to_s[0, 500]
     end
 
+    # Claim, classify outside any lock, complete (Moderate::Attachments): this job
+    # and the inline path or the guard never classify the same files at once, and a
+    # slow adapter never holds the content's row. When another worker holds a live
+    # claim, the job looks once more when that claim expires, so a worker that died
+    # mid-call doesn't leave the files unclassified.
+    def classify_attachment(record, field, policy, adapter:, attempt:, blob_ids:, claim_recheck:)
+      value = field_value(record, field)
+      return if blob_ids && Moderate::Attachments.blob_ids(value) != Array(blob_ids).sort
+      return wait_for_upload(record, field, adapter, attempt, blob_ids) unless Moderate::Attachments.uploaded?(value)
+
+      outcome = Moderate::Attachments.classify_once(
+        record, field,
+        owner: job_id,
+        read: -> { fresh_value(record, field) },
+        classify: ->(current) { Moderate.classify(current, policy: policy) },
+        file: ->(current, result) { file_flag(record, field, policy, result, current) }
+      )
+      return unless outcome == :claimed && !claim_recheck
+
+      expires_at = Moderate::Attachments.claim_expires_at(record, field, value) || Time.current
+      self.class.set(wait_until: expires_at + 1)
+        .perform_later(record, field, adapter: adapter, blob_ids: blob_ids, claim_recheck: true)
+    end
+
+    # The field as committed now, read through a fresh instance (the job's own copy
+    # caches the attachment it was enqueued with).
+    def fresh_value(record, field)
+      fresh = record.class.unscoped.find_by(id: record.id)
+      fresh && field_value(fresh, field)
+    end
+
+    def wait_for_upload(record, field, adapter, attempt, blob_ids)
+      if attempt < UPLOAD_ATTEMPTS
+        self.class.set(wait: UPLOAD_WAIT * attempt)
+          .perform_later(record, field, adapter: adapter, upload_attempt: attempt + 1, blob_ids: blob_ids)
+        return
+      end
+
+      Moderate.audit(
+        :classification_skipped,
+        subject: record,
+        payload: {
+          field: field,
+          reason: "attachment_not_uploaded",
+          attempts: attempt,
+          summary: "#{record.class.name}##{field} not classified: its file never reached the storage service"
+        }
+      )
+    end
+
     def field_value(record, field)
       record.public_send(field)
     rescue NoMethodError

data/lib/moderate/label.rb

@@ -16,7 +16,7 @@ module Moderate
   # reasons, and the Art. 24 transparency counters all aggregate over a single set.
   # See: https://developers.openai.com/api/docs/guides/moderation
   #
-  # Implemented with Ruby's `Data.define` (Ruby 3.2+, which the gemspec requires):
+  # Implemented with Ruby's `Data.define` (Ruby 3.2+; the gemspec requires 3.3+):
   # an immutable, frozen-by-construction value object — exactly what a label
   # should be (you never mutate a verdict after the fact).
   Label = Data.define(:category, :subcategory, :score, :flagged, :input) do
@@ -36,7 +36,7 @@ module Moderate
       super(
         category: normalize_symbol(category),
         subcategory: subcategory.nil? ? nil : normalize_symbol(subcategory),
-        score: score.nil? ? nil : score.to_f,
+        score: score&.to_f,
         flagged: flagged ? true : false,
         input: normalize_symbol(input || :unknown)
       )

data/lib/moderate/macros.rb

@@ -51,10 +51,15 @@ module Moderate
     # empty, and a blank reported_field is then allowed — see
     # Reportable#reportable_field_allowed?).
     #
-    # Equivalent to `include Moderate::Reportable` + `reportable_fields(*fields)`.
-    def has_reportable_content(*fields)
+    # `labels:` gives each field the human name moderators and affected users see
+    # ("Chat message" instead of "Body"); see Reportable.reportable_fields.
+    #
+    #   has_reportable_content :body, :files, labels: { body: "Chat message", files: "Chat photo" }
+    #
+    # Equivalent to `include Moderate::Reportable` + `reportable_fields(*fields, labels:)`.
+    def has_reportable_content(*fields, labels: nil)
       include Moderate::Reportable unless include?(Moderate::Reportable)
-      reportable_fields(*fields) if fields.any?
+      reportable_fields(*fields, labels: labels) if fields.any? || labels
       self
     end
 

data/lib/moderate/models/appeal.rb

@@ -16,6 +16,8 @@ module Moderate
   #     report (`report_must_be_closed`).
   # Source: https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Art. 20)
   class Appeal < ApplicationRecord
+    include Moderate::DeferredNotices
+
     self.table_name = "moderate_appeals"
 
     # Validated by the `validates :status, inclusion` below — NOT a DB constraint, so
@@ -63,12 +65,18 @@ module Moderate
     validates :appellant_email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
     validates :resolution_note, presence: true, if: :closed?
     validate :report_must_be_closed
-    validate :report_must_still_be_appealable
+    # Only when the complaint is FILED: Art. 20 bounds when one may be lodged, not
+    # when it must be decided, so a complaint filed in time is decided (and saved)
+    # whenever the review ends, even after the window has closed.
+    validate :report_must_still_be_appealable, on: :create
 
     def open?
       status == "open"
     end
 
+    # Awaiting a decision — the twin of the `pending` scope (see Report#pending?).
+    alias pending? open?
+
     def closed?
       status.in?(%w[upheld rejected])
     end
@@ -144,6 +152,7 @@ module Moderate
     # Enforce the DSA Art. 20 six-month window: refuse appeals filed after the
     # report's `appeal_deadline_at` (stamped to decision-time + APPEAL_WINDOW). If no
     # deadline was stamped yet, we don't block — the window simply hasn't been opened.
+    # Checked on create only (see the declaration above).
     def report_must_still_be_appealable
       return if report.blank? || report.appeal_deadline_at.blank?
       return if Time.current <= report.appeal_deadline_at

data/lib/moderate/models/block.rb

@@ -16,6 +16,8 @@ module Moderate
   # Apple:  https://developer.apple.com/app-store/review/guidelines/#user-generated-content
   # Google: https://support.google.com/googleplay/android-developer/answer/9876937
   class Block < ApplicationRecord
+    include Moderate::DeferredNotices
+
     self.table_name = "moderate_blocks"
 
     # Both ends resolve to the host's configured user class (read lazily as a String
@@ -35,7 +37,7 @@ module Moderate
 
     # Find the edge between two users in EITHER direction (used to answer
     # "blocked_with?" — is there a block between us, regardless of who blocked whom).
-    scope :between, ->(user_a, user_b) {
+    scope :between, lambda { |user_a, user_b|
       return none if user_a.blank? || user_b.blank?
 
       where(blocker_id: user_a.id, blocked_id: user_b.id)
@@ -75,6 +77,7 @@ module Moderate
       created = false
 
       transaction do
+        connection = Moderate::DeferredNotices.connection_for(self) # before any save
         block = find_or_initialize_by(blocker: blocker, blocked: blocked)
         created = block.new_record?
         block.save! if created
@@ -97,18 +100,12 @@ module Moderate
               summary: "user #{blocker.id} blocked user #{blocked.id}"
             )
           )
-        end
-      end
 
-      # Notify outside the transaction (see class doc): notify must never be able to
-      # roll back the action it's announcing.
-      if created
-        Moderate.notify(
-          :user_blocked,
-          subject: block,
-          actor: blocker,
-          payload: { blocker_id: blocker.id, blocked_id: blocked.id, summary: "user #{blocker.id} blocked user #{blocked.id}" }
-        )
+          # Announced once the block is durable (Moderate::DeferredNotices): after the
+          # outermost commit, never if a surrounding transaction rolls back, and
+          # outside any transaction, so notify can't roll back what it announces.
+          block.after_commit_notice(on: connection) { block.send(:announce, :user_blocked, blocker, blocked) }
+        end
       end
 
       block
@@ -121,7 +118,9 @@ module Moderate
       return false if block.blank?
 
       transaction do
+        connection = Moderate::DeferredNotices.connection_for(self) # before the destroy
         block.destroy!
+        block.after_commit_notice(on: connection) { block.send(:announce, :user_unblocked, blocker, blocked) }
         Moderate.audit(
           name: :user_unblocked,
           subject: block,
@@ -134,13 +133,6 @@ module Moderate
         )
       end
 
-      Moderate.notify(
-        :user_unblocked,
-        subject: block,
-        actor: blocker,
-        payload: { blocker_id: blocker.id, blocked_id: blocked.id, summary: "user #{blocker.id} unblocked user #{blocked.id}" }
-      )
-
       true
     end
 
@@ -192,6 +184,18 @@ module Moderate
     end
     private_class_method :audit_payload_from_on_block
 
+    def announce(name, blocker, blocked)
+      verb = name == :user_blocked ? "blocked" : "unblocked"
+      Moderate.notify(
+        name,
+        subject: self,
+        actor: blocker,
+        payload: {
+          blocker_id: blocker.id, blocked_id: blocked.id, summary: "user #{blocker.id} #{verb} user #{blocked.id}"
+        }
+      )
+    end
+
     # The DB has a CHECK constraint (`moderate_blocks_no_self_block`) too; this gives
     # the friendly validation error before the row ever reaches the database.
     def cannot_block_self

data/lib/moderate/models/classification.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Moderate
+  # One record's field, for one exact set of attached files (`digest`, of the ordered
+  # blob ids): who is classifying it right now (`claimed_by`, `claimed_at`) and when
+  # it was classified (`classified_at`, with the adapter and whether it flagged).
+  # The claim protocol that writes it lives in Moderate::Attachments; rows hold ids,
+  # a digest and timestamps, no content, and Moderate.purge deletes old ones.
+  #
+  # @api private
+  class Classification < ApplicationRecord
+    self.table_name = "moderate_classifications"
+
+    belongs_to :record, polymorphic: true, optional: true
+
+    scope :for_set, lambda { |record, field, digest|
+      where(record_type: record.class.polymorphic_name, record_id: record.id, field: field.to_s, digest: digest)
+    }
+
+    def classified?
+      classified_at.present?
+    end
+  end
+end

data/lib/moderate/models/concerns/actor.rb

@@ -72,10 +72,19 @@ module Moderate
     # model (not here) means the public DSA notice intake and this in-app path share
     # one source of truth.
     #
-    # `details:` is the README's name for the reporter's free-text reason; it maps
+    # `details:` is optional (blank, the report's message is the category's label);
+    # it's the README's name for the reporter's free-text reason, and it maps
     # onto the Report's `message`. Extra keyword args (e.g. `field:`) pass straight
     # through, so this stays forward-compatible with the Report model's attributes.
-    def report!(reportable, category:, details: nil, **attributes)
+    #
+    # `block: true` also blocks the person responsible for the content once the
+    # report is filed — the "Report and block" checkbox. (Nothing is blocked if the
+    # content has no person behind it, or if it's your own.)
+    #
+    # The report is refused (RecordInvalid, an error on :reportable) when this actor
+    # may not report it — the reportable's own `report_visible_to?`, the same rule
+    # that hides the report link.
+    def report!(reportable, category:, details: nil, block: false, **attributes)
       attributes[:message] = details if details && !attributes.key?(:message)
       reported_field = attributes.delete(:reported_field)
       field = attributes.delete(:field)
@@ -96,6 +105,7 @@ module Moderate
         intake_kind: "community",
         **attributes
       )
+      report.block_reported_user = block
 
       intake = Moderate::Services::IntakeReport.new(
         report: report,
@@ -164,6 +174,11 @@ module Moderate
       self
     end
 
+    # A report about a person is about their profile.
+    def moderation_content_type(_field = nil)
+      "user_profile"
+    end
+
     # You can never report yourself, and a field still has to be reportable. This
     # tightens Reportable's default with the self-report guard, so the
     # `moderate_report_link` helper hides the control on your own profile.