core-framework 0.3.0__py3-none-any.whl

core_framework/domains/comment/service.py

@@ -0,0 +1,259 @@
+from collections import defaultdict
+from datetime import datetime
+from typing import Any, Final, Literal
+
+from ulid import ULID
+
+from core_framework.domains.comment import Comment, CommentPreview, CommentStats, CommentStatus, CommentWithMetadata
+from core_framework.domains.comment.enums import CommentSubjectType
+from core_framework.domains.comment.repository import CommentRepository
+
+
+class CommentService:
+    MAX_EDIT_COUNT: Final[int] = 5
+    MAX_REPLY_LEVEL: Final[int] = 4
+
+    def __init__(self, repository: CommentRepository):
+        self.repository = repository
+
+    async def add_comment(
+        self,
+        *,
+        author_id: str,
+        content: str,
+        subject_type: CommentSubjectType,
+        subject_id: str,
+    ) -> None:
+        await self.repository.insert_comment(
+            comment_id=str(ULID()),
+            author_id=author_id,
+            content=content,
+            subject_type=subject_type,
+            subject_id=subject_id,
+        )
+
+    async def add_reply(
+        self,
+        *,
+        author_id: str,
+        content: str,
+        parent_comment_id: str,
+    ) -> None:
+        await self.repository.insert_reply(
+            comment_id=str(ULID()),
+            author_id=author_id,
+            content=content,
+            parent_comment_id=parent_comment_id,
+            max_reply_level=self.MAX_REPLY_LEVEL,
+        )
+
+    async def retrieve_comment_content_mapping(self, *, comment_ids: set[str]) -> defaultdict[str, str]:
+        comment_content_mapping = await self.repository.select_comment_content_mapping(comment_ids=comment_ids)
+        return defaultdict(str, comment_content_mapping)
+
+    async def retrieve_comments_with_metadata(
+        self,
+        *,
+        cursor: datetime,
+        limit: int,
+    ) -> list[CommentWithMetadata]:
+        return await self.repository.select_comments_with_metadata(cursor=cursor, limit=limit)
+
+    async def retrieve_comment_with_metadata_by_id(self, *, comment_id: str) -> CommentWithMetadata:
+        return await self.repository.select_comment_with_metadata_by_id(comment_id=comment_id)
+
+    async def retrieve_comment_preview_mapping(self, *, comment_ids: set[str]) -> dict[str, CommentPreview]:
+        return await self.repository.select_comment_preview_mapping(comment_ids=comment_ids)
+
+    async def retrieve_post_comment_count(self, *, post_id: str) -> int:
+        return await self.repository.select_active_comment_count_for_post(post_id=post_id)
+
+    async def retrieve_comments_by_subject(
+        self,
+        *,
+        subject_type: CommentSubjectType,
+        subject_id: str,
+        cursor: datetime,
+        limit: int,
+        viewer_id: str | None,
+    ) -> list[Comment]:
+        return await self.repository.select_comments_by_subject(
+            subject_type=subject_type,
+            subject_id=subject_id,
+            cursor=cursor,
+            limit=limit,
+            viewer_id=viewer_id,
+        )
+
+    async def retrieve_comments_by_author_id(
+        self,
+        *,
+        author_id: str,
+        cursor: datetime,
+        limit: int,
+        viewer_id: str | None,
+    ) -> list[Comment]:
+        return await self.repository.select_comments_by_author_id(
+            author_id=author_id,
+            cursor=cursor,
+            limit=limit,
+            viewer_id=viewer_id,
+        )
+
+    async def retrieve_replies_by_parent_id(
+        self,
+        *,
+        parent_comment_id: str,
+        cursor: datetime,
+        limit: int,
+        viewer_id: str | None,
+    ) -> list[Comment]:
+        return await self.repository.select_replies_by_parent_id(
+            parent_comment_id=parent_comment_id,
+            cursor=cursor,
+            limit=limit,
+            viewer_id=viewer_id,
+        )
+
+    async def retrieve_comment_by_id(
+        self,
+        *,
+        comment_id: str,
+        viewer_id: str | None,
+    ) -> Comment | None:
+        return await self.repository.select_comment_by_id(
+            comment_id=comment_id,
+            viewer_id=viewer_id,
+        )
+
+    async def add_user_restriction_lookup(self, *, user_id: str, restriction_type: Literal["muted", "banned"]) -> None:
+        await self.repository.insert_user_restriction_lookup(
+            user_id=user_id,
+            restriction_type=restriction_type,
+        )
+
+    async def remove_user_restriction_lookup(self, *, user_id: str) -> None:
+        await self.repository.delete_user_restriction_lookup(user_id=user_id)
+
+    async def add_user_block_lookup(self, *, blocker_id: str, blocked_id: str) -> None:
+        await self.repository.insert_user_block_lookup(
+            blocker_id=blocker_id,
+            blocked_id=blocked_id,
+        )
+
+    async def remove_user_block_lookup(self, *, blocker_id: str, blocked_id: str) -> None:
+        await self.repository.delete_user_block_lookup(
+            blocker_id=blocker_id,
+            blocked_id=blocked_id,
+        )
+
+    async def remove_user(self, *, user_id: str) -> None:
+        await self.repository.delete_user(user_id=user_id)
+
+    async def add_comment_like(self, *, comment_id: str, liker_id: str) -> None:
+        await self.repository.insert_comment_like(
+            comment_id=comment_id,
+            liker_id=liker_id,
+        )
+
+    async def remove_comment_like(self, *, comment_id: str, liker_id: str) -> None:
+        await self.repository.delete_comment_like(
+            comment_id=comment_id,
+            liker_id=liker_id,
+        )
+
+    async def edit_comment(
+        self,
+        *,
+        comment_id: str,
+        author_id: str,
+        validated_update_request: dict[str, Any],
+    ) -> None:
+        await self.repository.update_comment(
+            comment_id=comment_id,
+            author_id=author_id,
+            comment_updates=validated_update_request,
+            max_edit_count=self.MAX_EDIT_COUNT,
+        )
+
+    async def remove_comment(self, *, comment_id: str, author_id: str) -> str | None:
+        return await self.repository.update_comment_status_by_id_and_author(
+            comment_id=comment_id,
+            author_id=author_id,
+            status=CommentStatus.DELETED,
+        )
+
+    async def set_comment_status_by_id(self, *, comment_id: str, status: CommentStatus) -> str | None:
+        return await self.repository.update_comment_status_by_id(
+            comment_id=comment_id,
+            status=status,
+        )
+
+    async def retrieve_comment_ids_by_subject_strong(
+        self,
+        *,
+        subject_type: CommentSubjectType,
+        subject_id: str,
+    ) -> set[str]:
+        return await self.repository.select_comment_ids_by_subject_strong(
+            subject_type=subject_type,
+            subject_id=subject_id,
+        )
+
+    async def retrieve_comment_subtree_ids_strong(self, *, root_comment_id: str) -> set[str]:
+        return await self.repository.select_comment_subtree_ids_strong(root_comment_id=root_comment_id)
+
+    async def retrieve_parent_comment_id_strong(self, *, comment_id: str) -> str | None:
+        return await self.repository.select_parent_comment_id_strong(comment_id=comment_id)
+
+    async def remove_comment_subtree(self, *, root_comment_id: str) -> None:
+        await self.repository.delete_comment_subtree(root_comment_id=root_comment_id)
+
+    async def remove_comments_by_subject(
+        self,
+        *,
+        subject_type: CommentSubjectType,
+        subject_id: str,
+    ) -> None:
+        await self.repository.delete_comments_by_subject(
+            subject_type=subject_type,
+            subject_id=subject_id,
+        )
+
+    async def retrieve_comment_ids_liked_by_user(self, *, liker_id: str, comment_ids: set[str]) -> frozenset[str]:
+        ids = await self.repository.select_comment_ids_liked_by_user(liker_id=liker_id, comment_ids=comment_ids)
+        return frozenset(ids)
+
+    async def retrieve_comment_stats_mapping(self, *, comment_ids: set[str]) -> defaultdict[str, CommentStats]:
+        comment_stats_mapping = await self.repository.select_comment_stats_mapping(comment_ids=comment_ids)
+        return defaultdict(lambda: CommentStats.DEFAULT, comment_stats_mapping)
+
+    async def insert_comment_stats_dirty(self, *, comment_id: str) -> None:
+        await self.repository.insert_comment_stats_dirty(comment_id=comment_id)
+
+    async def claim_comment_ids_dirty(self) -> list[str]:
+        return await self.repository.claim_comment_ids_dirty()
+
+    async def delete_comment_stats_dirty(self, *, comment_ids: set[str]) -> None:
+        await self.repository.delete_comment_stats_dirty(comment_ids=comment_ids)
+
+    async def update_comment_stats(
+        self,
+        *,
+        comment_id: str,
+        like_count: int,
+        reply_count: int,
+        report_count: int,
+    ) -> None:
+        await self.repository.update_comment_stats(
+            comment_id=comment_id,
+            like_count=like_count,
+            reply_count=reply_count,
+            report_count=report_count,
+        )
+
+    async def retrieve_comment_like_count(self, *, comment_id: str) -> int:
+        return await self.repository.select_comment_like_count(comment_id=comment_id)
+
+    async def retrieve_comment_reply_count(self, *, comment_id: str) -> int:
+        return await self.repository.select_comment_reply_count(comment_id=comment_id)

