moderate 1.0.0.beta2 → 1.0.0

data/docs/chats.md

@@ -0,0 +1,140 @@
+# Trust & Safety for [`chats`](https://github.com/rameerez/chats): report, block and filter messages
+
+Messages between users are user-generated content. App Store Guideline 1.2, Google Play's UGC policy and the EU DSA all expect people to be able to **report** a message, **block** its sender, and the app to **filter** and **moderate** what's said. `chats` and `moderate` were built for each other, with no hard dependency either way. `chats` already speaks moderate's reportable contract, so the integration is a handful of lines in your app.
+
+This is the moderate side of the recipe. It is the shape two production apps (CarHey and playscbw) converged on. chats' own README covers its half: the [Trust & Safety section](https://github.com/rameerez/chats#%EF%B8%8F-trust--safety-snaps-onto-the-moderate-gem).
+
+## What chats already answers
+
+`Chats::Message` (and `Chats::Conversation`) implement moderate's duck-typed reportable contract themselves:
+
+| moderate asks | chats answers |
+|---|---|
+| `reported_owner` | `author \|\| sender`: the person who wrote it. For an unsigned support-desk reply that's the desk, which moderate treats as "nobody to reach" (`Moderate.responsible_user`): the report still files and the content can still be removed. There's nothing to override. |
+| `moderation_snapshot(:body)` | the body, frozen into the report as evidence |
+| `remove_reported_field!(:body)` | the soft-delete tombstone ("Message deleted"), which also works in a locked conversation |
+| `report_visible_to?(viewer)` | participants only, never the author. moderate enforces it when the report is filed, not only when the link renders. |
+| `moderation_content_type` | `"message"` (`"group"` for a conversation), stored on the report |
+
+## 1. Make messages reportable and filtered
+
+In an after-boot hook, so a code reload re-applies the macros to the engine's model:
+
+```ruby
+# config/initializers/chats_moderation.rb
+Rails.application.config.to_prepare do
+  Chats::Message.has_reportable_content :body, labels: { body: "Message" }
+  Chats::Message.moderates :body, mode: :flag
+  # with attachments on:
+  # Chats::Message.has_reportable_content :body, :files, labels: { body: "Message", files: "Photo" }
+  # Chats::Message.moderates :files, mode: :flag, with: :your_image_adapter
+end
+```
+
+- **`:flag`, never `:block`.** A wordlist false positive must not gag someone mid-conversation. The message sends, and a pending `Moderate::Flag` lands in the queue.
+- **Declare each filter once.** `moderates :body, mode: :flag` and `config.filter "Chats::Message", :body, mode: :flag` write the same policy. Keep one of them; the macro next to `has_reportable_content` reads best.
+- **`labels:`** is what the queue, the statement of reasons and the appeal page call the field. Without it they print "Text" (the gem's generic label for `body`).
+
+## 2. Blocks are moderate's, everywhere chats decides something
+
+```ruby
+# config/initializers/chats.rb
+config.blocked_messager_ids = ->(messager) { messager.is_a?(User) ? Moderate.blocked_ids_for(messager) : [] }
+```
+
+A blocked pair can't open a conversation or send into one, and their direct thread leaves both inboxes. The thread is hidden, never deleted: unblocking brings it back. Group conversations are exempt from pair blocks. The `is_a?(User)` guard keeps non-person messagers (a support desk) out of the block table.
+
+`Moderate.blocked_ids_for` always returns a relation of user ids, which chats turns into a subquery. If you compose it with ids of your own, call `.ids` first: `relation | array` gives you User records, not ids.
+
+## 3. Report on a bubble
+
+chats renders each bubble **once per broadcast** and shares it with every viewer, so the bubble can't ask who is looking. That rules out `moderate_report_link`, whose per-viewer check would vanish from live bubbles. Use the viewer-agnostic path in chats' `message_meta` slot, and hide the link on your own bubbles client-side:
+
+```erb
+<%# app/views/chats/slots/_message_meta.html.erb %>
+<% if message.sender && !message.deleted? %>
+  <%= link_to t("messages.report"), moderate_report_target_path(message, field: :body), class: "chats-report" %>
+<% end %>
+```
+
+```css
+.chats-message--own .chats-report { display: none; } /* cosmetic: the server refuses it anyway */
+```
+
+`moderate_report_target_path` builds your report form's path (`new_report_path`, or `new_moderate_report_path`, found through `main_app` from inside chats' views) with a signed, non-expiring target (`message.to_moderation_sgid`), so the URL is identical on every render. If your route has another name, build it yourself: `main_app.new_abuse_report_path(target: message.to_moderation_sgid, field: "body")`. Hiding the link is cosmetic. When the report is filed, moderate refuses anyone `report_visible_to?` rejects (a non-participant, the author) with an error on `:reportable`.
+
+Your `ReportsController` stays yours (moderate is UI-agnostic):
+
+```ruby
+def create
+  reportable = Moderate::Report.locate_signed_reportable(params[:target]) or return head(:not_found)
+  current_user.report!(reportable, category: params.dig(:report, :category), details: params.dig(:report, :message),
+                       field: params[:field], block: params.dig(:report, :block) == "1")
+  redirect_back fallback_location: root_path, notice: t(".filed")
+rescue ActiveRecord::RecordInvalid => error
+  # …render the form with error.record.errors
+end
+```
+
+- **The category select:** `f.select :category, Moderate::Report.category_options`. It honors `config.report_categories` and prints labels in the reader's language (English and Spanish ship with the gem).
+- **"Report and block":** `block: true` blocks the message's author once the report is filed.
+
+## 4. Block from the thread menu
+
+Put a Block action in chats' `conversation_header_actions` slot, posting to a small controller of yours. Blocking hides the very thread the user is standing in, so land on the inbox, not back:
+
+```ruby
+class BlocksController < ApplicationController
+  before_action :authenticate_user!
+
+  def create
+    current_user.block!(User.find(params[:user_id]))
+    redirect_to chats.root_path, status: :see_other
+  end
+
+  def destroy
+    other = User.find(params[:user_id])
+    current_user.unblock!(other)
+    redirect_to profile_path(other), status: :see_other # there's no thread to go back to while blocked
+  end
+end
+```
+
+If your inbox badges or notification bell should catch up on both players' screens when a block is placed or lifted, do it from moderate's `user_blocked` / `user_unblocked` events rather than from the controller. They fire after the block commits, and also for blocks placed elsewhere (`report!(…, block: true)`, a console):
+
+```ruby
+# config/initializers/moderate.rb
+config.notify = lambda do |event|
+  case event.name
+  when :user_blocked, :user_unblocked
+    InboxSettler.call(event.subject.blocker, event.subject.blocked) # your code, refreshing both sides
+  end
+  # …
+end
+```
+
+## 5. The admin side
+
+Reports and flags about messages land in moderate's queues (`Moderate::Report.pending`, `Moderate::Flag.pending`) with no chat-specific branches:
+
+- **Open the message in context.** Define `moderation_admin_path(routes)` on `Chats::Message`, in the same `to_prepare`, pointing at your admin transcript, anchored at the line.
+- **Decide.** `include Moderate::Moderation` in your admin's reports and flags controllers (see [the madmin guide](madmin.md)). Resolving with `remove_content` removes the message through chats' tombstone. On a flag, `remove_content` / `ban_user` escalate to a report, so the author gets the statement of reasons and the appeal window. A ban needs `config.ban_handler`.
+- **"Flag for review" from the transcript:**
+
+  ```ruby
+  flag = Moderate::Flag.flag_for_review!(message, field: :body, by: current_user)
+  flag.previously_new_record? # => false when one was already waiting
+  ```
+
+  At most one flag is pending per message and field, and the database enforces it, so two moderators pressing it at once file one flag: the second gets the first's. Skip deleted or system messages yourself; there's nothing left to review.
+
+## Launch checklist
+
+- [ ] `Chats::Message.has_reportable_content :body` (and `:files`), with `labels:`
+- [ ] one `:flag` filter per field (macro *or* `config.filter`, not both)
+- [ ] `config.blocked_messager_ids` → `Moderate.blocked_ids_for`, for people only
+- [ ] Report on every bubble via `moderate_report_target_path`, hidden on your own
+- [ ] Block in the thread menu, landing on the inbox; Unblock where the person still is (their profile)
+- [ ] `moderation_admin_path` on `Chats::Message`
+- [ ] admin decisions wired (`Moderate::Moderation`), and `config.ban_handler` set before anyone can press "ban"
+- [ ] `config.notify` for at least `report_received`, `report_decision`, `affected_user_decision` (see [notifications](notifications.md))

