# SCRATCHPAD — Workflow Event Catalog v2 Domain Events

Rolling notes for this plan: discoveries, decisions, links, commands, and gotchas.

## Source Material

- Event proposals inventory: `ee/docs/plans/2025-12-28-workflow-event-catalog/event-proposals.md`
- Existing Events Catalog v2 plan: `ee/docs/plans/2025-12-28-workflow-event-catalog/PRD.md`
- This plan: `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/PRD.md`
- Features/tests: `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/features.json` and `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/tests.json`

## Key Discovery: Event Bus Already Has a Large Event Surface

`shared/workflow/streams/eventBusSchema.ts` already defines many event types beyond what exists in `system_event_catalog` migrations, including:

- Ticket comment events (`TICKET_COMMENT_ADDED`, `TICKET_COMMENT_UPDATED`)
- Scheduling events (`SCHEDULE_ENTRY_CREATED`, `SCHEDULE_ENTRY_UPDATED`, `SCHEDULE_ENTRY_DELETED`)
- Accounting export and calendar sync events
- Document mention event (`USER_MENTIONED_IN_DOCUMENT`)
- RMM events (`RMM_*`)

Implication: adding events is not only “add catalog rows”; we must keep **catalog**, **event bus schema/types**, and **workflow schema registry refs** aligned.

## Key Discovery: Schema Registry (Workflow Runtime v2) Is Separate From Event Bus Zod Schemas

Workflow runtime v2 registers payload schemas in `shared/workflow/runtime/init.ts` (schema registry keys like `payload.TicketCreated.v1`).

Event bus has its own Zod payload schemas in `shared/workflow/streams/eventBusSchema.ts`.

Implication: for each new catalog entry we want form-mode simulation and trigger mapping, we likely need:

- `payload_schema_ref` → schema registry registration (`payload.*.v1`)
- and (if the event is published through the event bus) inclusion in `EventTypeEnum` + `EventPayloadSchemas` mapping.

## Current Event Publishing Path (observed)

- Workflow v2 simulation / submission path uses: `packages/workflows/src/actions/workflow-event-actions.ts` (`submitWorkflowEventAction`) which publishes to the event bus and validates `event_type` exists in catalog tables.
- There are multiple non-workflow publishers already in the repo (examples found via ripgrep):
  - `packages/billing/src/services/accountingExportService.ts`
  - `packages/integrations/src/services/calendar/CalendarSyncService.ts`
  - `server/src/services/email/EmailProcessor.ts` (publishes `INBOUND_EMAIL_RECEIVED`)

Implication: we should standardize on `@alga-psa/event-bus/publishers` helpers for new emissions, and ensure payload shapes match both schemas.

## Decisions Needed (Blocking)

1. **Ticket messages vs ticket comments**
   - Keep existing `TICKET_COMMENT_*` as canonical, and map proposed `TICKET_MESSAGE_*` onto those semantics?
   - Or introduce `TICKET_MESSAGE_*` and deprecate `TICKET_COMMENT_*`?
   - **Decision (2026-01-23):** Introduce `TICKET_MESSAGE_*` as canonical workflow v2 domain events; keep `TICKET_COMMENT_*` as legacy/back-compat (no automatic aliasing due to payload shape differences).
2. **Scheduling appointments vs schedule entries**
   - Reuse existing `SCHEDULE_ENTRY_*` as canonical?
   - Or introduce `APPOINTMENT_*` (and decide whether a schedule entry is an appointment)?
   - **Decision (2026-01-23):** Introduce `APPOINTMENT_*` as canonical workflow triggers; keep `SCHEDULE_ENTRY_*` for lower-level schedule entry changes and existing integrations.
3. **Client/company identifiers**
   - Standardize payloads on `clientId`, `companyId`, or include both?
4. **Payload casing**
   - **Decision (2026-01-23):** use camelCase payload keys for all new `payload.*.v1` schemas and event bus payloads (documented in `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/PRD.md` §6.2).
5. **Catalog-only events**
   - Which of SLA/approvals/dispatch/signatures are expected to be emitted now vs later?

## Work Log

- 2026-01-23: Completed `F001` (payload conventions) by expanding `PRD.md` §6.2 with:
  - camelCase key requirement
  - required `tenantId` + `occurredAt`
  - actor field guidance (`actorUserId` / `actorContactId` / optional `actorType`)
  - transition and mutation conventions (`previousX`/`newX`, `updatedFields`, `changes`)
- 2026-01-23: Completed `F002` (shared publishing helpers + hooks):
  - Added payload enrichment helper `shared/workflow/streams/workflowEventPublishHelpers.ts`:
    - ensures `tenantId` and `occurredAt`
    - enriches actor fields (`actorType`, `actorUserId`, `actorContactId`)
    - carries optional `idempotencyKey`
  - Added publish-time hooks for workflow stream conversion:
    - `shared/workflow/streams/eventBusSchema.ts` now supports `WorkflowPublishHooks` and `convertToWorkflowEvent(event, hooks)`
    - workflow `user_id` now prefers `payload.actorUserId` (falls back to `payload.userId`)
  - Wired hooks through both event bus implementations:
    - `packages/event-bus/src/eventBus.ts` and `server/src/lib/eventBus/index.ts` accept `{ workflow }` publish options
  - Added convenience publisher wrappers:
    - `packages/event-bus/src/publishers/index.ts` and `server/src/lib/eventBus/publishers/index.ts` export `publishWorkflowEvent(...)`
- 2026-01-23: Completed `F003` (schema registry payload schemas + registrations):
  - Added shared payload building blocks in `shared/workflow/runtime/schemas/commonEventPayloadSchemas.ts`:
    - `tenantId` + `occurredAt` required on all new payload schemas
    - optional actor fields (`actorUserId`, `actorContactId`, `actorType`)
    - shared `updatedFields[]` and `changes{path:{previous,new}}` helpers
  - Added `payload.*.v1` Zod payload schemas for every event in `event-proposals.md`:
    - tickets: `shared/workflow/runtime/schemas/ticketEventSchemas.ts`
    - scheduling: `shared/workflow/runtime/schemas/schedulingEventSchemas.ts`
    - projects: `shared/workflow/runtime/schemas/projectEventSchemas.ts`
    - billing: `shared/workflow/runtime/schemas/billingEventSchemas.ts`
    - CRM/tags: `shared/workflow/runtime/schemas/crmEventSchemas.ts`
    - documents: `shared/workflow/runtime/schemas/documentEventSchemas.ts`
    - email/notifications/surveys: `shared/workflow/runtime/schemas/communicationsEventSchemas.ts`
    - integrations: `shared/workflow/runtime/schemas/integrationEventSchemas.ts`
    - assets/media: `shared/workflow/runtime/schemas/assetMediaEventSchemas.ts`
    - company: `shared/workflow/runtime/schemas/companyEventSchemas.ts`
  - Centralized schema registrations in `shared/workflow/runtime/schemas/workflowEventPayloadSchemas.ts` and updated `shared/workflow/runtime/init.ts` to register the full map at init.
  - Verified registry coverage: all `payload.<PascalCase>.v1` refs implied by `event-proposals.md` are present in `workflowEventPayloadSchemas`.
- 2026-01-23: Completed `F004` (event bus schema/types + overlap resolution):
  - Expanded `shared/workflow/streams/eventBusSchema.ts`:
    - added all proposed domain `EventTypeEnum` values from `event-proposals.md`
    - mapped new domain event types to workflow runtime payload schemas (camelCase + `occurredAt`)
    - kept legacy event payloads working via Zod unions for overlapping “already present” events
    - added a runtime guard to ensure every `EVENT_TYPES` entry has a payload schema
  - Removed duplicate schema/type definitions by re-exporting shared schema from:
    - `packages/event-bus/src/events.ts`
    - `server/src/lib/eventBus/events.ts`
  - Aligned catalog typing with the shared event bus enum:
    - `shared/workflow/types/eventCatalog.ts`
  - Added focused test coverage:
    - `shared/workflow/streams/__tests__/eventBusSchema.expandedEvents.test.ts`
  - Documented overlap decisions in `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/PRD.md` §10.
