moderate 0.1.0 → 1.0.0.beta1

data/lib/moderate/configuration.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Moderate
+  # The single configuration object the host populates in
+  # `config/initializers/moderate.rb` via `Moderate.configure do |config| ... end`.
+  #
+  # Design rules, straight from docs/configuration.md:
+  #   - Config is read AT THE POINT OF USE, not frozen at boot. Class names are
+  #     stored as strings and constantized lazily, so the initializer works no
+  #     matter when the app loads (the User model may not exist yet at boot).
+  #   - Validating setters normalize their input (`to_s.strip.downcase.to_sym`) so
+  #     "Block", :block and " block " all mean the same thing, and raise a
+  #     plain-English ArgumentError on a bad value — failing fast at the assignment
+  #     line. `validate!` runs once more at the end of `configure` for cross-field
+  #     checks (e.g. a :block filter pointed at an async adapter).
+  #   - Every hook (`audit`/`notify`/`on_block`/`ban_handler`) defaults to a no-op,
+  #     so the gem works untouched and a host wires hooks only as needed.
+  #
+  # This mirrors the validating-setter convention across the ecosystem
+  # (usage_credits' `default_currency=`, wallets' `default_asset=`).
+  class Configuration
+    # The three filter modes a `moderates :field` / `config.filter` can use.
+    #   :off   — no check
+    #   :block — reject the save with a validation error if the filter trips
+    #   :flag  — allow the save, create a Moderate::Flag after commit for review
+    # Order matters for the error message ("must be one of: off, block, flag").
+    FILTER_MODES = %i[off block flag].freeze
+
+    # A per-(class, field) filter policy. `class_name` is stored as a STRING and
+    # constantized lazily by the consumer, same as `user_class`, so declaring a
+    # filter for a model that isn't loaded yet is fine. `adapter` is the adapter
+    # NAME (a symbol) resolved against the adapters registry at classify time —
+    # never the adapter object itself, so swapping a backend is a one-line change.
+    FilterPolicy = Data.define(:class_name, :field, :adapter, :mode) do
+      def off? = mode == :off
+      def block? = mode == :block
+      def flag? = mode == :flag
+    end
+
+    # --- Identity -------------------------------------------------------------
+    attr_reader :user_class
+
+    # --- Filtering ------------------------------------------------------------
+    attr_reader :default_filter_mode, :filter_adapter
+    attr_accessor :additional_words, :excluded_words
+    attr_reader :adapters, :filters
+
+    # --- Taxonomy (host-customizable) -----------------------------------------
+    # Override the in-app COMMUNITY report category list. nil ⇒ the gem default
+    # (Moderate::Report::DEFAULT_CATEGORIES). Adding a category here requires NO
+    # migration: `category` is validated in the model (Moderate::Report), not by a DB
+    # check constraint. (The DSA legal-reason/country taxonomies are regulator-defined
+    # and NOT overridable.) A plain accessor — any value here is coerced to strings and
+    # compared at validation time by Report.report_categories.
+    attr_accessor :report_categories
+
+    # --- Hooks (all no-op by default) ----------------------------------------
+    attr_accessor :audit, :notify, :on_block, :ban_handler
+
+    # --- Misc -----------------------------------------------------------------
+    attr_accessor :locale
+
+    # --- DSA notice form ------------------------------------------------------
+    # Documented in docs/dsa-notice-form.md. Held here so the engine/controller
+    # (written by other components) read them off the same Configuration object.
+    # `notice_guard` is the gem-absent fallback bot gate (see
+    # app/controllers/moderate/notices_controller.rb#verify_human!): a proc that
+    # receives the controller and returns truthy to allow the POST. nil/no-op ⇒ the
+    # form just works (the default). When the host installs `rails_cloudflare_turnstile`,
+    # the controller auto-uses Turnstile instead and this proc is bypassed.
+    attr_reader :parent_controller
+    attr_accessor :notice_form_enabled, :notice_rate_limit,
+                  :notice_turnstile_site_key, :notice_turnstile_secret_key,
+                  :notice_captcha_verifier, :notice_guard, :notice_human_verification_skip_if,
+                  :appeal_form_enabled, :appeal_rate_limit, :appeal_guard,
+                  :appeal_human_verification_skip_if, :appeal_return_path,
+                  :transparency_report_enabled,
+                  :signed_gid_purposes
+
+    def initialize
+      # Identity. "User" is the overwhelmingly common case; the host overrides it
+      # if their actor model is "Account", "Member", etc.
+      @user_class = "User"
+
+      # Filtering defaults. :block is the safe default per docs (reject objectionable
+      # writes); :wordlist is the offline, zero-dependency default text adapter.
+      @default_filter_mode = :block
+      @filter_adapter = :wordlist
+      @additional_words = []
+      @excluded_words = []
+
+      # Community report category override. nil ⇒ Moderate::Report::DEFAULT_CATEGORIES.
+      # No migration needed to add a category — `category` is validated in the model.
+      @report_categories = nil
+
+      # Adapters registry: name (Symbol) => adapter (an object responding to
+      # `classify`, OR a String class name to constantize lazily at use time, so we
+      # don't force the built-in adapter files to be loaded before the initializer
+      # runs). Seeded with the ONE built-in (the offline :wordlist) the README
+      # documents; OpenAI/Rekognition/etc. are reference adapters in examples/ a host
+      # copies in and registers — they are not shipped, loaded, or a dependency.
+      #
+      # The class behind this name is the gem's own adapter; we reference it by string
+      # to keep this file decoupled from its load order (and there is no
+      # `Moderate::Adapters` alias namespace — point straight at the Filters class).
+      @adapters = {
+        wordlist: "Moderate::Filters::Wordlist"
+      }
+
+      # Per-field filter policies, keyed by [class_name_string, field_string].
+      @filters = {}
+
+      # Hooks — no-ops by default. These exact signatures are documented:
+      #   audit/notify take a single Moderate::Event
+      #   on_block/ban_handler take keyword args
+      @audit = ->(_event) {}
+      @notify = ->(_event) {}
+      @on_block = ->(blocker:, blocked:, at:) {}
+      @ban_handler = ->(user:, by:, reason:) {}
+
+      # Misc. nil locale ⇒ follow I18n.default_locale at use time.
+      @locale = nil
+
+      # Engine controller defaults. The parent controller defaults to a stock base so
+      # the engine works even on API-only apps — the same `parent_controller`
+      # indirection Devise and api_keys use.
+      @parent_controller = "::ActionController::Base"
+
+      # DSA notice-form defaults (see docs/dsa-notice-form.md). The form is on by
+      # default; both bot-gates no-op when their keys are blank; the rate limit is a
+      # sane per-IP throttle.
+      @notice_form_enabled = true
+      @notice_rate_limit = { max: 5, within: 3600 } # 1.hour, expressed in seconds to avoid an ActiveSupport dependency here
+      @notice_turnstile_site_key = nil
+      @notice_turnstile_secret_key = nil
+      @notice_captcha_verifier = nil
+      # Gem-absent fallback bot gate. nil ⇒ no extra gate (the form just works); the
+      # controller only consults it when rails_cloudflare_turnstile is NOT installed.
+      @notice_guard = nil
+      @notice_human_verification_skip_if = nil
+
+      # DSA internal complaint / appeal form defaults. Same shape as the notice
+      # form: public route, optional bot gate, runtime rate limit, and a redirect
+      # target the host can choose.
+      @appeal_form_enabled = true
+      @appeal_rate_limit = { max: 10, within: 60 }
+      @appeal_guard = nil
+      @appeal_human_verification_skip_if = nil
+      @appeal_return_path = "/"
+
+      # The public Art. 24 transparency report. OFF by default — opt in with
+      # `config.transparency_report_enabled = true`. A *live* transparency portal is
+      # not itself a legal requirement: the DSA obligation is to *publish* a report at
+      # least annually (a static page/file is fine), and micro/small enterprises are
+      # exempt from the transparency tier entirely (Art. 15(2) / Art. 19). So we don't
+      # publicly expose moderation counts unless the host explicitly turns it on. When
+      # off, the mounted `/transparency` route 404s; the aggregation stays queryable in
+      # code so a host can still build/publish its own report.
+      @transparency_report_enabled = false
+
+      @signed_gid_purposes = %i[appeal confirm_notice unsubscribe]
+    end
+
+    def parent_controller=(value)
+      name = value.is_a?(Class) ? value.name : value.to_s
+      raise ArgumentError, "parent_controller can't be blank" if name.strip.empty?
+
+      @parent_controller = name
+    end
+
+    # --- Validating setters ---------------------------------------------------
+
+    # user_class is stored as a String (constantized lazily by `Moderate.user_class`).
+    # We accept a Class or a String and reject blanks, so a `nil`/"" slip surfaces
+    # at the assignment line instead of as a cryptic NameError much later.
+    def user_class=(value)
+      name = value.is_a?(Class) ? value.name : value.to_s
+      raise ArgumentError, "user_class can't be blank" if name.strip.empty?
+
+      @user_class = name
+    end
+
+    # default_filter_mode normalizes and validates against FILTER_MODES.
+    def default_filter_mode=(value)
+      @default_filter_mode = normalize_mode(value)
+    end
+
+    # filter_adapter normalizes to a symbol; existence is checked in `validate!`
+    # (it may legitimately name an adapter the host registers later in the same
+    # block, so we can't insist it already exists at assignment time).
+    def filter_adapter=(value)
+      @filter_adapter = normalize_name(value)
+    end
+
+    # --- Adapters -------------------------------------------------------------
+
+    # Register a host adapter under a name of the host's choosing. The adapter is
+    # any object responding to `classify(value) → Moderate::Result`. The name is
+    # what gets recorded as `Moderate::Flag#source`, so it shows in the queue.
+    #
+    # Both arg orders are accepted for ergonomics:
+    #   config.register_adapter :openai, OpenAIModerator.new
+    #   config.register_adapter(:openai, OpenAIModerator.new)
+    def register_adapter(name, adapter)
+      key = normalize_name(name)
+      unless adapter.is_a?(String) || adapter.is_a?(Class) || adapter.respond_to?(:classify)
+        raise ArgumentError, "adapter for #{key.inspect} must respond to #classify"
+      end
+
+      @adapters[key] = adapter
+    end
+
+    # Look up a registered adapter object by name, constantizing a String/Class
+    # reference (the built-ins) on first use. Returns nil for an unknown name —
+    # callers decide whether that's an error (the validator/classify path raises a
+    # helpful message; see Moderate.classify).
+    def adapter_for(name)
+      key = normalize_name(name)
+      ref = @adapters[key]
+      return nil if ref.nil?
+
+      resolve_adapter(ref).tap do |adapter|
+        @adapters[key] = adapter unless adapter.equal?(ref)
+      end
+    end
+
+    def adapter_registered?(name)
+      @adapters.key?(normalize_name(name))
+    end
+
+    # --- Filters --------------------------------------------------------------
+
+    # Declare a per-field filter policy in the initializer — the twin of
+    # `moderates :field, with:, mode:` on the model. Stores the policy keyed by
+    # [class_name, field] so `filter_policy_for` can resolve it (including up the
+    # ancestor chain) at classify time.
+    def filter(class_name, field, with: nil, mode: nil)
+      name = class_name.is_a?(Class) ? class_name.name : class_name.to_s
+      field_s = field.to_s
+      adapter = with.nil? ? @filter_adapter : normalize_name(with)
+      resolved_mode = mode.nil? ? @default_filter_mode : normalize_mode(mode)
+
+      policy = FilterPolicy.new(class_name: name, field: field_s, adapter: adapter, mode: resolved_mode)
+      @filters[[name, field_s]] = policy
+      policy
+    end
+
+    # --- Validation -----------------------------------------------------------
+
+    # Cross-field validation run at the end of `Moderate.configure`. The per-setter
+    # checks already caught most typos; this catches the things that need the whole
+    # block resolved:
+    #   - the default text adapter must actually be registered
+    #   - every per-field filter must name a registered adapter
+    #   - a :block-mode filter must use a SYNCHRONOUS adapter — you can't reject a
+    #     save on a background result, so :block + an async adapter (e.g. a remote
+    #     classifier) is a configuration error. Async adapters run in :flag mode.
+    #     (README: "`:block` requires a synchronous adapter".)
+    def validate!
+      validate_adapter_name!(@filter_adapter, context: "filter_adapter")
+
+      @filters.each_value do |policy|
+        validate_adapter_name!(policy.adapter, context: "filter #{policy.class_name}##{policy.field}")
+        validate_block_mode_adapter!(policy)
+      end
+
+      true
+    end
+
+    private
+
+    # Normalize a free-form mode into one of FILTER_MODES, raising a plain-English
+    # ArgumentError otherwise. The normalization ("Block"/" block " → :block) is
+    # the ecosystem-wide convention.
+    def normalize_mode(value)
+      mode = value.to_s.strip.downcase.to_sym
+      unless FILTER_MODES.include?(mode)
+        raise ArgumentError, "default_filter_mode must be one of: #{FILTER_MODES.join(', ')}"
+      end
+
+      mode
+    end
+
+    def normalize_name(value)
+      value.to_s.strip.downcase.to_sym
+    end
+
+    def validate_adapter_name!(name, context:)
+      return if adapter_registered?(name)
+
+      raise ArgumentError,
+        "unknown filter adapter #{name.inspect} for #{context} — the only built-in is :wordlist; " \
+        "register your own with `config.register_adapter #{name.inspect}, MyAdapter.new`"
+    end
+
+    # A :block filter needs a synchronous adapter. We treat an adapter as
+    # synchronous unless it explicitly declares `synchronous? == false` (an adapter
+    # may expose a `synchronous?`/`async?` predicate — the built-in Filters::Base
+    # does — and we honor it). Adapters that don't answer the predicate are assumed
+    # synchronous — the conservative default that keeps simple adapters working.
+    def validate_block_mode_adapter!(policy)
+      return unless policy.block?
+
+      adapter = resolve_adapter_safely(policy.adapter)
+      return if adapter.nil? # unknown adapter already raised above
+
+      return unless adapter.respond_to?(:synchronous?)
+      return if adapter.synchronous?
+
+      raise ConfigurationError,
+        "filter #{policy.class_name}##{policy.field} uses mode :block with the async adapter " \
+        "#{policy.adapter.inspect}. :block must reject a save synchronously, which an async adapter " \
+        "can't do — use mode: :flag (allow the write, classify in a job, file a Moderate::Flag)."
+    end
+
+    # Turn an adapters-registry value into an adapter object. Strings/Classes are
+    # constantized and used directly when they expose class-level `classify`
+    # (Moderate::Filters::Base style), otherwise instantiated so a host can
+    # register a plain class whose instances implement `#classify`.
+    def resolve_adapter(ref)
+      adapter = case ref
+      when String then ref.constantize
+      when Class then ref
+      else
+        return ref
+      end
+
+      adapter.respond_to?(:classify) ? adapter : adapter.new
+    end
+
+    # Like resolve_adapter but never raises (a built-in whose file isn't loaded yet
+    # shouldn't blow up validation) — returns nil if it can't be resolved.
+    def resolve_adapter_safely(name)
+      adapter_for(name)
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/moderate/engine.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Moderate
+  # The Rails engine that wires `moderate` into a host app.
+  #
+  # It's an ISOLATED engine (`isolate_namespace Moderate`) for the same reason
+  # Devise's is: the gem ships a mountable public DSA notice form
+  # (`mount Moderate::Engine => "/legal"`, see docs/dsa-notice-form.md) with its
+  # own controllers, views, helpers, and `moderate_`-prefixed tables. Isolation
+  # keeps every one of those from colliding with the host app's namespace, and
+  # gives the host the `moderate.` URL-helper proxy for the mounted routes.
+  #
+  # NOTE: the engine is intentionally thin. The host can use the whole gem
+  # (reporting, blocking, filtering, the queue) WITHOUT mounting anything — the
+  # mount is only needed for the public Art. 16 notice form. Everything here is
+  # plumbing that runs whether or not the engine is mounted.
+  class Engine < ::Rails::Engine
+    isolate_namespace Moderate
+
+    # The autoloadable code that needs the host's ActiveRecord/ApplicationRecord and
+    # the host's `config.user_class` to exist before it loads — the four AR models,
+    # the three model concerns, the async classify job, the filter adapters, and the
+    # service objects — lives under `lib/moderate/{models,jobs,filters,services}`,
+    # NOT under the engine's `app/` tree. That's a deliberate gem-packaging choice
+    # (everything ships under `lib/`), but it means we have to teach the host's
+    # Zeitwerk loader about that subtree ourselves, with three corrections:
+    #
+    #   1. NAMESPACE. A bare `eager_load_paths << ".../lib/moderate"` would map the
+    #      directory to the TOP-LEVEL namespace, so Zeitwerk would expect
+    #      `lib/moderate/configuration.rb` to define `::Configuration` (not
+    #      `Moderate::Configuration`) and blow up with "uninitialized constant
+    #      Configuration" during eager load. We push the dir mapped to the `Moderate`
+    #      module instead, so `lib/moderate/models/report.rb` → `Moderate::Report`.
+    #      (Zeitwerk's `push_dir(path, namespace:)` is exactly for this — see
+    #      https://github.com/fxn/zeitwerk#custom-root-namespaces.)
+    #
+    #   2. COLLAPSED DIRECTORIES. `models/`, `models/concerns/`, and `jobs/` are
+    #      organizational, not namespace, segments — `report.rb` must be
+    #      `Moderate::Report`, NOT `Moderate::Models::Report`; `actor.rb` must be
+    #      `Moderate::Actor`, not `Moderate::Models::Concerns::Actor`. We `collapse`
+    #      them so they contribute no namespace. (`services/` and `filters/` are
+    #      KEPT, because the code intentionally namespaces `Moderate::Services::*`
+    #      and `Moderate::Filters::*`.)
+    #
+    #   3. IGNORED FILES. The gem's SPINE (`version`, `errors`, `label`, `result`,
+    #      `event`, `configuration`, `engine`, `macros`) is `require_relative`'d from
+    #      `lib/moderate.rb` so the value objects work in a plain-Ruby context with
+    #      no Rails — those files MUST NOT also be managed by Zeitwerk (a constant
+    #      can't be both manually required and autoloaded). The 0.x compatibility
+    #      shims (`text`, `text_validator`, `word_list`) are ignored too: they either
+    #      define non-conventional constants (`text_validator.rb` reopens
+    #      `ActiveModel::Validations`, not a `Moderate::*` constant) or are legacy and
+    #      loaded only on demand.
+    #
+    # We do this on the host's MAIN autoloader (`Rails.autoloaders.main`) inside an
+    # initializer scheduled BEFORE `:set_autoload_paths`, the same point Rails wires
+    # up its own roots — so our `push_dir`/`collapse`/`ignore` are in place before
+    # Zeitwerk's `setup`/`eager_load` ever run.
+    LIB_ROOT = File.expand_path("..", __dir__) # => .../lib
+    MODERATE_LIB = File.expand_path("moderate", LIB_ROOT) # => .../lib/moderate
+
+    # Spine + 0.x-compat files Zeitwerk must NOT manage (they're require_relative'd
+    # from the spine or define non-conventional constants).
+    ZEITWERK_IGNORED = %w[
+      version.rb errors.rb label.rb result.rb event.rb
+      configuration.rb engine.rb macros.rb
+      text.rb text_validator.rb word_list.rb
+    ].freeze
+
+    initializer "moderate.autoload", before: :set_autoload_paths do
+      loader = Rails.autoloaders.main
+
+      # Files the spine already requires (or that define top-level constants) — tell
+      # Zeitwerk to leave them alone so it doesn't try to (re)manage their constants.
+      ZEITWERK_IGNORED.each do |file|
+        path = File.join(MODERATE_LIB, file)
+        loader.ignore(path) if File.exist?(path)
+      end
+
+      # `models`, `models/concerns`, and `jobs` are organizational dirs that must not
+      # appear in the constant path (Moderate::Report, not Moderate::Models::Report).
+      %w[models models/concerns jobs].each do |dir|
+        path = File.join(MODERATE_LIB, dir)
+        loader.collapse(path) if File.directory?(path)
+      end
+
+      # Push lib/moderate as an autoload root mapped to the Moderate namespace, so
+      # lib/moderate/foo.rb → Moderate::Foo (and, with the collapses above,
+      # lib/moderate/models/report.rb → Moderate::Report).
+      loader.push_dir(MODERATE_LIB, namespace: Moderate)
+    end
+
+    # Eager-load the same subtree in production (and in the test suite, which sets
+    # `config.eager_load = true`) so autoload/NameError problems surface as a boot
+    # failure rather than a mid-request error. `push_dir` above already makes it
+    # autoloadable; adding it to eager_load_paths makes the boot-time pass cover it.
+    config.eager_load_paths << MODERATE_LIB
+
+    # Make the host's migrations:install task pick up the gem's migration template
+    # location, and ensure the gem's own migration directory is on the path. The
+    # primary install path is still `rails generate moderate:install` (which copies
+    # the adaptive migration into the host's db/migrate); appending the path here is
+    # belt-and-suspenders so engine-style `moderate:install:migrations` also works.
+    initializer "moderate.migrations" do |app|
+      unless app.root.to_s == root.to_s
+        config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+
+    # Register the model macros on ActiveRecord, the canonical Rails way.
+    #
+    # `ActiveSupport.on_load(:active_record)` defers until ActiveRecord::Base is
+    # actually defined, so we never force-load AR at boot and we play nicely with
+    # the host's load order. Once it fires, every model gains `has_reporting_and_blocking`,
+    # `has_reportable_content`, and `moderates` as class methods (the macros that lazily
+    # include Moderate::Actor / Moderate::Reportable / Moderate::ContentFilterable).
+    #
+    # `Moderate::Macros` is require_relative'd by the spine, so the constant resolves
+    # the instant this hook fires.
+    initializer "moderate.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend Moderate::Macros
+      end
+    end
+
+    # Surface the gem's I18n files (filter validation messages, the DSA taxonomy
+    # labels, the notice-form copy) to the host's I18n load path. The locale files
+    # ship under the engine's conventional config/locales (provided by other
+    # components); listing the glob here is harmless if none exist yet.
+    initializer "moderate.locales" do |app|
+      app.config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.{rb,yml}").to_s]
+    end
+  end
+end

