moderate 0.1.0 → 1.0.0.beta1

data/lib/moderate/filters/base.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The built-in filter adapters live under `Moderate::Filters`. They're the
+  # gem's own implementations of the ONE adapter contract the whole filtering
+  # design hinges on:
+  #
+  #     adapter.classify(value) -> Moderate::Result
+  #
+  # ...where `value` is a piece of user content (a String of text, or an image
+  # reference) and the returned `Moderate::Result` answers "is this allowed?" and,
+  # if not, "why?" (the per-`Moderate::Label` detail, mapped onto the gem's single
+  # canonical taxonomy — see `Moderate::Label`).
+  #
+  # ── How adapters are invoked ────────────────────────────────────────────────
+  # The configuration registry (`Moderate::Configuration#adapters`) stores each
+  # adapter as EITHER a live object the host registered, OR a class-NAME String the
+  # gem constantizes lazily. The one built-in is seeded as the string
+  # "Moderate::Filters::Wordlist", and `Configuration#resolve_adapter` returns the
+  # CLASS itself for a String/Class entry. That means the gem calls
+  # `SomeAdapterClass.classify(value)` and `SomeAdapterClass.synchronous?` — i.e. the
+  # built-in exposes CLASS methods, not instance methods. (A host's own adapter
+  # registered as an instance — including the reference adapters in `examples/` —
+  # exposes the same `#classify`/`#synchronous?` on that instance — same duck type,
+  # both work.)
+  #
+  # `Base` gives the built-in both halves of that duck type from a single source:
+  # subclasses implement the work as an INSTANCE method (`#classify`), and `Base`
+  # provides the CLASS-level `classify`/`synchronous?`/`async?` that the registry
+  # resolution path calls, delegating the class call to a fresh instance. So one
+  # implementation satisfies both call styles and there's no copy-paste. (It's the
+  # base for the bundled wordlist; the `examples/` reference adapters don't need it —
+  # any object answering `#classify` is a valid adapter.)
+  #
+  # ── Sync vs. async (why it matters for :block) ──────────────────────────────
+  # `Configuration#validate!` enforces the README's rule: a `:block`-mode filter
+  # MUST use a synchronous adapter, because you can't reject a save on a result
+  # that's still computing in a background job. The validator probes the adapter
+  # with `synchronous?` and treats anything that doesn't answer, or answers truthy,
+  # as synchronous (the safe default that keeps simple adapters working); only an
+  # adapter that explicitly returns `synchronous? == false` is rejected for :block.
+  #
+  # We model this once here as `async?` (default `false` — the built-in wordlist is
+  # sync) and derive `synchronous?` from it, so a subclass flips ONE flag
+  # (`def self.async? = true`) to declare itself background-only. The wordlist leaves
+  # the default; a network-backed reference adapter (see `examples/`) declares itself
+  # async via its own `synchronous? == false`, which the spine honors regardless of
+  # whether the adapter inherits from `Base`.
+  module Filters
+    class Base
+      class << self
+        # The class-level entry point the registry resolution path calls. Spins up
+        # a per-call instance so subclasses can keep per-classification state in
+        # instance vars without any thread-safety worry (a new instance per call).
+        def classify(value)
+          new.classify(value)
+        end
+
+        # Is this adapter background-only? Default `false` — the built-in
+        # deterministic adapters run inline. Override with `def self.async? = true`
+        # in an adapter whose `classify` does blocking I/O (a network moderation
+        # API), so the gem routes it through `Moderate::ClassifyJob` in :flag mode
+        # and forbids it in :block mode.
+        def async?
+          false
+        end
+
+        # The predicate the spine's `Configuration#validate_block_mode_adapter!`
+        # actually reads. Defined in terms of `async?` so there's a single source
+        # of truth: an async adapter is, by definition, not synchronous.
+        def synchronous?
+          !async?
+        end
+      end
+
+      # Subclasses MUST implement `#classify(value) -> Moderate::Result`. We raise a
+      # clear NotImplementedError rather than silently allowing nil, so a half-built
+      # adapter fails loudly in development instead of mysteriously "allowing"
+      # everything in production.
+      def classify(_value)
+        raise NotImplementedError, "#{self.class} must implement #classify(value) and return a Moderate::Result"
+      end
+
+      private
+
+      # Mirror the class-level predicates on the instance, so a `Base` subclass
+      # registered as an *instance* (rather than resolved from a class name) still
+      # answers the same duck type the validator probes.
+      def async?
+        self.class.async?
+      end
+
+      def synchronous?
+        self.class.synchronous?
+      end
+
+      # ── Shared helpers for subclasses ────────────────────────────────────────
+
+      # The canonical "nothing matched" Result, stamped with this adapter's name so
+      # an allowed verdict is still attributable in audit. Adapters call this on the
+      # happy path (and a network-backed adapter calls it on a fail-open error path
+      # too — a moderation API must NEVER block a save on a transient network blip;
+      # see the reference adapters in `examples/`).
+      def allowed_result(raw: nil)
+        Moderate::Result.allowed(source: source_name, raw: raw)
+      end
+
+      # Build a flagged Result from a list of canonical label hashes/objects. Thin
+      # wrapper so subclasses don't repeat the `source:`/`allowed:` bookkeeping.
+      def flagged_result(labels:, raw: nil)
+        Moderate::Result.new(allowed: false, labels: labels, source: source_name, raw: raw)
+      end
+
+      # The adapter's `source` string — the value recorded on `Moderate::Flag#source`
+      # so the moderation queue shows which backend flagged each item. Defaults to
+      # the demodulized, underscored class name ("Wordlist" -> "wordlist"); the
+      # bundled wordlist overrides it to one of the migration's allowed `source` enum
+      # values ("text_filter"), and a reference adapter sets the value that fits it
+      # ("image_filter" / "external_classifier"). See the `moderate_flags_source_check`
+      # constraint in the install migration.
+      def source_name
+        self.class.name.to_s.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      end
+    end
+  end
+end

