moderate 1.0.0.beta2 → 1.0.0

data/lib/moderate/retention.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Opt-in retention: strip the personal data out of moderation records nobody can
+  # act on any more, and keep the decisions.
+  #
+  #   Moderate.purge(older_than: 1.year)                # what a nightly job runs
+  #   Moderate.purge(older_than: 18.months, dry_run: true)  # => counts, nothing changed
+  #   bin/rails moderate:purge OLDER_THAN_DAYS=365 DRY_RUN=1
+  #
+  # Nothing in the gem calls this: until a host schedules it, every report, flag,
+  # appeal and block is kept as it was written. docs/compliance.md ("Retention")
+  # says what is stored, what this removes, and why the rest stays.
+  #
+  # What it touches — only records whose decision is final:
+  #
+  #   * a REPORT (in-app report or DSA notice) that is closed, was decided more than
+  #     `older_than` ago, whose appeal window has closed, and that has no open
+  #     appeal: its message, evidence snapshot, reported URLs, reported account
+  #     identifier, notifier name and email, and reporter are removed;
+  #   * a FLAG that was decided more than `older_than` ago: its excerpt and its
+  #     context (the classifier's raw response, a reviewer's note) are removed;
+  #   * an APPEAL that was decided more than `older_than` ago: its reason and the
+  #     appellant's name and email are removed.
+  #
+  # What it keeps: every row, with its type, category, legal ground, member state,
+  # content type, status, timestamps, the decision (resolution basis, actions,
+  # note, decision visibility, automated-means disclosure) and who it was about
+  # (reported user, flag owner). Those are the statement of reasons, the record a
+  # repeat-misuse policy (DSA Art. 23) and a legal claim rely on, and what
+  # `Moderate.transparency` counts, so a published Art. 15/24 report stays
+  # reproducible. Blocks are never touched: they are live safety state, not a
+  # record of the past, and go when either person unblocks or is deleted.
+  #
+  # Pending reports, flags and appeals are never touched, whatever their age.
+  module Retention
+    # What a removed text column reads afterwards (message, excerpt and reason are
+    # NOT NULL). Only a filler: whether a row is done is its `redacted_at`.
+    REDACTED = "[redacted]"
+
+    # The default age, counted from the decision. Six months of appeal window
+    # (Art. 20), the time an out-of-court dispute settlement body may take (Art. 21),
+    # and a margin for a complaint or legal claim that arrives late.
+    DEFAULT_AGE = 1.year
+
+    # `older_than` may not be shorter than the appeal window: a decision that can
+    # still be appealed must keep its evidence.
+    def self.minimum_age
+      Moderate::Report::APPEAL_WINDOW
+    end
+
+    # Redact what is old enough, and return how many rows of each kind changed (or
+    # would change, with `dry_run: true`), plus, under `:held`, how many were old
+    # enough but kept for a legal hold. Audited as `:retention_purged` when anything
+    # changed. Idempotent: a row is selected while its `redacted_at` is nil, whatever
+    # its content says, and stamped when it is redacted.
+    #
+    #   Moderate.purge  # => { reports: 3, flags: 9, appeals: 1, classifications: 40,
+    #                   #      held: { reports: 1, flags: 2, appeals: 0 } }
+    def self.purge(older_than: DEFAULT_AGE, now: Time.current, dry_run: false)
+      age = older_than.to_i
+      if older_than.nil? || age < minimum_age.to_i
+        raise ArgumentError,
+          "older_than must be at least the #{minimum_age.inspect} appeal window (got #{older_than.inspect}): " \
+          "a decision that can still be appealed keeps its evidence"
+      end
+
+      cutoff = now - older_than
+      due = { reports: reports_due(cutoff, now), flags: flags_due(cutoff), appeals: appeals_due(cutoff) }
+      held = due.to_h { |kind, scope| [kind, scope.where(hold_condition(kind, now, held: true)).count] }
+      free = due.to_h { |kind, scope| [kind, scope.where(hold_condition(kind, now, held: false))] }
+      classifications = classifications_due(cutoff, now)
+      kept = { claims_kept: live_claims(cutoff, now).count, held: held }
+      return free.transform_values(&:count).merge(classifications: classifications.count, **kept) if dry_run
+
+      counts = {
+        reports: redact(free[:reports], report_redaction(now)),
+        flags: redact(free[:flags], flag_redaction(now)),
+        appeals: redact(free[:appeals], appeal_redaction(now)),
+        classifications: delete(classifications)
+      }
+      audit(counts, held, cutoff: cutoff, older_than: age) if counts.values.sum.positive?
+      counts.merge(kept)
+    end
+
+    # Put `report` under a legal hold until `until:` (a future time): the purge leaves
+    # the report, its appeals and the flags on its content alone, however old they
+    # are — an out-of-court dispute (DSA Art. 21), a court case, an authority's
+    # request. Placing it again moves the date (later or earlier). Audited as
+    # `:legal_hold_placed`.
+    def self.hold(report, until:, by: nil, reason: nil)
+      held_until = binding.local_variable_get(:until)
+      unless held_until.respond_to?(:to_time) && held_until.to_time > Time.current
+        raise ArgumentError, "a legal hold needs a time in the future (until: #{held_until.inspect})"
+      end
+
+      report.update_columns(held_until: held_until, updated_at: Time.current)
+      Moderate.audit(:legal_hold_placed, **hold_event(report, by: by, reason: reason, held_until: held_until))
+      report
+    end
+
+    # Lift `report`'s legal hold: the next purge treats it like any other report.
+    # Audited as `:legal_hold_released`. A report with no hold is returned unchanged.
+    def self.release_hold(report, by: nil, reason: nil)
+      return report if report.held_until.nil?
+
+      report.update_columns(held_until: nil, updated_at: Time.current)
+      Moderate.audit(:legal_hold_released, **hold_event(report, by: by, reason: reason, held_until: nil))
+      report
+    end
+
+    # Closed reports decided before `cutoff`, out of their appeal window and with
+    # no appeal still open, not redacted yet.
+    def self.reports_due(cutoff, now)
+      reports = Moderate::Report
+      open_appeals = Moderate::Appeal.pending.select(:report_id)
+
+      reports.where(status: reports::STATUSES - ["open"], redacted_at: nil)
+        .where(resolved_at: ..cutoff)
+        .where(reports.arel_table[:appeal_deadline_at].eq(nil).or(reports.arel_table[:appeal_deadline_at].lteq(now)))
+        .where.not(id: open_appeals)
+    end
+
+    def self.flags_due(cutoff)
+      flags = Moderate::Flag
+      flags.where(status: flags::STATUSES - ["pending"], redacted_at: nil).where(reviewed_at: ..cutoff)
+    end
+
+    # Attachment classification bookkeeping (Moderate::Classification: ids, a digest,
+    # timestamps) last touched before `cutoff`: classified then, or a claim nobody
+    # completed. Deleted, not redacted: nothing in them is evidence. Never a row with
+    # a LIVE claim (younger than config.classification_claim_ttl), whatever its age:
+    # a worker is classifying those files right now, and would discard its result.
+    def self.classifications_due(cutoff, now)
+      rows = Moderate::Classification.arel_table
+      Moderate::Classification.where(updated_at: ..cutoff)
+        .where(rows[:claimed_at].eq(nil).or(rows[:claimed_at].lt(now - Moderate::Attachments.claim_ttl)))
+    end
+
+    # Rows the age cutoff would take but a live claim keeps (`:claims_kept`).
+    def self.live_claims(cutoff, now)
+      Moderate::Classification.where(updated_at: ..cutoff).where(claimed_at: (now - Moderate::Attachments.claim_ttl)..)
+    end
+
+    def self.delete(scope)
+      deleted = 0
+      scope.in_batches(of: 500) { |batch| deleted += batch.delete_all }
+      deleted
+    end
+
+    def self.appeals_due(cutoff)
+      appeals = Moderate::Appeal
+      appeals.where(status: appeals::STATUSES - ["open"], redacted_at: nil).where(resolved_at: ..cutoff)
+    end
+
+    # Arel for "kept by a legal hold" (held: true) or "not" (held: false): the
+    # report's own hold; an appeal's report's; for a flag, a held report on the same
+    # content and field (or on the whole record). Written both ways rather than
+    # negated, because NOT (held_until > now) is NULL, not true, for a report that
+    # was never held.
+    def self.hold_condition(kind, now, held:)
+      reports = Moderate::Report.arel_table
+      held_reports = Moderate::Report.where(reports[:held_until].gt(now))
+      case kind
+      when :reports
+        held ? reports[:held_until].gt(now) : reports[:held_until].eq(nil).or(reports[:held_until].lteq(now))
+      when :appeals
+        ids = held_reports.select(:id).arel
+        held ? Moderate::Appeal.arel_table[:report_id].in(ids) : Moderate::Appeal.arel_table[:report_id].not_in(ids)
+      when :flags
+        flags = Moderate::Flag.arel_table
+        same_content = held_reports
+          .where(reports[:reportable_type].eq(flags[:flaggable_type]))
+          .where(reports[:reportable_id].eq(flags[:flaggable_id]))
+          .where(reports[:reported_field].eq(flags[:field]).or(reports[:reported_field].eq(nil)))
+          .arel.exists
+        held ? same_content : same_content.not
+      end
+    end
+
+    def self.report_redaction(now)
+      {
+        message: REDACTED,
+        snapshot: { "redacted_at" => now.iso8601 },
+        subject_url: nil,
+        subject_urls: [],
+        reported_account_identifier: nil,
+        notifier_name: nil,
+        notifier_email: nil,
+        reporter_id: nil,
+        redacted_at: now,
+        updated_at: now
+      }
+    end
+
+    def self.flag_redaction(now)
+      { excerpt: REDACTED, context: { "redacted_at" => now.iso8601 }, redacted_at: now, updated_at: now }
+    end
+
+    def self.appeal_redaction(now)
+      { reason: REDACTED, appellant_name: nil, appellant_email: nil, redacted_at: now, updated_at: now }
+    end
+
+    # One UPDATE per batch, no callbacks or validations: a redacted DSA notice no
+    # longer carries the notifier details its validations ask for, and nothing
+    # should re-save a final record anyway.
+    def self.redact(scope, attributes)
+      changed = 0
+      scope.in_batches(of: 500) { |batch| changed += batch.update_all(attributes) }
+      changed
+    end
+
+    def self.audit(counts, held, cutoff:, older_than:)
+      Moderate.audit(
+        :retention_purged,
+        payload: counts.merge(
+          held: held,
+          cutoff: cutoff.iso8601,
+          older_than_seconds: older_than,
+          summary: "retention: redacted #{counts[:reports]} reports, #{counts[:flags]} flags, " \
+                   "#{counts[:appeals]} appeals decided before #{cutoff.to_date}; deleted " \
+                   "#{counts[:classifications]} classification rows"
+        )
+      )
+    end
+
+    def self.hold_event(report, by:, reason:, held_until:)
+      {
+        subject: report,
+        actor: by,
+        payload: {
+          report_id: report.id, held_until: held_until&.iso8601, reason: reason,
+          summary: held_until ? "Report ##{report.id} held until #{held_until.to_date}" : "Report ##{report.id} hold released"
+        }.compact
+      }
+    end
+
+    private_class_method :reports_due, :flags_due, :appeals_due, :classifications_due, :live_claims, :delete,
+      :hold_condition, :report_redaction, :flag_redaction, :appeal_redaction, :redact, :audit, :hold_event
+  end
+end