- 2026-01-23: Completed `F005` (catalog migration upsert for expanded domain events):
  - Added idempotent system catalog upsert migration: `server/migrations/20260123150000_upsert_domain_workflow_event_catalog_v2.cjs`
    - Upserts **134** total events into `system_event_catalog`:
      - **122** proposed events parsed from `ee/docs/plans/2025-12-28-workflow-event-catalog/event-proposals.md`
      - **12** “already present” core events (Company/Ticket/Project/Invoice/Email provider)
    - Normalizes `name`, `description`, `category`, and `payload_schema_ref` for each row.
    - Sets `payload_schema_ref` as `payload.<PascalCase(event_type)>.v1` (e.g. `INBOUND_EMAIL_RECEIVED` → `payload.InboundEmailReceived.v1`).
    - Intentionally does **not** manage legacy `payload_schema` JSON in catalog rows (workflow v2 uses schema registry via `payload_schema_ref`).
- 2026-01-23: Completed `F006` (simulation uses `payload_schema_ref` + schema validation):
  - Server-side event ingestion now enriches simulator payloads and validates them against the schema registry:
    - `server/src/lib/actions/workflow-runtime-v2-actions.ts` now:
      - derives `sourcePayloadSchemaRef` from submission override or catalog `payload_schema_ref`
      - enriches payload via `buildWorkflowPayload(...)` (adds `tenantId`, `occurredAt`, `actorUserId`, `actorType`)
      - rejects invalid payloads with `400` including Zod `issues`, and records an error `workflow_runtime_event`
  - Added schema registry coverage tests (no DB required):
    - `shared/workflow/runtime/__tests__/workflowEventSimulatorSchemas.test.ts`
  - Attempted DB-backed integration test run, but this sandbox cannot connect to localhost Postgres (EPERM); kept verification to schema-level tests.

- 2026-01-23: Completed `F010` (ticket transition emission):
  - Emitted workflow v2 domain events from real ticket update paths:
    - `packages/tickets/src/actions/ticketActions.ts` now publishes: `TICKET_STATUS_CHANGED`, `TICKET_PRIORITY_CHANGED`, `TICKET_UNASSIGNED`, `TICKET_REOPENED`, `TICKET_ESCALATED`, `TICKET_QUEUE_CHANGED` via `publishWorkflowEvent(...)` and shared transition detection.
    - `packages/tickets/src/actions/optimizedTicketActions.ts` updated similarly (this is the main cached ticket update path).
  - Upgraded legacy ticket lifecycle emissions to include workflow v2 context:
    - `TICKET_UPDATED`, `TICKET_ASSIGNED`, `TICKET_CLOSED` now emit via `publishWorkflowEvent(...)` (adds `occurredAt` + `actorUserId`), and `TICKET_ASSIGNED` includes `previousAssignee*`/`newAssignee*` fields for domain-style payloads while keeping legacy `userId`.
  - Added a pure transition builder for testability: `packages/tickets/src/lib/workflowTicketTransitionEvents.ts`.
  - Extended ticket zod schemas to include ITIL escalation fields (present in DB): `packages/tickets/src/schemas/ticket.schema.ts`.
  - Added unit coverage for transition detection: `packages/tickets/src/lib/__tests__/workflowTicketTransitionEvents.test.ts` (runs without DB).

- 2026-01-23: Completed `F011` (ticket relationship/aggregation emission):
  - Implemented `TICKET_MERGED` / `TICKET_SPLIT` emissions via ticket bundling actions:
    - `packages/tickets/src/actions/ticketBundleActions.ts` now publishes:
      - `TICKET_MERGED` when child tickets are attached to a master bundle (bundle/add children/promote master).
      - `TICKET_SPLIT` when child tickets are detached (remove child/unbundle master).
    - Semantics note: these events represent **bundle attach/detach** in today’s product (there is no true destructive “merge tickets” feature yet); payload still follows proposed schema (`sourceTicketId`/`targetTicketId`, `originalTicketId`/`newTicketIds`) and includes `reason` for workflow authors.
  - Updated bundling integration test harness to mock `@alga-psa/event-bus/publishers` to keep DB-backed tests isolated from the event bus.

- 2026-01-23: Completed `F012` (ticket communication emission):
  - Added a shared builder for ticket communication domain events:
    - `packages/tickets/src/lib/workflowTicketCommunicationEvents.ts` builds additive `TICKET_MESSAGE_ADDED` plus:
      - `TICKET_INTERNAL_NOTE_ADDED` for internal visibility
      - `TICKET_CUSTOMER_REPLIED` when a contact id is available
  - Emitted these events from real comment creation paths (while keeping legacy `TICKET_COMMENT_*` unchanged):
    - `packages/tickets/src/actions/comment-actions/commentActions.ts` (primary comment creation flow)
    - `packages/tickets/src/actions/ticketActions.ts` and `packages/tickets/src/actions/optimizedTicketActions.ts` (legacy/server action flows)
  - Added unit coverage with schema validation via `buildWorkflowPayload(...)`:
    - `packages/tickets/src/lib/__tests__/workflowTicketCommunicationEvents.test.ts`

- 2026-01-23: Completed `F013` (ticket work tracking emission):
  - Emitted `TICKET_TIME_ENTRY_ADDED` when time entries are created for `work_item_type='ticket'`:
    - `server/src/lib/api/services/TimeEntryService.ts` publishes on both direct create (`create`) and time-tracking completion (`stopTimeTracking`).
  - Added a small pure builder for publish-time payload shaping:
    - `server/src/lib/api/services/timeEntryWorkflowEvents.ts`
  - Added unit coverage that validates the built payload against `payload.TicketTimeEntryAdded.v1` via `buildWorkflowPayload(...)`:
    - `server/src/test/unit/timeEntryWorkflowEvents.test.ts`

- 2026-01-23: Completed `F014` (ticket SLA stage emission):
  - Implemented ITIL-backed “resolution SLA” stage events when `itil_priority_level` is present:
    - `TICKET_SLA_STAGE_ENTERED` emitted on ticket create in:
      - `packages/tickets/src/actions/ticketActions.ts` (`addTicket`, `createTicketFromAsset`)
    - `TICKET_SLA_STAGE_MET` / `TICKET_SLA_STAGE_BREACHED` emitted on ticket close in:
      - `packages/tickets/src/actions/ticketActions.ts` (`updateTicket`)
      - `packages/tickets/src/actions/optimizedTicketActions.ts` (`updateTicketWithCache`)
  - Added pure builders and idempotency keys:
    - `packages/tickets/src/lib/workflowTicketSlaStageEvents.ts`
  - Notes/constraints:
    - Stage emitted is currently `resolution` only (no first-class response/custom stage model in product yet).
    - Uses `tenantId` as a stable `slaPolicyId` placeholder until a real SLA policy model exists.

