moderate 0.1.0 → 1.0.0.beta1

data/lib/moderate/result.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "label"
+
+module Moderate
+  # The single return type of every filter adapter: `adapter.classify(value) → Moderate::Result`.
+  #
+  # This is the gem's content-filtering value object — immutable, frozen at
+  # construction. It answers the two questions the rest of the gem asks ("is this
+  # allowed?" and "if not, why?") and carries the per-label detail for the
+  # moderation queue, the DSA statement of reasons, and the transparency counters.
+  #
+  # The public surface follows the README's "Content filtering" section verbatim:
+  #   result.allowed?    # => false
+  #   result.flagged?    # => true   (the inverse — convenience for the validator)
+  #   result.categories  # => [:hate, :"hate/threatening"]   (canonical slugs)
+  #   result.scores      # => { "hate" => 0.97, "hate/threatening" => 0.81 }
+  #   result.labels      # => [#<Moderate::Label ...>, ...]
+  #   result.source      # => "wordlist" / "openai" / your adapter name
+  #   result.raw         # => the untouched provider response (for debugging/audit)
+  #
+  # Built on `Data.define` (Ruby 3.2+) for a frozen value object. We expose a
+  # keyword `.new` whose contract is forgiving: an adapter can hand us either a
+  # rich `labels:` array OR the flatter `categories:`/`scores:` shape (the simpler
+  # shape a deterministic adapter naturally returns), and we reconcile both into a
+  # coherent Result.
+  Result = Data.define(:allowed, :labels, :source, :raw) do
+    # @param allowed    [Boolean, nil] explicit allow/deny. If nil, we infer it
+    #   from whether any label is flagged (no labels ⇒ allowed).
+    # @param labels     [Array<Moderate::Label, Hash>] rich per-label verdicts.
+    #   Hashes are coerced to `Moderate::Label`. Optional.
+    # @param categories [Array<String, Symbol>] flat canonical slugs, the simpler
+    #   shape adapters may return instead of `labels:`. Each becomes a Label
+    #   (parsing "hate/threatening" → category :hate, subcategory :threatening).
+    # @param scores     [Hash] slug => 0..1 score, merged onto the labels built
+    #   from `categories:` (and onto label slugs generally).
+    # @param source     [String, Symbol] the adapter name that produced this — the
+    #   value recorded as `Moderate::Flag#source` so the queue shows which backend
+    #   flagged each item. Defaults to "unknown".
+    # @param raw        [Object] the untouched provider payload, kept for audit
+    #   and debugging. Never relied on by the gem's own logic.
+    def initialize(allowed: nil, labels: nil, categories: nil, scores: nil, source: nil, raw: nil)
+      scores_hash = normalize_scores(scores)
+      built_labels = build_labels(labels, categories, scores_hash)
+
+      # Infer `allowed` when the adapter didn't say: any flagged label ⇒ denied.
+      # This lets a deterministic adapter return just `categories: [...]` and have
+      # the verdict fall out correctly, without having to compute `allowed` itself.
+      resolved_allowed =
+        if allowed.nil?
+          built_labels.none?(&:flagged)
+        else
+          allowed ? true : false
+        end
+
+      super(
+        allowed: resolved_allowed,
+        labels: built_labels.freeze,
+        source: (source || "unknown").to_s,
+        raw: raw
+      )
+    end
+
+    # Convenience builder for the most common deterministic case: nothing matched.
+    def self.allowed(source: nil, raw: nil)
+      new(allowed: true, labels: [], source: source, raw: raw)
+    end
+
+    def allowed? = allowed
+
+    # The inverse of `allowed?`. The validator and the `moderates` concern read
+    # this; it's spelled out (rather than `!allowed`) because "flagged?" is the
+    # word everyone reaches for.
+    def flagged? = !allowed
+
+    # Canonical category slugs as symbols, e.g. [:hate, :"hate/threatening"].
+    # Only flagged labels count — an adapter may return a full score map including
+    # non-tripping categories, and those shouldn't show up as "the categories this
+    # tripped". De-duplicated, order-preserving.
+    def categories
+      flagged_labels.map { |label| label.slug.to_sym }.uniq
+    end
+
+    # slug => score, e.g. { "hate" => 0.97, "hate/threatening" => 0.81 }. String
+    # keys to match OpenAI's wire format and what we persist on the Flag. Skips
+    # labels with a nil score (a deterministic adapter may not provide one).
+    def scores
+      flagged_labels.each_with_object({}) do |label, acc|
+        acc[label.slug] = label.score unless label.score.nil?
+      end
+    end
+
+    private
+
+    def flagged_labels
+      labels.select(&:flagged)
+    end
+
+    def normalize_scores(scores)
+      return {} if scores.nil?
+
+      # Accept symbol- or string-keyed maps; normalize keys to the slug string so
+      # we can look up by a Label's slug regardless of how the adapter keyed them.
+      scores.each_with_object({}) do |(key, value), acc|
+        acc[key.to_s] = value&.to_f
+      end
+    end
+
+    # Reconcile the two accepted shapes (`labels:` and `categories:`+`scores:`)
+    # into one frozen array of `Moderate::Label`.
+    def build_labels(labels, categories, scores_hash)
+      out = []
+
+      Array(labels).each do |label|
+        out << coerce_label(label, scores_hash)
+      end
+
+      Array(categories).each do |category|
+        out << label_from_slug(category.to_s, scores_hash)
+      end
+
+      out
+    end
+
+    def coerce_label(label, scores_hash)
+      return apply_score(label, scores_hash) if label.is_a?(Moderate::Label)
+
+      # Allow a plain Hash (e.g. from a deserialized adapter response).
+      label_from_hash(label.to_h, scores_hash)
+    end
+
+    # Backfill a Label's score from the scores map when the Label itself carries
+    # none — so an adapter can pass `labels:` for structure and `scores:` for
+    # confidence as two parallel inputs.
+    def apply_score(label, scores_hash)
+      return label unless label.score.nil?
+
+      score = scores_hash[label.slug]
+      return label if score.nil?
+
+      Moderate::Label.new(
+        category: label.category, subcategory: label.subcategory,
+        score: score, flagged: label.flagged, input: label.input
+      )
+    end
+
+    def label_from_hash(hash, scores_hash)
+      hash = hash.transform_keys { |k| k.to_s }
+      category = hash["category"]
+      subcategory = hash["subcategory"]
+      slug = subcategory ? "#{category}/#{subcategory}" : category.to_s
+
+      Moderate::Label.new(
+        category: category,
+        subcategory: subcategory,
+        score: hash.fetch("score", scores_hash[slug]),
+        flagged: hash.fetch("flagged", true),
+        input: hash.fetch("input", :unknown)
+      )
+    end
+
+    # Parse a canonical slug ("hate/threatening" or "hate") into a Label, pulling
+    # its score from the scores map if present.
+    def label_from_slug(slug, scores_hash)
+      category, subcategory = slug.split("/", 2)
+
+      Moderate::Label.new(
+        category: category,
+        subcategory: subcategory,
+        score: scores_hash[slug],
+        flagged: true,
+        input: :unknown
+      )
+    end
+  end
+end