data/lib/moderate/services/intake_notice.rb

@@ -69,6 +69,15 @@ module Moderate
         true
       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
+
       private
 
       attr_reader :reporter
@@ -103,7 +112,7 @@ module Moderate
             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}"
+            summary: "New DSA notice (#{report.legal_reason || "illegal_content"}) — Report ##{report.id}"
           }
         )
       end
@@ -118,15 +127,6 @@ module Moderate
 
         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

@@ -51,18 +51,27 @@ module Moderate
       # 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
+        # The report and, for "report and block", the block are ONE act: both commit
+        # or neither does (a host on_block hook that raises rolls the report back
+        # too, and the error reaches the caller), and the receipt goes out only after.
+        Moderate::Report.transaction do
+          # Captured before the save (Moderate::DeferredNotices).
+          connection = Moderate::DeferredNotices.connection_for(Moderate::Report)
+          next 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
+          # 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!
+          block_reported_user
+          # The receipt waits for the report to be durable (Moderate::DeferredNotices):
+          # never a "we got your report" for a report a surrounding transaction undid.
+          report.after_commit_notice(on: connection) { deliver_receipt }
+          audit_intake
+          true
+        end
       end
 
       private
@@ -87,10 +96,13 @@ module Moderate
           payload: {
             category: report.category,
             intake_kind: report.intake_kind,
+            reported_field: report.reported_field,
+            reported_field_label: field_label,
             # `: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}"
-          }
+            # The field label is host-declared copy, never user content, so it's safe here.
+            summary: ["New #{report.category} report on #{reportable_label}", field_label].compact.join(" · ")
+          }.compact
         )
       end
 
