arkhe_kernel/runtime/
event.rs

1//! `KernelEvent` and supporting enums.
2//!
3//! `#[non_exhaustive]` everywhere: external matchers cannot wildcard-match,
4//! so adding a variant is not breaking for external consumers. The
5//! `clippy::wildcard_enum_match_arm = deny` lint enforces this within
6//! the crate as well.
7
8use bitflags::bitflags;
9use bytes::Bytes;
10use serde::{Deserialize, Serialize};
11
12use crate::abi::{EntityId, InstanceId, RouteId, Tick, TypeCode};
13use crate::state::ScheduledActionId;
14
15/// Top-level kernel-emitted event. Routed through observer filters and
16/// recorded in WAL (chunks 3b/c+).
17#[derive(Debug, Clone, Serialize, Deserialize)]
18#[non_exhaustive]
19pub enum KernelEvent {
20    /// An action completed dispatch successfully.
21    ActionExecuted {
22        /// Instance where the action ran.
23        instance: InstanceId,
24        /// Type code of the executed action.
25        action_type: TypeCode,
26        /// Tick at which `step()` processed the action.
27        at: Tick,
28    },
29    /// Action `compute()` failed (panic or error). `reason` is opaque bytes.
30    ActionFailed {
31        /// Instance where the action was attempted.
32        instance: InstanceId,
33        /// Type code of the failing action.
34        action_type: TypeCode,
35        /// Opaque failure reason — kernel does not interpret.
36        reason: Bytes,
37    },
38    /// Effect application failed during dispatcher.
39    EffectFailed {
40        /// Instance where the effect was being applied.
41        instance: InstanceId,
42        /// Opaque failure reason (e.g. `b"budget_exceeded"` from
43        /// memory-budget enforcement).
44        reason: Bytes,
45    },
46    /// Observer panicked during `on_event`. Bounded payload —
47    /// `observer_index` only, no panic message (covert channel closed).
48    ObserverPanic {
49        /// Index of the panicking observer in the registry.
50        observer_index: u16,
51    },
52    /// First-panic eviction (A22).
53    ObserverEvicted {
54        /// Index of the evicted observer.
55        observer_index: u16,
56        /// Sequence number of the event that triggered the panic.
57        panic_at_seq: u64,
58        /// Panic count before eviction (always `1` under the
59        /// first-panic policy).
60        panic_count_before_eviction: u32,
61    },
62    /// Cross-instance signal dropped (reserved variant for the
63    /// `SendSignal` rate-limit (deferred); constructible today for tests).
64    SignalDropped {
65        /// Target instance the signal was destined for.
66        target: InstanceId,
67        /// Route discriminant.
68        route: RouteId,
69        /// Why the kernel dropped the signal.
70        reason: SignalDropReason,
71    },
72    /// Module force-unloaded via `force_unload` cap path.
73    ModuleForceUnloaded {
74        /// Route id whose `inflight_refs` were drained.
75        route_id: RouteId,
76        /// Sum of live refs that were dropped across instances.
77        live_refs_at_unload: u32,
78    },
79    /// Action deferred to the next tick (reserved variant).
80    ActionDeferredToNextTick {
81        /// Id of the deferred scheduled action.
82        action_id: ScheduledActionId,
83        /// Why the action was deferred.
84        reason: DeferReason,
85    },
86    /// `BestEffort` durability barrier flushed pending observer events.
87    ObserversFlushed {
88        /// Caller-supplied barrier ticket.
89        barrier_ticket: u64,
90        /// Number of events drained at this barrier.
91        event_count: u32,
92    },
93    /// Domain `Op::EmitEvent` produced an event payload.
94    DomainEventEmitted {
95        /// Instance that emitted the event.
96        instance: InstanceId,
97        /// Optional originating entity.
98        actor: Option<EntityId>,
99        /// Event type discriminant.
100        event_type_code: TypeCode,
101        /// Canonical bytes of the event payload.
102        bytes: Bytes,
103    },
104}
105
106/// Why a `SendSignal` op was dropped before delivery.
107#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
108#[non_exhaustive]
109pub enum SignalDropReason {
110    /// Target instance's IPC queue was full.
111    QueueFull,
112    /// Target instance does not exist (or has been despawned).
113    TargetNotFound,
114    /// Sender cancelled the signal before delivery.
115    Cancelled,
116}
117
118/// Why a scheduled action was deferred to the next tick.
119#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
120#[non_exhaustive]
121pub enum DeferReason {
122    /// Per-step scheduler dispatch budget was reached.
123    SchedulerBusy,
124    /// Per-instance resource budget would be exceeded by running this
125    /// action now.
126    BudgetExceeded,
127}
128
129/// Stable observer registration handle returned by `Kernel::register_observer`.
130#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
131#[serde(transparent)]
132pub struct ObserverHandle(
133    /// Monotonic registry index assigned at registration.
134    pub u16,
135);
136
137bitflags! {
138    /// Event-class filter for observer registration. One bit per
139    /// `KernelEvent` variant; an observer registered with a mask only
140    /// receives events whose variant bit is set. `EventMask::ALL`
141    /// (the `Default`) matches every variant — backward-compatible with
142    /// the unfiltered `Kernel::register_observer` path.
143    ///
144    /// Bit assignments are part of the public surface; new variants
145    /// must take the next free bit (no repurposing).
146    #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, serde::Serialize, serde::Deserialize)]
147    pub struct EventMask: u32 {
148        /// Match [`KernelEvent::ActionExecuted`].
149        const ACTION_EXECUTED       = 1 << 0;
150        /// Match [`KernelEvent::ActionFailed`].
151        const ACTION_FAILED         = 1 << 1;
152        /// Match [`KernelEvent::EffectFailed`].
153        const EFFECT_FAILED         = 1 << 2;
154        /// Match [`KernelEvent::ObserverPanic`].
155        const OBSERVER_PANIC        = 1 << 3;
156        /// Match [`KernelEvent::ObserverEvicted`].
157        const OBSERVER_EVICTED      = 1 << 4;
158        /// Match [`KernelEvent::SignalDropped`].
159        const SIGNAL_DROPPED        = 1 << 5;
160        /// Match [`KernelEvent::ModuleForceUnloaded`].
161        const MODULE_FORCE_UNLOADED = 1 << 6;
162        /// Match [`KernelEvent::ActionDeferredToNextTick`].
163        const ACTION_DEFERRED       = 1 << 7;
164        /// Match [`KernelEvent::ObserversFlushed`].
165        const OBSERVERS_FLUSHED     = 1 << 8;
166        /// Match [`KernelEvent::DomainEventEmitted`].
167        const DOMAIN_EVENT_EMITTED  = 1 << 9;
168        /// Match every variant — equivalent to `Default`.
169        const ALL                   = 0x3FF;
170    }
171}
172
173impl Default for EventMask {
174    fn default() -> Self {
175        Self::ALL
176    }
177}
178
179impl EventMask {
180    /// Whether this mask wants to be notified of `event`.
181    pub(crate) fn matches(&self, event: &KernelEvent) -> bool {
182        match event {
183            KernelEvent::ActionExecuted { .. } => self.contains(Self::ACTION_EXECUTED),
184            KernelEvent::ActionFailed { .. } => self.contains(Self::ACTION_FAILED),
185            KernelEvent::EffectFailed { .. } => self.contains(Self::EFFECT_FAILED),
186            KernelEvent::ObserverPanic { .. } => self.contains(Self::OBSERVER_PANIC),
187            KernelEvent::ObserverEvicted { .. } => self.contains(Self::OBSERVER_EVICTED),
188            KernelEvent::SignalDropped { .. } => self.contains(Self::SIGNAL_DROPPED),
189            KernelEvent::ModuleForceUnloaded { .. } => self.contains(Self::MODULE_FORCE_UNLOADED),
190            KernelEvent::ActionDeferredToNextTick { .. } => self.contains(Self::ACTION_DEFERRED),
191            KernelEvent::ObserversFlushed { .. } => self.contains(Self::OBSERVERS_FLUSHED),
192            KernelEvent::DomainEventEmitted { .. } => self.contains(Self::DOMAIN_EVENT_EMITTED),
193        }
194    }
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200
201    #[test]
202    fn kernel_event_all_variants_constructible() {
203        let inst = InstanceId::new(1).unwrap();
204        let route = RouteId(1);
205        let _ = KernelEvent::ActionExecuted {
206            instance: inst,
207            action_type: TypeCode(1),
208            at: Tick(0),
209        };
210        let _ = KernelEvent::ActionFailed {
211            instance: inst,
212            action_type: TypeCode(1),
213            reason: Bytes::from_static(b"r"),
214        };
215        let _ = KernelEvent::EffectFailed {
216            instance: inst,
217            reason: Bytes::new(),
218        };
219        let _ = KernelEvent::ObserverPanic { observer_index: 0 };
220        let _ = KernelEvent::ObserverEvicted {
221            observer_index: 0,
222            panic_at_seq: 1,
223            panic_count_before_eviction: 1,
224        };
225        let _ = KernelEvent::SignalDropped {
226            target: inst,
227            route,
228            reason: SignalDropReason::QueueFull,
229        };
230        let _ = KernelEvent::ModuleForceUnloaded {
231            route_id: route,
232            live_refs_at_unload: 0,
233        };
234        let _ = KernelEvent::ActionDeferredToNextTick {
235            action_id: ScheduledActionId::new(1).unwrap(),
236            reason: DeferReason::SchedulerBusy,
237        };
238        let _ = KernelEvent::ObserversFlushed {
239            barrier_ticket: 0,
240            event_count: 0,
241        };
242    }
243
244    #[test]
245    fn signal_drop_reason_copy_eq() {
246        let r1 = SignalDropReason::QueueFull;
247        let r2 = r1;
248        assert_eq!(r1, r2);
249        assert_ne!(r1, SignalDropReason::TargetNotFound);
250    }
251
252    #[test]
253    fn defer_reason_copy_distinct() {
254        let r1 = DeferReason::SchedulerBusy;
255        let r2 = DeferReason::BudgetExceeded;
256        assert_ne!(r1, r2);
257    }
258
259    #[test]
260    fn observer_handle_total_order() {
261        let h1 = ObserverHandle(1);
262        let h2 = ObserverHandle(2);
263        assert!(h1 < h2);
264        assert_eq!(h1, ObserverHandle(1));
265    }
266}
arkhe_kernel/runtime/event.rs

arkhe_kernel/runtime/
event.rs
