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}