alla-allaos-fullstack/plans/task-ep.1.3.md

Task EP.1.3 – Business Event Foundation

Status: Completed Priority: Critical Type: Platform Foundation / Business Event Architecture

Depends On

• EP.1.1 Activity Domain Foundation
• EP.1.2 Activity Integration & Legacy Follow-up Adapter
• BU-R.0 Business Blueprint Freeze
• BU-R.0.1 Workspace & Activity Business Blueprint Completion
• BU-R.1 Business Capability Audit
• AR.1 Architecture Transition Plan
• AR.2 Epic & Technical Design
• ENG.0 Engineering Constitution

---

Objective

Introduce the shared Business Event Foundation for ALLA OS.

This task establishes the canonical event contract, event registry, publisher and subscriber abstractions, in-process dispatcher, event ownership rules, event versioning, sequence rules, consumer mappings, projection contracts, replay contracts, testing standards, and observability hooks.

The Business Event Foundation must enable future Timeline, Calendar, Notification, Dashboard, My Day, Forecast, Relationship Health, and Automation capabilities without requiring those consumers to couple directly to operational domain implementations.

This task must remain additive and transport-independent.

It must not introduce Kafka, RabbitMQ, Redis Streams, external message brokers, projection tables, or asynchronous infrastructure.

---

Background

EP.1.1 introduced the additive Activity Domain and the first crm_activities write model.

EP.1.2 introduced:

• legacy lead follow-up adapter
• legacy opportunity follow-up adapter
• legacy quotation follow-up adapter
• canonical ActivityTimelineItem
• compatibility read layer
• additive recent-activity integration
• Activity numbering and attachment foundations

The next architectural requirement is a shared Business Event Foundation.

Without this foundation, Timeline, Calendar, Notification, Dashboard, My Day, Forecast, Relationship Health, and Automation may independently interpret operational changes and duplicate business logic.

Business events must become the governed communication contract between source domains and downstream projections.

---

Architecture Principles

1. Source Domain Ownership

Operational domains remain the owners of business state.

Examples:

• Activity owns Activity lifecycle changes.
• Lead owns Lead assignment and handoff changes.
• Opportunity owns project progress, forecast, Hot Project, and business outcome.
• Quotation owns quotation document lifecycle.
• Approval owns approval workflow decisions.
• Customer owns customer relationship record changes.

A projection or subscriber must never publish an event that belongs to another domain.

---

2. Publish After Successful State Change

Business events must be published only after the related business mutation succeeds.

Route Handlers must not publish business events directly.

Publishing belongs to the owning service or an approved service-layer integration component.

---

3. Transport Independence

Business domains publish through an abstraction.

Initial implementation:

Domain Service
    ↓
Business Event Publisher
    ↓
In-Process Dispatcher

Future implementation may introduce another transport without changing domain event contracts.

---

4. Projection over Duplication

Timeline, Calendar, Dashboard, Notification, My Day, Forecast, and Relationship Health consume business events or governed read contracts.

They do not become alternate owners of operational lifecycle state.

---

5. Backward Compatibility

Existing APIs, follow-up behavior, dashboard datasets, report datasets, notification behavior, approval events, and audit history must remain operational.

No existing event name that is already used in production may be renamed without a compatibility plan.

---

6. Audit and Event Separation

Audit Log and Business Event have different responsibilities.

• Audit Log records immutable mutation evidence.
• Business Event communicates a business fact to downstream consumers.

Publishing a Business Event does not replace mandatory audit logging.

---

Review Required

Review before implementation:

Governance

• AGENTS.md
• docs/standards/engineering-constitution.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/ui-ux-rules.md
• docs/standards/task-review-checklist.md
• docs/standards/task-catalog.md

Business and Architecture

• Relationship & Sales Workspace Blueprint
• BU-R.0 Implementation Report
• BU-R.0.1 Implementation Report
• BU-R.1 Capability Audit
• AR.1 Architecture Transition Plan
• AR.2 Epic & Technical Design
• AR.2 Workspace UI/UX Design Note

Existing Implementation

