PSA/ee/docs/plans/2026-02-11-contact-commentors-inbound-email/SCRATCHPAD.md

Scratchpad — Ticket Contact Commentors + Inbound Email Contact Authorship

• Plan slug: contact-commentors-inbound-email
• Created: 2026-02-11

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also update earlier notes when a decision changes or an open question is resolved.

Decisions

• (2026-02-11) Draft approach: represent contact-only comment authorship by adding comments.contact_id (tenant-scoped FK to contacts.contact_name_id) rather than creating a new author enum state.
• (2026-02-11) Preserve current semantic meaning of customer-authored comments as author_type=client for response-state transitions; contact_id carries identity when user_id is absent.
• (2026-02-11) Keep scope focused on core behavior (data model + comment creation + rendering + inbound email wiring + tests), no operational/observability extras unless requested.
• (2026-02-11) No mandatory historical backfill in phase 1; additive behavior for new/updated comments first.
• (2026-02-11) Canonical authorship contract is now explicit in shared types via CommentAuthorship (author_type + nullable user_id + nullable contact_id), and IComment mirrors this nullable dual-link model.
• (2026-02-11) Shared comment typing extension is implemented in packages/types/src/interfaces/comment.interface.ts; downstream loaders/components can now consume comment.contact_id without ad-hoc casting.

Discoveries / Constraints

• (2026-02-11) comments previously had contact columns, but they were removed in server/migrations/20250217202553_drop_contact_columns.cjs.
• (2026-02-11) TicketModel.createComment currently maps author_type=contact to DB author_type=client and only persists user_id; no contact identity is stored today (shared/models/ticketModel.ts).
• (2026-02-11) Inbound new-ticket flow already resolves contact and optional client user (findContactByEmail) and sets author_id only when user exists; reply paths do not currently resolve contact (shared/services/email/processInboundEmailInApp.ts).
• (2026-02-11) MSP and client-portal ticket details render comments from comments + userMap sourced from users; comments with no user_id render as Unknown User (packages/tickets/src/components/ticket/CommentItem.tsx, packages/tickets/src/actions/optimizedTicketActions.ts, packages/client-portal/src/actions/client-portal-actions/client-tickets.ts).
• (2026-02-11) Ticket comment API schema currently expects created_by as UUID in responses, which is brittle for contact-only authors if user_id is null (server/src/lib/api/schemas/ticket.ts).
• (2026-02-11) packages/types had IComment.user_id?: string and no contact author linkage field; adding nullable user_id + contact_id in the base interface is required before loader/UI/API updates.
• (2026-02-11) Added migration scaffold server/migrations/20260211190000_add_comments_contact_id.cjs to reintroduce nullable comments.contact_id; FK/index are intentionally separated into the next step for checklist traceability.
• (2026-02-11) Migration 20260211190000_add_comments_contact_id.cjs now includes comments_tenant_contact_id_fk (tenant, contact_id -> contacts.tenant, contact_name_id) and comments_tenant_contact_id_idx for bounded comment-author lookups.
• (2026-02-11) shared/models/ticketModel.ts comment creation schema and input types now accept optional contact_id with UUID validation.
• (2026-02-11) TicketModel.createComment now performs tenant-scoped contact validation (contacts.contact_name_id + tenant) and fails fast when contact_id is missing/out-of-tenant.
• (2026-02-11) TicketModel.createComment insert payload now writes comments.contact_id directly, enabling contact-only comments and dual-link comments (user_id + contact_id).
• (2026-02-11) Shared comment creation now updates tickets.response_state to awaiting_internal for non-internal author_type=contact comments; internal comments remain unchanged.
• (2026-02-11) createCommentFromEmail contract in shared/workflow/actions/emailWorkflowActions.ts now accepts optional contact_id to support contact-only comment authorship from inbound paths.
• (2026-02-11) createCommentFromEmail now forwards contact_id into TicketModel.createComment, so inbound email comments can persist contact authorship linkage.
• (2026-02-11) New-ticket inbound path now passes contact_id into createCommentFromEmail whenever sender contact is matched, regardless of whether a client user was resolved.
• (2026-02-11) Reply-token inbound path now resolves sender contact once per email and forwards both contact_id and resolved author_id (when present) to comment creation.
• (2026-02-11) Thread-header inbound reply path reuses the same sender-contact resolution and now forwards contact_id/author_id to comment creation.
• (2026-02-11) End-to-end inbound paths now support dual linkage (author_id + contact_id) when a matched contact has an associated client user, preserving user identity while keeping explicit contact authorship.
• (2026-02-11) Workflow action schemas now expose contact_id in create_comment_from_email (V2 runtime + legacy action registry), so workflow definitions can pass contact authorship explicitly.
• (2026-02-11) Workflow runtime implementations now pass contact_id through to shared comment creation (create_comment_from_email, create_ticket_with_initial_comment, and parsed-reply comment path with sender contact resolution fallback).
• (2026-02-11) MSP consolidated ticket loader now builds a contactMap keyed by contact_name_id for all comments.contact_id values, giving conversation rendering a first-class contact author source alongside userMap.
• (2026-02-11) Client-portal ticket details loader now also returns contactMap from comments.contact_id, keeping author resolution parity between MSP and portal views.
• (2026-02-11) Added packages/tickets/src/lib/commentAuthorResolution.ts as the shared author resolver with deterministic precedence: user author, then contact author, then unknown fallback.
• (2026-02-11) CommentItem now resolves authors via shared helper + contactMap, rendering contact-authored comments with contact name/email/avatar (without requiring user_id).
• (2026-02-11) Unknown-user fallback is now explicitly constrained to comments where neither userMap[comment.user_id] nor contactMap[comment.contact_id] resolves, via resolveCommentAuthor precedence.
• (2026-02-11) API comment payloads now support contact-authored rows by making created_by nullable and adding contact author fields (author_contact_id/name/email) from TicketService.getTicketComments + ticketCommentResponseSchema.
• (2026-02-11) ticketEmailSubscriber now resolves comment author identity from persisted comments row (user_id/contact_id + emails) and excludes author recipients by both user-id and email/contact in comment fan-out paths.
• (2026-02-11) Added focused unit coverage for processInboundEmailInApp covering contact-only authorship in new-ticket, reply-token, and thread-header paths (shared/services/email/__tests__/processInboundEmailInApp.test.ts).