core_framework/domains/moderation/README.md

@@ -0,0 +1,138 @@
+# Moderation Domain
+
+## Scope
+
+Moderation is the **policy enforcement system**. It owns report intake (user, post, comment), review workflow, enforcement actions (restrictions), appeals, and audit. Provides the authoritative source for whether a user is restricted and why.
+
+**Policy enforcement lifecycle**: Intake (reports) → Review (moderation queue) → Enforcement (restrictions) → Appeals → Audit (history and actions).
+
+## Owns
+
+### Reports
+
+- **User reports**: User-to-user reports for policy violations
+- **Post reports**: User-to-post reports for policy violations
+- **Comment reports**: User-to-comment reports for policy violations
+- Report reason/category and freeform details
+- Reports are for analytics and moderation intake; reporters do not receive outcome notifications
+
+### Restriction History
+
+- Append-only audit log of all restriction changes
+- Tracks insert, update, and delete operations on restrictions
+- Each entry includes actor, target, action type, and restriction details
+- Entries are immutable once created
+
+### Restrictions
+
+- Current effective restriction state for each user (active, muted, banned)
+- Derived from enforcement actions or set directly by moderators
+- Includes reason and expiration (if applicable)
+
+### Appeals
+
+- User-initiated appeals (can only be submitted when muted or banned)
+- Appeal status lifecycle (pending, approved, denied)
+- User justification and admin decision reasoning
+- One pending appeal per user at a time
+
+### Audit Trail
+
+- All restriction changes are logged via restriction_history
+- Includes actor, target, action type, timestamp, and restriction details
+
+### Moderation Actions
+
+- Append-only audit log of all moderation actions (ban, mute, warn, unrestrict, add_note, change_username, delete_user, etc.)
+- Per-moderator retrieval for accountability; see [Moderation Flow: Moderator Actions](../../../docs/flows/moderation/moderator_actions.md)
+
+## Does Not Own
+
+- User identity, authentication, or profile data
+- User-to-user blocks (personal preference, owned by user domain)
+- Notification delivery mechanisms
+- Post/comment content and lifecycle (post and comment domains own content; moderation owns reports and enforcement; content domains perform removal when moderators decide)
+
+## Cross-Domain Sync
+
+- Moderation remains the source-of-truth for user restriction state.
+- Post-domain `user_restrictions_lookup` is a read-time mirror maintained from moderation application flows.
+- Restriction commands are idempotent and may run on no-op paths to reconcile mirror drift after partial failures.
+
+## Invariants
+
+- A user can have at most one active restriction at a time
+- Restriction history entries are append-only and immutable
+- Appeals can only be submitted when user is muted or banned
+- Appeals become read-only once decided (approved or denied)
+- Only users with moderator or admin roles can modify restrictions
+- Users can submit new appeals immediately after denial (only one pending appeal at a time)
+
+## Persistence Model
+
+### Tables
+
+#### user_reports
+
+- Tracks user-to-user reports for policy violations
+- Stores reporter_id, target_id, category, reason, and timestamp
+- One report per (reporter_id, target_id); duplicate reports are idempotent (no-op)
+- Reports are append-only and used for analytics; no status tracking
+
+#### post_reports
+
+- Tracks user-to-post reports for policy violations
+- Stores reporter_id, target_id (post ID), category, reason, and timestamp
+- One report per (reporter_id, target_id); duplicate reports are idempotent (no-op)
+- Append-only; used for moderation intake and analytics
+
+#### comment_reports
+
+- Tracks user-to-comment reports for policy violations
+- Stores reporter_id, target_id (comment ID), category, reason, and timestamp
+- Append-only; used for moderation intake and analytics
+
+#### restriction_history
+
+- Append-only audit log of all changes to user_restrictions
+- Tracks action type (inserted, updated, deleted) and restriction details
+- Each entry references the target user and acting moderator
+- Populated automatically via trigger on user_restrictions
+
+#### user_restrictions
+
+- Current effective restriction state per user
+- Stores restriction type (warned, muted, banned), reason, and expiry
+- Updated when new enforcement actions are applied
+- A user with no restriction has no row (or state = active)
+
+#### appeals
+
+- User appeals submitted when muted or banned
+- Stores user justification and admin decision reason
+- Tracks appeal status and reviewer
+- Rows become read-only once decided (enforced by trigger)
+
+#### moderation_actions
+
+- Append-only audit log of all moderation actions (ban, mute, warn, add_note, delete_user, etc.)
+- Stores actor_id, action_type, target_user_id (optional), action_metadata, created_at
+- Rows are never deleted when actors or targets are deleted (audit trail preserved)
+
+### Enums
+
+#### history_action
+
+- Types of history entries (inserted, updated, deleted)
+
+#### restriction_type
+
+- Types of restrictions (warned, muted, banned)
+
+#### appeal_status
+
+- Appeal lifecycle states (pending, approved, denied)
+
+#### report_category
+
+- Report categories used for policy classification (shared by user_reports, post_reports, comment_reports)

