Events

The event envelope, the microbatch a broadcast message carries, and every event type with its channel, stage and delivery class.

  • Availability: Planned
  • Evidence: Read from source
  • Reference

The event

JSON
{
  "id": "evt_9fK2mQ7x",
  "stream": { "organization": "team-42", "application": "app_Shop0001x", "job": "job_Prep0001x" },
  "sequence": 118,
  "type": "stage.progress",
  "time": "2026-09-19T10:15:02.250Z",
  "data": { "stage": "generate", "done": 41, "total": 96 }
}
Member Meaning
id Stable identity of the event. Use it to discard duplicates.
stream The scope of the event, and therefore its channel: organization always, application and job when they apply
sequence Monotonic and gap-free per channel, starting at 1
type One of the types below
time When the state change was committed
data Depends on the type. job.* events carry state; stage.* carry stage, done and total; module, cache.hit and retry.scheduled events carry module, and key or attempt where they apply.

Events and logs never carry credentials, tokens or another tenant's data.

The microbatch

One broadcast message carries a microbatch:

JSON
{ "protocol": "beyond-cdn-events/1", "channel": "job:job_Prep0001x", "events": [] }

Events keep their order inside a batch. Progress and log notifications are merged over a short interval to keep cost and fan-out bounded; a notifier splits a batch instead of exceeding the payload bound. Events of the immediate class are sent without waiting for the interval.

Every event is persisted with its sequence whatever its delivery class. Batching affects when you are notified, never what you can replay.

The pointer

Sometimes a notifier cannot or should not send an event. It then broadcasts a pointer instead, under its own broadcast event name, beyond-cdn-pointer/1:

JSON
{ "protocol": "beyond-cdn-events/1", "channel": "job:job_Prep0001x", "sequence": 131, "reason": "oversize" }
Member Meaning
protocol beyond-cdn-events/1. The pointer is an additive message of the events protocol; the broadcast event name and the absence of events tell it from a microbatch.
channel The channel it concerns
sequence The channel reached at least this sequence, and those events did not travel
reason oversize: the event cannot fit one message. stale: the notification waited longer than the notify age, so a backlog costs one pointer per channel instead of a flood.

A pointer is not an event type. It has no id, no type and no sequence of its own, it is never persisted, and a replay never returns it. Treat it as a gap up to sequence and replay from your cursor. A pointer at or below your cursor is ignored. Nothing is lost, because every event is persisted whatever happens to its notification.

Event types

Immediate events are never delayed, merged or dropped by a notifier. Batched events may be microbatched.

Jobs, queue and turns

Type Channels Delivery
job.queued, job.running, job.waiting_turn, job.succeeded, job.failed, job.cancelled, job.limit_exceeded job, application Immediate
queue.position job Batched
turn.started, turn.ended job Immediate
retry.scheduled job Immediate

Stages

Type Stage Channels Delivery
stage.started, stage.succeeded, stage.failed any job Immediate
stage.progress any job Batched
graph.pinned resolve job, application Immediate
graph.exception resolve job Immediate
package.fetched, package.reused prepare job Batched
package.failed prepare job Immediate
inventory.persisted analyze job, application Immediate
inventory.unknown analyze job Immediate
module.queued, module.started, module.generated, cache.hit generate job Batched
module.failed, module.limit_exceeded, diagnostics.reported generate job Immediate
closure.validated, closure.incomplete validate job, application Immediate

Releases, application and organization

Type Channels Delivery
release.ready, release.failed job, application Immediate
release.candidate, release.activated, release.retired application Immediate
application.changed application, organization Immediate
domain.changed, notice.update application Immediate
plan.changed, credit.granted organization Immediate
credit.reserved, credit.settled, credit.released organization Batched
usage.recorded job, organization Batched

Logs and control

Type Channels Delivery Meaning
log.batch job Batched Sanitized log lines: time, level, stage, message
access.revoked all Immediate Your access to the channel ended. See Revocation.
resync.required all Immediate Your position can no longer be trusted: load a snapshot. See Reconnect and replay.

Type names, states and codes are identifiers and are never translated. User-facing explanations of them are localized by the applications that show them.