@@ -114,10 +126,27 @@ module Moderate
         )
       end
 
+      # "Report and block": the reporter asked to block the person responsible too.
+      # After the report is safely filed, through the one block path (Block.block!:
+      # idempotent, audited, on_block, user_blocked). A self-block is a no-op there.
+      def block_reported_user
+        return unless ActiveModel::Type::Boolean.new.cast(report.block_reported_user)
+
+        reporter = report.reporter
+        blocked = report.reported_user
+        return if reporter.blank? || blocked.blank? || !reporter.respond_to?(:block!)
+
+        reporter.block!(blocked)
+      end
+
       def recipient_email
         report.notifier_email
       end
 
+      def field_label
+        report.reported_field_label
+      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

data/lib/moderate/services/resolve_appeal.rb

@@ -45,8 +45,13 @@ module Moderate
       def transition!(status, note)
         note = require_note!(note)
 
+        # Captured before any save (Moderate::DeferredNotices).
+        connection = Moderate::DeferredNotices.connection_for(appeal.class)
+
         appeal.with_lock do
-          appeal.reload
+          # `with_lock` already re-read the row under the lock (SELECT … FOR UPDATE):
+          # no plain reload here — under MySQL's REPEATABLE READ a plain read pins the
+          # transaction's snapshot, and every later check must see what committed.
 
           # A decided appeal is immutable — re-check inside the lock so a concurrent
           # second decision bails cleanly instead of overwriting the first.