• EP.1.1 Activity Domain Foundation
• EP.1.2 Activity Integration & Legacy Follow-up Adapter
• Activity service and lifecycle transitions
• Activity timeline compatibility layer
• existing notification event foundation
• existing approval event publication
• audit-log foundation
• customer service
• lead service
• opportunity service
• quotation service
• approval service
• notification event service
• dashboard and report consumers

---

Scope

Part 1 — Canonical Business Event Contract

Introduce the canonical Business Event envelope.

Minimum contract:

export type BusinessEvent<TPayload = Record<string, unknown>> = {
  eventId: string;
  eventType: string;
  schemaVersion: number;

  organizationId: string;
  branchId?: string | null;

  entityType: string;
  entityId: string;

  primaryRecord: {
    type: string;
    id: string;
  };

  relatedRecords: Array<{
    type: string;
    id: string;
  }>;

  actorUserId: string | null;

  occurredAt: string;

  correlationId: string;
  causationId?: string | null;

  visibility: {
    productType?: string | null;
    pricingSensitive?: boolean;
    internalOnly?: boolean;
  };

  payload: TPayload;

  metadata: Record<string, unknown>;
};

The implementation may adjust naming to match existing repository conventions, but the same business information must remain represented.

Rules

• eventId must be globally unique.
• eventType must be registered.
• schemaVersion must be explicit.
• organizationId is mandatory.
• occurredAt must use a stable ISO timestamp.
• correlationId must support tracing related mutations.
• pricing-sensitive payloads must not bypass CRM authorization.
• payloads must not contain decrypted secrets or unsafe binary content.

---

Part 2 — Event Naming Standard

Freeze the official naming convention.

Preferred convention:

<entity>.<past-tense-action>

Examples:

activity.created
activity.assigned
activity.reassigned
activity.rescheduled
activity.started
activity.completed
activity.cancelled

lead.created
lead.assigned
lead.handoff-ready
lead.converted

opportunity.created
opportunity.reassigned
opportunity.expected-award-changed
opportunity.hot-project-flagged
opportunity.hot-project-cleared
opportunity.won
opportunity.lost
opportunity.reopened

quotation.created
quotation.revised
quotation.sent
quotation.pending-approval
quotation.approved
quotation.rejected
quotation.returned
quotation.cancelled

approval.requested
approval.step-approved
approval.step-rejected
approval.returned
approval.completed
approval.escalated

customer.created
customer.updated
customer.owner-changed

po.received

Rules

• use lowercase names
• use stable domain prefixes
• use past-tense business facts
• do not encode UI action names
• do not create synonyms for the same business event
• preserve existing production approval event names through aliases or compatibility mapping where required

---

Part 3 — Event Ownership Matrix

Define which domain owns each event family.

Minimum ownership:

Event Family	Owning Domain
activity.*	Activity
customer.*	Customer
contact.*	Customer / Contact
lead.*	Lead
opportunity.*	Opportunity
quotation.*	Quotation
approval.*	Approval
po.*	Opportunity outcome / PO integration

Frozen Rule

The following consumers do not own source-domain business events:

• Timeline
• Calendar
• Dashboard
• Reports
• Notification
• My Day
• Manager Workspace
• Executive Workspace
• Relationship Health
• Forecast projection

These components consume events and may emit only their own technical processing signals if required.

---

Part 4 — Event Registry

Create the official Business Event Registry.

Every registered event must define:

• event type
• owner
• schema version
• business meaning
• trigger condition
• payload contract
• allowed visibility metadata
• expected ordering
• known consumers
• compatibility aliases
• deprecation status

Recommended structure:

export type BusinessEventDefinition = {
  eventType: string;
  owner: string;
  schemaVersion: number;
  description: string;
  payloadSchema: unknown;
  consumers: string[];
  deprecated?: boolean;
  replacementEventType?: string;
};

Unknown or unregistered events must be handled explicitly according to the frozen error strategy.

---

Part 5 — Event Publisher Framework

Implement the publisher abstraction.

Minimum capability:

publish(event)
publishMany(events)

Responsibilities:

• validate event registration
• validate payload contract
• enrich event metadata
• propagate correlation and causation IDs
• perform structured logging
• invoke the configured dispatcher
• expose testing seams
• avoid duplicate publication during one service operation

Rules