data/lib/moderate/filters/wordlist.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "set"
+
+module Moderate
+  module Filters
+    # The default, built-in TEXT adapter: a fast, offline, multilingual,
+    # zero-dependency wordlist matcher. It is the ONE built-in adapter the gem ships
+    # — registered by the spine under the name :wordlist (config seed
+    # "Moderate::Filters::Wordlist", constantized lazily). Synchronous, so it's valid
+    # in :block mode.
+    #
+    # ── What it's for, and what it's NOT ─────────────────────────────────────────
+    # This satisfies the store bar of "a method for filtering objectionable UGC
+    # before it's posted" (Apple Guideline 1.2:
+    # https://developer.apple.com/app-store/review/guidelines/#user-generated-content;
+    # Google Play UGC: https://support.google.com/googleplay/android-developer/answer/9876937)
+    # with no network call and no external service. It is NOT a full trust-&-safety
+    # classifier — it can't read context. For nuance (or for images), register a
+    # reference adapter from `examples/` (OpenAI, AWS Rekognition, …) or your own.
+    # The bar this clears is "obvious slurs/threats/spam don't sail straight
+    # through", at zero latency and zero cost.
+    #
+    # ── Evasion resistance (the part that matters) ───────────────────────────────
+    # Naive substring matching is trivially defeated ("f.u.c.k", "FÜCK", "f u c k",
+    # "fuuuck", "fμck"). Before matching, text is NORMALIZED:
+    #   1. Unicode NFKD decomposition + stripping combining marks — folds accented
+    #      and look-alike forms ("FÜCK" -> "fuck") to a plain base form. NFKD
+    #      (compatibility decomposition) also flattens many homoglyph/fullwidth
+    #      tricks. (Ruby String#unicode_normalize; \p{Mn} = Unicode "Mark,
+    #      nonspacing", the combining accents.)
+    #   2. Leetspeak transliteration (0->o, 1->i, 3->e, 4->a, 5->s, 7->t, @->a,
+    #      $->s) — folds the common letter/number/symbol swaps.
+    #   3. Lowercasing + collapsing every run of non-alphanumerics to a single space
+    #      — kills punctuation-as-separator evasion ("f.u.c.k" -> "f u c k").
+    # The normalized text is then matched in TWO forms: the single-spaced form
+    # (so word-boundary patterns like "\bkill yourself\b" work), AND a space-removed
+    # "compact" form (so spacing evasion "f u c k" -> "fuck" is caught). A pattern
+    # hits if it matches EITHER form. This is a fast offline baseline matching
+    # strategy the adapter relies on.
+    #
+    # ── Output ───────────────────────────────────────────────────────────────────
+    # On a hit, returns a flagged Moderate::Result whose labels are the canonical
+    # categories that matched, each with score 1.0 — a deterministic matcher has no
+    # probability, so a trip is "certain". `source` is "text_filter" to match the
+    # `moderate_flags_source_check` migration constraint.
+    class Wordlist < Base
+      # NFKD-fold, then strip combining marks. `\p{Mn}` is the Unicode general
+      # category "Mark, nonspacing" — the accents that NFKD splits off the base
+      # letter. Removing them turns "é" -> "e", "ñ" -> "n", etc.
+      COMBINING_MARKS = /\p{Mn}/
+
+      # Common leetspeak / symbol substitutions, folded back to plain letters before
+      # matching. Kept tiny on purpose — over-aggressive folding creates false
+      # positives (e.g. folding "l"->"i" would mangle ordinary words). These are the
+      # high-signal swaps that catch the bulk of leetspeak evasion.
+      LEETSPEAK = {
+        "0" => "o", "1" => "i", "3" => "e", "4" => "a",
+        "5" => "s", "7" => "t", "@" => "a", "$" => "s"
+      }.freeze
+
+      # Everything that isn't a-z or 0-9 becomes a single space — collapses
+      # punctuation/emoji/whitespace runs into one separator so "f.u.c.k" reads as
+      # "f u c k".
+      NON_ALNUM = /[^a-z0-9]+/
+
+      # The bundled blocklist YAMLs live in the gem's config dir, one per locale.
+      # We load and MERGE all of them (multilingual by default — see es.yml's note).
+      BLOCKLISTS_GLOB = File.expand_path("../../../config/moderate/blocklists/*.yml", __dir__)
+
+      # The normalized text, in both matchable forms. A tiny immutable value object
+      # so we compute the (mildly expensive) normalization exactly once per classify.
+      Normalized = Data.define(:spaced, :compact)
+
+      # The bundled patterns are the same for every classify call and never change
+      # at runtime, so compile them ONCE per process and memoize on the class.
+      # (config.additional_words / excluded_words are layered in per-call, since the
+      # host can in principle reconfigure between calls — and they're cheap.)
+      def self.patterns
+        @patterns ||= compile_bundled_patterns
+      end
+
+      # Reset the compiled-pattern cache. Exposed mainly for the test suite, which
+      # may stub the blocklist files; harmless in production.
+      def self.reset!
+        @patterns = nil
+      end
+
+      # Compile every bundled locale file into
+      #   { canonical_slug_string => [[spaced_regex, compact_regex], ...] }.
+      # Multiple locales contributing the same category (e.g. en + es both add to
+      # "harassment") are merged into one pattern list.
+      #
+      # Each blocklist source string yields TWO compiled regexes, because the matcher
+      # tests two normalized forms (see #classify):
+      #   - `spaced_regex`  = the source verbatim, with its `\b` word boundaries
+      #     intact, tested against the single-spaced form. Boundaries here are what
+      #     keep ordinary text from over-matching (the Scunthorpe protection for
+      #     normal input).
+      #   - `compact_regex` = the source with any TRAILING `\b` removed, tested
+      #     against the space-STRIPPED form. This is the spacing-evasion defense:
+      #     "f u c k you" normalizes to compact "fuckyou", which a trailing `\b` would
+      #     reject (no boundary after "fuck" in "fuckyou"). We keep the LEADING `\b`
+      #     so we still anchor to a real word start — that's what stops "scunthorpe"
+      #     from matching "\bcunt" (the "cunt" in "scunthorpe" is preceded by "s", so
+      #     there's no leading boundary). Dropping only the trailing boundary is the
+      #     sweet spot: catches concatenation evasion without opening the Scunthorpe
+      #     floodgates. (Genuine residual false positives are handled by
+      #     `config.excluded_words`.)
+      def self.compile_bundled_patterns
+        Dir.glob(BLOCKLISTS_GLOB).each_with_object({}) do |path, acc|
+          loaded = YAML.safe_load_file(path) || {}
+          loaded.each do |category, raw_patterns|
+            list = Array(raw_patterns).map { |source| compile_pair(source) }
+            (acc[category.to_s] ||= []).concat(list)
+          end
+        end
+      end
+
+      # Build the [spaced, compact] regex pair for one blocklist source string.
+      def self.compile_pair(source)
+        spaced = Regexp.new(source)
+        compact = Regexp.new(compact_source(source))
+        [spaced, compact]
+      end
+
+      # Derive the compact-form pattern from a blocklist source. The compact form of
+      # the text has ALL whitespace removed, so the pattern must too:
+      #   - strip a single trailing `\b` (so single tokens survive concatenation,
+      #     e.g. "fuck" inside "fuckyou"); the LEADING `\b` is kept to anchor to a real
+      #     word start and keep Scunthorpe-type false positives out;
+      #   - drop interior whitespace matchers (`\s+`, `\s*`, and literal spaces) so a
+      #     multi-word phrase pattern ("kill\s+yourself") still matches the
+      #     space-stripped form ("killyourself") — the no-spaces spelling of the same
+      #     evasion.
+      def self.compact_source(source)
+        source
+          .sub(/\\b\z/, "")          # drop trailing word boundary
+          .gsub(/\\s[*+]?/, "")      # drop \s, \s*, \s+ whitespace matchers
+          .gsub(/\[ ([^\]]*)\]/, '[\1]') # drop a literal space inside a char class
+          .delete(" ")               # drop any remaining literal spaces
+      end
+
+      def classify(value)
+        text = value.to_s
+        # Empty / blank content can't violate anything — short-circuit so we don't
+        # pay for normalization on the (very common) empty case.
+        return allowed_result if text.strip.empty?
+
+        norm = normalize(text)
+        hits = matched_categories(norm)
+
+        return allowed_result if hits.empty?
+
+        # One Label per matched canonical slug, score 1.0 (deterministic = certain).
+        # `Moderate::Label` parses "hate/threatening" into category :hate +
+        # subcategory :threatening for us.
+        labels = hits.map do |slug|
+          category, subcategory = slug.split("/", 2)
+          Moderate::Label.new(
+            category: category, subcategory: subcategory,
+            score: 1.0, flagged: true, input: :text
+          )
+        end
+
+        flagged_result(labels: labels)
+      end
+
+      private
+
+      # The wordlist writes flags with source "text_filter" — one of the four values
+      # allowed by the migration's `moderate_flags_source_check` constraint.
+      def source_name
+        "text_filter"
+      end
+
+      # The canonical slugs that tripped. An excluded word (config.excluded_words)
+      # is stripped from the normalized text BEFORE matching, so a legitimate word
+      # that contains a banned substring (the classic "Scunthorpe problem") never
+      # trips. additional_words are matched as a whole-word extra "harassment" bucket
+      # — a host's domain-specific terms it wants caught.
+      def matched_categories(norm)
+        slugs = self.class.patterns.filter_map do |slug, pairs|
+          # A category trips if ANY of its patterns matches EITHER the spaced form
+          # (with the precise boundary regex) OR the compact/space-stripped form (with
+          # the trailing-boundary-relaxed regex — the spacing-evasion defense).
+          slug if pairs.any? { |spaced_re, compact_re| spaced_re.match?(norm.spaced) || compact_re.match?(norm.compact) }
+        end
+
+        slugs.concat(additional_word_categories(norm))
+        slugs.uniq
+      end
+
+      # config.additional_words: extra terms the host wants flagged beyond the
+      # bundled lists. We treat a hit on any of them as plain "harassment" (the
+      # safest generic bucket for "a word this host disallows") with a word-boundary
+      # match on the normalized spaced form. Returns [] when none configured.
+      def additional_word_categories(norm)
+        words = Array(config.additional_words).map { |w| normalize_token(w) }.reject(&:empty?)
+        return [] if words.empty?
+
+        matched = words.any? do |word|
+          boundary = /\b#{Regexp.escape(word)}\b/
+          boundary.match?(norm.spaced) || norm.compact.include?(word)
+        end
+        matched ? ["harassment"] : []
+      end
+
+      # Full normalization pipeline (see the class header for the why of each step),
+      # producing both the single-spaced and space-removed matchable forms. Excluded
+      # words are deleted from the spaced form first so they can never contribute a
+      # match (and can't bleed into the compact form either).
+      def normalize(text)
+        folded = fold(text)
+        folded = strip_excluded_words(folded)
+        Normalized.new(spaced: folded, compact: folded.delete(" "))
+      end
+
+      def fold(text)
+        text
+          .unicode_normalize(:nfkd)
+          .downcase
+          .gsub(COMBINING_MARKS, "")
+          .tr(LEETSPEAK.keys.join, LEETSPEAK.values.join)
+          .gsub(NON_ALNUM, " ")
+          .strip
+          .squeeze(" ") # collapse any residual double spaces (no ActiveSupport #squish dependency)
+      end
+
+      # Normalize a single configured token the same way as content, so an
+      # excluded/additional word the host writes with caps/accents still lines up
+      # with the normalized text it's compared against.
+      def normalize_token(word)
+        fold(word.to_s).delete(" ")
+      end
+
+      # Remove configured false-positive words from the spaced form before matching.
+      # We match them on word boundaries so we only excise the standalone word, not
+      # every occurrence of the substring.
+      def strip_excluded_words(spaced)
+        excluded = Array(config.excluded_words).map { |w| normalize_token(w) }.reject(&:empty?)
+        return spaced if excluded.empty?
+
+        excluded.reduce(spaced) do |acc, word|
+          acc.gsub(/\b#{Regexp.escape(word)}\b/, " ")
+        end.squeeze(" ").strip
+      end
+
+      def config
+        Moderate.config
+      end
+    end
+  end
+end

data/lib/moderate/jobs/classify_job.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The background worker for ASYNCHRONOUS filter adapters (the :openai adapter, a
+  # host's hosted classifier, the default :image adapter) running in :flag mode.
+  #
+  # ── Why a job exists at all ──────────────────────────────────────────────────
+  # An async adapter does blocking I/O (a moderation API call), which must never run
+  # inside the request that saved the content — and CANNOT run inside a validator or
+  # an after_commit callback without stalling the write. So the :flag path works in
+  # two halves:
+  #   1. The model's filter concern (`moderates :field`) lets the write succeed, then
+  #      in an after_commit hook enqueues THIS job for any field whose policy uses an
+  #      async adapter. (Synchronous adapters like :wordlist skip the job — the
+  #      concern classifies inline and files the Flag directly.)
+  #   2. This job re-reads the saved value, classifies it through the adapter, and —
+  #      if the content is flagged — files (or updates) a Moderate::Flag for the
+  #      moderation queue.
+  #
+  # ── Re-reading the value (deliberate) ────────────────────────────────────────
+  # The job is handed the RECORD (GlobalID-serialized by ActiveJob) and the FIELD
+  # NAME, not the raw text/image — so it always classifies the CURRENT persisted
+  # value. If the record was edited or deleted between enqueue and run, we classify
+  # what's actually there now (or skip a vanished record), never a stale snapshot.
+  #
+  # ── Idempotency ──────────────────────────────────────────────────────────────
+  # Flag creation goes through `Moderate::Flag.flag!`, the single builder shared by
+  # the synchronous and asynchronous paths. It's an upsert-by-(flaggable, field,
+  # source) so a retried job (ActiveJob retries on transient failures) doesn't pile
+  # up duplicate queue entries for the same content.
+  #
+  # ── Base class ───────────────────────────────────────────────────────────────
+  # We subclass `ActiveJob::Base` directly (not the host's ApplicationJob) so the gem
+  # doesn't depend on a constant that lives in the host app — the same reason the
+  # rest of the gem stays host-agnostic. The host configures the queue adapter,
+  # retries, and queue name globally as usual.
+  class ClassifyJob < ActiveJob::Base
+    # Run on a low-priority queue by default — moderation flagging is important but
+    # not latency-critical (the content is already published in :flag mode). A host
+    # can override the queue globally.
+    queue_as { Moderate.config.respond_to?(:job_queue) && Moderate.config.job_queue || :default }
+
+    # @param record [ActiveRecord::Base] the flaggable record (any Moderate::Reportable).
+    # @param field  [String, Symbol] the field whose value to classify.
+    # @param adapter [String, Symbol, nil] optional explicit adapter name; when nil,
+    #   the field's resolved FilterPolicy (or the global default) decides.
+    def perform(record, field, adapter: nil)
+      # The record may have been destroyed between enqueue and execution — nothing
+      # to classify, nothing to flag. (ActiveJob raises DeserializationError for a
+      # GlobalID that no longer resolves; that's rescued at the framework level, but
+      # we also guard a nil here defensively.)
+      return if record.nil?
+
+      field = field.to_s
+      policy = resolve_policy(record, field, adapter)
+
+      # If the field's policy is :off (e.g. it was reconfigured to off after the job
+      # was enqueued), there's nothing to do.
+      return if policy.respond_to?(:off?) && policy.off?
+
+      value = field_value(record, field)
+      return if blank?(value)
+
+      result = Moderate.classify(value, policy: policy)
+      return unless result.flagged?
+
+      file_flag(record, field, policy, result, value)
+    end
+
+    private
+
+    # Resolve the FilterPolicy for this record/field. If an explicit adapter name was
+    # passed (the enqueuer already knew it), prefer the field's declared policy but
+    # fall back to the global resolution — `Moderate.filter_policy_for` already walks
+    # the ancestor chain and falls back to an :off policy, so this is always defined.
+    def resolve_policy(record, field, adapter)
+      policy = Moderate.filter_policy_for(record, field)
+      return policy if adapter.nil?
+
+      # An explicit adapter override: keep the resolved policy's class/field/mode but
+      # swap in the requested adapter, so the job classifies with exactly the backend
+      # the enqueuer intended even if config changed.
+      Moderate::Configuration::FilterPolicy.new(
+        class_name: policy.class_name, field: field,
+        adapter: adapter.to_s.strip.downcase.to_sym, mode: policy.mode
+      )
+    end
+
+    # File (or upsert) the Moderate::Flag via the shared builder. We pass exactly the
+    # columns the install migration defines for moderate_flags. `Flag.flag!` owns the
+    # `content_flagged` notify event so there's a single emission site across the
+    # sync and async paths — the job doesn't fire it itself, to avoid double-notifying.
+    #
+    # `result.source` is the human-readable adapter NAME the spine stamped on the
+    # Result (e.g. "openai"); the persisted `source` COLUMN, however, is constrained
+    # to text_filter/image_filter/external_classifier/manual, which the adapter's own
+    # Result already reflects via its `source_name`. We pass `result.source` and let
+    # the model coerce/validate against the constraint.
+    def file_flag(record, field, policy, result, value)
+      Moderate::Flag.flag!(
+        flaggable: record,
+        field: field,
+        owner: content_owner(record),
+        source: result.source,
+        mode: policy.respond_to?(:mode) ? policy.mode : :flag,
+        categories: result.categories,
+        scores: result.scores,
+        excerpt: excerpt_for(value),
+        context: flag_context(policy, result)
+      )
+    end
+
+    # Who owns the flagged content. The Reportable concern defines `reported_owner`
+    # (the "who's responsible" hook); we use it when present and degrade to nil
+    # otherwise (the owner column is nullable — a flag with no resolvable owner is
+    # still a valid queue item).
+    def content_owner(record)
+      record.respond_to?(:reported_owner) ? record.reported_owner : nil
+    end
+
+    # Diagnostic context persisted on the flag (the `context` jsonb column): the raw
+    # provider payload (for audit/debugging) plus the policy that produced this flag.
+    # Never relied on by the gem's own logic — purely for the human in the queue.
+    def flag_context(policy, result)
+      context = {}
+      context[:raw] = result.raw unless result.raw.nil?
+      context[:policy] = {
+        class_name: policy.class_name, field: policy.field, mode: policy.mode.to_s
+      }
+      context
+    end
+
+    # A short, human-readable snippet of the offending value for the queue. We keep
+    # it to 500 chars — enough context for a moderator, not
+    # a full copy of a long document. An image value (not a String) gets stringified
+    # to its reference, which is fine for the queue's "what was flagged" column.
+    def excerpt_for(value)
+      value.to_s[0, 500]
+    end
+
+    def field_value(record, field)
+      record.public_send(field)
+    rescue NoMethodError
+      nil
+    end
+
+    # Blank check without forcing an ActiveSupport dependency in the job's hot path
+    # (ActiveSupport IS loaded in a Rails host, but #blank? on arbitrary values is
+    # easy to reproduce and keeps the job self-contained).
+    def blank?(value)
+      return true if value.nil?
+      return value.strip.empty? if value.is_a?(String)
+      return value.empty? if value.respond_to?(:empty?)
+
+      false
+    end
+  end
+end

data/lib/moderate/label.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Moderate
+  # A single classification label produced by a filter adapter.
+  #
+  # One piece of content can produce *several* labels — e.g. a message might trip
+  # both `hate` and `hate/threatening`, or an image might trip `sexual/minors`
+  # while its caption trips `harassment`. Each Label records exactly one
+  # (category, subcategory) verdict, the adapter's confidence `score`, and which
+  # `input` (text vs image) tripped it. `Moderate::Result` holds the collection.
+  #
+  # The taxonomy is OpenAI's `omni-moderation-latest` category set, adopted as the
+  # gem's ONE canonical vocabulary so every adapter (the offline wordlist, the
+  # OpenAI moderation endpoint, or a host-registered backend) speaks the same
+  # language — which in turn lets `Moderate::Flag`, the DSA Art. 17 statement of
+  # reasons, and the Art. 24 transparency counters all aggregate over a single set.
+  # See: https://developers.openai.com/api/docs/guides/moderation
+  #
+  # Implemented with Ruby's `Data.define` (Ruby 3.2+, which the gemspec requires):
+  # an immutable, frozen-by-construction value object — exactly what a label
+  # should be (you never mutate a verdict after the fact).
+  Label = Data.define(:category, :subcategory, :score, :flagged, :input) do
+    # NOTE: constants live OUTSIDE this block (see below). A `Data.define do...end`
+    # block is class_eval'd in a context where constant *assignment* leaks to the
+    # lexically-enclosing namespace (here `Moderate`) instead of attaching to the
+    # Data class — a well-known Ruby gotcha. So `TAXONOMY`/`CATEGORIES`/`INPUTS` are
+    # defined by reopening `Moderate::Label` after the `Data.define` call. Instance
+    # methods defined in the block (below) are unaffected and work as written.
+
+    # Normalize everything on the way in so adapters can be sloppy about types:
+    #   - category/subcategory/input accepted as String or Symbol, downcased
+    #   - score coerced to Float (defaults to 1.0 — deterministic adapters like the
+    #     wordlist have no probability, so a trip is "certain")
+    #   - flagged defaults to true (you only build a Label when something matched)
+    def initialize(category:, subcategory: nil, score: 1.0, flagged: true, input: :unknown)
+      super(
+        category: normalize_symbol(category),
+        subcategory: subcategory.nil? ? nil : normalize_symbol(subcategory),
+        score: score.nil? ? nil : score.to_f,
+        flagged: flagged ? true : false,
+        input: normalize_symbol(input || :unknown)
+      )
+    end
+
+    # The full slug, OpenAI-style: "hate/threatening", "self-harm/intent", or just
+    # "hate" when there's no subcategory. This is the canonical wire/storage form
+    # used by `Moderate::Result#categories` and persisted on `Moderate::Flag`.
+    def slug
+      subcategory ? "#{category}/#{subcategory}" : category.to_s
+    end
+
+    # True when this label belongs to the canonical taxonomy. Adapters MAY emit
+    # off-taxonomy labels (a provider category we haven't mapped) — we don't raise,
+    # we just let callers filter on `canonical?` when they want strictness.
+    def canonical?
+      # `self.class::TAXONOMY` resolves the constant on the Label class regardless
+      # of the Data.define block's quirky lexical scope (see the note at the top).
+      subs = self.class::TAXONOMY[category]
+      return false if subs.nil?
+
+      subcategory.nil? || subs.include?(subcategory)
+    end
+
+    private
+
+    def normalize_symbol(value)
+      value.to_s.strip.downcase.to_sym
+    end
+  end
+
+  # --- Canonical taxonomy constants (attached to Moderate::Label) -------------
+  # Defined here, by reopening the class, rather than inside the Data.define block
+  # above, because constant assignment inside that block would leak to the
+  # `Moderate` namespace instead of landing on `Moderate::Label`.
+  class Label
+    # The canonical OpenAI moderation taxonomy: each top-level category mapped to
+    # its allowed subcategories. Sources, in the README and OpenAI's docs
+    # (https://developers.openai.com/api/docs/guides/moderation):
+    #   harassment      → :threatening
+    #   hate            → :threatening
+    #   sexual          → :minors
+    #   self-harm       → :intent, :instructions
+    #   violence        → :graphic
+    #   illicit         → :violent
+    #
+    # `nil` is always an implicitly-valid subcategory (the bare top-level category,
+    # e.g. plain `:hate` with no qualifier).
+    #
+    # NOTE: `self-harm` is the hyphenated symbol `:"self-harm"` to match OpenAI's
+    # wire format verbatim — `Result#categories` joins category+subcategory with "/"
+    # to reproduce OpenAI's exact slug strings ("self-harm/intent" etc.), so
+    # downstream consumers comparing against OpenAI labels line up byte-for-byte.
+    TAXONOMY = {
+      harassment: %i[threatening],
+      hate: %i[threatening],
+      sexual: %i[minors],
+      "self-harm": %i[intent instructions],
+      violence: %i[graphic],
+      illicit: %i[violent]
+    }.freeze
+
+    # Every canonical category as a flat symbol list, for validation and iteration.
+    CATEGORIES = TAXONOMY.keys.freeze
+
+    # Which inputs an adapter can attribute a label to. `:text` and `:image` mirror
+    # OpenAI's multimodal `category_applied_input_types`; `:unknown` is the safe
+    # default for adapters (like the offline wordlist) that only see one kind of
+    # input and don't bother to say which.
+    INPUTS = %i[text image unknown].freeze
+  end
+end