areev 0.2.0

//! `Grains` resource — grain CRUD on the configured memory.
//!
//! Mirrors the Python SDK's `client.grains.*` surface: `add`,
//! `batch_add`, `recall`, `recall_chain`, `get`, `get_raw`, `list`,
//! `forget`, `forget_many`, `forget_user`, `supersede`, `accumulate`,
//! `detect_pii`, `cal`, `predicate_registry`, `predicate_hint`.
//!
//! All methods are loosely typed (`serde_json::Value`) — the goal is
//! parity with Python rather than a strongly typed surface, which is
//! deferred to a future generated layer. Builders are provided for the
//! verbs with many optional parameters (`recall`, `accumulate`).

use serde_json::{json, Map, Value};

use crate::error::{AreevError, Result};
use crate::http::HttpClient;

/// Grain CRUD on the client's configured memory.
///
/// Access via [`crate::Areev::grains`].
pub struct Grains<'a> {
    http: &'a HttpClient,
    memory_id: String,
}

impl<'a> Grains<'a> {
    /// Internal constructor — use [`crate::Areev::grains`].
    pub(crate) fn new(http: &'a HttpClient, memory_id: String) -> Self {
        Self { http, memory_id }
    }

    /// Add a grain of any of the 10 OMS types. Returns the
    /// content-address hash (`blob_hash`) of the new grain.
    ///
    /// `fields` is the typed payload for the grain — see
    /// `docs/facts/areev-overview.md` for the per-grain shape. The
    /// optional `namespace` is added as a top-level body field.
    ///
    /// # Errors
    ///
    /// Returns [`AreevError::Server`] (502, `SDK-E012`) when the server
    /// response carries no grain hash — the store did not happen.
    pub async fn add(
        &self,
        grain_type: &str,
        fields: Value,
        namespace: Option<&str>,
    ) -> Result<String> {
        let mut body = json!({ "grain_type": grain_type, "fields": fields });
        if let Some(ns) = namespace {
            body.as_object_mut()
                .unwrap()
                .insert("namespace".to_string(), Value::String(ns.to_string()));
        }
        let path = format!("/memories/{}/add", self.memory_id);
        let resp = self.http._post(&path, Some(&body)).await?;
        extract_string(&resp, &["blob_hash", "hash"]).ok_or_else(missing_hash_error)
    }

    /// Add multiple grains in one request. Returns the raw server
    /// response (`{"succeeded": [...], "failed": [...]}`).
    pub async fn batch_add(&self, grains: Vec<Value>) -> Result<Value> {
        let body = json!({ "grains": grains });
        let path = format!("/memories/{}/batch-add", self.memory_id);
        self.http._post(&path, Some(&body)).await
    }

    /// Start a [`RecallBuilder`] for the given query — chain
    /// `limit()`, `namespace()`, `tags()`, etc. and call `send()`.
    pub fn recall(&self, query: &str) -> RecallBuilder<'_, 'a> {
        RecallBuilder::new(self, query)
    }

    /// Multi-hop recall — decomposes `question` into sub-queries and
    /// merges results. Returns the raw server response.
    pub async fn recall_chain(&self, question: &str, limit: u32) -> Result<Value> {
        let body = json!({ "query": question, "limit": limit });
        let path = format!("/memories/{}/recall-chain", self.memory_id);
        self.http._post(&path, Some(&body)).await
    }

    /// Fetch a grain by its SHA-256 content-address hash.
    pub async fn get(&self, hash: &str) -> Result<Value> {
        let path = format!("/memories/{}/grains/{}", self.memory_id, hash);
        self.http._get(&path, None).await
    }

    /// Forget a single grain by hash.
    pub async fn forget(&self, hash: &str) -> Result<()> {
        let body = json!({ "blob_hash": hash });
        let path = format!("/memories/{}/forget", self.memory_id);
        self.http._post(&path, Some(&body)).await.map(|_| ())
    }

    /// Forget multiple grains in one request.
    pub async fn forget_many(&self, hashes: &[&str]) -> Result<()> {
        let body = json!({ "hashes": hashes });
        let path = format!("/memories/{}/forget", self.memory_id);
        self.http._post(&path, Some(&body)).await.map(|_| ())
    }

    /// GDPR Art. 17 forget-by-user — crypto-erases every grain attributed
    /// to `user_id`.
    ///
    /// **IRREVERSIBLE.** Destroys the user's grains and their key
    /// material; there is no undo. Emits an audit event.
    /// Requires: admin scope.
    ///
    /// This is a data-subject-rights operation — always issued, never
    /// blocked by tier or credit gates. The response body is excluded
    /// from SDK request logging and the call is **not** auto-retried.
    ///
    /// # Errors
    ///
    /// Returns [`AreevError::Validation`] (`SDK-E002`) when `confirm`
    /// is not `true`.
    pub async fn forget_user(&self, user_id: &str, confirm: bool) -> Result<Value> {
        if !confirm {
            return Err(confirm_error("grains.forget_user"));
        }
        let body = json!({ "user_id": user_id });
        let path = format!("/memories/{}/forget", self.memory_id);
        self.http._post_sensitive(&path, Some(&body), false).await
    }