core_framework/domains/moderation/__init__.py

@@ -0,0 +1,47 @@
+from core_framework.domains.moderation.enums import (
+    AppealDecision,
+    HistoryAction,
+    ModerationActionType,
+    ReportCategory,
+    ReportType,
+    RestrictionCategory,
+    RestrictionType,
+)
+from core_framework.domains.moderation.exceptions import (
+    AppealAlreadyDecidedException,
+    AppealNotFoundException,
+    AppealRequirementException,
+    BaseModerationException,
+    ExistingPendingAppealException,
+    SelfReportException,
+)
+from core_framework.domains.moderation.models import (
+    InternalNote,
+    ModerationAction,
+    Report,
+    RestrictionHistory,
+    UserModeration,
+    UserRestriction,
+)
+
+__all__ = [
+    "ModerationActionType",
+    "ReportType",
+    "RestrictionType",
+    "AppealDecision",
+    "ReportCategory",
+    "RestrictionCategory",
+    "HistoryAction",
+    "Report",
+    "UserModeration",
+    "RestrictionHistory",
+    "InternalNote",
+    "ModerationAction",
+    "AppealAlreadyDecidedException",
+    "AppealNotFoundException",
+    "SelfReportException",
+    "ExistingPendingAppealException",
+    "AppealRequirementException",
+    "BaseModerationException",
+    "UserRestriction",
+]

