@helyx/module-moderation

Moderation lets authorised Discord staff apply accountable member actions, keep durable case history, and recover safely from ambiguous Discord outcomes.

Availability and deployment

Moderation is a Live module distributed under HSAL-1.0. It supports Hosted and Self-Hosted Helyx installations, requires no third-party credentials, and does not depend on Auto Moderation.

Package installation does not enable the module for a server.

What it does

• Creates an immutable, server-numbered case before each Discord mutation.
• Supports warnings, timeouts, timeout removal, kicks, bans, configured-role demotion, unbans, and bounded member history.
• Records typed action attempts so succeeded, failed, ambiguous, and review-required outcomes can be distinguished without raw Discord errors.
• Opens optional user-visible private violation threads and keeps their evidence delivery outside the punitive-action transaction.
• Lets authorised dashboard users reconcile, correct, disassociate, or reveal a private note without rewriting the original action.

Moderation does not classify messages, own keyword rules, or scan content. Auto Moderation can use its closed action provider when both modules are enabled, but each remains independently useful.

Commands and interactions

| Command path | Default access | Outcome | | --------------------- | -------------- | -------------------------------------------------------------- | | /mod warn | Administrators | Records a warning and optionally attempts a direct message. | | /mod timeout | Administrators | Applies a timeout from one minute to 28 days. | | /mod timeout-remove | Administrators | Removes an active timeout. | | /mod kick | Administrators | Removes the member from the server. | | /mod ban | Administrators | Bans the member with a bounded message-deletion choice. | | /mod demote | Administrators | Removes every eligible configured role in a list of up to ten. | | /mod unban | Administrators | Removes a ban by user ID. | | /mod history | Administrators | Shows a bounded case history privately. |

All commands are enabled-guild, server-only commands with deferred ephemeral acknowledgement and one unique moderation.* permission identity per executable path. Staff actions require a trimmed 10–500 character reason. An optional same-server message link stores channel and message IDs only; an optional private note is limited to 1,000 characters.

Kick, ban, demotion, unban, and timeouts longer than 24 hours require a 60-second actor/server/revision-bound confirmation with an explicit cancel path. Before dispatch, Helyx rechecks current module access, staff authority, target state, role hierarchy, and its own Discord permissions.

Violation-thread controls are Kick, Ban, Unmute when currently timed out, and No Further Action. Close and the separately permission-checked Close and delete appear only after one of those staff resolutions succeeds. Close archives and locks the thread; Close and delete additionally permanently deletes that case's Discord thread and messages, not its moderation records. Each control resolves a durable opaque case token, then fresh-authorises the clicking staff member and rechecks the case revision.

Dashboard configuration

Case name prefix controls new violation-thread names. Helyx appends the case number, padded to at least three digits (for example, moderation-case-001 or violation-012), without an operation-hash suffix. Existing thread names are not changed when the prefix is edited. The default applies to older saved configurations automatically.

Settings cover the optional warning direct message, 30–730 day settled-case retention, the violation-thread parent and access role, up to ten moderator notification roles and ten individual notification users, and an opening message. The channel, access role and case prefix share one half-width group; staff role/user notifications occupy the other, with mobile stacking and the opening message below. Enter each staff member's Discord user ID and select Add user. Current human server membership is checked before settings are saved; an empty list is valid. Existing configurations default to no individual notifications.

Individual notification users are mentioned as staff and invited to new private threads. Check channel previews their minimum parent access; Configure channel can apply View Channel, Read Message History and Send Messages in Threads member overwrites, never Manage Threads or moderation powers. Notification selection does not grant Helyx action permissions. Removing a selection stops future notifications but does not remove existing Discord overwrites or membership; review these separately when staff leave. Notification IDs stay in server configuration until removed or erased through the core privacy workflow and are hidden from support disclosure. The fixed core configuration privacy provider covers these associations even when the module is disabled or removed, exports only the requesting user's membership, and preserves other recipients and settings during erasure.

Auto Moderation owns each rule's decision to open a thread; there is no second severity gate in Moderation. Channel and role selections can be saved during setup, and Configure channel can create the access role. Active warning delivery requires a non-empty template; thread delivery requires complete channel/role configuration and an opening message.

The Cases / offences resource lists at most 50 cases with exact case/member search, bounded filters, a maximum 31-day date window, stable newest-first cursors, and revision-checked detail. It has no dashboard create, update, delete, or export operation.

• Reconcile inspects current Discord state before settling or retrying recovery work.
• Correct creates a linked correction case; it never edits the original action.
• Disassociate user is a one-click authorised action with no reason or confirmation. It clears the subject association and repeat count eligibility while preserving the case number and anonymous action history.
• Reveal private note is separately authorised and audited. Notes remain concealed in ordinary list and detail responses.

