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/common/src/enterprise/llm.rs

@@ -86,6 +86,17 @@ pub struct Call<'x> {
     pub temperature: f64,
     pub max_tokens: u32,
     pub timeout: Duration,
+    /// Set for "Explain this" (ai-explain spec, EX-10, EX-14, EX-15).
+    pub explain: Option<Explain<'x>>,
+}
+
+/// What an explanation call does differently: it leaves a slot for mail,
+/// counts against the administrator's explanations, and is logged without
+/// its answer.
+pub struct Explain<'x> {
+    pub calls_per_hour: u32,
+    /// The subject's type, the only thing about it that is logged.
+    pub subject: &'x str,
 }
 
 fn kind(model: &AiModel) -> Kind {
@@ -129,12 +140,50 @@ impl Server {
         by_id
     }
 
+    /// The model "Explain this" asks (ai-explain spec, EX-3): the one chosen
+    /// for explanations, else the spam classifier's, else the only model
+    /// there is. `None` when explanations are off or no model resolves.
+    pub async fn ai_explain_model(&self, limits: &AiLimits) -> Option<(Id, AiModel)> {
+        use registry::schema::structs::SpamLlm;
+        if !limits.explain_enabled {
+            return None;
+        }
+        if let Some(id) = limits.explain_model_id {
+            let id = Id::from(id);
+            return self.ai_model_by_id(id).await.map(|model| (id, model));
+        }
+        if let Ok(Some(SpamLlm::Enable(settings))) =
+            self.registry().object::<SpamLlm>(Id::singleton()).await
+            && let Some(model) = self.ai_model_by_id(settings.model_id).await
+        {
+            return Some((settings.model_id, model));
+        }
+        let ids = self
+            .registry()
+            .query::<Vec<Id>>(RegistryQuery::new(ObjectType::AiModel))
+            .await
+            .ok()?;
+        match ids.as_slice() {
+            [id] => self.ai_model_by_id(*id).await.map(|model| (*id, model)),
+            _ => None,
+        }
+    }
+
     /// Makes one call. The answer, or why there is none; either way the
     /// outcome is logged, with no message content and no secret (AI-5).
     pub async fn ai_call(&self, call: Call<'_>) -> Result<String, Failure> {
         let limits = self.ai_limits().await;
         let gate = Gate::global();
-        let permit = match gate.try_start(call.model_id.id(), call.account_id, limits.gate()) {
+        let attempt = match (&call.explain, call.account_id) {
+            (Some(explain), Some(account_id)) => gate.try_start_explain(
+                call.model_id.id(),
+                account_id,
+                limits.gate(),
+                explain.calls_per_hour,
+            ),
+            _ => gate.try_start(call.model_id.id(), call.account_id, limits.gate()),
+        };
+        let permit = match attempt {
             Ok(permit) => permit,
             Err(refused) => {
                 trc::event!(
@@ -170,13 +219,23 @@ impl Server {
             None => {}
         }
         match &result {
-            Ok(answer) => trc::event!(
-                Ai(AiEvent::LlmResponse),
-                Details = call.model.name.clone(),
-                AccountId = call.account_id,
-                Elapsed = started.elapsed(),
-                Result = request::cut(answer, 1024),
-            ),
+            Ok(answer) => match &call.explain {
+                // EX-10: an explanation's answer is never logged
+                Some(explain) => trc::event!(
+                    Ai(AiEvent::LlmResponse),
+                    Details = call.model.name.clone(),
+                    AccountId = call.account_id,
+                    Elapsed = started.elapsed(),
+                    Reason = format!("Explained a {}", explain.subject),
+                ),
+                None => trc::event!(
+                    Ai(AiEvent::LlmResponse),
+                    Details = call.model.name.clone(),
+                    AccountId = call.account_id,
+                    Elapsed = started.elapsed(),
+                    Result = request::cut(answer, 1024),
+                ),
+            },
             Err(failure) => trc::event!(
                 Ai(AiEvent::ApiError),
                 Details = call.model.name.clone(),
@@ -347,6 +406,7 @@ pub async fn sieve_prompt(
             temperature: temperature.unwrap_or_else(|| model.temperature.into_inner()),
             max_tokens: request::PROMPT_MAX_TOKENS,
             timeout,
+            explain: None,
         })
         .await
         .ok()?;

crates/common/src/manager/defaults.rs

@@ -445,6 +445,9 @@ async fn insert_safe_defaults(bp: &mut Bootstrap) -> trc::Result<()> {
         }
     }
 
+    // inbuxa: administrator roles stored before a permission existed get it once
+    super::granted_permissions::grant_new_admin_permissions(bp).await?;
+
     if bp
         .registry
         .count_object(ObjectType::NetworkListener)

crates/common/src/manager/granted_permissions.rs

@@ -0,0 +1,124 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+//! Permissions the fork adds after an install's roles were stored. A new
+//! install's roles take them from `DefaultPermissions`; an older install's
+//! administrator roles were written once, before the permission existed, so
+//! each is added to them here, once. An operator who takes one away later
+//! keeps it away: the grant is recorded and never repeated.
+
+use registry::schema::{
+    enums::Permission,
+    prelude::ObjectType,
+    structs::{Authentication, Role},
+};
+use registry::types::EnumImpl;
+use registry::types::id::ObjectId;
+use store::{
+    SUBSPACE_INBUXA, ValueKey,
+    registry::{
+        bootstrap::Bootstrap,
+        write::{RegistryWrite, RegistryWriteResult},
+    },
+    write::{AnyClass, BatchBuilder, ValueClass},
+};
+use trc::AddContext;
+use types::id::Id;
+
+/// Granted to the default administrator roles: "Explain this"
+/// (ai-explain spec, EX-4: superuser by default).
+const ADMIN_GRANTS: &[Permission] = &[Permission::SysAiExplain];
+
+fn granted_key(permission: Permission) -> ValueClass {
+    let mut key = b"Pg".to_vec();
+    key.extend_from_slice(permission.as_str().as_bytes());
+    ValueClass::Any(AnyClass {
+        subspace: SUBSPACE_INBUXA,
+        key,
+    })
+}
+
+pub(crate) async fn grant_new_admin_permissions(bp: &mut Bootstrap) -> trc::Result<()> {
+    let mut pending = Vec::new();
+    for permission in ADMIN_GRANTS {
+        if bp
+            .data_store
+            .get_value::<String>(ValueKey::from(granted_key(*permission)))
+            .await
+            .caused_by(trc::location!())?
+            .is_none()
+        {
+            pending.push(*permission);
+        }
+    }
+    if pending.is_empty() {
+        return Ok(());
+    }
+    // An administrator's default roles include the plain User role, which
+    // every user also holds; only roles that are administrators' alone get it
+    let admin_roles: Vec<Id> = bp
+        .registry
+        .object::<Authentication>(Id::singleton())
+        .await?
+        .map(|auth| {
+            let shared = [
+                auth.default_user_role_ids.as_slice(),
+                auth.default_group_role_ids.as_slice(),
+                auth.default_tenant_role_ids.as_slice(),
+            ]
+            .concat();
+            auth.default_admin_role_ids
+                .as_slice()
+                .iter()
+                .filter(|id| !shared.contains(id))
+                .copied()
+                .collect()
+        })
+        .unwrap_or_default();
+    // Fetched by id: the registry's listing doesn't reach stored roles
+    for role_id in admin_roles {
+        let Some(stored) = bp
+            .registry
+            .get(ObjectId::new(ObjectType::Role, role_id))
+            .await?
+        else {
+            continue;
+        };
+        let role = Role::from(stored.clone());
+        let mut updated = role.clone();
+        for permission in &pending {
+            // A role that disables it outright keeps it disabled
+            if !updated.enabled_permissions.as_slice().contains(permission)
+                && !updated.disabled_permissions.as_slice().contains(permission)
+            {
+                updated.enabled_permissions.push(*permission);
+            }
+        }
+        if updated == role {
+            continue;
+        }
+        let result = bp
+            .registry
+            .write(RegistryWrite::update(role_id, &updated.into(), &stored))
+            .await?;
+        if !matches!(result, RegistryWriteResult::Success(_)) {
+            return Err(trc::StoreEvent::UnexpectedError
+                .into_err()
+                .details("Failed to add a new permission to an administrator role.")
+                .reason(result.to_string())
+                .caused_by(trc::location!()));
+        }
+    }
+    let mut batch = BatchBuilder::new();
+    for permission in pending {
+        batch.set(granted_key(permission), b"granted".to_vec());
+    }
+    bp.data_store
+        .write(batch.build_all())
+        .await
+        .caused_by(trc::location!())
+        .map(|_| ())
+}

crates/common/src/manager/mod.rs

@@ -21,6 +21,7 @@ pub mod boot;
 pub mod console;
 pub mod defaults;
 pub mod first_party;
+pub mod granted_permissions; // inbuxa: permissions added after roles were stored
 pub mod restore;
 pub mod spam_rules; // inbuxa: rules bundled with the server