Reporter events

Reporter has 17 emitted business-event definitions. They are CloudEvents 1.0 binary-mode messages. Every event travels over RabbitMQ when STREAMING_ENABLED=true. When STREAMING_KAFKA_BROKERS is also set, the worker publishes report.finished and report.partial to Kafka as well. When streaming is off, Reporter publishes no events.

Envelope and routing

Every event uses ce-source reporter 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`
Kafka topic	`lerian.streaming.reporter`, for `report.finished` and `report.partial` only, when `STREAMING_KAFKA_BROKERS` is set
Content type	`application/json`
Delivery mode	Persistent AMQP message
Resource type	`template`, `report`, `deadline`, or `regulatory`
Subject	Template, report, or deadline ID. For `regulatory.version_adopted`, the regulatory document ID
Tenant	Context tenant in `ce-tenantid` and `X-Tenant-ID`; `default` in single-tenant mode
Manifest	`GET /v1/streaming/events`

Both copies carry the same ce-id. 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 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	Emitted by	Policy	Schema	Fires when
`template.created`	Manager	Important	`1.0.0`	Template file and metadata are persisted.
`template.updated`	Manager	Important	`1.0.0`	A template update and any file replacement complete, or a report-family assignment changes the template’s category.
`template.deleted`	Manager	Important	`1.0.0`	A template deletion completes; create rollback does not emit it.
`report.requested`	Manager	Important	`1.0.0`	A report created through `POST /v1/reports` or by the deadline trigger is persisted as `Processing`, before manager publishes the worker command. It does not prove that the command was queued. A regulatory filing request does not emit it.
`report.finished`	Worker	Critical	`2.0.0`	The artifact is stored and the `Finished` status is committed.
`report.partial`	Worker	Critical	`2.0.0`	The artifact is stored and the `Partial` status is committed.
`report.errored`	Manager and worker	Critical	`2.0.0`	An `Error` status is committed: the worker run failed, manager could not queue the command of a report created through `POST /v1/reports` or by the deadline trigger, or manager found that the worker stopped sending heartbeats.
`deadline.created`	Manager	Important	`1.0.0`	A deadline is persisted.
`deadline.updated`	Manager	Important	`1.0.0`	A deadline update is persisted and the updated record is loaded.
`deadline.deleted`	Manager	Important	`1.0.0`	A deadline soft delete is persisted.
`deadline.delivered`	Manager	Critical	`1.0.0`	The delivery mark is persisted.
`deadline.delivery_reverted`	Manager	Critical	`1.0.0`	The delivery mark is removed.
`deadline.due`	Manager	Critical	`1.0.0`	The deadline trigger announces an occurrence whose day arrived. Requires `DEADLINE_TRIGGER_ENABLED=true`.
`deadline.generation_failed`	Manager	Critical	`1.0.0`	The trigger announced an occurrence, and the report it had to generate for a category in `DEADLINE_TRIGGER_GENERATE_CATEGORIES` was refused or failed.
`regulatory.draft_ready`	Worker	Critical	`1.0.0`	A regulatory draft and its file are stored and ready for review. `template_id` is an empty string when a subscription generated the draft.
`regulatory.filing_approved`	Manager	Critical	`1.0.0`	A person approved a regulatory draft, and it is `Final`. Deliver the filing from this event.
`regulatory.version_adopted`	Manager	Critical	`1.0.0`	A subscription moves to another version of its regulatory document. Adopting the version already in force emits nothing.

A regulatory filing emits regulatory.draft_ready instead of report.finished. A failed filing run emits report.errored.

Event identifiers

Reporter sets a deterministic ce-id on these events:

Event	`ce-id`
`report.finished`, `report.partial`	`reporter.report.<status>.<report_id>`, with `finished` or `partial`
`report.errored`	`reporter.report.error.<report_id>`
`deadline.delivered`	`reporter.deadline.delivered.<deadline_id>.<delivered_at>`
`deadline.delivery_reverted`	`reporter.deadline.delivery_reverted.<deadline_id>.<reverted_at>`
`deadline.due`	`reporter.deadline.due.<deadline_id>.<occurrence_at>`
`deadline.generation_failed`	`reporter.deadline.generation_failed.<deadline_id>.<occurrence_at>`
`regulatory.draft_ready`	`<report_id>:draft:1`
`regulatory.filing_approved`	`<report_id>:approved`
`regulatory.version_adopted`	`<document_id>:<adopted_version>:<tenant_id>`

Every report.errored variant uses the same ce-id. A consumer deduplicating on (ce-source, ce-id) therefore keeps only the first report.errored received for a report_id. Template events, report.requested, and deadline create, update, and delete events carry a generated identifier.

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.

type RFC3339 = string
type UUID = string

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

type TemplateUpdatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  category: 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 ReportFinishedDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  document_type: string
  artifact_ttl?: string
  completed_at: RFC3339
  duration_ms: number
  section_count: number
}

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

type ManagerReportErroredDataV2 = {
  report_id: UUID
  status: string
  error_code: "report_generation_failed" | "report_worker_lost"
  error_summary: string
  completed_at: RFC3339
}

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

type WorkerFunnelReportErroredDataV2 = {
  report_id: UUID
  status: string
  error_code:
    | "report_generation_failed"
    | "report_generation_timeout"
    | "report_generation_canceled"
  error_summary: string
  document_type: string
  document_id: string
  document_version: string
  completed_at: RFC3339
}

type ReportErroredDataV2 =
  | ManagerReportErroredDataV2
  | WorkerTerminalReportErroredDataV2
  | WorkerFunnelReportErroredDataV2

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[] | null
  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[] | null
  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
}

type DeadlineDueDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  type: string
  category?: string
  due_date: RFC3339
  frequency: string
  occurrence_at: RFC3339
}

type DeadlineGenerationFailedDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  category?: string
  occurrence_at: RFC3339
  retryable: boolean
  reason:
    | "business_refusal"
    | "budget_exceeded"
    | "sweep_cancelled"
    | "transient"
    | "unknown"
  error_summary: string
  failed_at: RFC3339
}

type RegulatoryDraftReadyDataV1 = {
  report_id: UUID
  document_id: string
  document_version: string
  template_id: string
  output_format: string
  draft_version: number
  required_gaps_count: number
  requested_by: string
  generated_at: RFC3339
}

type RegulatoryFilingApprovedDataV1 = {
  report_id: UUID
  document_id: string
  document_version: string
  template_id: string
  output_format: string
  artifact_object_key: string
  artifact_sha256: string
  artifact_size_bytes: number
  draft_version: number
  delivery_attempt: number
  parameters: Record<string, string>
  corrections_count: number
  corrected_by: string
  corrected_at: string
  approved_by: string
  approved_at: RFC3339
}

type RegulatoryVersionAdoptedDataV1 = {
  document_id: string
  previous_version: string
  adopted_version: string
  adopted_by: string
  adopted_at: RFC3339
  binding_gaps_count: number
  mapping_broken: boolean
}

document_type carries the template category. It holds an empty string on the worker failure variant that carries no template_id. Treat an empty value as no category. document_id and document_version on report.errored name the regulatory document when a subscription generated the report, and are empty strings otherwise. artifact_object_key on report.finished, report.partial, and regulatory.filing_approved is the storage key of the file exactly as Reporter wrote it, and it is never empty. Use it as is. Do not rebuild it from other fields. On regulatory.filing_approved, verify the stored object against artifact_sha256 before you send it. parameters carries the generation parameters without the ones that start with system.. binding_gaps_count on regulatory.version_adopted counts the fields of the adopted version that the existing mapping leaves unmapped. The mapping_broken field is true when Reporter could not assess the existing mapping against the adopted version. In that case, binding_gaps_count is 0.

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, and its shape is not a public contract.

Inbound event status

Reporter consumes no public business event. Its Hub subscriber is unavailable: enabling it is rejected at startup.

Getting started

Templates API

Template Builder API

Reports API

Deadlines API

Data Sources API

Institutions API

Regulatory Catalog API

Regulatory Subscriptions API

Regulatory Bindings API

Regulatory Reports API

Metrics API

Streaming API

Error handling

Events

Reporter events

Envelope and routing

Delivery semantics

Emitted event catalog

Event identifiers

Complete `data` contracts

Separate internal command rail

Inbound event status

​Envelope and routing

​Delivery semantics

​Emitted event catalog

​Event identifiers

​Complete data contracts

​Separate internal command rail

​Inbound event status

Envelope and routing

Delivery semantics

Emitted event catalog

Event identifiers

Complete `data` contracts

Separate internal command rail

Inbound event status