[jacksonsr451]

Summary

Closes #29

Implements entity-scoped comments, secure attachments, and immutable audit history for EventFlow's Work Management bounded context.

This PR extends the existing collaboration and evidence infrastructure while preserving workspace isolation, RBAC, approval invariants, and append-only audit guarantees.

The implementation supports comments on Consultations, Proposals, WorkItems, and BoardCards, alongside authorized attachments for Proposals, WorkItems, and BoardCards.

Existing Consultation attachment and evidence infrastructure remains unchanged.

Changes

1. Entity Comments

Implemented persistent comments for:

• Consultations
• Proposals
• WorkItems
• BoardCards

Capabilities include:

• Authenticated comment creation.
• Entity-scoped comment retrieval.
• Cursor-based pagination.
• Server-derived author identity.
• Workspace and project isolation.
• Role-based access control.
• Idempotent comment creation.
• Tombstone-only deletion.
• Immutable comment bodies.

Comment editing is intentionally unsupported.

PostgreSQL triggers prevent unauthorized modification, hard deletion, and truncation of historical comment records.

2. Secure Entity Attachments

Introduced generic attachment support for:

• Proposals
• WorkItems
• BoardCards

The implementation reuses the existing attachment security model rather than introducing an independent upload pipeline.

Security guarantees include:

• Authorized uploads and downloads.
• Workspace and project ownership validation.
• File metadata validation.
• Fail-closed malware scanning.
• Explicit attachment availability states.
• Restricted deletion permissions.
• Protection against cross-tenant access.

Attachment scan outcomes:

Scan result	Attachment state	Download
Clean	Available	Allowed when authorized
Unknown / scanner unavailable	Quarantined	Blocked
Infected	Rejected	Blocked

Rejected attachments do not retain stored file blobs.

Quarantined and rejected attachments cannot expose content bytes.

Existing Consultation attachment and evidence tables remain untouched.

3. Append-Only Audit History

Implemented read-only entity history projections using the existing Work Management audit infrastructure.

Supported collaboration events include:

• comment.created
• comment.deleted
• attachment.uploaded
• attachment.rejected
• attachment.deleted

Historical records remain append-only.

Database-level protections prevent unauthorized mutation of audit history.

The implementation preserves the existing approval and transition audit infrastructure rather than duplicating it.

4. Authorization and Tenant Isolation

Added the following RBAC actions:

• comment:read
• comment:create
• comment:delete

Authorization behavior:

• Workspace members can read accessible comments.
• Contributors and higher-privileged roles can create comments.
• Comment deletion is restricted to the author or owner/admin.
• Attachment deletion is restricted to the uploader or owner/admin.
• Unauthorized mutations are rejected.
• Foreign-workspace resources are concealed using HTTP 404.

Comment authorship is always derived from the authenticated principal.

Client-supplied author identities are never trusted.

5. API and Contract Updates

Implemented 10 API operations under entity-scoped workspace routes.

Operations cover:

• Comment creation.
• Comment listing.
• Comment retrieval.
• Comment deletion.
• Attachment upload.
• Attachment listing.
• Attachment metadata retrieval.
• Attachment download.
• Attachment deletion.
• Entity history retrieval.

Supported route structure:

/v1/workspaces/{workspace_id}/{entity_collection}/{entity_id}/...

BoardCard resources use the established flat card path.

The collaboration router is registered after the existing Consultation routes to preserve route precedence and compatibility.

Updated contract definitions include:

• EntityCollection
• AttachmentEntityCollection
• EntityType
• EntityComment
• EntityAttachment
• Entity history pagination.
• Comment operations.
• Attachment operations.
• History retrieval.

Idempotency is supported for comment creation and attachment uploads.

Repeated requests with matching fingerprints return the original resource.

Reusing an idempotency key with a different request fingerprint returns:

409 IDEMPOTENCY_CONFLICT

6. Database Migration

Added migration:

0009_entity_collaboration

Parent revision:

0008_kanban_boards_columns

New tables:

• entity_comments
• entity_attachments
• entity_attachment_blobs

Database protections include:

• Comment rewrite guards.
• Comment hard-delete guards.
• Comment truncate guards.
• Workspace/project consistency constraints.
• Composite project foreign keys.
• Entity type validation.
• Attachment status validation.
• Scan verdict validation.
• Checksum and storage-key constraints.

