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