- 2026-01-23: Completed `F015` (ticket approvals — catalog-only):
  - Marked `TICKET_APPROVAL_REQUESTED` / `TICKET_APPROVAL_GRANTED` / `TICKET_APPROVAL_REJECTED` as **catalog-only** for now (no ticket approval subsystem exists to emit these events from).
  - Documented the decision in `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/PRD.md` (Open Questions #4).

- 2026-01-23: Completed `F020` (appointment lifecycle/assignment emission):
  - Emitted workflow v2 appointment domain events from real scheduling/appointment flows:
    - `packages/scheduling/src/actions/scheduleActions.ts` emits `APPOINTMENT_CREATED`, `APPOINTMENT_RESCHEDULED`, `APPOINTMENT_CANCELED`, `APPOINTMENT_COMPLETED`, `APPOINTMENT_NO_SHOW`, `APPOINTMENT_ASSIGNED` when schedule entries represent appointments (`work_item_type='appointment_request'` or `ticket`).
    - `packages/client-portal/src/actions/client-portal-actions/appointmentRequestActions.ts` emits `APPOINTMENT_CREATED`, `APPOINTMENT_RESCHEDULED`, `APPOINTMENT_CANCELED`, `APPOINTMENT_ASSIGNED` for client portal appointment requests (actor is `CONTACT`).
    - `packages/scheduling/src/actions/appointmentRequestManagementActions.ts` emits `APPOINTMENT_CREATED`/`APPOINTMENT_ASSIGNED` for the legacy “approve request creates schedule entry” fallback; emits `APPOINTMENT_ASSIGNED` on reassignment during approval.
  - Added shared payload builders:
    - `shared/workflow/streams/domainEventBuilders/appointmentEventBuilders.ts`
  - Added schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/__tests__/appointmentEventBuilders.test.ts`
  - Notes/constraints:
    - `timezone` is emitted as `UTC` (schedule UI and storage treat times as UTC today).
    - `APPOINTMENT_NO_SHOW` is emitted only when a schedule entry status is set to a no-show variant; `party` defaults to `customer` until the product captures who no-showed explicitly.

- 2026-01-23: Completed `F021` (schedule block create/delete emission):
  - Implemented `SCHEDULE_BLOCK_CREATED` / `SCHEDULE_BLOCK_DELETED` emission for “availability blocks” represented today as **private ad-hoc schedule entries**:
    - `is_private=true`, `work_item_type='ad_hoc'`, `work_item_id=null`, exactly one `assigned_user_ids` owner.
  - Added shared payload builders:
    - `shared/workflow/streams/domainEventBuilders/scheduleBlockEventBuilders.ts`
  - Emitted events from scheduling actions:
    - `packages/scheduling/src/actions/scheduleActions.ts` publishes on create/delete, and on update when an entry becomes/ceases a private ad-hoc block.
  - Added schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/__tests__/scheduleBlockEventBuilders.test.ts`
  - Notes/constraints:
    - `timezone` is emitted as `UTC`.
    - No “block updated” domain event exists yet; time changes to an existing block do not emit a domain event unless the entry crosses the block/non-block boundary.

- 2026-01-23: Completed `F022` (capacity threshold emission):
  - Emitted `CAPACITY_THRESHOLD_REACHED` from real scheduling mutations:
    - `packages/scheduling/src/actions/scheduleActions.ts` publishes after create/update/delete via `maybePublishCapacityThresholdReached(...)`.
  - Implemented team/day capacity math (UTC date) based on existing data model:
    - Capacity limit = sum of `resources.max_daily_capacity` for active team members.
    - Current booked = sum of schedule-entry overlap hours per assignee for that team/date.
    - Event emits only on a threshold **crossing** (previousBooked < limit && currentBooked >= limit).
  - Added shared payload builder + unit coverage:
    - `shared/workflow/streams/domainEventBuilders/capacityThresholdEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/capacityThresholdEventBuilders.test.ts`
  - Added scheduling unit coverage for threshold/date math:
    - `packages/scheduling/src/lib/__tests__/capacityThresholdWorkflowEvents.test.ts`

- 2026-01-23: Completed `F023` (technician dispatch lifecycle emission):
  - Added shared payload/status helpers:
    - `shared/workflow/streams/domainEventBuilders/technicianDispatchEventBuilders.ts`
  - Emitted dispatch lifecycle workflow events from real scheduling updates:
    - `packages/scheduling/src/actions/scheduleActions.ts` now publishes:
      - `TECHNICIAN_DISPATCHED` when technicians are newly assigned to a ticket/appointment schedule entry
      - `TECHNICIAN_EN_ROUTE` / `TECHNICIAN_ARRIVED` when schedule entry `status` transitions to an en-route / arrived value (case-insensitive, supports common variants)
      - `TECHNICIAN_CHECKED_OUT` when schedule entry `status` transitions to a checked-out value **or** when the appointment is marked completed
  - Added schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/__tests__/technicianDispatchEventBuilders.test.ts`

- 2026-01-23: Completed `F030` (project lifecycle emission):
  - Added shared payload builders:
    - `shared/workflow/streams/domainEventBuilders/projectLifecycleEventBuilders.ts`
  - Emitted domain events from real project update paths:
    - `packages/projects/src/actions/projectActions.ts` publishes `PROJECT_UPDATED` (with `updatedFields` + `{previous,new}` `changes`) and `PROJECT_STATUS_CHANGED` on status transitions via `publishWorkflowEvent(...)`.
    - `server/src/lib/api/services/ProjectService.ts` publishes the same domain events for REST API updates.
  - Kept legacy email notifications working with the new payload shape:
    - `server/src/lib/eventBus/subscribers/projectEmailSubscriber.ts` now supports both legacy `{ changes: Record<string, unknown> }` and domain `{ changes: Record<string, {previous,new}> }` shapes and uses `actorUserId` when `userId` is absent.
  - Added schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectLifecycleEventBuilders.test.ts`
  - Cleanup: removed forbidden feature-to-feature import (projects → clients) by querying contacts directly in `packages/projects/src/actions/projectActions.ts`.

- 2026-01-23: Completed `F031` (project task lifecycle emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/projectTaskEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectTaskEventBuilders.test.ts`
  - Emitted workflow v2 domain events from real task creation/update paths:
    - `packages/projects/src/actions/projectTaskActions.ts` publishes:
      - `PROJECT_TASK_CREATED` on task create/duplicate
      - `PROJECT_TASK_ASSIGNED` on primary assignee changes (domain payload with `assignedToId/assignedToType`)
      - `PROJECT_TASK_STATUS_CHANGED` + `PROJECT_TASK_COMPLETED` when status mapping transitions (completed = enters a closed status)
    - `packages/projects/src/actions/phaseTaskImportActions.ts` publishes `PROJECT_TASK_CREATED` (+ `PROJECT_TASK_ASSIGNED` when assigned) for imported tasks.
    - `server/src/lib/api/services/ProjectService.ts` publishes the same task lifecycle events for REST API create/update paths.
    - `server/src/lib/models/scheduleEntry.ts` now publishes domain-shaped `PROJECT_TASK_ASSIGNED` when schedule-driven dispatch assigns a task.
  - Updated legacy notification/email subscribers to tolerate domain payloads:
    - `server/src/lib/eventBus/subscribers/internalNotificationSubscriber.ts` (PROJECT_TASK_ASSIGNED)
    - `server/src/lib/eventBus/subscribers/projectEmailSubscriber.ts` (PROJECT_TASK_ASSIGNED)
  - Verification:
    - `npx vitest run shared/workflow/streams/domainEventBuilders/__tests__/projectTaskEventBuilders.test.ts`

- 2026-01-23: Completed `F032` (project dependency events emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/projectTaskEventBuilders.ts` (dependency blocked/unblocked payload builders)
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectTaskEventBuilders.test.ts`
  - Emitted dependency lifecycle workflow events from real dependency CRUD paths:
    - `packages/projects/src/actions/projectTaskActions.ts` publishes:
      - `PROJECT_TASK_DEPENDENCY_BLOCKED` when a blocking relationship is created (`dependency_type` in {`blocks`,`blocked_by`})
      - `PROJECT_TASK_DEPENDENCY_UNBLOCKED` when a blocking relationship is removed
  - Notes/constraints:
    - Only blocking relationships emit events; `related_to` dependencies remain non-workflow.

- 2026-01-23: Completed `F033` (project approvals — catalog-only):
  - Discovery: there is no authoritative “project approval request/decision” subsystem today (no project approval model/service/actions to hook).
  - Decision: treat `PROJECT_APPROVAL_*` events as **catalog-only** (mirrors `TICKET_APPROVAL_*` rationale) until a real project approval feature exists.
  - Updated `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/PRD.md` Open Questions #4 to reflect `PROJECT_APPROVAL_*` catalog-only status.

- 2026-01-23: Completed `F040` (invoice lifecycle emission):
  - Added billing workflow payload builders:
    - `server/src/lib/api/services/invoiceWorkflowEvents.ts`
  - Emitted invoice lifecycle workflow v2 domain events from real invoice operations:
    - `server/src/lib/api/services/InvoiceService.ts` now publishes:
      - `INVOICE_SENT` on `sendInvoice` (delivery method inferred; includes `clientId`, `sentByUserId`, `sentAt`)
      - `INVOICE_STATUS_CHANGED` on all invoice status transitions across `update`, `finalizeInvoice`, `sendInvoice`, `recordPayment`, `applyCredit`, `recordRefund`, `bulkUpdateStatus`, and soft-cancel in `delete`
      - `INVOICE_DUE_DATE_CHANGED` from `update` when due date changes
      - `INVOICE_OVERDUE` when status transitions into `overdue` (amount due computed from payments + credits)
      - `INVOICE_WRITTEN_OFF` when transitioning `overdue` → `cancelled` with a remaining balance (maps “write off” onto today’s available status model)
  - Added schema-compat unit coverage:
    - `server/src/test/unit/invoiceWorkflowEvents.test.ts`

- 2026-01-23: Completed `F041` (payment events emission):
  - Added billing workflow payload builders:
    - `server/src/lib/api/services/paymentWorkflowEvents.ts`
  - Emitted workflow v2 payment domain events from real payment paths:
    - Manual invoice payments/refunds in `server/src/lib/api/services/InvoiceService.ts` now publish:
      - `PAYMENT_RECORDED` + `PAYMENT_APPLIED` on `recordPayment`
      - `PAYMENT_REFUNDED` on `recordRefund`
    - Stripe webhook processing in `ee/server/src/lib/payments/PaymentService.ts` now publishes:
      - `PAYMENT_RECORDED` + `PAYMENT_APPLIED` on successful payment recording
      - `PAYMENT_REFUNDED` on refund recording
      - `PAYMENT_FAILED` on `payment_intent.payment_failed` events (when amount is present)
  - Added schema-compat unit coverage:
    - `server/src/test/unit/paymentWorkflowEvents.test.ts`
  - Verification:
    - `npx vitest run server/src/test/unit/paymentWorkflowEvents.test.ts`

- 2026-01-23: Completed `F042` (credit events emission):
  - Added shared billing payload builders + schema-compat tests:
    - `shared/workflow/streams/domainEventBuilders/creditNoteEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/creditNoteEventBuilders.test.ts`
  - Emitted workflow v2 credit note domain events from real credit flows:
    - `packages/billing/src/actions/creditActions.ts` now publishes:
      - `CREDIT_NOTE_CREATED` when prepayment credit tracking entries are created
      - `CREDIT_NOTE_APPLIED` per credit source used when applying credits to an invoice (supports multi-credit allocation)
    - `packages/billing/src/actions/invoiceModification.ts` now publishes:
      - `CREDIT_NOTE_CREATED` when finalizing a negative invoice that issues credit (`credit_issuance_from_negative_invoice`)
      - `CREDIT_NOTE_VOIDED` when hard-deleting a negative invoice that issued unused credit (maps delete → void)
  - Verification:
    - `npx vitest run shared/workflow/streams/domainEventBuilders/__tests__/creditNoteEventBuilders.test.ts`

- 2026-01-23: Completed `F043` (contract events emission):
  - Added shared contract payload builders + renewal timing helper:
    - `shared/workflow/streams/domainEventBuilders/contractEventBuilders.ts`
    - Renewal “upcoming” window default: **30 days** (`computeContractRenewalUpcoming`)
  - Emitted workflow v2 contract domain events from real client-contract paths:
    - `packages/clients/src/actions/clientContractActions.ts` publishes:
      - `CONTRACT_CREATED` on `assignContractToClient` and `createClientContract`
      - `CONTRACT_UPDATED` + `CONTRACT_STATUS_CHANGED` + `CONTRACT_RENEWAL_UPCOMING` (on threshold crossing) on `updateClientContract`
      - `CONTRACT_STATUS_CHANGED` on `deactivateClientContract`
    - `packages/billing/src/actions/contractWizardActions.ts` publishes:
      - `CONTRACT_CREATED` (+ optional `CONTRACT_RENEWAL_UPCOMING`) on `createClientContractFromWizard`
  - Added schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/__tests__/contractEventBuilders.test.ts`

- 2026-01-23: Completed `F044` (recurring billing run events emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/recurringBillingRunEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/recurringBillingRunEventBuilders.test.ts`
  - Implemented a billing “run” action that publishes workflow v2 events around invoice generation:
    - `packages/billing/src/actions/recurringBillingRunActions.ts` publishes `RECURRING_BILLING_RUN_STARTED` / `COMPLETED` (with `invoicesCreated`, `failedCount`) and `FAILED` for unexpected fatal failures.
  - Updated billing dashboard invoice generation flows to use the run action (batch + preview generation):
    - `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`
  - Verification:
    - `npx vitest run shared/workflow/streams/domainEventBuilders/__tests__/recurringBillingRunEventBuilders.test.ts`
    - Note: `npx tsc -p packages/billing/tsconfig.json --noEmit` currently fails due to existing TS errors in `packages/billing/src/actions/contractWizardActions.ts` and `packages/billing/src/actions/creditActions.ts` (pre-existing; not addressed in this item).

- 2026-01-23: Completed `F050` (CRM client events emission):
  - Added shared payload builders:
    - `shared/workflow/streams/domainEventBuilders/clientEventBuilders.ts`
  - Emitted workflow v2 domain events from real client create/update/archive paths:
    - `packages/clients/src/actions/clientActions.ts` now publishes:
      - `CLIENT_CREATED` on create
      - `CLIENT_UPDATED` on update (with `updatedFields` + `{previous,new}` `changes`)
      - `CLIENT_STATUS_CHANGED` when `properties.status` transitions
      - `CLIENT_OWNER_ASSIGNED` when `account_manager_id` changes to a user
      - `CLIENT_ARCHIVED` when `is_inactive` transitions to true (including `markClientInactiveWithContacts`)
    - `server/src/lib/api/services/ClientService.ts` now publishes the same domain events for REST API create/update paths.
  - Added schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/__tests__/clientEventBuilders.test.ts`
  - Notes/constraints:
    - `CLIENT_MERGED` remains catalog-only for now (no authoritative client merge/consolidate path exists to emit from today).

- 2026-01-23: Completed `F051` (CRM contact events emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/contactEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/contactEventBuilders.test.ts`
  - Emitted workflow v2 contact domain events from real contact create/update/archive paths:
    - `packages/clients/src/actions/contact-actions/contactActions.tsx` publishes `CONTACT_CREATED`, `CONTACT_UPDATED`, `CONTACT_ARCHIVED` (when `is_inactive` transitions `false → true`) via `publishWorkflowEvent(...)`.
    - `server/src/lib/api/services/ContactService.ts` publishes the same domain events for REST API create/update paths.
  - Implemented `CONTACT_PRIMARY_SET` emission from the authoritative client billing contact change:
    - `packages/clients/src/actions/clientActions.ts` publishes when `billing_contact_id` changes to a non-empty contact id.
    - `server/src/lib/api/services/ClientService.ts` publishes the same event for REST API updates.
  - Notes/constraints:
    - `CONTACT_MERGED` remains catalog-only for now (no authoritative “merge contacts” path exists in product code today).

- 2026-01-23: Completed `F052` (CRM interaction/note events emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/crmInteractionNoteEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/crmInteractionNoteEventBuilders.test.ts`
  - Emitted workflow v2 domain events from real CRM activity paths:
    - `packages/clients/src/actions/interactionActions.ts` publishes `INTERACTION_LOGGED` on interaction creation (derives `channel` from interaction type; ensures interactions are linked to a `clientId`).
    - `packages/clients/src/actions/clientNoteActions.ts` publishes `NOTE_CREATED` when a notes document is first created/linked to a client.
    - `packages/clients/src/actions/contact-actions/contactNoteActions.ts` publishes `NOTE_CREATED` when a notes document is first created/linked to a contact.

- 2026-01-23: Completed `F053` (tags events emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/tagEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/tagEventBuilders.test.ts`
  - Emitted workflow v2 tag domain events from tag actions:
    - `packages/tags/src/actions/tagActions.ts` publishes `TAG_DEFINITION_CREATED`, `TAG_DEFINITION_UPDATED`, `TAG_APPLIED`, `TAG_REMOVED` (uses definition id as `tagId`, and `entityType/entityId` from `tagged_type/tagged_id`).
  - Added `getOrCreateWithStatus` to detect definition creates reliably:
    - `packages/tags/src/models/tagDefinition.ts`

- 2026-01-23: Completed `F060` (document storage lifecycle emission):
  - Added shared payload builders:
    - `shared/workflow/streams/domainEventBuilders/documentStorageEventBuilders.ts`
  - Emitted workflow v2 document storage domain events from the authoritative storage service:
    - `packages/documents/src/storage/StorageService.ts` publishes:
      - `DOCUMENT_UPLOADED` after file record creation (includes `documentId`, `fileName`, `contentType`, `sizeBytes`, `storageKey`)
      - `DOCUMENT_DELETED` after storage delete + soft delete (includes `documentId`, `deletedAt`)
  - Verification:
    - `npx tsc -p packages/documents/tsconfig.json --noEmit`
    - `npx vitest run packages/documents/tests/storageConfig.test.ts`
  - Notes/constraints:
    - `documentId` maps to the file storage record id (`external_files.file_id`) today.
    - Publishing is best-effort (errors are logged but do not fail the upload/delete).

- 2026-01-24: Completed `F061` (document association/detach emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/documentAssociationEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/documentAssociationEventBuilders.test.ts`
  - Emitted workflow v2 document association events from real document flows:
    - `packages/documents/src/actions/documentActions.ts` publishes:
      - `DOCUMENT_ASSOCIATED` on association creation (bulk associate and upload-time associations; also client/contract-specific helpers)
      - `DOCUMENT_DETACHED` on manual detach and on document deletion (reason=`document_deleted`)
    - `packages/documents/src/actions/documentBlockContentActions.ts` publishes `DOCUMENT_ASSOCIATED` when a block-document is created and linked to an entity
  - Verification:
    - `npx vitest run shared/workflow/streams/domainEventBuilders/__tests__/documentAssociationEventBuilders.test.ts`

- 2026-01-24: Completed `F062` (document generation emission):
  - Added shared payload builder + schema-compat unit test:
    - `shared/workflow/streams/domainEventBuilders/documentGeneratedEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/documentGeneratedEventBuilders.test.ts`
  - Emitted `DOCUMENT_GENERATED` from the authoritative PDF generation path (covers invoice PDFs and document-to-PDF conversion):
    - `server/src/services/pdf-generation.service.ts` publishes `DOCUMENT_GENERATED` after storing the generated PDF in `external_files`
    - `sourceType` is `invoice` when generating an invoice PDF, otherwise `document`
    - `sourceId` is the invoice id / source document id
  - Notes/constraints:
    - Publishing is best-effort (errors are logged but do not fail PDF generation/storage).

- 2026-01-24: Completed `F063` (document signatures — catalog-only):
  - Discovery: there is no authoritative “document signature request/fulfillment” subsystem today (no signature request model/service/actions and no provider callback/webhook ingestion path to hook).
  - Decision: treat `DOCUMENT_SIGNATURE_REQUESTED`, `DOCUMENT_SIGNED`, and `DOCUMENT_SIGNATURE_EXPIRED` as **catalog-only** until an e-sign feature is implemented.
  - Updated `ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events/PRD.md` Open Questions #4 to record the decision.

- 2026-01-24: Completed `F070` (inbound email reply emission):
  - Emitted `INBOUND_EMAIL_REPLY_RECEIVED` when the system email processing workflow matches an inbound email to an existing ticket and successfully creates the ticket comment.
  - Implemented best-effort publishing from `shared/workflow/actions/emailWorkflowActions.ts` (`createCommentFromEmail`) behind an optional `inboundReplyEvent` input.
  - Updated both workflow definitions to pass `matchedBy` (`reply_token` vs `thread_headers`) and normalized `receivedAt` for action schema validation:
    - `shared/workflow/workflows/system-email-processing-workflow.ts` (+ `.generated.js`)
    - `services/workflow-worker/src/workflows/system-email-processing-workflow.ts` (+ `.generated.js`)
  - Added a domain payload builder + schema-compat unit test:
    - `shared/workflow/streams/domainEventBuilders/inboundEmailReplyEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/inboundEmailReplyEventBuilders.test.ts`

- 2026-01-24: Completed `F071` (outbound email lifecycle emission):
  - Emitted workflow v2 outbound lifecycle events from the authoritative outbound send abstraction:
    - `server/src/lib/email/BaseEmailService.ts` now publishes best-effort:
      - `OUTBOUND_EMAIL_QUEUED` immediately before provider send attempt
      - `OUTBOUND_EMAIL_SENT` or `OUTBOUND_EMAIL_FAILED` after provider result
  - Notes/constraints:
    - Uses a generated workflow `messageId` (UUID) per send attempt, and includes provider message id when available.
    - Publishing failures do not block email delivery (events are best-effort).
  - Added unit coverage:
    - `server/src/test/unit/outboundEmailWorkflowEvents.test.ts`

- 2026-01-24: Completed `F072` (email delivery/feedback emission):
  - Implemented Resend delivery/feedback webhook ingestion (Svix signature verification):
    - `server/src/app/api/email/webhooks/resend/route.ts`
    - `server/src/services/email/webhooks/resendWebhookEvents.ts` (signature verify + mapping)
  - Added correlation tags/headers so provider callbacks can map back to `tenantId` + workflow `messageId`:
    - `server/src/lib/email/BaseEmailService.ts` now sets `X-Alga-Workflow-Message-Id`/`X-Alga-Tenant-Id` headers and `alga_*` tags on provider messages.
  - Emits workflow v2 domain events (best-effort) when Resend provider support exists:
    - `EMAIL_DELIVERED`, `EMAIL_BOUNCED`, `EMAIL_COMPLAINT_RECEIVED`, `EMAIL_UNSUBSCRIBED`
  - Added schema-compat unit coverage:
    - `shared/workflow/streams/domainEventBuilders/emailFeedbackEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/emailFeedbackEventBuilders.test.ts`
    - `server/src/test/unit/resendWebhookEvents.test.ts`

- 2026-01-24: Completed `F073` (notification delivery lifecycle emission):
  - Implemented workflow v2 notification lifecycle events for **in-app internal notifications**:
    - `NOTIFICATION_SENT` when an internal notification row is created
    - `NOTIFICATION_DELIVERED` / `NOTIFICATION_FAILED` based on Redis Pub/Sub broadcast success/failure
    - `NOTIFICATION_READ` when a user marks a notification as read
  - Wired emissions into the authoritative internal notification paths:
    - `packages/notifications/src/actions/internal-notification-actions/internalNotificationActions.ts`
    - `packages/notifications/src/realtime/internalNotificationBroadcaster.ts`
  - Added shared payload builders + schema-compat unit test coverage:
    - `shared/workflow/streams/domainEventBuilders/notificationEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/notificationEventBuilders.test.ts`

- 2026-01-24: Completed `F074` (survey/CSAT lifecycle emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/surveyEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/surveyEventBuilders.test.ts`
  - Emitted workflow v2 survey lifecycle events from the authoritative survey flows:
    - `server/src/services/surveyService.ts` now publishes `SURVEY_SENT` when an invitation is sent, and publishes `SURVEY_REMINDER_SENT` when a subsequent invitation is sent for the same `(ticketId, templateId, contactId)` tuple (treated as reminder #N).
    - `packages/surveys/src/actions/surveyResponseActions.ts` now publishes `SURVEY_RESPONSE_RECEIVED` when a response is persisted, and publishes `CSAT_ALERT_TRIGGERED` when the rating is <= `NEGATIVE_RATING_THRESHOLD` (scope = assigned agent when available, otherwise org).
    - `packages/surveys/src/actions/surveyTokenService.ts` now publishes `SURVEY_EXPIRED` (best-effort) when an expired token is resolved (idempotencyKey = `survey_expired:<tenant>:<invitationId>`).

- 2026-01-24: Completed `F080` (integration sync lifecycle emission):
  - Added workflow v2 integration sync domain payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/integrationSyncEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationSyncEventBuilders.test.ts`
  - Emitted `INTEGRATION_SYNC_STARTED` / `INTEGRATION_SYNC_COMPLETED` / `INTEGRATION_SYNC_FAILED` from real RMM sync paths (NinjaOne):
    - `ee/server/src/lib/integrations/ninjaone/sync/syncEngine.ts` publishes lifecycle events for:
      - full sync (`runFullSync`)
      - incremental sync (`runIncrementalSync`)
      - single-device sync (`syncDevice`)
    - Uses `SyncOptions.performedBy` (when provided) to attribute `INTEGRATION_SYNC_STARTED.initiatedByUserId`.

- 2026-01-24: Completed `F081` (integration webhook receipt emission):
  - Added safe webhook payload builders:
    - `shared/workflow/streams/domainEventBuilders/integrationWebhookEventBuilders.ts`
      - `sanitizeIntegrationWebhookRawPayload(...)` redacts sensitive keys (token/secret/password/apiKey/authorization/signature) and enforces a size cap
      - `buildIntegrationWebhookReceivedPayload(...)` builds schema-aligned payloads
  - Emitted `INTEGRATION_WEBHOOK_RECEIVED` from the authoritative NinjaOne webhook handler:
    - `ee/server/src/lib/integrations/ninjaone/webhooks/webhookHandler.ts` publishes the domain event with:
      - `webhookId` derived from `payload.id`/`payload.activityId` (falls back to sha256-based id)
      - `rawPayloadRef` set to a generated `integration-webhook:<uuid>` reference
      - a structured log entry containing a **redacted** payload snapshot keyed by `rawPayloadRef`
  - Added schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationWebhookEventBuilders.test.ts`

- 2026-01-24: Completed `F082` (integration connection health emission):
  - Added workflow v2 integration connection payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/integrationConnectionEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationConnectionEventBuilders.test.ts`
  - Emitted `INTEGRATION_CONNECTED` on successful NinjaOne OAuth connect:
    - `ee/server/src/app/api/integrations/ninjaone/callback/route.ts`
  - Emitted `INTEGRATION_DISCONNECTED` on manual NinjaOne disconnect:
    - `ee/server/src/lib/actions/integrations/ninjaoneActions.ts`
  - Note: for RMM, `connectionId` is set to the tenant integration UUID (`integrationId`) since the current data model has a single connection row per provider/tenant.

- 2026-01-24: Completed `F083` (integration token lifecycle emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/integrationTokenEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationTokenEventBuilders.test.ts`
  - Implemented best-effort emission from the NinjaOne OAuth client:
    - `ee/server/src/lib/integrations/ninjaone/ninjaOneClient.ts` now publishes `INTEGRATION_TOKEN_REFRESH_FAILED` when refresh attempts fail (deduped in 5-minute buckets).
    - `ee/server/src/lib/integrations/ninjaone/ninjaOneClient.ts` now publishes `INTEGRATION_TOKEN_EXPIRING` when a token expiry timestamp indicates a long-lived token nearing expiration (default window 7 days; suppresses noisy <24h expiries).
  - Propagated integration context into NinjaOne client factories where available:
    - `ee/server/src/lib/integrations/ninjaone/sync/*` passes `integrationId` into `createNinjaOneClient(...)` so token events can include `integrationId`/`connectionId`.

- 2026-01-24: Completed `F084` (external mapping change emission):
  - Added shared payload builder:
    - `shared/workflow/streams/domainEventBuilders/externalMappingEventBuilders.ts`
  - Emitted `EXTERNAL_MAPPING_CHANGED` from the authoritative accounting mapping CRUD actions:
    - `packages/integrations/src/actions/externalMappingActions.ts` publishes on create/update/delete for `tenant_external_entity_mappings`
    - Payload uses `provider=integration_type`, `mappingType=alga_entity_type`, and includes `previousValue`/`newValue` snapshots (camelCase keys).
  - Added unit coverage for payload shaping:
    - `packages/integrations/src/lib/externalMappingWorkflowEvents.ts`
    - `packages/integrations/src/lib/__tests__/externalMappingWorkflowEvents.test.ts`

- 2026-01-24: Completed `F090` (asset lifecycle emission):
  - Added shared payload builders + schema-compat unit tests:
    - `shared/workflow/streams/domainEventBuilders/assetEventBuilders.ts`
    - `shared/workflow/streams/domainEventBuilders/__tests__/assetEventBuilders.test.ts`
  - Emitted workflow v2 asset domain events from authoritative asset and association paths:
    - `packages/assets/src/actions/assetActions.ts` publishes:
      - `ASSET_CREATED` on asset creation
      - `ASSET_UPDATED` on asset updates (with `updatedFields` + `{previous,new}` `changes` derived from the update payload)
      - `ASSET_ASSIGNED` / `ASSET_UNASSIGNED` on asset association create/remove (ownerType = `ticket`/`project`)
      - `ASSET_ASSIGNED` on client reassignment when `client_id` changes (ownerType = `client`)
      - `ASSET_WARRANTY_EXPIRING` on 30-day threshold crossings (create/update) via `computeAssetWarrantyExpiring(...)`
  - Verification:
    - `npx vitest run shared/workflow/streams/domainEventBuilders/__tests__/assetEventBuilders.test.ts`
    - `npx tsc -p packages/assets/tsconfig.json --noEmit`

- 2026-01-24: Completed `F091` (media upload + processing emission):
   - Added shared payload builders + schema-compat unit tests:
     - `shared/workflow/streams/domainEventBuilders/mediaEventBuilders.ts`
     - `shared/workflow/streams/domainEventBuilders/__tests__/mediaEventBuilders.test.ts`
   - Emitted `FILE_UPLOADED` from the authoritative file storage services:
     - `packages/documents/src/storage/StorageService.ts` (alongside existing `DOCUMENT_UPLOADED`)
     - `server/src/lib/storage/StorageService.ts`
   - Emitted media processing lifecycle events for document preview generation:
     - `MEDIA_PROCESSING_SUCCEEDED` / `MEDIA_PROCESSING_FAILED` from:
       - `packages/documents/src/lib/documentPreviewGenerator.ts`
       - `server/src/lib/utils/documentPreviewGenerator.ts`
     - Success outputs include `thumbnail`/`preview` file ids when generated; failures include a stable `errorCode`.
   - Added focused unit coverage:
     - `server/src/test/unit/documentPreviewGenerator.test.ts` asserts `MEDIA_PROCESSING_SUCCEEDED` is published for supported file types.
     - `packages/documents/tests/storageService.workflowEvents.test.ts` asserts `FILE_UPLOADED` is published on upload.
   - Gotcha: `packages/documents/src/storage/StorageService.ts` imports `@alga-psa/auth/getCurrentUser` (which depends on `@alga-psa/media`); tests that import this module must mock `@alga-psa/auth/getCurrentUser` to avoid Vite import-analysis failures.

## Next Up

- All features in `features.json` are now implemented; proceed to `tests.json` checklist.

- 2026-01-24: Completed `T001` (schema conventions coverage):
  - Added a schema-level regression test that parses `event-proposals.md` and asserts payload schema conventions:
    - `shared/workflow/runtime/__tests__/payloadSchemaConventions.test.ts`
    - Ensures `tenantId` + `occurredAt` are required, top-level keys are camelCase (no `_`), and `updatedFields`/`changes` are paired.
    - Ensures `previous*` transition fields have corresponding `new*` fields, with explicit exceptions for documented unassignment patterns and `CONTACT_PRIMARY_SET`.
  - Tweaked `payload.TicketUnassigned.v1` schema to include optional `newAssigneeId/newAssigneeType` fields for consistency:
    - `shared/workflow/runtime/schemas/ticketEventSchemas.ts`

- 2026-01-24: Completed `T002` (schema registry resolves + validates examples):
  - Added an auto-example generator test that:
    - Parses `event-proposals.md`, derives `payload.*.v1` refs, asserts `schemaRegistry.has(ref)`, and validates an auto-generated example payload per ref.
    - `shared/workflow/runtime/__tests__/payloadSchemaExamples.test.ts`

- 2026-01-24: Completed `T003` (event bus schema coverage):
  - Existing test asserts `EVENT_TYPES` ↔ `EventTypeEnum` alignment and that every event type has a payload schema mapping:
    - `shared/workflow/streams/__tests__/eventBusSchema.expandedEvents.test.ts`

- 2026-01-24: Completed `T004` (catalog migration coverage):
  - Added a migration-level coverage test that parses `event-proposals.md` and asserts the system catalog upsert migration includes every proposed `event_type`:
    - `server/src/test/unit/workflowEventCatalogMigrationCoverage.test.ts`

- 2026-01-24: Completed `T005` (simulator form-mode schema + validation coverage):
  - Added a schema-driven test that asserts every proposed `payload.*.v1` ref can be converted to JSON schema (form builder input) and that representative schemas reject invalid payloads:
    - `shared/workflow/runtime/__tests__/workflowEventFormModeBuilder.test.ts`

- 2026-01-24: Completed `T006` (overlap handling coverage):
  - Existing event bus schema regression test asserts overlap decisions are encoded explicitly:
    - `shared/workflow/streams/__tests__/eventBusSchema.expandedEvents.test.ts`

- 2026-01-24: Completed `T010` (ticket status/priority transition coverage):
  - Existing transition builder unit test asserts `TICKET_STATUS_CHANGED` + `TICKET_PRIORITY_CHANGED` include `previous*`/`new*` values:
    - `packages/tickets/src/lib/__tests__/workflowTicketTransitionEvents.test.ts`

- 2026-01-24: Completed `T011` (ticket assignment change coverage):
  - Added schema-level regression coverage to ensure the event bus accepts domain-shaped assignment payloads:
    - `shared/workflow/streams/__tests__/ticketAssignmentEvents.test.ts`

- 2026-01-24: Completed `T012` (ticket reopened coverage):
  - Existing transition builder unit test asserts `TICKET_REOPENED` includes `previousStatusId/newStatusId`:
    - `packages/tickets/src/lib/__tests__/workflowTicketTransitionEvents.test.ts`

- 2026-01-24: Completed `T013` (ticket escalation/queue change coverage):
  - Existing transition builder unit test asserts `TICKET_ESCALATED` + `TICKET_QUEUE_CHANGED` payloads:
    - `packages/tickets/src/lib/__tests__/workflowTicketTransitionEvents.test.ts`

- 2026-01-24: Completed `T014` (ticket merge/split coverage):
  - Added schema-level regression coverage for relationship event payloads:
    - `shared/workflow/streams/__tests__/ticketMergeSplitEvents.test.ts`

- 2026-01-24: Completed `T015` (ticket tag change coverage):
  - Existing tag action builder tests cover tag add/remove events (applies to tickets via `entityType/entityId`):
    - `shared/workflow/streams/domainEventBuilders/__tests__/tagEventBuilders.test.ts`

- 2026-01-24: Completed `T016` (ticket communication coverage):
  - Existing unit coverage validates `TICKET_MESSAGE_ADDED`, `TICKET_CUSTOMER_REPLIED`, and `TICKET_INTERNAL_NOTE_ADDED` payload construction and schema compatibility:
    - `packages/tickets/src/lib/__tests__/workflowTicketCommunicationEvents.test.ts`

- 2026-01-24: Completed `T017` (ticket time entry coverage):
  - Existing unit coverage validates `TICKET_TIME_ENTRY_ADDED` payload building against `payload.TicketTimeEntryAdded.v1`:
    - `server/src/test/unit/timeEntryWorkflowEvents.test.ts`

- 2026-01-24: Completed `T018` (ticket SLA stage coverage):
  - Existing unit coverage validates stage enter/met/breached builders and idempotency behavior:
    - `packages/tickets/src/lib/__tests__/workflowTicketSlaStageEvents.test.ts`

- 2026-01-24: Completed `T019` (ticket approvals are catalog-only):
  - Per PRD decision, `TICKET_APPROVAL_*` events are catalog-only; coverage relies on:
    - Schema registry example validation (`T002`): `shared/workflow/runtime/__tests__/payloadSchemaExamples.test.ts`
    - Migration coverage (`T004`): `server/src/test/unit/workflowEventCatalogMigrationCoverage.test.ts`

- 2026-01-24: Completed `T020` (appointment lifecycle coverage):
  - Existing builder unit test validates appointment lifecycle payloads (start/end time + timezone) against schemas:
    - `shared/workflow/streams/domainEventBuilders/__tests__/appointmentEventBuilders.test.ts`

- 2026-01-24: Completed `T021` (appointment assignment coverage):
  - Existing builder unit test validates `APPOINTMENT_ASSIGNED` payloads (previous/new assignee) against schemas:
    - `shared/workflow/streams/domainEventBuilders/__tests__/appointmentEventBuilders.test.ts`

- 2026-01-24: Completed `T022` (schedule block coverage):
  - Existing builder unit test validates `SCHEDULE_BLOCK_CREATED` and `SCHEDULE_BLOCK_DELETED` payloads against schemas:
    - `shared/workflow/streams/domainEventBuilders/__tests__/scheduleBlockEventBuilders.test.ts`

## Suggested Phasing (to reduce risk)

Phase 1 (authoritative CRUD/state transitions; low provider dependency):
- Tickets transitions + assignment
- Projects task/status
- Billing invoice lifecycle + payments
- CRM client/contact changes
- Tags generic apply/remove

Phase 2 (integration/provider dependent):
- Email delivery/bounce/complaint/unsubscribe
- Notifications delivered/read
- Integrations token lifecycle + webhook receipt

Phase 3 (feature dependent / optional modules):
- SLA stages, approvals, dispatch/field ops, signatures

## Commands / Runbooks

- Validate plan JSON shape: `python3 scripts/validate_plan.py ee/docs/plans/2026-01-23-workflow-event-catalog-domain-events`
- Local verification for this plan (until NX worker issue is resolved):
  - Lint changed files: `npx eslint shared/workflow/streams/eventBusSchema.ts shared/workflow/streams/workflowEventPublishHelpers.ts packages/event-bus/src/eventBus.ts packages/event-bus/src/publishers/index.ts server/src/lib/eventBus/index.ts server/src/lib/eventBus/publishers/index.ts`
  - Note: `npx nx build @alga-psa/shared` fails in this sandbox with `NX   Failed to start plugin worker.`

## Gotchas

- (Resolved in this worktree) Earlier sandbox runs had `git add` / `git commit` failing with `.../.git/worktrees/.../index.lock` permission errors. As of 2026-01-23 in `/Users/roberisaacs/alga-psa.worktrees/feature/workflow-events-catalog`, commits succeed normally.
- DB-backed vitest integration tests (e.g. `server/src/test/integration/ticketBundling.integration.test.ts`) require a local Postgres instance matching `.env.localtest` (observed `ECONNREFUSED` on `localhost:5438` when not running).
- `npm run test:nx` currently fails on `tools/nx-tests/editionSwapping.test.ts` (CE alias `ee` resolves to `packages/ee/src` instead of `server/src/empty`). This appears unrelated to workflow event changes; use targeted vitest runs for verification until fixed.
- Some older unit tests import deep, non-exported subpaths (e.g. `@alga-psa/projects/actions/projectActions`) and fail under Vite import-analysis with `Missing "./actions/projectActions" specifier...`; use source-relative imports in tests or prefer shared-schema-level tests until package exports are updated.
- `npx tsc -p ee/server/tsconfig.json --noEmit` currently fails with a pre-existing type error in `shared/workflow/runtime/actions/registerEmailWorkflowActions.ts` (`messageId` required vs optional mismatch).

## Work Log (continued)

- 2026-01-24: Completed `T023` (capacity thresholds coverage):
  - Added unit coverage that asserts `CAPACITY_THRESHOLD_REACHED` publishes only on a threshold crossing and does nothing when capacity isn’t configured:
    - `packages/scheduling/src/lib/__tests__/capacityThresholdWorkflowEvents.publisher.test.ts`
  - Refactored `maybePublishCapacityThresholdReached(...)` to accept optional `__deps` (publisher + data access functions + clock) so it can be tested without a DB:
    - `packages/scheduling/src/lib/capacityThresholdWorkflowEvents.ts`

- 2026-01-24: Completed `T024` (dispatch lifecycle “supported only” coverage):
  - Expanded unit coverage to assert dispatch lifecycle gating and technician id normalization:
    - `shared/workflow/streams/domainEventBuilders/__tests__/technicianDispatchEventBuilders.test.ts`

- 2026-01-24: Completed `T030` (project updated coverage):
  - Coverage already exists via schema-compat builder test asserting `updatedFields` + `{previous,new}` `changes` shape:
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectLifecycleEventBuilders.test.ts`

- 2026-01-24: Completed `T031` (project status changed coverage):
  - Coverage already exists via schema-compat builder test asserting `previousStatus`/`newStatus` transition shape:
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectLifecycleEventBuilders.test.ts`

- 2026-01-24: Completed `T032` (project task lifecycle coverage):
  - Coverage already exists via schema-compat builder test for task create/assign/status/complete payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectTaskEventBuilders.test.ts`

- 2026-01-24: Completed `T033` (project dependency coverage):
  - Coverage already exists via schema-compat builder test for dependency blocked/unblocked payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/projectTaskEventBuilders.test.ts`

- 2026-01-24: Completed `T034` (project approvals are catalog-only):
  - Per PRD decision, `PROJECT_APPROVAL_*` events are catalog-only; coverage relies on:
    - Schema registry example validation (`T002`): `shared/workflow/runtime/__tests__/payloadSchemaExamples.test.ts`
    - Migration coverage (`T004`): `server/src/test/unit/workflowEventCatalogMigrationCoverage.test.ts`

- 2026-01-24: Completed `T040` (invoice send/status/due-date coverage):
  - Coverage exists via billing payload builder unit tests:
    - `server/src/test/unit/invoiceWorkflowEvents.test.ts`

- 2026-01-24: Completed `T041` (invoice overdue/write-off coverage):
  - Coverage exists via billing payload builder unit tests (days overdue + monetary context):
    - `server/src/test/unit/invoiceWorkflowEvents.test.ts`

- 2026-01-24: Completed `T042` (payments coverage):
  - Coverage exists via billing payload builder unit tests (recorded/applied/failed/refunded + invoice applications):
    - `server/src/test/unit/paymentWorkflowEvents.test.ts`

- 2026-01-24: Completed `T043` (credits coverage):
  - Coverage exists via schema-compat builder tests for credit note created/applied/voided payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/creditNoteEventBuilders.test.ts`

- 2026-01-24: Completed `T044` (contracts coverage):
  - Coverage exists via schema-compat builder tests for contract lifecycle + renewal-upcoming timing:
    - `shared/workflow/streams/domainEventBuilders/__tests__/contractEventBuilders.test.ts`

- 2026-01-24: Completed `T045` (recurring billing run coverage):
  - Coverage exists via schema-compat builder tests for run started/completed/failed payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/recurringBillingRunEventBuilders.test.ts`

- 2026-01-24: Completed `T050` (CRM client coverage):
  - Coverage exists via schema-compat builder tests for client lifecycle payload shapes (including catalog-only `CLIENT_MERGED`):
    - `shared/workflow/streams/domainEventBuilders/__tests__/clientEventBuilders.test.ts`

- 2026-01-24: Completed `T051` (CRM contact coverage):
  - Coverage exists via schema-compat builder tests for contact lifecycle payload shapes (including catalog-only `CONTACT_MERGED`):
    - `shared/workflow/streams/domainEventBuilders/__tests__/contactEventBuilders.test.ts`

- 2026-01-24: Completed `T052` (CRM interaction/note coverage):
  - Coverage exists via schema-compat builder tests for interaction logged + note created payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/crmInteractionNoteEventBuilders.test.ts`

- 2026-01-24: Completed `T053` (tags coverage):
  - Coverage exists via schema-compat builder tests for definition create/update and tag apply/remove payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/tagEventBuilders.test.ts`

- 2026-01-24: Completed `T060` (document upload/delete coverage):
  - Added a unit test that asserts `StorageService` publishes both `DOCUMENT_UPLOADED` and `DOCUMENT_DELETED` with storage metadata:
    - `packages/documents/tests/storageService.workflowEvents.test.ts`

- 2026-01-24: Completed `T061` (document association/detach coverage):
  - Coverage exists via schema-compat builder tests for document associated/detached payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/documentAssociationEventBuilders.test.ts`

- 2026-01-24: Completed `T062` (document generation coverage):
  - Coverage exists via schema-compat builder tests for `DOCUMENT_GENERATED` payload shape (sourceType/sourceId):
    - `shared/workflow/streams/domainEventBuilders/__tests__/documentGeneratedEventBuilders.test.ts`

- 2026-01-24: Completed `T063` (document signatures are catalog-only):
  - Per PRD decision, `DOCUMENT_SIGNATURE_*` events are catalog-only; coverage relies on:
    - Schema registry example validation (`T002`): `shared/workflow/runtime/__tests__/payloadSchemaExamples.test.ts`
    - Migration coverage (`T004`): `server/src/test/unit/workflowEventCatalogMigrationCoverage.test.ts`

- 2026-01-24: Completed `T070` (inbound email reply coverage):
  - Coverage exists via schema-compat builder tests for `INBOUND_EMAIL_REPLY_RECEIVED` payload shape:
    - `shared/workflow/streams/domainEventBuilders/__tests__/inboundEmailReplyEventBuilders.test.ts`

- 2026-01-24: Completed `T071` (outbound email lifecycle coverage):
  - Coverage exists via unit tests for the outbound send pipeline publishing queued/sent/failed events:
    - `server/src/test/unit/outboundEmailWorkflowEvents.test.ts`

- 2026-01-24: Completed `T072` (email delivery/feedback coverage):
  - Coverage exists via schema-compat builder tests and provider webhook mapping tests:
    - `shared/workflow/streams/domainEventBuilders/__tests__/emailFeedbackEventBuilders.test.ts`
    - `server/src/test/unit/resendWebhookEvents.test.ts`

- 2026-01-24: Completed `T073` (notification lifecycle coverage):
  - Coverage exists via schema-compat builder tests for sent/delivered/failed/read payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/notificationEventBuilders.test.ts`

- 2026-01-24: Completed `T074` (survey/CSAT lifecycle coverage):
  - Coverage exists via schema-compat builder tests for survey sent/response/reminder/expired and CSAT alert payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/surveyEventBuilders.test.ts`

- 2026-01-24: Completed `T080` (integration sync lifecycle coverage):
  - Coverage exists via schema-compat builder tests for sync started/completed/failed payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationSyncEventBuilders.test.ts`

- 2026-01-24: Completed `T081` (integration webhook receipt coverage):
  - Coverage exists via schema-compat builder tests for safe redaction and `INTEGRATION_WEBHOOK_RECEIVED` payload shape:
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationWebhookEventBuilders.test.ts`

- 2026-01-24: Completed `T082` (integration connect/disconnect coverage):
  - Coverage exists via schema-compat builder tests for connected/disconnected payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationConnectionEventBuilders.test.ts`

- 2026-01-24: Completed `T083` (integration token lifecycle coverage):
  - Coverage exists via schema-compat builder tests for token expiring and refresh-failed payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/integrationTokenEventBuilders.test.ts`

- 2026-01-24: Completed `T084` (external mapping changed coverage):
  - Coverage exists via unit tests for mapping payload shaping (previous/new snapshots + mappingType):
    - `packages/integrations/src/lib/__tests__/externalMappingWorkflowEvents.test.ts`

- 2026-01-24: Completed `T090` (asset lifecycle coverage):
  - Coverage exists via schema-compat builder tests for asset lifecycle + warranty-expiring payload shapes:
    - `shared/workflow/streams/domainEventBuilders/__tests__/assetEventBuilders.test.ts`

- 2026-01-24: Completed `T091` (media upload + processing coverage):
  - Coverage exists via schema-compat builder tests and preview-generation publish tests:
    - `shared/workflow/streams/domainEventBuilders/__tests__/mediaEventBuilders.test.ts`
    - `packages/documents/tests/storageService.workflowEvents.test.ts` (FILE_UPLOADED)
    - `server/src/test/unit/documentPreviewGenerator.test.ts` (MEDIA_PROCESSING_SUCCEEDED)