@@ -63,9 +68,10 @@ module Moderate
           )
 
           audit_decision(status, note)
+          # Sent once the decision is durable (Moderate::DeferredNotices).
+          appeal.after_commit_notice(on: connection) { deliver_decision_notice(status) }
         end
 
-        deliver_decision_notice(status)
         appeal
       end
 

data/lib/moderate/services/resolve_flag.rb

@@ -2,40 +2,48 @@
 
 module Moderate
   module Services
-    # ResolveFlag — the decision on an auto-filter `Moderate::Flag`, behind the
-    # flag's `action!` / `dismiss!`.
+    # ResolveFlag — the decision on a `Moderate::Flag`, behind the flag's
+    # `action!` / `dismiss!` (and `resolve!`, the queue-wide verb).
     #
     # A Flag is a SYSTEM-raised queue item (the wordlist/image/external classifier
-    # tripped on a `:flag`-mode field, or a human filed one manually) — it's the
-    # "ongoing moderation" surface Apple Guideline 1.2 and Google Play UGC expect:
+    # tripped on a `:flag`-mode field, or an administrator filed one by hand) — it's
+    # the "ongoing moderation" surface Apple Guideline 1.2 and Google Play UGC expect:
     #   - https://developer.apple.com/app-store/review/guidelines/#user-generated-content
     #   - https://support.google.com/googleplay/android-developer/answer/9876937
     #
