moderate 0.1.0 → 1.0.0.beta1

data/lib/moderate/macros.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# The macros lazily mix the gem's concerns into a host model.
+#
+# We DON'T `require_relative` the concern files here, even though this file is
+# itself require_relative'd by the spine (lib/moderate.rb) at gem-load time. The
+# concerns (Moderate::Actor / Reportable / ContentFilterable) live under
+# `lib/moderate/models/concerns/` and are AUTOLOADED by Zeitwerk (the engine
+# `push_dir`s that subtree under the `Moderate` namespace with the `models` and
+# `concerns` dirs collapsed). Requiring them here too would double-manage the same
+# constants and make Zeitwerk raise on its eager-load pass ("already defined").
+#
+# This is safe because the macro methods below only REFERENCE the concern constants
+# inside their bodies (`include Moderate::Actor`), which run when a host model calls
+# `has_reporting_and_blocking`/`has_reportable_content`/`moderates` — long after
+# boot, when the autoloader is fully wired. So Zeitwerk autoloads each concern
+# lazily on first use.
+module Moderate
+  # The class-level DSL the gem adds to every ActiveRecord model.
+  #
+  # The engine does `ActiveSupport.on_load(:active_record) { extend Moderate::Macros }`,
+  # so `has_reporting_and_blocking`, `has_reportable_content`, and `moderates` become
+  # class methods on ActiveRecord::Base — readable plain-English declarations that
+  # sit alongside the rest of a host's stack (`has_credits`, `has_wallets`, `has_api_keys`):
+  #
+  #   class User    < ApplicationRecord; has_reporting_and_blocking; end
+  #   class Listing < ApplicationRecord; has_reportable_content :title, :description; end
+  #   class Message < ApplicationRecord; moderates :body, mode: :flag; end
+  #
+  # Each macro is exact sugar for an `include` + a declaration — the README
+  # documents both forms as equivalent. The macros are deliberately thin: they
+  # lazily include the right concern (only models that opt in pay for it) and then
+  # forward to that concern's declaration method. All behavior lives in the
+  # concerns, never here.
+  module Macros
+    # `has_reporting_and_blocking` — make this model an ACTOR in the Trust & Safety
+    # system: it can report content/users and block/unblock other users
+    # (report!/block!/unblock!/blocks?/blocked_by?/blocked_with?, plus the block &
+    # report associations), and — since the actor is usually itself reportable and is
+    # the be-banned target — it's also made reportable. One macro, both halves.
+    #
+    # Equivalent to `include Moderate::Actor`. Idempotent: re-declaring (or both
+    # macro + explicit include) won't double-include.
+    def has_reporting_and_blocking
+      include Moderate::Actor unless include?(Moderate::Actor)
+    end
+
+    # `has_reportable_content(*fields)` — mark this model as REPORTABLE content,
+    # optionally narrowing to specific fields. Bare `has_reportable_content` (no
+    # fields) means "the whole record is reportable" (the field whitelist stays
+    # 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)
+      include Moderate::Reportable unless include?(Moderate::Reportable)
+      reportable_fields(*fields) if fields.any?
+      self
+    end
+
+    # `moderates(*fields, mode:, with:)` — filter one or more fields before they're
+    # saved. `mode:`/`with:` default to nil so the field inherits the global
+    # `config.default_filter_mode` / `config.filter_adapter` (resolved inside
+    # `config.filter`), letting a bare `moderates :body` Just Work.
+    #
+    # Two things happen, per field:
+    #   1. The field is registered on the model (Moderate::ContentFilterable), so
+    #      the :block validation and :flag after_commit hook run for it.
+    #   2. A Configuration FilterPolicy is recorded keyed by [class_name, field],
+    #      so `Moderate.filter_policy_for` (which the concern consults at
+    #      validate/commit time, walking the ancestor chain) can find the field's
+    #      adapter + mode. This is the exact twin of `config.filter "Class", :field,
+    #      with:, mode:` in the initializer — same storage, same resolution.
+    #
+    # Equivalent to `include Moderate::ContentFilterable` + `moderates_fields(*fields)`
+    # plus the per-field policy registration.
+    def moderates(*fields, mode: nil, with: nil)
+      include Moderate::ContentFilterable unless include?(Moderate::ContentFilterable)
+      moderates_fields(*fields)
+
+      fields.each do |field|
+        # `config.filter` normalizes/validates the adapter+mode and stores the
+        # policy; passing `self` (the class) lets it record the class NAME string.
+        Moderate.config.filter(self, field, with: with, mode: mode)
+      end
+
+      self
+    end
+  end
+end

