1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
//! Exposes Taskvisor's best-effort lifecycle stream for observability.
//!
//! The registry, task actors, controller, and shutdown workflow publish ordinary [`Event`] values to an internal bounded bus.
//! The runtime relay forwards retained events to the bounded queue of each [`Subscribe`](crate::Subscribe) implementation.
//! Internal subscriber diagnostics can start at the relay or a subscriber lane and bypass the shared bus.
//!
//! ```text
//! runtime components
//! │ Event
//! ▼
//! bounded Bus
//! │ retained events
//! ▼
//! event relay ──► subscriber queues ──► Subscribe callbacks
//!
//! internal diagnostics ──► event relay or subscriber lane ──► callbacks
//! ```
//!
//! # Choosing the right result path
//!
//! | Need | Use |
//! |---------------------------------------|------------------------------------------|
//! | Logs, metrics, alerts, or diagnostics | [`Subscribe`](crate::Subscribe) events |
//! | Final outcome for watched work | [`TaskWaiter`](crate::TaskWaiter) |
//! | Result of a management command | The management method's returned result |
//!
//! The stream is observational, not a reliable confirmation channel.
//! Bus overflow and subscriber queue pressure can drop events.
//! Missing an event does not mean the action did not happen, and runtime state never depends on delivery.
//!
//! [`EventKind`] identifies what happened. [`Event`] carries its metadata.
//! [`TaskOutcomeKind`](crate::TaskOutcomeKind), [`BackoffSource`], and [`RejectionKind`] provide
//! typed details for outcomes, backoff, and rejection events. Implement [`Subscribe`](crate::Subscribe)
//! for custom handling, or use the feature-gated `LogWriter` and `TracingBridge` subscribers for ready-made output.
//!
//! Important stream rules:
//!
//! - [`AttemptFailed`](EventKind::AttemptFailed) and [`AttemptTimedOut`](EventKind::AttemptTimedOut) describe one attempt. A later attempt may still run.
//! - [`TaskFinished`](EventKind::TaskFinished) carries the final outcome class. Registry cleanup then attempts [`TaskRemoved`](EventKind::TaskRemoved).
//! - Cancellation between attempts can reach `TaskFinished(Canceled)` without an [`AttemptCanceled`](EventKind::AttemptCanceled) event.
//! - [`Event::seq`] records process-local construction order. It is not a causal clock, and gaps are expected when events are dropped.
//! - [`Event::reason`] is diagnostic text. Use typed enums and their stable `as_label` methods for machine decisions and telemetry.
//! - Rejected work never enters the registry. It has no `TaskFinished` or `TaskRemoved` event.
pub use ;
pub use ;