@helyx/module-automod

Auto Moderation lets authorised managers publish transparent Discord-native safety rules, review content-free activity receipts, and optionally connect confirmed offences to Moderation cases and repeat-offender actions.

Availability and deployment

Auto Moderation is a Live module distributed under HSAL-1.0. Standard mode supports Hosted and Self-Hosted Helyx installations, uses no third-party credentials, and does not require the Message Content privileged intent.

Package installation does not enable the module for a server. The deployment-neutral Enhanced matching engine is included through the deliberate @helyx/module-automod/engine export. Hosted Helyx connects it through Ecko for eligible Enhanced servers, while Self-Hosted Helyx runs the same scanner contract through the embedded adapter. Standard rules remain effective without either adapter.

What it does

• Keeps one logical Helyx keyword rule mapped to one Helyx-owned Discord Auto Moderation rule.
• Supports keyword/phrase/wildcard and Discord regex filters, one Discord preset rule, one generic-spam rule, and one mention-spam rule.
• Applies global and per-rule role/channel exclusions and detects external Discord edits or deletion as drift or missing state.
• Records bounded structural action receipts without matched words or message content.
• Supplies the current rule revision, exclusions, repeat window, and first/second/third action policy to the closed Moderation integration.
• Uses a durable enforcement claim before requesting an optional Moderation effect so native action events collapse into one offence.
• Compiles immutable, versioned Enhanced rule snapshots and deterministically evaluates exact, phrase, wildcard, reviewed normalisation and explicitly opted-in bounded fuzzy matching.
• Keeps custom regex on Discord's native Rust engine until an approved linear-time Node engine is available; it never falls back to JavaScript's backtracking regular-expression engine.
• Provides bounded process-memory configuration, edit-metadata and keyed similar-message caches that remain correct when restarted empty.

Auto Moderation does not provide staff commands, own moderation case numbers, or perform Discord member punishment directly. The optional Moderation module remains the only provider allowed to create a case and dispatch a Helyx warning, mute, kick, ban, demotion, or violation thread.

Commands and interactions

Auto Moderation has no slash commands or Discord components. Managers use the dashboard resources. Each operation is separately authorised through automod.rules.read, automod.rules.manage, automod.rules.publish, automod.rules.reconcile, automod.activity.read, or automod.settings.manage; all default to Administrators.

Dashboard configuration

The Rules resource uses the exact responsive columns Rule name, Filter, Action, Moderation thread, Ignored roles, and Repeat offender. One Save validates the complete native definition, fixed mute durations, high-impact repeat actions, combined exemptions, Discord capacity, and current publishing permission before creating or updating the active Discord rule. The module must be enabled to apply a rule. A 4,000-byte bounded import reviews comma/newline-separated terms without saving or applying them and without silent truncation.

Published mappings support Disable, Adopt current Discord values, Restore Helyx values, and confirmed cleanup of only the mapped Helyx-owned Discord rule. A missing rule is never recreated automatically. Active rules can be edited and saved directly; mapped filter types cannot be changed because Discord treats them as immutable. Drifted or missing mappings must be reconciled before ordinary Save can apply changes.

Settings contain Standard/Enhanced mode identity, Strict (90), Balanced (80), Sensitive (70) and Custom (60–95) confidence choices, optional per-category overrides, native rule-type configuration switches, a default Discord alert channel, global ignored roles/channels, and a 1–365 day repeat-offender window. These switches permit configuration of preset, generic spam and mention spam rules; they do not create a rule or import existing Discord rules. Unmanaged Discord rules remain untouched and still count towards Discord's capacity. Adopt current Discord values applies only to an existing Helyx-owned mapping. Exact, native-equivalent and reviewed high-confidence normalised matches do not depend on the slider. Fuzzy matching must also be enabled explicitly on the rule's bounded keyword group, and terms under four characters never enter fuzzy comparison.

