Explain this: the local model reads delivery failures, verdicts, logs and settings

A new method, inbuxa:Explanation/set, asks the node's local model for a
short plain-words reading of one thing an administrator is looking at:
a failed recipient in the queue, a Classify verdict, a log line or trace
event, or one setting with its saved value. The server builds the prompt
itself from stored data and the registry schema, never from text the
console sends, and grounds SMTP replies in RFC 3463 and RFC 5321.

What the model is never shown: secrets (including ones nested inside a
setting, like an AI model's HTTP auth), raw protocol events, and the
contents of any other event. A tag name that doesn't have a tag's shape is
refused before a model is asked.

Calls share the AI gate with spam classification, but mail always keeps
its slot, and Explain has its own hourly count per account and its own
on/off switch in inbuxa:AiLimits. The permission is sysAiExplain,
superuser only; tenant administrators can't use it. The session carries
an aiExplain flag so a console knows when to offer the button.

An install whose roles were stored before the permission existed gets it
added once, at start-up, to the roles that are administrators' alone,
not the User role their defaults share with every account. An operator
who removes it later isn't overruled.

Tests: unit tests in inbuxa-features and jmap, and ai_explain_tests
(run with --ignored) covering the acceptance tests and the upgrade.

crates/jmap-proto/src/error/set.rs

@@ -2,6 +2,8 @@
  * SPDX-FileCopyrightText: 2020 Stalwart Labs LLC <[email protected]>
  *
  * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-SEL
+ *
+ * Modified by Coffey Labs in 2026 for INBUXA.
  */
 
 use jmap_tools::{Key, Property};
@@ -122,6 +124,9 @@ pub enum SetErrorType {
     PrimaryKeyViolation,
     #[serde(rename = "validationFailed")]
     ValidationFailed,
+    // inbuxa: a create that couldn't run (ai-explain spec: busy, timeout, …)
+    #[serde(rename = "serverFail")]
+    ServerFail,
 }
 
 impl SetErrorType {
@@ -160,6 +165,7 @@ impl SetErrorType {
             SetErrorType::InvalidForeignKey => "invalidForeignKey",
             SetErrorType::PrimaryKeyViolation => "primaryKeyViolation",
             SetErrorType::ValidationFailed => "validationFailed",
+            SetErrorType::ServerFail => "serverFail",
         }
     }
 }

crates/jmap-proto/src/object/inbuxa_ai_limits.rs

@@ -26,6 +26,11 @@ pub enum AiLimitsProperty {
     MaxContentBytes,
     FailureBackoff,
     UserCallsPerHour,
+    // "Explain this" (ai-explain spec, EX-21)
+    ExplainEnabled,
+    ExplainModelId,
+    ExplainCallsPerHour,
+    ExplainCeiling,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -48,6 +53,10 @@ impl Property for AiLimitsProperty {
             AiLimitsProperty::MaxContentBytes => "maxContentBytes",
             AiLimitsProperty::FailureBackoff => "failureBackoff",
             AiLimitsProperty::UserCallsPerHour => "userCallsPerHour",
+            AiLimitsProperty::ExplainEnabled => "explainEnabled",
+            AiLimitsProperty::ExplainModelId => "explainModelId",
+            AiLimitsProperty::ExplainCallsPerHour => "explainCallsPerHour",
+            AiLimitsProperty::ExplainCeiling => "explainCeiling",
         }
         .into()
     }
@@ -64,6 +73,10 @@ impl AiLimitsProperty {
             b"maxContentBytes" => AiLimitsProperty::MaxContentBytes,
             b"failureBackoff" => AiLimitsProperty::FailureBackoff,
             b"userCallsPerHour" => AiLimitsProperty::UserCallsPerHour,
+            b"explainEnabled" => AiLimitsProperty::ExplainEnabled,
+            b"explainModelId" => AiLimitsProperty::ExplainModelId,
+            b"explainCallsPerHour" => AiLimitsProperty::ExplainCallsPerHour,
+            b"explainCeiling" => AiLimitsProperty::ExplainCeiling,
         )
     }
 }
