khive_storage/usage.rs
1//! ADR-103 Amendment 2: dispatch-scoped executed-usage counters.
2//!
3//! A closed seven-counter vocabulary of work a dispatch actually executed,
4//! collected by a dispatch-accounting context armed around each verb dispatch
5//! and surfaced (a) as a per-op `usage` object in the response envelope and
6//! (b) as `resource.units` payload enrichment on the per-dispatch audit row.
7//!
8//! Propagation contract (Amendment 2 Part 2): the context is an Arc-shared
9//! accumulator carried in a task-local scope. Futures the dispatch awaits or
10//! `join!`s directly observe it automatically; a **request-owned spawned
11//! child** (a `tokio::spawn` whose `JoinHandle` is awaited before the
12//! response is produced) must capture the handle with [`current`] before the
13//! spawn and re-enter it with [`scope`] inside the child, because Tokio
14//! task-locals do not cross `tokio::spawn`. Detached background work receives
15//! no context and is attributed via phase-span events instead.
16//!
17//! Reporting is best-effort and can never fail a verb: every increment path
18//! is a no-op when no context is armed, and a dispatch whose counters cannot
19//! be trusted ships no `usage` object at all — never a partial one.
20//!
21//! **Issued vs returned.** Each counter's doc below says which it is, and the
22//! distinction decides where its increment goes relative to the `?` on the
23//! fallible call. An *issued* counter (`embed_calls`, `fts_passes`,
24//! `vector_passes`, `db_round_trips`) counts work handed to an engine or
25//! store, so it must be incremented whether or not the call resolved `Ok` —
26//! a request that ran real work and then failed reporting zero is the exact
27//! case a consumer of these numbers cannot afford. A *returned* counter
28//! (`graph_hops`, `ann_jobs_consumed`, `event_rows`) counts what came back,
29//! so a failed call legitimately contributes nothing. Increment an issued
30//! counter *after* the resource is resolved (so a lookup that never reached
31//! the engine counts nothing) and *before* the error propagates.
32
33use std::sync::atomic::{AtomicU64, Ordering};
34use std::sync::Arc;
35
36use serde_json::Value;
37
38/// One executed-work counter in the closed Amendment 2 vocabulary.
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum UsageUnit {
41 /// Issued. One text handed to one embedding engine (a batch of k texts
42 /// through one engine counts k, per engine).
43 EmbedCalls,
44 /// Issued. One FTS5 query execution.
45 FtsPasses,
46 /// Issued. One vector/ANN probe, per engine per query.
47 VectorPasses,
48 /// Returned. One adjacency entry returned by storage during
49 /// BFS/traversal, counted before visited-set de-duplication.
50 GraphHops,
51 /// Issued. One batched storage round-trip issued by the handler path.
52 DbRoundTrips,
53 /// Returned. One `ann_write_log` job drained by the inline warm-path
54 /// consumer.
55 AnnJobsConsumed,
56 /// Returned. One event-plane row successfully appended by this dispatch,
57 /// excluding the enclosing per-dispatch audit row (the snapshot is frozen
58 /// before that row is written; it cannot count itself).
59 EventRows,
60}
61
62#[derive(Debug, Default)]
63struct UsageInner {
64 frozen: std::sync::OnceLock<Value>,
65 embed_calls: AtomicU64,
66 fts_passes: AtomicU64,
67 vector_passes: AtomicU64,
68 graph_hops: AtomicU64,
69 db_round_trips: AtomicU64,
70 ann_jobs_consumed: AtomicU64,
71 event_rows: AtomicU64,
72}
73
74/// The Arc-shared dispatch-accounting context (Amendment 2 Part 2).
75#[derive(Debug, Clone, Default)]
76pub struct UsageContext {
77 inner: Arc<UsageInner>,
78}
79
80impl UsageContext {
81 pub fn new() -> Self {
82 Self::default()
83 }
84
85 /// Add `n` to one counter. Saturating: a counter never wraps.
86 pub fn add(&self, unit: UsageUnit, n: u64) {
87 let cell = match unit {
88 UsageUnit::EmbedCalls => &self.inner.embed_calls,
89 UsageUnit::FtsPasses => &self.inner.fts_passes,
90 UsageUnit::VectorPasses => &self.inner.vector_passes,
91 UsageUnit::GraphHops => &self.inner.graph_hops,
92 UsageUnit::DbRoundTrips => &self.inner.db_round_trips,
93 UsageUnit::AnnJobsConsumed => &self.inner.ann_jobs_consumed,
94 UsageUnit::EventRows => &self.inner.event_rows,
95 };
96 let mut cur = cell.load(Ordering::Relaxed);
97 loop {
98 let next = cur.saturating_add(n);
99 match cell.compare_exchange_weak(cur, next, Ordering::Relaxed, Ordering::Relaxed) {
100 Ok(_) => break,
101 Err(observed) => cur = observed,
102 }
103 }
104 }
105
106 /// Freeze the counters once, at the audit-snapshot point (Amendment 2
107 /// Part 3 ordering: after request-owned children are joined and non-audit
108 /// appends have resolved, before the enclosing audit row is written).
109 /// The first call takes the snapshot; every later call — including the
110 /// response-envelope read — returns the same frozen object, so both read
111 /// paths carry the identical value even if stray increments (e.g. the
112 /// post-audit dispatch hook) land afterwards.
113 pub fn freeze(&self) -> Value {
114 self.inner.frozen.get_or_init(|| self.snapshot()).clone()
115 }
116
117 /// The frozen object if [`Self::freeze`] ran, else a live snapshot.
118 pub fn frozen_or_snapshot(&self) -> Value {
119 match self.inner.frozen.get() {
120 Some(v) => v.clone(),
121 None => self.snapshot(),
122 }
123 }
124
125 /// Freeze the counters into the wire `usage` object. Zero-valued counters
126 /// are omitted; a fully zero snapshot still returns an (empty) object —
127 /// "measured, nothing counted" is distinct from "not measured", which is
128 /// represented by the absence of the object entirely.
129 pub fn snapshot(&self) -> Value {
130 let mut map = serde_json::Map::new();
131 let mut put = |key: &str, cell: &AtomicU64| {
132 let v = cell.load(Ordering::Relaxed);
133 if v > 0 {
134 map.insert(key.to_string(), Value::from(v));
135 }
136 };
137 put("embed_calls", &self.inner.embed_calls);
138 put("fts_passes", &self.inner.fts_passes);
139 put("vector_passes", &self.inner.vector_passes);
140 put("graph_hops", &self.inner.graph_hops);
141 put("db_round_trips", &self.inner.db_round_trips);
142 put("ann_jobs_consumed", &self.inner.ann_jobs_consumed);
143 put("event_rows", &self.inner.event_rows);
144 Value::Object(map)
145 }
146}
147
148tokio::task_local! {
149 static CURRENT: UsageContext;
150}
151
152/// Run `fut` with `ctx` armed as the current dispatch-accounting context.
153pub async fn scope<F: std::future::Future>(ctx: UsageContext, fut: F) -> F::Output {
154 CURRENT.scope(ctx, fut).await
155}
156
157/// The currently armed context, if any. Request-owned spawned children
158/// capture this before `tokio::spawn` and re-enter it with [`scope`] inside
159/// the child; every other caller should prefer [`count`].
160pub fn current() -> Option<UsageContext> {
161 CURRENT.try_with(Clone::clone).ok()
162}
163
164/// Add `n` to one counter of the currently armed context. No-op when no
165/// context is armed (background work, tests, un-instrumented entry points) —
166/// reporting can never fail or perturb the verb itself.
167pub fn count(unit: UsageUnit, n: u64) {
168 if n == 0 {
169 return;
170 }
171 if let Ok(ctx) = CURRENT.try_with(Clone::clone) {
172 ctx.add(unit, n);
173 }
174}
175
176#[cfg(test)]
177mod tests {
178 use super::*;
179
180 #[tokio::test]
181 async fn count_is_noop_without_scope_and_counts_inside() {
182 count(UsageUnit::EmbedCalls, 3);
183 let ctx = UsageContext::new();
184 scope(ctx.clone(), async {
185 count(UsageUnit::EmbedCalls, 2);
186 count(UsageUnit::FtsPasses, 1);
187 count(UsageUnit::GraphHops, 0);
188 })
189 .await;
190 let snap = ctx.snapshot();
191 assert_eq!(snap["embed_calls"], 2);
192 assert_eq!(snap["fts_passes"], 1);
193 assert!(
194 snap.get("graph_hops").is_none(),
195 "zero counters are omitted"
196 );
197 }
198
199 #[tokio::test]
200 async fn joined_spawned_child_counts_via_explicit_handle() {
201 let ctx = UsageContext::new();
202 scope(ctx.clone(), async {
203 let handle = current().expect("scope armed");
204 let child = tokio::spawn(scope(handle, async {
205 count(UsageUnit::VectorPasses, 2);
206 }));
207 child.await.expect("join child");
208 })
209 .await;
210 assert_eq!(ctx.snapshot()["vector_passes"], 2);
211 }
212
213 #[tokio::test]
214 async fn detached_spawn_without_handle_contributes_nothing() {
215 let ctx = UsageContext::new();
216 scope(ctx.clone(), async {
217 // A detached task spawned WITHOUT re-entering the scope: its
218 // counts must not reach the dispatch context.
219 let orphan = tokio::spawn(async {
220 count(UsageUnit::EmbedCalls, 99);
221 });
222 orphan.await.expect("join orphan");
223 })
224 .await;
225 assert_eq!(
226 ctx.snapshot(),
227 serde_json::json!({}),
228 "task-locals do not cross tokio::spawn; only an explicit handle propagates"
229 );
230 }
231
232 #[test]
233 fn saturating_add_never_wraps() {
234 let ctx = UsageContext::new();
235 ctx.add(UsageUnit::EventRows, u64::MAX);
236 ctx.add(UsageUnit::EventRows, 5);
237 assert_eq!(ctx.snapshot()["event_rows"], u64::MAX);
238 }
239}