Reporter events

Reporter has 12 unique emitted business-event definitions. They are CloudEvents 1.0 binary-mode messages carried over RabbitMQ when STREAMING_ENABLED=true. Reporter does not publish these facts to Kafka. When streaming is off, manager and worker use a no-op emitter and do not start an outbox dispatcher.

Envelope and routing

Every event uses ce-source reporter, ce-schemaversion 1.0.0, and a source-qualified ce-type in the form studio.lerian.reporter.<resource>.<event>. The payload is JSON with snake_case keys.

Contract item	Value
Exchange	Value of `RABBITMQ_REPORT_EVENTS_EXCHANGE`
AMQP routing key	Definition key exactly, such as `report.finished`
Content type	`application/json`
Delivery mode	Persistent AMQP message
Subject	Template, report, or deadline ID
Tenant	Context tenant in `ce-tenantid` and `X-Tenant-ID`; single-tenant fallback when no tenant is present
Manifest	`GET /v1/streaming/events`

Use the shared envelope for the complete CloudEvents header contract.

Delivery semantics

Reporter emits after the business-state change has committed. Publication errors do not fail the underlying operation.

Important: direct publication, with durable outbox fallback when the broker circuit is open.
Critical: Reporter skips direct publication. It always persists the event to the durable outbox for dispatch and retry.
Both policies request on_routable_failure, but the current RabbitMQ routes define no explicit DLQ destination. The publisher sees a routable failure. No copy goes to a dead-letter route.
Broker delivery is at least once. Consumers must be idempotent and deduplicate with (ce-source, ce-id).

Emitted event catalog

Definition key	`ce-type`	Policy	Fires when
`template.created`	`studio.lerian.reporter.template.created`	Important	Template file and metadata are persisted.
`template.updated`	`studio.lerian.reporter.template.updated`	Important	A template update and any file replacement complete.
`template.deleted`	`studio.lerian.reporter.template.deleted`	Important	A template deletion completes; create rollback does not emit it.
`report.requested`	`studio.lerian.reporter.report.requested`	Important	The report is persisted as `Processing`, before manager attempts the worker command publish. It does not prove that the command was queued.
`report.finished`	`studio.lerian.reporter.report.finished`	Critical	The artifact is stored and the `Finished` status is committed.
`report.partial`	`studio.lerian.reporter.report.partial`	Critical	The artifact is stored and a partial terminal status is committed.
`report.errored`	`studio.lerian.reporter.report.errored`	Critical	Manager or worker commits an `Error` terminal status.
`deadline.created`	`studio.lerian.reporter.deadline.created`	Important	A deadline is persisted.
`deadline.updated`	`studio.lerian.reporter.deadline.updated`	Important	A deadline update is persisted and the updated record is loaded.
`deadline.deleted`	`studio.lerian.reporter.deadline.deleted`	Important	A deadline soft delete is persisted.
`deadline.delivered`	`studio.lerian.reporter.deadline.delivered`	Critical	The delivery mark is persisted.
`deadline.delivery_reverted`	`studio.lerian.reporter.deadline.delivery_reverted`	Critical	The delivery mark is removed.

Both manager and worker emit report.errored. All variants use deterministic ce-id reporter.report.error.<report_id>. A consumer deduplicating on (ce-source, ce-id) therefore keeps only the first report.errored received for a report_id. Critical deadline transitions use reporter.deadline.<event_type>.<deadline_id>.<timestamp>.

Complete `data` contracts

These TypeScript-style declarations mirror the JSON wire shape. ? means the property is optional. | null means the property is present but can be JSON null. Timestamps are RFC 3339 strings.

type RFC3339 = string
type UUID = string

type TemplateCreatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  file_name: string
  mapped_datasource_keys: string[]
  mapped_fields_count: number
  created_at: RFC3339
}

type TemplateUpdatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  updated_fields: string[]
  file_replaced: boolean
  updated_at: RFC3339
}

type TemplateDeletedDataV1 = {
  template_id: UUID
  hard_delete: boolean
  cascaded_deadlines_deleted: number
  deleted_at: RFC3339
}