    /// Fetch a grain's raw `.mg` blob (9-byte header + canonical
    /// MessagePack) by content-address hash.
    ///
    /// The endpoint responds with `application/octet-stream` — raw bytes,
    /// not JSON — so this returns the bytes verbatim. Parse them with an
    /// `.mg` reader; do **not** assume UTF-8 / JSON.
    pub async fn get_raw(&self, hash: &str) -> Result<Vec<u8>> {
        let path = format!("/memories/{}/grains/{}/raw", self.memory_id, hash);
        self.http._get_bytes(&path, None).await
    }

    /// List grains in the memory, optionally filtered. `filters` is added
    /// as query parameters (e.g. `namespace`, `grain_type`, `limit`).
    pub async fn list(&self, filters: Option<&Value>) -> Result<Value> {
        let path = format!("/memories/{}/grains", self.memory_id);
        self.http._get(&path, filters).await
    }

    /// Run a CAL (Contextual Access Language) query. `query` is the raw
    /// CAL text (e.g. `RECALL facts WHERE subject = "john"`).
    ///
    /// The query is sent as the raw request body with Content-Type
    /// `text/cal`; the server parses the text into a `CalQuery` AST. Do
    /// **not** wrap it in `{"query": ...}` — the JSON path
    /// (`application/json+cal`) expects a pre-parsed AST and rejects a
    /// bare string with `CAL-E120`. For callers that already hold a
    /// JSON-CAL AST, use [`Grains::cal_ast`].
    pub async fn cal(&self, query: &str) -> Result<Value> {
        let path = format!("/memories/{}/cal", self.memory_id);
        self.http
            ._post_raw(&path, query.to_string(), "text/cal")
            .await
    }

    /// Run a CAL query from a pre-parsed JSON-CAL AST (`CalQuery` shape —
    /// `{"statement": {"kind": "recall", ...}, ...}`).
    ///
    /// Sends `ast` as the request body with Content-Type
    /// `application/json+cal`. Most callers want [`Grains::cal`] (raw
    /// text); reach for this only when you build the AST yourself (e.g. a
    /// query builder) and want to skip the server-side text parse.
    pub async fn cal_ast(&self, ast: &Value) -> Result<Value> {
        let path = format!("/memories/{}/cal", self.memory_id);
        let body = serde_json::to_string(ast).map_err(AreevError::from)?;
        self.http
            ._post_raw(&path, body, "application/json+cal")
            .await
    }

    /// List the memory's registered predicates (relations) and metadata.
    pub async fn predicate_registry(&self) -> Result<Value> {
        let path = format!("/memories/{}/predicate-registry", self.memory_id);
        self.http._get(&path, None).await
    }

    /// Register a normalization hint for a relation predicate.
    ///
    /// Requires: Scale or Custom plan. Emits an audit event.
    pub async fn predicate_hint(
        &self,
        relation: &str,
        hint: &str,
        confidence: f64,
        user_id: &str,
    ) -> Result<Value> {
        let body = json!({
            "relation": relation,
            "hint": hint,
            "confidence": confidence,
            "user_id": user_id,
        });
        let path = format!("/memories/{}/predicate-hint", self.memory_id);
        self.http._post(&path, Some(&body)).await
    }

    /// Replace `old_hash` with a new grain (versioned, audit-trailed).
    /// Returns the new content-address hash.
    ///
    /// `old_hash` is sent as `blob_hash` and the field overrides under
    /// `fields`.
    pub async fn supersede(&self, old_hash: &str, fields: Value) -> Result<String> {
        let body = json!({
            "blob_hash": old_hash,
            "fields": fields,
        });
        let path = format!("/memories/{}/supersede", self.memory_id);
        let resp = self.http._post(&path, Some(&body)).await?;
        extract_string(&resp, &["new_hash", "blob_hash", "hash"]).ok_or_else(missing_hash_error)
    }

    /// Start an [`AccumulateBuilder`] for the given grain — chain
    /// `deltas()`, `reason()` and call `send()`.
    pub fn accumulate<'b>(
        &'b self,
        grain_type: &str,
        subject: &str,
        relation: &str,
    ) -> AccumulateBuilder<'b, 'a> {
        AccumulateBuilder::new(self, grain_type, subject, relation)
    }

    /// Scan text for PII categories without storing anything.
    ///
    /// The scanned text + detected spans are excluded from the SDK's
    /// request logging.
    pub async fn detect_pii(&self, text: &str) -> Result<Value> {
        let body = json!({ "text": text });
        let path = format!("/memories/{}/detect-pii", self.memory_id);
        self.http._post_sensitive(&path, Some(&body), true).await
    }
}

/// Builder for [`Grains::recall`]. Chain optional knobs and call
/// `send()` to issue the request.
pub struct RecallBuilder<'b, 'a> {
    grains: &'b Grains<'a>,
    body: Map<String, Value>,
}