data/lib/moderate/services/intake_appeal.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Moderate
+  module Services
+    # IntakeAppeal — persistence path for a DSA Article 20 internal complaint
+    # ("appeal") against a moderation decision.
+    #
+    # Art. 20 requires an internal complaint-handling system that is FREE, by
+    # ELECTRONIC means, open for AT LEAST SIX MONTHS after the decision, and decided
+    # by a human (not solely automated). This service owns only the *intake* half:
+    # validating + persisting the complaint and emitting the `appeal_received`
+    # receipt. The human decision lives in ResolveAppeal.
+    # See: https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Article 20).
+    #
+    # The model enforces the legal preconditions (the report must be closed and its
+    # appeal window still open) as validations, so a save that violates them returns
+    # false with errors — this service doesn't re-implement that, it just runs the
+    # surrounding side effects on success.
+    #
+    # HOST-AGNOSTIC: the appellant may be a User (a logged-in affected party) OR an
+    # anonymous notifier (name + email) appealing a public-notice decision. We never
+    # assume a User.
+    class IntakeAppeal
+      # @param appeal [Moderate::Appeal] an unsaved Appeal the caller has populated
+      #   (reason, source, appellant contact). The caller owns strong-params; we own
+      #   save + side effects.
+      # @param report [Moderate::Report] the decision being appealed.
+      # @param appellant [user_class, nil] the complainant, when they're a User.
+      def initialize(appeal:, report:, appellant: nil)
+        @appeal = appeal
+        @appeal.assign_attributes(report: report, appellant: appellant)
+      end
+
+      attr_reader :appeal
+
+      def save
+        return false unless appeal.save
+
+        deliver_receipt
+        audit_intake
+        true
+      end
+
+      private
+
+      # The appellant's receipt ("we got your appeal; a person will review it").
+      # Recipient is the User when present, else the lightweight notifier struct,
+      # so the host's notify hook addresses both the same way (`recipient.email`).
+      def deliver_receipt
+        Moderate.notify(
+          :appeal_received,
+          subject: appeal,
+          actor: appeal.appellant,
+          recipients: [appellant_recipient].compact,
+          payload: {
+            report_id: appeal.report_id,
+            source: appeal.source,
+            summary: "New appeal on Report ##{appeal.report_id}"
+          }
+        )
+      end
+
+      def audit_intake
+        Moderate.audit(
+          :appeal_received,
+          subject: appeal,
+          actor: appeal.appellant,
+          payload: {
+            appeal_id: appeal.id,
+            report_id: appeal.report_id,
+            source: appeal.source,
+            summary: "Appeal ##{appeal.id} filed on Report ##{appeal.report_id}"
+          }.compact
+        )
+      end
+
+      # Prefer the User; fall back to a non-User recipient carrying just the email/
+      # name an anonymous appellant supplied. Reuses the same lightweight-recipient
+      # contract as IntakeNotice (responds to email/name only) so host mailers don't
+      # special-case appeals.
+      def appellant_recipient
+        return appeal.appellant if appeal.appellant
+        return nil if appeal.appellant_email.blank?
+
+        IntakeNotice::NotifierRecipient.new(appeal.appellant_email, appeal.appellant_name)
+      end
+    end
+  end
+end

