core-framework 0.3.0__py3-none-any.whl

core_framework/domains/comment/README.md

@@ -0,0 +1,243 @@
+# Comment Domain
+
+## Implementation Status
+
+- **Implemented**: Root and reply creation; comment retrieval (by subject, replies under a parent, by author with viewer restrictions/blocks). Materialized path stored as PostgreSQL `ltree` (path labels are comment IDs); max reply depth enforced in application code. Author comment edit with a fixed max edit count and `edited_count` / `edited_at`. Soft delete via `comment_status` (`active` / `deleted`) for the author’s own comments and status updates by comment id (used by admin inactive/restore flows outside this package). Comment likes (idempotent like/unlike; counts feed into stats). Engagement stats materialized in `comment_stats`, driven by a `comment_stats_dirty` table and periodic aggregation (see `docs/flows/comments/comment_stats_aggregation.md`).
+- **Planned**: Media attachments on comments (metadata, ordering, processing lifecycle as described in this document).
+
+## Scope
+
+Owns comment content lifecycle, subject attachment, reply hierarchy, media attachments, and comment likes. Provides the authoritative source for comment existence and current content state. Comments are always attached to a subject (e.g., post, user wall); the subject cannot be null.
+
+## Owns
+
+### Comment Content
+
+- Comment creation, retrieval, editing, and deletion state
+- Author-owned content fields (body and optional metadata)
+- Comment timestamps (created_at, updated_at, edited_at)
+- Edit limit (max 5 edits) and `edited_count` for author capability display
+- Comment ID uses ULID format (varchar(26)), same as posts
+
+### Subject Attachment
+
+- Every comment is attached to exactly one subject
+- Subject is identified by `subject_type` (e.g., post, user_wall) and `subject_id`
+- Subject cannot be null; a comment always belongs to something
+- Domain stores only IDs for external entities (no cross-domain foreign keys)
+
+### Reply Hierarchy
+
+- Comments can be replies to other comments (nested structure)
+- Top-level comments have `parent_comment_id` = null
+- Replies have `parent_comment_id` pointing to the parent comment
+- **Database layer**: No restriction on nesting depth
+- **Application layer**: Maximum depth of 5 levels (configurable in code; can be increased later without schema changes)
+- **Materialized path (`ltree`)**: Each comment stores `path` as an `ltree` built from **comment IDs** (ULIDs) as labels, plus `level` (0 = root, 1 = first reply, …) for depth checks. Used for ancestor/descendant and subtree queries, not for display order.
+
+### Comment Lifecycle
+
+- Soft-delete state for comment lifecycle management
+- Readability/editability rules based on state
+
+### Media Attachments
+
+- Comment-linked media metadata for images and videos
+- Attachment ordering and per-comment attachment limits
+- Media state lifecycle (processing, ready, failed, removed)
+
+### Comment Likes
+
+- User-to-comment like relationships
+- Idempotent like/unlike behavior as relationship state
+- Aggregate like counts derived from comment_like rows
+
+### Engagement Analytics
+
+- Comment engagement counters and derived analytics (likes, replies, reports)
+- Aggregation strategy for comment metrics (similar to post_stats)
+- Retrieval of comment-level stats for display and sorting
+
+### Post `comment_count` (read by post domain)
+
+For `subject_type = post`, **`post.post_stats.comment_count`** is derived in **`aggregate_post_stats`** using **`select_active_comment_count_for_post`**: count **`active`** comments where **no ancestor on that post** has **`deleted`** status, using **`ltree` `path`** and the `@>` ancestor operator. A soft-deleted comment therefore removes itself and **all descendants** from that tally until counts are recomputed. See `docs/flows/posts/post_stats_aggregation.md` (Comment count semantics).
+
+## Does Not Own
+
+- User identity, authentication, or profile data
+- User relationship graph (follows/friends/blocks)
+- Subject entities (posts, user walls, etc.)—comment domain stores subject_type and subject_id only
+- Comment reports (owned by moderation domain)
+- Enforcement decisions (ban/mute/warn) and appeal lifecycle—owned by moderation domain
+- Hashtags (comments do not support hashtags)
+
+## User removal and redacted authors (design)
+
+When an account is removed, **comments authored by that user are not hard-deleted**. The row and `id` stay so **replies and `ltree` structure remain valid** and other participants can still read the thread.
+
+- Set `author_id` to a **well-known sentinel** (e.g. `DELETED`) defined in application/domain code; it must not match a real user id.
+- **Redact** `content` to an agreed placeholder; the comment remains **visible** in listings where policy allows (e.g. not soft-deleted).
+- **Moderation**: keep existing `comment_reports` and `comment_likes`; do **not** rewrite `reporter_id` / `liker_id` to the sentinel (orphan UUIDs are fine for current product). Public comment **GET** responses set **`engagement_allowed`** to `false` when `author_id` is the redaction sentinel so clients can hide like/report/reply affordances; **write** endpoints do not enforce that flag.
+- **User identity**: resolve the sentinel to a default identity in read paths (same idea as “deleted user” for missing users).
+
+See `docs/flows/users/user_removal.md` for the full cross-domain policy.
+
+## Hard delete when a post is removed (design)
+
+When an admin **hard-deletes a post** (`DELETE /admin/posts/{post_id}`), **all comments** with `subject_type = post` and `subject_id = that post` are **removed from the database** (roots and nested replies), together with **`comment_likes`**, **`comment_stats`**, **`comment_stats_dirty`**, **`comment_attachments`**, and **`comment_reports`** for those comments. This is **not** redaction: comment ids under that post cease to exist after a successful hard delete.
+
+User **account removal** does **not** do this; it redacts authored comments in place and keeps ids for thread stability. See `docs/flows/posts/admin_posts.md` (Hard delete post) and `docs/flows/users/user_removal.md`.
+
+## Invariants
+
+- A comment has exactly one author_id
+- A comment has exactly one subject (subject_type + subject_id, both not null)
+- A comment in deleted state is not editable
+- Attachments are immutable once published on an active comment
+- Attachment type must be image or video
+- A user can like a given comment at most once
+- Engagement counters are non-negative
+- Domain stores only IDs for external entities (no cross-domain foreign keys)
+- Comment reads/writes only touch the comment schema
+
+## Feed Visibility Filtering Rules
+
+- Comment domain may keep local lookup mirrors for cross-domain visibility checks:
+  - `user_restrictions_lookup` (restricted authors: muted/banned)
+  - `user_blocks_lookup` (directed block edge: blocker -> blocked)
+- For viewer `A` and comment author `B`, hide the comment when either:
+  - `A` has blocked `B` (exists in `user_blocks_lookup`)
+  - `B` is restricted as muted/banned (exists in `user_restrictions_lookup`)
+- Special rule: if viewer `A` is muted, `A` can still see their own comments.
+- These lookup tables are mirrors for read-time filtering only; source-of-truth remains outside comment domain.
+
+## Lookup Sync Contract
+
+- Source-of-truth for restriction state is the moderation domain.
+- Source-of-truth for user-to-user blocks is the user domain.
+- Comment domain mirrors (`user_restrictions_lookup`, `user_blocks_lookup`) exist only to support read-time filtering.
+- Sync operations should be idempotent and safe to run repeatedly.
+- No-op moderation operations (for example, banning an already banned user or clearing an already active user)
+  should still reconcile comment-domain lookup rows to heal prior cross-domain partial failures.
+
+## Materialized Path (`ltree` + `level`)
+
+To avoid recursive CTEs or multiple round-trips when resolving comment trees, each comment stores:
+
+- **path** (`ltree`): A dot-separated chain of **labels**, where each label is that comment’s **own** `id` (ULID) from the root down to this node.
+  - **Root**: `path` is a single label—the new comment’s `id` (e.g. `01HZXK...` as one `ltree` value).
+  - **Reply**: `path` is `parent.path` with this comment’s `id` appended as the next label (e.g. `01HZROOT...01HZCHILD...` in `ltree` form).
+  - Stored type is PostgreSQL `ltree`; the `ltree` extension lives in the shared **extension** schema (see repo Postgres conventions). App connections must resolve `ltree` types/operators (e.g. via `search_path` including the extension schema).
+- **level** (int): Depth in the tree (0 = root, 1 = first reply, …). Used for max-depth enforcement and API rules (e.g. `can_reply`). May be kept in sync with `nlevel(path) - 1` conceptually.
+
+**Display order**: List and reply endpoints use **`created_at` (or other explicit sort keys)**. Do not use `ORDER BY path` for Reddit-style chronological or scored ordering—`ltree` compares labels as text; ULID labels are not a reliable sibling order.
+
+With **max depth 5**, paths are short (at most five labels, each 26 characters for a ULID), which keeps rows and indexes reasonable.
+
+### Example
+
+Illustrative (real IDs are 26-character ULIDs):
+
+| comment_id | parent_comment_id | path (`ltree`)         | level |
+| ---------- | ----------------- | ---------------------- | ----- |
+| `01HZ…A`   | null              | `01HZ…A`               | 0     |
+| `01HZ…B`   | `01HZ…A`          | `01HZ…A.01HZ…B`        | 1     |
+| `01HZ…C`   | `01HZ…A`          | `01HZ…A.01HZ…C`        | 1     |
+| `01HZ…D`   | `01HZ…B`          | `01HZ…A.01HZ…B.01HZ…D` | 2     |
+
+### Query patterns
+
+- **Subtree (descendants of a node, including the node)**: `WHERE path <@ root.path` (and usually restrict by `subject_type` / `subject_id` for safety).
+- **Ancestor chain**: walk `parent_comment_id` or use `ltree` operators / `subpath` as needed.
+- **Depth limit**: `WHERE level < 5` (application max depth); or `nlevel(path) <= 5` if aligned with the same policy.
+- **Indexing**: GiST on `path` supports `<@`, `@>`, and related `ltree` operators (see PostgreSQL `ltree` docs).
+
+### Insert behavior
+
+1. Generate the new comment `id` (ULID) before insert.
+1. **Root**: set `path` to that single id as `ltree`; set `level` to 0.
+1. **Reply**: read parent’s `path` and `level`; set `path` to `parent.path || new_id`; set `level` to `parent.level + 1`.
+
+No sibling index or `count(*)` is required for `path` construction—each new segment is unique because the new `id` is unique.
+
+### Path format (summary)
+
+- **Chosen format**: ID labels only (`comment_id` per segment).
+- **Not used**: Numeric sibling indices (`1.2.3`) for `path`; those are superseded by this design.
+
+## Nesting Depth Policy
+
+- **Database**: No constraint on reply depth. The schema allows arbitrary nesting via `parent_comment_id`.
+- **Application**: Enforce a maximum depth of 5 levels when creating replies. This limit lives in the application/service layer, not in the database.
+- **Extensibility**: To increase the nesting limit, change the application-layer constant or configuration; no migration required.
+
+## Persistence Model
+
+### Tables
+
+#### comments
+
+- Canonical comment record (id, author_id, content, subject_type, subject_id, parent_comment_id, path, level, status, timestamps)
+- `id`: ULID format (varchar(26)), same as posts
+- `path`: `ltree` materialized path; each label is the comment `id` along the chain from root to this row (see Materialized Path above)
+- `level`: Depth in reply tree (0 = root, 1 = first reply, …)
+- Supports soft deletion and edit tracking (max 5 edits)
+- Indexed for subject-based listing, author timeline, parent lookups, and subtree queries (e.g. GiST on `path` for `ltree` operators)
+
+#### comment_stats
+
+- Denormalized engagement counters per comment
+- Stores comment_id, like_count, reply_count, report_count, timestamps
+- like_count from comment_likes; reply_count from comments (parent_comment_id); report_count from moderation domain comment_reports
+- Aggregated periodically via dirty-table pattern. See `docs/flows/comments/comment_stats_aggregation.md`.
+- One row per comment; created when comment is created
+
+#### comment_stats_dirty
+
+- Tracks which comments need stats aggregation
+- One row per comment_id; INSERT ON CONFLICT DO NOTHING
+- Marked by like, reply, report events (async after commit)
+- Drained by scheduled job every 5 min; worker aggregates and deletes
+
+#### comment_likes
+
+- Tracks user likes on comments as a relationship table
+- Stores comment_id, liker_id, and created_at
+- One row per (comment_id, liker_id) pair to enforce idempotent likes
+
+#### user_restrictions_lookup
+
+- Read-time mirror for restricted users (muted/banned). Source-of-truth: moderation domain.
+- Stores user_id, restriction_type (muted, banned)
+- Used in comment queries to hide comments from restricted authors. Sync operations reconcile from moderation domain; see Lookup Sync Contract above.
+
+#### user_blocks_lookup
+
+- Read-time mirror for user-to-user blocks. Source-of-truth: user domain.
+- Stores blocker_id, blocked_id (directed edge: blocker has blocked blocked)
+- Used in comment queries to hide comments from authors the viewer has blocked. Sync operations reconcile from user domain; see Lookup Sync Contract above.
+
+#### comment_attachments
+
+- Tracks media attached to comments (image/video)
+- Stores comment_id, media_id/storage_key, media_type, order_index, and processing status
+- Supports deterministic ordering for multi-attachment comments
+
+### Enums
+
+#### comment_subject_type
+
+- Subject type for comment attachment (post, user_wall, …)
+- Extensible: add new values as new subject types are introduced
+
+#### comment_status
+
+- Lifecycle state of a comment (active, deleted)
+
+#### comment_media_type
+
+- Attachment media type (image, video)
+
+#### comment_attachment_status
+
+- Attachment processing lifecycle (processing, ready, failed, removed)

