Data and primitivesEvents and notification delivery

Events and notification delivery

Publish bounded notifications independently of durable state synchronization.

Publish an event when a peer needs a bounded notification before saved context arrives. Event acceptance and remote delivery are separate outcomes.

Event envelope

FieldMeaning
event_idStable notification identity for deduplication
typeVersioned application event type
producerPublisher identity bound to verified signing evidence
observed_atProducer observation time, not a network delivery guarantee
topicApplication-defined interest and routing label
scopeApplication replication and authorization context
entity_refOptional durable record reference
stream_refOptional advertised live stream reference
payloadBounded application-defined event body

Your versioned application contract defines the event type, payload schema, and topic. The envelope does not prescribe JSON wire encoding. Keep large context in records or binary content. Events do not replace durable state or continuing telemetry.

Publish after a local save

Supply publication authority for the selected topic and scope, a bounded payload, and PublishOptions. An event announcing a saved record requires the local save to succeed first.

PublishResult returns event_id, local acceptance, and delivery. A locally accepted event does not confirm receipt by a remote consumer.

If the save fails, this workflow does not announce a saved record. If publication fails after the save, the record remains locally committed. Report both outcomes. Do not roll back valid local data to imply atomic network delivery.

Subscribe and keep the receiver available

events.subscribe(EventFilter, SubscriptionOptions) returns an EventSubscription. The filter selects event types, topics, producers, or scopes according to the contract. The options bound receiver capacity and lifetime.

Authenticate identity, check authority and freshness, and deduplicate by event_id within the configured retention window. Display the permitted initial payload. Schedule record resolution and stream subscription independently of event receipt.

Both entity_ref and stream_ref are optional. Resolve or subscribe only when the corresponding reference exists, using independent read authority. An event without stream_ref does not end a stream opened by an earlier event.

Delivery and failure behavior

Events do not promise universal replay, exactly-once delivery, or a fixed latency. A disconnected reader can miss live notifications. Recover current context through durable state, not by assuming every event reappears after reconnect.

ConditionResponse
Duplicate event_idSuppress duplicate local action within the deduplication window
Stale observationApply the application's freshness policy before presentation
Event precedes stateKeep the observation and resolve context asynchronously
UnavailableReport that the selected live path cannot deliver
CapacityExceeded from next()Report terminal receiver overflow once. Pending events were discarded. Later receives return Closed, not more events.
Unauthorized or RevokedReject or stop affected delivery
Canceled or ClosedStop using that subscription

latest admits a new event by discarding older queued events within capacity. reject-overflow rejects the overflowing event, discards pending events, and ends only that receiver. One terminal latch records CapacityExceeded; it is not an unbounded error queue.

The first terminal transition wins. Receiver cancellation first reports Canceled once, then Closed. An already pending overflow error survives later cancellation. Canceling one pending next() call does not cancel the subscription.

Call cancel() in cleanup, including after overflow. Cancellation is idempotent, stops delivery, and joins receiver resources. It affects only that consumer's subscription. It does not retract an event or delete the referenced record.

Streams defines descriptor and sample lifetimes.