data/lib/moderate/services/intake_notice.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Moderate
+  module Services
+    # IntakeNotice — persistence path for a *public* DSA Article 16 notice.
+    #
+    # This is the regulator-facing intake: the "Report illegal content (EU)" form
+    # you see at the bottom of X / YouTube / Reddit, open to ANYONE (not just
+    # logged-in users), by electronic means, with a confirmation of receipt. It is
+    # legally distinct from the in-app "Report" button:
+    #   - it carries a `legal_reason` from the DSA statement-of-reasons taxonomy
+    #     (the law's vocabulary) rather than a community `category` (your rules);
+    #   - the notifier may be anonymous (a name+email, not a User);
+    #   - it requires the exact electronic location (URL) of the content — Art.16(2)(b);
+    #   - it requires a good-faith attestation — Art.16(2)(d).
+    # See: https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Article 16).
+    #
+    # A notice is NOT a fourth table: it's a `Moderate::Report` with
+    # `intake_kind: "dsa"`, so it shares the same queue, evidence snapshot, appeal
+    # window, statement-of-reasons path, and Art. 24 transparency counters as an
+    # in-app report. One queue, one decision workflow, two front doors. This service
+    # builds that notice-kind Report and hands it to IntakeReport for the shared
+    # persistence + side effects, then emits the notice-specific `notice_received`
+    # event whose delivery boolean gates the Art. 16(4) "confirmation of receipt".
+    #
+    # HOST-AGNOSTIC: no concrete content type is named. The URL is resolved to a
+    # reportable record (if the host can) by the Report model's snapshot logic; this
+    # service only owns intake orchestration and the legal-email gating.
+    class IntakeNotice
+      # @param attributes [Hash] the public-form attributes, already strong-param'd
+      #   by the controller: notifier_name, notifier_email, good_faith_confirmed,
+      #   legal_reason, legal_country_code, subject_url(s), content_type, message
+      #   (the substantiated explanation), anonymous, reported_account_identifier.
+      # @param reporter [user_class, nil] the submitter IF they happened to be
+      #   logged in (the form is public, so usually nil).
+      def initialize(attributes:, reporter: nil)
+        # Force the DSA shape regardless of what the form posted: a public notice is
+        # always intake_kind "dsa". We default the community `category` to a neutral
+        # "illegal_content" because the column is NOT NULL and a notice's real
+        # taxonomy lives in `legal_reason` — the category is just the bucket that
+        # keeps a notice in the same queue as community reports.
+        @report = Moderate::Report.new(attributes)
+        @report.assign_attributes(
+          intake_kind: "dsa",
+          category: @report.category.presence || "illegal_content"
+        )
+        @report.skip_received_notice = true
+        @reporter = reporter
+      end
+
+      attr_reader :report
+
+      def save
+        # Reuse the shared intake (save + acknowledge! + audit). We pass the report
+        # straight through — it already carries the notice attributes and the forced
+        # DSA shape. The reporter is the actor when present (a logged-in submitter);
+        # for a truly anonymous notice the actor is nil, which the event envelope
+        # handles (system/no-actor events are normal).
+        intake = IntakeReport.new(
+          report: report,
+          reporter: reporter,
+          reportable: report.reportable,
+          reported_field: report.reported_field,
+          actor: reporter
+        )
+        return false unless intake.save
+
+        deliver_confirmation_of_receipt
+        true
+      end
+
+      private
+
+      attr_reader :reporter
+
+      # DSA Art. 16(4): "the provider shall, without undue delay, send to that
+      # individual or entity a confirmation of receipt of the notice."
+      #
+      # We send it to the NOTIFIER (who is often not a User — an anonymous person
+      # with just an email), distinct from IntakeReport's in-app receipt. The notify
+      # hook returns a "delivered" boolean: when it's truthy we stamp
+      # `decision_notified_at`... no — we stamp nothing here, because the durable
+      # legal proof of *receipt* is `acknowledged_at` (already set by IntakeReport).
+      # The boolean instead lets the controller fall back to an on-screen receipt
+      # (the form shows a reference number) when the host hasn't wired a mailer —
+      # that's the whole reason `Moderate.notify` returns delivered/undelivered
+      # rather than nothing. See docs/notifications.md and docs/dsa-notice-form.md.
+      #
+      # The recipient is a lightweight notifier struct (responds to email/name) when
+      # the submitter isn't a User, so the host's `notify` hook can email it the same
+      # way it emails a real user — the recipes guard with `respond_to?(:email)`.
+      def deliver_confirmation_of_receipt
+        return false if report.notifier_email.blank?
+
+        Moderate.notify(
+          :notice_received,
+          subject: report,
+          actor: reporter,
+          recipients: [notifier_recipient],
+          payload: {
+            legal_reason: report.legal_reason,
+            legal_country_code: report.legal_country_code,
+            subject_url: report.subject_url,
+            # Redaction-safe admin one-liner. We deliberately keep host content out
+            # of it — just the legal ground and an opaque pointer to the record.
+            summary: "New DSA notice (#{report.legal_reason || 'illegal_content'}) — Report ##{report.id}"
+          }
+        )
+      end
+
+      # A non-User recipient the host's mailer can address. We prefer the real
+      # reporter (a User) when the submitter was logged in; otherwise we build a
+      # minimal value object that quacks like a recipient (responds to `email`,
+      # `name`) — documented in docs/notifications.md as the "lightweight recipient"
+      # for anonymous DSA notifiers.
+      def notifier_recipient
+        return report.reporter if report.reporter
+
+        NotifierRecipient.new(report.notifier_email, report.notifier_name)
+      end
+
+      # The anonymous-notifier recipient. Intentionally tiny and NOT a User: the
+      # host's notify hook reaches `recipient.email` / `recipient.name` and nothing
+      # else. Frozen value object.
+      NotifierRecipient = Data.define(:email, :name) do
+        # Mirror the User-ish reader some host mailers reach for, so a notifier and a
+        # User are interchangeable at the `recipient.email` call site.
+        def display_name = name.to_s.empty? ? email : name
+      end
+    end
+  end
+end