core_framework/domains/comment/__init__.py

@@ -0,0 +1,25 @@
+from core_framework.domains.comment.enums import CommentStatus, CommentSubjectType
+from core_framework.domains.comment.exceptions import (
+    BaseCommentException,
+    CommentEditLimitReachedException,
+    CommentNotFoundException,
+    CommentUpdateNotFoundException,
+    MaxReplyDepthException,
+    ParentCommentNotFoundException,
+)
+from core_framework.domains.comment.models import Comment, CommentPreview, CommentStats, CommentWithMetadata
+
+__all__ = [
+    "CommentStatus",
+    "CommentSubjectType",
+    "BaseCommentException",
+    "CommentEditLimitReachedException",
+    "CommentNotFoundException",
+    "CommentUpdateNotFoundException",
+    "MaxReplyDepthException",
+    "ParentCommentNotFoundException",
+    "Comment",
+    "CommentPreview",
+    "CommentStats",
+    "CommentWithMetadata",
+]

core_framework/domains/comment/constants.py

@@ -0,0 +1,3 @@
+from typing import Final
+
+REDACTED_CONTENT_PLACEHOLDER: Final[str] = "<deleted>"

core_framework/domains/comment/dependencies.py

@@ -0,0 +1,29 @@
+from core_framework.core.runtime import CoreRuntime, unconfigured_dependency
+from core_framework.domains.comment.repository import CommentRepository
+from core_framework.domains.comment.service import CommentService
+
+
+def build_comment_repository(runtime: CoreRuntime) -> CommentRepository:
+    return CommentRepository(runtime.write_postgres, runtime.read_postgres, runtime.write_postgres)
+
+
+def build_comment_service(runtime: CoreRuntime) -> CommentService:
+    return CommentService(build_comment_repository(runtime))
+
+
+def configure_comment_dependencies(runtime: CoreRuntime) -> None:
+    global comment_repository, comment_service
+    comment_repository = build_comment_repository(runtime)
+    comment_service = build_comment_service(runtime)
+
+
+comment_repository = unconfigured_dependency("CommentRepository")
+comment_service = unconfigured_dependency("CommentService")
+
+__all__ = [
+    "build_comment_repository",
+    "build_comment_service",
+    "configure_comment_dependencies",
+    "comment_repository",
+    "comment_service",
+]

