Comments: User and state model

Comments attach to a document revision, support hide versus delete, allow mentions only of users the commenter can see, bound the edit window, and record moderation actions in an audit trail.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Comments are threaded conversations anchored to a specific document revision and an optional text or block range. Authors may edit within a bounded window; after that, the body is frozen except for moderation. Hide conceals a comment from ordinary readers while retaining it for moderators; delete is a separate privileged path that still leaves an audit record. Mentions resolve only to users the commenter is allowed to see in that workspace. Moderation actions are append-only.

Scope

• Thread create, reply, edit window, hide, delete, mention ACL, revision anchors, and moderation audit on web and backend.
• Document collaboration surfaces that already have membership and visibility rules.
• Notification triggers for mentions of visible users.

Outside this block

• Real-time presence cursors and conflict-free text editing.
• Organization membership join, leave, and transfer, except as the source of mention visibility.

Contract

• A comment stores document_id, revision_id, optional anchor, thread_id, and parent_id for replies.
• Edit is allowed only for the author before edit_window_minutes elapse and only if the comment is not hidden by moderation.
• hide sets visibility: hidden without removing bytes; ordinary readers omit it; moderators with comments.moderate still load it.
• Mentions that name a user outside the commenter's visible membership set are rejected and never notify.
• Moderation events append actor, action, reason_code, and timestamp; they do not rewrite history.
• Replies remain attached to the thread even when the parent is hidden; the parent placeholder is visible to readers as hidden, not as another user's private text.

Implementation

• Resolve anchors against the revision snapshot; if the range vanished, keep an orphaned-on-revision flag instead of dropping the comment.
• Enforce mention ACL with the same visibility graph as directory search, not a global user table.

Failure handling

• If the revision is gone, new comments fail with revision_not_found; existing threads stay readable as history.
• If hide and edit race, hide wins and the edit is rejected.

Verification

• Mention a user from another private workspace and expect rejection.
• Hide a parent and assert replies do not leak the hidden body to a regular reader.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision for collaborative comments.