core_framework/domains/moderation/dependencies.py

@@ -0,0 +1,29 @@
+from core_framework.core.runtime import CoreRuntime, unconfigured_dependency
+from core_framework.domains.moderation.repository import ModerationRepository
+from core_framework.domains.moderation.service import ModerationService
+
+
+def build_moderation_repository(runtime: CoreRuntime) -> ModerationRepository:
+    return ModerationRepository(runtime.write_postgres, runtime.read_postgres, runtime.write_postgres)
+
+
+def build_moderation_service(runtime: CoreRuntime) -> ModerationService:
+    return ModerationService(build_moderation_repository(runtime))
+
+
+def configure_moderation_dependencies(runtime: CoreRuntime) -> None:
+    global moderation_repository, moderation_service
+    moderation_repository = build_moderation_repository(runtime)
+    moderation_service = build_moderation_service(runtime)
+
+
+moderation_repository = unconfigured_dependency("ModerationRepository")
+moderation_service = unconfigured_dependency("ModerationService")
+
+__all__ = [
+    "build_moderation_repository",
+    "build_moderation_service",
+    "configure_moderation_dependencies",
+    "moderation_repository",
+    "moderation_service",
+]

core_framework/domains/moderation/enums.py

@@ -0,0 +1,62 @@
+from enum import StrEnum
+
+
+class RestrictionType(StrEnum):
+    ACTIVE = "active"
+    WARNED = "warned"
+    MUTED = "muted"
+    BANNED = "banned"
+
+
+class ReportType(StrEnum):
+    USER = "user"
+    POST = "post"
+    COMMENT = "comment"
+
+
+class ReportCategory(StrEnum):
+    SPAM = "spam"
+    HARASSMENT = "harassment"
+    INAPPROPRIATE_CONTENT = "inappropriate_content"
+    IMPERSONATION = "impersonation"
+    SELF_HARM = "self_harm"
+    HATE_SPEECH = "hate_speech"
+    VIOLENCE = "violence"
+    SCAM = "scam"
+    OTHER = "other"
+
+
+class RestrictionCategory(StrEnum):
+    SPAM = "spam"
+    HARASSMENT = "harassment"
+    INAPPROPRIATE_CONTENT = "inappropriate_content"
+    IMPERSONATION = "impersonation"
+    HARMFUL_CONTENT = "harmful_content"
+    SCAM = "scam"
+    OTHER = "other"
+
+
+class HistoryAction(StrEnum):
+    INSERTED = "inserted"
+    UPDATED = "updated"
+    DELETED = "deleted"
+
+
+class AppealDecision(StrEnum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    DENIED = "denied"
+
+
+class ModerationActionType(StrEnum):
+    BAN = "ban"
+    MUTE = "mute"
+    WARN = "warn"
+    UNRESTRICT = "unrestrict"
+    ADD_NOTE = "add_note"
+    DELETE_NOTE = "delete_note"
+    CHANGE_USERNAME = "change_username"
+    CHANGE_ROLE = "change_role"
+    CHANGE_PROFILE = "change_profile"
+    DECIDE_APPEAL = "decide_appeal"
+    DELETE_USER = "delete_user"

core_framework/domains/moderation/exceptions.py

@@ -0,0 +1,31 @@
+class BaseModerationException(Exception):
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class SelfReportException(BaseModerationException):
+    def __init__(self):
+        super().__init__("Self report is not allowed")
+
+
+class ExistingPendingAppealException(BaseModerationException):
+    def __init__(self):
+        super().__init__("An existing pending appeal already exists for this user")
+
+
+class AppealNotFoundException(BaseModerationException):
+    def __init__(self):
+        super().__init__("Appeal not found")
+
+
+class AppealAlreadyDecidedException(BaseModerationException):
+    def __init__(self):
+        super().__init__("Appeal already decided")
+
+
+class AppealRequirementException(BaseModerationException):
+    def __init__(self):
+        super().__init__("User must be muted or banned to submit an appeal")

core_framework/domains/moderation/models.py

@@ -0,0 +1,94 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar
+
+from core_framework.domains.moderation.enums import (
+    AppealDecision,
+    HistoryAction,
+    ModerationActionType,
+    ReportCategory,
+    RestrictionCategory,
+    RestrictionType,
+)
+from core_framework.domains.user import DEFAULT_USER_ID
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Report:
+    id: int
+    reporter_id: str
+    target_id: str
+    category: ReportCategory
+    reason: str
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserRestriction:
+    user_id: str
+    status: RestrictionType
+    category: RestrictionCategory
+    expires_at: datetime | None
+
+    DEFAULT: ClassVar[UserRestriction]
+
+
+UserRestriction.DEFAULT = UserRestriction(
+    user_id=DEFAULT_USER_ID,
+    status=RestrictionType.ACTIVE,
+    category=RestrictionCategory.OTHER,
+    expires_at=None,
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InternalNote:
+    id: int
+    target_user_id: str
+    actor_id: str
+    content: str
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserModeration:
+    restriction: UserRestriction
+    notes: tuple[InternalNote, ...]
+
+    DEFAULT: ClassVar[UserModeration]
+
+
+UserModeration.DEFAULT = UserModeration(restriction=UserRestriction.DEFAULT, notes=())
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Appeal:
+    id: int
+    user_id: str
+    justification: str
+    decision_reason: str | None
+    reviewer_id: str | None
+    status: AppealDecision
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RestrictionHistory:
+    user_id: str
+    action: HistoryAction
+    restriction_type: RestrictionType
+    category: RestrictionCategory
+    reason: str
+    actor_id: str | None
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ModerationAction:
+    id: int
+    actor_id: str
+    action_type: ModerationActionType
+    target_user_id: str | None
+    action_metadata: dict
+    created_at: datetime