moderate 1.0.0.beta1 → 1.0.0

data/CHANGELOG.md

@@ -4,20 +4,281 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - unreleased
+## [1.0.0] - 2026-10-19
 
-A complete, ground-up rewrite. `moderate` graduates from a single-purpose profanity
-validator (0.1.0) into a full **Trust & Safety** engine for Rails apps with user-generated
-content: report, block, filter, a moderation queue, appeals, and EU DSA / App Store / Google
-Play **aligned** primitives. (First cut ships as `1.0.0.beta1`.)
+The first stable release. The public API is frozen until 2.0: everything listed in the
+README's "What is public" section keeps its name, arguments and meaning, and
+`test/public_api_test.rb` keeps that list honest. Since 1.0.0.beta4: Ruby 3.3+ and Rails
+8.0.5.1+, attachments classified once and only once their files exist, opt-in retention with
+legal holds, an appeal window that runs from confirmed delivery, and **one migration** (see
+_Upgrading from 1.0.0.beta4_). Coming from an earlier beta, apply each beta's _Upgrading_
+notes below in order, then these; coming from 0.x, see _Upgrading from 0.x_ at the end of
+this entry.
 
-> **Breaking:** 1.0 keeps the gem name but is an entirely new API. The 0.x profanity
-> validator (`validates :field, moderate: true`) still loads for backward compatibility
-> (see _Upgrading from 0.x_), but everything else is new. Pin `~> 0.1` if you relied on the
-> old behavior and are not ready to adopt the new surface.
+### Upgrading from 1.0.0.beta4
+
+- **One migration: run `bin/rails db:migrate`** (after `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; boot now fails, naming it, if you forget). `db/migrate/20261018210000_add_retention_and_classifications_to_moderate_tables.rb`
+  adds `redacted_at` to `moderate_reports`, `moderate_flags` and `moderate_appeals`,
+  `held_until` and `covered_by_report_id` (both indexed) to `moderate_reports`, and creates
+  `moderate_classifications`. It
+  sorts after beta4's `pending_key` migration and needs no backfill. Like that one it is the
+  only thing that creates what it adds: `rails generate moderate:install` leaves it out of
+  `create_moderate_tables` and copies the migration after it, an app without copies gets it
+  through the engine, and its `down` drops only what it created.
+
+- **What changes for an app upgrading from beta4** (each is detailed below):
+  - Ruby 3.3+ and Rails 8.0.5.1+ (Rails 8.0 hosts on json 3 need `json < 3`, as before).
+  - `config.signed_gid_purposes` is gone: delete the line if you set it.
+  - `report.resolve!` with neither `remove_content:` nor `ban_user:` is refused: dismiss
+    instead.
+  - `decision_notified_at` / `affected_user_notified_at` (and the appeal window's
+    extension) wait for `Moderate.delivered!` from your mailer's delivery.
+  - `Report#reported_content_text` is the intake snapshot.
+  - If your app can lift a ban, set `config.banned`.
+  - If you worked around the attachment upload race (CarHey's avatar), remove the
+    workaround.
+  - Attachment classification queues two `ClassifyJob`s per upload (the guard and the
+    immediate one); each set of files is still classified once.
 
 ### Added
 
+- **A missed migration copy fails at boot.** An app holding copies of the gem's migrations
+  (`*.moderate.rb`) runs only those, so a release migration it didn't copy would never
+  run, silently. At boot (`after_initialize`) the engine compares the copies with its own
+  migrations by name and, when one is missing, raises `Moderate::ConfigurationError`
+  naming it and `bin/rails moderate:install:migrations`; under a rake task (that command,
+  `db:migrate`) it logs instead. **`config.migration_copies_check`** (`:raise`, `:log`,
+  `:off`) changes it. Apps without copies aren't checked.
+- **The public API is frozen and listed.** The README's new "What is public" section names
+  everything that keeps its name, arguments and meaning until 2.0: the macros, `report!` /
+  `block!`, the reportable contract, the decision methods (`resolve!` / `dismiss!` /
+  `action!` / `uphold!` / `reject!`) and their services, `flag_for_review!`, `taxonomy_label`,
+  `reportable_field_label`, `blocked_ids_for`, `purge`, `hold` / `release_hold`,
+  `delivered!`, every configuration key, the view
+  helpers, the controller concern and its seams, the adapter contract, and the event
+  vocabulary with the notifier contract. The vocabulary is now code:
+  `Moderate::Event::NOTIFY_NAMES` and `Moderate::Event::AUDIT_NAMES`.
+  `test/public_api_test.rb` fails when a listed name doesn't exist, when a public
+  `Moderate.*` method or configuration key isn't listed, when the event lists drift from
+  what the gem emits, or when the README or docs/ name a `Moderate…` constant or method that
+  doesn't exist (it caught `Moderate::DSA_LEGAL_REASONS` in docs/compliance.md; it is
+  `Moderate::Report::DSA_LEGAL_REASONS`).
+- **What isn't public is marked.** `@api private`: `Moderate.notify`, `.audit`, `.apply_ban`,
+  `.announce_ban`, `.ensure_ban_handler!`, `.run_on_block`, `.with_row_lock`,
+  `.register_reportable`, `.locale`; `Report::SIGNED_GLOBAL_ID_PURPOSE` /
+  `APPEAL_SIGNED_GLOBAL_ID_PURPOSE`, `Report#signed_reportable_gid`, `#acknowledge!`,
+  `#close_redress_window!`, `#block_reported_user`, `Report.locate_signed_appeal_report`;
+  `DeferredNotices.defer` / `.connection_for` / `Envelope`; the wordlist's compiler
+  internals. `Moderate::Engine::LIB_ROOT`, `MODERATE_LIB` and `ZEITWERK_IGNORED` are private
+  constants. Nothing tagged was removed; a host still calling one should move:
+  `Moderate.apply_ban` → `flag.action!(ban_user: true)` or `report.resolve!(ban_user: true)`
+  (which also send the statement of reasons and open the appeal window);
+  `to_sgid_param(for: Moderate::Report::SIGNED_GLOBAL_ID_PURPOSE)` and
+  `report.signed_reportable_gid` → `record.to_moderation_sgid` or
+  `moderate_report_target_path(record, field:)`.
+- **docs/notifications.md lists the audit events** instead of claiming `audit` fires for every
+  event (`content_flagged`, for one, is notify-only: the flag row is its record).
+- **Retention: `Moderate.purge(older_than: 1.year, dry_run: false)`** and the
+  `moderate:purge` rake task (`OLDER_THAN_DAYS`, `DRY_RUN`), opt-in. They redact the personal
+  data in reports, notices, flags and appeals whose decision is final (closed, decided more
+  than `older_than` ago, appeal window over, no open appeal): messages, evidence snapshots,
+  reported URLs, notifier and appellant contact details, flag excerpts and context. Every row
+  and every decision stays, so the statement of reasons, a repeat-misuse history and the
+  transparency counts are unchanged; blocks and pending records are never touched;
+  `older_than` below the six-month appeal window raises. Idempotent, batched, audited as
+  `:retention_purged`. `docs/compliance.md` gains a retention section: what the gem stores,
+  that nothing is purged by default, and what the DSA and the GDPR expect. A purged row is
+  stamped `redacted_at`, and the purge selects on that column, never on the content (a
+  message that literally read `"[redacted]"` would otherwise have kept its snapshot, URLs,
+  contacts and reporter, and `dry_run` under-counted it). The returned counts are
+  `:reports`, `:flags`, `:appeals`, `:classifications`, `:claims_kept` and `:held`.
+  `1.year` is documented as a default the host sets per its own purposes.
+- **Legal holds: `Moderate.hold(report, until:, by: nil, reason: nil)` /
+  `Moderate.release_hold(report)`** and `Report#held?`. A held report, its appeals and the
+  flags on its content are left out of the purge until the date (an out-of-court dispute
+  under DSA Art. 21, a court case, an authority's request); `dry_run` and the rake task
+  report held rows separately; both are audited (`:legal_hold_placed`,
+  `:legal_hold_released`).
+- **RuboCop runs in CI** (a `rubocop` job next to the test matrix) and the codebase has zero
+  offenses. `.rubocop.yml` now describes the code as it is: size metrics off (the gem
+  explains itself in long, commented methods), complexity metrics capped where the code is,
+  140-column lines, continuation lines indented one step, and the ecosystem's `has_*` macro
+  names allowed. The rest was fixed: safe autocorrections plus a few by hand (`rescue
+  StandardError`, double-quoted strings, documentation comments on the small classes,
+  `FileUtils.rm_f`). New cops are enabled.
+
+### Fixed
+
+- **`Report#reported_content_text` is the evidence snapshot**, as its documentation always
+  said: the reported field's text when the report was filed, surviving edits and deletion
+  (nil once a purge redacts the report). It read the live content.
+- **Refusals, validation messages and the admin concern's flash messages ship in English
+  and Spanish** (`moderate.errors.*`, `moderate.moderation.*`); they existed only as inline
+  English defaults. A test keeps every such key covered in both files. (The notice, appeal
+  and transparency pages' own copy still has inline English defaults, overridable under
+  `moderate.notices.*`, `moderate.appeals.*`, `moderate.transparency.*`.)
+- **docs/madmin.md listed a `.resolved` scope** that doesn't exist; the scopes are
+  `.pending`, `.actioned`, `.dismissed` and `.recent_first`.
+- **A second report on content an earlier decision already removed closes against it.**
+  Flags had "already dealt with"; reports had no truthful way to close: removing again
+  removed nothing and was refused. A decision that removes content now reads, under the
+  content's lock and right before removing, the text it is about to remove (recorded as
+  `resolution_actions["removed_text_digest"]`), and stamps the OTHER reports pending on
+  that content and field whose intake snapshot holds exactly that text, once the removal is
+  verified (below),
+  (`covered_by_report_id`, readable as `Report#covered_by`); with no readable text it
+  stamps nobody. A stamped report resolved with `remove_content: true` closes against that
+  decision while the decision stands (no appeal against it upheld: an overturned removal
+  covers nothing, though the stamp stays as history) and the content is gone now (read
+  fresh under the lock; deleted content counts), and records
+  `resolution_actions["content_already_removed_by"]`. No clocks are compared: a report that
+  wasn't pending when the content was removed (a repost, a removal that didn't take, a late
+  or backdated report) was never stamped, so a report filed after a removal is never
+  credited to it; the normal removal or refusal ("Nothing was removed") applies. A report
+  filed during the removal, or one whose snapshot holds older text than what was removed,
+  is stamped only if its snapshot holds the removed text. Nothing is removed, audited or
+  announced a second time, the author gets no second statement of
+  reasons (unless this decision also bans), and the reporter's `report_decision` carries
+  `content_already_removed_by` and says "already removed by the decision on Report #X".
+- **A removal is verified, not taken on trust.** When the reportable's
+  `remove_reported_field!` returns true, the field is read again under the same lock; unless
+  it reads as gone (through `moderation_snapshot` and the field itself, or `deleted?`) the
+  decision is refused as "Nothing was removed", nobody is stamped and no digest recorded. A
+  host method that rewrote the field instead of removing it used to be recorded as a
+  removal. The seam's contract is now written in the README: remove the field's content as
+  it is when called, persist it, return whether anything was removed, and never rewrite the
+  field first.
+- **A report whose content was deleted can be decided.** The intake check that a report
+  without content names a URL ran on every save, so once the content was deleted (its
+  pointer nullified) no decision on the report could be saved. It now runs at intake.
+- **A report resolved with neither removal nor ban is refused.** It recorded
+  `decision_visibility: "other_restriction"` and sent the author a statement of reasons
+  for a restriction nobody imposed. `resolve!` restricts something (`remove_content:`,
+  `ban_user:`, or both); with neither it now raises `ActiveRecord::RecordInvalid` with
+  `moderate.errors.resolve_needs_action` (en/es: "… To close it without a restriction,
+  dismiss it."), and the report stays open. **Behavior change:** a host that resolved
+  reports with only a note (a "warning") should `dismiss!` them, or apply its own measure
+  and dismiss. `other_restriction` stays in the decision taxonomy for labels.
+- **A ban after a host-side unban is applied again.** One ban per person per episode: a
+  second ban decision in the same episode was recorded as covered by the first
+  (`ban_already_applied_by`), so after the host lifted the ban the `ban_handler` wasn't
+  called and the statement of reasons said "account suspended" for an account nothing had
+  suspended. **`config.banned = ->(user) { … }`** (optional, documented beside
+  `ban_handler`) says whether the person is banned now: when it returns false the earlier
+  ban no longer counts and the handler runs again. Unset, the earlier ban counts, as before;
+  hosts that can unban should set it.
+  Both `config.banned` and the `ban_handler` get the person as read again, with a locking
+  read, once the decision holds their lock: two ban decisions on one person at once ban
+  once (the second records `ban_already_applied_by`), even inside a host transaction that
+  read the person earlier (on MySQL that read pins an older snapshot).
+- **`validates :field, moderate: true` works again.** The README promised the 0.x one-liner
+  still worked; it raised `Unknown validator: 'ModerateValidator'`, because its file was
+  never loaded (and had it been, it downloaded a word list over HTTP and read a
+  configuration key 1.0 doesn't have). It is now what the README says: the built-in
+  `:wordlist` in `:block` mode, adding the same `:objectionable_content` error (or your
+  `message:`). The unreachable 0.x `Moderate::Text` and `Moderate::WordList` are deleted.
+- **A field rejected by `:block` reads as copy.** `errors.add(field, :objectionable_content)`
+  had no translation, so a person saw "Body Translation missing. Options considered
+  were: …". The gem ships `errors.messages.objectionable_content` in English ("contains
+  language that isn't allowed") and Spanish; override it per model and attribute the usual
+  Active Record way.
+- **docs/notifications.md's statement-of-reasons mailer had no working appeal link.** It
+  read `event.payload[:appeal_url]`, which the gem has never set, so a copied mailer
+  rendered an "Appeal this decision" button to nowhere (Art. 17(3)(f) requires the redress
+  path). It now builds the link the way a working host does:
+  `moderate.new_appeal_url(token: event.subject.signed_appeal_gid, source: "affected_user")`.
+- **An attachment is classified once its file is uploaded, never before.** Active Storage
+  uploads a new attachment in its own `after_commit`, and commit callbacks run in the order
+  they were defined, so on a model that calls `moderates` above `has_one_attached` the
+  filter ran first: a synchronous adapter classified a blob whose file wasn't on the
+  service yet, and an async adapter's `ClassifyJob` could run before the upload finished.
+  The filter now watches Active Storage's upload itself, from `before_save` (so in either
+  declaration order), and classifies when it returns: inline for a synchronous adapter, by
+  an immediate job for an async one. Works for `has_one_attached` and `has_many_attached`.
+  `ClassifyJob` also checks that every blob behind the value exists on its service:
+  if one doesn't (a direct upload still in flight, a lagging replica) it re-enqueues itself
+  after 5, 10, 15 and 20 seconds (`UPLOAD_WAIT`, `UPLOAD_ATTEMPTS`), then gives up with a
+  `classification_skipped` audit event. Nothing classifies a file that isn't there: the
+  inline (synchronous adapter) path checks too, and hands a missing file to the job; a
+  direct upload attached before its file arrives (whose Active Storage `upload` is a no-op)
+  waits the same way. A failed upload is never silent: just before Active Storage uploads,
+  the filter queues a guard `ClassifyJob` for `UPLOAD_WAIT` seconds later, so an upload that
+  raises (or a process that dies) still ends in a classification or a `classification_skipped`
+  audit. Each set of files is classified once: the job takes `blob_ids:` and
+  stops if the field holds other files by then, and whoever classifies first records it,
+  so the guard finds that and stops.
+  The inline path and the job claim the files under the content record's row lock (content
+  first, as everywhere), call the adapter outside any lock, then re-take the lock to file
+  the flag, mark the files classified and clear the claim, but only if the field still
+  holds the same files and the claim is still theirs (else the result is discarded: the
+  new files have their own classification). The immediate job and the guard can't both
+  classify, and a slow provider never blocks writes to the content's row. A claim expires
+  after **`config.classification_claim_ttl`** (10 minutes): a job that finds a live claim
+  looks once more at its expiry, so a worker that died mid-call is taken over. The mark is
+  a row of the gem's own **`moderate_classifications`** table (record, field, a digest of the
+  ordered blob ids, the claim, `classified_at`, the adapter and whether it flagged; UNIQUE
+  on record + field + digest), written only under the content lock. A changed set (a file
+  added or removed) or the same blob on another record is another row, classified again;
+  nothing of ours is written to `blob.metadata`, so other records sharing a blob and Active
+  Storage's analyzer can't overwrite a claim. `Moderate.purge` deletes rows last touched
+  before its cutoff (`:classifications` in its counts), never one under a live claim
+  (`:claims_kept`). `classification_claim_ttl` must be more than 0 and at most a day, or
+  boot raises. An adapter that raises leaves its claim until it expires and schedules no
+  retry itself; the guard job, a job's recheck at expiry, a new save or the job backend's
+  own retry takes it over. Under **`mode: :block`**, an attachment whose stored blob isn't
+  on the service yet (a direct upload in flight) fails validation with
+  `errors.messages.upload_not_finished` ("hasn't finished uploading yet", en/es) instead of
+  being classified without its file.
+  **If you worked around this** (CarHey's avatar):
+  1. delete the `moderation_field_changed_for_commit?` override that returns `false` for
+     the attachment field;
+  2. delete your own `Moderate::ClassifyJob.perform_later(self, "avatar")` after_commit
+     and the `before_save` that remembered the attachment change, or the field is
+     classified twice;
+  3. the order of `moderates` and `has_one_attached` no longer matters, so the "keep this
+     below the attachment" comments can go. An adapter that retries on
+     `ActiveStorage::FileNotFoundError` may keep doing so; the job's own wait makes it rare.
+- **The appeal window runs from when the person is informed** (DSA Art. 20(2)), not from
+  the decision, and only a confirmed delivery counts. A decision stamps
+  `appeal_deadline_at` six months out, a minimum (its notice's `appeal_deadline_at` is that
+  date: "at least until"). **`Moderate.delivered!(report, :decision | :affected_user, at:)`**,
+  which your notifier calls when the message actually went out (Action Mailer's
+  `after_deliver`; docs/notifications.md), stamps `decision_notified_at` /
+  `affected_user_notified_at` once and moves the deadline to six months after it, never
+  earlier; later calls change nothing. **Behavior change:** those two timestamps are no
+  longer stamped because the notify hook returned something truthy (a queued delivery job
+  is not a delivery), so a host that reads them must call `Moderate.delivered!`.
+- **An appeal filed in time can be decided after the appeal window closes.** The six-month
+  check (`report_must_still_be_appealable`) ran on every save, so `appeal.uphold!` /
+  `reject!` on a complaint filed in month five and decided in month seven failed with "the
+  appeal window for this decision has closed". Art. 20 bounds when a complaint may be
+  filed, not when it is decided; the check now runs when the appeal is created.
+
+### Removed
+
+- **`config.signed_gid_purposes`.** Nothing ever read it: each signed token's purpose is
+  fixed by the flow that mints it. A host initializer that sets it now raises
+  `NoMethodError` at boot; delete the line (the generated initializer only had it
+  commented out).
+- **Rails 7.2 and older, and Ruby 3.2, are no longer supported** (all end of life upstream:
+  Rails 7.2's security support ended in August 2026). The gemspec now requires Ruby 3.3+ and
+  `activerecord` / `activesupport` / `railties` `>= 8.0.5.1, < 9.0` (8.0.5.1 is the first 8.0
+  release with every current Rails security advisory fixed). CI runs Ruby 3.3, 3.4 and 4.0
+  against Rails 8.0 and 8.1 on SQLite, plus PostgreSQL and MySQL, and a `bundler-audit` job
+  checks every lock it tests with. The Rails 7.1 and 7.2 appraisals are gone; the `json < 3`
+  pin moved to the 8.0 appraisal, because Rails 8.0 still passes `quirks_mode:` to
+  `JSON.generate`, which json 3 rejects. A host on 8.0 needs the same pin, with or without
+  `moderate`.
+
+### The 1.0 feature set (since 0.1.0)
+
+A complete, ground-up rewrite. `moderate` graduates from a single-purpose profanity validator
+(0.1.0) into a full **Trust & Safety** engine for Rails apps with user-generated content:
+report, block, filter, a moderation queue, appeals, and EU DSA / App Store / Google Play
+**aligned** primitives (first cut shipped as `1.0.0.beta1`).
+
 - **Reporting.** `Moderate::Report` plus the `has_reportable_content :fields` macro and
   `Actor#report!(reportable, category:, details:)`. Reports and DSA notices share one model
   and one queue (`intake_kind: "community" | "dsa"`).
@@ -40,17 +301,19 @@ Play **aligned** primitives. (First cut ships as `1.0.0.beta1`.)
   at any path, **statement of reasons** (Art. 17), internal **appeals** (Art. 20), and
   **transparency** counters (Art. 24). The notice form prefills from query params + the signed-in
   user, locks auto-filled identity fields, and auto-detects `rails_cloudflare_turnstile`.
-- **Hooks (all no-op by default).** `config.audit`, `config.notify` (returns a delivery boolean
-  used to gate `decision_notified_at`), `config.on_block`, `config.ban_handler`, the
+- **Hooks (all no-op by default).** `config.audit`, `config.notify` (its truthy return marks
+  a DSA notice's receipt as sent; decision notices count as delivered only through
+  `Moderate.delivered!`), `config.on_block`, `config.ban_handler`, the
   host-overridable `config.report_categories`, and `config.notice_human_verification_skip_if` /
   `config.appeal_human_verification_skip_if` for native-app bot-gate carve-outs.
-- **Optional integrations**, all auto-detected at runtime via `defined?`/`respond_to?` and never
-  hard dependencies: madmin, goodmail, telegrama, noticed, rails_cloudflare_turnstile.
+- **Optional integrations**, never hard dependencies: madmin, goodmail, telegrama and noticed are
+  wired through the hooks above (recipes in docs/), and rails_cloudflare_turnstile is
+  detected at runtime by the public forms.
 - **Install tooling.** `rails generate moderate:install` writes a documented initializer and an
-  adaptive migration (uuid/bigint primary keys, jsonb/json/MySQL JSON columns); `moderate:views`
-  ejects the notice form for customization.
+  adaptive migration (uuid/bigint primary keys, jsonb/json/MySQL JSON columns), then copies the
+  gem's own migrations after it; `moderate:views` ejects the notice form for customization.
 
-### Changed
+Design choices that differ from 0.x:
 
 - Taxonomies (report categories, DSA legal reasons, country codes) are now frozen model
   constants with inclusion validations instead of DB `CHECK` constraints — adding or
@@ -63,10 +326,387 @@ Play **aligned** primitives. (First cut ships as `1.0.0.beta1`.)
 
 ### Upgrading from 0.x
 
-- The 0.x profanity validator still loads: `validates :field, moderate: true` continues to work
-  via compatibility shims, so existing apps keep validating. To adopt 1.0, add
-  `has_reporting_and_blocking` to your user model and `has_reportable_content` / `moderates` to your
-  content models, run `rails generate moderate:install`, and migrate.
+> **Breaking:** 1.0 keeps the gem name but is an entirely new API. Pin `~> 0.1` if you relied
+> on the old behavior and are not ready to adopt the new surface.
+
+- `validates :field, moderate: true` still works: it is now the built-in `:wordlist` adapter
+  in `:block` mode (the same check as `moderates :field, with: :wordlist, mode: :block`), so
+  existing apps keep validating. To adopt the rest, add `has_reporting_and_blocking` to your
+  user model and `has_reportable_content` / `moderates` to your content models, run
+  `rails generate moderate:install`, and migrate.
+
+## [1.0.0.beta4] - 2026-10-18
+
+Concurrency fixes, and **one migration**: run `bin/rails db:migrate` after upgrading (see
+_Upgrading from 1.0.0.beta3_ below). No API change.
+
+### Fixed
+
+- **MySQL double enforcement under REPEATABLE READ.** Two moderators enforcing flags on the
+  same content, or banning the same person from two flags at once, could remove the content
+  twice or call the `ban_handler` twice on MySQL. A plain `SELECT` there returns the
+  transaction's consistent snapshot, which may predate the content's or the person's row
+  lock, so the second worker never saw the decision it had waited for. Every check that
+  decides "already done" under a lock (the covering decision and the open report a flag
+  escalates to, whether the content is gone, the per-person prior ban) is now a locking read
+  (`SELECT … FOR UPDATE`), identical on every database; the redundant plain reloads after
+  `with_lock` are gone. A flag escalation that can ban takes the person's row lock right
+  after the content's, before it reads the reports table, so two bans of the same person
+  serialize before either takes a gap lock (MySQL's locking reads take them, and two holders
+  that each insert a report deadlock). PostgreSQL and SQLite were not affected.
+- **One lock order everywhere: flag, then content, then person, then report.**
+  `Flag.flag_for_review!` locked the content and then the waiting flag, the reverse of a
+  flag decision (the flag, then the content), so a review and an enforcement of the same
+  content could deadlock on any database. It now takes no content lock at all (see the next
+  entry); the order is documented once, on `Moderate.with_row_lock`.
+- **At most one pending flag per content and field, enforced by the database.** Two
+  "Flag for review" filings at once could create two pending flags for the same field: a
+  plain "is one already waiting?" read can't see another transaction's flag under MySQL's
+  REPEATABLE READ once the caller's transaction has read anything. `moderate_flags` gets a
+  `pending_key` (`"<flaggable_type>/<flaggable_id>/<field>"` while pending, NULL once closed;
+  the model keeps it in sync on every save, so closing frees it and reopening takes it back)
+  with a unique index. The key compares as bytes everywhere: on MySQL the column is
+  `utf8mb4_bin`, since the default collation ignores case and would make content types that
+  differ only by case (`Post`, `POST`) share one key. `utf8mb4_bin` still ignores trailing
+  spaces (MySQL's PAD SPACE), so `Flag#field` is now stripped wherever it is assigned: a key
+  never differs by them. `Flag.flag!` and `Flag.flag_for_review!` insert and, on the
+  collision, return the flag already waiting, read with a locking read (the latest committed row on
+  every database); no plain read decides anything, and `flag_for_review!` locks only the
+  waiting flag, only on a collision. On MySQL, locking a pending flag (`with_lock`, `lock!`)
+  takes its `pending_key` index entry before its row, the order a colliding insert takes
+  them in, so a filing and a decision on the same field don't deadlock. The one deadlock
+  InnoDB can still pick (an insert's duplicate check queued on the gap a closing flag's index
+  entry moves into) is retried by `Flag.flag!` when it is the whole transaction, and raised
+  as `ActiveRecord::Deadlocked` inside a caller's transaction, which InnoDB rolled back.
+  `Flag.flag!` tries three times, then raises the last failure as it was:
+  `ActiveRecord::Deadlocked` after three deadlocks, `ActiveRecord::RecordNotUnique` only when
+  each collision's waiting flag was decided before it could be joined.
+- **The install migration on Trilogy.** `moderate:install`'s migration now treats Rails'
+  Trilogy adapter as MySQL, as it already did mysql2 (MySQL refuses defaults on JSON columns).
+- **Removal-only enforcement no longer locks the person's row.** Only a decision that can
+  ban takes the account's lock, so removing one message never waits on (or holds up) other
+  work on the author's account.
+
+### Changed
+
+- **While a flag waits on a field, another flag on that field joins it.** `Flag.flag!` (the
+  filters' and `ClassifyJob`'s builder too) returns the waiting flag instead of filing a
+  second one (`flag.previously_new_record?` is false; no second `content_flagged`). A field
+  has one item in the queue; once it's decided, the next flag files anew. Code that relied on
+  several pending flags per field, or that closes flags with `update_column` / `update_all`,
+  must set `pending_key` itself (NULL when not pending).
+
+### Upgrading from 1.0.0.beta3
+
+1. `bin/rails db:migrate`. The engine adds the gem's `db/migrate` to your app's migration
+   paths, so `AddPendingKeyToModerateFlags` runs with your own migrations (don't also copy it
+   with `moderate:install:migrations`; if you already did, the copy runs instead). It adds the
+   column and the unique index, and backfills: on each content and field, the newest pending
+   flag takes the key; older duplicate pending flags from before this release stay pending
+   without one (close them when you can). Before writing any key it has the database group
+   the keys under the column's own collation, and if it would treat two as one (on MySQL,
+   a legacy flag whose field ends in a space against one without) it stops with a message
+   naming each key and its flags, rather than failing on an UPDATE or the index; close all
+   but one of each, or fix the field, and run it again. On MySQL it refuses an existing
+   `pending_key` column that ignores case, giving the `ALTER TABLE` to run. It is the only
+   migration that creates `pending_key`, in every app, so `down` drops the index and the
+   column and leaves the tables `create_moderate_tables` made as they were.
+
+### Changed (installing)
+
+- **`moderate:install` copies the gem's migrations too.** A fresh install gets
+  `create_moderate_tables` (the 1.0.0.beta3 table shape, no `pending_key`) and then, in
+  order, a copy of each of the gem's own migrations, named like
+  `bin/rails moderate:install:migrations` names them (`…_add_pending_key_to_moderate_flags.moderate.rb`).
+  An app holding such copies runs them, and the engine leaves the gem's `db/migrate` out of
+  its paths; from then on, after upgrading, run `bin/rails moderate:install:migrations` and
+  migrate. An app installed without copies (as with beta3) keeps getting the gem's
+  migrations through the engine.
+
+## [1.0.0.beta3] - 2026-10-18
+
+### Added
+
+- **Human labels for reportable fields.** `has_reportable_content :body, :files, labels:
+  { body: "Chat message", files: "Chat photo" }` (and `reportable_fields …, labels:`) names
+  each field once, next to its declaration, so moderators and affected users stop reading raw
+  column names («Body») for what was reported. Resolution: the declared label (a String, or a
+  lambda evaluated at read time) → i18n `moderate.reportable_fields.<model>.<field>` (walking
+  reportable STI parents) → `moderate.reportable_fields.<field>` → `field.humanize`. Read it
+  with `Moderate.reportable_field_label(record_or_class_or_type, field)`,
+  `Report#reported_field_label`, `Flag#field_label`, or `record.reportable_field_label(field)`;
+  labels resolve from the stored type, so they survive the content being deleted. A label key
+  for an undeclared field raises. Hosts that kept their own field → label map can delete it.
+- **Labels everywhere the gem names a field.** The public appeal page shows the reported
+  content's label; the statement-of-reasons payload (`affected_user_decision`, `report_decision`)
+  carries `reported_field` + `reported_field_label`; `report_received` carries both and appends
+  the label to its summary; `content_flagged` and the `flag_decision` audit carry `field_label`,
+  and the `content_flagged` summary prints the label instead of `Type#field`.
+- **Default locale files** (`config/locales/en.yml`, `es.yml`): the appeal page's new string and
+  generic labels for common field names (`body` → "Text"/"Texto", `avatar` → "Profile
+  photo"/"Foto de perfil", …).
+- **Labels for every value list the gem defines, in English and Spanish.**
+  `Moderate.taxonomy_label(kind, value)` names a community category, a DSA legal reason, an
+  EU member state, a content type, a resolution basis, a decision, an intake kind, a report /
+  flag / appeal status, a flag source or mode, or an appeal source in the current locale, from
+  `moderate.<scope>.<value>` (scopes in `Moderate::TAXONOMY_LABEL_SCOPES`), falling back to
+  the value humanized so a host's own category or adapter name still renders. The gem's
+  `config/locales/{en,es}.yml` now carry every value, and a host's translation wins. The
+  public notice form, which always read `moderate.legal_reasons/content_types/member_states`,
+  now shows real copy in both languages. **`Moderate::Report.category_options`** gives a
+  report form's select its `[label, value]` pairs, honoring `config.report_categories`. Hosts
+  that translated the regulator's vocabulary themselves can drop their copies for en/es.
+- **An in-app report's details are optional.** A community report with a blank message now
+  files with the category's label (in the reporter's language) as its message, instead of
+  failing "Message can't be blank": the category a person picked is the reason. A DSA notice
+  still needs its own explanation (Art. 16(2)(a)). Hosts that filled the message with the
+  category label themselves, or whose forms said "optional" while the gem refused it, can
+  stop.
+- **"Report and block": `report!(…, block: true)`** blocks the person responsible for the
+  content in the same transaction as the report (both or neither; the receipt goes out
+  after), through the one block path (idempotent, audited, `on_block`, `user_blocked`). `Report#block_reported_user`, which has existed since beta1
+  and which nothing read, is what it sets. Nothing is blocked when the content has no person
+  behind it.
+- **Reports know what kind of content they're about.** A community report with no
+  `content_type` takes the reportable's `moderation_content_type` (with or without the field
+  argument, since chats' takes none), stored if it is one of `Report::CONTENT_TYPES`, else
+  `"other"`, so a host's own word never fails an intake. `Moderate::Reportable` defines it
+  (nil) and `Moderate::Actor` answers `"user_profile"`. Hosts that mapped their models to
+  content types in the report controller can delete the map.
+- **`Reportable#to_moderation_sgid`** and the view helper
+  **`moderate_report_target_path(record, field:)`**: the signed report target and the report
+  form's path, public and non-expiring, for markup rendered once for many viewers (a chat
+  bubble broadcast to everyone in the thread, a fragment cache), where
+  `moderate_report_link`'s per-viewer check can't run. The helper always probed for
+  `to_moderation_sgid`; now it exists. Hosts building
+  `to_sgid_param(for: Moderate::Report::SIGNED_GLOBAL_ID_PURPOSE)` by hand can use these
+  (without `expires_in: nil`, that token changed on every render and died after a month).
+- **The `content_removed` event is emitted.** It was in the documented vocabulary from
+  beta1 and nothing sent it. A decision whose `remove_reported_field!` removed something now
+  audits `content_removed` inside the decision's transaction and announces it with the
+  decision notices, to the content's person, with `reported_field`, its label and the
+  moderator's reason. (`notice_received`, which the DSA form has always sent, joins the
+  vocabulary lists in the README, the configuration guide and the initializer.)
+- **`examples/regexp_pattern_adapter.rb`**: a reference adapter for what a word list can't
+  express (phone numbers, links, "contact me on…"), each pattern filed under the category it
+  means, synchronous so `:block` works too, the matched fragments in `raw[:matches]`. The
+  idea is @killondark's (#1, written against the 0.x validator).
+- **Enforce from a flag.** `flag.action!(by:, note:, remove_content: true)` and
+  `flag.action!(by:, note:, ban_user: true)` (any combination, plus `resolution_basis:`)
+  escalate to a report and resolve it: the newest open report on the same content and field
+  if a person already filed one, else a system report (no reporter, so no receipt and no
+  reporter-facing decision). Content is removed through the reportable's
+  `remove_reported_field!`, the ban goes through your `ban_handler`, and the affected user
+  gets the statement of reasons and the appeal window a restriction requires. It runs under
+  the flag's row lock and then the content's, so two moderators enforcing the same flag, or
+  two flags on the same content, enforce once: the second closes against the decision the
+  first took (unless it asks for more, say a ban after a removal). A recorded removal only
+  counts if the content is gone now, so an older decision that said "removed" without
+  removing anything doesn't stand in for a real one. A system report may name the flag's
+  field even when people can't report that field (a filtered image) — an exception only
+  the escalation sets, on a report with no reporter, never on a DSA notice — and
+  enforcing a classifier's flag through a person's earlier report adds the classifier to
+  that report's automated-means disclosure. `flag.report` is the report it went through.
+  Hosts that hand-wrote this bridge (find-or-create a report, resolve it, then close the
+  flag) can delete it. Without those options `action!` is the triage close it was.
+- **`Moderate::Flag.flag_for_review!(record, field:, by:, note: nil)`**: an administrator
+  filing content for review by hand (the "Flag for review" button on a transcript line). It
+  returns the pending flag on that field if one already waits, else files a
+  `source: "manual"` flag owned by the content's person, with the evidence snapshot as
+  excerpt and `context` naming who filed it; `flag.previously_new_record?` says which. The
+  check and the insert run under the record's row lock, so two administrators pressing it
+  together file one flag. Audited as `:flag_filed`. Hosts that hand-assembled the nine
+  `Flag.flag!` arguments (and, without a lock, could file two) can call this instead.
+- **`Flag#resolve!`**, an alias of `action!`: reports and flags now share one verb and one
+  keyword contract, which is what `Moderate::Moderation#resolve` and `docs/madmin.md`
+  always assumed.
+
+### Changed
+
+- **`Flag#action!` / `#dismiss!` go through `Moderate::Services::ResolveFlag`.** The beta2
+  model methods were a second closing path with no row lock and no `flag_decision` audit;
+  now there is one. Re-closing an already decided flag returns it unchanged (as the service
+  always did) instead of overwriting the first decision.
+- **`ResolveReport.new(report, by:, deliver: false)`** holds the decision notices back for a
+  caller that decides inside a lock of its own; `#deliver_decision_notices` sends them.
+- **Notices follow Active Record's after_commit rules, on every supported Rails.** Report,
+  flag and appeal decisions (with their `user_banned` and `content_removed`), the in-app
+  report receipt, and `user_blocked` / `user_unblocked` are owned by the transaction they
+  were queued in (`Moderate::DeferredNotices`, `record.after_commit_notice { … }`): each is
+  enrolled in the current transaction as a transaction record, exactly as a saved record
+  is, so the transaction sends it on commit and drops it on rollback or when an exception
+  ends it. Nested transactions and savepoints under a joinable parent send at the
+  outermost commit; a rolled-back savepoint drops only its own; under a parent that isn't
+  joinable (including the wrapper of Rails' transactional tests) it's sent at the
+  savepoint's release, when after_commit runs too; with no transaction open, at once.
+  Under multiple databases or shards, the notice joins the transaction of the connection
+  it's queued on: `record.after_commit_notice(on: connection) { … }`, `on:` defaulting to
+  the record class's connection at call time. Queue it inside the transaction that saved
+  the record, on that transaction's connection. The gem's services do: each captures its
+  model's connection at the top of its transaction, before any save, and passes it to
+  every notice it queues, so a host callback that switches databases or shards mid-save
+  can't move them. A host that calls `after_commit_notice` itself passes `on:` when it uses
+  `connected_to`.
+  Nothing lives on a record instance or on the thread. A host that decides, reports or
+  blocks inside a transaction of its own and rolls it back tells nobody; Rails 7.1, 7.2 and
+  8.x behave the same. `Moderate.apply_ban(…, announce: false)` +
+  `Moderate.announce_ban` split the ban's notice from the ban for the same reason. (The
+  public notice and appeal forms' own receipts are unchanged.)
+- **One lock order for enforcement: flag, then content, then the person (for a ban), then
+  the report.** Row locks are taken by query (`Moderate.with_row_lock`), so concurrent
+  decisions on the same content, or bans of the same person from different content,
+  serialize instead of enforcing twice or deadlocking.
+- **One ban per person per episode.** A decision asked to ban someone who a decision on
+  any content or field has already banned since this conduct was raised (the report's
+  creation; the flag's, for an escalation) doesn't call the `ban_handler` again: it records
+  `resolution_actions["ban_already_applied_by"]` with that decision's id. An older ban
+  doesn't count (the person may have been unbanned since).
+- **A manual flag is not automated means.** A report's automated-processing disclosure
+  (DSA Art. 17(3)(c)) no longer counts `source: "manual"` flags on the same content.
+
+- **Removing content that isn't removable refuses the decision.** `remove_content: true`
+  when the reportable's `remove_reported_field!` removes nothing (the default for a
+  reportable that defines no removal, a field that isn't removable, content already gone),
+  when the content was deleted (the report's reportable is nil), or when the reportable has
+  no removal method at all, now raises `RecordInvalid` ("Nothing was removed…", `moderate.errors.nothing_removed`)
+  and rolls the decision back, a ban with it. Before, the report was closed with
+  `decision_visibility: "content_removed"` and the affected person was told their content
+  was removed while it was still up. **Behavior change:** offer "remove content" only where
+  `removable_reported_field?` says it can happen.
+- **A ban needs a `ban_handler`.** With none configured, `ban_user: true` (on a report or a
+  flag) and `Moderate.apply_ban` raise `Moderate::ConfigurationError` before anything
+  changes. Before, the default no-op handler let the decision record
+  `decision_visibility: "account_suspended"`, audit and announce `user_banned`, and send the
+  person a statement of reasons saying their account was suspended, while nothing had
+  suspended it: a false Art. 17 statement. `config.ban_handler = nil` restores the default;
+  a non-callable raises `ArgumentError`; `config.ban_handler_configured?` tells. Decisions
+  without a ban are unaffected. **Behavior change** for hosts that never wired one and
+  relied on the no-op.
+- **An in-app report is refused when its reporter may not report the content.** A community
+  report filed by a signed-in person now validates the reportable's own `report_visible_to?`
+  (never your own content; for a chats message, only a conversation you're in), with an
+  error on `:reportable` ("isn't something you can report",
+  `moderate.errors.not_reportable_by_reporter`). The report link always hid itself on that
+  rule, and chats' docs said moderate re-checks it server-side, but nothing did: a signed
+  target replayed or pasted from elsewhere reached the model unchecked. DSA notices and
+  system reports (no reporter) are not affected. **Behavior change:** a host that files
+  community reports on behalf of people who couldn't see the content now gets a validation
+  error; use a manual flag (`Flag.flag_for_review!`) for an administrator's own concern.
+
+### Fixed
+
+- **`moderate_report_target_path` (and `moderate_report_link`) find the host's report route
+  from inside another engine's views**, through `main_app`. Rendered in a chats slot, the
+  helper fell back to the hard-coded `/reports/new`.
+- **The transparency page labels its counters from the gem's own keys.** Two of its cards
+  read `moderation.legal_reasons.*` / `moderation.resolution_bases.*`, a namespace from the
+  app the gem was extracted from that no other part of the gem uses; the rest printed raw
+  values humanized. Every card now goes through `Moderate.taxonomy_label`.
+- **`Moderate.blocked_ids_for(nil)` returns the same type as every other call**: an empty
+  relation selecting user ids, not `[]`. Composing the two shapes was a real bug in a host
+  (`relation | array` yields User records, and `include?(id)` silently missed). Call `.ids`
+  for an Array.
+- **`Report#pending?` and `Appeal#pending?`** exist, twins of the `pending` scopes all three
+  queues share (`docs/madmin.md` called them and they didn't exist).
+- **`Moderate::Moderation#resolve` works on flags.** It called `record.resolve!`, which
+  `Moderate::Flag` didn't have, so a host following the concern's own documentation got a
+  `NoMethodError` (as an alert flash) on every flag. It also passes `resolution_basis` when
+  the form sends one, and its flash says "Flag actioned." / "Flag dismissed." for flags.
+- **Content spoken by something that isn't a person no longer breaks reports and flags.**
+  moderate stored `reportable.reported_owner` straight into `Report#reported_user` and
+  `Flag#owner`, both associations to `config.user_class`. A support desk or a bot behind the
+  content (chats answers `author || sender`, which is a desk for an unsigned support reply)
+  raised `ActiveRecord::AssociationTypeMismatch` and the report never filed. The new
+  `Moderate.responsible_user(record)` keeps the owner only if it is a person; anything else
+  means "nobody to reach": the report files, the evidence is kept, content can still be
+  removed, and only a decision notice or a ban has no addressee. Report intake, `Flag.flag!`,
+  the `:flag` after_commit and `ClassifyJob` all go through it. A reportable that never
+  defined `reported_owner` still raises at the first report. Hosts that overrode
+  `Chats::Message#reported_owner` to return nil for non-users can delete the override.
+- **The gem's locale files can no longer override the host's.** The engine appended its
+  `config/locales` to `config.i18n.load_path`, which Rails loads AFTER the app's own locale
+  files — harmless while the directory was empty, but any shipped default would have silently
+  beaten the host's translation of the same key. Rails already loads an engine's
+  `config/locales` before the app's, so the initializer is gone.
+
+### Documentation
+
+- **`docs/chats.md`**: the whole chats integration from moderate's side (reportable and
+  filtered messages, blocks, Report on a broadcast bubble, Block in the thread menu, the
+  admin side, a launch checklist), the shape two production hosts converged on.
+- **`docs/madmin.md` runs as written.** It called `scope :resolved` (the scopes are
+  `actioned`), `attribute :kind` / `:details` (the columns are `intake_kind` / `message`),
+  `report.pending?` (now real), `Moderate.system_actor` (never existed; automated decisions
+  pass `by: nil`) and `flag.scores[:csam]` (scores are JSON with string keys, and the
+  canonical category is `sexual/minors`). The flag controller now shows enforcement, and a
+  new section covers "Flag for review" from a browse screen.
+
+### Upgrading from 1.0.0.beta2
+
+No migrations. Check these against your app:
+
+1. **Wire `config.ban_handler`** if any moderator can press "ban": without one, a ban now
+   raises instead of being a silent no-op.
+2. **Reports are visibility-checked.** If you file community reports with a `reporter:` who
+   couldn't see the content, they now fail validation. Use `Flag.flag_for_review!` for an
+   administrator's own concern.
+3. **Delete the workarounds this release makes unnecessary**, if you wrote them:
+   - a `reported_owner` override that returns nil for non-users;
+   - a find-or-create-report bridge for removing or banning from a flag (use
+     `flag.action!(remove_content:, ban_user:)`);
+   - a hand-assembled manual `Flag.flag!` (use `Flag.flag_for_review!`);
+   - a model-to-`content_type` map in your report controller;
+   - your own "report and block" (use `report!(…, block: true)`);
+   - `to_sgid_param(for: Moderate::Report::SIGNED_GLOBAL_ID_PURPOSE)` (use
+     `to_moderation_sgid` or `moderate_report_target_path`);
+   - en/es translations of the gem's taxonomies and field names (keep only the ones you
+     changed);
+   - a duplicated `config.filter` next to a `moderates` declaration for the same field.
+4. **"Remove content" must remove something.** If your admin offers it on content whose
+   `remove_reported_field!` returns false, those decisions now fail instead of claiming a
+   removal. Gate the checkbox on `removable_reported_field?`.
+5. **`Flag#action!` re-closing** an already decided flag no longer overwrites the first
+   decision: it returns the flag as it was.
+6. **`Moderate.blocked_ids_for(nil)`** is an empty relation, not `[]`. Call `.ids` if you
+   need an Array.
+
+## [1.0.0.beta2] - 2026-07-10
+
+Second beta on the road to 1.0. Fixes beta1's async-adapter routing bug (the one
+that forced hosts to hand-roll their own enqueue), makes Active Storage
+attachments filterable with zero wiring, and gives `Flag` first-class close
+methods. Drop-in upgrade from beta1: no migrations, no breaking API changes —
+and hosts that worked around the ClassifyJob bug can now delete the workaround.
+
+### Fixed
+
+- **Async adapters now actually run in `Moderate::ClassifyJob`.** beta1's `:flag`
+  after_commit called `Moderate.classify` inline for *every* adapter — including
+  ones declaring `synchronous? == false` — so a remote moderation API ran its
+  network call inside the request that saved the content, and `ClassifyJob`
+  (whose docs promised this routing) was never enqueued by anything. The concern
+  now checks `config.adapter_async?(policy.adapter)` (new public helper, same
+  probe as the `:block` validator) and enqueues the job instead; the job re-reads
+  the persisted value and files the Flag itself. Hosts that worked around this by
+  enqueuing `ClassifyJob` themselves and short-circuiting
+  `moderation_field_changed_for_commit?` can delete both workarounds. (#3)
+
+### Added
+
+- **Active Storage attachments filter out of the box.** `moderates :avatar, with:
+  :your_image_adapter, mode: :flag` on a `has_one_attached` model needs zero extra
+  wiring now: the concern snapshots `attachment_changes` in a `before_save` (AR
+  dirty tracking can't see attachment writes, and Active Storage clears the
+  changes before after_commit), consumes the snapshot at commit time, and both
+  the concern and `ClassifyJob` treat an unattached `ActiveStorage::Attached`
+  proxy as blank (nothing to classify — covers purge-between-enqueue-and-run).
+  The three `moderation_field_*` seam overrides remain for richer cases. (#3)
+- **Flag close sugar.** `Flag#action!(note:, by: nil)` / `Flag#dismiss!(note:, by: nil)` —
+  model-level closes mirroring `Report#resolve!`/`#dismiss!`, so hosts stop hand-writing
+  status updates. `by:` stays nil for automated closes (don't fake a human in the audit
+  trail). Canonical automated use: dismiss a pending flag whose flagged content was
+  **superseded** (text edited, photo replaced/reverted) — left pending it keeps `flagged?`
+  true and mislabels the NEW content in any host UI keyed on it. (#4)
 
 ## [0.1.0] - 2024-11-03