moderate 1.0.0.beta1 → 1.0.0

data/CLAUDE.md

@@ -2,6 +2,6 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Please read the `README.md` for a full overview of the gem's API and philosophy, and the `docs/` directory (`docs/configuration.md`, `docs/notifications.md`, `docs/compliance.md`, `docs/madmin.md`, `docs/dsa-notice-form.md`) for the detailed integration guides.
+Please read the `README.md` for a full overview of the gem's API and philosophy, and the `docs/` directory (`docs/configuration.md`, `docs/notifications.md`, `docs/compliance.md`, `docs/madmin.md`, `docs/dsa-notice-form.md`, `docs/chats.md`) for the detailed integration guides.
 
 This gem is part of a coherent ecosystem (`railsfast`, `goodmail`, `telegrama`, `usage_credits`, `pricing_plans`, `wallets`, `api_keys`). Match the ecosystem conventions exactly: a single `Moderate.configure do |config| … end` block, `has_*`/verb-style class macros, adapter objects + no-op-default hook procs, string class names constantized lazily, adaptive install migrations, Minitest with a `test/dummy` app, SimpleCov, and the README/docs voice.

data/README.md

@@ -11,6 +11,8 @@ Trust & Safety (T&S) is the system within an app that lets users **report** abus
 
 If you have an app where users can upload / generate content or send messages to each other, you probably need a Trust & Safety system.
 
+![Moderate gem sample use case for reporting profiles and blocking users](/docs/images/moderate-user-report-block-actions.webp)
+
 `moderate` ships with mechanisms aligned with the **DSA** (EU Digital Services Act), and also aligned with the **Apple App Store** and Android's **Google Play** directives for User-Generated Content (UGC) in their app stores.
 
 ## 👨‍💻 Example
@@ -64,6 +66,8 @@ That's the whole idea: **the messy, legally-loaded plumbing every social/UGC app
 
 ## Quickstart
 
+`moderate` needs Ruby 3.3+ and Rails 8.0.5.1+ (8.0 and 8.1 are tested), on SQLite, PostgreSQL or MySQL.
+
 Add the gem:
 
 ```ruby
@@ -171,9 +175,18 @@ Post.where.not(user_id: Moderate.blocked_ids_for(current_user))
 ```ruby
 current_user.report!(@message, category: :harassment, details: "Won't stop messaging me")
 current_user.report!(@user,    category: :impersonation)
+current_user.report!(@message, category: :spam, block: true)   # "Report and block"
+```
+
+`moderate` snapshots the offending content at report time (so evidence survives edits/deletes), infers who's responsible, records what kind of content it is (`moderation_content_type`), sends the reporter a receipt, and drops it in the queue. A report is refused when the reporter may not report the content (the reportable's own `report_visible_to?`: never your own content, never a conversation you're not in), whether or not the link was hidden.
+
+Your report form's category select is one line, labeled in the reader's language (the gem ships English and Spanish for every value it defines, and your locale files win):
+
+```erb
+<%= f.select :category, Moderate::Report.category_options %>   <%# honors config.report_categories %>
 ```
 
-`moderate` snapshots the offending content at report time (so evidence survives edits/deletes), infers who's responsible, sends the reporter a receipt, and drops it in the queue.
+`Moderate.taxonomy_label(kind, value)` labels the rest of the gem's vocabulary the same way in your queue: `Moderate.taxonomy_label(:flag_status, flag.status)`, `(:legal_reason, report.legal_reason)`, `(:decision, report.decision_visibility)`, and so on.
 
 ## 🚩 Reportable content
 
@@ -191,6 +204,37 @@ end
 
 *(Explicit-include equivalent: `include Moderate::Reportable` + `reportable_fields :title, :description`.)*
 
+Give each field the name a human should see. Without a label, a report of a chat message reaches your moderators as «Body» and they have to guess what was reported — declare it once, next to the field:
+
+```ruby
+class Message < ApplicationRecord
+  has_reportable_content :body, :files, labels: { body: "Chat message", files: "Chat photo" }
+end
+
+report.reported_field_label                    # => "Chat message"
+flag.field_label                               # => "Chat message"
+Moderate.reportable_field_label(Message, :body) # => "Chat message" (also takes a record, or a "Message" type string)
+```
+
+`moderate` prints the label wherever it names a field — the public appeal page, the statement-of-reasons payload (`reported_field_label`), the `report_received` / `content_flagged` summaries — and keeps the raw name next to it (`reported_field`, `field`) for your code. Labels are optional and per field; each field resolves to the first of:
+
+1. its `labels:` entry — a String, or a lambda evaluated at read time (`-> { I18n.t("chat.message") }`);
+2. `moderate.reportable_fields.<model>.<field>` in your locale files, where `<model>` is the model's `model_name.i18n_key` (`chats/message` for `Chats::Message`; STI children also try their reportable parent);
+3. `moderate.reportable_fields.<field>` — one label for that field name on every model. `moderate` ships `en` and `es` defaults for the common ones (`body` → "Text" / "Texto", `avatar` → "Profile photo" / "Foto de perfil", …), and your locale files override them;
+4. `field.humanize`.
+
+```yaml
+# config/locales/es.yml — the multi-locale way to say the same thing
+es:
+  moderate:
+    reportable_fields:
+      chats/message:
+        body: "Mensaje de chat"
+        files: "Foto de chat"
+```
+
+Model-scoped and field-wide keys share one namespace, so a model whose key matches a field name (`Listing` and a `listing` field) can't also have a field-wide label for that name — scope it to the model instead. A whole-record report has no field, so its label is `nil`.
+
 You get:
 
 ```ruby