Existing Consultation attachment tables were preserved.

Migration integration tests validate the schema, triggers, database functions, and migration revision head.

Testing

All reported local validation checks passed.

Test suite	Passed	Failed	Skipped
Work Management	184	0	1
Root contracts and security	114	0	0
Total	298	0	1

Additional verification:

• Collaboration integration tests: 6 passed.
• Contract validation: passed.
• Pre-commit checks: passed.
• Database migration validation: passed.
• No failing tests.

The collaboration suite covers:

• Comments across all four supported entity types.
• Verified author attribution.
• Tombstone deletion.
• Database-level comment immutability.
• RBAC enforcement.
• Workspace isolation.
• Authorized attachment operations.
• Malware scanning outcomes.
• Quarantined and rejected download restrictions.
• Idempotency conflicts.
• Audit history retrieval.

Validation Checklist

• Entity comments implemented.
• Comment authorship derived from authenticated principals.
• Comment bodies protected against modification.
• Tombstone-only comment deletion.
• Authorized entity attachments implemented.
• Existing Consultation attachment infrastructure preserved.
• Malware scanning remains fail-closed.
• Quarantined attachments cannot be downloaded.
• Rejected attachments do not retain blobs.
• Workspace and project isolation enforced.
• RBAC and ownership restrictions enforced.
• Append-only audit history preserved.
• Database-level immutability enforced.
• Idempotent mutations implemented.
• Cursor pagination implemented.
• OpenAPI and schema contracts updated.
• Documentation updated.
• PostgreSQL integration tests passed.
• Contract validation passed.
• Pre-commit checks passed.
• Remote CI verification pending.
• Pull Request review pending.

Architectural Decisions

No Direct WorkItem or BoardCard Creation

This PR does not introduce direct WorkItem or BoardCard creation.

The existing architecture requires authorized Proposal approval before executable work is created.

Direct creation remains blocked pending an approved architectural amendment.

Immutable Comments

Comments cannot be edited.

Deletion creates a tombstone rather than removing the historical record.

This preserves accountability and prevents retrospective modification of collaboration history.

Reuse of Existing Audit Infrastructure

Entity history is a read-only projection of existing append-only audit records.

No competing audit subsystem was introduced.

Known Limitations and Risks

Polymorphic Entity References

entity_id is polymorphic and does not have a direct foreign key to every supported entity table.

Referential correctness depends on entity resolution and the existing workspace/project constraints.

Review should verify that all write paths enforce these checks consistently.

Workspace and Project Deletion

Database triggers protecting immutable comments may block cascading deletion of workspaces or projects containing historical collaboration records.

A future archival or retention workflow must account for these constraints.

No unrestricted destructive deletion behavior is introduced by this PR.

Row-Level Security

PostgreSQL Row-Level Security remains deferred.

Tenant isolation currently relies on application authorization and query scoping, supported by integration tests.

Idempotency Implementation

Idempotency uses the existing application and database-row mechanism.

Concurrency behavior, crash recovery, and replay guarantees should remain review considerations.

Review Focus

Please pay particular attention to:

1. Entity resolution and polymorphic reference integrity.
2. Workspace/project isolation.
3. RBAC and ownership checks.
4. Comment immutability triggers.
5. Tombstone deletion semantics.
6. Attachment scanning and quarantine enforcement.
7. Blob persistence and rejected-upload behavior.
8. Audit history consistency.
9. Idempotency under concurrent requests.
10. Migration compatibility and future archival requirements.

Git Information

Branch: feat/29-entity-comments-attachments-audit

Base commit: 557c6e0

Commits:

• 1c2beea — feat(work-management): add entity comments attachments and audit trails ([FEAT] Implementar comentários, anexos e trilha auditável #29)
• 31dc697 — test(work-management): cover proposal comments in collaboration suite ([FEAT] Implementar comentários, anexos e trilha auditável #29)

Working tree: Clean.

Local verification: 298 passed, 0 failed, 1 skipped.

Final Status

READY FOR PR

Issue #29 has been implemented and verified locally.

The implementation preserves the existing Work Management architecture, extends collaboration capabilities, and provides database-enforced immutable history.

Remote CI execution and Pull Request review remain pending.