impl<'b, 'a> RecallBuilder<'b, 'a> {
    fn new(grains: &'b Grains<'a>, query: &str) -> Self {
        let mut body = Map::new();
        body.insert("query".to_string(), Value::String(query.to_string()));
        body.insert("limit".to_string(), Value::from(10u32));
        Self { grains, body }
    }

    /// Maximum number of hits to return (default 10).
    pub fn limit(mut self, limit: u32) -> Self {
        self.body.insert("limit".to_string(), Value::from(limit));
        self
    }

    /// Restrict recall to a specific namespace.
    pub fn namespace(mut self, namespace: &str) -> Self {
        self.body.insert(
            "namespace".to_string(),
            Value::String(namespace.to_string()),
        );
        self
    }

    /// Restrict recall to grains tagged with all of `tags`.
    pub fn tags(mut self, tags: &[&str]) -> Self {
        let arr: Vec<Value> = tags.iter().map(|t| Value::String(t.to_string())).collect();
        self.body.insert("tags".to_string(), Value::Array(arr));
        self
    }

    /// Restrict recall to a grain type.
    pub fn grain_type(mut self, grain_type: &str) -> Self {
        self.body.insert(
            "grain_type".to_string(),
            Value::String(grain_type.to_string()),
        );
        self
    }

    /// Set the user attribution filter.
    pub fn user_id(mut self, user_id: &str) -> Self {
        self.body
            .insert("user_id".to_string(), Value::String(user_id.to_string()));
        self
    }

    /// Set an arbitrary additional field on the request body — escape
    /// hatch for server flags the typed builder doesn't expose yet.
    pub fn extra(mut self, key: &str, value: Value) -> Self {
        self.body.insert(key.to_string(), value);
        self
    }

    /// Issue the request.
    pub async fn send(self) -> Result<Value> {
        let path = format!("/memories/{}/recall", self.grains.memory_id);
        self.grains
            .http
            ._post(&path, Some(&Value::Object(self.body)))
            .await
    }
}

/// Builder for [`Grains::accumulate`].
pub struct AccumulateBuilder<'b, 'a> {
    grains: &'b Grains<'a>,
    body: Map<String, Value>,
}

impl<'b, 'a> AccumulateBuilder<'b, 'a> {
    fn new(grains: &'b Grains<'a>, grain_type: &str, subject: &str, relation: &str) -> Self {
        let mut body = Map::new();
        body.insert(
            "grain_type".to_string(),
            Value::String(grain_type.to_string()),
        );
        // The target grain is resolved by subject + relation (tip-resolved).
        body.insert(
            "target".to_string(),
            json!({
                "kind": "tip_resolved",
                "subject": subject,
                "relation": relation,
            }),
        );
        body.insert("add".to_string(), Value::Object(Map::new()));
        // `reason` is required by the server — default to empty until set.
        body.insert("reason".to_string(), Value::String(String::new()));
        Self { grains, body }
    }

    /// Numeric deltas to apply (field name → delta).
    pub fn deltas(mut self, deltas: &[(&str, f64)]) -> Self {
        let mut map = Map::new();
        for (k, v) in deltas {
            map.insert((*k).to_string(), Value::from(*v));
        }
        self.body.insert("add".to_string(), Value::Object(map));
        self
    }

    /// Reason for the accumulation — surfaced in the audit log.
    pub fn reason(mut self, reason: &str) -> Self {
        self.body
            .insert("reason".to_string(), Value::String(reason.to_string()));
        self
    }

    /// Issue the request.
    pub async fn send(self) -> Result<Value> {
        let path = format!("/memories/{}/accumulate", self.grains.memory_id);
        self.grains
            .http
            ._post(&path, Some(&Value::Object(self.body)))
            .await
    }
}

/// Pull the first non-empty string field from `keys` out of `v`.
fn extract_string(v: &Value, keys: &[&str]) -> Option<String> {
    let map = v.as_object()?;
    for k in keys {
        if let Some(s) = map.get(*k).and_then(|x| x.as_str()) {
            if !s.is_empty() {
                return Some(s.to_string());
            }
        }
    }
    None
}

/// Error for a successful store whose response carries no grain hash —
/// the store did not happen, and a silent empty string would mask it.
/// Shared by `grains.add` and `grains.supersede`.
///
/// Reported as a **server** error (`AreevError::Server`, HTTP 502) — the
/// fault is the server's malformed response, not the caller's request. All
/// three SDKs surface this identically (server-error variant, 502,
/// `SDK-E012`).
fn missing_hash_error() -> AreevError {
    AreevError::Server {
        code: Some("SDK-E012".to_string()),
        http_status: 502,
        message: "unexpected server response: no grain hash".to_string(),
        body: Value::Null,
        request_id: None,
    }
}

/// Build the `confirm=false` guard error shared by destructive ops
/// (`grains.forget_user`, `scope.erase`, `namespaces.purge`).
pub(crate) fn confirm_error(op: &str) -> AreevError {
    AreevError::Validation {
        code: Some("SDK-E002".to_string()),
        http_status: 0,
        message: format!(
            "{op} requires confirm=true — this is irreversible (crypto-erasure / drops grains)"
        ),
        body: serde_json::Value::Null,
        request_id: None,
    }
}