Events¶

Target Architecture — Final-State Design

This page describes the final-state event contracts of the Observability & Feedback Platform. All events use the canonical event envelope, are named in NounVerbPastTense, and are published on Azure Service Bus via MassTransit. Commands are VerbNoun.

Events are the spine of the Observability & Feedback Platform. The platform consumes telemetry events from the rest of the factory, emits domain events as it distils signals, and promotes the most important of those to integration events that cross platform boundaries — most notably into the Knowledge Platform to close the improvement loop.

Commands (`VerbNoun`)¶

Commands are imperative requests handled by exactly one aggregate; they are not part of the public event stream.

Command	Target Aggregate	Purpose
`RecordTrace`	`TraceRecord`	Project an ingested trace into a correlated record.
`AggregateMetric`	`MetricSeries`	Roll raw metrics into a series for a window.
`EvaluateAlertRule`	`AlertRule`	Evaluate a rule against current metrics.
`OpenIncident`	`Incident`	Open an incident from a trigger or breach.
`ResolveIncident`	`Incident`	Mark an incident resolved with root cause.
`CreateFeedbackItem`	`FeedbackItem`	Capture a feedback item from a signal/human/agent.
`ComputeQualityScore`	`QualityScore`	Recompute quality for a project/artifact.
`EvaluateSlo`	`SloDefinition`	Evaluate error budget and detect breach.
`DetectCostAnomaly`	`CostSignal`	Attribute cost and flag anomalies.
`CorrelateTelemetry`	`TelemetryCorrelation`	Stitch signals into one view by `traceId`.

Domain & Integration Events (`NounVerbPastTense`)¶

Event	Emitted by	Kind	Triggers / Consumers
`TraceRecorded`	TraceService	Domain → Integration	TelemetryCorrelationWorker; Knowledge Platform (lineage)
`MetricAggregated`	MetricAggregationService	Domain	AlertEvaluationWorker, SloService, DashboardService
`AlertTriggered`	AlertRuleService	Domain → Integration	IncidentAnalysisWorker; Control Plane
`SloBreached`	SloService	Domain → Integration	IncidentAnalysisWorker; Control Plane
`IncidentOpened`	IncidentService	Integration	Control Plane, Factory Studio, Knowledge Platform
`IncidentResolved`	IncidentService	Integration	FeedbackCreationWorker; Knowledge Platform
`FeedbackItemCreated`	FeedbackService	Integration	Knowledge Platform, QualityScoreWorker
`QualityScoreComputed`	QualityScoreService	Integration	Knowledge Platform, Factory Studio (QA Center)
`CostAnomalyDetected`	CostTelemetryService	Integration	FeedbackCreationWorker, Governance, Factory Studio (Cost Center)

Canonical Envelope¶

All events use the platform-wide envelope. Example for IncidentOpened:

{
  "eventId": "evt-3a1b9c4e-77d2-4e1a-9b6d-0f2a8c3d5e10",
  "eventType": "IncidentOpened",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40",
  "causationId": "evt-alert-trigger-id",
  "occurredAt": "2026-06-11T09:01:00Z",
  "payload": {
    "incidentId": "inc-5521",
    "severity": "high",
    "source": { "type": "alert", "alertRuleId": "alert-9a02" },
    "dimensions": {
      "executionId": "exec-771",
      "agentId": null,
      "skillId": null,
      "artifactId": "artifact-reservations-repo",
      "workflowId": "wf-runtime-monitor",
      "environment": "production",
      "version": "1.4.2"
    }
  }
}

The envelope carries the four identity fields (tenantId, projectId, moduleId, traceId) directly; the remaining required telemetry dimensions (executionId, agentId, skillId, artifactId, workflowId, environment, version) travel inside payload.dimensions and are mirrored to Service Bus application properties where needed for routing.

Event-Flow Diagram¶

flowchart LR
    Runtime["Runtime &amp; Agents"] -->|"OTLP"| Trace["TraceRecorded"]
    Trace --> Metric["MetricAggregated"]
    Metric --> Slo["SloBreached"]
    Metric --> Alert["AlertTriggered"]
    Slo --> IncOpen["IncidentOpened"]
    Alert --> IncOpen
    IncOpen --> IncResolve["IncidentResolved"]
    IncResolve --> Feedback["FeedbackItemCreated"]
    Trace --> Feedback
    Cost["CostAnomalyDetected"] --> Feedback
    Feedback --> Quality["QualityScoreComputed"]
    Feedback --> KP["Knowledge Platform"]
    Quality --> KP

Hold "Alt" / "Option" to enable pan & zoom

Azure Service Bus Topics¶

Events are published to per-context topics; subscriptions filter on cs-event-type and cs-tenant-id application properties.

Topic	Events	Primary Subscribers
`obs.tracing`	`TraceRecorded`	TelemetryCorrelationWorker, Knowledge Platform
`obs.metrics`	`MetricAggregated`, `SloBreached`	AlertEvaluationWorker, IncidentAnalysisWorker, Control Plane
`obs.alerts`	`AlertTriggered`	IncidentAnalysisWorker, Control Plane
`obs.incidents`	`IncidentOpened`, `IncidentResolved`	FeedbackCreationWorker, Knowledge Platform, Factory Studio
`obs.feedback`	`FeedbackItemCreated`	Knowledge Platform, QualityScoreWorker
`obs.quality`	`QualityScoreComputed`	Knowledge Platform, Factory Studio
`obs.cost`	`CostAnomalyDetected`	FeedbackCreationWorker, Governance, Factory Studio

Versioning & Consumer Rules¶

eventType names are stable; breaking changes create a new type or an additive, version-bumped payload.
Consumers deduplicate on eventId, tolerate unknown payload fields, and ignore-and-log unknown eventType values.
traceId and correlationId propagate into every consumer's OTEL spans and Serilog context.
Poison messages dead-letter with the full envelope preserved for replay.

See the canonical Event Envelope and Naming Conventions for the full contract.