-    # A flag is lighter than a report: there's no reporter to inform and no appeal
-    # window to stamp (an appeal attaches to a *report* decision, not to a raw
-    # queue item). So this service is the simplest of the resolvers — atomic
-    # transition, mandatory note, audit — but it follows the same discipline:
+    # Same discipline as every resolver:
     #   - `with_lock` + re-check `pending?` inside the lock for idempotency under
-    #     concurrent review;
+    #     concurrent review (a flag already reviewed is returned as-is: a benign
+    #     "already done" suits a fast triage queue);
     #   - a NOTE IS MANDATORY (the moderator's rationale is the audit trail);
-    #   - the decision is recorded via `Moderate.audit`, never a host-specific log.
+    #   - the decision is recorded via `Moderate.audit` (`:flag_decision`).
     #
-    # NOTE: unlike ResolveReport, resolving a flag does NOT itself run content
-    # removal/bans. A flag marks "this needs a look"; the enforcement decision is a
-    # *report* concern. If a moderator wants to remove the flagged content, they file
-    # /resolve a report on it. This keeps the flag a pure triage record and avoids
-    # two divergent enforcement paths. (Documented so a maintainer doesn't "helpfully"
-    # add removal here and create that divergence.)
+    # ENFORCEMENT GOES THROUGH A REPORT. A flag carries no reporter, no statement of
+    # reasons and no appeal window — but removing content or suspending an account is
+    # a restriction, and DSA Art. 17 (statement of reasons) and Art. 20 (appeal) attach
+    # to restrictions, not to queue items. So `action!(remove_content: or ban_user:)`
+    # ESCALATES: it takes the open report on the same content and field, or opens a
+    # system one (no reporter, no receipt), and resolves it through ResolveReport —
+    # the one enforcement path in the gem (remove via `remove_reported_field!`, ban via
+    # `ban_handler`, the decision notices, the appeal window). All of it happens under
+    # the FLAG's row lock, so two moderators pressing "remove" at once enforce once;
+    # the decision notices go out after the lock is released, like every decision.
+    #
+    # Without enforcement options, `action!` is a pure triage close, as before.
     class ResolveFlag
       def initialize(flag, by:)
         @flag = flag
         @moderator = by
       end
 
-      # The flagged content was indeed objectionable — mark the flag actioned. (Any
-      # actual takedown is done by acting on a report; see the class note.)
-      def action!(note:)
-        transition!("actioned", note)
+      # The flagged content was indeed objectionable — mark the flag actioned, and,
+      # when asked, enforce through a report (see the class doc). `resolution_basis`
+      # is the report's legal/contractual ground (Report::RESOLUTION_BASES).
+      def action!(note:, remove_content: false, ban_user: false, resolution_basis: "terms")
+        enforcement = { remove_content: truthy?(remove_content), ban_user: truthy?(ban_user) }
+        enforcement = nil unless enforcement.values.any?
+
+        transition!("actioned", note, enforcement: enforcement, resolution_basis: resolution_basis)
       end
 
       # False positive / acceptable — dismiss the flag.
@@ -47,31 +55,165 @@ module Moderate
 
       attr_reader :flag, :moderator
 
-      def transition!(status, note)
+      def transition!(status, note, enforcement: nil, resolution_basis: nil)
         note = require_note!(note)
+        decision = nil
+        # Captured before any save: the decision's notices join this connection's
+        # transaction, whatever a host callback switches to (Moderate::DeferredNotices).
+        connection = Moderate::DeferredNotices.connection_for(flag.class)
 
         flag.with_lock do
-          flag.reload
+          # `with_lock` already re-read the row under the lock (SELECT … FOR UPDATE):
+          # no plain reload here — under MySQL's REPEATABLE READ a plain read pins the
+          # transaction's snapshot, and every later check must see what committed.
 
           # Re-check inside the lock. A flag already reviewed is returned as-is (NOT