data/lib/moderate/models/appeal.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Moderate
+  # A DSA Art. 20 internal complaint against a moderation decision.
+  #
+  # The Digital Services Act requires platforms to give affected users an
+  # "effective internal complaint-handling system" that is FREE, ELECTRONIC, open
+  # for AT LEAST SIX MONTHS after the decision, and decided by a HUMAN (not "solely
+  # on the basis of automated means"). This model encodes each of those:
+  #   - free + electronic: it's just a record + a queue (no payment path exists);
+  #   - six-month window: an appeal is refused once the report's appeal window has
+  #     closed (`report_must_still_be_appealable`);
+  #   - human-decided: there is no auto-decide path — uphold!/reject! (in a service)
+  #     require a moderator and a note;
+  #   - against a DECISION: an appeal can only be opened on an already-resolved
+  #     report (`report_must_be_closed`).
+  # Source: https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Art. 20)
+  class Appeal < ApplicationRecord
+    self.table_name = "moderate_appeals"
+
+    # Validated by the `validates :status, inclusion` below — NOT a DB constraint, so
+    # the vocabulary can grow without a host migration. `upheld` overturns the original
+    # decision; `rejected` confirms it.
+    STATUSES = %w[open upheld rejected].freeze
+
+    # Who lodged the complaint. `notifier` = the person who filed the original
+    # notice; `affected_user` = the content owner whose content was actioned; the
+    # rest are operational. Validated by the model (inclusion), not a DB constraint.
+    SOURCES = %w[notifier affected_user admin other].freeze
+
+    belongs_to :report, class_name: "Moderate::Report"
+    # Appellant may be a logged-in user OR an emailed notifier (public DSA notices
+    # come from non-users), so it's optional and we also carry name/email columns.
+    belongs_to :appellant, class_name: Moderate.config.user_class, optional: true
+    belongs_to :resolved_by, class_name: Moderate.config.user_class, optional: true
+
+    before_validation :normalize_strings
+    before_validation :hydrate_appellant_contact, if: :appellant
+    before_validation :capture_snapshot, on: :create
+    # Default the JSON `snapshot` to {} before save. The migration makes it NOT NULL,
+    # but MySQL 8+ forbids a DEFAULT on a JSON column, so without this an appeal whose
+    # `capture_snapshot` produced an empty hash that got dropped (or any direct build)
+    # could write NULL and trip a NotNullViolation. (SQLite/PostgreSQL get the {}
+    # default from the migration; coalescing is harmless there.)
+    before_save :default_json_columns
+
+    scope :open, -> { where(status: "open") }
+    scope :upheld, -> { where(status: "upheld") }
+    scope :rejected, -> { where(status: "rejected") }
+    # `pending` mirrors `open`, named for the queue's vocabulary (an appeal awaiting
+    # a human decision) — `Moderate::Appeal.pending` is the documented admin scope.
+    scope :pending, -> { where(status: "open") }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :source, inclusion: { in: SOURCES }
+    # Reuse the Report's message length cap so a complaint and a notice share one
+    # limit (a model-level length validation; `reason` carries no DB constraint).
+    validates :reason, presence: true, length: { maximum: Report::MESSAGE_MAX_LENGTH }
+    # The complainant must be reachable to receive the appeal decision (Art. 20
+    # requires informing them of the outcome), so an email is mandatory here even
+    # though the original notice's may not have been.
+    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
+
+    def open?
+      status == "open"
+    end
+
+    def closed?
+      status.in?(%w[upheld rejected])
+    end
+
+    def upheld?
+      status == "upheld"
+    end
+
+    def rejected?
+      status == "rejected"
+    end
+
+    # Decide this appeal — model-level sugar over Moderate::Services::ResolveAppeal,
+    # so a host can write `appeal.uphold!(by: moderator, note: "…")` /
+    # `appeal.reject!(by: moderator, note: "…")` instead of constructing the service.
+    # The service does the real work (audit, the appeal-decision notification, and —
+    # for an upheld appeal — reversing the original decision); these only forward.
+    def uphold!(by:, note:)
+      Moderate::Services::ResolveAppeal.new(self, by: by).uphold!(note: note)
+    end
+
+    def reject!(by:, note:)
+      Moderate::Services::ResolveAppeal.new(self, by: by).reject!(note: note)
+    end
+
+    private
+
+    # See the before_save comment: keep the NOT-NULL JSON `snapshot` non-null on MySQL.
+    def default_json_columns
+      self.snapshot ||= {}
+    end
+
+    def normalize_strings
+      self.status = status.to_s.squish.presence || "open"
+      self.source = source.to_s.squish.presence || "notifier"
+      self.appellant_name = appellant_name.to_s.squish.presence
+      self.appellant_email = appellant_email.to_s.squish.presence&.downcase
+      self.reason = reason.to_s.gsub(/\r\n?/, "\n").strip.presence
+      self.resolution_note = resolution_note.to_s.strip.presence
+    end
+
+    # Carry the logged-in appellant's contact onto the appeal so the decision can be
+    # delivered the same way whether the appellant is a user or an emailed notifier.
+    # Read via `try` so the host's user class only needs whichever attribute it has.
+    def hydrate_appellant_contact
+      self.appellant_email ||= appellant.try(:email)
+      self.appellant_name ||= appellant.try(:display_name)
+    end
+
+    # Snapshot the DECISION being appealed at the moment the appeal is filed, so the
+    # complaint is anchored to exactly what was decided even if the report is later
+    # re-resolved. Mirrors the Report's evidence-snapshot philosophy.
+    def capture_snapshot
+      self.snapshot = {
+        report_id: report_id,
+        report_status: report&.status,
+        report_resolution_basis: report&.resolution_basis,
+        report_resolution_actions: report&.resolution_actions,
+        report_resolved_at: report&.resolved_at&.iso8601,
+        captured_at: Time.current.iso8601
+      }.compact
+    end
+
+    # You can only appeal a DECISION — an appeal presupposes the report was resolved.
+    # We key off `resolved_at` (set when a moderator acts) rather than `status` so a
+    # report reopened for any reason can't be appealed in limbo.
+    def report_must_be_closed
+      return if report&.resolved_at.present?
+
+      errors.add(:report, I18n.t("moderate.errors.appeal_report_must_be_closed", default: "decision can only be appealed after it is made"))
+    end
+
+    # 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.
+    def report_must_still_be_appealable
+      return if report.blank? || report.appeal_deadline_at.blank?
+      return if Time.current <= report.appeal_deadline_at
+
+      errors.add(:report, I18n.t("moderate.errors.appeal_window_expired", default: "the appeal window for this decision has closed"))
+    end
+  end
+end