@@ -81,7 +94,9 @@ impl Element for AiLimitsValue {
 
     fn try_parse<P>(key: &Key<'_, Self::Property>, value: &str) -> Option<Self> {
         match key {
-            Key::Property(AiLimitsProperty::Id) => Id::from_str(value).ok().map(AiLimitsValue::Id),
+            Key::Property(AiLimitsProperty::Id | AiLimitsProperty::ExplainModelId) => {
+                Id::from_str(value).ok().map(AiLimitsValue::Id)
+            }
             _ => None,
         }
     }

crates/jmap-proto/src/object/inbuxa_explanation.rs

@@ -0,0 +1,172 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+//! `inbuxa:Explanation/set` under `urn:inbuxa:jmap`: "Explain this", the
+//! local model explaining something in the admin console
+//! (`inbuxa-drafts/specs/ai-explain.md`). Created, never stored: `subject`
+//! goes in, `text` and its provenance come back.
+
+use crate::object::{AnyId, JmapObject, JmapObjectId};
+use jmap_tools::{Element, Key, Property};
+use std::{borrow::Cow, str::FromStr};
+use types::id::Id;
+
+#[derive(Debug, Clone, Default)]
+pub struct Explanation;
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum ExplanationProperty {
+    Id,
+    Subject,
+    Text,
+    Model,
+    Node,
+    ElapsedMs,
+    Grounded,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum ExplanationValue {
+    Id(Id),
+}
+
+impl Property for ExplanationProperty {
+    fn try_parse(parent: Option<&Key<'_, Self>>, value: &str) -> Option<Self> {
+        // Only the object's own properties: a subject's fields (its `id`,
+        // `@type`, …) stay plain keys
+        match parent {
+            None => ExplanationProperty::parse(value),
+            Some(_) => None,
+        }
+    }
+
+    fn to_cow(&self) -> Cow<'static, str> {
+        match self {
+            ExplanationProperty::Id => "id",
+            ExplanationProperty::Subject => "subject",
+            ExplanationProperty::Text => "text",
+            ExplanationProperty::Model => "model",
+            ExplanationProperty::Node => "node",
+            ExplanationProperty::ElapsedMs => "elapsedMs",
+            ExplanationProperty::Grounded => "grounded",
+        }
+        .into()
+    }
+}
+
+impl ExplanationProperty {
+    fn parse(value: &str) -> Option<Self> {
+        hashify::tiny_map!(value.as_bytes(),
+            b"id" => ExplanationProperty::Id,
+            b"subject" => ExplanationProperty::Subject,
+            b"text" => ExplanationProperty::Text,
+            b"model" => ExplanationProperty::Model,
+            b"node" => ExplanationProperty::Node,
+            b"elapsedMs" => ExplanationProperty::ElapsedMs,
+            b"grounded" => ExplanationProperty::Grounded,
+        )
+    }
+}
+
+impl FromStr for ExplanationProperty {
+    type Err = ();
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        ExplanationProperty::parse(s).ok_or(())
+    }
+}
+
+impl Element for ExplanationValue {
+    type Property = ExplanationProperty;
+
+    fn try_parse<P>(key: &Key<'_, Self::Property>, value: &str) -> Option<Self> {
+        match key {
+            Key::Property(ExplanationProperty::Id) => Id::from_str(value).ok().map(ExplanationValue::Id),
+            _ => None,
+        }
+    }
+
+    fn to_cow(&self) -> Cow<'static, str> {
+        match self {
+            ExplanationValue::Id(id) => id.to_string().into(),
+        }
+    }
+}
+
+impl JmapObject for Explanation {
+    type Property = ExplanationProperty;
+
+    type Element = ExplanationValue;
+
+    type Id = Id;
+
+    type Filter = ();
+
+    type Comparator = ();
+
+    type GetArguments = ();
+
+    type SetArguments<'de> = ();
+
+    type QueryArguments = ();
+
+    type CopyArguments = ();
+
+    type ParseArguments = ();
+
+    const ID_PROPERTY: Self::Property = ExplanationProperty::Id;
+}
+
+impl From<Id> for ExplanationValue {
+    fn from(id: Id) -> Self {
+        ExplanationValue::Id(id)
+    }
+}
+
+impl JmapObjectId for ExplanationValue {
+    fn as_id(&self) -> Option<Id> {
+        match self {
+            ExplanationValue::Id(id) => Some(*id),
+        }
+    }
+
+    fn as_any_id(&self) -> Option<AnyId> {
+        match self {
+            ExplanationValue::Id(id) => Some(AnyId::Id(*id)),
+        }
+    }
+
+    fn as_id_ref(&self) -> Option<&str> {
+        None
+    }
+
+    fn try_set_id(&mut self, new_id: AnyId) -> bool {
+        if let AnyId::Id(id) = new_id {
+            *self = ExplanationValue::Id(id);
+            true
+        } else {
+            false
+        }
+    }
+}
+
+impl JmapObjectId for ExplanationProperty {
+    fn as_id(&self) -> Option<Id> {
+        None
+    }
+
+    fn as_any_id(&self) -> Option<AnyId> {
+        None
+    }
+
+    fn as_id_ref(&self) -> Option<&str> {
+        None
+    }
+
+    fn try_set_id(&mut self, _: AnyId) -> bool {
+        false
+    }
+}

