alla-allaos-fullstack/docs/implementation/task-ep1.3-business-event-foundation-2026-07-13.md

# Task EP.1.3 Business Event Foundation - 2026-07-13

## Scope

- introduced canonical Business Event contract
- added machine-readable registry, alias resolution, ownership metadata, naming rules, and payload validation
- added transport-independent publisher abstraction and in-process dispatcher
- added idempotent subscriber handling and unsupported-version detection
- published initial Activity lifecycle business events from Activity service layer
- documented projection consumer contracts, event sequence matrix, replay readiness, compatibility mapping, and versioning strategy
- preserved existing notification, approval, follow-up, dashboard, report, and audit behavior

## Review Summary

Reviewed before and during implementation:

- `AGENTS.md`
- `plans/task-ep.1.3.md`
- `docs/standards/task-catalog.md`
- `docs/standards/project-foundations.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/task-review-checklist.md`
- `docs/security/crm-authorization-boundaries.md`
- `docs/implementation/task-ep1.1-activity-domain-foundation-2026-07-10.md`
- `docs/implementation/task-ep1.2-activity-integration-legacy-followup-adapter-2026-07-13.md`
- existing Activity lifecycle service operations
- existing notification event service
- existing approval notification publication behavior
- existing audit-log foundation

## Implementation Summary

### Canonical Contract

Added `BusinessEvent<TPayload>` in `src/features/foundation/business-events/types.ts`.

The envelope includes:

- globally unique `eventId`
- registered `eventType`
- explicit `schemaVersion`
- organization, branch, entity, primary record, and related records
- actor, `occurredAt`, `correlationId`, and `causationId`
- visibility metadata for product type, pricing sensitivity, and internal-only events
- payload and metadata

### Registry And Naming

Added `src/features/foundation/business-events/registry.ts`.

The registry freezes canonical names and ownership for Activity, Lead, Opportunity, Quotation, Approval, Customer, and PO families. Naming follows lowercase `<entity>.<past-tense-action>` where practical, with compatibility aliases for existing approval notification names such as `approval.step.approved`.

Unknown event types are rejected by publisher validation.

### Publisher And Dispatcher

Added:

- `src/features/foundation/business-events/publisher.ts`
- `src/features/foundation/business-events/dispatcher.ts`

The initial dispatcher is in-process and transport-independent. It supports independent subscriber registration, no-subscriber dispatch, duplicate detection by `consumerName:eventId`, subscriber isolation, unsupported-version reporting, and publish-many ordering.

No Kafka, RabbitMQ, Redis Streams, persistent event store, replay table, or projection table was introduced.

### Initial Activity Event Publishing

Activity lifecycle events now publish from `src/features/crm/activities/server/service.ts`, after successful service-layer mutations:

- `activity.created`
- `activity.assigned`
- `activity.reassigned`
- `activity.started`
- `activity.rescheduled`
- `activity.completed`
- `activity.cancelled`
- `activity.deleted`

Route handlers do not publish events directly.

Activity payloads redact narrative fields when an Activity is pricing-sensitive or internal-only. Visibility metadata remains available so future consumers can enforce CRM authorization before re-querying source details.

Legacy follow-up adapters do not publish events in EP.1.3.

### Event Sequence Matrix

Added `BUSINESS_EVENT_SEQUENCE_MATRIX` in `src/features/foundation/business-events/matrices.ts`.

It freezes expected order for key operations:

- Create Activity
- Assign Existing Activity
- Start Activity
- Reschedule Activity
- Complete Activity
- Cancel Activity
- Convert Lead
- Submit Approval
- Receive PO

### Event Consumer Matrix

Added `BUSINESS_EVENT_CONSUMER_MATRIX` in `src/features/foundation/business-events/matrices.ts`.

Consumers are explicitly non-owning:

- Timeline
- Calendar
- Dashboard
- Notification
- My Day
- Relationship Health
- Forecast

All listed projection consumers are forbidden from mutating source-domain lifecycle state.

### Replay Contracts

Added `src/features/foundation/business-events/replay.ts`.

Replay is contract-only in EP.1.3:

- request must be organization-scoped
- dry-run defaults to true
- ordering is `occurred_at_then_event_id`
- idempotency is required
- no replay route or persistent event store was added

### Existing Event Compatibility

Added `src/features/foundation/business-events/compatibility.ts`.

Existing approval notification event behavior remains untouched. Compatibility aliases map current names to canonical business event names where needed:

- `approval.step.approved` -> `approval.step-approved`
- `approval.step.rejected` -> `approval.step-rejected`

## Versioning Strategy

- Every event includes `schemaVersion`.
- Additive optional payload fields can remain on the same event type and schema version when existing consumers are unaffected.
- Incompatible semantic changes require a new schema version.
- Consumers can declare supported versions per event type.
- Unsupported versions are reported by the dispatcher and do not silently process.
- Deprecated event definitions must specify `replacementEventType`.

## Ordering And Idempotency Rules

- Global ordering across all domains is not guaranteed.
- Related events in one operation share `correlationId`.
- Child events use `causationId` when one event directly triggers another.
- Consumers must not rely on undocumented timing.
- Dispatcher duplicate handling is in-memory for EP.1.3 tests and contracts only.
- Persistent checkpointing remains a future projection-foundation concern.

## Observability Hooks

The dispatch result captures:

- event id and type
- dispatch status
- dispatch duration
- subscriber name
- subscriber status
- subscriber duration
- subscriber error message
- duplicate and unsupported-version outcomes

Structured persistence of these observations is intentionally deferred until persistent event/projection infrastructure is approved.

## Projection Readiness

Ready for EP.1.4 to define projection storage and consumers using:

- `BusinessEvent`
- `BusinessEventConsumer`
- `BusinessEventPublisher`
- `BusinessEventDispatcher`
- event registry definitions
- sequence matrix
- consumer matrix
- replay contract

Not implemented in EP.1.3:

- Timeline projection
- Calendar projection
- Dashboard projection replacement
- Notification expansion
- My Day
- Manager Workspace
- Executive Workspace
- Relationship Health
- Forecast projection
- Automation engine
- external broker
- persistent replay engine
- projection storage tables

## Verification

- `npm run typecheck`
- `node --disable-warning=ExperimentalWarning --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test src/features/foundation/business-events/*.test.ts src/features/crm/activities/server/business-events.test.ts`

## Residual Risks

- Business events are currently in-process only; no cross-process delivery guarantee exists.
- No persistent event store exists, so replay remains a contract and testing surface only.
- Subscriber failures will fail publisher dispatch; no production subscriber is registered in EP.1.3.
- Existing approval notifications still use the current notification event service and are mapped for compatibility rather than migrated.