data/lib/moderate/models/application_record.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The abstract base class every model the gem ships inherits from
+  # (Moderate::Report / Block / Flag / Appeal). It plays the exact role an engine's
+  # `app/models/<engine>/application_record.rb` normally plays:
+  #
+  #   - It is `abstract_class`, so it never maps to a table of its own; it only
+  #     exists to give the gem's records a single, gem-owned ancestor.
+  #
+  #   - It inherits from the HOST's `::ActiveRecord::Base`, NOT from the host's
+  #     `::ApplicationRecord`. That matters: the gem must not pick up host
+  #     concerns/defaults bolted onto the app's ApplicationRecord (multitenancy
+  #     scopes, default associations, etc.) — its tables are infrastructure, owned
+  #     by the gem, and should behave identically in every host. (This is why the
+  #     dummy's own `ApplicationRecord` doc note says the gem's models inherit from
+  #     `Moderate::ApplicationRecord`, not from the host base.)
+  #
+  # WHY this class has to exist as a separate file (and isn't just `ActiveRecord::Base`
+  # inline in each model): the gem's models are written as `class Report <
+  # ApplicationRecord` *inside* `module Moderate`. Ruby constant lookup resolves the
+  # bare `ApplicationRecord` to `Moderate::ApplicationRecord` first (the lexically
+  # enclosing namespace), and Zeitwerk autoloads it from this file. Defining it here
+  # — rather than letting the lookup fall through to the host's top-level
+  # `::ApplicationRecord` — keeps the gem's base independent of the host's, which is
+  # the whole point. The reference to `::ActiveRecord::Base` is fully qualified so it
+  # can never be re-bound to a `Moderate::ActiveRecord` by the same lookup quirk.
+  class ApplicationRecord < ::ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/moderate/models/block.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The bidirectional safety edge between two users — the table behind every
+  # "block" feature and behind `Moderate.blocked_ids_for`.
+  #
+  # A block is DIRECTED in the data (`blocker` → `blocked`) but BIDIRECTIONAL in
+  # effect: once either side blocks, neither should see or reach the other. That
+  # asymmetry-in-storage / symmetry-in-meaning is the whole subtlety of blocking,
+  # and it lives in exactly one place — the `related_user_ids` SSOT query below —
+  # so search, messaging, profiles, and feeds never hand-roll their own block SQL
+  # (and never get the direction half-right, which is the classic blocking bug).
+  #
+  # Apple Guideline 1.2(c) and Google Play's UGC policy both require an in-app way
+  # to block abusive users; this model is the mechanism.
+  # 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
+    self.table_name = "moderate_blocks"
+
+    # Both ends resolve to the host's configured user class (read lazily as a String
+    # from config, same pattern as every other actor association in the gem). NOT
+    # optional: a block edge with a missing end is meaningless.
+    belongs_to :blocker, class_name: Moderate.config.user_class
+    belongs_to :blocked, class_name: Moderate.config.user_class
+
+    # A user can block another user at most once. The DB also enforces this with a
+    # unique index (`index_moderate_blocks_on_blocker_id_and_blocked_id`); the model
+    # validation gives a friendly error instead of a raw RecordNotUnique, and the
+    # `block!` entrypoint uses find_or_initialize to stay idempotent regardless.
+    validates :blocked_id, uniqueness: { scope: :blocker_id }
+    validate :cannot_block_self
+
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    # 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) {
+      return none if user_a.blank? || user_b.blank?
+
+      where(blocker_id: user_a.id, blocked_id: user_b.id)
+        .or(where(blocker_id: user_b.id, blocked_id: user_a.id))
+    }
+
+    # Idempotent block. Creating the same edge twice is a no-op that returns the
+    # existing record, so callers never have to check first. Everything runs in one
+    # transaction so the audit entry and the on_block side effect commit atomically
+    # with the row; the notify fires AFTER the transaction so a slow/failing mailer
+    # can't roll back the block itself.
+    #
+    # On a real (new) block we:
+    #   1. fire the host's `on_block` side-effect hook (e.g. tear down a pending
+    #      invite, leave a shared room) — host-defined, no-op by default;
+    #   2. audit "block created" with both ids;
+    #   3. notify `:user_blocked`.
+    # Re-blocking an existing edge skips all three (nothing actually changed).
+    def self.block!(blocker:, blocked:)
+      raise ArgumentError, "blocker is required" if blocker.blank?
+      raise ArgumentError, "blocked is required" if blocked.blank?
+
+      # Self-block is a NO-OP, not an exception. Blocking yourself is meaningless, and
+      # a UI that wires a generic "block this user" affordance shouldn't have to guard
+      # the degenerate "block myself" case — so we return an UNPERSISTED, invalid
+      # record (carrying the `cannot_block_self` validation error for inspection)
+      # rather than raising. No row is written, no on_block/audit/notify fires. (The
+      # DB CHECK constraint `moderate_blocks_no_self_block` is the belt-and-suspenders
+      # backstop if a caller bypasses this path.)
+      if blocker.id.present? && blocker.id == blocked.id
+        block = new(blocker: blocker, blocked: blocked)
+        block.valid? # populate errors[:blocked] with the self-block message
+        return block
+      end
+
+      block = nil
+      created = false
+
+      transaction do
+        block = find_or_initialize_by(blocker: blocker, blocked: blocked)
+        created = block.new_record?
+        block.save! if created
+
+        if created
+          # Side-effect hook FIRST, inside the transaction: if the host's on_block
+          # raises, the whole block rolls back rather than leaving a half-applied
+          # state (edge saved but invite not torn down).
+          on_block_payload = audit_payload_from_on_block(
+            Moderate.run_on_block(blocker: blocker, blocked: blocked, at: block.created_at)
+          )
+
+          Moderate.audit(
+            name: :user_blocked,
+            subject: block,
+            actor: blocker,
+            payload: on_block_payload.merge(
+              blocker_id: blocker.id,
+              blocked_id: blocked.id,
+              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}" }
+        )
+      end
+
+      block
+    end
+
+    # Remove a block. Returns false if there was nothing to remove (already
+    # unblocked), true otherwise — so it's safe to call unconditionally.
+    def self.unblock!(blocker:, blocked:)
+      block = find_by(blocker: blocker, blocked: blocked)
+      return false if block.blank?
+
+      transaction do
+        block.destroy!
+        Moderate.audit(
+          name: :user_unblocked,
+          subject: block,
+          actor: blocker,
+          payload: {
+            blocker_id: blocker.id,
+            blocked_id: blocked.id,
+            summary: "user #{blocker.id} unblocked user #{blocked.id}"
+          }
+        )
+      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
+
+    # THE source of truth for "everyone this user is on a block edge with" — both
+    # the people they blocked AND the people who blocked them (bidirectional). This
+    # is what `Moderate.blocked_ids_for` delegates to, and what hosts use to hide
+    # blocked pairs from each other everywhere:
+    #
+    #   Post.where.not(user_id: Moderate.blocked_ids_for(current_user))  # via the facade
+    #
+    # Returns an AR relation of user ids (NOT a loaded array) so callers can compose
+    # it into a `where.not(user_id: ...)` subquery that runs entirely in the database
+    # — no N user ids round-tripped into Ruby just to be sent back as a giant IN list.
+    #
+    # The UNION is the cleanest portable way to express "blocked_id where I'm the
+    # blocker, OR blocker_id where I'm the blocked" as a single id set; we build it
+    # against the model's OWN `quoted_table_name` (not a hard-coded "moderate_blocks")
+    # so a host that renames/prefixes the table still gets correct SQL.
+    def self.related_user_ids(user)
+      user_model = Moderate.user_class
+      return user_model.none.select(:id) if user.blank?
+
+      user_table = user_model.quoted_table_name
+      user_primary_key = connection.quote_column_name(user_model.primary_key)
+      block_table = quoted_table_name
+
+      user_model
+        .where(
+          "#{user_table}.#{user_primary_key} IN (
+            SELECT blocked_id FROM #{block_table} WHERE blocker_id = :user_id
+            UNION
+            SELECT blocker_id FROM #{block_table} WHERE blocked_id = :user_id
+          )",
+          user_id: user.id
+        )
+        .select(:id)
+    end
+
+    private
+
+    def self.audit_payload_from_on_block(result)
+      return {} if result.nil?
+      return result if result.is_a?(Hash)
+      return result.to_h if result.respond_to?(:to_h)
+
+      {}
+    rescue ArgumentError, TypeError
+      {}
+    end
+    private_class_method :audit_payload_from_on_block
+
+    # 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
+      return if blocker_id.blank? || blocked_id.blank? || blocker_id != blocked_id
+
+      errors.add(:blocked, I18n.t("moderate.errors.cannot_block_self", default: "You can't block yourself"))
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The "person who acts" in the Trust & Safety system: the model that reports
+  # other content, blocks other actors, gets reported, gets banned. Backs the
+  # `has_reporting_and_blocking` macro (and its documented equivalent,
+  # `include Moderate::Actor`).
+  #
+  # This is the one model the gem treats as the actor/identity, configured via
+  # `config.user_class`. There's normally exactly one such model per app ("User",
+  # "Account", "Member"), and it is BOTH an actor and itself reportable — Apple
+  # 1.2 and Google Play UGC both require reporting and blocking *users*, not just
+  # content (docs/compliance.md). So including Actor also includes
+  # Moderate::Reportable, giving a user the reportable contract with sensible
+  # actor-flavored defaults (a user IS its own `reported_owner`).
+  #
+  # Everything host-specific (what "banned" means, whether a block tears down a
+  # pending invite) is delegated to the configured hooks via the Moderate facade,
+  # never hard-coded here — keeping the actor host-agnostic.
+  module Actor
+    extend ActiveSupport::Concern
+
+    # A user is also reportable. Pulling Reportable in here means `has_reporting_and_blocking`
+    # alone gives you both halves (act AND be-acted-on) without a second macro.
+    include Moderate::Reportable
+
+    included do
+      # Blocks this actor initiated, and blocks filed against this actor. Two
+      # associations on the one Moderate::Block table, distinguished by which
+      # foreign key points here. `dependent: :destroy` cleans up the edges if the
+      # account is hard-deleted (a soft-delete/ban leaves them, which is correct —
+      # the safety edge should outlive a suspension).
+      has_many :moderate_initiated_blocks,
+        class_name: "Moderate::Block",
+        foreign_key: :blocker_id,
+        inverse_of: :blocker,
+        dependent: :destroy
+      has_many :moderate_received_blocks,
+        class_name: "Moderate::Block",
+        foreign_key: :blocked_id,
+        inverse_of: :blocked,
+        dependent: :destroy
+
+      # Reports this actor filed, and reports filed against this actor. `nullify`
+      # (not destroy): a report is legal/evidentiary and must survive either party
+      # deleting their account — we just detach the foreign key. `moderate_reports`
+      # is the README-documented reader for "reports against me / my content."
+      has_many :moderate_submitted_reports,
+        class_name: "Moderate::Report",
+        foreign_key: :reporter_id,
+        inverse_of: :reporter,
+        dependent: :nullify
+      has_many :moderate_reports,
+        class_name: "Moderate::Report",
+        foreign_key: :reported_user_id,
+        inverse_of: :reported_user,
+        dependent: :nullify
+    end
+
+    # --- Reporting ------------------------------------------------------------
+
+    # File a report from this actor against a piece of content (or another actor —
+    # a user with `has_reporting_and_blocking` is itself reportable).
+    #
+    #   current_user.report!(@message, category: :harassment, details: "...")
+    #   current_user.report!(@other_user, category: :impersonation)
+    #
+    # We build and persist a Moderate::Report; the Report model owns the rest of
+    # the lifecycle the README promises — snapshotting the offending content so
+    # evidence survives edits/deletes, inferring the responsible owner, sending the
+    # reporter a receipt, and dropping it into the queue. Keeping that logic IN the
+    # 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
+    # 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)
+      attributes[:message] = details if details && !attributes.key?(:message)
+      reported_field = attributes.delete(:reported_field)
+      field = attributes.delete(:field)
+      reported_field ||= field
+
+      # An in-app reporter attests to good faith IMPLICITLY by choosing to report —
+      # there's no separate checkbox in the in-app flow (that's the public DSA notice
+      # form's job). The Report model requires `good_faith_confirmed` to be truthy
+      # (Art. 16(2)(d)), so we set it here for the community path unless the caller
+      # already passed it. (A host that wants an explicit in-app attestation can still
+      # override by passing `good_faith_confirmed:` in `attributes`.)
+      attributes[:good_faith_confirmed] = true unless attributes.key?(:good_faith_confirmed)
+
+      report = Moderate::Report.new(
+        reporter: self,
+        reportable: reportable,
+        category: category.to_s,
+        intake_kind: "community",
+        **attributes
+      )
+
+      intake = Moderate::Services::IntakeReport.new(
+        report: report,
+        reporter: self,
+        reportable: reportable,
+        reported_field: reported_field
+      )
+      return report if intake.save
+
+      raise ActiveRecord::RecordInvalid, report
+    end
+
+    # --- Blocking -------------------------------------------------------------
+    #
+    # Blocking is a BIDIRECTIONAL safety edge: once either side blocks, neither
+    # should see or reach the other. The single source of truth for "who can't see
+    # whom" is `Moderate.blocked_ids_for`, which reads BOTH directions — so these
+    # predicates expose each direction, and `blocked_with?` is the one you check in
+    # features.
+
+    # Block `other` (idempotent, audited, fires the `on_block` hook). The actual
+    # create/audit/notify is owned by Moderate::Block.block! so there's one block
+    # write path for the whole gem.
+    def block!(other)
+      Moderate::Block.block!(blocker: self, blocked: other)
+    end
+
+    # Lift a block this actor placed on `other`. No-op (returns false) if no such
+    # block exists.
+    def unblock!(other)
+      Moderate::Block.unblock!(blocker: self, blocked: other)
+    end
+
+    # Did I block them? (one direction)
+    def blocks?(other)
+      return false if other.blank?
+
+      moderate_initiated_blocks.exists?(blocked_id: other.id)
+    end
+
+    # Did they block me? (the other direction)
+    def blocked_by?(other)
+      return false if other.blank?
+
+      moderate_received_blocks.exists?(blocker_id: other.id)
+    end
+
+    # Is there a block edge in EITHER direction? This is the predicate to check in
+    # product code ("can these two interact?") — blocking is symmetric for
+    # visibility/reachability even though only one side pressed the button. A
+    # self-check is never "blocked."
+    def blocked_with?(other)
+      return false if other.blank? || other.id == id
+
+      blocks?(other) || blocked_by?(other)
+    end
+
+    # --- Reportable defaults for an actor -------------------------------------
+    #
+    # A user is reportable; these override Moderate::Reportable's defaults with
+    # actor-appropriate behavior. Hosts can override again for richer copy/rules.
+
+    # A user is responsible for themselves — so a report against a user (e.g. for
+    # impersonation) attributes to and notifies that same user.
+    def reported_owner
+      self
+    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.
+    def report_visible_to?(viewer, field:)
+      viewer.present? && viewer.id != id && reportable_field_allowed?(field)
+    end
+  end
+end