type ReportRequestedDataV1 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  request_id: string
  filter_datasource_count: number
  template_description: string
}

type ReportFinishedDataV1 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  artifact_ttl?: string
  completed_at: RFC3339
  duration_ms: number
  section_count: number
}

type ReportPartialDataV1 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  section_failures: string[]
  completed_at: RFC3339
  duration_ms: number
  section_count: number
  failed_section_count: number
}

type ManagerReportErroredDataV1 = {
  report_id: UUID
  status: string
  error_code: "report_generation_failed"
  error_summary: "Report generation failed"
  completed_at: RFC3339
}

type WorkerTerminalReportErroredDataV1 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  error_code: "report_generation_failed"
  error_summary: "All report data sections failed"
  completed_at: RFC3339
  duration_ms: number
}

type WorkerFunnelReportErroredDataV1 = {
  report_id: UUID
  template_id?: UUID
  output_format?: string
  status: string
  error_code:
    | "report_generation_failed"
    | "report_generation_timeout"
    | "report_generation_canceled"
  error_summary: string
  completed_at: RFC3339
  duration_ms?: number
}

type ReportErroredDataV1 =
  | ManagerReportErroredDataV1
  | WorkerTerminalReportErroredDataV1
  | WorkerFunnelReportErroredDataV1

type DeadlineCreatedDataV1 = {
  deadline_id: UUID
  name: string
  type: string
  template_id: UUID | null
  template_name: string
  due_date: RFC3339
  frequency: string
  months_of_year: number[]
  active: boolean
  notify_days_before: number
  color: string
  status_snapshot: string
  created_at: RFC3339
}

type DeadlineUpdatedDataV1 = {
  deadline_id: UUID
  updated_fields: string[]
  template_id: UUID | null
  template_name: string
  due_date: RFC3339
  frequency: string
  months_of_year: number[]
  active: boolean
  status_snapshot: string
  updated_at: RFC3339
}

type DeadlineDeletedDataV1 = {
  deadline_id: UUID
  soft_delete: boolean
  deleted_at: RFC3339
}

type DeadlineDeliveredDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  template_name: string
  type: string
  due_date: RFC3339
  delivered_at: RFC3339 | null
  status_snapshot: string
  frequency: string
  next_occurrence: RFC3339 | null
  updated_at: RFC3339
}

type DeadlineDeliveryRevertedDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  template_name: string
  type: string
  due_date: RFC3339
  reverted_at: RFC3339
  previous_delivered_at: RFC3339 | null
  status_snapshot: string
  frequency: string
  updated_at: RFC3339
}

Separate internal command rail

Manager sends worker a non-CloudEvents JSON command on RabbitMQ. It uses RABBITMQ_EXCHANGE, RABBITMQ_GENERATE_REPORT_KEY, and RABBITMQ_GENERATE_REPORT_QUEUE, with persistent delivery. This command is not part of the public event catalog.

type FilterCondition = {
  eq?: unknown[] | null
  gt?: unknown[] | null
  gte?: unknown[] | null
  lt?: unknown[] | null
  lte?: unknown[] | null
  between?: unknown[] | null
  in?: unknown[] | null
  nin?: unknown[] | null
}

type GenerateReportMessage = {
  templateId: UUID
  reportId: UUID
  outputFormat: string
  filters: Record<string, Record<string, Record<string, FilterCondition>>> | null
  mappedFields: Record<string, Record<string, string[]>> | null
}

Inbound event status

Reporter consumes no public lib-streaming fact. Its Hub subscriber remains unavailable: enabling it is rejected at startup until a compatible downstream worker contract exists.

Getting started

Templates API

Template Builder API

Reports API

Deadlines API

Data Sources API

Metrics API

Streaming API

Error handling

Events

Reporter events

Envelope and routing

Delivery semantics

Emitted event catalog

Complete `data` contracts

Separate internal command rail

Inbound event status

​Envelope and routing

​Delivery semantics

​Emitted event catalog

​Complete data contracts

​Separate internal command rail

​Inbound event status

Envelope and routing

Delivery semantics

Emitted event catalog

Complete `data` contracts

Separate internal command rail

Inbound event status