crates/jmap-proto/src/object/mod.rs

@@ -22,6 +22,7 @@ pub mod email;
 pub mod email_submission;
 pub mod fastmail_masked_email; // inbuxa: masked email
 pub mod inbuxa_ai_limits; // inbuxa: AI spam classification
+pub mod inbuxa_explanation; // inbuxa: "Explain this" with the local model
 pub mod inbuxa_protocol_policy; // inbuxa: legacy protocols off
 pub mod inbuxa_tenant_protocol_policy; // inbuxa: legacy protocols off, per tenant
 pub mod inbuxa_deleted_account; // inbuxa: undelete

crates/jmap-proto/src/references/resolve.rs

@@ -93,6 +93,9 @@ impl Response<'_> {
                 SetRequestMethod::AiLimits(request) => {
                     request.resolve_references(self, 1, false)?
                 }
+                SetRequestMethod::Explanation(request) => {
+                    request.resolve_references(self, 1, false)?
+                }
                 SetRequestMethod::ProtocolPolicy(request) => {
                     request.resolve_references(self, 1, false)?
                 }

crates/jmap-proto/src/request/capability.rs

@@ -147,6 +147,11 @@ pub struct InbuxaAccountCapabilities {
     /// (legacy-protocols spec, Interfaces; LP-19).
     #[serde(rename(serialize = "legacyProtocols"))]
     pub legacy_protocols: &'static str,
+    /// Whether the principal may use "Explain this" now: it holds
+    /// `sysAiExplain`, is server-level, and a model resolves (ai-explain
+    /// spec, EX-1 to EX-4).
+    #[serde(rename(serialize = "aiExplain"))]
+    pub ai_explain: bool,
 }
 
 #[derive(Debug, Clone, serde::Serialize)]

crates/jmap-proto/src/request/method.rs

@@ -49,6 +49,8 @@ pub enum MethodObject {
     DeletedAccount,
     // inbuxa: AI call limits
     AiLimits,
+    // inbuxa: "Explain this" with the local model
+    Explanation,
     ProtocolPolicy,
     TenantProtocolPolicy,
 }
@@ -77,6 +79,7 @@ impl MethodObject {
             MethodObject::MaskedEmail => Capability::FastmailMaskedEmail,
             MethodObject::DeletedAccount => Capability::Inbuxa,
             MethodObject::AiLimits => Capability::Inbuxa,
+            MethodObject::Explanation => Capability::Inbuxa,
             MethodObject::ProtocolPolicy => Capability::Inbuxa,
             MethodObject::TenantProtocolPolicy => Capability::Inbuxa,
         }
