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
| Field | Meaning |
|---|---|
event_id | Stable notification identity for deduplication |
type | Versioned application event type |
producer | Publisher identity bound to verified signing evidence |
observed_at | Producer observation time, not a network delivery guarantee |
topic | Application-defined interest and routing label |
scope | Application replication and authorization context |
entity_ref | Optional durable record reference |
stream_ref | Optional advertised live stream reference |
payload | Bounded 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.
| Condition | Response |
|---|---|
Duplicate event_id | Suppress duplicate local action within the deduplication window |
| Stale observation | Apply the application's freshness policy before presentation |
| Event precedes state | Keep the observation and resolve context asynchronously |
Unavailable | Report 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 Revoked | Reject or stop affected delivery |
Canceled or Closed | Stop 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.