@@ -206,6 +250,14 @@ Drop a report link into any view with the helper (it renders nothing if the view
 <%= moderate_report_link(@listing, field: :description) %>
 ```
 
+For markup rendered once and shown to many viewers (a chat bubble broadcast to everyone in the thread, a cached fragment), where the per-viewer check can't run, use the viewer-agnostic path and hide it on the author's own content client-side; the server still refuses a report the viewer may not make:
+
+```erb
+<%= link_to "Report", moderate_report_target_path(message, field: :body) %>   <%# target: message.to_moderation_sgid, never expires %>
+```
+
+Using [`chats`](https://github.com/rameerez/chats) for messages? Its messages already speak this contract; the whole integration is in [`docs/chats.md`](docs/chats.md).
+
 Because `moderate` is UI-agnostic, it does not render a built-in "under review" badge. Use `flagged?` / `flagged?(:field)` to render copy that fits your product when `:flag` mode lets content through but queues it for review.
 
 If your app runs inside Hotwire Native / Turbo Native, remember that native path configuration is host-owned. Add rules for the in-app report routes you mount (for example `/reports/new` **and** the form action `/reports`, so validation errors stay in the same modal stack) and for the engine's public legal routes **and their form actions** such as `<mount>/notices/new`, `<mount>/notices`, `<mount>/appeals/new`, `<mount>/appeals`, and `<mount>/transparency` — where `<mount>` is wherever you mounted `Moderate::Engine` in your routes (it is host-chosen, not fixed). `moderate` can provide the Rails routes; your native shell still decides whether they push, present modally, use a sheet, and which Android `uri` maps to the destination.
@@ -233,6 +285,8 @@ end
 
 Why this matters: `:flag` never lives in a validator (validators must be side-effect-free, and a flag created inside a rolled-back transaction would silently vanish) — `moderate` handles that correctly for you.
 
+**Active Storage attachments** (`has_one_attached` / `has_many_attached`) take the same one line, `moderates :avatar, with: :image, mode: :flag`, and no other wiring. The file is classified once it is on the storage service, never before, whichever of `moderates` and `has_one_attached` you declare first, and a failed upload is never silent. Just before Active Storage uploads, `moderate` queues a `Moderate::ClassifyJob` for 5 seconds later; once the upload returns, it classifies right away (inline for a synchronous adapter, by an immediate job for an async one) if the file is there. Whichever comes first claims the files (a row in the gem's `moderate_classifications` table, written under the content record's row lock, held only for the claim), calls your adapter outside any lock, and marks the row classified; the other sees the claim or the mark and stops. So each set of files is classified once per record (a changed set, or the same file on another record, is classified again), and a slow provider never blocks writes to the content's row. A claim expires after `config.classification_claim_ttl` (10 minutes), so a worker that died mid-call doesn't leave the files unclassified. A file that isn't there (a direct upload still in flight, an upload that raised) is left to the job, which looks again 5, 10, 15 and 20 seconds later, then gives up with a `classification_skipped` audit event instead of handing your adapter a missing file. Under `mode: :block`, an attachment whose direct upload hasn't finished fails validation ("Photo hasn't finished uploading yet", en/es, key `errors.messages.upload_not_finished`) rather than being checked without its file: nothing enters unverified.
+
 Check content directly anywhere:
 
 ```ruby
@@ -294,16 +348,22 @@ Moderate::Appeal.pending             # appeals awaiting a human
 
 report.resolve!(by: admin, remove_content: true, ban_user: false, note: "Removed: hate speech")
 report.dismiss!(by: admin, note: "No violation")
+flag.resolve!(by: admin, note: "Slur", remove_content: true)   # enforces through a report (below)
+flag.dismiss!(by: admin, note: "False positive")
 appeal.uphold!(by: admin, note: "...")   # overturns the decision
 appeal.reject!(by: admin, note: "...")
+
+Moderate::Flag.flag_for_review!(message, field: :body, by: admin)   # "Flag for review" from any browse screen
 ```
 
-Every action is atomic, requires a moderator + a note, runs your enforcement (content removal via the reportable's own `remove_reported_field!`, bans via your `ban_handler`), and writes to your audit log.
+Every action is atomic, requires a moderator + a note, runs your enforcement (content removal via the reportable's own `remove_reported_field!`, bans via your `ban_handler`), and writes to your audit log. A ban needs a `ban_handler`: without one, `ban_user: true` raises instead of telling someone their account was suspended when nothing suspended it. And a report's `resolve!` restricts something (`remove_content:`, `ban_user:`, or both): one with neither is refused, because its statement of reasons would claim a restriction nobody imposed; a decision that restricts nothing is a `dismiss!`.
+
+A flag has no reporter, statement of reasons or appeal window, but removing content or suspending an account is a restriction that needs all three. So `remove_content:` / `ban_user:` on a flag escalate it: the open report on the same content and field (if a person reported it too) or a system one is resolved under the flag's lock, and `flag.report` is that report afterwards. Without them, resolving a flag only triages it.
 
 ### Use it from a controller (BYOUI)
 
 ```ruby
-class Admin::ReportsController < ApplicationController
+class Admin::ReportsController < ApplicationController   # the same concern drives Admin::FlagsController
   include Moderate::Moderation   # resolve!/dismiss! actions, strong params, redirects
 
   before_action :require_admin
@@ -346,7 +406,9 @@ end
 
 Events carry a stable envelope (`event.name`, `event.subject`, `event.recipients`, `event.actor`, `event.payload`), so a single `notify` hook can drive **goodmail** (user emails), **telegrama** (admin alerts), and **noticed** (in-app feed + push) at once. Notify users via email/in-app **and** ping admins on Telegram from the same place. (Recipes in [`docs/notifications.md`](docs/notifications.md).)
 
-The full event vocabulary: `report_received`, `report_decision`, `affected_user_decision`, `appeal_received`, `appeal_decision`, `user_blocked`, `user_unblocked`, `user_banned`, `content_flagged`, `content_removed`.
+**Notices follow Active Record's `after_commit` rules.** A decision, a report's receipt, a block: each notice belongs to the transaction it happened in and is sent when that transaction commits, never if it rolls back. If you decide inside a transaction of your own, nothing goes out until yours commits; inside nested transactions and savepoints, at the outermost commit; under a parent that isn't joinable (Rails' transactional tests run every test in one), when the savepoint is released, the same moment your models' `after_commit` runs; with no transaction open, at once. Under multiple databases or shards, queue a notice inside the transaction that saved the record, on that transaction's connection: the gem's services capture their connection before they save and pass it along, so a host callback that switches databases mid-save can't move them; if you call `record.after_commit_notice { … }` yourself under `connected_to`, pass `on: connection` (it defaults to the record class's connection at call time).
+
+The full event vocabulary: `report_received`, `notice_received`, `report_decision`, `affected_user_decision`, `appeal_received`, `appeal_decision`, `user_blocked`, `user_unblocked`, `user_banned`, `content_flagged`, `content_removed`.
 
 ## ⚖️ DSA & app-store compliance, out of the box
 
@@ -356,6 +418,7 @@ The full event vocabulary: `report_received`, `report_decision`, `affected_user_
 - **DSA Art. 17 (statement of reasons):** decision notices state the action, the legal/contractual ground, whether automated means were used, and the redress path.
 - **DSA Art. 20 (appeals):** a free, electronic internal complaint mechanism, open ≥ 6 months, decided by a human.
 - **DSA Art. 24 (transparency):** counters you can publish (notices received, actions taken, median handling time, appeal outcomes). The public transparency page is **opt-in** (`config.transparency_report_enabled = true`, off by default) — a live portal isn't itself required (the duty is to *publish* a report, and micro/small enterprises are exempt), so you turn it on only when you want it.
+- **Retention (GDPR storage limitation):** nothing is purged unless you ask. `Moderate.purge(older_than: 1.year)` (or `bin/rails moderate:purge`, opt-in, safe to run nightly) redacts the content copies and contact details from reports, flags and appeals whose decision is final, and keeps every decision and every transparency count. `Moderate.hold(report, until:)` keeps a report under external dispute out of it. What is stored, for how long, and why: [`docs/compliance.md#5-retention-what-moderate-keeps-and-for-how-long`](docs/compliance.md#5-retention-what-moderate-keeps-and-for-how-long).
 - **Apple Guideline 1.2 & Google Play UGC:** filter-before-post, in-app report **and** block, ongoing moderation, published contact — `moderate` covers all four. See the mapped checklist in [`docs/compliance.md`](docs/compliance.md).
 
 > Two taxonomies, on purpose: an in-app **community report** category set (harassment, spam, …) and a separate, regulator-aligned **DSA legal-reason** taxonomy for public notices. `moderate` ships both. The community set is host-customizable via `config.report_categories`; the DSA legal-reason taxonomy is regulator-defined and fixed.
@@ -371,7 +434,7 @@ The full event vocabulary: `report_received`, `report_decision`, `affected_user_
 
 > The value-list taxonomies (community `category`, `status`, `content_type`, the DSA `legal_reason`/`legal_country_code`, `resolution_basis`, plus `Flag` source/mode/status and `Appeal` source/status) are validated **in the models** — frozen constants + ActiveModel `inclusion` validations — **not** by database `CHECK` constraints. That means **adding or customizing a label never requires a migration**: the community category list is host-overridable via `config.report_categories` (defaults to `Moderate::Report::DEFAULT_CATEGORIES`), and the gem can grow its own taxonomies in a point release without touching your schema. The only value guard kept at the DB level is a cheap message-length backstop; everything else the migration adds is structural (NOT NULLs, FKs, the unique block edge, and the self-block CHECK).
 
-The migration is **adaptive**: it matches your app's primary-key type (UUID or bigint) and JSON column type (`jsonb` / `json`) automatically, so it drops cleanly into any Rails 7.1+ schema.
+The migration is **adaptive**: it matches your app's primary-key type (UUID or bigint) and JSON column type (`jsonb` / `json`) automatically, so it drops cleanly into any Rails 8.0+ schema.
 
 ## Configuration reference
 
@@ -384,7 +447,7 @@ Moderate.configure do |config|
   config.audit       = ->(event) { ... }     # optional; no-op by default
   config.notify      = ->(event) { ... }     # optional; no-op by default
   config.on_block    = ->(blocker:, blocked:, at:) { ... }   # optional
-  config.ban_handler = ->(user:, by:, reason:) { user.suspend! }   # how a "ban" is applied in your app
+  config.ban_handler = ->(user:, by:, reason:) { user.suspend! }   # how a "ban" is applied in your app (required before any ban_user: true)
 
   config.filter "Message", :body, with: :wordlist, mode: :flag
 end
@@ -392,12 +455,90 @@ end
 
 Reportable classes are auto-discovered from the `has_reportable_content` macro (or `include Moderate::Reportable`) — no manual registry.
 
+## What is public
+
+From 1.0 on, everything listed here keeps its name, its arguments and its meaning until 2.0. Anything not listed (and anything tagged `@api private` in the source) may change in any release. `test/public_api_test.rb` reads this section and fails if a name listed here doesn't exist, if a public `Moderate.*` method or configuration key isn't listed, or if the event lists drift from what the gem emits.
+
+#### Declarations (`Moderate::Macros`, on every Active Record model)
+
+`#has_reporting_and_blocking` · `#has_reportable_content` (`*fields, labels:`) · `#moderates` (`*fields, mode:, with:`). The include forms are equivalent: `Moderate::Actor`; `Moderate::Reportable` with `Moderate::Reportable::ClassMethods#reportable_fields`; `Moderate::ContentFilterable` with `Moderate::ContentFilterable::ClassMethods#moderates_fields`.
+
+#### `Moderate::Actor` (your user model)
+
+`#report!` (`reportable, category:, details: nil, block: false, field:, …`) · `#block!` · `#unblock!` · `#blocks?` · `#blocked_by?` · `#blocked_with?`
+
+#### `Moderate::Reportable` (your content models)
+
+What you define (each has a default): `#reported_owner` (required in practice) · `#moderation_label` · `#moderation_snapshot` · `#moderation_content_type` · `#report_visible_to?` · `#remove_reported_field!` · `#removable_reported_field?` · `#moderation_subject_url` · `#moderation_return_path` · `#moderation_admin_path`.
+The removal seam's contract: `#remove_reported_field!(field)` removes that field's content as it is when called (clear it, purge the attachment, soft-delete the record so `deleted?` is true), persists that, and returns whether anything was removed; it must not rewrite the field to other content first. The gem verifies it: after a true return the field is read again under the same lock, and unless it reads as gone (through `#moderation_snapshot` and the field itself, or `deleted?`) the decision is refused as "nothing was removed".
+What you get: `#reports` · `#open_reports` · `#reported?` · `#flagged?` · `#moderation_flags` · `#pending_moderation_flags` · `#to_moderation_sgid` · `#reportable_field_label` · `#reportable_field_allowed?` · `Moderate::Reportable::ClassMethods#reportable_field_label`.
+
+#### `Moderate::ContentFilterable` (seams you may override)
+
+`#moderation_field_value` · `#moderation_field_changed_for_commit?` · `#moderation_field_committed`
+
+#### `Moderate` (the module)
+
+`.configure` · `.config` · `.configuration` · `.reset!` · `.user_class` · `.reportable_classes` · `.classify` · `.filter_policy_for` · `.register_adapter` · `.blocked_ids_for` · `.responsible_user` · `.reportable_field_label` · `.taxonomy_label` · `.transparency` · `.delivered!` (`report, :decision | :affected_user, at:`) · `.purge` · `.hold` (`report, until:, by:, reason:`) · `.release_hold` · `Moderate::TAXONOMY_LABEL_SCOPES` · `Moderate::VERSION`
+
+#### `Moderate::Report`
+
+Queries: `.pending` · `.open` · `.actioned` · `.dismissed` · `.recent_first` · `.report_categories` · `.category_options` · `.locate_signed_reportable`.
+Decisions: `#resolve!` (`by:, note:, remove_content: false, ban_user: false, resolution_basis: "terms"`) · `#dismiss!` (`by:, note:`).
+Readers: `#pending?` · `#open?` · `#closed?` · `#actioned?` · `#dismissed?` · `#dsa?` · `#community?` · `#anonymous_notice?` · `#automated_processing_used?` · `#reported_field_label` · `#reportable_label` · `#notifier_label` · `#reported_content_text` · `#subject_url_list` · `#safe_subject_url` · `#safe_subject_urls` · `#safe_subject_url_for` · `#signed_appeal_gid` · `#held?` · `#covered_by` · `#skip_received_notice` · `#appeals` · `#flags`.
+Value lists: `::DEFAULT_CATEGORIES` · `::DSA_LEGAL_REASONS` · `::EU_COUNTRY_CODES` · `::CONTENT_TYPES` · `::RESOLUTION_BASES` · `::STATUSES` · `::INTAKE_KINDS` · `::APPEAL_WINDOW` · `::MESSAGE_MAX_LENGTH`.
+
+#### `Moderate::Flag`
+
+`.pending` · `.actioned` · `.dismissed` · `.recent_first` · `.flag_for_review!` (`record, field:, by:, note: nil`) · `.flag!` (`flaggable:, field:, owner:, source:, mode:, excerpt:, categories:, scores:, context:`, for a host's own classifier pipeline) · `.sources` · `#action!` (`note:, by: nil, remove_content:, ban_user:, resolution_basis:`) · `#resolve!` (its alias) · `#dismiss!` (`note:, by: nil`) · `#pending?` · `#closed?` · `#report` · `#field_label` · `#flaggable_label` · `::STATUSES` · `::SOURCES` · `::MODES`
+
+#### `Moderate::Appeal`
+
+`.pending` · `.open` · `.upheld` · `.rejected` · `.recent_first` · `#uphold!` (`by:, note:`) · `#reject!` (`by:, note:`) · `#pending?` · `#open?` · `#closed?` · `#upheld?` · `#rejected?` · `::STATUSES` · `::SOURCES`
+
+#### `Moderate::Block`
+
+`.block!` (`blocker:, blocked:`) · `.unblock!` (`blocker:, blocked:`) · `.between` · `.recent_first`. Read the edge set with `Moderate.blocked_ids_for(user)`: always a relation of user ids, `.ids` for an Array.
+
+#### Services (the long form of the decision methods, same keywords)
+
+`Moderate::Services::ResolveReport` (`.new(report, by:)`, `#resolve!`, `#dismiss!`) · `Moderate::Services::ResolveFlag` (`.new(flag, by:)`, `#action!`, `#dismiss!`) · `Moderate::Services::ResolveAppeal` (`.new(appeal, by:)`, `#uphold!`, `#reject!`) · `Moderate::Services::IntakeReport` · `Moderate::Services::IntakeNotice` · `Moderate::Services::IntakeAppeal` (each `#save`).
+
+#### Jobs, adapters and value objects
+
+`Moderate::ClassifyJob` (`perform_later(record, field)`; `::UPLOAD_WAIT`, `::UPLOAD_ATTEMPTS`) · the adapter contract: any object with `classify(value)` returning a `Moderate::Result` (or a Hash of its fields), optionally `synchronous?`; `Moderate::Filters::Base` to inherit from · `Moderate::Filters::Wordlist` (`:wordlist`) · `Moderate::Result` (`.allowed`, `#allowed?`, `#flagged?`, `#categories`, `#scores`, `#labels`, `#source`, `#raw`) · `Moderate::Label` (`#slug`, `#canonical?`, `::CATEGORIES`) · `Moderate::Error` · `Moderate::ConfigurationError` · the 0.x validator `validates :field, moderate: true`.
+
+#### Views and controllers
+
+Helpers (`Moderate::EngineHelper`): `#moderate_report_link` · `#report_link` · `#moderate_report_target_path`, and the seam `#moderate_current_viewer`.
+Admin decisions (`Moderate::Moderation`, a controller concern): `#resolve` · `#dismiss` · `#uphold` · `#reject`, and the seams `#moderation_record` · `#moderation_actor` · `#moderation_note` · `#moderation_decision_params` · `#moderation_redirect_path`.
+The engine (`mount Moderate::Engine => "/trust"`): `new_notice_path` / `notices_path`, `new_appeal_path` / `appeals_path` (`token:`, `source:`), `transparency_path`; `record.after_commit_notice` (`Moderate::DeferredNotices#after_commit_notice`) on the gem's records. Generators: `moderate:install`, `moderate:views`. Rake: `moderate:purge`.
+
+#### Configuration (`Moderate.configure do |config| … end`)
+
+`config.user_class` · `config.default_filter_mode` · `config.filter_adapter` · `config.additional_words` · `config.excluded_words` · `config.report_categories` · `config.register_adapter` · `config.filter` · `config.audit` · `config.notify` · `config.on_block` · `config.ban_handler` · `config.banned` · `config.locale` · `config.classification_claim_ttl` · `config.migration_copies_check` · `config.parent_controller` · `config.notice_form_enabled` · `config.notice_rate_limit` · `config.notice_turnstile_site_key` · `config.notice_turnstile_secret_key` · `config.notice_captcha_verifier` · `config.notice_guard` · `config.notice_human_verification_skip_if` · `config.appeal_form_enabled` · `config.appeal_rate_limit` · `config.appeal_guard` · `config.appeal_human_verification_skip_if` · `config.appeal_return_path` · `config.transparency_report_enabled`.
+Read-only: `config.adapters` · `config.filters` · `config.adapter_for` · `config.adapter_registered?` · `config.adapter_async?` · `config.ban_handler_configured?` · `config.validate!`.
+
+#### Events and the notifier contract
+
+Notify events (`Moderate::Event::NOTIFY_NAMES`): `:report_received` · `:notice_received` · `:report_decision` · `:affected_user_decision` · `:appeal_received` · `:appeal_decision` · `:user_blocked` · `:user_unblocked` · `:user_banned` · `:content_flagged` · `:content_removed`
+
+Audit events (`Moderate::Event::AUDIT_NAMES`): `: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`
+
+Every hook receives one `Moderate::Event`: `#name` · `#subject` · `#actor` · `#recipients` · `#payload` (always with `:summary`) · `#occurred_at` · `#id` · `#summary` · `#to_h`. The contract for `config.notify`: it is called once per event, after the transaction that caused it commits (never for a rolled-back change); a truthy return means "handed off" (for a DSA notice the gem then treats the Art. 16(4) receipt as sent); a decision notice counts as delivered only when your notifier confirms it with `Moderate.delivered!(report, :decision | :affected_user)` from the mail's actual delivery, which stamps `decision_notified_at` / `affected_user_notified_at` once and starts the appeal window from then (DSA Art. 20(2)); an exception is swallowed, audited as `:notify_failed`, and never rolls back the decision. `config.audit` follows the same rules and its return value is ignored. Payload keys may be added in a minor release, never removed or renamed.
+
+## Upgrading from a 1.0 beta
+
+**1.0.0 adds a migration** (retention columns and `moderate_classifications`): run `bin/rails moderate:install:migrations` if your app holds copies of the gem's migrations (`*.moderate.rb`, as every app installed from 1.0.0.beta4 on does), then `bin/rails db:migrate`. An app without copies gets it through the engine, like beta4's. **A missed copy is no longer silent:** at boot, an app that holds copies but not one of this version's migrations raises `Moderate::ConfigurationError` naming it and the command that copies it (under a rake task, such as that command itself, it logs instead); `config.migration_copies_check = :log` or `:off` changes that.
+
+**1.0.0.beta4 adds a migration.** After upgrading, run `bin/rails db:migrate`: the engine adds the gem's own `db/migrate` to your app's migration paths, so it runs with yours. (If your app holds copies of the gem's migrations, `*.moderate.rb` files from `bin/rails moderate:install:migrations`, the engine adds nothing and the copies run instead: run `bin/rails moderate:install:migrations` to copy the new one, then migrate.) A fresh install from 1.0.0.beta4 on gets the same migration from `rails generate moderate:install`, copied right after the tables, so it holds copies: after each later upgrade, run `bin/rails moderate:install:migrations`, then migrate. It gives `moderate_flags` a `pending_key` with a unique index, so at most one flag is pending per content and field. If flags filed before the upgrade would break that index, the migration stops and lists them; close all but one of each and run it again. On MySQL the key column is `utf8mb4_bin`, so keys compare by case; that collation still ignores trailing spaces (PAD SPACE), which is why `moderate` strips a flag's `field`, and why a legacy flag whose field ends in a space can be one of those the migration lists. See [`CHANGELOG.md`](CHANGELOG.md) for what each beta changes.
+
 ## Upgrading from 0.x
 
 `moderate` 1.0 is a ground-up rewrite: the old gem was a profanity validator; 1.0 is a full Trust & Safety system. The one piece of the old API that remains is the validator, now backed by the `:wordlist` adapter:
 
 ```ruby
-validates :body, moderate: true     # still works — equivalent to `moderates :body, mode: :block`
+validates :body, moderate: true     # still works — the same check as `moderates :body, with: :wordlist, mode: :block`
 ```
 
 Everything else is new. There's no automated data migration (0.x stored nothing). See [`CHANGELOG.md`](CHANGELOG.md).
@@ -408,6 +549,7 @@ We use Minitest. Run the suite (a dummy Rails app under `test/dummy`, against SQ
 
 ```bash
 bundle exec rake test
+bundle exec rubocop   # CI expects zero offenses
 ```
 
 ## Development

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 begin
   require "bundler/setup"
 rescue LoadError

data/app/controllers/concerns/moderate/moderation.rb

@@ -26,8 +26,9 @@ module Moderate
 
     # --- Report / Flag decisions ---------------------------------------------
     # Both `Moderate::Report` and `Moderate::Flag` expose `resolve!`/`dismiss!` with
-    # the same keyword contract, so the SAME two actions drive either resource —
-    # the host just includes this concern in whichever controller.
+    # the same keyword contract (`Flag#resolve!` is `Flag#action!`), so the SAME two
+    # actions drive either resource — the host just includes this concern in
+    # whichever controller.
 
     # Resolve (action) a report/flag: optionally remove the offending content and/or
     # ban the responsible user, always with a moderator + a note.
@@ -39,8 +40,8 @@ module Moderate
     def resolve
       record = moderation_record
       record.resolve!(**moderation_decision_params)
-      redirect_after_moderation(record, notice: moderation_t(:resolved))
-    rescue => error
+      redirect_after_moderation(record, notice: moderation_t(moderation_outcome_key(record, :resolved)))
+    rescue StandardError => error
       redirect_after_moderation(record, alert: moderation_error(:resolve, error))
     end
 
@@ -48,8 +49,8 @@ module Moderate
     def dismiss
       record = moderation_record
       record.dismiss!(by: moderation_actor, note: moderation_note)
-      redirect_after_moderation(record, notice: moderation_t(:dismissed))
-    rescue => error
+      redirect_after_moderation(record, notice: moderation_t(moderation_outcome_key(record, :dismissed)))
+    rescue StandardError => error
       redirect_after_moderation(record, alert: moderation_error(:dismiss, error))
     end
 
@@ -62,7 +63,7 @@ module Moderate
       record = moderation_record
       record.uphold!(by: moderation_actor, note: moderation_note)
       redirect_after_moderation(record, notice: moderation_t(:upheld))
-    rescue => error
+    rescue StandardError => error
       redirect_after_moderation(record, alert: moderation_error(:uphold, error))
     end
 
@@ -70,7 +71,7 @@ module Moderate
       record = moderation_record
       record.reject!(by: moderation_actor, note: moderation_note)
       redirect_after_moderation(record, notice: moderation_t(:rejected))
-    rescue => error
+    rescue StandardError => error
       redirect_after_moderation(record, alert: moderation_error(:reject, error))
     end
 
@@ -100,14 +101,18 @@ module Moderate
     # `params.require(:report)` because the decision form is a flat panel of
     # checkboxes + a note, not a nested model form — so we read top-level params and
     # hand the model exactly the keyword args it documents. `ban_user`/`remove_content`
-    # default to off so a missing checkbox never accidentally bans someone.
+    # default to off so a missing checkbox never accidentally bans someone, and
+    # `resolution_basis` (the Art. 17 ground) is passed only when the form sent one,
+    # so the model's default ("terms") applies otherwise. On a Flag, either
+    # enforcement option escalates to a report (Flag#action!).
     def moderation_decision_params
       {
         by: moderation_actor,
         note: moderation_note,
         remove_content: params[:remove_content],
-        ban_user: params[:ban_user]
-      }
+        ban_user: params[:ban_user],
+        resolution_basis: params[:resolution_basis].presence
+      }.compact
     end
 
     # Redirect back to the record after a decision.
@@ -146,12 +151,19 @@ module Moderate
       moderation_t(:"#{action}_failed", default: "Could not #{action}: #{message}", error: message)
     end
 
+    # A flag's outcome reads as a flag's ("Flag actioned."), a report's as a report's.
+    def moderation_outcome_key(record, outcome)
+      record.is_a?(Moderate::Flag) ? :"flag_#{outcome}" : outcome
+    end
+
     # Translated flash copy, with a plain-English default so the concern works even
     # before the host loads the gem's locale file.
     def moderation_t(key, **options)
       defaults = {
         resolved: "Report resolved.",
         dismissed: "Report dismissed.",
+        flag_resolved: "Flag actioned.",
+        flag_dismissed: "Flag dismissed.",
         upheld: "Appeal upheld.",
         rejected: "Appeal rejected."
       }

data/app/controllers/moderate/appeals_controller.rb

@@ -11,7 +11,10 @@ module Moderate
 
     def new
       @report = Moderate::Report.locate_signed_appeal_report(params[:token])
-      return redirect_to appeal_return_path, alert: t("moderate.appeals.not_found", default: "We couldn't find that moderation decision.") if @report.blank?
+      if @report.blank?
+        return redirect_to appeal_return_path,
+          alert: t("moderate.appeals.not_found", default: "We couldn't find that moderation decision.")
+      end
 
       @appeal = Moderate::Appeal.new(
         report: @report,
@@ -24,7 +27,10 @@ module Moderate
 
     def create
       @report = Moderate::Report.locate_signed_appeal_report(params[:token])
-      return redirect_to appeal_return_path, alert: t("moderate.appeals.not_found", default: "We couldn't find that moderation decision.") if @report.blank?
+      if @report.blank?
+        return redirect_to appeal_return_path,
+          alert: t("moderate.appeals.not_found", default: "We couldn't find that moderation decision.")
+      end
 
       attributes = appeal_params
       attributes[:source] = appeal_source_for(@report, attributes[:source])
@@ -64,9 +70,7 @@ module Moderate
       return @current_appellant if defined?(@current_appellant)
 
       @current_appellant =
-        if respond_to?(:current_user, true)
-          current_user
-        end
+        (current_user if respond_to?(:current_user, true))
     rescue StandardError
       @current_appellant = nil
     end

data/app/controllers/moderate/application_controller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Resolves the host's `config.parent_controller` once, for the engine's base controller.
 module Moderate
   # Base controller for the engine's OWN controllers (today: the public DSA notice
   # form). It is NOT used by the host's in-app report/admin controllers — those are
@@ -32,14 +33,13 @@ module Moderate
     ::ActionController::Base
   end
 
+  # The base of the engine's own controllers (notices, appeals, transparency).
   class ApplicationController < parent
     # CSRF protection — but only when the parent actually supports it. On
     # `ActionController::API` (or a host base that doesn't include the module),
     # `protect_from_forgery` isn't defined, so we guard the call. The public notice
     # form is a state-changing POST, so we want forgery protection whenever it's
     # available. `with: :exception` is the modern Rails default.
-    if respond_to?(:protect_from_forgery)
-      protect_from_forgery with: :exception
-    end
+    protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
   end
 end

data/app/controllers/moderate/notices_controller.rb

@@ -154,9 +154,7 @@ module Moderate
       return @current_notifier if defined?(@current_notifier)
 
       @current_notifier =
-        if respond_to?(:current_user, true)
-          current_user
-        end
+        (current_user if respond_to?(:current_user, true))
     rescue StandardError
       # A host `current_user` that raises (e.g. a not-yet-migrated session) must not
       # break the public notice form — fall back to "anonymous".
@@ -222,9 +220,8 @@ module Moderate
 
     # A public, unauthenticated POST is a spam/abuse magnet, so we throttle per IP.
     #
-    # Rails 7.2 shipped a first-class controller `rate_limit` macro; on 7.1 it
-    # doesn't exist, so we fall back to a tiny `Rails.cache`-backed counter. We
-    # implement the throttle as a single `before_action` (rather than the class-level
+    # A tiny `Rails.cache`-backed counter rather than Rails' own `rate_limit` macro:
+    # we implement the throttle as a single `before_action` (not the class-level
     # `rate_limit` macro) precisely so we can honor the host's RUNTIME
     # `config.notice_rate_limit` (the macro is evaluated at class load, before the
     # host's initializer has necessarily run).

data/app/helpers/moderate/engine_helper.rb

@@ -65,6 +65,20 @@ module Moderate
       moderate_report_link(record, field: field, label: label, **html_options)
     end
 
+    # The path to the in-app report form for `record` (and `field`), with the record
+    # as a signed target — WITHOUT asking who is looking. For markup rendered once
+    # and shown to many viewers (a chat bubble broadcast to every participant, a
+    # fragment cache), where `moderate_report_link`'s per-viewer check can't run at
+    # render time: show it to everyone but the author on the client, and let the
+    # report be refused server-side (Report validates `report_visible_to?`).
+    #
+    #   <%= link_to "Report", moderate_report_target_path(message, field: :body) %>
+    #
+    # The target never expires, so the URL is stable across renders.
+    def moderate_report_target_path(record, field: nil)
+      moderate_report_path_for(record, field: field)
+    end
+
     private
 
     # The path to the in-app intake form for this record/field.
@@ -87,15 +101,20 @@ module Moderate
       target = moderate_signed_target(record)
       query = { target: target, field: field.presence }.compact
 
-      if respond_to?(:new_report_path)
-        new_report_path(query)
-      elsif respond_to?(:new_moderate_report_path)
-        new_moderate_report_path(query)
-      else
-        # Last-resort conventional path so the helper is never a hard dependency on
-        # a particular route name. The host wires the actual route (BYOUI).
-        "/reports/new?#{query.to_query}"
+      # The host's route, from this view's own helpers first, then through
+      # `main_app` — inside ANOTHER isolated engine's views (a chats slot, say) the
+      # host's route helpers are only reachable that way.
+      route_sets = [self]
+      route_sets << main_app if respond_to?(:main_app)
+      route_sets.each do |routes|
+        %i[new_report_path new_moderate_report_path].each do |name|
+          return routes.public_send(name, query) if routes.respond_to?(name)
+        end
       end
+
+      # Last-resort conventional path so the helper is never a hard dependency on
+      # a particular route name. The host wires the actual route (BYOUI).
+      "/reports/new?#{query.to_query}"
     end
 
     # The record as a signed, purpose-scoped GID parameter. We delegate to the
@@ -146,6 +165,8 @@ end
 # Expose the helper to the HOST app's views (see the "isolated engine" gotcha in
 # the module doc above). `on_load(:action_view)` defers until ActionView is loaded,
 # so we never force it at boot and we play nice with the host's load order.
-ActiveSupport.on_load(:action_view) do
-  include Moderate::EngineHelper
-end if defined?(ActiveSupport)
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:action_view) do
+    include Moderate::EngineHelper
+  end
+end

data/app/views/moderate/appeals/new.html.erb

@@ -31,6 +31,12 @@
           <strong><%= t("moderate.appeals.decision", default: "Decision") %></strong>
           <span><%= @report.id %></span>
         </p>
+        <% if (field_label = @report.reported_field_label) %>
+          <p class="moderate-reported-field">
+            <strong><%= t("moderate.appeals.reported_field", default: "Content") %></strong>
+            <span><%= field_label %></span>
+          </p>
+        <% end %>
         <% if @report.appeal_deadline_at.present? %>
           <p><%= t("moderate.appeals.deadline", default: "You can request a free internal review until %{deadline}. A person will review it.", deadline: l(@report.appeal_deadline_at, format: :long)) %></p>
         <% end %>

data/app/views/moderate/transparency_reports/_summary_card.html.erb

@@ -1,6 +1,6 @@
 <%
   rows = rows.to_h.compact_blank
-  translation_scope = local_assigns[:translation_scope]
+  kind = local_assigns[:kind]
 %>
 
 <article class="moderate-card">
@@ -9,7 +9,7 @@
     <dl>
       <% rows.sort_by { |key, _value| key.to_s }.each do |key, value| %>
         <div>
-          <dt><%= translation_scope ? t("#{translation_scope}.#{key}", default: key.to_s.humanize) : key.to_s.humanize %></dt>
+          <dt><%= kind ? Moderate.taxonomy_label(kind, key) : key.to_s.humanize %></dt>
           <dd><%= value %></dd>
         </div>
       <% end %>

data/app/views/moderate/transparency_reports/show.html.erb

@@ -28,11 +28,11 @@
 
   <main class="moderate-main">
     <div class="moderate-container moderate-grid">
-      <%= render "summary_card", title: t("moderate.transparency.cards.notices_by_intake", default: "Notices by intake"), rows: @summary[:notices_by_intake] %>
-      <%= render "summary_card", title: t("moderate.transparency.cards.dsa_by_reason", default: "DSA notices by legal reason"), rows: @summary[:dsa_notices_by_legal_reason], translation_scope: "moderation.legal_reasons" %>
-      <%= render "summary_card", title: t("moderate.transparency.cards.actions_by_basis", default: "Actions by basis"), rows: @summary[:actions_by_basis], translation_scope: "moderation.resolution_bases" %>
-      <%= render "summary_card", title: t("moderate.transparency.cards.flags_by_source", default: "Automated flags by source"), rows: @summary[:automated_flags_by_source] %>
-      <%= render "summary_card", title: t("moderate.transparency.cards.appeals_by_status", default: "Appeals by status"), rows: @summary[:appeals_by_status] %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.notices_by_intake", default: "Notices by intake"), rows: @summary[:notices_by_intake], kind: :intake_kind %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.dsa_by_reason", default: "DSA notices by legal reason"), rows: @summary[:dsa_notices_by_legal_reason], kind: :legal_reason %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.actions_by_basis", default: "Actions by basis"), rows: @summary[:actions_by_basis], kind: :resolution_basis %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.flags_by_source", default: "Automated flags by source"), rows: @summary[:automated_flags_by_source], kind: :flag_source %>
+      <%= render "summary_card", title: t("moderate.transparency.cards.appeals_by_status", default: "Appeals by status"), rows: @summary[:appeals_by_status], kind: :appeal_status %>
 
       <article class="moderate-card">
         <h2><%= t("moderate.transparency.cards.median_times", default: "Median times") %></h2>