Skip to main content

khive_runtime/
events_split.rs

1//! Events-daemon split (ADR-170): the audit lane leaves the domain store.
2//!
3//! The ADR-133 idempotent audit batch is the measured bulk of event write
4//! volume, and in a single-store deployment its rows queue on the same SQLite
5//! writer lane as domain mutations. This module moves that lane into a
6//! dedicated events daemon that owns the events database, reachable over a
7//! Unix socket with the same length-prefixed framing and peer-uid admission the
8//! main daemon socket uses. Plain event appends stay on the domain store —
9//! the legacy `events` table has raw-SQL consumers (schedule provenance, kg
10//! projection guards, graph-query substrate unions) whose correctness
11//! depends on finding those rows there.
12//!
13//! Cooperating pieces:
14//!
15//! - [`run_events_daemon`] — the server loop the `events-daemon` subcommand
16//!   runs: binds the events socket, owns the only resident writer of the
17//!   events database, and serves append/read requests through the ordinary
18//!   `SqlEventStore`.
19//! - [`EventsSplitClient`] — one per domain process. Plain appends ride a
20//!   bounded in-memory queue drained by a background forwarder
21//!   (fire-and-forget; overflow or a dead daemon drops the batch, counts it,
22//!   and logs — the loss-tolerant durability class made concrete; unused by
23//!   the default routing until telemetry producers opt in). Idempotent
24//!   audit-batch appends and reads are synchronous framed round-trips with
25//!   bounded timeouts, because their callers are background flushers or query
26//!   paths, never the dispatch hot path.
27//! - [`ForwardingEventStore`] — the lane-side [`khive_storage::EventStore`] over the socket.
28//!   Preflight validation delegates to an in-memory `SqlEventStore`, so the
29//!   ADR-133 audit-batch seam keeps its pre-enqueue shape check without any
30//!   I/O on the dispatch path.
31//! - [`SplitEventStore`] — the per-namespace handle
32//!   [`crate::runtime::KhiveRuntime::events`] returns when the split is
33//!   configured: routes the idempotent lane to the events store, plain
34//!   appends to the legacy store, and merges reads across both.
35//!
36//! Domain availability never depends on events-daemon liveness: every failure
37//! path here degrades (drop + count + log, or a typed storage error for the
38//! synchronous lanes) instead of blocking the caller.
39
40#[path = "events_count_read_budget.rs"]
41mod events_count_read_budget;
42#[doc(hidden)]
43pub use events_count_read_budget::WireReadFailure;
44
45#[cfg(unix)]
46mod events_daemon;
47mod file_hardening;
48#[cfg(unix)]
49mod forwarder;
50mod paths;
51mod protocol;
52mod registry;
53#[cfg(unix)]
54mod server;
55mod stores;
56
57#[cfg(unix)]
58pub use events_daemon::{
59    events_readiness, events_readiness_window, run_events_daemon, run_events_daemon_with_policies,
60    supervise_events_daemon, supervise_events_daemon_with_policies,
61    supervise_events_daemon_with_readiness, try_acquire_events_daemon_guard, EventsDaemonGuard,
62    EventsNotReady, EventsNotReadyReason, EventsReadiness, EventsReadinessSignal,
63    EVENTS_READINESS_WINDOW,
64};
65#[cfg(unix)]
66pub use forwarder::{EventsForwardingMetrics, EventsSplitClient};
67#[cfg(unix)]
68use paths::absolutize;
69pub use paths::{
70    events_db_path_beside, events_socket_path_beside, EVENTS_PROTOCOL_VERSION,
71    MAX_QUERY_EVENTS_PAGE_ROWS,
72};
73#[cfg(unix)]
74pub use paths::{DEFAULT_APPEND_QUEUE_BATCHES, DEFAULT_APPEND_QUEUE_BYTES};
75pub use protocol::{EventsRequest, EventsResponse, WireWriterTaskFailure, WireWriterTaskState};
76pub(crate) use registry::direct_backend_with_policies;
77#[cfg(any(test, feature = "test-internals"))]
78#[doc(hidden)]
79pub use registry::TestRegistryGuard;
80#[cfg(unix)]
81pub use registry::{client_for, forwarding_metrics};
82pub use registry::{direct_backend_for, direct_backend_read_only_for, EventsSplitConfig};
83#[cfg(unix)]
84use server::storage_error_response;
85#[cfg(unix)]
86pub use stores::ForwardingEventStore;
87pub use stores::SplitEventStore;
88
89#[cfg(unix)]
90#[path = "events_split_socket_path.rs"]
91pub(crate) mod socket_path;
92#[cfg(unix)]
93pub use socket_path::validate_events_socket_path;
94
95#[cfg(unix)]
96#[path = "events_split_policy_entries.rs"]
97mod policy_entries;
98#[cfg(unix)]
99pub use policy_entries::{
100    run_events_daemon_with_wal_ceiling, supervise_events_daemon_with_wal_ceiling,
101};
102
103#[cfg(all(test, unix))]
104#[path = "events_wal_policy_tests.rs"]
105mod wal_policy_tests;
106
107#[cfg(all(test, unix))]
108#[path = "events_count_read_budget_tests.rs"]
109mod count_read_budget_tests;
110
111#[cfg(all(test, unix))]
112#[path = "events_split_sqlite_full_tests.rs"]
113mod sqlite_full_tests;
114
115#[cfg(test)]
116mod tests;