data/lib/moderate/services/intake_report.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Moderate
+  module Services
+    # IntakeReport — the single persistence path for an *in-app* community report
+    # (a logged-in actor tapping "Report" on a piece of content or another user).
+    #
+    # WHY a service object and not just `Report.create`:
+    #   - Intake is more than a save. After the row commits we must (a) acknowledge
+    #     receipt, (b) emit the `report_received` event (the reporter's receipt +
+    #     the admin ping), and (c) write the immutable audit record. Keeping all of
+    #     that in one object means the model stays a plain validating record and the
+    #     side effects live in exactly one place — easy to test, impossible to
+    #     accidentally skip from a second call site.
+    #   - The same shape is reused by the public DSA notice path (see IntakeNotice),
+    #     which delegates here once it has assembled a notice-kind Report. One intake,
+    #     two front doors.
+    #
+    # This object is HOST-AGNOSTIC: it never references a concrete content type. The
+    # `has_reportable_content` is any `Moderate::Reportable` record (polymorphic), the actor is
+    # whatever `Moderate.user_class` resolves to, and notification/audit go through
+    # the configured hooks — never a hard-wired mailer.
+    class IntakeReport
+      # @param report [Moderate::Report] an unsaved Report the caller has already
+      #   populated (category, message, etc.). Letting the caller build the record
+      #   keeps this service free of the (host-specific) strong-params shape — the
+      #   controller/macro decides which attributes are permitted; we own the save +
+      #   side effects.
+      # @param reporter [user_class, nil] who filed it. nil for an anonymous public
+      #   notice (the DSA path), present for an in-app report.
+      # @param reportable [Moderate::Reportable, nil] the reported content/record.
+      # @param reported_field [String, Symbol, nil] which field was reported.
+      # @param actor [user_class, nil] who triggered the intake for the audit/event
+      #   envelope (defaults to the reporter — they're the same person for an in-app
+      #   report; a public notice may have no actor).
+      def initialize(report:, reporter: nil, reportable: nil, reported_field: nil, actor: :reporter)
+        @report = report
+        @report.assign_attributes(
+          reporter: reporter,
+          reportable: reportable,
+          reported_field: reported_field&.to_s
+        )
+        # ":reporter" sentinel means "use the reporter as the actor" — the common
+        # case — while still letting a caller pass `actor: nil` explicitly.
+        @actor = actor == :reporter ? reporter : actor
+      end
+
+      attr_reader :report
+
+      # Persist + run side effects. Returns true on success, false if validation
+      # failed (the report carries its errors, Rails-conventionally) so a controller
+      # can `if intake.save ... else render :new` exactly like a bare model save.
+      def save
+        return false unless report.save
+
+        # DSA Art. 16(4): the provider must confirm receipt "without undue delay."
+        # `acknowledge!` stamps `acknowledged_at` — the durable, on-record proof of
+        # receipt — BEFORE we attempt the (best-effort, possibly-undelivered) email,
+        # so the legal obligation is met by the database fact, not by a mailer that
+        # might not be wired. See: https://eur-lex.europa.eu/eli/reg/2022/2065/oj
+        report.acknowledge!
+
+        deliver_receipt
+        audit_intake
+        true
+      end
+
+      private
+
+      attr_reader :actor
+
+      # The reporter's receipt. We only attempt it when there's somewhere to send it
+      # (a notifier_email) — an in-app reporter without a contact email simply gets
+      # the in-app acknowledgement instead. `Moderate.notify` returns a "delivered"
+      # boolean; we don't gate anything on it here (the durable receipt is
+      # `acknowledged_at`, set above), but the recipient list is still resolved so
+      # the host's single notify hook can email AND ping admins from one event.
+      def deliver_receipt
+        return if report.skip_received_notice
+        return if recipient_email.blank?
+
+        Moderate.notify(
+          :report_received,
+          subject: report,
+          actor: actor,
+          recipients: [report.reporter].compact,
+          payload: {
+            category: report.category,
+            intake_kind: report.intake_kind,
+            # `:summary` is the contract every event carries — a redaction-safe,
+            # ready-to-send one-liner for the admin Telegram ping (docs/notifications.md).
+            summary: "New #{report.category} report on #{reportable_label}"
+          }
+        )
+      end
+
+      # Append-only audit of the intake itself (separate from the notify hook, which
+      # is for humans). `Moderate.audit` swallows its own errors, so a broken audit
+      # sink can never roll back an accepted report.
+      def audit_intake
+        Moderate.audit(
+          :report_received,
+          subject: report,
+          actor: actor,
+          payload: {
+            report_id: report.id,
+            reportable_type: report.reportable_type,
+            reportable_id: report.reportable_id,
+            reported_user_id: report.reported_user_id,
+            category: report.category,
+            intake_kind: report.intake_kind,
+            summary: "Report ##{report.id} filed (#{report.category})"
+          }.compact
+        )
+      end
+
+      def recipient_email
+        report.notifier_email
+      end
+
+      # The reportable's own human label, or a neutral fallback — NEVER a host-
+      # specific string. The Reportable concern supplies `moderation_label`.
+      def reportable_label
+        if report.reportable.respond_to?(:moderation_label)
+          report.reportable.moderation_label
+        else
+          [report.reportable_type, report.reportable_id].compact.join(" #")
+        end
+      end
+    end
+  end
+end