@@ -256,6 +259,7 @@ impl MethodName {
             (MethodFunction::Set, MethodObject::DeletedAccount) => "inbuxa:DeletedAccount/set",
             (MethodFunction::Get, MethodObject::AiLimits) => "inbuxa:AiLimits/get",
             (MethodFunction::Set, MethodObject::AiLimits) => "inbuxa:AiLimits/set",
+            (MethodFunction::Set, MethodObject::Explanation) => "inbuxa:Explanation/set",
             (MethodFunction::Get, MethodObject::ProtocolPolicy) => "inbuxa:ProtocolPolicy/get",
             (MethodFunction::Set, MethodObject::ProtocolPolicy) => "inbuxa:ProtocolPolicy/set",
             (MethodFunction::Get, MethodObject::TenantProtocolPolicy) => {
@@ -389,6 +393,7 @@ impl MethodName {
             "inbuxa:DeletedAccount/set" => (MethodObject::DeletedAccount, MethodFunction::Set),
             "inbuxa:AiLimits/get" => (MethodObject::AiLimits, MethodFunction::Get),
             "inbuxa:AiLimits/set" => (MethodObject::AiLimits, MethodFunction::Set),
+            "inbuxa:Explanation/set" => (MethodObject::Explanation, MethodFunction::Set),
             "inbuxa:ProtocolPolicy/get" => (MethodObject::ProtocolPolicy, MethodFunction::Get),
             "inbuxa:ProtocolPolicy/set" => (MethodObject::ProtocolPolicy, MethodFunction::Set),
             "inbuxa:TenantProtocolPolicy/get" => (MethodObject::TenantProtocolPolicy, MethodFunction::Get),
@@ -446,6 +451,7 @@ impl Display for MethodObject {
             MethodObject::MaskedEmail => "MaskedEmail",
             MethodObject::DeletedAccount => "inbuxa:DeletedAccount",
             MethodObject::AiLimits => "inbuxa:AiLimits",
+            MethodObject::Explanation => "inbuxa:Explanation",
             MethodObject::ProtocolPolicy => "inbuxa:ProtocolPolicy",
             MethodObject::TenantProtocolPolicy => "inbuxa:TenantProtocolPolicy",
             MethodObject::Registry(obj) => {

crates/jmap-proto/src/request/mod.rs

@@ -143,6 +143,7 @@ pub enum SetRequestMethod<'x> {
     MaskedEmail(Box<SetRequest<'x, crate::object::fastmail_masked_email::FastmailMaskedEmail>>),
     DeletedAccount(Box<SetRequest<'x, crate::object::inbuxa_deleted_account::DeletedAccount>>),
     AiLimits(Box<SetRequest<'x, crate::object::inbuxa_ai_limits::AiLimits>>),
+    Explanation(Box<SetRequest<'x, crate::object::inbuxa_explanation::Explanation>>),
     ProtocolPolicy(Box<SetRequest<'x, crate::object::inbuxa_protocol_policy::ProtocolPolicy>>),
     TenantProtocolPolicy(
         Box<SetRequest<'x, crate::object::inbuxa_tenant_protocol_policy::TenantProtocolPolicy>>,

crates/jmap-proto/src/request/parser.rs

@@ -350,6 +350,13 @@ impl<'de> Visitor<'de> for CallVisitor {
                     return Err(de::Error::invalid_length(1, &self));
                 }
             },
+            (MethodFunction::Set, MethodObject::Explanation) => match seq.next_element() {
+                Ok(Some(value)) => RequestMethod::Set(SetRequestMethod::Explanation(value)),
+                Err(err) => RequestMethod::invalid(err),
+                Ok(None) => {
+                    return Err(de::Error::invalid_length(1, &self));
+                }
+            },
             (MethodFunction::Set, MethodObject::ProtocolPolicy) => match seq.next_element() {
                 Ok(Some(value)) => RequestMethod::Set(SetRequestMethod::ProtocolPolicy(value)),
                 Err(err) => RequestMethod::invalid(err),

crates/jmap-proto/src/response/mod.rs

@@ -131,6 +131,7 @@ pub enum SetResponseMethod {
     MaskedEmail(Box<SetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>>),
     DeletedAccount(Box<SetResponse<crate::object::inbuxa_deleted_account::DeletedAccount>>),
     AiLimits(Box<SetResponse<crate::object::inbuxa_ai_limits::AiLimits>>),
+    Explanation(Box<SetResponse<crate::object::inbuxa_explanation::Explanation>>),
     ProtocolPolicy(Box<SetResponse<crate::object::inbuxa_protocol_policy::ProtocolPolicy>>),
     TenantProtocolPolicy(
         Box<SetResponse<crate::object::inbuxa_tenant_protocol_policy::TenantProtocolPolicy>>,
@@ -343,6 +344,12 @@ impl<'x> From<SetResponse<crate::object::inbuxa_ai_limits::AiLimits>> for Respon
     }
 }
 
+impl<'x> From<SetResponse<crate::object::inbuxa_explanation::Explanation>> for ResponseMethod<'x> {
+    fn from(value: SetResponse<crate::object::inbuxa_explanation::Explanation>) -> Self {
+        ResponseMethod::Set(SetResponseMethod::Explanation(Box::new(value)))
+    }
+}
+
 // inbuxa: deleted accounts (UD-17)
 impl<'x> From<GetResponse<crate::object::inbuxa_deleted_account::DeletedAccount>> for ResponseMethod<'x> {
     fn from(value: GetResponse<crate::object::inbuxa_deleted_account::DeletedAccount>) -> Self {