moderate 0.1.0 → 1.0.0.beta2

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

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Pre-publication content filtering for a model's fields. Backs the `moderates`
+  # macro (and its documented equivalent, `include Moderate::ContentFilterable` +
+  # `moderates_fields :body`).
+  #
+  # For each declared field the concern resolves the field's FilterPolicy (via
+  # `Moderate.filter_policy_for`, which walks the ancestor chain so an STI parent's
+  # policy covers its children) and enforces it in one of two ways, by mode:
+  #
+  #   :off   — nothing.
+  #   :block — a VALIDATION. If the classifier flags the value, the save is
+  #            rejected with `errors.add(field, :objectionable_content)`. Runs
+  #            synchronously, so it only works with a synchronous adapter — the
+  #            Configuration validates that invariant (README: ":block requires a
+  #            synchronous adapter").
+  #   :flag  — an AFTER_COMMIT side effect. The save SUCCEEDS, then (only if the
+  #            field actually changed) the value is classified and a
+  #            `Moderate::Flag` is filed when it trips. HOW it's classified
+  #            depends on the adapter: a synchronous adapter (the wordlist)
+  #            classifies inline right here; an ASYNC adapter (`synchronous? ==
+  #            false` — any remote moderation API) is routed through
+  #            `Moderate::ClassifyJob`, because blocking network I/O must never
+  #            run inside the request that saved the content. The job re-reads
+  #            the current value and files the Flag itself.
+  #
+  # WHY :flag lives in after_commit and not in a validator (this is the whole
+  # reason `:flag` is a `moderates` mode you can't hand-roll with `validates`):
+  # validators must be side-effect-free, and a Flag created inside a transaction
+  # that later rolls back would silently vanish — you'd think you flagged something
+  # you didn't. `after_commit` guarantees the surrounding transaction committed
+  # before we write the Flag (and that a ClassifyJob never races a rollback). See
+  # docs/configuration.md ("`:flag` never lives in a validator").
+  #
+  # ACTIVE STORAGE ATTACHMENTS work out of the box: `moderates :avatar, with:
+  # :your_image_adapter, mode: :flag` on a `has_one_attached :avatar` model needs
+  # no extra wiring. AR dirty tracking can't see attachment writes — and Active
+  # Storage clears `attachment_changes` before after_commit — so the concern
+  # snapshots "these filtered attachments changed" in a before_save and consumes
+  # the snapshot at commit time. The overridable seam below still exists for
+  # richer cases (derived values, non-AS blobs).
+  module ContentFilterable
+    extend ActiveSupport::Concern
+
+    included do
+      # The set of filtered field names (Strings), inherited via class_attribute so
+      # STI subclasses keep their parent's filtered fields. Accumulates across
+      # multiple `moderates`/`moderates_fields` declarations on the same class.
+      class_attribute :moderation_filtered_fields, instance_writer: false, default: [].freeze
+
+      validate :moderate_blocked_fields_must_be_allowed
+      # Snapshot attachment writes BEFORE Active Storage's own save callbacks
+      # clear `attachment_changes` — by after_commit they're gone (see
+      # activestorage's Attached::Model). One-shot; consumed + cleared below.
+      before_save :moderate_snapshot_attachment_changes
+      after_commit :moderate_flag_filtered_fields
+    end
+
+    class_methods do
+      # Register one or more fields for filtering. Additive and de-duplicated, so
+      # `moderates :a; moderates :b` and `moderates_fields :a, :b` are equivalent.
+      # The PER-FIELD adapter/mode (the `with:`/`mode:` of the `moderates` macro)
+      # is recorded separately as a Configuration FilterPolicy by the macro; this
+      # method only tracks WHICH fields to run on commit/validate.
+      def moderates_fields(*fields)
+        self.moderation_filtered_fields =
+          (moderation_filtered_fields + fields.map(&:to_s)).uniq.freeze
+      end
+    end
+
+    private
+
+    # :block enforcement — a validation. We deliberately skip :flag fields here
+    # (their work happens after_commit) and blank values (nothing to classify).
+    def moderate_blocked_fields_must_be_allowed
+      moderation_filtered_fields.each do |field|
+        policy = Moderate.filter_policy_for(self, field)
+        next unless policy.block?
+
+        value = moderation_field_value(field)
+        next if moderation_value_blank?(value)
+
+        result = Moderate.classify(value, policy: policy)
+        errors.add(field, :objectionable_content) if result.flagged?
+      end
+    end
+
+    # :flag enforcement — an after_commit side effect that files a Moderate::Flag
+    # (inline for synchronous adapters; via Moderate::ClassifyJob for async ones).
+    #
+    # We only act when the field actually CHANGED on this commit (re-saving an
+    # untouched record must not re-flag it and spam the queue), and we wrap each
+    # field in `begin/ensure` so the clean-up hook (`moderation_field_committed`)
+    # always runs even if classification raises — that hook is what clears the
+    # one-shot attachment snapshot.
+    def moderate_flag_filtered_fields
+      moderation_filtered_fields.each do |field|
+        policy = Moderate.filter_policy_for(self, field)
+        next unless policy.flag?
+        next unless moderation_field_changed_for_commit?(field)
+
+        begin
+          # ASYNC adapters (remote moderation APIs) never classify inline —
+          # a network call in the request's after_commit would stall the
+          # response for as long as the provider takes. ClassifyJob re-reads
+          # the value at run time (so it always classifies what's actually
+          # persisted) and files the Flag through the same Flag.flag! builder.
+          if Moderate.config.adapter_async?(policy.adapter)
+            Moderate::ClassifyJob.perform_later(self, field)
+            next
+          end
+
+          value = moderation_field_value(field)
+          next if moderation_value_blank?(value)
+
+          result = Moderate.classify(value, policy: policy)
+          next unless result.flagged?
+
+          Moderate::Flag.flag!(
+            flaggable: self,
+            field: field,
+            # `reported_owner` comes from Moderate::Reportable. A filterable model
+            # is usually also reportable; if it isn't, the owner is simply nil
+            # (the flag still lands in the queue, just unattributed).
+            owner: (reported_owner if respond_to?(:reported_owner)),
+            source: result.source,
+            mode: policy.mode,
+            # Cap the stored excerpt so we never balloon a row with a huge body;
+            # 500 chars is plenty of context for a reviewer.
+            excerpt: value.to_s.truncate(500),
+            categories: result.categories,
+            scores: result.scores,
+            # Keep the policy that produced the flag alongside the adapter's raw
+            # payload, so the queue can show "flagged by <adapter> under
+            # <Class>#<field>" and an auditor can inspect the untouched response.
+            context: {
+              raw: result.raw,
+              policy: { class_name: policy.class_name, field: policy.field, mode: policy.mode.to_s }
+            }
+          )
+        ensure
+          moderation_field_committed(field)
+        end
+      end
+    end
+
+    # --- Overridable field seam -----------------------------------------------
+    #
+    # These three methods are the seam that lets one concern filter BOTH plain text
+    # columns AND non-column content, without hosts having to re-plumb the common
+    # cases. Defaults handle text attributes AND Active Storage attachments; a
+    # host overrides them for anything richer (derived values, external blobs).
+
+    # The value to classify for `field`. Default: the attribute reader — which for
+    # a `has_one_attached` field returns the `ActiveStorage::Attached` proxy, the
+    # natural input for an image adapter (it can read `.record`, `.blob`,
+    # `.variant(...)`, or download bytes as it sees fit).
+    def moderation_field_value(field)
+      public_send(field)
+    end
+
+    # Did `field` change on the just-committed save? Defaults, in order:
+    #   1. the attachment snapshot taken in before_save (AR dirty tracking can't
+    #      see attachment writes, and Active Storage clears `attachment_changes`
+    #      before after_commit — hence the one-shot snapshot),
+    #   2. ActiveRecord's own dirty tracking (`saved_change_to_attribute?`),
+    #   3. `true` for a PORO/ActiveModel object with no dirty tracking at all —
+    #      the conservative assumption.
+    # Override for non-attribute content the defaults can't see.
+    def moderation_field_changed_for_commit?(field)
+      return true if @moderate_changed_attachment_fields&.include?(field.to_s)
+
+      if respond_to?(:saved_change_to_attribute?)
+        saved_change_to_attribute?(field)
+      elsif respond_to?(:"saved_change_to_#{field}?")
+        public_send(:"saved_change_to_#{field}?")
+      else
+        true
+      end
+    end
+
+    # Per-field clean-up after the commit-time flag attempt (success OR failure).
+    # Consumes the one-shot attachment snapshot; override-and-super if you track
+    # extra per-field state of your own.
+    def moderation_field_committed(field)
+      @moderate_changed_attachment_fields&.delete(field.to_s)
+      nil
+    end
+
+    # before_save: record which FILTERED fields have a pending attachment write
+    # on this save. `attachment_changes` only exists on Active Storage models —
+    # plain models skip straight through.
+    def moderate_snapshot_attachment_changes
+      return true unless respond_to?(:attachment_changes)
+
+      moderation_filtered_fields.each do |field|
+        next unless attachment_changes.key?(field)
+
+        (@moderate_changed_attachment_fields ||= Set.new) << field
+      end
+      true # never halt the save chain
+    end
+
+    # Blank check that can see through an `ActiveStorage::Attached` proxy — an
+    # attachment with nothing attached must read as "nothing to classify"
+    # (Object#blank? can't tell: the proxy is truthy and has no #empty?).
+    def moderation_value_blank?(value)
+      return !value.attached? if value.respond_to?(:attached?)
+
+      value.blank?
+    end
+  end
+end

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

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The contract a model opts into to become *reportable* — i.e. a piece of
+  # user-generated content (a comment, a listing, a profile) that another user (or
+  # a public DSA notice) can file a report against.
+  #
+  # Plain Rails polymorphism answers "what row was reported?" via the
+  # `Moderate::Report#reportable` association. This concern answers the
+  # Trust & Safety questions that polymorphism *can't*:
+  #
+  #   - which fields of the record may be reported (`reportable_fields`)
+  #   - who is *responsible* for the content (`reported_owner`) — the person a
+  #     decision's statement of reasons must reach (DSA Art. 17) and who a ban
+  #     would apply to
+  #   - what the moderation queue should *call* this item (`moderation_label`)
+  #   - what immutable evidence to snapshot at report time so it survives an edit
+  #     or delete (`moderation_snapshot`)
+  #   - what a moderator may *remove* without nuking the whole record
+  #     (`remove_reported_field!`)
+  #   - whether a given viewer is even allowed to report it (`report_visible_to?`)
+  #
+  # WHY a concern and not just config: these answers are intrinsic to each model
+  # (only the Listing knows its title is reportable but its internal SKU isn't),
+  # so they belong ON the model. Hosts override the handful of methods that need
+  # domain knowledge; everything else has a safe default.
+  #
+  # Regulatory grounding for why a reportable contract has to exist at all:
+  #   - Apple App Store Review Guideline 1.2 requires a way to report UGC and a
+  #     mechanism to remove offending content:
+  #     https://developer.apple.com/app-store/review/guidelines/#user-generated-content
+  #   - Google Play UGC policy requires in-app reporting and ongoing moderation:
+  #     https://support.google.com/googleplay/android-developer/answer/9876937
+  #   - EU DSA Art. 16 (notice & action) presupposes that reported items can be
+  #     identified, snapshotted, and acted on:
+  #     https://eur-lex.europa.eu/eli/reg/2022/2065/oj
+  #
+  # The documented include form is `include Moderate::Reportable` +
+  # `reportable_fields :a, :b`; the `has_reportable_content :a, :b` macro is exact sugar.
+  module Reportable
+    extend ActiveSupport::Concern
+
+    included do
+      # Reports filed against THIS record. Kept on the public `reports` reader
+      # because the README promises `listing.reports`, and because a reportable
+      # model should read naturally in host code. Reports are legal/evidentiary,
+      # so hard-deleting the content detaches rather than destroys them.
+      has_many :reports,
+        as: :reportable,
+        class_name: "Moderate::Report",
+        dependent: :nullify
+
+      # The whitelist of reportable field names, stored as frozen Strings. A
+      # `class_attribute` (not a plain constant) so it inherits down an STI tree
+      # AND can be overridden per subclass without mutating the parent's list.
+      # Empty default = "the whole record is reportable, no specific field."
+      class_attribute :moderation_reportable_fields, instance_writer: false, default: [].freeze
+
+      # Self-register in the gem's reportable registry the moment the concern is
+      # included, so `Moderate.reportable_classes` is auto-discovered with NO
+      # manual list to maintain (README: "Reportable classes are auto-discovered
+      # from the `has_reportable_content` macro — no manual registry."). We register the class
+      # NAME (the registry stores strings and constantizes lazily) so we never pin
+      # the class across a Zeitwerk reload in development.
+      Moderate.register_reportable(self)
+    end
+
+    class_methods do
+      # Declare (or read) the reportable fields. Idempotent and additive-free:
+      # the last declaration wins for THIS class (it doesn't merge with the
+      # inherited value), matching how a host expects `reportable_fields :title`
+      # to mean exactly `["title"]`. Called with no args, it's a reader.
+      #
+      #   reportable_fields :title, :description   # writer
+      #   reportable_fields                         # => ["title", "description"]
+      def reportable_fields(*fields)
+        self.moderation_reportable_fields = fields.map(&:to_s).freeze if fields.any?
+        moderation_reportable_fields
+      end
+    end
+
+    # Is `field` one a reporter is allowed to name? Two cases:
+    #
+    #   - A BLANK field is ALWAYS allowed — it means "report the whole record," which
+    #     is valid whether or not the model declared specific reportable fields. (A
+    #     user tapping "Report this comment" doesn't name a field; only the public DSA
+    #     notice / a field-targeted in-app flow does.) So a Comment that declares
+    #     `has_reportable_content :body` can still be reported as a whole with a nil field.
+    #
+    #   - A NAMED field must be in the whitelist. With no fields declared, the
+    #     whitelist is empty, so any named field is rejected (there's nothing to
+    #     target field-by-field on a bare-`has_reportable_content` record).
+    #
+    # This is the authorization gate the Report model and the report controller both
+    # consult before accepting a `reported_field`.
+    def reportable_field_allowed?(field)
+      field_s = field.to_s
+      return true if field_s.empty?
+
+      self.class.reportable_fields.include?(field_s)
+    end
+
+    # WHO is responsible for this content — the account a decision's statement of
+    # reasons reaches (DSA Art. 17) and the user a ban would apply to.
+    #
+    # NO default: a model that can be reported MUST tell the gem who's behind it,
+    # because guessing wrong here means notifying or banning the wrong person.
+    # We raise a NotImplementedError naming the class so the omission is loud at
+    # the first report, not silent. (A `User` model with `has_reporting_and_blocking` is itself
+    # reportable and returns `self` — see Moderate::Actor.)
+    def reported_owner
+      raise NotImplementedError,
+        "#{self.class.name} is reportable but doesn't define #reported_owner. " \
+        "Return the user responsible for this content (the one a decision notifies " \
+        "and a ban applies to), e.g. `def reported_owner = user`."
+    end
+
+    # The human-readable name the moderation queue shows for this item. Defaults
+    # to Rails' own `to_s` (usually "#<Comment id: 42>"); override for something an
+    # admin can act on at a glance, e.g. `def moderation_label = "Comment #{id}"`.
+    def moderation_label
+      to_s
+    end
+
+    # The immutable evidence text to capture for `field` at report time, so the
+    # report survives the content being edited or deleted. The Report model calls
+    # this in its `before_validation :capture_snapshot` (DSA-grade evidence
+    # preservation). Defaults to nil; override to return the actual field text
+    # (e.g. `public_send(field)`) or a description of a non-text attachment.
+    #
+    # NAMED `moderation_snapshot` per the gem's public reportable contract; takes
+    # the field so a multi-field record can snapshot the specific thing reported.
+    def moderation_snapshot(_field)
+      nil
+    end
+
+    # Remove the reported `field` as an enforcement action — WITHOUT destroying the
+    # whole record (a moderator removing one objectionable photo shouldn't delete
+    # the whole listing). Returns truthy if something was actually removed (so the
+    # decision service knows whether to fire the `content_removed` event).
+    #
+    # Defaults to a no-op returning false: a model that hasn't opted into
+    # field-level removal simply reports "nothing removed," and the moderator falls
+    # back to other actions. Override to purge an attachment, blank a column, etc.
+    def remove_reported_field!(_field)
+      false
+    end
+
+    # Companion query to `remove_reported_field!`: CAN this specific `field` be
+    # removed on this record? An admin UI uses it to decide whether to OFFER a
+    # "remove content" action at all. Without it, a host that only removes SOME
+    # fields (e.g. an avatar but not a display name) would render a remove button
+    # that always fails when the moderator clicks it on a non-removable field.
+    #
+    # Defaults to false (mirrors the no-op `remove_reported_field!`). Override it
+    # alongside `remove_reported_field!` and have the latter reuse it, so the
+    # "can I?" answer and the "do it" action never drift apart.
+    def removable_reported_field?(_field)
+      false
+    end
+
+    # Visibility/authorization gate for the report affordance: should `viewer` be
+    # offered a "report this" control for `field`? The default enforces two rules:
+    #
+    #   1. the field must be reportable (`reportable_field_allowed?`), and
+    #   2. you can't report YOUR OWN content — the affordance is hidden from the
+    #      content's owner, so an author never sees "Report" on their own post. We
+    #      compare the viewer to this content's `reported_owner` (the Reportable
+    #      contract's "who is responsible" answer).
+    #
+    # The `moderate_report_link` helper renders nothing when this is false, and the
+    # report controller redirects. Hosts can override for richer rules. (A User with
+    # `has_reporting_and_blocking` overrides this in Moderate::Actor to compare ids directly,
+    # since a user IS its own owner.)
+    def report_visible_to?(viewer, field:)
+      return false unless reportable_field_allowed?(field)
+      return false if viewer.present? && moderation_owner_is?(viewer)
+
+      true
+    end
+
+    # Open reports filed against this record, optionally narrowed to one field.
+    # Hosts can use this when they need the actual relation (queue previews,
+    # counters, "already reported" affordances) instead of just a boolean.
+    def open_reports(field = nil)
+      moderation_scope_by_field(reports.open, :reported_field, field)
+    end
+
+    # Has this record received any open reports? This is the public predicate
+    # documented beside `reports` in the README.
+    def reported?(field = nil)
+      open_reports(field).exists?
+    end
+
+    # All auto-filter/manual flags against this record, optionally narrowed to a
+    # field. We keep this as a method instead of a `has_many :flags` association:
+    # `flags` is a common host-model word, while `flagged?` is the public DX.
+    def moderation_flags(field = nil)
+      moderation_scope_by_field(
+        Moderate::Flag.where(flaggable: self),
+        :field,
+        field
+      )
+    end
+
+    # Pending flags are the "allowed through, awaiting review" state a host may
+    # want to surface near user-generated content.
+    def pending_moderation_flags(field = nil)
+      moderation_flags(field).pending
+    end
+
+    # Has this record been flagged and not yet resolved/dismissed? Optionally
+    # pass a field (`listing.flagged?(:description)`) for field-level UI.
+    def flagged?(field = nil)
+      pending_moderation_flags(field).exists?
+    end
+
+    # --- Route descriptor hooks -----------------------------------------------
+    #
+    # The gem is UI-agnostic and doesn't know the host's routes, so a reportable
+    # tells the gem how to build the few URLs/paths that decision notices and the
+    # public DSA notice form need. Each receives the host's route proxy (whatever
+    # responds to the app's `*_url`/`*_path` helpers — typically the controller or
+    # `Rails.application.routes.url_helpers`) and returns a string or nil.
+    #
+    # All default to nil — the gem treats a missing route as "no link available"
+    # and degrades gracefully (e.g. the statement of reasons just omits the link,
+    # the post-report redirect falls back to the app root). Hosts override only the
+    # ones their flows actually surface.
+
+    # The public, canonical URL of this content — what a DSA Art. 16 notice records
+    # as the precise location of the allegedly illegal content, and what a
+    # statement of reasons points the affected user to.
+    def moderation_subject_url(_routes)
+      nil
+    end
+
+    # Where to send a user *back to* after they file a report on this content
+    # (e.g. the content's own page). Falls back to the app root when nil.
+    def moderation_return_path(_routes)
+      nil
+    end
+
+    # The admin/back-office path for this content, so the moderation queue can deep
+    # link a reviewer straight to the item under review.
+    def moderation_admin_path(_routes)
+      nil
+    end
+
+    private
+
+    # Is `viewer` the user responsible for this content? Used by the default
+    # `report_visible_to?` to hide the report affordance from the content's own owner.
+    #
+    # We resolve ownership via the Reportable contract's `reported_owner`, but guard
+    # it carefully: `reported_owner` deliberately RAISES NotImplementedError on a
+    # reportable that hasn't defined it (so the omission is loud at report time). A
+    # visibility check, by contrast, must never blow up a view — so we rescue that
+    # case and treat "unknown owner" as "not the viewer" (show the link; the write
+    # path will still surface the missing-owner error if they actually report). We
+    # compare by primary key when both sides are AR records, else by object equality.
+    def moderation_owner_is?(viewer)
+      owner = reported_owner
+      return false if owner.nil?
+
+      if owner.respond_to?(:id) && viewer.respond_to?(:id)
+        owner.id == viewer.id && owner.class == viewer.class
+      else
+        owner == viewer
+      end
+    rescue NotImplementedError
+      false
+    end
+
+    def moderation_scope_by_field(scope, column, field)
+      field_s = field.to_s.squish
+      return scope if field_s.blank?
+
+      scope.where(column => field_s)
+    end
+  end
+end