• service-owned business logic publishes events
• Route Handlers stay thin
• publisher failures must follow a documented transaction and error strategy
• publishing must not silently report success if dispatch failed
• existing production mutation behavior must not be broken by optional consumers

---

Part 6 — Subscriber and Dispatcher Framework

Implement transport-independent subscriber and dispatcher contracts.

Minimum capability:

subscribe(eventType, handler)
unsubscribe(eventType, handler)
dispatch(event)

Initial implementation must be in-process.

Subscribers must:

• be independently registered
• declare the event types they consume
• be idempotent or use an idempotency guard
• not directly mutate unrelated source domains
• report processing failures through structured logging
• preserve subscriber isolation where practical

Unknown Event Strategy

Freeze behavior for:

• unregistered event
• registered event without subscribers
• subscriber exception
• invalid payload
• unsupported schema version

---

Part 7 — Initial Activity Event Publishing

Integrate the first production event publishers with Activity lifecycle operations.

Minimum events:

• activity.created
• activity.assigned
• activity.reassigned
• activity.started
• activity.rescheduled
• activity.completed
• activity.cancelled
• activity.deleted, only when deletion is a valid governed operation

Rules

• publish only after successful Activity state mutation
• include Activity owner, assignee, primary context, related references, schedule, priority, and outcome metadata as appropriate
• do not expose pricing-sensitive notes to unrestricted subscribers
• do not change existing Activity APIs
• do not publish events from legacy follow-up adapters in this task unless explicitly required for contract validation

Legacy follow-ups remain compatibility read sources during EP.1.3.

---

Part 8 — Existing Event Compatibility

Review current approval and notification event behavior.

Produce a compatibility mapping covering:

• existing event names
• current publisher
• current recipient resolution
• target Business Event equivalent
• whether aliasing is needed
• whether the current event should remain untouched temporarily

Frozen Rule

Do not break existing approval notifications while introducing the shared Business Event abstraction.

Adapter-first integration is preferred.

---

Part 9 — Projection Consumer Contracts

Define consumer contracts for future projections.

Do not implement the projections.

Minimum consumers:

• Timeline
• Calendar
• Dashboard
• Notification
• My Day
• Manager Workspace
• Executive Workspace
• Relationship Health
• Forecast

Recommended interface:

export interface BusinessEventConsumer {
  readonly consumerName: string;
  readonly supportedEventTypes: string[];

  handle(event: BusinessEvent): Promise<void>;
}

Clarification

Consumers may still use governed source queries to build complete read models.

Business events signal that something changed and provide projection context; they do not need to contain every source-field value.

---

Part 10 — Event Versioning Strategy

Freeze versioning rules.

Rules

• every event includes schemaVersion
• additive optional payload fields do not require a new event type
• incompatible semantic changes require a new schema version
• consumers must declare supported versions
• deprecated versions must have a transition period
• existing production event names must not be renamed without compatibility mapping

Produce:

• version-support policy
• deprecation workflow
• payload evolution examples
• consumer compatibility rules

---

Part 11 — Idempotency and Duplicate Handling

Define and implement foundational duplicate handling.

Minimum requirements:

• every event has a unique eventId
• subscribers can identify already-processed events
• duplicate dispatch must not duplicate projection effects
• event retries must remain safe

This task may use an in-memory idempotency strategy for tests and contracts.

Do not introduce a production projection checkpoint table unless separately approved.

---

Part 12 — Event Ordering

Freeze ordering expectations.

Rules

• global ordering across all domains is not guaranteed
• causal ordering within one business operation must be explicit
• related events use correlationId
• child events use causationId
• Event Sequence Matrix defines expected business order
• consumers must not rely on undocumented timing

---

Part 13 — Replay Contracts

Prepare replay interfaces without implementing a complete replay engine.

Define:

export type ReplayRequest = {
  organizationId: string;
  eventTypes?: string[];
  entityType?: string;
  entityId?: string;
  occurredFrom?: string;
  occurredTo?: string;
  dryRun?: boolean;
};

Define:

• replay request
• replay source abstraction
• ordering expectations
• idempotency expectations
• version compatibility
• security rules
• dry-run behavior

Constraint

No replay API route and no persistent event store are required in EP.1.3 unless separately approved.

The output is an implementation contract and readiness assessment.