Commands / Runbooks

• (2026-02-11) Locate existing comments/inbound-email/authorship behavior:
  • rg -n "author_type|author_id|Unknown User|processInboundEmailInApp|createCommentFromEmail" shared server packages -g"*.ts" -g"*.tsx"
• (2026-02-11) Review current ticket conversation rendering path:
  • sed -n '1,360p' packages/tickets/src/components/ticket/CommentItem.tsx
  • sed -n '180,320p' packages/tickets/src/actions/optimizedTicketActions.ts
• (2026-02-11) Review inbound email creation/reply logic:
  • sed -n '1,760p' shared/services/email/processInboundEmailInApp.ts
  • sed -n '680,820p' shared/workflow/actions/emailWorkflowActions.ts
• (2026-02-11) Review legacy migration history for comments/contact linkage:
  • rg -n "comments|contact_id|contact_name_id|author_type" server/migrations -g"*.cjs"
• (2026-02-11) Validate canonical type updates:
  • npx vitest run packages/types/src/interfaces/comment.interface.typecheck.test.ts
• (2026-02-11) Verify inbound email comment wiring after runtime action changes:
  • npx vitest run shared/workflow/actions/__tests__/emailWorkflowActions.responseSource.test.ts shared/services/email/__tests__/processInboundEmailInApp.test.ts

Links / References

