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}