-          # an error): unlike a report, double-reviewing a flag is harmless and a
-          # benign "already done" is friendlier for a fast triage queue.
-          return flag unless flag.pending?
-
-          flag.update!(
-            status: status,
-            resolution_note: note,
-            reviewed_by: moderator,
-            reviewed_at: Time.now
-          )
-
-          audit_decision(status, note)
+          # an error) — and nothing is enforced a second time.
+          next unless flag.pending?
+
+          decision, report = enforce!(note, enforcement, resolution_basis) if enforcement
+          close!(status, note, report)
+
+          # The escalated decision's notices, queued on the flag: sent when the
+          # outermost transaction commits, never on a rollback (DeferredNotices).
+          flag.after_commit_notice(on: connection) { decision.deliver_decision_notices } if decision
         end
 
         flag
       end
 
-      def audit_decision(status, note)
+      # Enforce under the CONTENT's row lock and, when the decision can ban, the
+      # PERSON's (after the flag's, before any report's: the lock order in
+      # Moderate.with_row_lock), so two flags on the same content can't both enforce,
+      # nor two bans of the same person: the second waits, then finds the decision the
+      # first took. Removal-only enforcement never touches the person's row.
+      #
+      # Both locks come BEFORE the first read of moderate_reports, and that matters on
+      # MySQL: its locking reads of the reports table (the checks below) take gap locks
+      # under REPEATABLE READ, and two decisions holding gap locks that each then insert
+      # a report deadlock. Waiting on the content or the person first means the second
+      # decision touches the reports table only after the first one has committed.
+      # Returns [the ResolveReport that decided, or nil, the report the flag answers to].
+      def enforce!(note, enforcement, resolution_basis)
+        Moderate.with_row_lock(flag.flaggable) do
+          Moderate.with_row_lock(enforcement[:ban_user] ? flag.owner : nil) do
+            prior = covering_decision(enforcement)
+            next [nil, prior] if prior
+
+            report = escalation_report!(note)
+            decision = ResolveReport.new(report, by: moderator, deliver: false, conduct_since: flag.created_at)
+            decision.resolve!(note: note, resolution_basis: resolution_basis, **enforcement)
+            [decision, report]
+          end
+        end
+      end
+
+      # A report on the same content and field, decided since this flag was filed,
+      # that already did everything asked now (removed it, banned the person). The
+      # flag closes against it instead of restricting a second time. A recorded
+      # removal only counts if the content is actually gone now: an older decision
+      # may say "removed" without having removed anything.
+      def covering_decision(enforcement)
+        asked = enforcement.select { |_action, wanted| wanted }.keys.map(&:to_s)
+        return if asked.include?("remove_content") && !content_gone?
+
+        # A locking read (see Moderate.with_row_lock): sees the decision a concurrent
+        # moderator committed while we waited, whatever the isolation level.
+        decided = Moderate::Report.actioned.where(same_content).where(resolved_at: flag.created_at..).recent_first.lock
+        decided.find { |report| asked.all? { |action| truthy?(report.resolution_actions.to_h[action]) } }
+      end
+
+      # Is the flagged field's content gone? The record deleted, the record saying it
+      # is (`deleted?`, a soft-delete tombstone), or the field reading as empty. Read
+      # fresh, under the content's lock: a decision that just committed removed it.
+      def content_gone?
+        content = flag.flaggable&.reload(lock: true) # a locking read: what committed, not our snapshot
+        return true if content.nil?
+        return true if content.respond_to?(:deleted?) && content.deleted?
+
+        value = flagged_value(content)
+        value.respond_to?(:attached?) ? !value.attached? : value.blank?
+      rescue ActiveRecord::RecordNotFound
+        true
+      end
+
+      def flagged_value(content)
+        return content.send(:moderation_field_value, flag.field) if content.respond_to?(:moderation_field_value, true)
+
+        content.public_send(flag.field) if content.respond_to?(flag.field)
+      end
+
+      def close!(status, note, report)
+        context = report ? flag.context.to_h.merge("report_id" => report.id) : flag.context
+        flag.update!(status: status, resolution_note: note, reviewed_by: moderator, reviewed_at: Time.current,
+          context: context)
+        audit_decision(status, note, report)
+      end
+
+      # The report enforcement runs through: the newest OPEN report on the same
+      # content and field (a person may already have reported what the filter
+      # caught), else a system report opened for this decision. A system report has
+      # no reporter, so it sends no receipt and no reporter-facing decision; the
+      # affected user still gets the statement of reasons and the appeal window.
+      def escalation_report!(note)
+        existing = Moderate::Report.open.where(same_content).recent_first.lock.first
+        return disclose_automation!(existing) if existing
+
+        system_report!(note)
+      end
+
+      def same_content
+        { reportable_type: flag.flaggable_type, reportable_id: flag.flaggable_id, reported_field: flag.field }
+      end
+
+      # A system report opened for this decision. It may name any field the flag is
+      # on (`escalated_from_flag`): a filtered field (an image, say) needn't be one a
+      # PERSON may report for the gem to enforce on it.
+      def system_report!(note)
+        message = "Escalated from flag ##{flag.id} (#{flag.source}): #{note}"
+        report = Moderate::Report.new(
+          reportable: flag.flaggable, reported_field: flag.field, reported_user: flag.owner,
+          intake_kind: "community", category: escalation_category,
+          message: message.truncate(Moderate::Report::MESSAGE_MAX_LENGTH),
+          good_faith_confirmed: true, skip_received_notice: true
+        )
+        # Private on Report, set only here: not a host-assignable way around the
+        # field whitelist.
+        report.send(:escalated_from_flag=, flag)
+        report.save!
+        report
+      end
+
+      # A person's report filed BEFORE a classifier flagged the same content never
+      # saw that flag, so its automated-means disclosure (DSA Art. 17(3)(c)) says
+      # "no". When the flag is what's being enforced, the decision must say "yes":
+      # merge the flag's evidence in first. A manual flag is a person, not automation.
+      def disclose_automation!(report)
+        return report if flag.source == "manual"
+
+        evidence = report.automated_processing.to_h
+        disclosed = evidence.merge(
+          "used" => true,
+          "flag_ids" => Array(evidence["flag_ids"]) | [flag.id],
+          "sources" => Array(evidence["sources"]) | [flag.source],
+          "categories" => Array(evidence["categories"]) | Array(flag.categories)
+        )
+        report.update_column(:automated_processing, disclosed)
+        report
+      end
+
+      # The flag's own categories speak the classifier taxonomy ("hate",
+      # "hate/threatening", "sexual/minors"); keep the first one the host's community
+      # list also has, else "other" (or the list's first entry, for a host whose list
+      # has no "other").
+      def escalation_category
+        allowed = Moderate::Report.report_categories
+        top_level = Array(flag.categories).map { |category| category.to_s.split("/").first }
+        found = top_level.find { |category| allowed.include?(category) }
+        found || (allowed.include?("other") ? "other" : allowed.first)
+      end
+
+      def audit_decision(status, note, report)
         Moderate.audit(
           :flag_decision,
           subject: flag,
@@ -81,8 +223,10 @@ module Moderate
             flaggable_type: flag.flaggable_type,
             flaggable_id: flag.flaggable_id,
             field: flag.field,
+            field_label: flag.field_label,
             source: flag.source,
             categories: flag.categories,
+            report_id: report&.id,
             note: note,
             summary: "Flag ##{flag.id} #{status} by moderator"
           }.compact
@@ -96,6 +240,10 @@ module Moderate
         flag.errors.add(:resolution_note, :blank)
         raise ActiveRecord::RecordInvalid, flag
       end
+
+      def truthy?(value)
+        ActiveModel::Type::Boolean.new.cast(value) || false
+      end
     end
   end
 end