data/lib/moderate/services/resolve_appeal.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Moderate
+  module Services
+    # ResolveAppeal — the human decision on a DSA Article 20 appeal, behind
+    # `appeal.uphold!` / `appeal.reject!`.
+    #
+    # Art. 20 demands appeals be decided "in a timely, non-discriminatory, diligent
+    # and non-arbitrary manner" and crucially "NOT SOLELY ON THE BASIS OF AUTOMATED
+    # MEANS." That last clause is why there is no auto-decide path here at all:
+    # `uphold!`/`reject!` REQUIRE a `by:` moderator and a `note:` — a human and a
+    # reason — and the model column for the moderator (`resolved_by`) makes the human
+    # decider part of the permanent record.
+    # See: https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Article 20).
+    #
+    # Same atomic discipline as ResolveReport: the transition runs under a row lock,
+    # re-checks `open?` inside the lock (so two moderators can't both decide the same
+    # appeal), and the notification happens after the lock releases.
+    #
+    # NOTE on enforcement: upholding an appeal means the ORIGINAL decision was wrong
+    # and should be reversed (Art. 20 outcomes must be acted on). Reversal is
+    # host-specific — re-publishing content, lifting a ban — and the gem can't know
+    # how to undo an arbitrary host action. So this service records the upheld
+    # outcome and emits `appeal_decision`; the host wires the actual reversal off
+    # that event (or off its `audit` hook). We document this rather than pretend a
+    # generic "un-remove" exists.
+    class ResolveAppeal
+      def initialize(appeal, by:)
+        @appeal = appeal
+        @moderator = by
+      end
+
+      def uphold!(note:)
+        transition!("upheld", note)
+      end
+
+      def reject!(note:)
+        transition!("rejected", note)
+      end
+
+      private
+
+      attr_reader :appeal, :moderator
+
+      def transition!(status, note)
+        note = require_note!(note)
+
+        appeal.with_lock do
+          appeal.reload
+
+          # A decided appeal is immutable — re-check inside the lock so a concurrent
+          # second decision bails cleanly instead of overwriting the first.
+          unless appeal.open?
+            appeal.errors.add(:base, already_closed_message)
+            raise ActiveRecord::RecordInvalid, appeal
+          end
+
+          appeal.update!(
+            status: status,
+            resolution_note: note,
+            resolved_by: moderator,
+            resolved_at: Time.now
+          )
+
+          audit_decision(status, note)
+        end
+
+        deliver_decision_notice(status)
+        appeal
+      end
+
+      # Inform the complainant of the appeal outcome and remaining redress (out-of-
+      # court dispute settlement / judicial — copy is the host's, it names the
+      # jurisdiction). We stamp `decision_notified_at` only when the hook reported a
+      # delivery, so the timestamp reflects an actual communication.
+      def deliver_decision_notice(status)
+        delivered = Moderate.notify(
+          :appeal_decision,
+          subject: appeal,
+          actor: moderator,
+          recipients: [appellant_recipient].compact,
+          payload: {
+            appeal_id: appeal.id,
+            report_id: appeal.report_id,
+            status: status,
+            reason: appeal.resolution_note,
+            summary: "Decision on appeal for Report ##{appeal.report_id}: #{status}"
+          }.compact
+        )
+
+        appeal.update_column(:decision_notified_at, Time.now) if delivered
+      end
+
+      def audit_decision(status, note)
+        Moderate.audit(
+          :appeal_decision,
+          subject: appeal,
+          actor: moderator,
+          payload: {
+            appeal_id: appeal.id,
+            report_id: appeal.report_id,
+            status: status,
+            note: note,
+            summary: "Appeal ##{appeal.id} #{status} by moderator"
+          }.compact
+        )
+      end
+
+      # The complainant: a User when present, else the lightweight notifier struct.
+      def appellant_recipient
+        return appeal.appellant if appeal.appellant
+        return nil if appeal.appellant_email.blank?
+
+        IntakeNotice::NotifierRecipient.new(appeal.appellant_email, appeal.appellant_name)
+      end
+
+      def require_note!(note)
+        normalized = note.to_s.strip
+        return normalized unless normalized.empty?
+
+        appeal.errors.add(:resolution_note, :blank)
+        raise ActiveRecord::RecordInvalid, appeal
+      end
+
+      def already_closed_message
+        if defined?(I18n)
+          I18n.t("moderate.errors.appeal_already_closed", default: "This appeal has already been decided.")
+        else
+          "This appeal has already been decided."
+        end
+      end
+    end
+  end
+end