CapaKraken/docs/comment-visibility-architecture.md

Comment Visibility Architecture

Date: 2026-03-30 Status: Phase 1 implemented

Problem

The original comment router accepted arbitrary entityType and entityId pairs behind protectedProcedure. That was too broad:

• comment visibility depends on the backing entity, not on the comment record alone
• generic strings allowed clients and assistant tools to imply support for entity types that had no explicit policy
• author/admin checks on resolve and delete were not enough, because list/create access was still effectively "any authenticated user"

Current Product Reality

There is only one real first-party consumer today:

• web UI estimate workspace comments via entityType: "estimate"

The older examples for scope_item, estimate_version, and demand_line were aspirational, not backed by an explicit visibility model or active UI.

Architecture Decision

Comments now use an explicit entity registry.

• supported entity types are allowlisted, not free-form
• each entity type owns:
  • its audience rule
  • its existence check
  • its deep link builder for notifications
• every comment route calls the entity access layer before touching comment data

Phase 1 Policy

Supported entity types:

• estimate

Audience:

• same audience as the estimate workspace
• controller, manager, or admin only

Route effects:

• list, count, create, resolve, and delete all require estimate visibility first
• resolve and delete still require comment author or admin after entity visibility is granted
• replies are only allowed when the parent comment belongs to the same entity tuple
• mention notifications use the entity policy link builder instead of hardcoded route assumptions scattered through the router

Why This Shape

• It closes the real security gap now without pretending a generic multi-entity policy already exists.
• It keeps future comment expansion additive: a new entity type must be onboarded deliberately.
• It gives the assistant and UI one source of truth for what is actually supported today.

Extension Rules For Future Entity Types

To add another commentable entity:

1. Add the entity type to the registry, not just to input examples.
2. Define the backing audience source of truth.
3. Add an existence check for that entity.
4. Add a notification link builder for that entity.
5. Update assistant tool metadata and assistant visibility gates in the same change.
6. Add router auth tests for unauthenticated, plain authenticated, and elevated callers.
7. Update docs/route-access-matrix.md.

Non-Goals In Phase 1

• generic comment support for arbitrary entities
• row-level polymorphic authorization based only on entityType strings
• automatic inheritance for future entities without explicit onboarding