---

Part 14 — Observability and Testing Foundation

Add integration points for:

• structured event logging
• correlation IDs
• causation IDs
• event type
• owner domain
• dispatch duration
• subscriber duration
• dispatch success/failure
• subscriber success/failure
• duplicate detection
• unsupported version handling

Testing must cover:

• valid publication
• invalid event rejection
• unregistered event behavior
• successful subscription
• multiple subscribers
• subscriber isolation
• duplicate dispatch
• idempotent consumer behavior
• ordering within a declared sequence
• unsupported schema version
• correlation propagation
• causation propagation

---

15. Event Sequence Matrix

Create and freeze the official Event Sequence Matrix.

The matrix defines the expected event order for governed business actions.

It prevents different services from publishing inconsistent event chains for the same business operation.

Minimum Matrix

Business Action	Owning Service	Required Event Sequence	Conditional Events	Notes
Create Activity	Activity Service	activity.created	activity.assigned when assignee differs from owner	Create event must occur first
Assign Existing Activity	Activity Service	activity.assigned or activity.reassigned	None	Do not publish both for one transition
Start Activity	Activity Service	activity.started	None	Only when lifecycle supports explicit start
Reschedule Activity	Activity Service	activity.rescheduled	reminder-related events in later epic	Activity remains source owner
Complete Activity	Activity Service	activity.completed	next-action suggestion in later automation epic	Completion event contains outcome summary metadata
Cancel Activity	Activity Service	activity.cancelled	None	Include cancellation reason where required
Create Lead	Lead Service	lead.created	assignment event if immediately assigned	Preserve lead ownership rules
Handoff Lead	Lead Service	lead.handoff-ready	lead.assigned when assignment changes	Must not imply opportunity creation until it succeeds
Convert Lead	Lead and Opportunity Services	lead.converted → opportunity.created	opportunity.reassigned if final owner differs	Use one correlation ID
Create Opportunity Directly	Opportunity Service	opportunity.created	assignment event if applicable	No fake Lead event
Change Expected Award Date	Opportunity Service	opportunity.expected-award-changed	Hot Project suggestion later	Include before/after dates safely
Flag Hot Project	Opportunity Service	opportunity.hot-project-flagged	None	Hot Project is not lifecycle status
Clear Hot Project	Opportunity Service	opportunity.hot-project-cleared	None	Preserve manual override metadata
Create Quotation	Quotation Service	quotation.created	None	Opportunity remains project owner
Create Revision	Quotation Service	quotation.revised	approval event later when submitted	Link revision chain
Submit Approval	Quotation / Approval Service	quotation.pending-approval → approval.requested	notification delivery in later consumer	Use one correlation ID
Approve Quotation	Approval Service	approval step events → approval.completed → quotation.approved	None	Document workflow only
Reject Quotation	Approval Service	approval rejection event → quotation.rejected	None	Does not directly mark opportunity lost
Send Quotation	Quotation Service	quotation.sent	follow-up suggestion later	Must occur after successful send/state mutation
Receive PO	Opportunity / PO Service	po.received → opportunity.won	downstream delivery milestone later	PO evidence governs won outcome
Mark Opportunity Lost	Opportunity Service	opportunity.lost	reminder cleanup by future consumer	Quotation status does not own outcome
Reopen Opportunity	Opportunity Service	opportunity.reopened	Hot Project recalculation later	Outcome must return to open state

Sequence Rules

• Sequence must represent completed business facts, not intended actions.
• All events from one business operation share the same correlationId.
• Each downstream event should identify the immediate triggering event through causationId.
• Events must not be published for mutations that fail or roll back.
• A required sequence must not be reordered by individual consumers.
• Conditional events must document their trigger.
• A source service must not publish events owned by another domain unless the operation is coordinated through an approved application service.
• Existing approval event order must be preserved or mapped explicitly.

Deliverables for Part 15

• Event Sequence Matrix
• sequence validation helper or test fixture
• correlation/causation examples
• coordinated-service transaction notes
• failure and partial-publication analysis
• compatibility mapping for current approval sequences

---

16. Event Consumer Matrix

Create and freeze the official Event Consumer Matrix.

The matrix defines which consumers may subscribe to each event family and what effect they are allowed to produce.

