Skip to main content

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}