The settings preview tests unsaved confidence values against fictional content and currently published rules in memory. It reports the selected rule, category, method, deterministic score, effective threshold and native coverage without returning the matched term or storing the fictional content. Rule imports accept CRLF/LF and comma-separated lists, normalise duplicates, and return bounded row-level errors for every rejected item instead of silently truncating input.

The Activity resource is read-only and lists bounded structural receipts with their rule/action/outcome and optional Moderation case ID. It never shows a matched term or message body.

Discord requirements

Helyx needs Manage Server to inspect, create, update, disable, or delete its owned Discord Auto Moderation rules. A Discord-native timeout additionally needs Moderate Members. Auto Moderation consumes Auto Moderation rule create/update/delete and action-execution Gateway events through the core adapter. Those events use the code-level AUTO_MODERATION_CONFIGURATION and AUTO_MODERATION_EXECUTION intents and require no separate Developer Portal switch.

A native rule must block a message or send an alert; timeout cannot be its only action. Discord alerts may include triggering content in the selected Discord-owned channel, so publication displays that disclosure. The Helyx adapter removes content and matched fields before module code, persistence, Logging, Audit, metrics, or traces.

Block message also removes posted Enhanced matches after detection, independently of the selected offence action. Native blocking happens before posting; Enhanced removal is asynchronous. Unconfirmed removal or thread delivery is surfaced through safe Activity codes while the primary action result remains authoritative.

Data, privacy and retention

| Record category | Retained data | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Rules | Logical/server identity, category, canonical rule document, owned Discord mapping/fingerprint, configuration revision, nullable creator/updater IDs, revision, and timestamps. | | Action receipts | Structural rule/action, nullable subject/channel/message/alert IDs, claim/case links, safe outcome, and timestamps. | | Enforcement claims | Stable claim fingerprint, nullable subject/case identity, policy generation, repeat ordinal, selected action, safe outcome, and timestamps. | | Daily counts | Anonymous server/day/source/action counts and last observation time. |

Matched content, matched keywords, message bodies, attachments, embeds, and transient evidence are never written by this module. Native action receipts expire after 90 days. Settled anonymous claim/count history is bounded to 365 days; unresolved claims linked to an active case follow the case safety lifecycle. The versioned privacy provider covers creator, updater, detected-member, and enforced-member associations even while the module is disabled. Erasure detaches nullable user identities while declared rule bodies and active safety records follow manual review.

Operations and failure behavior

Saving a rule writes Discord first and attaches the mapping only after success. If persistence fails or the local revision changed, Helyx compensates a new Discord rule by deleting it, or restores the previous owned definition after an update where safe; compensation never overwrites a newer mapping. An unsuccessful creation retains an internal unpublished rule for recovery: open its existing Rules row before retrying Save. Ambiguous Discord results remain reviewable rather than being retried blindly, and a differing unconfirmed Discord rule with the same ownership marker blocks another creation.

Deleting an unmapped unpublished rule also requires successful Discord inspection. A native rule with the same ownership marker blocks record deletion so an unconfirmed creation cannot be orphaned.

External edits mark a rule drifted; external deletion marks it missing. Module disablement disables mapped owned rules without deleting mappings or definitions. Re-enablement revalidates and synchronises only rules whose logical status is Published. Uninstall leaves owned Discord rules disabled unless an authorised manager separately confirms cleanup.

The module is unhealthy while stopped or when required records, configuration, installation, Discord Auto Moderation, or authorization services are unavailable. Moderation and Logging are optional: their absence does not stop native Discord enforcement or structural receipt storage. The pure Enhanced engine performs no Discord, database, network, environment, clock or logging access; adapters supply immutable snapshots, message observations and explicit time values.

Before release, run formatting, lint, type checks, focused tests, module contracts, migration integration, packed lifecycle checks, and the repository release dry run. Live Discord behaviour remains unclaimed until the credentialed smoke matrix passes.

Documentation and support

• Auto Moderation overview
• Auto Moderation permissions
• Auto Moderation failure recovery
• Auto Moderation FAQ
• Report an issue

Publication, licensing, release-state promotion, push, deployment, and production changes require explicit owner approval.