data/lib/moderate/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Base class for every error this gem raises. Host apps can rescue
+  # `Moderate::Error` to catch anything the gem throws without coupling to a
+  # specific subclass.
+  #
+  # NOTE: 0.x already defined `Moderate::Error` (a bare StandardError used by the
+  # profanity word-list downloader). We keep the exact same constant so any host
+  # code that rescued it on the old gem keeps working — see "Upgrading from 0.x"
+  # in the README. The class is just re-homed here in 1.0.
+  class Error < StandardError; end
+
+  # Raised by `Configuration#validate!` (called at the end of `Moderate.configure`)
+  # when the initializer block contains a bad value — an unknown filter mode, an
+  # unregistered adapter name, a blank `user_class`, etc.
+  #
+  # We deliberately *also* raise plain `ArgumentError` from the validating setters
+  # themselves (per docs/configuration.md: "raises a plain-English ArgumentError
+  # immediately"), so a typo fails fast at the assignment line. `ConfigurationError`
+  # exists for the cases where validation can only run once the whole block is
+  # known (e.g. a `:block`-mode filter pointed at an async adapter, which needs
+  # both the mode and the adapter resolved together). It subclasses `Error` so a
+  # blanket `rescue Moderate::Error` still catches it.
+  class ConfigurationError < Error; end
+end

