@anvailabs/sandhi 0.5.0

package/src/lib.rs

@@ -0,0 +1,834 @@
+//! Sandhi Node binding (napi-rs), published as `@anvailabs/sandhi`.
+//!
+//! `ProviderRuntime` exposes persistent typed chat-contract handles; provider-native request and
+//! response JSON never crosses the binding. The same module exposes metering and budget APIs.
+
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use sandhi_core::{
+    parse_anthropic_usage, parse_bedrock_usage, parse_cohere_usage, parse_gemini_usage,
+    parse_ollama_usage, parse_openai_responses_usage, parse_openai_usage, Backend, Budget,
+    BudgetLedger, Dimension, KeyStore, ParsedUsage, UsageAggregateV1, UsageAggregator, UsageEvent,
+    VirtualKey,
+};
+use sandhi_providers::{
+    AnthropicAuthScheme, GeminiAuthScheme, ProviderError, ProviderFamily, ProviderHandle,
+    ProviderRuntime as RustProviderRuntime,
+};
+
+fn parse_anthropic_auth_scheme(value: Option<&str>) -> Result<AnthropicAuthScheme> {
+    match value.map(str::trim).map(str::to_ascii_lowercase).as_deref() {
+        None | Some("") | Some("api_key") => Ok(AnthropicAuthScheme::ApiKey),
+        Some("bearer") => Ok(AnthropicAuthScheme::Bearer),
+        Some(other) => Err(Error::from_reason(format!(
+            "unsupported Anthropic auth_scheme {other:?}; expected 'api_key' or 'bearer'"
+        ))),
+    }
+}
+
+fn parse_gemini_auth_scheme(value: Option<&str>) -> Result<GeminiAuthScheme> {
+    match value.map(str::trim).map(str::to_ascii_lowercase).as_deref() {
+        None | Some("") | Some("api_key") => Ok(GeminiAuthScheme::ApiKey),
+        Some("bearer") => Ok(GeminiAuthScheme::Bearer),
+        Some(other) => Err(Error::from_reason(format!(
+            "unsupported Gemini auth_scheme {other:?}; expected 'api_key' or 'bearer'"
+        ))),
+    }
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum OpenAiProtocol {
+    ChatCompletions,
+    Responses,
+    ChatGptResponses,
+}
+
+fn parse_openai_protocol(value: Option<&str>) -> Result<OpenAiProtocol> {
+    match value.map(str::trim).map(str::to_ascii_lowercase).as_deref() {
+        None | Some("") | Some("chat_completions") | Some("openai_chat_completions") => {
+            Ok(OpenAiProtocol::ChatCompletions)
+        }
+        Some("responses") | Some("openai_responses") => Ok(OpenAiProtocol::Responses),
+        Some("chatgpt_responses") | Some("codex_responses") => {
+            Ok(OpenAiProtocol::ChatGptResponses)
+        }
+        Some(other) => Err(Error::from_reason(format!(
+            "unsupported protocol {other:?}; expected 'chat_completions', 'responses', or 'chatgpt_responses'"
+        ))),
+    }
+}
+
+fn parse_chat_request(request_json: &str) -> Result<sandhi_core::ChatRequestV1> {
+    let request: sandhi_core::ChatRequestV1 = serde_json::from_str(request_json)
+        .map_err(|e| Error::from_reason(format!("invalid ChatRequestV1 JSON: {e}")))?;
+    request
+        .validate()
+        .map_err(|e| Error::from_reason(format!("invalid ChatRequestV1: {e}")))?;
+    Ok(request)
+}
+
+fn typed_provider_error(error: ProviderError, provider: &str) -> Error {
+    let typed = error.as_typed(Some(provider));
+    Error::from_reason(serde_json::to_string(&typed).unwrap_or_else(|_| error.to_string()))
+}
+
+/// Persistent factory for typed provider handles. The HTTP pool, retry policy, and circuit
+/// breaker belong to each returned handle rather than being rebuilt for every request.
+#[napi(js_name = "ProviderRuntime")]
+pub struct JsProviderRuntime {
+    inner: RustProviderRuntime,
+}
+
+impl Default for JsProviderRuntime {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[napi]
+impl JsProviderRuntime {
+    #[napi(constructor)]
+    pub fn new() -> Self {
+        Self {
+            inner: RustProviderRuntime::new(),
+        }
+    }
+
+    #[napi]
+    #[allow(clippy::too_many_arguments)]
+    pub fn openai_compat(
+        &self,
+        provider: String,
+        base_url: String,
+        api_key: String,
+        headers_json: Option<String>,
+        max_retries: Option<u32>,
+        timeout_secs: Option<f64>,
+        stream_idle_timeout_secs: Option<f64>,
+    ) -> Result<TypedProvider> {
+        let headers = parse_headers_json(headers_json)?;
+        let handle = self.inner.openai_compat(
+            provider.clone(),
+            base_url,
+            api_key,
+            headers,
+            max_retries,
+            timeout_secs,
+            stream_idle_timeout_secs,
+        );
+        Ok(TypedProvider { provider, handle })
+    }
+
+    #[napi]
+    #[allow(clippy::too_many_arguments)]
+    pub fn openai_responses(
+        &self,
+        provider: String,
+        base_url: String,
+        bearer_token: String,
+        headers_json: Option<String>,
+        max_retries: Option<u32>,
+        timeout_secs: Option<f64>,
+        stream_idle_timeout_secs: Option<f64>,
+    ) -> Result<TypedProvider> {
+        let handle = self.inner.openai_responses(
+            provider.clone(),
+            base_url,
+            bearer_token,
+            parse_headers_json(headers_json)?,
+            max_retries,
+            timeout_secs,
+            stream_idle_timeout_secs,
+        );
+        Ok(TypedProvider { provider, handle })
+    }
+
+    #[napi]
+    #[allow(clippy::too_many_arguments)]
+    pub fn provider(
+        &self,
+        provider: String,
+        model: String,
+        api_key: String,
+        base_url: Option<String>,
+        headers_json: Option<String>,
+        max_retries: Option<u32>,
+        timeout_secs: Option<f64>,
+        stream_idle_timeout_secs: Option<f64>,
+        auth_scheme: Option<String>,
+        protocol: Option<String>,
+    ) -> Result<TypedProvider> {
+        let normalized = provider.trim().to_ascii_lowercase();
+        let protocol = parse_openai_protocol(protocol.as_deref())?;
+        // Contract principle (TD-0008): `authScheme: "bearer"` is a no-op for
+        // families whose default IS Bearer — accepted family-agnostically for
+        // gateway callers; only a contradictory scheme is rejected. Parity with
+        // the Python binding.
+        if let Some(scheme) = auth_scheme
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            let scheme_families = matches!(
+                normalized.as_str(),
+                "anthropic" | "claude" | "gemini" | "google"
+            );
+            if !scheme_families && scheme != "bearer" {
+                return Err(Error::from_reason(format!(
+                    "authScheme {scheme:?} is only valid for the Anthropic or Gemini \
+protocol; other families always authenticate with 'Authorization: Bearer' \
+(authScheme=\"bearer\" is accepted there as a no-op)"
+                )));
+            }
+        }
+        let handle = if protocol != OpenAiProtocol::ChatCompletions {
+            let resolved_base_url = if let Some(base_url) = base_url {
+                base_url
+            } else {
+                sandhi_providers::resolve_openai_compat_provider(&provider)
+                    .map(|spec| spec.base_url_for_model(&model).to_owned())
+                    .ok_or_else(|| {
+                        Error::from_reason(
+                            "Responses protocol requires baseUrl for an unknown provider",
+                        )
+                    })?
+            };
+            let headers = parse_headers_json(headers_json)?;
+            if protocol == OpenAiProtocol::ChatGptResponses {
+                self.inner.chatgpt_responses(
+                    provider.clone(),
+                    resolved_base_url,
+                    api_key,
+                    headers,
+                    max_retries,
+                    timeout_secs,
+                    stream_idle_timeout_secs,
+                )
+            } else {
+                self.inner.openai_responses(
+                    provider.clone(),
+                    resolved_base_url,
+                    api_key,
+                    headers,
+                    max_retries,
+                    timeout_secs,
+                    stream_idle_timeout_secs,
+                )
+            }
+        } else {
+            match normalized.as_str() {
+                "anthropic" | "claude" => self.inner.anthropic(
+                    base_url.unwrap_or_else(|| ProviderFamily::Anthropic.default_base_url().into()),
+                    api_key,
+                    parse_anthropic_auth_scheme(auth_scheme.as_deref())?,
+                    parse_headers_json(headers_json.clone())?,
+                    max_retries,
+                    timeout_secs,
+                    stream_idle_timeout_secs,
+                ),
+                "gemini" | "google" => self.inner.gemini(
+                    base_url.unwrap_or_else(|| ProviderFamily::Gemini.default_base_url().into()),
+                    api_key,
+                    parse_gemini_auth_scheme(auth_scheme.as_deref())?,
+                    parse_headers_json(headers_json.clone())?,
+                    max_retries,
+                    timeout_secs,
+                    stream_idle_timeout_secs,
+                ),
+                "cohere" => self.inner.cohere(
+                    base_url.unwrap_or_else(|| ProviderFamily::Cohere.default_base_url().into()),
+                    api_key,
+                    parse_headers_json(headers_json.clone())?,
+                    max_retries,
+                    timeout_secs,
+                    stream_idle_timeout_secs,
+                ),
+                "ollama" => self.inner.ollama(
+                    base_url.unwrap_or_else(|| ProviderFamily::Ollama.default_base_url().into()),
+                    api_key,
+                    parse_headers_json(headers_json.clone())?,
+                    max_retries,
+                    timeout_secs,
+                    stream_idle_timeout_secs,
+                ),
+                _ => {
+                    let headers = parse_headers_json(headers_json)?;
+                    if let Some(base_url) = base_url {
+                        self.inner.openai_compat(
+                            normalized,
+                            base_url,
+                            api_key,
+                            headers,
+                            max_retries,
+                            timeout_secs,
+                            stream_idle_timeout_secs,
+                        )
+                    } else {
+                        self.inner
+                            .known_openai_compat(
+                                &normalized,
+                                &model,
+                                api_key,
+                                headers,
+                                max_retries,
+                                timeout_secs,
+                                stream_idle_timeout_secs,
+                            )
+                            .map_err(|error| typed_provider_error(error, &normalized))?
+                    }
+                }
+            }
+        };
+        Ok(TypedProvider {
+            provider: handle.slug().to_owned(),
+            handle,
+        })
+    }
+}
+
+fn parse_headers_json(value: Option<String>) -> Result<reqwest::header::HeaderMap> {
+    let mut headers = reqwest::header::HeaderMap::new();
+    let Some(value) = value else {
+        return Ok(headers);
+    };
+    let values: HashMap<String, String> = serde_json::from_str(&value)
+        .map_err(|e| Error::from_reason(format!("headersJson is not a string map: {e}")))?;
+    for (name, value) in values {
+        let name = reqwest::header::HeaderName::from_bytes(name.as_bytes())
+            .map_err(|e| Error::from_reason(format!("invalid header name: {e}")))?;
+        let value = reqwest::header::HeaderValue::from_str(&value)
+            .map_err(|e| Error::from_reason(format!("invalid header value: {e}")))?;
+        headers.insert(name, value);
+    }
+    Ok(headers)
+}
+
+/// A persistent provider handle accepting Sandhi chat-contract v1 JSON documents.
+#[napi]
+pub struct TypedProvider {
+    provider: String,
+    handle: ProviderHandle,
+}
+
+#[napi]
+impl TypedProvider {
+    #[napi(getter)]
+    pub fn provider(&self) -> &str {
+        &self.provider
+    }
+
+    /// `wireHeadersJson` (optional, TD-0022 D1): per-call wire headers — a string map sent
+    /// with THIS call only, for gateway-path metadata that changes per turn (e.g.
+    /// `x-sandhi-step-id`). Transport-owned names are stripped and can never override the
+    /// credential.
+    #[napi]
+    pub async fn complete_json(
+        &self,
+        request_json: String,
+        wire_headers_json: Option<String>,
+    ) -> Result<String> {
+        let call_headers = parse_headers_json(wire_headers_json)?;
+        let request = parse_chat_request(&request_json)?;
+        let response = self
+            .handle
+            .complete_with(request, call_headers)
+            .await
+            .map_err(|e| typed_provider_error(e, &self.provider))?;
+        serde_json::to_string(&response).map_err(|e| Error::from_reason(e.to_string()))
+    }
+
+    /// `wireHeadersJson` (optional, TD-0022 D1): per-call wire headers, as `completeJson`.
+    #[napi]
+    pub fn stream_json(
+        &self,
+        request_json: String,
+        wire_headers_json: Option<String>,
+    ) -> Result<TypedEventStream> {
+        let call_headers = parse_headers_json(wire_headers_json)?;
+        let request = parse_chat_request(&request_json)?;
+        let handle = self.handle.clone();
+        let provider = self.provider.clone();
+        let (tx, rx) = tokio::sync::mpsc::channel::<std::result::Result<String, String>>(64);
+        tokio::spawn(async move {
+            use futures_util::StreamExt;
+            match handle.stream_with(request, call_headers).await {
+                Ok(mut stream) => {
+                    while let Some(event) = stream.next().await {
+                        let (item, stop) = match event {
+                            Ok(event) => (
+                                serde_json::to_string(&event).map_err(|e| e.to_string()),
+                                false,
+                            ),
+                            Err(error) => (
+                                Err(serde_json::to_string(&error.as_typed(Some(&provider)))
+                                    .unwrap_or_else(|_| error.to_string())),
+                                true,
+                            ),
+                        };
+                        if tx.send(item).await.is_err() || stop {
+                            break;
+                        }
+                    }
+                }
+                Err(error) => {
+                    let _ = tx
+                        .send(Err(serde_json::to_string(&error.as_typed(Some(&provider)))
+                            .unwrap_or_else(|_| error.to_string())))
+                        .await;
+                }
+            }
+        });
+        Ok(TypedEventStream {
+            rx: Arc::new(tokio::sync::Mutex::new(rx)),
+        })
+    }
+}
+
+/// Pull-based stream of serialized `ChatStreamEventV1` documents.
+#[napi]
+pub struct TypedEventStream {
+    rx: Arc<tokio::sync::Mutex<tokio::sync::mpsc::Receiver<std::result::Result<String, String>>>>,
+}
+
+#[napi]
+impl TypedEventStream {
+    #[napi]
+    pub async fn read(&self) -> Result<Option<String>> {
+        match self.rx.lock().await.recv().await {
+            Some(Ok(item)) => Ok(Some(item)),
+            Some(Err(error)) => Err(Error::from_reason(error)),
+            None => Ok(None),
+        }
+    }
+}
+
+/// The neutral token breakdown parsed from a provider response.
+#[napi(object)]
+pub struct UsageBreakdown {
+    pub tokens_in: u32,
+    pub tokens_out: u32,
+    pub cache_creation_tokens: u32,
+    pub cache_read_tokens: u32,
+}
+
+/// A neutral usage event (mirrors `usage-event.v1.schema.json`).
+#[napi(object)]
+pub struct Event {
+    pub schema_version: String,
+    pub request_id: String,
+    pub occurred_at: String,
+    pub provider: String,
+    pub model: String,
+    pub backend: String,
+    pub virtual_key_id: Option<String>,
+    pub subject_id: Option<String>,
+    pub group_id: Option<String>,
+    pub route: Option<String>,
+    pub session_id: Option<String>,
+    pub tokens_in: u32,
+    pub tokens_out: u32,
+    pub cache_creation_tokens: u32,
+    pub cache_read_tokens: u32,
+    pub usage_completeness: String,
+    pub attempts: u32,
+    pub outcome: Option<String>,
+    pub upstream_request_id: Option<String>,
+    pub gpu_seconds: Option<f64>,
+}
+
+/// The usage-event wire-contract major version this build targets.
+#[napi]
+pub fn wire_contract_version() -> String {
+    UsageEvent::SCHEMA_VERSION.to_string()
+}
+
+/// The neutral chat-contract (ChatRequestV1/ChatStreamEventV1) major version this
+/// build targets. Today equal to `wire_contract_version()` (pinned by a
+/// sandhi-core test); exported separately so a future split cannot silently
+/// invalidate consumer handshakes that validate the chat contract.
+#[napi]
+pub fn chat_contract_version() -> String {
+    sandhi_core::chat::CHAT_SCHEMA_VERSION_V1.to_string()
+}
+
+/// Additive growth counter within the v1 chat contract (W3c). Consumers
+/// feature-detect this export — an older binding without it reads as minor 0
+/// — and gate trust in newer additive fields on a minimum minor.
+#[napi]
+pub fn chat_contract_minor() -> u32 {
+    sandhi_core::chat::CHAT_CONTRACT_MINOR
+}
+
+/// Resolve an OpenAI-compatible provider spec (slug, aliases, base_url) as JSON.
+/// Parity with the Python binding's `provider_spec` (TD-0008 P4); JSON here
+/// because napi objects would otherwise diverge from the schema'd facades.
+#[napi]
+pub fn provider_spec_json(provider: String, model: Option<String>) -> Result<String> {
+    let spec = sandhi_providers::resolve_openai_compat_provider(&provider)
+        .ok_or_else(|| Error::from_reason(format!("unknown provider: {provider}")))?;
+    let base_url = model
+        .as_deref()
+        .map_or(spec.base_url, |name| spec.base_url_for_model(name));
+    serde_json::to_string(&serde_json::json!({
+        "slug": spec.slug,
+        "aliases": spec.aliases,
+        "base_url": base_url,
+    }))
+    .map_err(|error| Error::from_reason(format!("serialize provider spec: {error}")))
+}
+
+/// Return a checked chat-contract JSON Schema document by name
+/// (e.g. "chat-stream-event.v1"). Parity with the Python binding.
+#[napi]
+pub fn chat_contract_schema_json(name: String) -> Result<String> {
+    let filename = if name.ends_with(".schema.json") {
+        name.clone()
+    } else {
+        format!("{name}.schema.json")
+    };
+    sandhi_core::contract_schema_documents()
+        .remove(filename.as_str())
+        .ok_or_else(|| Error::from_reason(format!("unknown chat contract schema: {name}")))
+}
+
+/// Return the versioned typed descriptor for a known provider as JSON.
+#[napi]
+pub fn provider_descriptor_json(provider: String) -> Result<String> {
+    let descriptor = sandhi_providers::provider_descriptor(&provider)
+        .ok_or_else(|| Error::from_reason(format!("unknown provider: {provider}")))?;
+    serde_json::to_string(&descriptor)
+        .map_err(|error| Error::from_reason(format!("serialize provider descriptor: {error}")))
+}
+
+/// Return the curated model descriptors for a known provider as a JSON list (TD-0004 catalog DATA).
+/// Carries facts only (id, context window, max output, capabilities); no pricing.
+#[napi]
+pub fn provider_models_json(provider: String) -> Result<String> {
+    let descriptor = sandhi_providers::provider_descriptor(&provider)
+        .ok_or_else(|| Error::from_reason(format!("unknown provider: {provider}")))?;
+    serde_json::to_string(&descriptor.models)
+        .map_err(|error| Error::from_reason(format!("serialize provider models: {error}")))
+}
+
+/// Parse a provider response body (JSON string) into the neutral token breakdown. `provider`
+/// selects the parser: `anthropic` → the Anthropic Messages shape; anything else → OpenAI-compat.
+#[napi]
+pub fn parse_usage(provider: String, response_json: String) -> Result<UsageBreakdown> {
+    let value: serde_json::Value = serde_json::from_str(&response_json)
+        .map_err(|e| Error::from_reason(format!("response_json is not valid JSON: {e}")))?;
+    Ok(usage_breakdown(&parse_for(&provider, &value)))
+}
+
+/// In-process metering middleware: virtual keys, budgets, and usage-event emission.
+#[napi]
+pub struct Gateway {
+    inner: Mutex<Inner>,
+    counter: AtomicU64,
+}
+
+struct Inner {
+    keys: KeyStore,
+    ledger: BudgetLedger,
+    events: Vec<UsageEvent>,
+    jsonl_path: Option<PathBuf>,
+}
+
+#[napi]
+impl Gateway {
+    /// `sinkPath` — append emitted events as JSONL to this file (plus an in-memory buffer).
+    #[napi(constructor)]
+    pub fn new(sink_path: Option<String>) -> Self {
+        Gateway {
+            inner: Mutex::new(Inner {
+                keys: KeyStore::new(),
+                ledger: BudgetLedger::new(),
+                events: Vec::new(),
+                jsonl_path: sink_path.map(PathBuf::from),
+            }),
+            counter: AtomicU64::new(0),
+        }
+    }
+
+    /// Register a virtual key: `id` → subject/group attribution + an opaque `upstream` ref.
+    #[napi]
+    pub fn add_virtual_key(
+        &self,
+        id: String,
+        subject: Option<String>,
+        group: Option<String>,
+        upstream: Option<String>,
+    ) {
+        self.inner.lock().unwrap().keys.insert(VirtualKey {
+            id,
+            subject_id: subject,
+            group_id: group,
+            upstream_ref: upstream.unwrap_or_default(),
+            ..Default::default()
+        });
+    }
+
+    /// Set a token budget on a scope (e.g. `group:platform`). Exposed as a 64-bit `bigint` (napi
+    /// has no bare `u64`); negatives clamp to 0 — a budget is a non-negative token count.
+    #[napi]
+    pub fn set_budget(&self, scope: String, tokens: i64) {
+        self.inner
+            .lock()
+            .unwrap()
+            .ledger
+            .set_limit(scope, Budget::tokens(tokens.max(0) as u64));
+    }
+
+    /// Would `add` more tokens be within the scope's budget?
+    #[napi]
+    pub fn check_budget(&self, scope: String, add: i64) -> bool {
+        self.inner
+            .lock()
+            .unwrap()
+            .ledger
+            .check(&scope, add.max(0) as u64)
+            .is_ok()
+    }
+
+    /// Tokens spent so far on a scope.
+    #[napi]
+    pub fn spent(&self, scope: String) -> i64 {
+        i64::try_from(self.inner.lock().unwrap().ledger.spent(&scope)).unwrap_or(i64::MAX)
+    }
+
+    /// Meter one completed call: parse usage from `responseJson` (built-in parser for `provider`),
+    /// attribute it to `virtualKey`, emit the neutral event + record the budget, and return the
+    /// event. Throws on an unknown virtual key or bad JSON.
+    #[napi]
+    pub fn meter(
+        &self,
+        virtual_key: String,
+        provider: String,
+        model: String,
+        response_json: String,
+        session_id: Option<String>,
+        route: Option<String>,
+    ) -> Result<Event> {
+        let value: serde_json::Value = serde_json::from_str(&response_json)
+            .map_err(|e| Error::from_reason(format!("response_json is not valid JSON: {e}")))?;
+        let parsed = parse_for(&provider, &value);
+        self.record_and_build(&virtual_key, &provider, &model, parsed, session_id, route)
+    }
+
+    /// Meter from token counts you supply directly (bypass parsing) — the escape hatch for any
+    /// provider Sandhi doesn't natively parse: do your own parsing and pass the counts. Same
+    /// attribution + budget + emit as `meter()`.
+    #[napi]
+    #[allow(clippy::too_many_arguments)]
+    pub fn meter_tokens(
+        &self,
+        virtual_key: String,
+        provider: String,
+        model: String,
+        tokens_in: u32,
+        tokens_out: u32,
+        cache_creation_tokens: Option<u32>,
+        cache_read_tokens: Option<u32>,
+        session_id: Option<String>,
+        route: Option<String>,
+    ) -> Result<Event> {
+        let parsed = ParsedUsage {
+            tokens_in: u64::from(tokens_in),
+            tokens_out: u64::from(tokens_out),
+            cache_creation_tokens: u64::from(cache_creation_tokens.unwrap_or(0)),
+            cache_read_tokens: u64::from(cache_read_tokens.unwrap_or(0)),
+            reasoning_tokens: 0,
+        };
+        self.record_and_build(&virtual_key, &provider, &model, parsed, session_id, route)
+    }
+
+    /// All events emitted so far (in-memory).
+    #[napi]
+    pub fn events(&self) -> Vec<Event> {
+        self.inner
+            .lock()
+            .unwrap()
+            .events
+            .iter()
+            .map(event_to_napi)
+            .collect()
+    }
+
+    /// Fold the events recorded so far into `UsageAggregateV1` rows for one attribution
+    /// `dimension`, serialized as a JSON array (TD-0009 P2). `dimension` is one of `subject`
+    /// (`user`), `group`, `provider`, `model`, `key` (`virtual_key`), `session`, or `total`.
+    ///
+    /// The fold is `sandhi_core::UsageAggregator` — the same definition the proxy, the CLI, and
+    /// the dashboard read, so the in-process path cannot disagree with them. `cap` bounds the
+    /// number of distinct keys before the rest fold into `"(overflow)"` (default 1024): a
+    /// long-lived process metering unbounded `sessionId`s loses per-key detail, never the sum —
+    /// the rows always add up to the exact total. Throws on an unknown dimension.
+    #[napi]
+    pub fn usage_snapshot_json(&self, dimension: String, cap: Option<u32>) -> Result<String> {
+        let parsed = Dimension::parse(&dimension).ok_or_else(|| {
+            Error::from_reason(format!(
+                "unknown usage dimension {dimension:?}; expected one of \
+subject, group, provider, model, key, session, total"
+            ))
+        })?;
+        let inner = self.inner.lock().unwrap();
+        serde_json::to_string(&fold_usage(
+            &inner.events,
+            parsed,
+            cap.map(|cap| cap as usize),
+        ))
+        .map_err(|e| Error::from_reason(format!("serialize usage aggregate: {e}")))
+    }
+}
+
+impl Gateway {
+    fn next_request_id(&self) -> String {
+        let n = self.counter.fetch_add(1, Ordering::Relaxed);
+        let millis = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_millis())
+            .unwrap_or(0);
+        format!("req_{millis}_{n}")
+    }
+
+    /// Shared tail: resolve the key, build + emit the event, record the budget, return it.
+    fn record_and_build(
+        &self,
+        virtual_key: &str,
+        provider: &str,
+        model: &str,
+        parsed: ParsedUsage,
+        session_id: Option<String>,
+        route: Option<String>,
+    ) -> Result<Event> {
+        let mut inner = self.inner.lock().unwrap();
+        let vk = inner
+            .keys
+            .resolve(virtual_key)
+            .ok_or_else(|| Error::from_reason(format!("unknown virtual key: {virtual_key}")))?;
+
+        let event = parsed.apply(
+            UsageEvent::new(
+                self.next_request_id(),
+                now_rfc3339(),
+                provider,
+                model,
+                Backend::External,
+            )
+            .with_attribution(
+                Some(vk.id.clone()),
+                vk.subject_id.clone(),
+                vk.group_id.clone(),
+            )
+            .with_session(session_id)
+            .with_route(route),
+        );
+
+        if let Some(path) = &inner.jsonl_path {
+            if let Ok(line) = serde_json::to_string(&event) {
+                use std::io::Write;
+                if let Ok(mut f) = std::fs::OpenOptions::new()
+                    .create(true)
+                    .append(true)
+                    .open(path)
+                {
+                    let _ = writeln!(f, "{line}");
+                }
+            }
+        }
+        let scope = match &vk.group_id {
+            Some(g) => format!("group:{g}"),
+            None => format!("vk:{}", vk.id),
+        };
+        inner.ledger.record(&scope, event.billable_tokens());
+        inner.events.push(event.clone());
+        drop(inner);
+
+        Ok(event_to_napi(&event))
+    }
+}
+
+/// Fold recorded events into aggregate rows for one dimension. Mirrors the Python binding exactly
+/// (same core fold, same insertion order, same serializer), which is what makes the two
+/// snapshots byte-identical rather than merely similar (TD-0009 D6).
+fn fold_usage(
+    events: &[UsageEvent],
+    dimension: Dimension,
+    cap: Option<usize>,
+) -> Vec<UsageAggregateV1> {
+    let mut agg = match cap {
+        Some(cap) => UsageAggregator::with_cap(dimension, cap),
+        None => UsageAggregator::new(dimension),
+    };
+    for event in events {
+        agg.add(event);
+    }
+    agg.rows()
+}
+
+fn parse_for(provider: &str, value: &serde_json::Value) -> ParsedUsage {
+    match provider {
+        "anthropic" => parse_anthropic_usage(value),
+        "gemini" => parse_gemini_usage(value),
+        "cohere" => parse_cohere_usage(value),
+        "ollama" => parse_ollama_usage(value),
+        "bedrock" => parse_bedrock_usage(value),
+        "openai_responses" | "responses" => parse_openai_responses_usage(value),
+        _ => parse_openai_usage(value),
+    }
+    .unwrap_or_default()
+}
+
+fn now_rfc3339() -> String {
+    use time::format_description::well_known::Rfc3339;
+    time::OffsetDateTime::now_utc()
+        .format(&Rfc3339)
+        .unwrap_or_default()
+}
+
+fn usage_breakdown(u: &ParsedUsage) -> UsageBreakdown {
+    UsageBreakdown {
+        tokens_in: u.tokens_in as u32,
+        tokens_out: u.tokens_out as u32,
+        cache_creation_tokens: u.cache_creation_tokens as u32,
+        cache_read_tokens: u.cache_read_tokens as u32,
+    }
+}
+
+fn event_to_napi(e: &UsageEvent) -> Event {
+    Event {
+        schema_version: e.schema_version.clone(),
+        request_id: e.request_id.clone(),
+        occurred_at: e.occurred_at.clone(),
+        provider: e.provider.clone(),
+        model: e.model.clone(),
+        backend: match e.backend {
+            Backend::External => "external".to_string(),
+            Backend::SelfHosted => "self_hosted".to_string(),
+        },
+        virtual_key_id: e.virtual_key_id.clone(),
+        subject_id: e.subject_id.clone(),
+        group_id: e.group_id.clone(),
+        route: e.route.clone(),
+        session_id: e.session_id.clone(),
+        tokens_in: e.tokens_in as u32,
+        tokens_out: e.tokens_out as u32,
+        cache_creation_tokens: e.cache_creation_tokens as u32,
+        cache_read_tokens: e.cache_read_tokens as u32,
+        usage_completeness: match e.usage_completeness {
+            sandhi_core::UsageCompleteness::Final => "final",
+            sandhi_core::UsageCompleteness::Partial => "partial",
+            sandhi_core::UsageCompleteness::Unavailable => "unavailable",
+        }
+        .into(),
+        attempts: e.attempts,
+        outcome: e.outcome.clone(),
+        upstream_request_id: e.upstream_request_id.clone(),
+        gpu_seconds: e.gpu_seconds,
+    }
+}