data/lib/moderate/models/flag.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Moderate
+  # A system/auto-filter flag: the record an adapter (or a manual action) leaves
+  # behind when content is flagged for review rather than rejected outright.
+  #
+  # Flags are what `:flag`-mode filtering produces AFTER COMMIT — the write
+  # succeeds, then a Flag lands in the queue. This is intentional and load-bearing:
+  # a flag must NEVER be created inside a validator/transaction, because a validator
+  # is supposed to be side-effect-free and a Flag written inside a transaction that
+  # later rolls back would silently vanish (you'd "moderate" content that was never
+  # saved). The Filterable concern enforces the after_commit timing; this model is
+  # just the record + the queue + the "content flagged" notification.
+  #
+  # The same `pending` scope serves BOTH a human admin queue and an automated
+  # consumer (e.g. a job that auto-actions high-confidence flags), so the gem
+  # doesn't presume a human is the only reviewer.
+  class Flag < ApplicationRecord
+    self.table_name = "moderate_flags"
+
+    STATUSES = %w[pending actioned dismissed].freeze
+
+    # Built-in/generic source names. Host-registered adapter names are also valid
+    # sources (see `.sources` below) because `Moderate.classify` stamps the adapter
+    # name onto the Result when the adapter does not set one explicitly. This is why
+    # a host can register `:openai` or `:image` and see that exact name in the queue.
+    SOURCES = %w[text_filter image_filter external_classifier manual].freeze
+
+    # What the flag WOULD do. `:flag` allowed the write and queued it; `:block`
+    # rejected the write (a block-mode trip can also be recorded as a flag for the
+    # audit trail). Validated by the model (inclusion), not a DB constraint.
+    MODES = %w[flag block].freeze
+
+    # The flagged content is polymorphic — any `Moderate::Reportable`. `owner` is the
+    # responsible user (inferred from the flaggable's `reported_owner`), kept here so
+    # the queue can group flags by user without re-resolving ownership; optional
+    # because not all content has a single owning account. `reviewed_by` is the
+    # moderator who closed it. All user associations resolve to the host's configured
+    # user class, read lazily from config as a String.
+    belongs_to :flaggable, polymorphic: true
+    belongs_to :owner, class_name: Moderate.config.user_class, optional: true
+    belongs_to :reviewed_by, class_name: Moderate.config.user_class, optional: true
+
+    # Default the JSON columns to their empty shape before save: `categories` is a
+    # list ([]), `scores`/`context` are hashes ({}). The migration makes all three
+    # NOT NULL, but MySQL 8+ forbids a JSON DEFAULT, so a Flag built directly (rather
+    # than via `flag!`, which already coerces them) could write NULL and trip a
+    # NotNullViolation on MySQL. (SQLite/PostgreSQL get the defaults from the
+    # migration; coalescing is harmless there.)
+    before_save :default_json_columns
+
+    # Announce a new flag through the host's notify hook so admins get pinged (e.g.
+    # a Telegram alert) the moment content is flagged. after_create_COMMIT, not
+    # after_create: the flag must be durably saved before we tell anyone about it,
+    # and the notify must not be able to roll the flag back.
+    after_create_commit :notify_content_flagged
+
+    scope :pending, -> { where(status: "pending") }
+    scope :actioned, -> { where(status: "actioned") }
+    scope :dismissed, -> { where(status: "dismissed") }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    validates :field, presence: true
+    validates :status, inclusion: { in: STATUSES }
+    validates :source, inclusion: { in: ->(_flag) { sources } }, on: :create
+    validates :mode, inclusion: { in: MODES }
+    validates :resolution_note, presence: true, if: :closed?
+
+    # The single entry point the Filterable concern uses to file a flag. Centralizes
+    # coercion (categories → Array, scores/context → Hash) so callers can hand us
+    # whatever shape a Moderate::Result exposed without each one re-normalizing.
+    # `context` is freeform JSON for audit (which policy fired, the raw classifier
+    # payload, etc.) — never relied on by the gem's own logic.
+    def self.flag!(flaggable:, field:, owner:, source:, mode:, excerpt:, categories:, scores:, context:)
+      create!(
+        flaggable: flaggable,
+        field: field,
+        owner: owner,
+        source: source,
+        mode: mode,
+        excerpt: excerpt,
+        categories: Array(categories),
+        scores: scores.to_h,
+        context: context.to_h
+      )
+    end
+
+    def self.sources
+      (SOURCES + Moderate.config.adapters.keys.map(&:to_s)).uniq
+    end
+
+    def pending?
+      status == "pending"
+    end
+
+    def closed?
+      status.in?(%w[actioned dismissed])
+    end
+
+    # Close this flag as ACTIONED — someone (or an automated policy) took
+    # action on the flagged content. Model-level sugar mirroring
+    # Report#resolve!/#dismiss! so hosts stop hand-writing status updates.
+    # `by:` is the reviewing user when a human decided; leave it nil for
+    # automated closes — recording a human who never looked would poison the
+    # audit trail (DSA statements of reasons read these rows).
+    def action!(note:, by: nil)
+      close!(new_status: "actioned", note: note, by: by)
+    end
+
+    # Close this flag with NO action taken. The canonical automated use is
+    # SUPERSEDED content: when the flagged field changes (text edited, photo
+    # replaced/reverted), a still-pending flag is about content that is no
+    # longer live — leaving it pending keeps `flagged?` true and mislabels
+    # the NEW content in any host UI keyed on it. Hosts should dismiss with a
+    # note saying what superseded it.
+    def dismiss!(note:, by: nil)
+      close!(new_status: "dismissed", note: note, by: by)
+    end
+
+    # A label for the flagged thing in the queue. Asks the flaggable for its own
+    # `moderation_label` (Moderate::Reportable interface); falls back to a generic
+    # "Type id" string for content that doesn't implement it.
+    def flaggable_label
+      return flaggable.moderation_label if flaggable.respond_to?(:moderation_label)
+
+      "#{flaggable_type} #{flaggable_id}"
+    end
+
+    private
+
+    # Shared close path for action!/dismiss!. update! (not update_columns) on
+    # purpose: the `resolution_note presence if closed?` validation is the
+    # guard that every closed flag explains itself — sugar that skipped it
+    # would defeat the reason the sugar exists.
+    def close!(new_status:, note:, by:)
+      update!(
+        status: new_status,
+        resolution_note: note,
+        reviewed_by: by,
+        reviewed_at: Time.current
+      )
+    end
+
+    # See the before_save comment: keep the NOT-NULL JSON columns non-null on MySQL.
+    def default_json_columns
+      self.categories ||= []
+      self.scores ||= {}
+      self.context ||= {}
+    end
+
+    def notify_content_flagged
+      # `content_flagged` has NO user recipient by design — it's an admin/system
+      # signal, not a message to the content owner — so the Event's recipients stay
+      # empty and the host's notify hook routes it to admin channels only.
+      Moderate.notify(
+        :content_flagged,
+        subject: self,
+        payload: {
+          flaggable_type: flaggable_type,
+          flaggable_id: flaggable_id,
+          field: field,
+          source: source,
+          categories: Array(categories),
+          summary: "content flagged (#{source}) on #{flaggable_label}##{field}"
+        }
+      )
+    end
+  end
+end