cleveragents/cleveragents-core

Fork 3

feat(observability): implement Event System Domain Event Taxonomy (full EventType enum + DomainEvent model) #587

New issue

Closed

opened 2026-03-04 23:46:47 +00:00 by freemo · 2 comments

freemo commented

2026-03-04 23:46:47 +00:00

Owner

Metadata

Field	Value
Commit Message	`feat(observability): implement Event System Domain Event Taxonomy (full EventType enum + DomainEvent model)`
Branch	`feature/m6plus-event-system-domain-taxonomy`

Summary

Implement the full domain event taxonomy with the complete EventType enum (11 categories, 30+ event types) and the DomainEvent Pydantic model. This is the data model foundation for the EventBus (#473), audit logging auto-wiring, metrics collection, and real-time TUI updates.

Spec Reference

Section: Architecture > Observability > Event System
Lines: ~43655-43740

Current State

No EventType enum exists in the codebase.
No DomainEvent model exists.
The EventBus (#473) is tracked as an existing issue but the event taxonomy it needs is not defined.
Individual services have their own ad-hoc event/callback patterns but no unified event model.

Description

The spec defines a comprehensive event taxonomy:

EventType Enum (11 categories)

Plan lifecycle events:

plan.created, plan.phase_changed, plan.state_changed, plan.applied, plan.cancelled, plan.errored

Decision events:

decision.created, decision.approved, decision.corrected, decision.superseded

Invariant events:

invariant.reconciled, invariant.violated, invariant.enforced

Actor events:

actor.invoked, actor.completed, actor.errored, actor.escalated

Tool events:

tool.invoked, tool.completed, tool.errored, tool.retried

Resource events:

resource.accessed, resource.modified, resource.indexed

Sandbox events:

sandbox.created, sandbox.committed, sandbox.rolled_back, checkpoint.created, checkpoint.restored

Context events:

context.built, context.query_executed

Validation events:

validation.started, validation.passed, validation.failed

Session events:

session.created, session.message_sent

Cost events:

budget.warning, budget.exceeded

DomainEvent Model

class DomainEvent(BaseModel):
    event_type: EventType
    timestamp: datetime
    plan_id: str | None = None
    root_plan_id: str | None = None
    session_id: str | None = None
    actor_name: str | None = None
    project_name: str | None = None
    details: dict  # Event-type-specific payload

Two Event Channels

RxPY Reactive Stream: Real-time event stream for in-process subscribers (TUI updates, progress bars, streaming output)
Persistent Event Log: All events written to audit_log table for post-hoc analysis

Acceptance Criteria

EventType enum with all 30+ event types across 11 categories
DomainEvent Pydantic model with all fields from spec
Event correlation fields: plan_id, root_plan_id, session_id, actor_name, project_name
details dict typed per event type (at minimum documented, optionally with TypedDict subtypes)
EventBus Protocol with emit(event: DomainEvent) and subscribe(event_type: EventType, handler: Callable)
ReactiveEventBus implementation using RxPY Subject for fan-out distribution
stream property exposing raw rx.Observable for advanced RxPY operators
Persistent event log: all events written to audit_log on emit
Log correlation: every event within plan context includes plan_id, root_plan_id, phase, state
Unit tests for EventType enum completeness, DomainEvent serialization
Unit tests for ReactiveEventBus emit/subscribe/stream behavior

Prerequisite for: #473 (EventBus implementation), Audit Log Auto-Wiring, Metrics Collection
Used by: TUI real-time updates, CLI progress display
Parent epic: Observability

Suggested Milestone

v3.6.0

Priority

Medium

Suggested Assignee

@CoreRasurae — Async/event system/domain services

Subtasks

Code: Implement EventType enum with all 30+ event types across 11 categories (plan, decision, invariant, actor, tool, resource, sandbox, context, validation, session, cost)
Code: Implement DomainEvent Pydantic model with correlation fields (plan_id, root_plan_id, session_id, actor_name, project_name, details)
Code: Implement ReactiveEventBus using RxPY Subject for fan-out distribution with emit(), subscribe(), and stream property
Code: Implement persistent event log — all events written to audit_log table on emit
Docs: Document the full event taxonomy, DomainEvent model, and EventBus Protocol
Behave tests: Add BDD feature file features/observability/event_system_taxonomy.feature covering event emission, subscription, and persistence
Robot tests: Add Robot Framework integration test for ReactiveEventBus emit/subscribe/stream behavior
ASV benchmarks: Add ASV benchmark for event emission throughput and fan-out performance (benchmarks/bench_event_bus.py)
Quality: coverage >=97%: Verify via nox -s coverage_report
Quality: nox full suite: Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks below are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |-------|-------| | **Commit Message** | `feat(observability): implement Event System Domain Event Taxonomy (full EventType enum + DomainEvent model)` | | **Branch** | `feature/m6plus-event-system-domain-taxonomy` | ## Summary Implement the full domain event taxonomy with the complete `EventType` enum (11 categories, 30+ event types) and the `DomainEvent` Pydantic model. This is the data model foundation for the EventBus (#473), audit logging auto-wiring, metrics collection, and real-time TUI updates. ## Spec Reference **Section**: Architecture > Observability > Event System **Lines**: ~43655-43740 ## Current State - No `EventType` enum exists in the codebase. - No `DomainEvent` model exists. - The EventBus (#473) is tracked as an existing issue but the event taxonomy it needs is not defined. - Individual services have their own ad-hoc event/callback patterns but no unified event model. ## Description The spec defines a comprehensive event taxonomy: ### EventType Enum (11 categories) **Plan lifecycle events:** - `plan.created`, `plan.phase_changed`, `plan.state_changed`, `plan.applied`, `plan.cancelled`, `plan.errored` **Decision events:** - `decision.created`, `decision.approved`, `decision.corrected`, `decision.superseded` **Invariant events:** - `invariant.reconciled`, `invariant.violated`, `invariant.enforced` **Actor events:** - `actor.invoked`, `actor.completed`, `actor.errored`, `actor.escalated` **Tool events:** - `tool.invoked`, `tool.completed`, `tool.errored`, `tool.retried` **Resource events:** - `resource.accessed`, `resource.modified`, `resource.indexed` **Sandbox events:** - `sandbox.created`, `sandbox.committed`, `sandbox.rolled_back`, `checkpoint.created`, `checkpoint.restored` **Context events:** - `context.built`, `context.query_executed` **Validation events:** - `validation.started`, `validation.passed`, `validation.failed` **Session events:** - `session.created`, `session.message_sent` **Cost events:** - `budget.warning`, `budget.exceeded` ### DomainEvent Model ```python class DomainEvent(BaseModel): event_type: EventType timestamp: datetime plan_id: str | None = None root_plan_id: str | None = None session_id: str | None = None actor_name: str | None = None project_name: str | None = None details: dict # Event-type-specific payload ``` ### Two Event Channels 1. **RxPY Reactive Stream**: Real-time event stream for in-process subscribers (TUI updates, progress bars, streaming output) 2. **Persistent Event Log**: All events written to `audit_log` table for post-hoc analysis ## Acceptance Criteria - [x] `EventType` enum with all 30+ event types across 11 categories - [x] `DomainEvent` Pydantic model with all fields from spec - [x] Event correlation fields: `plan_id`, `root_plan_id`, `session_id`, `actor_name`, `project_name` - [x] `details` dict typed per event type (at minimum documented, optionally with TypedDict subtypes) - [x] `EventBus` Protocol with `emit(event: DomainEvent)` and `subscribe(event_type: EventType, handler: Callable)` - [x] `ReactiveEventBus` implementation using RxPY `Subject` for fan-out distribution - [x] `stream` property exposing raw `rx.Observable` for advanced RxPY operators - [x] Persistent event log: all events written to audit_log on emit - [x] Log correlation: every event within plan context includes plan_id, root_plan_id, phase, state - [x] Unit tests for EventType enum completeness, DomainEvent serialization - [x] Unit tests for ReactiveEventBus emit/subscribe/stream behavior ## Related Issues - **Prerequisite for**: #473 (EventBus implementation), Audit Log Auto-Wiring, Metrics Collection - Used by: TUI real-time updates, CLI progress display - Parent epic: Observability ## Suggested Milestone v3.6.0 ## Priority Medium ## Suggested Assignee @CoreRasurae — Async/event system/domain services ## Subtasks - [x] **Code**: Implement `EventType` enum with all 30+ event types across 11 categories (plan, decision, invariant, actor, tool, resource, sandbox, context, validation, session, cost) - [x] **Code**: Implement `DomainEvent` Pydantic model with correlation fields (`plan_id`, `root_plan_id`, `session_id`, `actor_name`, `project_name`, `details`) - [x] **Code**: Implement `ReactiveEventBus` using RxPY `Subject` for fan-out distribution with `emit()`, `subscribe()`, and `stream` property - [x] **Code**: Implement persistent event log — all events written to `audit_log` table on emit - [x] **Docs**: Document the full event taxonomy, DomainEvent model, and EventBus Protocol - [x] **Behave tests**: Add BDD feature file `features/observability/event_system_taxonomy.feature` covering event emission, subscription, and persistence - [x] **Robot tests**: Add Robot Framework integration test for ReactiveEventBus emit/subscribe/stream behavior - [x] **ASV benchmarks**: Add ASV benchmark for event emission throughput and fan-out performance (`benchmarks/bench_event_bus.py`) - [x] **Quality: coverage >=97%**: Verify via `nox -s coverage_report` - [x] **Quality: nox full suite**: Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks below are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

CoreRasurae was assigned by freemo

2026-03-05 00:30:28 +00:00

freemo added this to the v3.6.0 milestone