data/lib/moderate/event.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Moderate
+  # The stable envelope every notifiable/auditable moment travels in.
+  #
+  # `Moderate.notify` and `Moderate.audit` both hand the host's hook ONE of these,
+  # so a single `config.notify` lambda can `case event.name` and fan out to email
+  # (goodmail), admin alerts (telegrama), and in-app + push (noticed) without any
+  # of those channels knowing about each other. See docs/notifications.md.
+  #
+  # The fields are the contract the docs promise the host can rely on:
+  #   event.name        # Symbol — which moment, e.g. :report_decision
+  #   event.subject     # the record this is about (a Report / Flag / Block / Appeal / Notice)
+  #   event.actor       # who triggered it (a moderator, a user, or nil for system events)
+  #   event.recipients  # Array — already resolved to the right people to notify
+  #   event.payload     # Hash of event-specific context, ALWAYS including :summary
+  #   event.occurred_at # when it happened
+  #   event.to_h        # the whole envelope as a Hash (for logging, tests, noticed params)
+  #
+  # Immutable value object (`Data.define`, Ruby 3.2+). The host never constructs
+  # one — the gem's services do — the host only reads it.
+  Event = Data.define(:name, :subject, :actor, :recipients, :payload, :occurred_at, :id) do
+    # Keyword constructor with forgiving defaults so internal call sites stay terse.
+    # `recipients` is coerced to a compacted Array (an event may target one user,
+    # several, or none — `content_flagged` has no user recipient by design, so an
+    # empty array is normal and correct). `payload` is symbolized for stable access
+    # (hooks read `event.payload[:summary]`).
+    def initialize(name:, subject: nil, actor: nil, recipients: nil, payload: nil,
+                   occurred_at: Time.now, id: SecureRandom.uuid)
+      super(
+        name: name.to_sym,
+        subject: subject,
+        actor: actor,
+        recipients: Array(recipients).compact,
+        payload: symbolize(payload),
+        occurred_at: occurred_at,
+        id: id
+      )
+    end
+
+    # The whole envelope as a plain Hash. docs/notifications.md tells hosts to pass
+    # `event.to_h` (not the raw object) into `noticed`, because noticed serializes
+    # params to the database and a Hash of GlobalID-able records + scalars stores
+    # cleanly. Keep this a flat, predictable shape.
+    def to_h
+      {
+        name: name,
+        subject: subject,
+        actor: actor,
+        recipients: recipients,
+        payload: payload,
+        occurred_at: occurred_at,
+        id: id
+      }
+    end
+
+    # The one-line, redaction-safe description of what happened. Built for the
+    # admin Telegram ping ("Telegrama.send_message(event.payload[:summary])"), so
+    # we surface it as a first-class reader rather than making every hook reach
+    # into the payload Hash. Falls back to the event name if a producer forgot it.
+    def summary
+      payload[:summary] || name.to_s
+    end
+
+    private
+
+    def symbolize(payload)
+      return {} if payload.nil?
+
+      payload.to_h.transform_keys(&:to_sym)
+    end
+  end
+end