data/docs/compliance.md

@@ -64,7 +64,7 @@ The statement must include, at minimum: the **restriction imposed** (and its sco
 | State the **specific restriction** imposed and its scope (content removed? account suspended?). | Every resolution records its action (`remove_content:`, `ban_user:`) and emits `affected_user_decision` with that action in `event.payload`. | **[gem]** | `test/services/moderate/resolve_report_test.rb` |
 | State the **facts and circumstances** relied on. | The immutable **evidence snapshot** taken at report time travels with the decision; the moderator's mandatory `note:` is the human-readable ground. | **[gem]** | `test/models/moderate/report_test.rb` |
 | State whether **automated means** were used in detection or decision — Art. 17(3)(c). | Reports/flags carry their `source` (`text_filter`, `image_filter`, `external_classifier`, or `manual`). A decision acting on an auto-`Moderate::Flag` is flagged as automated-means in the `affected_user_decision` payload; a human report is not. | **[gem]** | `test/services/moderate/resolve_report_test.rb` |
-| State the **legal or contractual ground**. | For DSA notices, the `legal_reason` (from `Moderate::DSA_LEGAL_REASONS`) is the legal ground; for in-app reports, the community `category` + your `note:` is the contractual (terms-of-service) ground. Both ride in the decision payload. | **[gem + you]** | `test/services/moderate/resolve_report_test.rb` |
+| State the **legal or contractual ground**. | For DSA notices, the `legal_reason` (from `Moderate::Report::DSA_LEGAL_REASONS`) is the legal ground; for in-app reports, the community `category` + your `note:` is the contractual (terms-of-service) ground. Both ride in the decision payload. | **[gem + you]** | `test/services/moderate/resolve_report_test.rb` |
 | Communicate **redress** options (internal complaint, out-of-court, judicial). | The `affected_user_decision` event carries the appeal entry point; you render the redress text in your decision email (the gem ships the data; the copy is yours, because it names your jurisdiction). | **[gem + you]** | `test/services/moderate/resolve_report_test.rb` |
 | Deliver the statement to the **affected recipient** (the content owner), not just the reporter. | Two distinct events fire: `report_decision` → the **reporter**; `affected_user_decision` → the **content owner** (resolved via the reportable's `reported_owner`). You wire both. | **[gem + you]** | `test/services/moderate/resolve_report_test.rb` |
 
@@ -79,7 +79,7 @@ The statement must include, at minimum: the **restriction imposed** (and its sco
 | --- | --- | --- | --- |
 | An **internal** appeal mechanism against moderation decisions. | `Moderate::Appeal` — a complaint filed against a resolved report/notice; the queue is `Moderate::Appeal.pending`. | **[gem]** | `test/models/moderate/appeal_test.rb` |
 | **Free of charge.** | There is no charge anywhere in the appeal path — it's just a record + a queue. (You simply don't bill for it.) | **[gem]** | n/a (no payment code exists in the path) |
-| Open for **at least six months** after the decision. | Each report stores its **appeal window**; the gem's default window is **6 months** and `Moderate::Appeal` refuses to open against a decision whose window has closed. | **[gem]** | `test/models/moderate/appeal_test.rb` |
+| Open for **at least six months**, counted from the day the person **is informed** of the decision (Art. 20(2)). | Each report stores its **appeal window** (`appeal_deadline_at`): six months from the decision (a minimum: the notice says "at least until"), moved to six months from delivery when your notifier confirms the notice actually went out (`Moderate.delivered!`, which stamps `decision_notified_at` / `affected_user_notified_at` once), never earlier. A queued mail doesn't count. `Moderate::Appeal` refuses a complaint filed after it; one filed in time is decided whenever the review ends. | **[gem]** | `test/models/moderate/appeal_window_test.rb`, `test/models/moderate/appeal_test.rb` |
 | Decisions **reversible** — uphold the complaint and reverse the action. | `appeal.uphold!(by:, note:)` overturns the original decision (and runs the reverse enforcement); `appeal.reject!(by:, note:)` confirms it. | **[gem]** | `test/services/moderate/resolve_appeal_test.rb` |
 | **Not solely automated** — a human decides the complaint. | `uphold!`/`reject!` **require** a `by:` moderator and a `note:`; there is no path to auto-decide an appeal. | **[gem]** | `test/services/moderate/resolve_appeal_test.rb` |
 | Inform the complainant of the **appeal decision** and remaining redress (out-of-court / judicial). | Resolving an appeal emits `appeal_decision` to the complainant; you render the out-of-court / judicial redress copy. | **[gem + you]** | `test/services/moderate/resolve_appeal_test.rb` |
@@ -98,7 +98,7 @@ The statement must include, at minimum: the **restriction imposed** (and its sco
 | **Publish** the report (at least annually). | The gem produces the numbers; **you** publish them (a `/transparency` page, a PDF, whatever) — only you know your reporting period and format. | **[you]** | manual: render `Moderate.transparency(from:, to:)` |
 
 > [!TIP]
-> `Moderate.transparency(from: 1.year.ago, to: Time.current)` returns a plain hash you can drop straight into a view, a JSON endpoint, or a rake task that emails it to you each January. The counters are the regulator-aligned ones — same taxonomy as the notice form (`Moderate::DSA_LEGAL_REASONS`) — so the published numbers line up with the intake.
+> `Moderate.transparency(from: 1.year.ago, to: Time.current)` returns a plain hash you can drop straight into a view, a JSON endpoint, or a rake task that emails it to you each January. The counters are the regulator-aligned ones — same taxonomy as the notice form (`Moderate::Report::DSA_LEGAL_REASONS`) — so the published numbers line up with the intake.
 
 ---
 
@@ -162,6 +162,7 @@ If you read nothing else, this is the table that says "we did the thing."
 | **Play UGC** | Report + block, **users and content** | `report!`/`block!` on users; reportable + `blocked_ids_for` on content | ✅ gem |
 | **Play UGC** | Ongoing moderation surface | `Flag.pending` + `:flag`-mode filtering | ✅ gem (you review) |
 | **Play UGC** | Accept terms before UGC | your onboarding gate | ⬜ you (categories align) |
+| **GDPR Art. 5(1)(e)** | Don't keep personal data longer than needed | `Moderate.purge` (opt-in, keeps decisions; see [Retention](#5-retention-what-moderate-keeps-and-for-how-long)) | ✅ gem (you schedule it) |
 
 Legend: **✅ gem** — the mechanism ships and is tested. **⬜ you** — your operational/policy step that the gem makes straightforward.
 
@@ -170,6 +171,94 @@ Legend: **✅ gem** — the mechanism ships and is tested. **⬜ you** — your
 
 ---
 
+## 5. Retention: what `moderate` keeps, and for how long
+
+**Out of the box, nothing is purged.** The gem never deletes or redacts a moderation record on its own: every report, notice, flag, appeal and block stays exactly as it was written until you remove it, or until you schedule the opt-in purge below. That is a safe default for evidence and an unsafe one for privacy, so decide on a retention period and wire the purge before you launch in the EU.
+
+### What the gem stores
+
+| Table | What a row holds | Personal data in it |
+| --- | --- | --- |
+| `moderate_reports` | An in-app report or a DSA notice: category, legal ground, member state, content type; the reporter's message; an **evidence snapshot** (a copy of the reported text, the reported URLs, the reported account identifier, taken at intake so it survives edits); the **decision** (status, basis, actions, moderator note, decision visibility, automated-means disclosure, appeal deadline, notification timestamps); which earlier decision removed its content while it was pending (`covered_by_report_id`). | reporter, reported user, notifier name and email, message, snapshot, URLs |
+| `moderate_flags` | A filter, classifier or manual flag: source, mode, categories, scores; an **excerpt** of the content (up to 500 characters); **context** (the classifier's raw response, a reviewer's note); the review. | owner, excerpt, context |
+| `moderate_appeals` | An Art. 20 complaint: the reason, the appellant's name and email, a snapshot of the decision appealed, the outcome and its note. | appellant, name, email, reason |
+| `moderate_blocks` | One blocker → blocked edge and when it was made. | both people |
+| `moderate_classifications` | Bookkeeping for attachment classification: which record and field, a digest of the attached blob ids, who is classifying it (a claim) and when it was classified, the adapter and whether it flagged. | none beyond the record's id |
+
+**Notices** (receipts, statements of reasons, appeal decisions) are not stored by the gem: it emits events and your mailer sends them. It only stamps when your notifier confirms one went out (`Moderate.delivered!`: `decision_notified_at`, `affected_user_notified_at`). Whatever your mailer or `config.audit` keeps is yours to retain or purge.
+
+Rows go away by themselves only through ordinary associations: deleting a user destroys their blocks and nullifies them as reporter or reported user on reports (`Moderate::Actor`); deleting reported content nullifies the report's pointer to it (the evidence snapshot stays).
+
+### What the law expects, in plain words
+
+Not legal advice, and your national law and your own policies may add to it:
+
+- **Keep the decision and its evidence while it can be challenged.** A decision must stay appealable for at least six months (DSA Art. 20), an appeal filed in time is decided whenever the review ends, and afterwards the person may still take it to an out-of-court dispute settlement body (Art. 21) or a court.
+- **Keep the decision itself for longer.** It is the statement of reasons (Art. 17); it is what a repeat-misuse policy (Art. 23: suspending people who frequently post manifestly illegal content) looks back on; and the annual transparency report (Art. 15, 24) counts notices, actions, automated means, complaints and handling times for a whole reporting period, published after it ends.
+- **Don't keep the personal data longer than that purpose needs** (GDPR Art. 5(1)(c) and (e): data minimisation, storage limitation). The copy of the reported content, the notifier's contact details and the complaint text have done their job once the decision can no longer be challenged. A person may ask for erasure (GDPR Art. 17); the exceptions for legal obligations and legal claims (Art. 17(3)(b) and (e)) are what let you keep a decision that is still contestable.
+
+So: content copies and contact details get a short life, decisions and counts a long one. That split is what the purge implements.
+
+### `Moderate.purge`: opt in
+
+```ruby
+Moderate.purge(older_than: 1.year)
+# => { reports: 12, flags: 40, appeals: 1, classifications: 300, claims_kept: 0,
+#      held: { reports: 1, flags: 2, appeals: 0 } }
+Moderate.purge(older_than: 18.months, dry_run: true) # the same counts, changes nothing
+```
+
+**`1.year` is a default, not a rule.** GDPR storage limitation asks for a period set by *your* purposes (how long a decision can be challenged where you operate, your repeat-misuse policy, your national rules), so set `older_than` to the period your privacy policy states; the gem only refuses one shorter than the six-month appeal window.
+
+```bash
+bin/rails moderate:purge                              # OLDER_THAN_DAYS=365 by default
+bin/rails moderate:purge OLDER_THAN_DAYS=540 DRY_RUN=1
+```
+
+Schedule it like any recurring job (cron, `config/recurring.yml` for Solid Queue, `sidekiq-cron`): `Moderate.purge` is safe to run every night. The rake task prints what it redacted and what it kept for a legal hold.
+
+**Legal holds.** When a decision is under external redress (an out-of-court dispute settlement body, DSA Art. 21; a court case; an authority's request), hold that report and the nightly purge leaves it, its appeals and the flags on its content alone until the date you give:
+
+```ruby
+Moderate.hold(report, until: 1.year.from_now, by: admin, reason: "ODS case 2026-114")
+report.held?                                # => true
+Moderate.release_hold(report, by: admin)    # the dispute ended; the next purge treats it normally
+```
+
+Holding again moves the date; a hold that expires lifts itself. Both are audited (`:legal_hold_placed`, `:legal_hold_released`), and `dry_run` counts held rows under `:held` so you can see what a hold is keeping.
+
+| It redacts | Only when | It keeps |
+| --- | --- | --- |
+| **Reports and notices**: the message (→ `"[redacted]"`), the evidence snapshot, the reported URLs and account identifier, the notifier's name and email, the reporter. | The report is closed, was decided more than `older_than` ago, its appeal window has closed, no appeal on it is open, and it isn't held. | Every row; category, legal ground, member state, content type, status, timestamps; the whole decision (basis, actions, note, visibility, automated-means disclosure); the reported user. |
+| **Flags**: the excerpt (→ `"[redacted]"`) and the context. | The flag was decided more than `older_than` ago, and no held report is about its content and field. | Every row; source, mode, categories, scores, status, the owner, the review. |
+| **Appeals**: the reason (→ `"[redacted]"`) and the appellant's name and email. | The appeal was decided more than `older_than` ago, and its report isn't held. | Every row; status, outcome note, timestamps, the appellant's account. |
+| **Classification rows** (`moderate_classifications`): deleted, not redacted (nothing in them is evidence). | Last touched more than `older_than` ago, and not under a live claim (a worker classifying those files right now; counted under `:claims_kept`). | — |
+
+Guarantees, each with a test in `test/models/moderate/retention_test.rb`:
+
+- **Never** a pending report, flag or appeal, a report still inside its appeal window, a report with an open appeal, or anything a legal hold keeps, whatever their age. `older_than` below the six-month appeal window raises.
+- A redacted row is stamped `redacted_at`, and the purge selects on that column, never on the content: a message that literally reads `"[redacted]"` is purged like any other.
+- `Moderate.transparency` returns the same numbers before and after a purge, so a published report stays reproducible.
+- **Blocks are never touched**: they are live safety state, not a record of the past.
+- Idempotent (a second run finds nothing to do), `dry_run: true` only counts, and a run that changed something is audited as `:retention_purged` with the counts and the cutoff.
+- One `UPDATE` per batch of 500, with no callbacks or validations: a redacted DSA notice no longer has the notifier details its validations require, and a final record should not be re-saved.
+
+What it does **not** do, on purpose:
+
+- **Delete rows.** The default `1.year` keeps every decision forever, as pseudonymous rows that still name the reported account. If your policy says decisions go after N years, delete them yourself once the transparency report that counts them is published: `Moderate::Report.where.not(status: "open").where(resolved_at: ...N.years.ago).destroy_all` (appeals go with their report).
+- **Answer an erasure request.** Whether a given person's records must go now, or can be kept for a legal claim, is a decision for you and your counsel; the records are plain Active Record (`Moderate::Report.where(reporter: user)`, `Moderate::Appeal.where(appellant_email: email)`, `Moderate::Flag.where(owner: user)`).
+- **Know about disputes by itself.** The gem can't see an out-of-court or court case; when one starts, `Moderate.hold` the report.
+
+| Requirement | How `moderate` satisfies it | Who | Proof |
+| --- | --- | --- | --- |
+| Keep decisions contestable for ≥ 6 months (Art. 20) and while an appeal is open. | `Moderate.purge` never touches a record inside its appeal window or with an open appeal, and refuses an `older_than` below it. | **[gem]** | `test/models/moderate/retention_test.rb` |
+| Keep what the annual transparency report counts (Art. 15, 24). | Redaction keeps every row and every counted column; `Moderate.transparency` is unchanged by a purge. | **[gem]** | `test/models/moderate/retention_test.rb` |
+| Storage limitation for personal data (GDPR Art. 5(1)(e)). | `Moderate.purge` / `moderate:purge` redacts content copies and contact details from final records. | **[gem + you]** schedule it, choose `older_than` | `test/models/moderate/retention_test.rb` |
+| Keep evidence during external redress (Art. 21, courts, authorities). | `Moderate.hold(report, until:)` keeps the report, its appeals and the flags on its content out of the purge. | **[gem + you]** place the hold | `test/models/moderate/retention_test.rb` |
+| A written retention period, erasure requests. | Out of scope for a gem: your privacy policy and your counsel decide (`older_than` is yours to set). | **[you]** | manual |
+
+---
+
 ## See also
 
 - [`docs/dsa-notice-form.md`](dsa-notice-form.md) — the public Art. 16 notice form, in depth (mount, fields, Turnstile gate, the `moderate:views` eject)

data/docs/configuration.md

@@ -249,7 +249,7 @@ end
 Called for **every notifiable event**. One hook drives them all — `goodmail` for user emails, `telegrama` for admin alerts, `noticed` for in-app feed + push — because every event shares the same envelope. The full vocabulary:
 
 ```
-report_received   report_decision   affected_user_decision
+report_received   notice_received   report_decision   affected_user_decision
 appeal_received   appeal_decision
 user_blocked      user_unblocked    user_banned
 content_flagged   content_removed
@@ -272,7 +272,17 @@ Optional teardown when one user blocks another — cancel a pending invite, leav
 config.ban_handler = ->(user:, by:, reason:) { user.suspend!(reason: reason) }
 ```
 
-`moderate` doesn't own your user lifecycle, so it **never bans a user itself**. When a moderator resolves a report with `ban_user: true` (see [the madmin queue](madmin.md#step-3--the-controller-call-the-gems-decision-methods)), this proc decides what "banned" means in your domain — `suspend!`, soft-delete, flip a flag, revoke sessions, whatever. Signature is **keyword args** (`user:`, `by:`, `reason:`). No-op by default — the decision still audits and notifies even if you haven't wired a ban yet, so you're never silently dropping the action.
+`moderate` doesn't own your user lifecycle, so it **never bans a user itself**. When a moderator resolves a report with `ban_user: true` (see [the madmin queue](madmin.md#step-3--the-controller-call-the-gems-decision-methods)), this proc decides what "banned" means in your domain — `suspend!`, soft-delete, flip a flag, revoke sessions, whatever. Signature is **keyword args** (`user:`, `by:`, `reason:`).
+
+Leave it unset and everything works except a ban: `ban_user: true` (on a report or a flag) and `Moderate.apply_ban` raise `Moderate::ConfigurationError` before anything changes. A ban nothing applies would still audit `user_banned` and send the person a statement of reasons saying their account was suspended, which is a false statement, so the gem refuses it instead. Assigning `nil` puts the default back.
+
+### `banned` — is this person banned right now?
+
+```ruby
+config.banned = ->(user) { user.suspended? }   # optional; set it if your app can unban
+```
+
+One ban per person per episode: a second ban decision on someone a decision in the same episode already banned is recorded as covered by that one (`resolution_actions["ban_already_applied_by"]`), and the `ban_handler` isn't called twice. That only holds while the account is still banned. If your app can lift a ban (an admin unbans, a suspension expires), set `banned`: when it returns false, the earlier ban no longer covers the new decision and the `ban_handler` runs again, so the "account suspended" statement of reasons is true. Unset, the earlier ban counts, whatever happened since.
 
 ---
 
@@ -286,6 +296,24 @@ config.locale = :en   # default: your app's I18n.default_locale
 
 The locale for copy `moderate` generates on its own — filter validation messages, the DSA statement-of-reasons taxonomy labels, the notice-form strings. Leave it unset to follow `I18n.default_locale`.
 
+### `migration_copies_check`
+
+```ruby
+config.migration_copies_check = :raise   # default; or :log, or :off
+```
+
+An app that holds copies of the gem's migrations (`*.moderate.rb`, from `rails generate moderate:install` or `bin/rails moderate:install:migrations`) runs only those copies, so a release whose new migration you didn't copy would never run it. At boot `moderate` compares your copies with its migrations by name: if one is missing it raises `Moderate::ConfigurationError` naming it and the command that copies it (`bin/rails moderate:install:migrations`, then `bin/rails db:migrate`). Under a rake task it logs instead, so that command can run. `:log` always logs (to `Rails.logger` and stderr); `:off` skips the check. An app without copies is never checked: it gets the gem's migrations through the engine.
+
+### `classification_claim_ttl`
+
+```ruby
+config.classification_claim_ttl = 10.minutes   # default (600 seconds)
+```
+
+How long one worker's claim on a set of attached files lasts. An attachment is classified by whoever claims it first (the inline path, the immediate `ClassifyJob` or the after-upload guard); the others see the live claim and stop, and the adapter runs outside any lock. Make it longer than your slowest adapter call: a claim that expires mid-call lets another worker classify the same files, and the first result is then discarded. When a worker dies mid-call, the files wait this long before a job takes them over. It must be more than 0 and at most a day; anything else raises at boot.
+
+An adapter that **raises** leaves its claim in place until it expires, and the failure doesn't schedule a retry by itself. A later attempt takes the files over: the after-upload guard job, a job's single recheck at the claim's expiry, the next save of that field, or your job backend retrying the same job (it keeps its job id, so the claim is still its own). `Moderate.purge` never deletes a row whose claim is live, whatever its age (`:claims_kept` in its counts).
+
 ---
 
 ## How the macros relate to config

data/docs/dsa-notice-form.md

@@ -250,7 +250,7 @@ off the public form's bot gate.
 
 #### The rate-limit hook
 
-On Rails 7.2+ you could use the built-in `rate_limit` API; `moderate` instead implements a tiny per-IP, cache-backed counter (`Rails.cache`) as a `before_action`, so it honors your **runtime** `config.notice_rate_limit` (the class-level macro is evaluated at class load, before your initializer has run). Configure it once:
+You could use Rails' built-in `rate_limit` API; `moderate` instead implements a tiny per-IP, cache-backed counter (`Rails.cache`) as a `before_action`, so it honors your **runtime** `config.notice_rate_limit` (the class-level macro is evaluated at class load, before your initializer has run). Configure it once:
 
 ```ruby
 config.notice_rate_limit = { max: 5, within: 1.hour }   # default

data/docs/madmin.md

@@ -100,15 +100,17 @@ class Moderate::ReportResource < Madmin::Resource
   # Everything is read-only (form: false): decisions go through the custom
   # member actions below, never through madmin's stock edit form.
   attribute :id,          index: true, form: false
-  attribute :status,      index: true, form: false   # pending / resolved / dismissed
-  attribute :kind,        index: true, form: false   # "report" (in-app) or "dsa_notice"
+  attribute :status,      index: true, form: false   # open / actioned / dismissed
+  attribute :intake_kind, index: true, form: false   # "community" (in-app) or "dsa" (a public notice)
   attribute :category,    index: true, form: false   # community category OR DSA legal_reason
   attribute :reportable,  :polymorphic, index: true, form: false, label: "Target"
-  attribute :reported_field, index: true, form: false, label: "Field"
+  # The field's human label ("Chat message"), not the raw column ("body") — see
+  # `labels:` on has_reportable_content. A virtual attribute, so it needs a type.
+  attribute :reported_field_label, :string, index: true, form: false, label: "Field"
   attribute :reported_user,  index: true, form: false
   attribute :reporter,       index: true, form: false
   attribute :notifier_email, index: true, form: false, label: "Notifier"  # DSA notices
-  attribute :details,        index: false, form: false
+  attribute :message,        index: false, form: false, label: "Reason"   # what the reporter wrote
   attribute :snapshot,       index: false, form: false   # the immutable evidence snapshot
   attribute :resolution_note, index: false, form: false
   attribute :created_at,  index: true, form: false, label: "Received"
@@ -116,7 +118,7 @@ class Moderate::ReportResource < Madmin::Resource
 
   # Queue scopes — these are the gem's own scopes, surfaced as madmin filters.
   scope :pending
-  scope :resolved
+  scope :actioned
   scope :dismissed
 
   menu label: "Reports", parent: "Trust & Safety"
@@ -135,10 +137,10 @@ class Moderate::FlagResource < Madmin::Resource
   model Moderate::Flag
 
   attribute :id,         index: true, form: false
-  attribute :status,     index: true, form: false   # pending / resolved / dismissed
+  attribute :status,     index: true, form: false   # pending / actioned / dismissed
   attribute :source,     index: true, form: false   # wordlist / image / <your adapter> / manual
   attribute :flaggable,  :polymorphic, index: true, form: false, label: "Target"
-  attribute :field,      index: true, form: false
+  attribute :field_label, :string, index: true, form: false, label: "Field"   # "Chat message", not "body"
   attribute :owner,      index: true, form: false
   attribute :categories, index: false, form: false  # e.g. [:hate, :threats]
   attribute :scores,     index: false, form: false  # { hate: 1.0 } (0..1 for ML adapters)
@@ -147,7 +149,7 @@ class Moderate::FlagResource < Madmin::Resource
   attribute :reviewed_at, index: true, form: false
 
   scope :pending
-  scope :resolved
+  scope :actioned
   scope :dismissed
 
   menu label: "Flags", parent: "Trust & Safety"
@@ -296,8 +298,14 @@ end
 # app/controllers/madmin/flags_controller.rb
 module Madmin
   class FlagsController < Madmin::ResourceController
+    # Without the checkboxes this only triages the flag. With either, the flag
+    # escalates to a report (the open one on the same content, or a system one) and
+    # resolves it: the content goes through your remove_reported_field!, the ban
+    # through your ban_handler, and the author gets the statement of reasons and the
+    # appeal window a restriction requires. `@record.report` is that report after.
     def resolve
-      @record.resolve!(by: current_user, note: params[:note])
+      @record.resolve!(by: current_user, note: params[:note],
+                       remove_content: params[:remove_content], ban_user: params[:ban_user])
       redirect_to main_app.madmin_flag_path(@record), notice: "Flag actioned.", status: :see_other
     rescue => error
       redirect_to main_app.madmin_flag_path(@record), alert: "Could not action flag: #{error.message}", status: :see_other
@@ -379,7 +387,10 @@ Hand-rolling (above) is the right call when your redirects/flashes need to match
   <section>
     <h2>Resolve</h2>
     <%= form_with url: resolve_madmin_report_path(report), method: :post do %>
-      <label><%= check_box_tag :remove_content, "1" %> Remove reported content</label>
+      <% if report.reportable.respond_to?(:removable_reported_field?) && report.reportable.removable_reported_field?(report.reported_field) %>
+        <%# Only where removal can happen: a removal that removes nothing refuses the decision. %>
+        <label><%= check_box_tag :remove_content, "1" %> Remove reported content</label>
+      <% end %>
       <label><%= check_box_tag :ban_user, "1" %> Ban reported user</label>
       <%= text_area_tag :note, nil, placeholder: "Decision note", required: true %>
       <%= submit_tag "Resolve", data: { turbo_confirm: "Resolve and notify the parties?" } %>
@@ -414,11 +425,29 @@ The appeal show view is the same shape with `uphold`/`reject`:
 
 Two details worth copying:
 
+- **Resolve needs an action.** A report's `resolve!` with neither `remove_content` nor `ban_user` ticked is refused (the flash says why): it would tell the author a restriction was imposed when none was. Offer "Dismiss" for a decision that restricts nothing.
 - **Gate on `pending?`.** Show the decision forms only while the record is open; render "closed" once it isn't. The decision methods are also guarded server-side (calling `resolve!` on an already-resolved report raises), but hiding the buttons is the better UX.
 - **Require the note.** `required: true` on the textarea, and the gem requires it too — every decision must carry a rationale (that's what feeds the DSA Art. 17 statement of reasons). Belt and suspenders.
 
 The evidence snapshot (`report.snapshot`) is plain JSON on the record — render it in a `<pre>` so the moderator sees exactly what was reported, even if the original content was since edited or deleted. That immutability is the whole point of the snapshot.
 
+The flag show view is the report's, pointed at the flag routes: the same two checkboxes on `resolve` (each escalates the flag to a report, see the controller above), and `dismiss`. Print labels, not stored values: `Moderate.taxonomy_label(:flag_status, flag.status)`, `Moderate.taxonomy_label(:flag_source, flag.source)`, `flag.field_label`, and for reports `Moderate.taxonomy_label(:category, report.category)` and `report.reported_field_label`. The gem ships English and Spanish for every value it defines.
+
+### "Flag for review" from a browse screen
+
+Moderators often find bad content while browsing something else: a conversation's transcript, a user's page. Don't grow enforcement buttons there; file the content into the queue, where the decision tools already are:
+
+```ruby
+# app/controllers/madmin/messages_controller.rb
+def flag
+  flag = Moderate::Flag.flag_for_review!(@record, field: :body, by: current_user, note: params[:note])
+  notice = flag.previously_new_record? ? "Filed for review." : "It's already waiting for review."
+  redirect_to main_app.madmin_flag_path(flag), notice: notice, status: :see_other
+end
+```
+
+`flag_for_review!` files a `source: "manual"` flag owned by the content's person, or returns the one already waiting on that field. At most one flag is pending per content and field, and the database enforces it (a unique index), so two moderators pressing it at once file one flag: the second gets the first's.
+
 ---
 
 ## The moderation-queue pattern (the index)
@@ -456,14 +485,15 @@ The headline trick of the model design: **a human admin and an ML/automation con
 class AutoModerationJob < ApplicationJob
   def perform
     Moderate::Flag.pending.find_each do |flag|
-      next unless flag.scores[:csam].to_f >= 0.99   # only the unambiguous ones
-      flag.resolve!(by: Moderate.system_actor, note: "Auto-removed: high-confidence CSAM")
+      next unless flag.scores["sexual/minors"].to_f >= 0.99   # only the unambiguous ones
+      # `by: nil`: an automated decision is never attributed to a person who didn't look.
+      flag.resolve!(by: nil, note: "Removed automatically: high-confidence sexual/minors", remove_content: true)
     end
   end
 end
 ```
 
-Because the job calls `resolve!` (not a raw `update`), the auto-decision is identical to a human one — atomic enforcement, `notify`/`audit` hooks, statement-of-reasons, appeal window. Whatever the job doesn't touch stays in `pending` for a human in madmin. One queue, two consumers, zero divergence.
+Because the job calls `resolve!` (not a raw `update`), the auto-decision is identical to a human one — atomic enforcement, `notify`/`audit` hooks, statement-of-reasons, appeal window. (Declare the automation honestly: a decision taken by a job is "automated means" under DSA Art. 17(3)(c).) Whatever the job doesn't touch stays in `pending` for a human in madmin. One queue, two consumers, zero divergence.
 
 ---
 
@@ -474,7 +504,7 @@ To be explicit about the boundary this guide sits on:
 | `moderate` ships (the primitives) | You build (the UI chrome) |
 | --- | --- |
 | The models (`Report`/`Flag`/`Appeal`/`Block`) | The madmin resources (columns, labels, fields) |
-| The queue scopes (`.pending`, `.resolved`, …) | The index/show screens & nav grouping |
+| The queue scopes (`.pending`, `.actioned`, `.dismissed`, `.recent_first`) | The index/show screens & nav grouping |
 | The decision methods (`resolve!`/`dismiss!`/`uphold!`/`reject!`) — atomic enforcement + notify + audit + appeal window | The buttons/forms that call them |
 | The optional `Moderate::Moderation` controller concern | Auth (`current_user`, admin gate) |
 | Helpers + the evidence snapshot on each record | Your branding, layout, extra columns |

data/docs/notifications.md

@@ -80,7 +80,7 @@ event.to_h        # the whole envelope as a Hash (handy for logging, tests, and
 Two fields do most of the work:
 
 - **`event.recipients`** — already resolved to *the right people* for this event. For `report_received` it's the reporter (their receipt). For `report_decision` it's the reporter (the outcome). For `affected_user_decision` it's the person whose content/account was acted on (their statement of reasons). You don't compute audiences — `moderate` does, and hands you the array. Iterate it.
-- **`event.payload[:summary]`** — a short, human, already-redaction-safe one-liner describing what happened (e.g. `"New harassment report on Comment #4213 by joh…e@example.com"`). It exists so your **admin Telegram ping is literally one line** — no string-building, no leaking. Everything richer (the model, the category, the moderator's note) is also in `payload` if you want to compose your own copy.
+- **`event.payload[:summary]`** — a short, human, already-redaction-safe one-liner describing what happened (e.g. `"New harassment report on Comment #4213 by joh…e@example.com"`). It exists so your **admin Telegram ping is literally one line** — no string-building, no leaking. Everything richer (the model, the category, the moderator's note) is also in `payload` if you want to compose your own copy. Events about a specific field carry both the raw name and its human label (`reported_field` + `reported_field_label` on reports, `field` + `field_label` on flags) — print the label, keep the raw name for code (see [Reportable content](../README.md#-reportable-content)).
 
 A recipient is usually one of your `User` records (it responds to `email`, `id`, etc.), **except** for DSA-notice events (`notice_received`, and the `affected_user_decision` for a public notice) where the notifier may be an anonymous person — there `moderate` gives you a lightweight recipient that responds to `email`/`name` but is **not** a `User`. The `next unless user.respond_to?(:email)` / `user.is_a?(User)` guards in the recipes above handle that cleanly.
 
@@ -137,6 +137,16 @@ end
 class ModerationMailer < ApplicationMailer
   # `event` and `recipient` arrive via `.with(...)` and are available as `params[:event]` / `params[:recipient]`.
 
+  # DSA Art. 20(2): the appeal window runs from when the person was informed. Confirm a
+  # decision notice when it actually leaves, not when deliver_later queued it.
+  after_deliver do
+    event = params[:event]
+    case event&.name
+    when :affected_user_decision then Moderate.delivered!(event.subject, :affected_user)
+    when :report_decision        then Moderate.delivered!(event.subject, :decision)
+    end
+  end
+
   def report_received
     event = params[:event]
     goodmail_mail(to: params[:recipient].email, from: "trust@myapp.com",
@@ -156,11 +166,13 @@ class ModerationMailer < ApplicationMailer
                   subject: "An update about your content") do
       h1 "We took action on your content"
       text event.payload[:reason]                       # the human-readable ground
+      info_row "Content",         event.payload[:reported_field_label] # e.g. "Chat message" (nil for a whole-record report)
       info_row "Action",          event.payload[:action]        # e.g. "Content removed"
       info_row "Automated means", event.payload[:automated] ? "Yes" : "No"
       space
       text "If you believe this was a mistake, you can appeal — it's free and reviewed by a person."
-      button "Appeal this decision", event.payload[:appeal_url] # moderate mints a signed link for you
+      button "Appeal this decision",                    # the engine's appeal form, behind a signed link
+             moderate.new_appeal_url(token: event.subject.signed_appeal_gid, source: "affected_user")
       sign
     end
   end
@@ -183,7 +195,8 @@ Why this shape:
 - **`.with(event:, recipient:)`** is the standard Action Mailer params path, so the same arguments survive `deliver_later` serialization (the event's records are GlobalID-serializable AR objects).
 - **`public_send(event.name)`** lets the *event name* select the mailer action — `report_received` → `#report_received` — so adding a new email is "add a method," not "add a branch."
 - **`goodmail_mail`** is goodmail's mailer helper: it renders the DSL block, wires `List-Unsubscribe`, and hands a normal multipart message to Action Mailer. Use its DSL (`h1`, `text`, `info_row`, `button`, `sign`, …) instead of ERB templates. `info_row`/`price_row` are perfect for the reference/date/action rows a decision email needs.
-- **The appeal link** in a decision email is the signed link `moderate` mints for you (`config.signed_gid_purposes` includes `:appeal`); read it from `event.payload[:appeal_url]` rather than building your own route.
+- **The appeal link** in a decision email points at the engine's appeal form with the report's signed token: `moderate.new_appeal_url(token: event.subject.signed_appeal_gid, source: "affected_user")` (`source: "notifier"` in the reporter's `report_decision` email). The token names only that report and can't be replayed to find anything else; `event.payload[:appeal_deadline_at]` is a minimum: say "you can appeal at least until …".
+- **Confirm delivery with `Moderate.delivered!`** (the `after_deliver` above). A decision notice your hook queued is not one the person has received: the gem stamps `decision_notified_at` / `affected_user_notified_at` only on that confirmation, once, and moves the appeal deadline to six months after it (never earlier). Without it, the deadline stays decision + six months. A notifier that isn't Action Mailer calls it wherever it learns the message went out (a provider webhook, a push receipt).
 
 > [!TIP]
 > Per-product or per-tenant branding? `goodmail_mail` accepts `config: { company_name:, brand_color:, logo_url: }` for a scoped, thread-local override — handy if your app is white-labeled. See goodmail's "Per-message branding."
@@ -351,7 +364,7 @@ Moderate.configure do |config|
 end
 ```
 
-`audit` fires for **every** event (including the silent ones like `user_blocked` that you usually don't notify on), it's append-only by intent, and it's where DSA **Art. 24 transparency counters** ultimately draw from (notices received, actions taken, appeal outcomes). Wire it once next to `notify` and you have both halves: humans get told, history gets kept.
+`audit` fires for every intake, decision, block, ban and removal (including the silent ones like `user_blocked` that you usually don't notify on), plus the gem's own housekeeping: `report_received`, `appeal_received`, `report_decision`, `flag_decision`, `appeal_decision`, `flag_filed`, `user_blocked`, `user_unblocked`, `user_banned`, `content_removed`, `notify_failed`, `classification_skipped`, `retention_purged`, `legal_hold_placed`, `legal_hold_released` (`Moderate::Event::AUDIT_NAMES`). It's append-only by intent, and it's the trail behind the DSA **Art. 24 transparency counters** (notices received, actions taken, appeal outcomes), which `Moderate.transparency` computes from the moderation tables themselves. Wire it once next to `notify` and you have both halves: humans get told, history gets kept.
 
 > [!NOTE]
 > Same envelope (`name` / `subject` / `actor` / `recipients` / `payload` / `to_h`), two destinations. Keep both hooks fast and side-effect-light; push real work (emails, HTTP, heavy writes) to background jobs.

data/examples/aws_rekognition_adapter.rb

@@ -53,13 +53,13 @@ class AwsRekognitionAdapter
   # change that default if a different fallback fits your app.
   CATEGORY_MAP = {
     "Explicit Nudity" => [:sexual, nil],
-    "Sexual"          => [:sexual, nil],
+    "Sexual" => [:sexual, nil],
     "Non-Explicit Nudity of Intimate parts and Kissing" => [:sexual, nil],
-    "Violence"        => [:violence, nil],
-    "Visually Disturbing" => [:violence, :graphic],
-    "Hate Symbols"    => [:hate, nil],
+    "Violence" => [:violence, nil],
+    "Visually Disturbing" => %i[violence graphic],
+    "Hate Symbols" => [:hate, nil],
     "Drugs & Tobacco" => [:illicit, nil],
-    "Gambling"        => [:illicit, nil]
+    "Gambling" => [:illicit, nil]
   }.freeze
 
   def initialize(client: nil)
@@ -89,7 +89,7 @@ class AwsRekognitionAdapter
       source: "image_filter",
       raw: response.to_h
     )
-  rescue => error
+  rescue StandardError => error
     # FAIL OPEN on everything, same rationale as any network classifier: a moderation
     # API is defense-in-depth, not a gatekeeper that should block uploads on an AWS
     # blip. The image simply isn't auto-flagged this time; users can still report it.

data/examples/openai_moderation_adapter.rb

@@ -67,7 +67,7 @@ class OpenAIModerationAdapter
       source: "external_classifier",
       raw: result.results
     )
-  rescue => error
+  rescue StandardError => error
     # FAIL OPEN on EVERYTHING (network error, timeout, auth failure, malformed
     # response, …). A moderation API is best-effort defense-in-depth, not a
     # gatekeeper that should take down user posting when OpenAI has a hiccup — and a