Skip to main content

khive_runtime/daemon/
wire_frames.rs

1use serde::{Deserialize, Serialize};
2#[cfg(unix)]
3use tokio::io::{AsyncReadExt, AsyncWriteExt};
4
5#[cfg(doc)]
6use super::PROTOCOL_VERSION;
7use super::{ConnectionCapSnapshot, DaemonLifecycleSnapshot, RecallLedgerSnapshot};
8#[cfg(unix)]
9use super::{DAEMON_LEXICAL_TIMEOUT_MARKER, MAX_FRAME_BYTES};
10
11/// Request frame sent from a client to the daemon.
12#[derive(Serialize, Deserialize, Default)]
13pub struct DaemonRequestFrame {
14    pub ops: String,
15    /// Parse and inspect the catalog without dispatch, identity, or storage access.
16    #[serde(default)]
17    pub plan: bool,
18    #[serde(skip_serializing_if = "Option::is_none")]
19    pub presentation: Option<String>,
20    #[serde(skip_serializing_if = "Option::is_none")]
21    pub presentation_per_op: Option<Vec<Option<String>>>,
22    /// The client's resolved storage/gate default namespace for this request.
23    ///
24    /// As of protocol version 3 (ADR-096) the daemon serves the request under
25    /// this namespace instead of rejecting on mismatch: a per-request
26    /// identity input, not a same-process-identity assertion.
27    pub namespace: String,
28    /// The client's resolved write-stamp / gate actor identity (ADR-057),
29    /// carried on the frame so the warm daemon stamps writes with the
30    /// *caller's* actor instead of its own baked `actor_id` (ADR-096). `None`
31    /// mints `ActorRef::anonymous()`, matching an unconfigured actor.
32    #[serde(default)]
33    pub actor_id: Option<String>,
34    /// Opaque process provenance resolved in the originating client process.
35    /// It is carried per request because a shared warm daemon's environment
36    /// does not identify the worker that submitted the operation. Protocol v4
37    /// makes this field part of dispatch semantics: a v3 daemon must reject the
38    /// request rather than execute it while silently discarding provenance.
39    #[serde(default, skip_serializing_if = "Option::is_none")]
40    pub process_ref: Option<String>,
41    /// The client's resolved extra read-visibility namespaces (ADR-007 Rule
42    /// 3b), carried on the frame so the warm daemon widens read scope to
43    /// match the caller's own configuration rather than its own baked
44    /// `visible_namespaces` (ADR-096). A non-`local` `actor_id` joins default
45    /// reads where the registry mints the token (ADR-007 Rev 4 Rule 3b), so
46    /// an empty list still includes that actor in default reads. Explicit
47    /// `namespace=` operations remain scoped to exactly that namespace.
48    #[serde(default)]
49    pub visible_namespaces: Vec<String>,
50    /// Namespaces the client declared it owns (`[actor] owned_namespaces`,
51    /// ADR-021 Delta 1), carried with the caller's identity so the warm daemon
52    /// checks old-row namespaces against the caller's declaration rather than its
53    /// own. Omitted from the wire when empty. A daemon that predates the field
54    /// ignores it, so an owned row is refused there as `old-namespace`: a missing
55    /// declaration produces a refusal, never an admission. Purely additive:
56    /// `#[serde(default)]` with no `PROTOCOL_VERSION` bump.
57    #[serde(default, skip_serializing_if = "Vec::is_empty")]
58    pub owned_namespaces: Vec<String>,
59    /// Fingerprint of the client's engine-coherence config: packs, db target,
60    /// embedders, backend routing, and construction-baked outbound policy.
61    /// Identity fields are carried separately in this frame. The daemon rejects
62    /// requests whose configuration differs, except when its extra-embedder set
63    /// is a superset of the client's and every other field matches. See
64    /// ADR-027 / ADR-049 / ADR-096.
65    #[serde(default)]
66    pub config_id: String,
67    /// IPC protocol version sent by the client. Pre-versioning clients omit
68    /// this field (deserializes to 0). The daemon compares against
69    /// [`PROTOCOL_VERSION`] and rejects mismatches with an explicit error.
70    #[serde(default)]
71    pub protocol_version: u32,
72    /// When `true`, the daemon returns an identity frame (ok=true, result=None)
73    /// immediately after identity validation — without calling the dispatcher.
74    /// Used by the client's under-lock recovery probe to confirm a daemon is
75    /// alive and identity-matching without dispatching any mutating verb.
76    /// Pre-probe clients omit this field (deserializes to false → normal dispatch).
77    #[serde(default)]
78    pub probe_only: bool,
79    /// When `true`, the daemon returns a point-in-time [`MetricsSnapshot`] of
80    /// its server-side gauges (a read-only measurement surface for the
81    /// load/perf harness) instead of dispatching any op. Handled before the
82    /// `config_id` equality reject: a gauge read is process-global and
83    /// namespace/config-agnostic, not a namespaced record operation.
84    /// READ-ONLY — this field is the only input the frame accepts for a
85    /// metrics request; there is no reset or mutation reachable over the
86    /// wire. Pre-metrics clients omit this field (deserializes to `false` →
87    /// normal dispatch, unaffected).
88    #[serde(default)]
89    pub metrics_only: bool,
90    /// Output format for this request (ADR-078). Forwarded to the daemon's
91    /// serialization seam. `None` means use the daemon's resolved default.
92    #[serde(default)]
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub format: Option<String>,
95    /// Per-operation output format overrides (ADR-078).
96    #[serde(default)]
97    #[serde(skip_serializing_if = "Option::is_none")]
98    pub format_per_op: Option<Vec<Option<String>>>,
99    /// Whether this request originated from the agent-facing MCP `request`
100    /// tool (the wire surface). When `true`, the daemon rejects
101    /// `Visibility::Subhandler` verbs: agents must not invoke internal
102    /// subhandlers. When `false` (the default, and the only value any
103    /// operator path sends), subhandlers are allowed: `kkernel exec` and
104    /// other in-process callers are trusted operator surfaces.
105    ///
106    /// This is the origin discriminator, not a daemon-vs-local one: operator
107    /// requests flow through the daemon by default too, so the gate cannot
108    /// key on transport.
109    #[serde(default)]
110    pub from_wire: bool,
111    /// Request-group correlation id (khive#948), echoed back unchanged on
112    /// [`DaemonResponseFrame::request_id`] and stamped into the dispatch's
113    /// audit event (`resource.request_id`) so a benchmark harness can join
114    /// its own pre-send sample to the server-side audit row for the same
115    /// request. Agent-facing MCP requests always carry one: the bridge keeps a
116    /// caller-supplied value or mints an opaque nonzero value when absent.
117    /// Operator-built/probe frames may still use `None`. Purely additive —
118    /// `#[serde(default)]` matches `metrics_only`/`format`/`format_per_op`
119    /// precedent, with no `PROTOCOL_VERSION` bump.
120    #[serde(default)]
121    #[serde(skip_serializing_if = "Option::is_none")]
122    pub request_id: Option<u64>,
123}
124
125/// A dispatch failure whose domain outcome remains available to the transport.
126#[derive(Debug, Clone)]
127pub struct DaemonDispatchError {
128    pub message: String,
129    pub error_detail: serde_json::Value,
130}
131
132/// Per-field container limit, asserted equal to the request parser's bound by MCP.
133pub const ERROR_DETAIL_NESTING_DEPTH_LIMIT: usize = 64;
134
135/// Whether a JSON value fits the shared per-field container nesting limit.
136pub fn error_detail_value_within_limit(value: &serde_json::Value) -> bool {
137    let mut pending = vec![(value, 0_usize)];
138    while let Some((value, depth)) = pending.pop() {
139        match value {
140            serde_json::Value::Array(items) if depth < ERROR_DETAIL_NESTING_DEPTH_LIMIT => {
141                pending.extend(items.iter().map(|child| (child, depth + 1)));
142            }
143            serde_json::Value::Object(fields) if depth < ERROR_DETAIL_NESTING_DEPTH_LIMIT => {
144                pending.extend(fields.values().map(|child| (child, depth + 1)));
145            }
146            serde_json::Value::Array(_) | serde_json::Value::Object(_) => return false,
147            _ => {}
148        }
149    }
150    true
151}
152
153/// Discard an owned JSON value without recursing through nested containers.
154pub fn drop_error_detail_iteratively(value: serde_json::Value) {
155    let mut pending = vec![value];
156    while let Some(value) = pending.pop() {
157        match value {
158            serde_json::Value::Array(items) => pending.extend(items),
159            serde_json::Value::Object(fields) => pending.extend(fields.into_values()),
160            _ => {}
161        }
162    }
163}
164
165impl DaemonDispatchError {
166    /// Missing or unrecognized disposition from a legacy implementation is unknown.
167    pub fn new(message: impl Into<String>, error_detail: Option<serde_json::Value>) -> Self {
168        let message = message.into();
169        let mut fields = match error_detail {
170            Some(serde_json::Value::Object(fields)) => fields,
171            Some(data) => serde_json::Map::from_iter([("data".to_string(), data)]),
172            None => serde_json::Map::new(),
173        };
174        let disposition = match fields
175            .get("domain_disposition")
176            .and_then(serde_json::Value::as_str)
177        {
178            Some("committed") => crate::DomainDisposition::Committed,
179            Some("not_committed") => crate::DomainDisposition::NotCommitted,
180            _ => crate::DomainDisposition::Unknown,
181        };
182        if disposition != crate::DomainDisposition::Committed {
183            if let Some(result) = fields.remove("domain_result") {
184                drop_error_detail_iteratively(result);
185            }
186        }
187        let rejected: Vec<String> = fields
188            .iter()
189            .filter(|(_, value)| !error_detail_value_within_limit(value))
190            .map(|(name, _)| name.clone())
191            .collect();
192        let omitted_result = rejected.iter().any(|name| name == "domain_result");
193        let omitted_detail = !rejected.is_empty();
194        for name in rejected {
195            if let Some(value) = fields.remove(&name) {
196                drop_error_detail_iteratively(value);
197            }
198        }
199        let mut error_detail = serde_json::Value::Object(fields);
200        if error_detail["kind"].as_str().is_none() {
201            error_detail["kind"] = serde_json::json!("internal");
202        }
203        if error_detail["message"].as_str().is_none() {
204            error_detail["message"] = serde_json::json!(message);
205        }
206        error_detail["domain_disposition"] = serde_json::json!(disposition.as_str());
207        if omitted_detail {
208            error_detail["code"] = serde_json::json!(if omitted_result {
209                "result_too_deep"
210            } else {
211                "error_detail_too_deep"
212            });
213        }
214        Self {
215            message,
216            error_detail,
217        }
218    }
219}
220
221/// Response frame sent from the daemon back to a client.
222#[derive(Serialize, Deserialize, Debug)]
223pub struct DaemonResponseFrame {
224    pub ok: bool,
225    pub result: Option<String>,
226    pub error: Option<String>,
227    /// Additive failure metadata; legacy protocol-v4 peers still read `error` as text.
228    /// On a successful response, `{"lexical_timeout":true}` is a daemon-only
229    /// diagnostic that old clients ignore and new clients log locally.
230    #[serde(default, skip_serializing_if = "Option::is_none")]
231    pub error_detail: Option<serde_json::Value>,
232    pub namespace_mismatch: bool,
233    /// Set when the request's `config_id` does not match the daemon's. Like
234    /// `namespace_mismatch`, this signals the client to fall back to local
235    /// dispatch rather than execute under a different runtime/config.
236    #[serde(default)]
237    pub config_mismatch: bool,
238    /// The `config_id` the daemon dispatched under, echoed back so the client
239    /// can positively confirm the result came from a matching runtime. A
240    /// pre-`config_id` daemon omits this field (deserializes to `None`), which
241    /// the client treats as a mismatch and falls back to local dispatch — this
242    /// closes the upgrade window where a new restricted client could otherwise
243    /// trust a still-warm legacy daemon's broader registry.
244    #[serde(default)]
245    pub served_config_id: Option<String>,
246    /// Set when the client's `protocol_version` does not match the daemon's
247    /// [`PROTOCOL_VERSION`]. The client must treat this as a hard error and
248    /// surface the human-readable `error` field rather than falling back to
249    /// local dispatch (which would hide the version skew).
250    #[serde(default)]
251    pub version_mismatch: bool,
252    /// The daemon's [`PROTOCOL_VERSION`], echoed in error responses so the
253    /// client can include both sides in the diagnostic message. Pre-versioning
254    /// daemons omit this field (deserializes to 0).
255    #[serde(default)]
256    pub daemon_protocol_version: u32,
257    /// Populated when the request set `metrics_only: true`: a point-in-time
258    /// snapshot of the daemon's server-side gauges. `None` on every other
259    /// response, and on any response from a daemon that predates this field
260    /// (client-side back-compat via `#[serde(default)]`, matching
261    /// `served_config_id`'s upgrade-window handling above).
262    #[serde(default, skip_serializing_if = "Option::is_none")]
263    pub metrics: Option<MetricsSnapshot>,
264    /// Echo of the request's `request_id` (khive#948), present whenever the
265    /// frame that produced this response carried one — including on every
266    /// error/denied arm, not only success, so a client can join a failure
267    /// the same way it joins a success. `#[serde(default)]` so an older
268    /// daemon's response (predating this field) deserializes to `None`
269    /// rather than a parse error.
270    #[serde(default)]
271    pub request_id: Option<u64>,
272}
273
274/// Move the private dispatch signal out of the result before any client can
275/// observe it. Unmarked results retain their exact bytes. The marked result
276/// was serialized from a JSON Value by the MCP server, so reserializing after
277/// removal reproduces its public envelope. The marker's escaped frame cost
278/// equals `error_detail:{"lexical_timeout":true}`, keeping the server's exact
279/// frame-fit calculation valid after this move.
280#[cfg(unix)]
281pub(super) fn take_daemon_lexical_timeout_marker(
282    raw: String,
283) -> (String, Option<serde_json::Value>) {
284    if !raw.contains(DAEMON_LEXICAL_TIMEOUT_MARKER) {
285        return (raw, None);
286    }
287    let Ok(mut value) = serde_json::from_str::<serde_json::Value>(&raw) else {
288        return (raw, None);
289    };
290    let Some(fields) = value.as_object_mut() else {
291        return (raw, None);
292    };
293    if !fields
294        .get("results")
295        .is_some_and(serde_json::Value::is_array)
296    {
297        return (raw, None);
298    }
299    let Some(marker) = fields.remove(DAEMON_LEXICAL_TIMEOUT_MARKER) else {
300        return (raw, None);
301    };
302    let detail =
303        (marker.as_bool() == Some(true)).then(|| serde_json::json!({"lexical_timeout": true}));
304    (
305        serde_json::to_string(&value).expect("serde_json::Value is serializable"),
306        detail,
307    )
308}
309
310/// One checkpoint store in this daemon's fixed topology. IDs are process-local:
311/// `main` or `secondary:<index>` in dispatcher order. The basename is display-only,
312/// not an identity; no directory path is exposed. Restart/topology changes reset
313/// the interpretation of interval deltas.
314#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
315#[serde(default)]
316pub struct CheckpointStoreMetrics {
317    pub store_id: String,
318    pub role: String,
319    pub database: Option<String>,
320    #[serde(flatten)]
321    pub timing: khive_db::checkpoint::CheckpointTiming,
322}
323
324/// Point-in-time snapshot of the daemon's server-side gauges — the
325/// load/perf harness read-surface (measurement substrate, not a product feature).
326///
327/// Every field here is a **server-side** gauge reachable from `handle_conn`
328/// without any mutation: [`khive_storage::tx_registry`] (ADR-091 Plank 0,
329/// process-global singleton), the main pool's backend-keyed routine WAL
330/// sample and process TRUNCATE counters (`khive_db::checkpoint`), and the
331/// ADR-067 Component A write queue depth/latest writer-stage sample. There is
332/// no reset reachable through this type or through [`DaemonRequestFrame`] —
333/// gauges out, nothing in.
334#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
335pub struct MetricsSnapshot {
336    /// Launch mode and the current lifecycle of this daemon incarnation.
337    #[serde(default, skip_serializing_if = "Option::is_none")]
338    pub lifecycle: Option<DaemonLifecycleSnapshot>,
339    /// Last-observed WAL page count from the periodic checkpoint tick.
340    /// `None` when the checkpoint task has never ticked in this process
341    /// (for example, an in-memory dispatcher with no pool, or a daemon that
342    /// just started and hasn't hit its first tick yet).
343    pub wal_pages: Option<u64>,
344    /// Logical frames present in the WAL at the main backend's most recent
345    /// periodic PASSIVE checkpoint. Kept separate from physical allocation.
346    #[serde(default)]
347    pub wal_log_frames: Option<u64>,
348    /// Frames backfilled by that same periodic PASSIVE pass.
349    #[serde(default)]
350    pub wal_checkpointed_frames: Option<u64>,
351    /// Logical frames still pending after that pass (`log - checkpointed`).
352    #[serde(default)]
353    pub wal_pending_frames: Option<u64>,
354    /// Physical `-wal` sidecar bytes captured at the same routine tick.
355    #[serde(default)]
356    pub wal_physical_bytes: Option<u64>,
357    /// Wall-clock timestamp of the routine WAL sample, for staleness checks.
358    #[serde(default)]
359    pub wal_observed_at_unix_ms: Option<u64>,
360    /// Cumulative actual routine PASSIVE calls for each store this daemon
361    /// checkpoints. Microseconds preserve sub-millisecond costs; max is since
362    /// process start, not an interval maximum. Counters saturate rather than wrap.
363    #[serde(default)]
364    pub wal_checkpoint_stores: Vec<CheckpointStoreMetrics>,
365    /// Total WAL TRUNCATE escalation attempts (ADR-091 Plank 2) made in this
366    /// process's lifetime, regardless of whether they succeeded in reclaiming
367    /// pages.
368    pub wal_truncate_attempts: u64,
369    /// Current consecutive-failure count for TRUNCATE attempts that failed to
370    /// bring the WAL back below `warn_pages`; resets to 0 the next time an
371    /// attempt clears it.
372    pub wal_truncate_consecutive_failures: u64,
373    /// Total checkpoint ticks skipped because the dedicated checkpoint
374    /// connection was unavailable (ADR-091 checkpoint-pressure telemetry),
375    /// across this process's lifetime. `#[serde(default)]` so an older client
376    /// decoding a newer daemon's snapshot (or vice versa) does not fail.
377    #[serde(default)]
378    pub wal_checkpoint_skipped_ticks: u64,
379    /// Current consecutive-skip run length; 0 once the next tick is observed.
380    #[serde(default)]
381    pub wal_checkpoint_consecutive_skips: u64,
382    /// WAL page count last known at the time of the most recent skip, if any
383    /// skip has occurred yet in this process.
384    #[serde(default)]
385    pub wal_checkpoint_last_skip_wal_pages: Option<u64>,
386    /// Age, in microseconds, of the oldest currently-open transaction
387    /// registry entry (ADR-091 Plank 0). `None` when no transaction is
388    /// currently open.
389    pub oldest_pinned_tx_micros: Option<u64>,
390    /// Diagnostic label of the oldest currently-open transaction registry
391    /// entry, if any and if it was registered with one.
392    pub oldest_pinned_tx_label: Option<String>,
393    /// Number of currently open transaction registry entries.
394    pub open_tx_count: usize,
395    /// Current write-queue backlog depth (ADR-067 Component A): requests
396    /// enqueued but not yet accepted by the `WriterTask` drain loop. `None`
397    /// unless the write queue is enabled (`KHIVE_WRITE_QUEUE=1`) and a
398    /// file-backed pool is available.
399    pub write_queue_depth: Option<usize>,
400    /// The write queue's configured bounded capacity
401    /// (`PoolConfig::write_queue_capacity`), gated the same as
402    /// `write_queue_depth`.
403    pub write_queue_capacity: Option<usize>,
404    /// Latest completed writer-task span: bounded-channel admission/backlog.
405    #[serde(default)]
406    pub write_last_queue_wait_micros: Option<u64>,
407    /// Latest completed writer-task span: `BEGIN IMMEDIATE` acquisition.
408    #[serde(default)]
409    pub write_last_transaction_acquire_micros: Option<u64>,
410    /// Latest completed writer-task span: application transaction body.
411    #[serde(default)]
412    pub write_last_body_micros: Option<u64>,
413    /// Latest completed writer-task span: SQLite COMMIT/fsync phase.
414    #[serde(default)]
415    pub write_last_commit_micros: Option<u64>,
416    /// Whole latest writer-task request span, retained for compatibility and
417    /// comparison with the decomposed stages.
418    #[serde(default)]
419    pub write_last_total_micros: Option<u64>,
420    /// Wall-clock timestamp of the writer-stage sample.
421    #[serde(default)]
422    pub write_last_observed_at_unix_ms: Option<u64>,
423    /// Connection cap of the daemon socket this snapshot was served from.
424    /// `None` from a daemon that predates the cap and when no listener owns
425    /// the connection.
426    #[serde(default, skip_serializing_if = "Option::is_none")]
427    pub connections: Option<ConnectionCapSnapshot>,
428    /// Bounds and counts of the best-effort recall serve-ledger tasks.
429    /// `None` from a daemon that predates the bound.
430    #[serde(default, skip_serializing_if = "Option::is_none")]
431    pub recall_ledger: Option<RecallLedgerSnapshot>,
432}
433
434// ── framing ───────────────────────────────────────────────────────────────────
435
436/// Read one length-prefixed frame (4-byte BE u32 length + JSON bytes).
437#[cfg(unix)]
438pub async fn read_frame<R>(stream: &mut R) -> std::io::Result<Vec<u8>>
439where
440    R: tokio::io::AsyncRead + Unpin,
441{
442    let mut len_buf = [0u8; 4];
443    stream.read_exact(&mut len_buf).await?;
444    let len = u32::from_be_bytes(len_buf) as usize;
445    if len > MAX_FRAME_BYTES {
446        return Err(std::io::Error::new(
447            std::io::ErrorKind::InvalidData,
448            format!("daemon frame of {len} bytes exceeds {MAX_FRAME_BYTES} cap"),
449        ));
450    }
451    let mut buf = vec![0u8; len];
452    stream.read_exact(&mut buf).await?;
453    Ok(buf)
454}
455
456#[cfg(unix)]
457fn initial_frame_timeout_error() -> std::io::Error {
458    std::io::Error::new(
459        std::io::ErrorKind::TimedOut,
460        "daemon initial request frame read timed out",
461    )
462}
463
464#[cfg(unix)]
465pub(super) async fn read_initial_frame<R>(
466    stream: &mut R,
467    deadline: tokio::time::Instant,
468) -> std::io::Result<Vec<u8>>
469where
470    R: tokio::io::AsyncRead + Unpin,
471{
472    // Tokio polls the inner future before checking its timer. A frame already
473    // buffered when a delayed connection task first runs would otherwise pass
474    // even though its acceptance-time deadline has expired.
475    if tokio::time::Instant::now() >= deadline {
476        return Err(initial_frame_timeout_error());
477    }
478    let raw = tokio::time::timeout_at(deadline, read_frame(stream))
479        .await
480        .map_err(|_| initial_frame_timeout_error())??;
481    if tokio::time::Instant::now() >= deadline {
482        return Err(initial_frame_timeout_error());
483    }
484    Ok(raw)
485}
486
487/// Write one length-prefixed frame.
488#[cfg(unix)]
489pub async fn write_frame<W>(stream: &mut W, payload: &[u8]) -> std::io::Result<()>
490where
491    W: tokio::io::AsyncWrite + Unpin,
492{
493    if payload.len() > MAX_FRAME_BYTES {
494        return Err(std::io::Error::new(
495            std::io::ErrorKind::InvalidData,
496            format!(
497                "daemon frame of {} bytes exceeds {MAX_FRAME_BYTES} cap",
498                payload.len()
499            ),
500        ));
501    }
502    let len = (payload.len() as u32).to_be_bytes();
503    stream.write_all(&len).await?;
504    stream.write_all(payload).await?;
505    stream.flush().await?;
506    Ok(())
507}