• Plan folder: ee/docs/plans/2026-02-11-contact-commentors-inbound-email
• Existing related plan: ee/docs/plans/2026-01-24-inbound-email-in-app-processing
• Existing related plan: ee/docs/plans/2026-02-05-ticket-response-source
• Core files:
  • shared/services/email/processInboundEmailInApp.ts
  • shared/workflow/actions/emailWorkflowActions.ts
  • shared/models/ticketModel.ts
  • packages/tickets/src/actions/optimizedTicketActions.ts
  • packages/tickets/src/components/ticket/TicketConversation.tsx
  • packages/tickets/src/components/ticket/CommentItem.tsx
  • packages/client-portal/src/actions/client-portal-actions/client-tickets.ts
  • server/src/lib/api/services/TicketService.ts
  • server/src/lib/api/schemas/ticket.ts
  • server/migrations/20250217202553_drop_contact_columns.cjs

Open Questions

• Should contact-authored comments display Name (Contact) or only Name with contact avatar semantics?
• Should we always persist contact_id alongside user_id for client users when available, or only for contact-only authors?
• For reply flows with unresolved sender contact but resolved ticket, should we fallback to ticket contact or keep unknown?
• Do we want API responses to expose additive flat fields or a nested author object for future-proofing?
• Should client portal display for contact-authored comments differ from MSP display in any way?
• (2026-02-11) Added cross-layer verification for contact-authored comment support: integration assertions in inbound webhook tests, UI-level author resolution tests, and API schema tests for nullable created_by + contact author fields.
• (2026-02-11) T001 complete: added migration contract test asserting comments.contact_id is created as nullable UUID (server/src/test/unit/migrations/commentsContactAuthorshipMigration.test.ts).
• (2026-02-11) T002 complete: migration contract test now verifies tenant-scoped FK/index wiring for comments.contact_id -> contacts.contact_name_id.
• (2026-02-11) T003 complete: migration contract test now asserts down-path cleanup removes FK, index, and contact_id column.
• (2026-02-11) T004 complete: added TicketModel.createComment unit suite covering contact author input acceptance with contact_id and no author_id.
• (2026-02-11) T005 complete: TicketModel.createComment test now asserts invalid contact_id format is rejected by input validation. EOF && git add ee/docs/plans/2026-02-11-contact-commentors-inbound-email/tests.json ee/docs/plans/2026-02-11-contact-commentors-inbound-email/SCRATCHPAD.md && git commit -m "test(T005): reject malformed contact_id in createComment"- (2026-02-11) T006 complete: TicketModel.createComment tests cover tenant-safety by rejecting missing/cross-tenant contact_id lookups.
• (2026-02-11) T007 complete: TicketModel.createComment persistence test asserts inserted comments row contains contact_id for contact-authored comments. EOF && git add ee/docs/plans/2026-02-11-contact-commentors-inbound-email/tests.json ee/docs/plans/2026-02-11-contact-commentors-inbound-email/SCRATCHPAD.md && git commit -m "test(T007): verify contact_id persistence on comment insert"- (2026-02-11) T008 complete: TicketModel.createComment tests now verify dual-link persistence when both author_id and contact_id are supplied.
• (2026-02-11) T009 complete: unit tests assert public contact-authored comments set ticket response_state to awaiting_internal.
• (2026-02-11) T010 complete: unit tests confirm internal contact-authored comments do not change ticket response_state.
• (2026-02-11) T011 complete: createCommentFromEmail unit coverage now verifies contact_id is forwarded into TicketModel.createComment.
• (2026-02-11) T012 complete: unit tests now assert dual forwarding of author_id and contact_id from createCommentFromEmail.
• (2026-02-11) T013 complete: unit tests cover new-ticket inbound flow with matched contact/no user and assert contact_id is set while author_id is omitted.
• (2026-02-11) T014 complete: unit tests assert new-ticket inbound flow with matched contact+user forwards both contact_id and author_id.
• (2026-02-11) T015 complete: added dedicated unit coverage for unmatched new-ticket sender fallback (no contact_id, system author path preserved).
• (2026-02-11) T016 complete: unit tests cover reply-token threading with contact-only sender and assert contact_id propagation.
• (2026-02-11) T017 complete: additional unit coverage verifies reply-token path forwards both author_id and contact_id for contact+user matches.
• (2026-02-11) T018 complete: unit tests validate thread-header reply path sets contact_id for contact-only senders.
• (2026-02-11) T019 complete: added unit assertion that thread-header reply path without matched sender contact preserves fallback (contact_id omitted).
• (2026-02-11) T020 complete: runtime action registration tests now validate create_comment_from_email input schema accepts contact_id.
• (2026-02-11) T021 complete: runtime registration tests assert the initial ticket+comment action forwards targetContactId into createCommentFromEmail.
• (2026-02-11) T022 complete: runtime registration tests assert create_comment_from_email handler forwards contact_id into the shared email action call.
• (2026-02-11) T023 complete: added MSP consolidated data contract tests confirming comment-loading path carries contact_id support in returned conversation payloads.
• (2026-02-11) T024 complete: MSP contract tests now assert contact author resolution map (contactMap) is built from comment contacts.
• (2026-02-11) T025 complete: added client-portal ticket details contract test ensuring contact author resolution data is assembled in client-tickets.
• (2026-02-11) T026 complete: resolveCommentAuthor unit tests verify precedence order user → contact → unknown.
• (2026-02-11) T027 complete: added CommentItem contract tests confirming contact-authored comments resolve/render contact display name instead of unknown fallback.
• (2026-02-11) T028 complete: CommentItem contract tests verify contact email rendering path (mailto: link) when author email is available.
• (2026-02-11) T029 complete: CommentItem contract tests verify ContactAvatar branch is used for contact-authored comments.
• (2026-02-11) T030 complete: CommentItem contract tests preserve Unknown User fallback branch for unresolved user/contact authors.
• (2026-02-11) T031 complete: CommentItem contract tests confirm edit/delete permission gate remains tied to conversation.user_id ownership.
• (2026-02-11) T032 complete: added TicketService contract tests asserting getTicketComments exposes contact author fields and nullable created_by mapping.
• (2026-02-11) T033 complete: API schema unit tests validate contact-authored ticket comment payloads without requiring created_by UUID.
• (2026-02-11) T034 complete: response-shape test now covers schema-validated contact-authored comment payload acceptance for ticket comments API outputs.
• (2026-02-11) T035 complete: added ticket-email-subscriber contract tests asserting contact-author exclusion gates in recipient fan-out logic.
• (2026-02-12) T036 complete: existing inbound integration test Contact match: sender email matches existing contact and ticket uses contact's client_id/contact_id already asserts Google contact-only authorship (author_type=client, contact_id set, user_id null).
• (2026-02-12) Integration test execution in this worktree currently cannot establish DB auth (password authentication failed for user "postgres"), so webhook integration cases are validated by test code inspection + committed assertions but cannot be executed locally end-to-end.
• (2026-02-12) T037 complete: added Microsoft-provider integration case in inboundEmailInApp.webhooks.integration.test.ts asserting matched contact-without-user creates new ticket comment with author_type=client, contact_id set, and user_id null.
• (2026-02-12) T038 complete: added reply-token integration case for matched contact-without-user (provider: microsoft) asserting persisted reply comment is contact-authored (author_type=client, contact_id set, user_id null).
• (2026-02-12) T039 complete: strengthened matched client-user inbound integration assertion to require both preserved user linkage (user_id) and contact linkage (contact_id) on the created comment.
• (2026-02-12) T040 complete: unmatched-sender integration assertions now verify comment identity links remain unresolved (contact_id null, user_id null) with system/internal authoring, preserving unknown-user fallback behavior.