core_framework/domains/comment/enums.py

@@ -0,0 +1,11 @@
+from enum import StrEnum
+
+
+class CommentSubjectType(StrEnum):
+    POST = "post"
+    USER_WALL = "user_wall"
+
+
+class CommentStatus(StrEnum):
+    ACTIVE = "active"
+    DELETED = "deleted"

core_framework/domains/comment/exceptions.py

@@ -0,0 +1,31 @@
+class BaseCommentException(Exception):
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class ParentCommentNotFoundException(BaseCommentException):
+    def __init__(self) -> None:
+        super().__init__("Parent comment not found or not active")
+
+
+class MaxReplyDepthException(BaseCommentException):
+    def __init__(self) -> None:
+        super().__init__("Maximum reply depth reached")
+
+
+class CommentUpdateNotFoundException(BaseCommentException):
+    def __init__(self) -> None:
+        super().__init__("Unable to process request")
+
+
+class CommentEditLimitReachedException(BaseCommentException):
+    def __init__(self) -> None:
+        super().__init__("Edit limit reached. Maximum edits allowed per comment.")
+
+
+class CommentNotFoundException(BaseCommentException):
+    def __init__(self) -> None:
+        super().__init__("Comment not found")

core_framework/domains/comment/models.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar
+
+from core_framework.domains.comment.enums import CommentStatus, CommentSubjectType
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CommentStats:
+    like_count: int
+    reply_count: int
+    report_count: int
+
+    DEFAULT: ClassVar[CommentStats]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Comment:
+    id: str
+    author_id: str
+    content: str
+    edited_count: int
+    edited_at: datetime | None
+    level: int
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CommentWithMetadata:
+    id: str
+    author_id: str
+    content: str
+    subject_type: CommentSubjectType
+    subject_id: str
+    parent_comment_id: str | None
+    status: CommentStatus
+    edited_count: int
+    edited_at: datetime | None
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CommentPreview:
+    id: str
+    author_id: str
+    content: str
+    status: CommentStatus
+
+
+CommentStats.DEFAULT = CommentStats(
+    like_count=0,
+    reply_count=0,
+    report_count=0,
+)