This matrix becomes the Single Source of Truth for future projection implementation.

Minimum Consumer Matrix

Consumer	Consumed Events	Intended Effect	May Mutate Source Domain?	Implementation Phase
Timeline	Activity, Lead, Opportunity, Quotation, Approval, Customer, PO events	build chronological business-readable entries	No	EP.1.4 / Timeline epic
Calendar	scheduled/rescheduled/cancelled Activity events, milestone changes, approval due events	update time-based projection	No	Calendar projection epic
Dashboard	opportunity outcome, forecast, Hot Project, activity workload, approval events	refresh KPI and operational aggregates	No	Dashboard projection epic
Notification	Activity assignment/due/overdue, approval, quotation, opportunity events	resolve recipients and deliver inbox/email notifications	No	Notification expansion epic
My Day	Activity schedule/lifecycle, approval blockers, quotation urgency, Hot Project gaps	update personal action queue	No	My Day epic
Manager Workspace	Activity workload, idle opportunity, Hot Project, approval, forecast events	update team control-tower signals	No	Manager Workspace epic
Executive Workspace	opportunity outcome, forecast, strategic customer, PO, revenue events	update strategic summaries	No	Executive Workspace epic
Relationship Health	customer interaction, activity completion, overdue work, opportunity outcome	recalculate relationship health signal	No	Relationship Health epic
Forecast	Expected Award Date, probability, process, Hot Project, outcome events	update forward-looking projections	No	Forecast enhancement epic
Audit Bridge	governed event metadata where required	correlate business events with audit evidence	No	Foundation enhancement
Future Automation	activity completion, overdue, quotation approval, expected-award changes	suggest or execute governed automation	Only through owning service commands	Future automation epic

Event-to-Consumer Mapping

At minimum, document consumers for:

• activity.created
• activity.assigned
• activity.reassigned
• activity.rescheduled
• activity.started
• activity.completed
• activity.cancelled
• lead.created
• lead.assigned
• lead.handoff-ready
• lead.converted
• opportunity.created
• opportunity.reassigned
• opportunity.expected-award-changed
• opportunity.hot-project-flagged
• opportunity.hot-project-cleared
• opportunity.won
• opportunity.lost
• opportunity.reopened
• quotation.created
• quotation.revised
• quotation.sent
• quotation.pending-approval
• quotation.approved
• quotation.rejected
• quotation.returned
• approval.requested
• approval.completed
• approval.escalated
• po.received

Consumer Rules

• Consumers must declare subscribed event types explicitly.
• Consumers must not subscribe to every event through an unrestricted wildcard in production code.
• Consumer effects must be idempotent.
• Consumers must not bypass the owning service to mutate source lifecycle state.
• Consumers requiring source details must re-query through governed services or security-aware read models.
• Consumer failures must not silently corrupt source transactions.
• Pricing-sensitive consumers must enforce quotation pricing visibility.
• Notification delivery state must not become business lifecycle state.
• Timeline and Calendar remain rebuildable projections.
• Dashboard and workspace consumers must not calculate conflicting definitions for the same KPI.
• Consumer registration must be testable and discoverable.

Deliverables for Part 16

• Event Consumer Matrix
• per-event consumer mapping
• consumer ownership catalog
• subscriber registration map
• idempotency requirement by consumer
• security and data-redaction requirements
• future implementation phase mapping
• unused-event and missing-consumer report

---

Deliverables

1. Business Event Platform

Transport-independent publisher, subscriber, registry, and dispatcher foundation.

2. Canonical Business Event Contract

Shared envelope and validation rules.

3. Business Event Registry

Official machine-readable event catalog.

4. Event Naming Standard

Stable naming conventions and compatibility rules.

5. Domain Event Ownership Matrix

Official event ownership by domain.

6. Publisher Framework

Service-layer publication abstraction.

7. Subscriber Framework

Independent, testable consumer registration and dispatch.

8. Initial Activity Event Publishers

Activity lifecycle events published through the new foundation.

9. Projection Consumer Contracts

Contracts for Timeline, Calendar, Dashboard, Notification, My Day, Manager, Executive, Forecast, and Relationship Health.

10. Event Versioning Strategy