Case detail also offers separately permission-checked Mute, Unmute, Kick, Ban, Demote and No Further Action. Close thread and Close and delete appear only after a successful staff resolution; Close and delete also remains available for an already-closed thread. Punitive dashboard actions require a reason and confirmation; No Further Action and Close need no reason. Dashboard Close and delete requires confirmation but no reason. The initial case facts stay immutable: subsequent staff actions are additional audited attempts, not new offences. Timeout and demotion parameters are persisted by additive migration 0002_staff_attempt_parameters.sql for restart recovery.

Private notes come from the optional private-note input on staff /mod commands that offer it; automatic cases normally have no note. The dashboard states whether a concealed note exists.

Thread message layout selects Three containers, Single container, Compact incident, Conversation + evidence, or Spoiler evidence. A fictional dashboard preview changes with the selector without performing any moderation action. New threads place configured staff/user mentions, the opening message, rule name, confidence, original channel, escaped original message and staff buttons on one first message. Evidence exceeding Discord's aggregate display limit is delivered in a separate full evidence card without truncation. Refreshing buttons preserves the chosen containers and does not ping members again. Existing threads retain their layout when settings change and are not bulk-reformatted.

Check channel is read-only. Configure channel requires the checked revision and applies only the previewed minimum role/overwrite changes without removing unrelated Discord configuration.

Discord requirements

Helyx may need View Channel, Read Message History, Send Messages in Threads, Create Private Threads, Manage Threads, Manage Channels, Manage Messages, Manage Roles, Moderate Members, Kick Members, and Ban Members. Each operation checks only the permissions it needs at execution time; the manifest union is not proof of current authority and the module never requests Administrator.

Moderation consumes structural channel-delete, channel-update, guild-role-delete, and guild-role-update events for configuration and thread-access reconciliation. It does not require Message Content or a privileged Developer Portal intent.

Data, privacy and retention

| Record category | Retained data | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cases | Case/server identity, nullable subject and actor IDs, immutable action/reason fields, message-reference IDs, repeat metadata, state, safe outcome, revision, and timestamps. | | Attempts | Case, operation and actor IDs, action/reason, typed outcome, safe code, removed-role IDs, and timestamps. | | Operation receipts | Content-free idempotency input hash, case/attempt outcome references, and timestamp. | | Direct-message receipts | Case/template revision, delivery state, safe code, optional Discord message ID, and timestamps. | | Thread deliveries | Case/configuration IDs, private-thread/control message IDs, opaque control token, staged delivery states, fence/retry metadata, safe code, and timestamps. |

No offending message body, matched fragment, attachment, embed, or content-derived evidence is written to PostgreSQL, Logging, Audit, metrics, or traces. When transient evidence is available, it is delivered directly to Discord with mentions suppressed; absence never invalidates the case.

The versioned privacy provider covers cases directly and attempts, direct-message receipts, operation receipts, and thread deliveries through their case relationship, including while Moderation is disabled. Subject and actor associations can be detached; reasons, private notes, referenced Discord artefacts, and active safety constraints enter the declared manual-review or retention path. Disassociation is an operational correction, not a privacy erasure or hard delete.

Settled cases use the configured retention window. Active bans and open review cases remain protected; expiry removes attribution or private content without falsifying the anonymous safety history. Discord-owned threads and messages require separately tracked best-effort cleanup.

Operations and failure behavior

Case number allocation, pending case creation, and the first immutable attempt commit atomically before Discord mutation. Exact replay returns the original outcome; reused operation identities with different canonical input fail closed. Ambiguous Discord results are never blindly replayed: a bounded reconciliation inspects current state and either settles the case or leaves it for review.

Warning direct messages and violation-thread delivery are best effort and cannot roll back an applied moderation action. Thread creation, evidence, member addition, notification, control rendering, close, and access cleanup have typed retry/review states. Scheduled action reconciliation, thread delivery, and thread-access reconciliation use durable platform tasks with bounded attempts and requires_review exhaustion.

Close and delete requires Manage Threads and verifies the exact server, parent, private-thread identity and bot creator before deletion. An already-missing bound thread is idempotent completion. Failed or uncertain deletion is not reported as success: its durable recovery marker remains available for Reconcile case. Automatic recovery inspects state without blindly repeating deletion; an authorised dashboard reconciliation can retry the same audited deletion after fresh staff, configuration and binding checks. Records, case numbers and immutable action history are retained.

Disabling Moderation stops new commands, automated provider requests, and behavioural tasks without deleting cases. Health is unhealthy while stopped or when a required runtime service is missing, and degraded when durable recovery needs staff attention.

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

Documentation and support

• Moderation overview
• Moderation permissions
• Moderation troubleshooting
• Moderation FAQ
• Report an issue

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