@helyx/module-moderation 1.0.1

package/migrations/0001_moderation_foundation.sql

@@ -0,0 +1,552 @@
+CREATE TABLE IF NOT EXISTS moderation_case_sequences (
+  guild_id text PRIMARY KEY,
+  next_case_number bigint NOT NULL CHECK (next_case_number >= 1),
+  updated_at timestamptz NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS moderation_cases (
+  case_id uuid PRIMARY KEY,
+  guild_id text NOT NULL,
+  case_number bigint NOT NULL CHECK (case_number >= 1),
+  operation_key text NOT NULL CHECK (char_length(operation_key) BETWEEN 1 AND 200),
+  subject_user_id text,
+  actor_user_id text,
+  source text NOT NULL CHECK (source IN ('staff_command', 'auto_moderation')),
+  source_module_id text NOT NULL CHECK (char_length(source_module_id) BETWEEN 1 AND 100),
+  source_event_id text CHECK (source_event_id IS NULL OR char_length(source_event_id) BETWEEN 1 AND 200),
+  action text NOT NULL CHECK (action IN (
+    'warn', 'timeout', 'timeout_remove', 'kick', 'ban', 'demote',
+    'unban', 'delete_message', 'case_only'
+  )),
+  reason text NOT NULL CHECK (char_length(reason) BETWEEN 1 AND 500),
+  private_note text CHECK (private_note IS NULL OR char_length(private_note) BETWEEN 1 AND 1000),
+  evidence_channel_id text,
+  evidence_message_id text,
+  related_case_id uuid REFERENCES moderation_cases(case_id) ON DELETE RESTRICT,
+  requested_duration_seconds integer CHECK (
+    requested_duration_seconds IS NULL OR requested_duration_seconds BETWEEN 60 AND 2419200
+  ),
+  delete_message_seconds integer CHECK (
+    delete_message_seconds IS NULL OR delete_message_seconds IN (0, 3600, 21600, 86400, 259200, 604800)
+  ),
+  demote_role_ids jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(demote_role_ids) = 'array'),
+  observed_action_type text CHECK (
+    observed_action_type IS NULL OR observed_action_type IN (
+      'discord_native_block_message', 'discord_native_timeout'
+    )
+  ),
+  observed_timeout_duration_seconds integer CHECK (
+    observed_timeout_duration_seconds IS NULL OR observed_timeout_duration_seconds IN (
+      60, 300, 600, 3600, 86400, 604800
+    )
+  ),
+  repeat_rule_id text,
+  repeat_rule_revision integer CHECK (repeat_rule_revision IS NULL OR repeat_rule_revision >= 1),
+  repeat_configuration_revision text,
+  repeat_policy_fingerprint text,
+  repeat_window_starts_at timestamptz,
+  repeat_offence_ordinal smallint CHECK (repeat_offence_ordinal IS NULL OR repeat_offence_ordinal BETWEEN 1 AND 3),
+  repeat_offence_count integer CHECK (repeat_offence_count IS NULL OR repeat_offence_count >= 1),
+  open_violation_thread boolean NOT NULL DEFAULT false,
+  state text NOT NULL CHECK (state IN (
+    'pending', 'applied', 'failed', 'review', 'rejected', 'corrected', 'void'
+  )),
+  safe_outcome text CHECK (safe_outcome IS NULL OR char_length(safe_outcome) BETWEEN 1 AND 100),
+  revision integer NOT NULL DEFAULT 1 CHECK (revision >= 1),
+  disassociated_at timestamptz,
+  settled_at timestamptz,
+  retention_expires_at timestamptz,
+  retention_processed_at timestamptz,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (guild_id, case_id),
+  UNIQUE (guild_id, case_number),
+  UNIQUE (guild_id, source_module_id, operation_key),
+  CHECK (subject_user_id IS NULL OR subject_user_id ~ '^[0-9]{17,20}$'),
+  CHECK (actor_user_id IS NULL OR actor_user_id ~ '^[0-9]{17,20}$'),
+  CHECK ((evidence_channel_id IS NULL) = (evidence_message_id IS NULL)),
+  CHECK (evidence_channel_id IS NULL OR evidence_channel_id ~ '^[0-9]{17,20}$'),
+  CHECK (evidence_message_id IS NULL OR evidence_message_id ~ '^[0-9]{17,20}$'),
+  CHECK (
+    (observed_action_type IS NULL AND observed_timeout_duration_seconds IS NULL)
+    OR (observed_action_type = 'discord_native_block_message' AND observed_timeout_duration_seconds IS NULL)
+    OR (observed_action_type = 'discord_native_timeout' AND observed_timeout_duration_seconds IS NOT NULL)
+  ),
+  CHECK (
+    (repeat_rule_id IS NULL AND repeat_rule_revision IS NULL AND repeat_configuration_revision IS NULL
+      AND repeat_policy_fingerprint IS NULL AND repeat_window_starts_at IS NULL
+      AND repeat_offence_ordinal IS NULL AND repeat_offence_count IS NULL)
+    OR (repeat_rule_id IS NOT NULL AND repeat_rule_revision IS NOT NULL
+      AND repeat_configuration_revision IS NOT NULL AND repeat_policy_fingerprint IS NOT NULL
+      AND repeat_window_starts_at IS NOT NULL AND repeat_offence_ordinal IS NOT NULL
+      AND repeat_offence_count IS NOT NULL)
+  ),
+  CHECK (disassociated_at IS NULL OR subject_user_id IS NULL),
+  CHECK (
+    retention_expires_at IS NULL OR (
+      settled_at IS NOT NULL
+      AND retention_expires_at >= settled_at + INTERVAL '30 days'
+      AND retention_expires_at <= settled_at + INTERVAL '730 days'
+    )
+  ),
+  CHECK (
+    retention_processed_at IS NULL OR (
+      retention_expires_at IS NOT NULL AND retention_processed_at >= retention_expires_at
+    )
+  ),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS moderation_cases_guild_created_idx
+  ON moderation_cases (guild_id, created_at DESC, case_id DESC);
+CREATE INDEX IF NOT EXISTS moderation_cases_subject_created_idx
+  ON moderation_cases (guild_id, subject_user_id, created_at DESC, case_id DESC)
+  WHERE subject_user_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS moderation_cases_actor_created_idx
+  ON moderation_cases (guild_id, actor_user_id, created_at DESC, case_id DESC)
+  WHERE actor_user_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS moderation_cases_rule_created_idx
+  ON moderation_cases (guild_id, repeat_rule_id, created_at DESC, case_id DESC)
+  WHERE repeat_rule_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS moderation_cases_action_state_created_idx
+  ON moderation_cases (guild_id, action, state, created_at DESC, case_id DESC);
+CREATE INDEX IF NOT EXISTS moderation_cases_retention_due_idx
+  ON moderation_cases (retention_expires_at, case_id)
+  WHERE retention_expires_at IS NOT NULL AND retention_processed_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS moderation_action_attempts (
+  attempt_id uuid PRIMARY KEY,
+  guild_id text NOT NULL,
+  case_id uuid NOT NULL,
+  operation_key text NOT NULL CHECK (char_length(operation_key) BETWEEN 1 AND 200),
+  actor_user_id text,
+  attempt_number integer NOT NULL CHECK (attempt_number >= 1),
+  action text NOT NULL CHECK (action IN (
+    'warn', 'timeout', 'timeout_remove', 'kick', 'ban', 'demote',
+    'unban', 'delete_message', 'case_only'
+  )),
+  reason text NOT NULL CHECK (char_length(reason) BETWEEN 1 AND 500),
+  outcome text NOT NULL CHECK (outcome IN (
+    'pending', 'succeeded', 'already_applied', 'failed', 'ambiguous',
+    'rejected', 'no_longer_required', 'member_missing', 'missing_permission',
+    'hierarchy_blocked', 'review_required'
+  )),
+  safe_code text CHECK (safe_code IS NULL OR char_length(safe_code) BETWEEN 1 AND 100),
+  removed_role_ids jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(removed_role_ids) = 'array'),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  FOREIGN KEY (guild_id, case_id)
+    REFERENCES moderation_cases(guild_id, case_id) ON DELETE RESTRICT,
+  UNIQUE (attempt_id, attempt_number),
+  UNIQUE (case_id, attempt_number),
+  UNIQUE (case_id, operation_key),
+  CHECK (actor_user_id IS NULL OR actor_user_id ~ '^[0-9]{17,20}$'),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS moderation_action_attempts_case_created_idx
+  ON moderation_action_attempts (case_id, created_at, attempt_id);
+
+CREATE TABLE IF NOT EXISTS moderation_case_operations (
+  operation_id uuid PRIMARY KEY,
+  guild_id text NOT NULL,
+  operation_key text NOT NULL CHECK (char_length(operation_key) BETWEEN 1 AND 200),
+  case_id uuid,
+  operation_type text NOT NULL CHECK (operation_type IN (
+    'create_case', 'open_attempt', 'settle_attempt', 'disassociate',
+    'reconcile', 'correct', 'thread_control', 'record_observation', 'retention'
+  )),
+  input_hash text NOT NULL CHECK (input_hash ~ '^[a-f0-9]{64}$'),
+  outcome_code text NOT NULL CHECK (char_length(outcome_code) BETWEEN 1 AND 100),
+  outcome_revision integer CHECK (outcome_revision IS NULL OR outcome_revision >= 1),
+  outcome_attempt_id uuid,
+  outcome_attempt_number integer CHECK (outcome_attempt_number IS NULL OR outcome_attempt_number >= 1),
+  created_at timestamptz NOT NULL,
+  FOREIGN KEY (guild_id, case_id)
+    REFERENCES moderation_cases(guild_id, case_id) ON DELETE RESTRICT,
+  FOREIGN KEY (outcome_attempt_id, outcome_attempt_number)
+    REFERENCES moderation_action_attempts(attempt_id, attempt_number) ON DELETE RESTRICT,
+  UNIQUE (guild_id, operation_key),
+  CHECK ((outcome_attempt_id IS NULL) = (outcome_attempt_number IS NULL))
+);
+
+CREATE INDEX IF NOT EXISTS moderation_case_operations_case_created_idx
+  ON moderation_case_operations (case_id, created_at, operation_id)
+  WHERE case_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS moderation_dm_receipts (
+  receipt_id uuid PRIMARY KEY,
+  guild_id text NOT NULL,
+  case_id uuid NOT NULL,
+  template_revision integer NOT NULL CHECK (template_revision >= 1),
+  delivery_state text NOT NULL CHECK (delivery_state IN (
+    'not_requested', 'pending', 'succeeded', 'failed', 'retry_pending', 'review_required'
+  )),
+  safe_code text CHECK (safe_code IS NULL OR char_length(safe_code) BETWEEN 1 AND 100),
+  message_id text CHECK (message_id IS NULL OR message_id ~ '^[0-9]{17,20}$'),
+  attempted_at timestamptz,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  FOREIGN KEY (guild_id, case_id)
+    REFERENCES moderation_cases(guild_id, case_id) ON DELETE RESTRICT,
+  UNIQUE (guild_id, case_id),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS moderation_dm_receipts_case_idx
+  ON moderation_dm_receipts (case_id, created_at, receipt_id);
+
+CREATE TABLE IF NOT EXISTS moderation_thread_deliveries (
+  delivery_id uuid PRIMARY KEY,
+  guild_id text NOT NULL,
+  case_id uuid NOT NULL,
+  case_revision integer NOT NULL CHECK (case_revision >= 1),
+  operation_key text NOT NULL CHECK (char_length(operation_key) BETWEEN 1 AND 200),
+  parent_channel_id text CHECK (parent_channel_id IS NULL OR parent_channel_id ~ '^[0-9]{17,20}$'),
+  access_role_id text CHECK (access_role_id IS NULL OR access_role_id ~ '^[0-9]{17,20}$'),
+  thread_id text CHECK (thread_id IS NULL OR thread_id ~ '^[0-9]{17,20}$'),
+  control_token text CHECK (control_token IS NULL OR char_length(control_token) BETWEEN 32 AND 200),
+  control_message_id text CHECK (control_message_id IS NULL OR control_message_id ~ '^[0-9]{17,20}$'),
+  member_state text NOT NULL CHECK (member_state IN (
+    'not_requested', 'pending', 'succeeded', 'failed', 'retry_pending', 'review_required'
+  )),
+  evidence_state text NOT NULL CHECK (evidence_state IN (
+    'not_requested', 'pending', 'succeeded', 'failed', 'retry_pending', 'review_required'
+  )),
+  opening_state text NOT NULL CHECK (opening_state IN (
+    'not_requested', 'pending', 'succeeded', 'failed', 'retry_pending', 'review_required'
+  )),
+  notification_state text NOT NULL CHECK (notification_state IN (
+    'not_requested', 'pending', 'succeeded', 'failed', 'retry_pending', 'review_required'
+  )),
+  close_state text NOT NULL CHECK (close_state IN (
+    'not_requested', 'pending', 'succeeded', 'failed', 'retry_pending', 'review_required'
+  )),
+  resolution_state text NOT NULL CHECK (resolution_state IN (
+    'awaiting_staff', 'resolved', 'closed'
+  )),
+  attempt_count integer NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  fence_token bigint NOT NULL DEFAULT 0 CHECK (fence_token >= 0),
+  safe_code text CHECK (safe_code IS NULL OR char_length(safe_code) BETWEEN 1 AND 100),
+  retry_at timestamptz,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  FOREIGN KEY (guild_id, case_id)
+    REFERENCES moderation_cases(guild_id, case_id) ON DELETE RESTRICT,
+  UNIQUE (guild_id, case_id),
+  UNIQUE (guild_id, operation_key),
+  UNIQUE (control_token),
+  CHECK (updated_at >= created_at)
+);
+
+CREATE INDEX IF NOT EXISTS moderation_thread_deliveries_retry_idx
+  ON moderation_thread_deliveries (retry_at, delivery_id)
+  WHERE retry_at IS NOT NULL;
+CREATE INDEX IF NOT EXISTS moderation_thread_deliveries_state_idx
+  ON moderation_thread_deliveries (guild_id, resolution_state, updated_at, delivery_id);
+
+CREATE OR REPLACE FUNCTION moderation_protect_case_immutability()
+RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  subject_detachment boolean := (
+    OLD.subject_user_id IS NOT NULL
+    AND NEW.subject_user_id IS NULL
+    AND OLD.disassociated_at IS NULL
+    AND NEW.disassociated_at IS NOT NULL
+  );
+  retention_transition boolean := (
+    OLD.retention_processed_at IS NULL
+    AND NEW.retention_processed_at IS NOT NULL
+    AND OLD.retention_expires_at IS NOT NULL
+    AND NEW.retention_expires_at = OLD.retention_expires_at
+    AND NEW.retention_processed_at >= OLD.retention_expires_at
+  );
+BEGIN
+  IF retention_transition AND OLD.state = 'review' THEN
+    RAISE EXCEPTION 'open review cases cannot be retention processed';
+  END IF;
+  IF retention_transition AND OLD.action = 'ban' AND OLD.state = 'applied'
+    AND NOT EXISTS (
+      SELECT 1 FROM moderation_cases unban_case
+      WHERE unban_case.related_case_id = OLD.case_id
+        AND unban_case.action = 'unban'
+        AND unban_case.state = 'applied'
+    ) THEN
+    RAISE EXCEPTION 'active ban cases cannot be retention processed';
+  END IF;
+  IF retention_transition AND (
+    NEW.subject_user_id IS NOT NULL OR NEW.actor_user_id IS NOT NULL
+    OR NEW.private_note IS NOT NULL OR NEW.evidence_channel_id IS NOT NULL
+    OR NEW.evidence_message_id IS NOT NULL OR NEW.repeat_rule_id IS NOT NULL
+    OR NEW.repeat_rule_revision IS NOT NULL
+    OR NEW.repeat_configuration_revision IS NOT NULL
+    OR NEW.repeat_policy_fingerprint IS NOT NULL
+    OR NEW.repeat_window_starts_at IS NOT NULL
+    OR NEW.repeat_offence_ordinal IS NOT NULL
+    OR NEW.repeat_offence_count IS NOT NULL
+    OR NEW.disassociated_at IS NULL
+    OR NEW.operation_key <> 'retained:' || OLD.case_id::text
+  ) THEN
+    RAISE EXCEPTION 'moderation case retention redaction is incomplete';
+  END IF;
+  IF subject_detachment AND (
+    NEW.repeat_rule_id IS NOT NULL OR NEW.repeat_rule_revision IS NOT NULL
+    OR NEW.repeat_configuration_revision IS NOT NULL
+    OR NEW.repeat_policy_fingerprint IS NOT NULL
+    OR NEW.repeat_window_starts_at IS NOT NULL
+    OR NEW.repeat_offence_ordinal IS NOT NULL
+    OR NEW.repeat_offence_count IS NOT NULL
+  ) THEN
+    RAISE EXCEPTION 'moderation case disassociation must remove repeat linkage';
+  END IF;
+  IF ROW(
+    NEW.case_id, NEW.guild_id, NEW.case_number,
+    NEW.source, NEW.source_module_id, NEW.source_event_id, NEW.action,
+    NEW.reason, NEW.related_case_id,
+    NEW.requested_duration_seconds, NEW.delete_message_seconds,
+    NEW.demote_role_ids, NEW.open_violation_thread,
+    NEW.created_at
+  ) IS DISTINCT FROM ROW(
+    OLD.case_id, OLD.guild_id, OLD.case_number,
+    OLD.source, OLD.source_module_id, OLD.source_event_id, OLD.action,
+    OLD.reason, OLD.related_case_id,
+    OLD.requested_duration_seconds, OLD.delete_message_seconds,
+    OLD.demote_role_ids, OLD.open_violation_thread,
+    OLD.created_at
+  ) THEN
+    RAISE EXCEPTION 'moderation case immutable fields cannot change';
+  END IF;
+  IF NEW.operation_key IS DISTINCT FROM OLD.operation_key
+    AND NOT (
+      retention_transition
+      AND NEW.operation_key = 'retained:' || OLD.case_id::text
+    ) THEN
+    RAISE EXCEPTION 'moderation case operation key is immutable';
+  END IF;
+  IF NEW.private_note IS DISTINCT FROM OLD.private_note
+    AND NOT (
+      (retention_transition OR subject_detachment)
+      AND OLD.private_note IS NOT NULL
+      AND NEW.private_note IS NULL
+    ) THEN
+    RAISE EXCEPTION 'moderation case private note is immutable';
+  END IF;
+  IF ROW(NEW.evidence_channel_id, NEW.evidence_message_id)
+    IS DISTINCT FROM ROW(OLD.evidence_channel_id, OLD.evidence_message_id)
+    AND NOT (
+      retention_transition
+      AND NEW.evidence_channel_id IS NULL
+      AND NEW.evidence_message_id IS NULL
+    ) THEN
+    RAISE EXCEPTION 'moderation case evidence reference is immutable';
+  END IF;
+  IF NEW.actor_user_id IS DISTINCT FROM OLD.actor_user_id
+    AND NOT (OLD.actor_user_id IS NOT NULL AND NEW.actor_user_id IS NULL) THEN
+    RAISE EXCEPTION 'moderation case actor can only be detached';
+  END IF;
+  IF OLD.observed_action_type IS NOT NULL AND ROW(
+    NEW.observed_action_type, NEW.observed_timeout_duration_seconds
+  ) IS DISTINCT FROM ROW(
+    OLD.observed_action_type, OLD.observed_timeout_duration_seconds
+  ) THEN
+    RAISE EXCEPTION 'recorded native moderation observation is immutable';
+  END IF;
+  IF NEW.subject_user_id IS DISTINCT FROM OLD.subject_user_id
+    AND NOT subject_detachment THEN
+    RAISE EXCEPTION 'moderation case subject can only be disassociated';
+  END IF;
+  IF OLD.disassociated_at IS NOT NULL
+    AND NEW.disassociated_at IS DISTINCT FROM OLD.disassociated_at THEN
+    RAISE EXCEPTION 'moderation case disassociation is immutable';
+  END IF;
+  IF OLD.retention_processed_at IS NOT NULL
+    AND NEW.retention_expires_at IS DISTINCT FROM OLD.retention_expires_at THEN
+    RAISE EXCEPTION 'processed moderation case retention expiry is immutable';
+  END IF;
+  IF OLD.retention_expires_at IS NOT NULL AND (
+    NEW.retention_expires_at IS NULL
+    OR NEW.retention_expires_at < OLD.retention_expires_at
+    OR NEW.settled_at IS NULL
+    OR NEW.retention_expires_at < NEW.settled_at + INTERVAL '30 days'
+    OR NEW.retention_expires_at > NEW.settled_at + INTERVAL '730 days'
+  ) THEN
+    RAISE EXCEPTION 'moderation case retention expiry cannot shorten';
+  END IF;
+  IF NEW.retention_processed_at IS DISTINCT FROM OLD.retention_processed_at
+    AND NOT retention_transition THEN
+    RAISE EXCEPTION 'moderation case retention processing is immutable';
+  END IF;
+  IF ROW(
+    NEW.repeat_rule_id, NEW.repeat_rule_revision,
+    NEW.repeat_configuration_revision, NEW.repeat_policy_fingerprint,
+    NEW.repeat_window_starts_at, NEW.repeat_offence_ordinal,
+    NEW.repeat_offence_count
+  ) IS DISTINCT FROM ROW(
+    OLD.repeat_rule_id, OLD.repeat_rule_revision,
+    OLD.repeat_configuration_revision, OLD.repeat_policy_fingerprint,
+    OLD.repeat_window_starts_at, OLD.repeat_offence_ordinal,
+    OLD.repeat_offence_count
+  ) AND NOT (
+    NEW.subject_user_id IS NULL AND NEW.disassociated_at IS NOT NULL
+    AND NEW.repeat_rule_id IS NULL AND NEW.repeat_rule_revision IS NULL
+    AND NEW.repeat_configuration_revision IS NULL
+    AND NEW.repeat_policy_fingerprint IS NULL
+    AND NEW.repeat_window_starts_at IS NULL
+    AND NEW.repeat_offence_ordinal IS NULL
+    AND NEW.repeat_offence_count IS NULL
+  ) THEN
+    RAISE EXCEPTION 'moderation repeat association is immutable';
+  END IF;
+  IF NEW.revision <= OLD.revision THEN
+    RAISE EXCEPTION 'moderation case revision must increase';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER moderation_cases_immutable_update
+BEFORE UPDATE ON moderation_cases
+FOR EACH ROW EXECUTE FUNCTION moderation_protect_case_immutability();
+
+CREATE OR REPLACE FUNCTION moderation_protect_attempt_immutability()
+RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  retention_processed boolean;
+BEGIN
+  SELECT c.retention_processed_at IS NOT NULL INTO retention_processed
+    FROM moderation_cases c WHERE c.case_id = OLD.case_id;
+  IF ROW(
+    NEW.attempt_id, NEW.guild_id, NEW.case_id,
+    NEW.attempt_number, NEW.action,
+    NEW.created_at
+  ) IS DISTINCT FROM ROW(
+    OLD.attempt_id, OLD.guild_id, OLD.case_id,
+    OLD.attempt_number, OLD.action,
+    OLD.created_at
+  ) THEN
+    RAISE EXCEPTION 'moderation attempt immutable fields cannot change';
+  END IF;
+  IF NEW.operation_key IS DISTINCT FROM OLD.operation_key
+    AND NOT (
+      retention_processed
+      AND NEW.operation_key = 'retained:' || OLD.attempt_id::text
+    ) THEN
+    RAISE EXCEPTION 'moderation attempt operation key is immutable';
+  END IF;
+  IF NEW.reason IS DISTINCT FROM OLD.reason
+    AND NOT (
+      retention_processed AND NEW.reason = '[redacted after retention]'
+    ) THEN
+    RAISE EXCEPTION 'moderation attempt reason is immutable';
+  END IF;
+  IF NEW.actor_user_id IS DISTINCT FROM OLD.actor_user_id
+    AND NOT (OLD.actor_user_id IS NOT NULL AND NEW.actor_user_id IS NULL) THEN
+    RAISE EXCEPTION 'moderation attempt actor can only be detached';
+  END IF;
+  IF OLD.outcome <> 'pending' AND ROW(
+    NEW.outcome, NEW.safe_code, NEW.removed_role_ids
+  ) IS DISTINCT FROM ROW(
+    OLD.outcome, OLD.safe_code, OLD.removed_role_ids
+  ) THEN
+    RAISE EXCEPTION 'settled moderation attempts are immutable';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER moderation_action_attempts_immutable_update
+BEFORE UPDATE ON moderation_action_attempts
+FOR EACH ROW EXECUTE FUNCTION moderation_protect_attempt_immutability();
+
+CREATE OR REPLACE FUNCTION moderation_reject_immutable_delete()
+RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION 'immutable moderation audit rows cannot be deleted';
+END;
+$$;
+
+CREATE TRIGGER moderation_action_attempts_immutable_delete
+BEFORE DELETE ON moderation_action_attempts
+FOR EACH ROW EXECUTE FUNCTION moderation_reject_immutable_delete();
+
+CREATE OR REPLACE FUNCTION moderation_protect_case_operation_immutability()
+RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  retention_processed boolean;
+BEGIN
+  SELECT c.retention_processed_at IS NOT NULL INTO retention_processed
+    FROM moderation_cases c WHERE c.case_id = OLD.case_id;
+  IF ROW(
+    NEW.operation_id, NEW.guild_id, NEW.case_id, NEW.operation_type,
+    NEW.input_hash, NEW.outcome_code, NEW.outcome_revision,
+    NEW.outcome_attempt_id, NEW.outcome_attempt_number, NEW.created_at
+  ) IS DISTINCT FROM ROW(
+    OLD.operation_id, OLD.guild_id, OLD.case_id, OLD.operation_type,
+    OLD.input_hash, OLD.outcome_code, OLD.outcome_revision,
+    OLD.outcome_attempt_id, OLD.outcome_attempt_number, OLD.created_at
+  ) OR (
+    NEW.operation_key IS DISTINCT FROM OLD.operation_key AND NOT (
+      retention_processed
+      AND NEW.operation_key = 'retained:' || OLD.operation_id::text
+    )
+  ) THEN
+    RAISE EXCEPTION 'moderation case operation is immutable';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER moderation_case_operations_immutable_update
+BEFORE UPDATE ON moderation_case_operations
+FOR EACH ROW EXECUTE FUNCTION moderation_protect_case_operation_immutability();
+
+CREATE TRIGGER moderation_case_operations_immutable_delete
+BEFORE DELETE ON moderation_case_operations
+FOR EACH ROW EXECUTE FUNCTION moderation_reject_immutable_delete();
+
+CREATE OR REPLACE FUNCTION moderation_protect_dm_receipt_retention()
+RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  retention_processed boolean;
+BEGIN
+  SELECT c.retention_processed_at IS NOT NULL INTO retention_processed
+    FROM moderation_cases c WHERE c.case_id = OLD.case_id;
+  IF retention_processed AND NEW.message_id IS NOT NULL THEN
+    RAISE EXCEPTION 'retained moderation DM identifiers must stay redacted';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER moderation_dm_receipts_retention_update
+BEFORE UPDATE ON moderation_dm_receipts
+FOR EACH ROW EXECUTE FUNCTION moderation_protect_dm_receipt_retention();
+
+CREATE OR REPLACE FUNCTION moderation_protect_thread_delivery_retention()
+RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  retention_processed boolean;
+BEGIN
+  SELECT c.retention_processed_at IS NOT NULL INTO retention_processed
+    FROM moderation_cases c WHERE c.case_id = OLD.case_id;
+  IF retention_processed AND (
+    NEW.parent_channel_id IS NOT NULL OR NEW.access_role_id IS NOT NULL
+    OR NEW.thread_id IS NOT NULL OR NEW.control_token IS NOT NULL
+    OR NEW.control_message_id IS NOT NULL
+  ) THEN
+    RAISE EXCEPTION 'retained moderation thread identifiers must stay redacted';
+  END IF;
+  IF NEW.operation_key IS DISTINCT FROM OLD.operation_key
+    AND NOT (
+      retention_processed
+      AND NEW.operation_key = 'retained:' || OLD.delivery_id::text
+    ) THEN
+    RAISE EXCEPTION 'moderation thread operation key is immutable';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER moderation_thread_deliveries_retention_update
+BEFORE UPDATE ON moderation_thread_deliveries
+FOR EACH ROW EXECUTE FUNCTION moderation_protect_thread_delivery_retention();

package/migrations/0002_staff_attempt_parameters.sql

@@ -0,0 +1,27 @@
+ALTER TABLE moderation_action_attempts
+  ADD COLUMN requested_duration_seconds integer CHECK (
+    requested_duration_seconds IS NULL OR (
+      action = 'timeout' AND requested_duration_seconds BETWEEN 60 AND 2419200
+    )
+  ),
+  ADD COLUMN requested_demote_role_ids jsonb CHECK (
+    requested_demote_role_ids IS NULL OR (
+      action = 'demote' AND jsonb_typeof(requested_demote_role_ids) = 'array'
+      AND jsonb_array_length(requested_demote_role_ids) BETWEEN 1 AND 10
+    )
+  );
+
+CREATE FUNCTION moderation_protect_attempt_parameters()
+RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  IF ROW(NEW.requested_duration_seconds, NEW.requested_demote_role_ids)
+    IS DISTINCT FROM ROW(OLD.requested_duration_seconds, OLD.requested_demote_role_ids) THEN
+    RAISE EXCEPTION 'moderation attempt request parameters are immutable';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER moderation_action_attempts_parameters_immutable_update
+BEFORE UPDATE ON moderation_action_attempts
+FOR EACH ROW EXECUTE FUNCTION moderation_protect_attempt_parameters();

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@helyx/module-moderation",
+  "version": "1.0.1",
+  "description": "Apply accountable staff moderation actions and review durable cases.",
+  "keywords": [
+    "helyx",
+    "discord",
+    "moderation",
+    "module"
+  ],
+  "private": false,
+  "license": "HSAL 1.0",
+  "homepage": "https://helyx.gg/modules/",
+  "bugs": {
+    "url": "https://github.com/ZyC0R3/Helyx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZyC0R3/Helyx.git",
+    "directory": "modules/moderation"
+  },
+  "engines": {
+    "node": ">=24 <27",
+    "npm": ">=11"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "migrations",
+    "manifest.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --root ../.. modules/moderation/tests"
+  },
+  "dependencies": {
+    "@helyx/module-manifest": ">=0.11.0 <0.12.0",
+    "@helyx/sdk": ">=0.13.0 <0.14.0"
+  }
+}