Schema evolution and deprecation rules.

11. Replay Contracts

Replay interfaces and readiness documentation.

12. Event Testing Standards

Publisher, dispatcher, subscriber, ordering, duplicate, idempotency, and version tests.

13. Observability Integration Contracts

Structured logging, correlation, tracing, and metrics hooks.

14. Projection Readiness Report

Readiness assessment for all planned projection and workspace consumers.

15. Event Sequence Matrix

Official event ordering for governed business actions.

16. Event Consumer Matrix

Official event-to-consumer mapping and allowed consumer effects.

17. Existing Event Compatibility Report

Mapping for current approval and notification event behavior.

18. Business Event Catalog

Human-readable documentation for all registered events.

---

Constraints

Must preserve:

• Customer
• Contact
• Lead
• Opportunity
• Quotation
• Approval
• Activity
• existing follow-up APIs
• existing dashboard and report consumers
• existing notification behavior
• existing audit history
• current security boundaries
• current pricing visibility rules

Do not implement:

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

No UI changes are required.

No legacy follow-up migration.

No follow-up dual-write.

No dashboard/report source swap.

No breaking API changes.

---

Compatibility Strategy

The Business Event Foundation is additive.

Existing production events and consumers remain operational.

Activity lifecycle operations may begin publishing through the new abstraction, but existing API responses and business behavior must remain unchanged.

Existing approval notification events must remain compatible through one of these approved strategies:

• preserve current event name and register it
• map current event to canonical event contract
• publish a compatibility alias
• use an adapter at the dispatcher boundary

Do not delete or rename a live event without a dedicated migration and compatibility task.

---

Testing Requirements

Minimum tests:

Contract Tests

• valid canonical event
• missing required metadata
• invalid event type
• unsupported schema version
• unsafe payload rejection where applicable

Registry Tests

• register event
• duplicate event registration
• unknown event lookup
• deprecated event lookup
• compatibility alias resolution

Publisher Tests

• publish one event
• publish multiple events
• correlation propagation
• causation propagation
• metadata enrichment
• publish after successful service mutation

Dispatcher Tests

• no subscriber
• one subscriber
• multiple subscribers
• subscriber exception
• duplicate dispatch
• deterministic handler registration

Consumer Tests

• idempotent processing
• supported version
• unsupported version
• pricing-sensitive redaction boundary
• source-domain mutation prohibition

Sequence Tests

• Activity create sequence
• Lead conversion sequence
• Quotation approval sequence
• PO received / Opportunity won sequence
• failed mutation produces no event sequence
• shared correlation ID
• valid causation chain

---

Acceptance Criteria

• A single canonical Business Event contract exists.
• All registered events follow the canonical contract.
• Event names follow one governed naming standard.
• Event ownership is explicit and enforceable.
• Business services publish through one abstraction.
• Route Handlers do not publish domain events directly.
• An in-process dispatcher operates behind a transport-independent interface.
• Subscribers are independently registered and testable.
• Initial Activity lifecycle events are published successfully.
• Existing approval and notification behavior remains compatible.
• Event versioning and deprecation rules are documented.
• Duplicate handling and idempotency requirements are defined and tested.
• Replay contracts exist without requiring a persistent event store.
• Event Sequence Matrix covers the minimum governed business actions.
• Event Consumer Matrix maps the minimum events to their planned consumers.
• Consumers do not become source-domain lifecycle owners.
• No Timeline, Calendar, My Day, Dashboard, Notification, or Automation projection is implemented.
• Existing APIs, dashboard datasets, report datasets, follow-up behavior, and audit history remain unchanged.
• TypeScript, targeted lint, and event-foundation tests pass.

---

Success Criteria

ALLA OS has a production-ready, transport-independent Business Event Foundation.

Operational domains can publish governed business facts without coupling directly to downstream workspace or projection implementations.

Event ordering is standardized through the Event Sequence Matrix.

Future consumers and their allowed effects are standardized through the Event Consumer Matrix.

Timeline, Calendar, Dashboard, Notification, My Day, Manager Workspace, Executive Workspace, Relationship Health, Forecast, and Automation can proceed without redefining event contracts or domain ownership.

Ready for:

EP.1.4 – Projection Foundation